npm · #3768 most downloaded on npm

@anthropic-ai/claude-agent-sdk

0.3.289anthropics/claude-agent-sdk-typescript ↗New releases in your daily digest, changelog included.

SDK for building AI agents with Claude Code's capabilities. Programmatically interact with Claude to build autonomous agents that can understand codebases, edit files, and execute workflows.

Last release today
03 Oct 2026
Ships on a steady schedule
a new release about every 8 days
Nearly every release is documented
notes for 60 of the last 60 stable releases
Nothing withdrawn
no release was ever pulled
1 years old
313 releases · first in 2025

Release timeline

313 releases since 2025

20252026

Releases

0.3.2893 Oct 20262 sources agree

Updated to parity with Claude Code v2.1.289

What's changed

Updated to parity with Claude Code v2.1.289

Update

npm install @anthropic-ai/claude-agent-sdk@0.3.289
# or
yarn add @anthropic-ai/claude-agent-sdk@0.3.289
# or
pnpm add @anthropic-ai/claude-agent-sdk@0.3.289
# or
bun add @anthropic-ai/claude-agent-sdk@0.3.289

Open source →

0.3.2882 Oct 20262 sources agree

Updated to parity with Claude Code v2.1.288

What's changed

Updated to parity with Claude Code v2.1.288

Update

npm install @anthropic-ai/claude-agent-sdk@0.3.288
# or
yarn add @anthropic-ai/claude-agent-sdk@0.3.288
# or
pnpm add @anthropic-ai/claude-agent-sdk@0.3.288
# or
bun add @anthropic-ai/claude-agent-sdk@0.3.288

0.3.2871 Oct 20262 sources agree

Added optional remote-session latency fields ( first_text_post_queue_wait_ms , first_text_post_queued_behind ) to the success result message

What's changed

Added optional remote-session latency fields (first_text_post_queue_wait_ms, first_text_post_queued_behind) to the success result message
Fixed includePartialMessages streams sending a cut-short reply's message_stop late or never, so apps could show the reply as still in progress
Fixed the error for a revoked claude.ai login, which now reads "Failed to authenticate: OAuth token revoked" instead of a generic or "does not have access" message
Fixed a tool call to an in-process MCP server being left waiting after toggleMcpServer() disabled the server or setMcpServers() removed it
Fixed commands_changed arriving before init, or twice, at session start: the initialize response now includes commands registered at startup
Changed tool_use_result for a WebFetch or WebSearch call that steps aside for a priority "now" message to { detachedToolCall: true }; the result follows in a later turn
Changed tool_use_result for MCP tools: structuredContent over 1,048,576 JSON characters is left off and structuredContentOmitted: true set, except for SDK-server and MCP Apps tools
Updated to parity with Claude Code v2.1.287

Update

npm install @anthropic-ai/claude-agent-sdk@0.3.287
# or
yarn add @anthropic-ai/claude-agent-sdk@0.3.287
# or
pnpm add @anthropic-ai/claude-agent-sdk@0.3.287
# or
bun add @anthropic-ai/claude-agent-sdk@0.3.287

Open source →

0.3.28630 Sept 20262 sources agree

Added the initialize response field sdk_mcp_manifests_parked and the system/init capabilities sdk_mcp_manifests and sdk_mcp_tools_list_changed

What's changed

Added the initialize response field sdk_mcp_manifests_parked and the system/init capabilities sdk_mcp_manifests and sdk_mcp_tools_list_changed
Fixed foreground subagents sometimes not receiving the task-tracking tools listed in tools or allowedTools
Fixed an SDK MCP server listing no tools when one tool's schema cannot be converted to JSON Schema; that tool is now left out with a warning naming it
Fixed toggleMcpServer() not disconnecting, and failing to re-enable, an in-process MCP server created with createSdkMcpServer(), except one named claude-in-chrome
Changed a person's priority now message to move running shell commands, agents and MCP calls to the background and join the running turn instead of stopping it
Changed the TypeScript Agent SDK to leave an omitted permissionMode to Claude Code, so a settings defaultMode now applies and, on third-party providers or with telemetry off, the session starts in auto mode like claude -p; pass permissionMode: 'default' for manual approvals
Updated to parity with Claude Code v2.1.286

Update

npm install @anthropic-ai/claude-agent-sdk@0.3.286
# or
yarn add @anthropic-ai/claude-agent-sdk@0.3.286
# or
pnpm add @anthropic-ai/claude-agent-sdk@0.3.286
# or
bun add @anthropic-ai/claude-agent-sdk@0.3.286

Open source →

0.3.28529 Sept 20262 sources agree

Added an optional read.title (the artifact's stored title) to the Artifact tool's structured read result

What's changed

Added an optional read.title (the artifact's stored title) to the Artifact tool's structured read result
Added provider_not_allowed to startup_failure_reason and allowedProviders to the Settings type
Fixed sessions with CLAUDE_CODE_FORK_SUBAGENT=1: a subagent's own Agent call now runs in the foreground, so the subagent gets the child's result
Fixed getSessionMessages() leaving out a message sent while Claude was working when the process stopped before the reply, or when another prompt followed it with no reply in between
Fixed toggleMcpServer(name, false) leaving the connection open for a server that had not yet connected when the session started, or whose config was edited after it connected
Fixed rewind_conversation leaving a backgrounded MCP tool call running after the message that started it was removed
Changed Bash/PowerShell timeout to bound a run_in_background command (was ignored; default 30 min, max 2 h); the stopped task notification for a stop at that limit says why
Changed getSubagentMessages() to also return the messages a subagent read while it ran, such as a message sent to it; offset and limit count these rows
Updated to parity with Claude Code v2.1.285

Update

npm install @anthropic-ai/claude-agent-sdk@0.3.285
# or
yarn add @anthropic-ai/claude-agent-sdk@0.3.285
# or
pnpm add @anthropic-ai/claude-agent-sdk@0.3.285
# or
bun add @anthropic-ai/claude-agent-sdk@0.3.285

Open source →

0.3.28428 Sept 20262 sources agree

Added a renamed skill's directory name to its SlashCommand aliases when the name is plain and Claude Code ships no command by that name

What's changed

Added a renamed skill's directory name to its SlashCommand aliases when the name is plain and Claude Code ships no command by that name
Added applied.ultracodeAvailable and applied.ultracodeRequested to getSettings(): whether this session can run Ultracode, and whether it is requested, independent of whether it is in effect
Fixed forkSession() copies reading back the wrong history when cut at a progress row or fork briefing after a rewind, or when the session was compacted with some messages kept
Fixed getSessionMessages() leaving out messages from other agents, sessions and channels that the CLI transcript shows
Fixed { decision: 'block' } returned by Elicitation and ElicitationResult hook callbacks being ignored; it now declines the MCP elicitation
Fixed query() closing stdin before a follow-up turn woken by a finished background agent, which failed that turn's hooks, canUseTool and SDK MCP calls with "Stream closed"
Changed the first turn to still wait up to 2s for connecting MCP servers named in allowedTools or by an mcp_tool hook, even with CLAUDE_CODE_MCP_STARTUP_WAIT_MS set to 0
Changed applyFlagSettings({ ultracode: true }) to keep the current effort level instead of switching to xhigh; an effortLevel that changes the level without ultracode turns Ultracode off
Updated to parity with Claude Code v2.1.284

Update

npm install @anthropic-ai/claude-agent-sdk@0.3.284
# or
yarn add @anthropic-ai/claude-agent-sdk@0.3.284
# or
pnpm add @anthropic-ai/claude-agent-sdk@0.3.284
# or
bun add @anthropic-ai/claude-agent-sdk@0.3.284

Open source →

0.3.28325 Sept 20262 sources agree

Added plugin_errors to the SDKSystemMessage type ( system/init ), including path for a --plugin-dir entry that did not load

What's changed

Added plugin_errors to the SDKSystemMessage type (system/init), including path for a --plugin-dir entry that did not load
Fixed getSessionMessages() returning, and forkSession() copying, a rewound-away branch when the newest branch ends at a meta row or a local command's rows
Changed stream-json output to include warnings and notices raised during a turn as system/informational messages; it previously dropped them
Changed the set_max_thinking_tokens control request: omitting max_thinking_tokens now leaves the session's thinking budget unchanged; send null to reset it to the session default
Updated to parity with Claude Code v2.1.283

Update

npm install @anthropic-ai/claude-agent-sdk@0.3.283
# or
yarn add @anthropic-ai/claude-agent-sdk@0.3.283
# or
pnpm add @anthropic-ai/claude-agent-sdk@0.3.283
# or
bun add @anthropic-ai/claude-agent-sdk@0.3.283

Open source →

0.3.28224 Sept 20262 sources agree

Added support for strictKnownMarketplaces and blockedMarketplaces in host-supplied managedSettings : the allowlist applies only where admin policy set

What's changed

Added support for strictKnownMarketplaces and blockedMarketplaces in host-supplied managedSettings: the allowlist applies only where admin policy sets none; the blocklist adds to the admin's
Added @anthropic-ai/claude-agent-sdk/core, a smaller entry point for apps that bundle the SDK (query, MCP tool helpers, session mutations, resolveSettings); it uses your installed zod and MCP SDK
Added prewarm() and SpareProcess.claim() (alpha): start a Claude Code process before its session is known and bind it to a folder and its per-session options later
Fixed readMcpResource() relaying content _meta keys under the CLI-reserved com.anthropic/ prefix; they are now dropped, as for tool results
Updated to parity with Claude Code v2.1.282

Update

npm install @anthropic-ai/claude-agent-sdk@0.3.282
# or
yarn add @anthropic-ai/claude-agent-sdk@0.3.282
# or
pnpm add @anthropic-ai/claude-agent-sdk@0.3.282
# or
bun add @anthropic-ai/claude-agent-sdk@0.3.282

Open source →

0.3.28123 Sept 20262 sources agree

Added optional trigger , user_message_uuid and timestamp fields to the conversation_reset message so clients can tell what reset the conversation, mat

What's changed

Added optional trigger, user_message_uuid and timestamp fields to the conversation_reset message so clients can tell what reset the conversation, match a /clear to its message, and show when the reset happened
Fixed permission and dialog callbacks still being invoked for requests that arrived after close()
Fixed control requests issued after a query closed hanging or leaking, and permission prompts that could not be cancelled after a cancelled request was redelivered
Fixed session_state_changed staying at requires_action after an overlapping permission prompt and sandbox network-access prompt were both answered
Improved SDK package size and load time: sdk.mjs no longer bundles unused dependencies (1.47 MB → 0.97 MB)
Improved startup time for query() sessions with in-process MCP servers (createSdkMcpServer) by running their handshake inside the SDK; initialize may now wait up to 250 ms for them
Improved SDK session start-up: the CLI now answers the host's initialize request before starting its background start-up work
Changed the Settings type's attribution field to boolean | {...}; TypeScript code that reads attribution.commit from returned settings needs a type narrow
Updated to parity with Claude Code v2.1.281

Update

npm install @anthropic-ai/claude-agent-sdk@0.3.281
# or
yarn add @anthropic-ai/claude-agent-sdk@0.3.281
# or
pnpm add @anthropic-ai/claude-agent-sdk@0.3.281
# or
bun add @anthropic-ai/claude-agent-sdk@0.3.281

Open source →

0.3.28022 Sept 20262 sources agree

Added optional fireReason to the task-notification SDKMessageOrigin ; a local host's declared scheduled-task fire is honored only in a process it star

What's changed

Added optional fireReason to the task-notification SDKMessageOrigin; a local host's declared scheduled-task fire is honored only in a process it started with CLAUDE_CODE_HOST_SCHEDULED_RUN=1
Added verbatimPrompts option: prompts are delivered as written — no @path expansion, no slash-command dispatch and, on current CLIs, no ambient attachments with the prompt (Claude Code 2.1.248+)
Added _meta to mcpServerStatus() tool entries, carrying a tool's MCP Apps ui metadata so a host can find its ui:// resource
Added readMcpResource() (alpha) to read an MCP Apps ui:// resource from an MCP server that Claude Code connected
Improved askSideQuestion(): asked while a turn is running, it now sees that turn (its prompt, replies and finished tool results so far) instead of only the last completed turn
Improved unattended retry (CLAUDE_CODE_RETRY_WATCHDOG): a usage-limit wait emits rate_limit_event (rejected, resetsAt) as it begins; api_retry heartbeats continue while sub-agent work waits
Changed session_state_changed events (CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS=1) to report requires_action while an MCP elicitation waits on the user, as for permission prompts
Changed headless sessions to cancel an MCP server's pending form question when the tool call that drew it ends
Updated to parity with Claude Code v2.1.280

Update

npm install @anthropic-ai/claude-agent-sdk@0.3.280
# or
yarn add @anthropic-ai/claude-agent-sdk@0.3.280
# or
pnpm add @anthropic-ai/claude-agent-sdk@0.3.280
# or
bun add @anthropic-ai/claude-agent-sdk@0.3.280

Open source →

0.3.27718 Sept 20262 sources agree

Added an optional builtin field to SlashCommand , set when a command is built into Claude Code

What's changed

Added an optional builtin field to SlashCommand, set when a command is built into Claude Code
Added pasted_content to SDKUserMessage: text the user pasted rather than typed, appended after the typed prompt
Added optional remote-session latency fields (first_text_post_ms, first_text_post_wall_ms, first_stream_post_queue_wait_ms, first_stream_post_queued_behind) to the success result message
Added 'userSettings' as an updateSettings() source, accepting only effortLevel, which is saved for the session's current model as /effort saves it
Fixed a resumed or forked session's total_cost_usd, modelUsage and get_usage totals starting at zero instead of continuing from the earlier turns (maxBudgetUsd is unchanged)
Changed SDKUsageReport usage rows to always carry severity and is_active: the report relays only rows from a live server reply, and none while the usage fetch is failing
Updated to parity with Claude Code v2.1.277

Update

npm install @anthropic-ai/claude-agent-sdk@0.3.277
# or
yarn add @anthropic-ai/claude-agent-sdk@0.3.277
# or
pnpm add @anthropic-ai/claude-agent-sdk@0.3.277
# or
bun add @anthropic-ai/claude-agent-sdk@0.3.277

Open source →

0.3.27517 Sept 20262 sources agree

Fixed a deferred tool call's result being emitted with internal keys such as toolUseResult instead of tool_use_result when the tool re-runs at the sta

What's changed

Fixed a deferred tool call's result being emitted with internal keys such as toolUseResult instead of tool_use_result when the tool re-runs at the start of a resumed turn
Fixed getSessionMessages() and forkSession() sometimes missing a turn's assistant message when called right after the turn's result message
Fixed forkSession({ upToMessageId }) rejecting a client-supplied SDKUserMessage.uuid that is not in UUID format
Fixed forkSession rejecting the id that getSessionMessages returns for a message sent while Claude was working, and a fork showing a re-run prompt twice
Fixed getSessionMessages() omitting a task notification or other queued message that Claude read while running a tool; it now comes back where Claude read it
Updated to parity with Claude Code v2.1.275

Update

npm install @anthropic-ai/claude-agent-sdk@0.3.275
# or
yarn add @anthropic-ai/claude-agent-sdk@0.3.275
# or
pnpm add @anthropic-ai/claude-agent-sdk@0.3.275
# or
bun add @anthropic-ai/claude-agent-sdk@0.3.275

Open source →

0.3.27416 Sept 20262 sources agree

Added startup_failure_reason to the error result a stream-json run writes before exiting on a known startup failure

What's changed

Added startup_failure_reason to the error result a stream-json run writes before exiting on a known startup failure
Added mcpServer: {name, source} to canUseTool options, mcp_server to tool hook inputs, and source to MCP server status rows, so hosts can key trust on source === "sdk"
Added CLAUDE_CODE_MCP_STARTUP_WAIT_MS (pass via env) to bound or disable (0) the first-turn wait for connecting MCP servers
Added CLAUDE_CODE_EMIT_STARTUP_TIMING=1 for stream-json hosts: the session's first system/init then carries the per-phase startup_timing breakdown that cloud sessions already emit
Fixed getSessionMessages() omitting a message the user sent while Claude was running a tool; it now comes back as a user message where Claude read it
Fixed missing origin: {kind: 'task-notification'} on the replayed user message when a background task finishes during a running turn (--replay-user-messages)
Improved startup: the first turn no longer waits up to 2s for connecting MCP servers from settings files or plugins whose tools tool search defers; options.mcpServers servers are still awaited
Changed queued background-task completions to share one model call: each still gets its own result, all but the last empty with num_turns: 0
Updated to parity with Claude Code v2.1.274

Update

npm install @anthropic-ai/claude-agent-sdk@0.3.274
# or
yarn add @anthropic-ai/claude-agent-sdk@0.3.274
# or
pnpm add @anthropic-ai/claude-agent-sdk@0.3.274
# or
bun add @anthropic-ai/claude-agent-sdk@0.3.274

Open source →

0.3.27315 Sept 20262 sources agree

Added a usage_report sibling ( SDKUsageReport : session totals, the plan's usage rows as the server sends them, extra usage) on the assistant message

What's changed

Added a usage_report sibling (SDKUsageReport: session totals, the plan's usage rows as the server sends them, extra usage) on the assistant message that delivers a headless /usage result
Added reason: "worker_restart" to task_notification messages when a background task was stopped by a worker process restart
Added a one-line transcript notice when the SDK host's Stop or SessionStart hook callback times out, shown once until the host answers again
Fixed a Stop, SubagentStop or SessionStart hook callback that exceeds its timeout being reported as a hook failure and discarding other hooks' decisions; it now counts as no decision
Fixed the browser SSE transport dropping the live slash-command list update (system/commands_changed)
Updated to parity with Claude Code v2.1.273

Update

npm install @anthropic-ai/claude-agent-sdk@0.3.273
# or
yarn add @anthropic-ai/claude-agent-sdk@0.3.273
# or
pnpm add @anthropic-ai/claude-agent-sdk@0.3.273
# or
bun add @anthropic-ai/claude-agent-sdk@0.3.273

Open source →

0.3.27114 Sept 20262 sources agree

Added optional omitClaudeMd to AgentDefinition in the agents option, so a subagent can run without user, project and local CLAUDE.md files; managed po

What's changed

Added optional omitClaudeMd to AgentDefinition in the agents option, so a subagent can run without user, project and local CLAUDE.md files; managed policy files still load
Fixed listSessions, getSessionMessages and getSessionInfo with dir on Windows not finding sessions for a directory on a mapped network drive or SUBST drive
Fixed sessionStore resume losing the global config when it is stored under the legacy .config.json name or an OAuth-suffixed file name
Removed persistent from the MonitorInput tool type
Updated to parity with Claude Code v2.1.271

Update

npm install @anthropic-ai/claude-agent-sdk@0.3.271
# or
yarn add @anthropic-ai/claude-agent-sdk@0.3.271
# or
pnpm add @anthropic-ai/claude-agent-sdk@0.3.271
# or
bun add @anthropic-ai/claude-agent-sdk@0.3.271

Open source →

0.3.26911 Sept 20262 sources agree

Changed user_message_uuid , user_message_uuids and resume_reason to be stamped on a turn's first complete assistant message as well as its first strea

What's changed

Changed user_message_uuid, user_message_uuids and resume_reason to be stamped on a turn's first complete assistant message as well as its first stream event when partial messages are on
Fixed result.permission_denials omitting Read, Edit and Write calls blocked by a path-scoped deny rule
Fixed interrupts and permission responses being delayed while a host-started MCP server OAuth sign-in waited on a slow authorization server
Fixed missing tool_use_id on task_started / task_notification when the CLI resumes a background subagent on its own; they now carry the agent's last call id
Changed plan mode to route writes through canUseTool even when allowDangerouslySkipPermissions is set; the flag now only enables switching to bypassPermissions later
Updated to parity with Claude Code v2.1.269

Update

npm install @anthropic-ai/claude-agent-sdk@0.3.269
# or
yarn add @anthropic-ai/claude-agent-sdk@0.3.269
# or
pnpm add @anthropic-ai/claude-agent-sdk@0.3.269
# or
bun add @anthropic-ai/claude-agent-sdk@0.3.269

Open source →

0.3.26810 Sept 20262 sources agree

Added result_index to result messages: the result's position in delivery order within the run, from 0

What's changed

Added result_index to result messages: the result's position in delivery order within the run, from 0
Added local_command to the result message of a turn that ran a slash command without entering the model loop, carrying the command's name
Added hold_on_cache_impact to the reload_plugins control request (Query.reloadPlugins({ holdOnCacheImpact: true })): holds a reload that would invalidate the session's prompt cache
Added resume_reason to assistant, stream-event and result messages, set only on the automatic re-run of a turn a host restart interrupted
Added kind (used, free, buffer, deferred) to each category in the get_context_usage control response, matching the /context result's context_usage rows
Added optional defaultToNo and suppressAlwaysAllowRule hints to canUseTool options: the prompt should open on its decline option, or offer no persistent "always allow" choice
Changed setModel() to confirm a model id the CLI doesn't know locally with the API the first time a session uses it, instead of refusing it as unrecognized
Changed user_message_uuid on the automatic re-run of an interrupted turn to name that turn's last user prompt
Changed the initialize success response to always include pending_permission_requests (empty when nothing is pending), so clients can tell that apart from an older CLI
Changed the task-tracking tools (TaskCreate/Get/Update/List, TodoWrite) to be default tools only on Claude 3.x, Opus 4.0–4.7, Sonnet 4.0–4.6 and Haiku 4.5; elsewhere list them in tools/allowedTools
Updated to parity with Claude Code v2.1.268

Update

npm install @anthropic-ai/claude-agent-sdk@0.3.268
# or
yarn add @anthropic-ai/claude-agent-sdk@0.3.268
# or
pnpm add @anthropic-ai/claude-agent-sdk@0.3.268
# or
bun add @anthropic-ai/claude-agent-sdk@0.3.268

Open source →

0.3.2679 Sept 20262 sources agree

Added getCcrEvent(query, message) and getSseLastSequenceNum(query) to the browser SDK's SSE transport, plus fromSequenceNum , onCatchUpTruncated and o

What's changed

Added getCcrEvent(query, message) and getSseLastSequenceNum(query) to the browser SDK's SSE transport, plus fromSequenceNum, onCatchUpTruncated and onDeliveryUpdate SSE options
Changed systemPrompt recording to default on for custom prompts and appends (a mid-session prompt change takes effect at the next compaction); pass snapshot: false to keep per-request rendering
Updated to parity with Claude Code v2.1.267

Update

npm install @anthropic-ai/claude-agent-sdk@0.3.267
# or
yarn add @anthropic-ai/claude-agent-sdk@0.3.267
# or
pnpm add @anthropic-ai/claude-agent-sdk@0.3.267
# or
bun add @anthropic-ai/claude-agent-sdk@0.3.267

Open source →

0.3.2658 Sept 20262 sources agree

Added user_message_uuid and user_message_uuids to a synthetic turn's first reply and result for a message sent with isSynthetic: true and a uuid , nam

What's changed

Added user_message_uuid and user_message_uuids to a synthetic turn's first reply and result for a message sent with isSynthetic: true and a uuid, naming the message that started it
Added user_message_uuid and user_message_uuids to the first reply and the result of a turn Claude Code started itself, such as a resume, naming the messages you sent that it picked up mid-turn
Fixed user_message_uuid missing from the success result of a turn that sent no API request, such as a slash command
Fixed multi-turn sessions resetting the shell working directory to the cwd option at each new user message; a cd made by the agent now persists across turns, as in the interactive app
Changed user_message_uuid to be set on the first reply after each change of the message a turn is answering, instead of on one reply frame per turn
Updated to parity with Claude Code v2.1.265

Update

npm install @anthropic-ai/claude-agent-sdk@0.3.265
# or
yarn add @anthropic-ai/claude-agent-sdk@0.3.265
# or
pnpm add @anthropic-ai/claude-agent-sdk@0.3.265
# or
bun add @anthropic-ai/claude-agent-sdk@0.3.265

Open source →

0.3.2614 Sept 20262 sources agree

Added pluginDelivery: 'initialize' to send plugins over stdin so the launch command line no longer grows with the plugin count (fixes Windows start fa

What's changed

Added pluginDelivery: 'initialize' to send plugins over stdin so the launch command line no longer grows with the plugin count (fixes Windows start failures with many plugins)
Fixed query() throwing "Object not disposable" in runtimes without a native Symbol.dispose, such as Node ≤22 vm contexts (Jest's node environment, vitest vmThreads/vmForks) and Node <18.18
Updated to parity with Claude Code v2.1.261

Update

npm install @anthropic-ai/claude-agent-sdk@0.3.261
# or
yarn add @anthropic-ai/claude-agent-sdk@0.3.261
# or
pnpm add @anthropic-ai/claude-agent-sdk@0.3.261
# or
bun add @anthropic-ai/claude-agent-sdk@0.3.261

Open source →

0.3.2603 Sept 20262 sources agree

Added optional user_message_uuid to thinking_tokens system messages, linking thinking progress to the user message that triggered the turn

What's changed

Added optional user_message_uuid to thinking_tokens system messages, linking thinking progress to the user message that triggered the turn
Added optional first_content_frame_ms, first_stream_post_ms, first_stream_post_ack_ms and first_stream_post_wall_ms fields to the success result message for remote-session latency breakdowns
Fixed managedSettings disableAutoMode: "disable" (either spelling) being dropped by the restrictive-only filter instead of turning auto mode off for the spawned session
Fixed rewindFiles() reporting success when no files could be restored (for example when checkpoint backups are missing); it now fails
Changed error_max_structured_output_retries results to append the last StructuredOutput tool error; validation errors now name the offending key, allowed values, and actual length or count
Changed rate_limit_event to also re-emit during an exceeded window on repeat 429s (about once per 30 seconds per limit window), so stream consumers can refresh stale rate-limit state
Updated to parity with Claude Code v2.1.260

Update

npm install @anthropic-ai/claude-agent-sdk@0.3.260
# or
yarn add @anthropic-ai/claude-agent-sdk@0.3.260
# or
pnpm add @anthropic-ai/claude-agent-sdk@0.3.260
# or
bun add @anthropic-ai/claude-agent-sdk@0.3.260

Open source →

0.3.2592 Sept 20262 sources agree

Added user_message_uuids beside user_message_uuid on a turn's first reply frame and result: every user message the turn answered, so a reply to severa

What's changed

Added user_message_uuids beside user_message_uuid on a turn's first reply frame and result: every user message the turn answered, so a reply to several merged messages can be matched to each
Added permissionPrompts: 'none' option to auto-deny permission prompts in sessions with nobody to answer them, without disabling auto mode's classifier
Updated to parity with Claude Code v2.1.259

Update

npm install @anthropic-ai/claude-agent-sdk@0.3.259
# or
yarn add @anthropic-ai/claude-agent-sdk@0.3.259
# or
pnpm add @anthropic-ai/claude-agent-sdk@0.3.259
# or
bun add @anthropic-ai/claude-agent-sdk@0.3.259

Open source →

0.3.2571 Sept 20262 sources agree

Added thinkingTokens to ModelUsage (a subset of outputTokens ), and fixed result-message usage.output_tokens_details.thinking_tokens reporting 0 inste

What's changed

Added thinkingTokens to ModelUsage (a subset of outputTokens), and fixed result-message usage.output_tokens_details.thinking_tokens reporting 0 instead of the session's real count
Added tool_use_result.resourceLinks on user messages carrying MCP tool results: the resource_link blocks the tool returned, so hosts can render returned files without parsing the result text
Added optional resource_links to task_notification for an auto-backgrounded MCP tool call that completed, listing the files it returned by reference; join to the call via tool_use_id
Fixed mcp_reconnect and mcp_toggle acting on a same-named .mcp.json / ~/.claude.json server instead of the --mcp-config or mcp_set_servers one
Fixed mcp_toggle disable also removing the tools of a sibling MCP server whose name extends the disabled one's (disabling foo dropped foo__bar's tools)
Changed mcp_set_servers to also list a server whose connection attempt throws under added (with a failed row in mcp_status), not only under errors
Changed Agent tool calls to emit the periodic tool_progress heartbeat (heartbeat: true) like other long tools; heartbeat frames never clear a subagent_retry indicator
Fixed the browser SDK bundle (@anthropic-ai/claude-agent-sdk/browser) never streaming any messages on engines without native Symbol.dispose (Safari/iOS, Firefox ESR, older Chromium)
Fixed a background Bash task that is still running when a stream-json session ends right after an interrupt (stdin closed) never receiving its final task_notification
Fixed -p giving up on a long-running background subagent without actually stopping it, so background_tasks_changed kept listing it and events for it arrived after its stopped notification
Added detail option to Query.getContextUsage(): 'summary' answers from the last response's usage and local estimates without per-category token-count API calls (default 'full')
Updated to parity with Claude Code v2.1.257

Update

npm install @anthropic-ai/claude-agent-sdk@0.3.257
# or
yarn add @anthropic-ai/claude-agent-sdk@0.3.257
# or
pnpm add @anthropic-ai/claude-agent-sdk@0.3.257
# or
bun add @anthropic-ai/claude-agent-sdk@0.3.257

Open source →

0.3.24726 Aug 20262 sources agree

Added an optional ambient flag to task_started , task_notification and background_tasks_changed task entries so hosts can exclude housekeeping tasks f

What's changed

Added an optional ambient flag to task_started, task_notification and background_tasks_changed task entries so hosts can exclude housekeeping tasks from activity indicators
Fixed the permissionMode on per-turn system/init frames reporting the mode at turn start instead of the live mode, so a mode switch right after submitting no longer sends a stale value

Update

npm install @anthropic-ai/claude-agent-sdk@0.3.247
# or
yarn add @anthropic-ai/claude-agent-sdk@0.3.247
# or
pnpm add @anthropic-ai/claude-agent-sdk@0.3.247
# or
bun add @anthropic-ai/claude-agent-sdk@0.3.247

Open source →

0.3.24625 Aug 20262 sources agree

Added optional user_message_uuid to error result messages and to the first assistant message or stream_event of each turn, linking a reply or failure

What's changed

Added optional user_message_uuid to error result messages and to the first assistant message or stream_event of each turn, linking a reply or failure to the user message that triggered it
Added modelUsage[*].costBasis ('list' | 'managed' | 'unknown') reporting which price table each model's costUSD was computed from
Added modelPricing support in the managedSettings option for hosts that set CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST; an admin-managed settings source that sets modelPricing still wins
Added perTaskStopAffordance option: when set, interrupt() aborts only the current turn and keeps background agents and workflows running; otherwise (and for one-shot string prompts) they stop

Update

npm install @anthropic-ai/claude-agent-sdk@0.3.246
# or
yarn add @anthropic-ai/claude-agent-sdk@0.3.246
# or
pnpm add @anthropic-ai/claude-agent-sdk@0.3.246
# or
bun add @anthropic-ai/claude-agent-sdk@0.3.246

Open source →

0.3.24324 Aug 2026

chore: Update CHANGELOG.md

Open source →

Additional notes

Added optional queued_turn_count to result messages: the number of queued user sends still pending when the result was produced, so hosts know whether another turn and result will follow
Fixed mcp_status reporting a remote MCP server as connected after its connection dropped; it now reports pending while reconnecting, then connected or failed
Fixed managed disableAllHooks also disabling hook callbacks registered through the hooks option; they now keep running, matching allowManagedHooksOnly
Changed Read tool PDF results: the document block (or page image blocks for pages reads) now arrives inside the tool_result content instead of as a separate user message after it
Updated to parity with Claude Code v2.1.243

Open source →

0.3.23921 Aug 20262 sources agree

total_cost_usd / modelUsage.costUSD now include the 1.1× US-only-inference (data residency) multiplier when the response reports inference_geo: "us"

What's changed

total_cost_usd / modelUsage.costUSD now include the 1.1× US-only-inference (data residency) multiplier when the response reports inference_geo: "us"
A result held back for background subagents in one-shot mode now reports total_cost_usd, duration_api_ms and modelUsage as of its release, not the turn-end snapshot
Fixed SYSTEM_PROMPT_DYNAMIC_BOUNDARY in an array systemPrompt being sent to the model as literal text on Bedrock, Vertex, Foundry, and gateway providers
A repeated initialize on a running process is now followed by a background_tasks_changed snapshot of the live background tasks, so reconnecting hosts see work that is still running

Update

npm install @anthropic-ai/claude-agent-sdk@0.3.239
# or
yarn add @anthropic-ai/claude-agent-sdk@0.3.239
# or
pnpm add @anthropic-ai/claude-agent-sdk@0.3.239
# or
bun add @anthropic-ai/claude-agent-sdk@0.3.239

Open source →

0.3.23820 Aug 20262 sources agree

Added is_backgrounded and spawn_depth to task_started events for subagent tasks ( is_backgrounded also on background Bash tasks)

What's changed

Added is_backgrounded and spawn_depth to task_started events for subagent tasks (is_backgrounded also on background Bash tasks)
Added suppressOriginalPrompt to UserPromptExpansion hook output, matching UserPromptSubmit
Added command_lifecycle state refused: a cross-session peer message the session's receive-side policy declines now reports this terminal state instead of producing no lifecycle frames
Fixed SDK hook callbacks silently not applying after a host re-sends initialize to an already-running CLI; the response now reports hooks_applied
Fixed CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION=true not keeping prompt_suggestion messages on when the account is near, but not over, its usage limit
Changed vcs_state_changed push events to emit one event per pushed branch

Update

npm install @anthropic-ai/claude-agent-sdk@0.3.238
# or
yarn add @anthropic-ai/claude-agent-sdk@0.3.238
# or
pnpm add @anthropic-ai/claude-agent-sdk@0.3.238
# or
bun add @anthropic-ai/claude-agent-sdk@0.3.238

Open source →

0.3.23417 Aug 20262 sources agree

Removed unused bypass_permissions_disabled from ExitReason type; the value was never emitted — TypeScript consumers with an explicit case branch get a

What's changed

Removed unused bypass_permissions_disabled from ExitReason type; the value was never emitted — TypeScript consumers with an explicit case branch get a compile error on upgrade (runtime unaffected)
Updated the ApiKeySource type to include the values system/init actually reports (ANTHROPIC_API_KEY, apiKeyHelper, /login managed key, none)
vcs_state_changed events report the directory the shell finished in (an inner cd is reflected)
A peer origin injected by the host may declare the sending session's permission class (fromMode) so a same-class message is delivered to a recipient that runs without asking
SDKSystemMessage (system/init) gains an optional effort field: the session's applied effort level, or null when none is sent. Set on Remote Control bridge init frames

Update

npm install @anthropic-ai/claude-agent-sdk@0.3.234
# or
yarn add @anthropic-ai/claude-agent-sdk@0.3.234
# or
pnpm add @anthropic-ai/claude-agent-sdk@0.3.234
# or
bun add @anthropic-ai/claude-agent-sdk@0.3.234

Open source →

0.3.23314 Aug 20262 sources agree

Notification hooks now fire for pending permission prompts on the SDK path, matching the interactive REPL behavior

What's changed

Notification hooks now fire for pending permission prompts on the SDK path, matching the interactive REPL behavior
Todo/task-tracking tools (TaskCreate/TaskGet/TaskUpdate/TaskList, TodoWrite) are no longer in the default tool surface on Opus 4.8, Sonnet 5, Fable 5, Mythos 5, and newer models; name them in the tools option or reference them in allowedTools (or set CLAUDE_CODE_ENABLE_TODO_TOOLS=1) to keep them

Update

npm install @anthropic-ai/claude-agent-sdk@0.3.233
# or
yarn add @anthropic-ai/claude-agent-sdk@0.3.233
# or
pnpm add @anthropic-ai/claude-agent-sdk@0.3.233
# or
bun add @anthropic-ai/claude-agent-sdk@0.3.233

Open source →

0.3.23213 Aug 20262 sources agree

Subagent MCP tool_result frames whose result carries _meta now emit tool_use_result as { content, _meta } (matching main-loop frames) instead of a bar

What's changed

Subagent MCP tool_result frames whose result carries _meta now emit tool_use_result as { content, _meta } (matching main-loop frames) instead of a bare value
/context result messages now carry a structured context_usage payload (new SDKContextUsage type), so consumers can render the context-usage card without parsing the markdown table
vcs_state_changed events now populate the branch field for push operations, sourced from the pushed ref

Update

npm install @anthropic-ai/claude-agent-sdk@0.3.232
# or
yarn add @anthropic-ai/claude-agent-sdk@0.3.232
# or
pnpm add @anthropic-ai/claude-agent-sdk@0.3.232
# or
bun add @anthropic-ai/claude-agent-sdk@0.3.232

Open source →

0.3.22912 Aug 20262 sources agree

Added terminal_slash_commands to the system init message so Remote Control clients can hide terminal-oriented commands

What's changed

Added terminal_slash_commands to the system init message so Remote Control clients can hide terminal-oriented commands
Changed conversations whose messages alone exceed the API's 32 MB limit to end the turn with terminal_reason "api_error" instead of "image_error"; StopFailure error_details is "request_body_over_limit: …"

Update

npm install @anthropic-ai/claude-agent-sdk@0.3.229
# or
yarn add @anthropic-ai/claude-agent-sdk@0.3.229
# or
pnpm add @anthropic-ai/claude-agent-sdk@0.3.229
# or
bun add @anthropic-ai/claude-agent-sdk@0.3.229

Open source →

0.3.2247 Aug 20262 sources agree

Added crossSessionInbound and dialogExpiry settings: cross-session messages sent to a session running with bypassed permissions are held for your appr

What's changed

Added crossSessionInbound and dialogExpiry settings: cross-session messages sent to a session running with bypassed permissions are held for your approval, and messages to other sessions auto-deliver
Added subkind: 'peer-send-message' to the task-notification member of SDKMessageOrigin, marking a notification raised by a cross-session SendMessage
Added source: 'archive' plugin config variant to Settings, with url and optional sha256, for installing plugins from a zip over HTTPS
Added sandbox credential-masking fields to Settings: decode: 'jwt' with maskClaims, extract/onExtractNoMatch on envVars, and awsPairs/sigv4 for AWS SigV4 re-signing
Fixed long (>200 char) project paths resolving to another project's session directory under a shared sanitized prefix; session list/get/rename/tag/fork/delete and /resume no longer cross projects

Update

npm install @anthropic-ai/claude-agent-sdk@0.3.224
# or
yarn add @anthropic-ai/claude-agent-sdk@0.3.224
# or
pnpm add @anthropic-ai/claude-agent-sdk@0.3.224
# or
bun add @anthropic-ai/claude-agent-sdk@0.3.224

Open source →

0.3.2235 Aug 20262 sources agree

Added resumeDropsTurn option: with resumeSessionAt, declares the turn a truncating resume intends to drop; the CLI refuses the resume if anything else

What's changed

Added resumeDropsTurn option: with resumeSessionAt, declares the turn a truncating resume intends to drop; the CLI refuses the resume if anything else would be discarded
Result messages for repeated 529 overload failures now include api_error_status: 529, so SDK consumers can detect overload terminations structurally instead of matching message text
Bare headless (-p / SDK query() without canUseTool) now emits system/permission_denied stream events when a tool call is auto-denied
Documented usage vs modelUsage on stream-json results: usage is main-loop-only and per-turn; modelUsage is cumulative, covers all query-pipeline calls, and is the field for cost accounting

Update

npm install @anthropic-ai/claude-agent-sdk@0.3.223
# or
yarn add @anthropic-ai/claude-agent-sdk@0.3.223
# or
pnpm add @anthropic-ai/claude-agent-sdk@0.3.223
# or
bun add @anthropic-ai/claude-agent-sdk@0.3.223

Open source →

0.3.2224 Aug 20262 sources agree

Fixed query({ sessionStore, resume }) not carrying user settings.json (apiKeyHelper, env, hooks, permissions) into the resumed subprocess

What's changed

Fixed query({ sessionStore, resume }) not carrying user settings.json (apiKeyHelper, env, hooks, permissions) into the resumed subprocess

Update

npm install @anthropic-ai/claude-agent-sdk@0.3.222
# or
yarn add @anthropic-ai/claude-agent-sdk@0.3.222
# or
pnpm add @anthropic-ai/claude-agent-sdk@0.3.222
# or
bun add @anthropic-ai/claude-agent-sdk@0.3.222

Open source →

0.3.2213 Aug 20262 sources agree

Improved skills option validation: malformed names (delimiters or control characters) and wildcard-form names are rejected with a clear error; use ski

What's changed

Improved skills option validation: malformed names (delimiters or control characters) and wildcard-form names are rejected with a clear error; use skills: 'all' to enable every skill
Fixed external MCP servers passed via the mcpServers option not being connected before the first turn, which caused the model to emit tool calls as literal text

Update

npm install @anthropic-ai/claude-agent-sdk@0.3.221
# or
yarn add @anthropic-ai/claude-agent-sdk@0.3.221
# or
pnpm add @anthropic-ai/claude-agent-sdk@0.3.221
# or
bun add @anthropic-ai/claude-agent-sdk@0.3.221

Open source →