npm / @anthropic-ai/claude-agent-sdk
@anthropic-ai/claude-agent-sdk
What changed in @anthropic-ai/claude-agent-sdk 0.3, from its official release notes, upgrade guides and advisories. Sources checked 2026-10-19.
44 breaking13 security1 deprecations154 new APIs and options4 performance49 behavior and defaults124 fixes and other
See which of these apply to your code, ranked, in your agent:
npx @unstale/cli init@anthropic-ai/claude-agent-sdk 0.3389 changes
Breaking changes 44
An omitted permissionMode now starts in default mode on third-party providers, with telemetry off or on a fresh install; pass permissionMode: 'auto' to keep auto mode.
When the API refuses a response, the result is now an error with no payload instead of delivering the response output as structured_output.
When a full disk prevents login refresh, api_error_status is now null instead of 401.
When a full disk prevents login refresh, the error is now invalid_request instead of authentication_failed.
Connector tools that an organization set to require approval no longer receive this option as true.
Values from PreToolUse and PermissionRequest hook callbacks are validated like Claude's own input, and unknown keys are dropped;
canUseToolis unchanged.When a user message merges several queued peer messages, origin.body is omitted instead of containing only the first message's text.
initialize, mcp_set_servers, and claim_session now refuse the reserved MCP server names __proto__, __defineGetter__, __defineSetter__, __lookupGetter__, and __lookupSetter__.
For permission answers received after a restart, lists with over 4,096 updatedPermissions entries count as a denial.
For MCP Apps tools, _meta over 8,388,608 JSON characters is left off tool_use_result.
_meta.ui with no ui:// resource no longer lifts the ordinary caps for MCP Apps tool results.
For MCP tools, result _meta over 1,048,576 JSON characters is left off, except for SDK-server tools.
User-message pasted_content is ignored when it contains more than 1,000 entries and blocks in total.
For MCP Apps tools, structuredContent over 8,388,608 JSON characters is left off tool_use_result.
Text blocks' _meta is left off when it totals over 65,536 characters.
This field is absent when a mod withheld the result of a tool that ran without error; it was previously permission-rule.
A permission answer with more than 4,096 updates, rules, and directories now counts as a denial.
For a finishing background task, this event now arrives after task_updated and task_notification.
For WebFetch or WebSearch calls that yield to a priority "now" message, the result is
{ detachedToolCall: true }and follows in a later turn.For MCP tools,
structuredContentover 1,048,576 JSON characters is omitted andstructuredContentOmitted: trueis set, except for SDK-server and MCP Apps tools.When permissionMode is omitted, Claude Code settings defaultMode now applies; on third-party providers or with telemetry off, sessions start in auto mode. Pass permissionMode: 'default' for manual approvals.
Now returns messages a subagent read while running, such as messages sent to it; offset and limit count those rows.
Bash and PowerShell timeout now bounds run_in_background commands; its default is 30 minutes and its maximum is 2 hours, and the stopped task notification explains when that limit stops a task.
Changing the effort level without ultracode turns Ultracode off.
The first turn still waits up to 2 seconds for connecting MCP servers named in allowedTools or by an mcp_tool hook, even when this variable is set to 0.
Drops content _meta keys under the CLI-reserved com.anthropic/ prefix when relaying resource results, matching tool-result behavior.
The attribution field's type is now boolean | {...}; TypeScript code reading attribution.commit from returned settings needs a type narrow.
Headless sessions cancel an MCP server's pending form question when the tool call that drew it ends.
Queued completions now share one model call; each still gets its own result, with all but the last empty and
num_turns: 0.Removes persistent from the MonitorInput tool type.
In plan mode, writes now go through canUseTool even when allowDangerouslySkipPermissions is set; the flag only enables switching to bypassPermissions later.
TaskCreate/Get/Update/List and TodoWrite are default tools only on the listed Claude and model versions; elsewhere, list them in
toolsorallowedTools.Reports failure when no files could be restored, such as when checkpoint backups are missing, instead of reporting success.
total_cost_usd and modelUsage.costUSD now include the 1.1× US-only-inference multiplier when the response reports inference_geo: "us".
Push events now emit one event per pushed branch.
Removed the unused bypass_permissions_disabled value; TypeScript consumers with an explicit case branch get a compile error on upgrade, with no runtime effect.
Todo/task-tracking tools are no longer in the default tool surface on Opus 4.8, Sonnet 5, Fable 5, Mythos 5, and newer models; name them in tools or allowedTools, or set CLAUDE_CODE_ENABLE_TODO_TOOLS=1, to keep them.
Subagent MCP tool_result frames with _meta now emit tool_use_result as { content, _meta }, matching main-loop frames.
Conversations whose messages alone exceed the API's 32 MB limit now end with terminal_reason "api_error" instead of "image_error"; StopFailure error_details is "request_body_over_limit: …".
Malformed and wildcard-form skill names are rejected with a clear error; use skills: 'all' to enable every skill.
Subagents no longer spawn nested subagents by default; the depth cap is lowered from 5 to 1. Set CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH to allow deeper nesting.
Unrecognized permission modes now produce an error instead of being silently adopted; the 'manual' alias is accepted at every ingress.
SessionStart hooks now report source
"fork"instead of"resume"when a session begins as a fork.Control requests now reject unrecognized model strings before latching.
Security 13
Deny and ask rules now match aliased tools with wildcard and match-all patterns, including when an input field is also in
disallowedTools.A hook callback returning
{ decision: 'block' }now declines the MCP elicitation.canUseTool options now include MCP server name and source, allowing hosts to key trust on the source.
Added a setting that holds cross-session messages sent to a session running with bypassed permissions for approval; messages to other sessions auto-deliver.
Fixed long project paths resolving to another project's session directory under a shared sanitized prefix; session operations and /resume no longer cross projects.
Added awsPairs for sandbox credential masking associated with AWS SigV4 re-signing.
Added extract to envVars as part of sandbox credential-masking configuration.
Added maskClaims for sandbox credential masking alongside JWT decoding.
Added onExtractNoMatch to envVars as part of sandbox credential-masking configuration.
Adds an SDK settings option for deterministically denying non-allowlisted hosts in sandboxed commands.
Maps isSynthetic to isMeta on ingestion so synthetic messages are not treated as real user messages.
Adds a setting for configuring credential file and environment variable denial in sandboxed commands.
MCP server-level specs mcp__server and mcp__server__* now correctly remove all tools from the named server instead of being silently ignored.
Deprecations 1
A runtime warning is added when canUseTool is configured alongside allowedTools or bypassPermissions, which shadow the callback.
New APIs and options 154
Exports the public built-in tool names for checking permission rules and tool settings.
Exports earlier built-in tool names for checking permission rules and tool settings.
Accepts addPlugins so a host can load more plugin folders into a running session.
sdk-type MCP server configs can set per-tool permission policies to always_ask or always_deny, applied on initialize and setMcpServers().
CronCreate and CronList tool outputs now optionally include the epoch millisecond time of the next run.
The elicitation control request includes form field names in MCP server order for hosts whose transport does not preserve JSON object key order.
AgentDefinition now supports setting a subagent to auto-compact earlier than the main conversation's window.
The initialize control response now includes the CLI version, so clients can know it before the first turn.
Adds overageEnabled to indicate whether the account has extra usage turned on when usage-limit warnings occur.
Task entries can optionally include a subagent type, so hosts can identify each subagent without pairing with task_started.
Assistant and user messages produced by a subagent now include its task ID, which remains stable when the subagent is resumed.
Each notification in ReadNotifications output can include when it reached the session.
Options now carry suppressAlwaysAllowRule: true for connector tools an organization requires approval for, allowing hosts to hide their always-allow choice.
The ListAgents tool result now provides typed notes so hosts can list agents without parsing its text.
Task notifications now include the run ID, letting hosts distinguish runs of a resumed task.
Task-started events and background-task entries now identify the subagent task that launched a task.
ReadNotifications output can include when the tool read the session's queued notifications.
SendMessage tool-use inputs on assistant messages now include recipient_kind, so hosts need not infer it from raw input.
Background task events now include a run ID so hosts can distinguish runs of a resumed task.
The ListAgents tool result now provides typed sections so hosts can list agents without parsing its text.
The WebFetch tool input accepts an optional offset for reading on through long pages.
The success result message can include this optional remote-session latency field.
The success result message can include this optional remote-session latency field.
The system/init capabilities now include sdk_mcp_manifests.
The initialize response now includes the sdk_mcp_manifests_parked field.
The system/init capabilities now include sdk_mcp_tools_list_changed.
The Artifact tool's structured read result can now include the artifact's stored title.
The Settings type now includes allowedProviders.
The startup_failure_reason type now includes provider_not_allowed.
Adds a setting that reports whether the session can run Ultracode, regardless of whether it is in effect.
Adds a setting that reports whether Ultracode is requested, independently of whether it is in effect.
The system/init message type now includes plugin_errors, with path identifying a --plugin-dir entry that did not load.
Adds a smaller entry point for apps that bundle the SDK, providing query, MCP tool helpers, session mutations, and resolveSettings; it uses the installed zod and MCP SDK.
Host-supplied managedSettings supports blockedMarketplaces, adding to the admin's blocklist.
Host-supplied managedSettings supports strictKnownMarketplaces; its allowlist applies only where admin policy sets none.
Starts a Claude Code process before its session is known so it can later be bound to a folder and per-session options.
Adds the alpha claim operation to bind a prewarmed Claude Code process to a folder and its per-session options.
Adds an optional timestamp field so clients can show when the reset happened.
Adds an optional trigger field so clients can tell what reset the conversation.
Adds an optional user_message_uuid field so clients can match a /clear to its message.
Tool entries now include MCP Apps ui metadata so a host can find the tool's ui:// resource.
This alpha API reads an MCP Apps ui:// resource from an MCP server connected by Claude Code.
Task-notification origins can include the optional fireReason field.
This option delivers prompts as written, without @path expansion or slash-command dispatch; on current CLIs, it also prevents ambient attachments with the prompt.
Success result messages can include this optional remote-session latency field.
Success result messages can include this optional remote-session latency field.
Success result messages can include this optional remote-session latency field.
Success result messages can include this optional remote-session latency field.
SDKUserMessage includes pasted_content for text the user pasted rather than typed, appended after the typed prompt.
SlashCommand has an optional builtin field indicating whether a command is built into Claude Code.
Set this environment variable to
1for stream-json hosts to emit per-phase startup timing in the session's first system/init.Set this environment variable to bound or disable (
0) the first-turn wait for connecting MCP servers.Stream-JSON error results now include the known startup failure reason before the run exits.
The first system/init can include a per-phase startup timing breakdown for stream-json hosts.
task_notification messages now include reason: "worker_restart" when a background task was stopped by a worker process restart.
Assistant messages delivering a headless /usage result now include a usage_report sibling containing session totals, the plan's usage rows as sent by the server, and extra usage.
Adds optional omitClaudeMd so a subagent can run without user, project and local CLAUDE.md files; managed policy files still load.
This optional hint makes the prompt open on its decline option.
This optional hint makes the prompt offer no persistent "always allow" choice.
Each category in the
get_context_usagecontrol response now identifies its kind as used, free, buffer, or deferred.A result message includes the slash command's name when a turn runs a slash command without entering the model loop.
Set
holdOnCacheImpact: trueto hold a plugin reload that would invalidate the session's prompt cache.Result messages now include the result's position in delivery order within the run, starting at 0.
Assistant, stream-event, and result messages include this field only on an automatic re-run of a turn interrupted by a host restart.
Added as an SSE option.
Added to the browser SDK's SSE transport.
Added to the browser SDK's SSE transport.
Added as an SSE option.
Added as an SSE option.
Synthetic turns started with isSynthetic: true and a uuid now include user_message_uuid and user_message_uuids in the first reply and result, identifying the message that started the turn.
The first reply and result of a turn Claude Code starts itself now include user_message_uuid and user_message_uuids, identifying messages sent that it picked up mid-turn.
Added the initialize delivery option to send plugins over stdin, preventing the launch command line from growing with the plugin count and fixing Windows start failures with many plugins.
The success result message can include this field for remote-session latency breakdowns.
The success result message can include this field for remote-session latency breakdowns.
The success result message can include this field for remote-session latency breakdowns.
The success result message can include this field for remote-session latency breakdowns.
Thinking-token system messages can include the user message UUID that triggered the turn, linking thinking progress to that message.
Added the 'none' option to auto-deny permission prompts in sessions with nobody to answer them, without disabling auto mode's classifier.
Added to a turn's first reply frame and result to identify every user message the turn answered, including replies to several merged messages.
Adds a detail option: summary uses the last response's usage and local estimates without per-category token-count API calls; full remains the default.
Notifications for completed auto-backgrounded MCP tool calls can list returned files by reference, joined to the call via tool_use_id.
User messages carrying MCP tool results now include returned resource_link blocks, allowing hosts to render returned files without parsing result text.
Adds a per-server timeout for SDK-hosted MCP servers, overriding MCP_TOOL_TIMEOUT for that server's tool calls.
Added an optional flag to task entries so hosts can exclude housekeeping tasks from activity indicators.
Hosts that set CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST can provide modelPricing through managedSettings; an admin-managed settings source that sets modelPricing still takes precedence.
modelUsage[*].costBasis reports which price table was used to compute each model's costUSD.
When set, interrupt() aborts only the current turn and leaves background agents and workflows running; otherwise, and for one-shot string prompts, they stop.
Error results and the first assistant message or stream_event of each turn can include user_message_uuid, linking the reply or failure to the user message that triggered it.
Added to task_started events for subagent tasks and background Bash tasks, so handlers can identify backgrounded tasks.
Added to task_started events for subagent tasks, so handlers can access the task's spawn depth.
Added to UserPromptExpansion hook output, matching UserPromptSubmit.
PostToolUse hooks can return a short host-asserted note about a tool call's result, which the auto mode permission classifier reads alongside that result.
The type now includes the values system/init actually reports: ANTHROPIC_API_KEY, apiKeyHelper, /login managed key, and none.
A host-injected peer origin may declare the sending session's permission class, allowing a same-class message to reach a recipient that runs without asking.
The system/init message gains an optional effort field containing the session's applied effort level, or null when none is sent; it is set on Remote Control bridge init frames.
/context result messages now include a structured context_usage payload with the new SDKContextUsage type, allowing consumers to render the context-usage card without parsing markdown.
The system init message now includes terminal_slash_commands so Remote Control clients can hide terminal-oriented commands.
Agent tool results now carry through usage.output_tokens_details, making that usage detail available in AgentOutput.
Added dialogExpiry as a setting; the notes do not specify its behavior.
Added the peer-send-message subkind to task-notification, identifying notifications raised by a cross-session SendMessage.
Added JWT decoding support for sandbox credential masking, with maskClaims.
Added sigv4 for AWS SigV4 re-signing in sandbox credential-masking configuration.
Added an archive plugin config variant with a URL and optional SHA-256 for installing plugins from a zip over HTTPS.
Result messages for repeated 529 overload failures now include this field, allowing SDK consumers to detect overload terminations structurally.
With resumeSessionAt, declares the turn a truncating resume intends to drop; the CLI refuses the resume if anything else would be discarded.
Adds a control-protocol lifecycle hook event fired when a new working directory is registered mid-session.
Result and init messages include fast_mode_disabled_reason so SDK hosts can explain why fast mode is off.
Opt-in cancel_queued cancels queued and pending-dispatch messages alongside the abort.
Adds an SDK settings option for setting the advisory dynamic-workflow size guideline.
Each modelUsage entry now includes canonicalModel so downstream billing can look up the correct rate table for costUSD.
Each modelUsage entry now includes provider so downstream billing can look up the correct rate table for costUSD.
Concurrently-running subagents are capped at 20 by default; override the cap with CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS.
The success result message can include an optional request_sent_wall_ms for cross-host request-latency correlation.
The rewindFiles response can include an optional skippedLinks count for paths safety guards refused to restore or delete.
User messages include a sidecar with non_execution_kind and user_feedback so consumers can classify denied, interrupted, or cancelled tool calls without matching result prose.
The success result message can include an optional user_message_uuid for cross-host request-latency correlation.
The
task-notificationmember can includesubkind: 'scheduled-trigger'to mark deliveries that are the fired prompt of a user-configured scheduled task.tool_progressmessages can includesubagent_retryso clients can show a subagent waiting out an API rate-limit retry.tool_progressmessages can includesubagent_typeso clients can show a subagent waiting out an API rate-limit retry.The live stream adds an ISO-8601 timestamp to assistant messages; older emitters omit it, so consumers should fall back to receive time.
Rate-limit message prefix buckets are available as @alpha exports, letting consumers classify rate-limit messages without maintaining mirrored lists.
Adds timedOutAfterMs to BashToolOutput, set when a command is auto-backgrounded on timeout.
A published SDK type for the Agent tool's structured result now matches the emitted object exactly.
Stream-json and SDK sessions now emit frames reporting each uuid-stamped message's terminal state.
Peer-message session events now expose the decoded message body in a structured body field.
system/init advertises the interrupt_receipt_v1 capability for feature detection.
Peer-message session events now expose the sender display name in a structured name field.
Interrupt control responses now include still_queued, the UUIDs of queued async messages that will still run.
A system message now reports the full set of live background tasks on every membership change, letting consumers track background activity as a level instead of pairing task_started and task_notification edges.
Subagent session messages now include parent_agent_id, enabling developers to build depth-2+ agent trees from disk-persisted metadata.
SDK inputs now accept 'manual' as an alias for the 'default' permission mode.
The canUseTool callback options include requestId to correlate out-of-band permission responses.
Returning null suppresses the SDK's automatic control response.
Progress events include a blocked field indicating when an agent was blocked by the auto-mode safety classifier.
Adds a per-server request_timeout_ms option to the mcp_set_servers control request.
Hook input payloads now include prompt_id to correlate hook events with OpenTelemetry prompt-level events.
Adds a method to re-send the initialize control request and redeliver pending permission and dialog prompts after a transport gap.
Added the promptSuggestions option to Browser SDK query() to opt the remote CLI into emitting follow-up suggestions.
The usage response now includes model_scoped for per-model weekly limit windows with utilization and reset times.
NotebookEdit tool results now include old_source for replace and delete operations, enabling inline diffs.
The rateLimitType field adds seven_day_overage_included for per-model weekly usage limits.
Control requests now include agent_id; background agents forward permission prompts to canUseTool instead of auto-denying, and stdin stays open while background tasks run.
SDK schemas add a dedicated tool type for MCP resource directory listing, replacing the fallback inside ReadMcpResourceTool.
A new control request supports rewinding a conversation to a previous point with durable resume anchor support.
Adds canUserPurchaseCredits to SDKRateLimitInfo for detecting credits-required rate limits.
Adds errorCode to SDKRateLimitInfo for detecting credits-required rate limits.
Adds hasChargeableSavedPaymentMethod to SDKRateLimitInfo for detecting credits-required rate limits.
Adds icon_url to assistant messages, populated from MCP server directory metadata.
Assistant messages can include an optional sidecar with display-friendly tool-call names, allowing SDK consumers to render human-readable labels instead of raw wire names.
Remote Control workers send a worker_shutting_down system message on graceful exit so remote clients can show why the session ended.
The message's trigger field now includes the server_error and last_resort values.
The SDK plugins option accepts skipMcpDiscovery: true per plugin, letting hosts manage MCP connections without the engine re-reading the plugin's .mcp.json.
Added claude-fable-5 to SDK model types, making it available as a model identifier.
Added the fable alias to SDK model types, making it available as a model identifier.
Performance 4
The browser SDK bundle is 40% smaller to download because it no longer bundles a Node
cryptopolyfill.The SDK package is smaller and loads faster because sdk.mjs no longer bundles unused dependencies.
Improves query() session startup with in-process MCP servers by running their handshake inside the SDK; initialize may wait up to 250 ms for them.
The first turn no longer waits up to 2 seconds for connecting MCP servers from settings files or plugins whose tool search defers; options.mcpServers servers are still awaited.
Behavior and default changes 49
Fork subagents are now on by default in SDK sessions, matching the terminal; run_in_background remains available, and CLAUDE_CODE_FORK_SUBAGENT=0 turns them off.
In auto mode, the final report now runs as its own turn instead of being joined with another message from the same subagent.
maxThinkingTokens: 0runs as adaptive thinking on models that cannot turn thinking off.thinking: { type: 'disabled' }runs as adaptive thinking on models that cannot turn thinking off.The default limit on MCP server instructions increased from 2,048 to 4,096 characters, including for in-process SDK servers.
The default limit on MCP tool descriptions sent up front increased from 2,048 to 4,096 characters.
Descriptions loaded through tool search, including those from in-process SDK servers, are now cut at 16,384 characters instead of 2,048.
When a long result is saved to a file or cut because it could not be, text kept past 500,000 characters is dropped with a note of how much.
The SDK now passes named option values to Claude Code in the same argument as their flag, using the --flag=value form.
The top-level approve field on SendMessage tool-use inputs is now always a boolean, so hosts need not infer it from raw input.
A person's priority now message moves running shell commands, agents and MCP calls to the background and joins the running turn instead of stopping it.
Setting ultracode to true preserves the current effort level instead of switching it to xhigh.
A renamed skill's directory name is added to its SlashCommand aliases when the name is plain and Claude Code has no command by that name.
Omitting max_thinking_tokens leaves the session's thinking budget unchanged; send null to reset it to the session default.
The CLI answers the host's initialize request before starting background start-up work, improving SDK session start-up.
Retry heartbeats continue while sub-agent work waits during unattended retry.
When asked during a running turn, side questions now see that turn's prompt, replies, and finished tool results so far.
A local host's declared scheduled-task fire is honored only in a process it started with this environment variable set to 1.
When an unattended retry waits on a usage limit, it emits a rate_limit_event with rejected and resetsAt as the wait begins.
With session-state events enabled, events report requires_action while an MCP elicitation waits on the user, as they do for permission prompts.
Usage report rows always carry is_active; reports relay rows only from a live server reply and none while the usage fetch is failing.
A one-line transcript notice appears when the SDK host's Stop or SessionStart hook callback times out, and is shown once until the host answers again.
Updated to parity with Claude Code v2.1.270; the notes do not specify which behaviors changed.
user_message_uuid, user_message_uuids and resume_reason are now stamped on a turn's first complete assistant message as well as its first stream event when partial messages are on.
The initialize success response always includes this field, empty when nothing is pending, so clients can distinguish it from an older CLI.
A model id the CLI does not know locally is confirmed with the API the first time a session uses it instead of being refused as unrecognized.
On an automatic re-run of an interrupted turn, this field now names that turn's last user prompt.
Recording now defaults on for custom prompts and appends; a mid-session prompt change takes effect at the next compaction.
Pass
snapshot: falseto keep per-request rendering.user_message_uuid is now set on the first reply after each change of the message a turn is answering, rather than on one reply frame per turn.
Re-emits during an exceeded window on repeat 429s about once every 30 seconds per limit window, letting stream consumers refresh stale rate-limit state.
Validation errors now identify the offending key, allowed values, and actual length or count.
Lists a server whose connection attempt throws under added as well as reporting a failed row in mcp_status.
Agent tool calls emit periodic heartbeat progress like other long tools; heartbeat frames do not clear a subagent_retry indicator.
Updated the SDK to parity with Claude Code v2.1.252; the notes do not specify which behaviors changed.
Updated the SDK to parity with Claude Code v2.1.251.
The SDK was updated to parity with Claude Code v2.1.241.
A repeated initialize on a running process is followed by a snapshot of live background tasks, allowing reconnecting hosts to see work that is still running.
A result held back for background subagents in one-shot mode reports total_cost_usd, duration_api_ms, and modelUsage as of its release rather than the turn-end snapshot.
Updated the SDK to parity with Claude Code v2.1.237.
Bare headless (-p / SDK query() without canUseTool) now emits this stream event when a tool call is auto-denied.
SkillToolOutput now reports background: true when a forked skill is dispatched as a detached background agent.
Assistant messages truncated by
interrupt()now carryaborted: true, allowing consumers to distinguish mid-stream partial messages from completed messages.Plugin entries in
system/initmessages andreload_pluginsresponses now include each plugin's manifest version.Query.interrupt() now returns the typed interrupt receipt.
Updated the SDK to parity with Claude Code v2.1.201.
Updated the SDK to parity with Claude Code v2.1.185.
Advisory messages now carry typed denial reasons safetyCheck and asyncAgent, letting SDK consumers programmatically match denial causes.
SDK consumers now receive this message for overloaded, server_error, and last_resort fallback triggers, in addition to model_not_found and permission_denied.
Fixes and other changes 124
Continues reporting a tool's _meta.ui.visibility when the rest of its _meta.ui fails validation.
A model ID now applies even when the account is at its five-hour or weekly usage limit; the next message reports the limit.
Transcript rows containing Unicode line or paragraph separators are no longer skipped on Node 24 and Bun.
When refusing with “unseen later turn,” the operation no longer stops the running turn first.
When queued user messages with content-block arrays are merged into one turn, they now have a line break between them.
For a message stopped during prompt hooks or plugins, rewind now returns rewound: true with null prefillText until a reply or input follows.
In-process SDK MCP servers named constructor or toString are no longer silently dropped when a prewarm() process is claimed.
The sandbox option now merges with an inline settings.sandbox block; option values win, and deny and credential lists from both are combined.
For permission answers received after a restart, a malformed updatedPermissions list is ignored as a whole.
Assistant text blocks no longer lose citations in streamed responses.
Fixes an MCP server added with mcp_set_servers sometimes keeping an outdated tool list when another server in the same request connects later.
Events with status allowed_warning now include overageDisabledReason, as allowed and rejected events already do.
Events with status allowed_warning now include overageResetsAt, as allowed and rejected events already do.
Events with status allowed_warning now include overageStatus, as allowed and rejected events already do.
Claude is no longer told an in-process MCP server was disabled by the user when it was switched off with toggleMcpServer().
When auto mode is unavailable, tool calls from subagents with a declared auto permission mode are decided by the canUseTool callback instead of the auto-mode classifier.
A repeated user message with the same UUID is replayed when a turn takes it, rather than while its first copy is still waiting for its turn.
This field is now also set on a turn resumed by a restarted worker after a permission answer or while tool calls are still in flight.
Failed Claude in Chrome tool calls now include
_metaintool_use_resultwhen the result has one, matching other MCP tools.This field is now also set on a turn resumed by a restarted worker after a permission answer or while tool calls are still in flight.
This field is now also set on a turn resumed by a restarted worker after a permission answer or while tool calls are still in flight.
Streams no longer leave a message without
message_stopwhen cut, interrupted, or falling back to non-streaming.The response now includes commands registered at startup, preventing
commands_changedfrom arriving beforeinitor twice at session start.A revoked claude.ai login now reports this specific authentication error instead of a generic or access-related message.
In-process MCP tool calls no longer remain waiting when this API removes their server.
In-process MCP tool calls no longer remain waiting when this API disables their server.
Fixed foreground subagents sometimes not receiving the task-tracking tools listed in tools or allowedTools.
When a tool's schema cannot be converted to JSON Schema, the server leaves that tool out with a warning naming it, rather than listing no tools.
Fixed disconnecting and re-enabling in-process MCP servers created with createSdkMcpServer(), except one named claude-in-chrome.
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.
Now includes a message sent while Claude was working if the process stops before the reply or another prompt follows without a reply in between.
Rewinding a conversation now stops a backgrounded MCP tool call started by the message that was removed.
Calling toggleMcpServer(name, false) now closes the connection for a server that had not connected when the session started or whose config changed after connecting.
A hook callback returning
{ decision: 'block' }now declines the MCP elicitation.Fixes forked sessions reading the wrong history in cases involving rewinds, progress rows, fork briefings, or compaction with messages kept.
Includes messages from other agents, sessions, and channels that appear in the CLI transcript.
Keeps stdin open for a follow-up turn woken by a finished background agent, preventing its hooks, canUseTool, and SDK MCP calls from failing with “Stream closed.”
No longer copies a rewound-away branch when the newest branch ends at a meta row or a local command's rows.
No longer returns a rewound-away branch when the newest branch ends at a meta row or a local command's rows.
Output now includes warnings and notices raised during a turn as system/informational messages instead of dropping them.
Permission and dialog callbacks are no longer invoked for requests that arrive after close().
Fixes control requests issued after a query closed hanging or leaking.
Permission prompts can now be cancelled after a cancelled request is redelivered.
Fixes session_state_changed remaining at requires_action after overlapping permission and sandbox network-access prompts are answered.
Updated the SDK to parity with Claude Code v2.1.278; the notes do not specify individual changes.
Resumed or forked sessions now continue get_usage totals from earlier turns instead of starting at zero; maxBudgetUsd is unchanged.
Resumed or forked sessions now continue modelUsage totals from earlier turns instead of starting at zero; maxBudgetUsd is unchanged.
Usage report rows always carry severity; reports relay rows only from a live server reply and none while the usage fetch is failing.
Resumed or forked sessions now continue total_cost_usd from earlier turns instead of starting at zero; maxBudgetUsd is unchanged.
forkSession({ upToMessageId }) now accepts a client-supplied SDKUserMessage.uuid that is not in UUID format.
forkSession now accepts the id returned by getSessionMessages for a message sent while Claude was working.
A fork no longer shows a re-run prompt twice.
Calling getSessionMessages() right after a turn's result message no longer sometimes misses the assistant message.
Queued messages Claude read while running a tool, including task notifications, now appear in the returned messages where Claude read them.
Deferred tool call results now use the tool_use_result key when the tool reruns at the start of a resumed turn.
Messages sent while Claude was running a tool are now returned as user messages where Claude read them.
Replayed user messages now include the task-notification origin when a background task finishes during a running turn.
Timed-out Stop, SubagentStop, or SessionStart hook callbacks now count as no decision instead of being reported as failures and discarding other hooks' decisions.
The browser SSE transport no longer drops live slash-command list updates.
Fixes finding sessions when dir is on a mapped network drive or SUBST drive on Windows.
Fixes finding sessions when dir is on a mapped network drive or SUBST drive on Windows.
Fixes finding sessions when dir is on a mapped network drive or SUBST drive on Windows.
Fixes resume losing the global config when it is stored under the legacy .config.json name or an OAuth-suffixed file name.
Interrupts and permission responses are no longer delayed while OAuth sign-in waits on a slow authorization server.
Fixed permission_denials omitting Read, Edit and Write calls blocked by a path-scoped deny rule.
task_started and task_notification now carry the agent's last call id when the CLI resumes a background subagent on its own.
A shell working directory changed with cd now persists across turns in multi-turn sessions instead of resetting to the cwd option at each new user message.
The success result now includes user_message_uuid when a turn sends no API request, such as for a slash command.
Fixed query() throwing "Object not disposable" in runtimes without a native Symbol.dispose, including certain Node vm contexts and Node <18.18.
Results now append the last StructuredOutput tool error.
The value "disable" is no longer dropped by the restrictive-only filter and turns auto mode off for the spawned session.
The browser SDK bundle now streams messages on engines without native Symbol.dispose, including Safari/iOS, Firefox ESR, and older Chromium.
Acts on the server configured through --mcp-config or mcp_set_servers rather than a same-named server in .mcp.json or ~/.claude.json.
Acts on the server configured through --mcp-config or mcp_set_servers rather than a same-named server in .mcp.json or ~/.claude.json.
Disabling a server no longer removes tools belonging to a sibling MCP server whose name extends the disabled server's name.
Adds thinkingTokens as a subset of outputTokens and reports the session's real thinking-token count in result-message usage.
Stops a long-running background subagent when giving up, preventing it from remaining listed or emitting events after its stopped notification.
A background Bash task still running when a stream-json session ends immediately after an interrupt now receives its final notification.
Per-turn
system/initframes now report the permission mode at turn start, avoiding a stale value when the mode switches right after submitting.Fixes array systemPrompt handling so SYSTEM_PROMPT_DYNAMIC_BOUNDARY is not sent to the model as literal text on Bedrock, Vertex, Foundry, and gateway providers.
Setting this environment variable to true now keeps prompt_suggestion messages on when the account is near, but not over, its usage limit.
A cross-session peer message declined by the session's receive-side policy now reports the terminal state refused instead of producing no lifecycle frames.
The response now reports hooks_applied when a host re-sends initialize to an already-running CLI, fixing SDK hook callbacks silently not applying.
Events report the directory the shell finished in, reflecting an inner cd.
Notification hooks now fire for pending permission prompts on the SDK path, matching interactive REPL behavior.
vcs_state_changed events now populate branch for push operations, sourced from the pushed ref.
Updated the SDK to parity with Claude Code v2.1.231; the notes do not specify which behaviors changed.
Fixed background subagents in headless/SDK sessions not resuming when a background shell command or Monitor they left running completed, so they can see the result.
Resumed subprocesses now carry user settings.json values for apiKeyHelper, env, hooks, and permissions.
External MCP servers passed via this option are connected before the first turn, preventing the model from emitting tool calls as literal text.
The initialize response now reports fast_mode_state from the current model after a model switch, rather than from the spawn-time model.
The result event now reports 429 or 529 instead of null for rate-limit and overloaded errors delivered mid-stream.
Fixed pending permission prompts not being re-sent to clients that connect after the prompt appeared.
The TypeScript type for
effortLevelnow accepts'max', which was already supported at runtime.Agent tool output now includes the resolved model when a mid-turn model swap changed the subagent's model.
Dash-leading values are now passed to the CLI using equals-form, preventing them from being interpreted as separate argv tokens.
Dash-leading values are now passed to the CLI using equals-form, preventing them from being interpreted as separate argv tokens.
Process-exit errors include the CLI's stderr output, reporting the child process's actual cause instead of only an exit code.
With --include-partial-messages, the turn-start user replay is emitted before the turn's content events instead of after the first content block.
Streaming queries sharing one controller no longer accumulate abort listeners on its signal after each completed query.
Dash-leading
extraArgsvalues are now bound with equals-form argv instead of being parsed as their own CLI flags.Clarified that
MCP_TOOL_TIMEOUTis the environment variable for configuring the MCP tool-call timeout.A caller abort during a pending hook callback no longer becomes hook success, preventing PreToolUse-gated tools from executing after the abort.
Fixed a per-query resource leak when spawning the CLI fails because the executable path is nonexistent or inaccessible.
Fixed an uncaught exception when writing to stdin after the Claude Code subprocess has exited.
A hook callback timeout now blocks the prompt with a clear timeout message while allowing the session to continue, rather than killing the query with an empty error.
Allowing a tool without updatedInput now runs it with the original input instead of rejecting it with a raw ZodError message.
Zero-API results no longer report stale duration_api_ms values.
Fixed stable releases shipping sdk.d.ts with unresolved type references that broke consumer typechecking when skipLibCheck was disabled.
Non-object settings values now return a control error instead of crashing the session.
The callback now fires for SDK-hosted Remote Control sessions.
Prevents workflow progress events from silently dropping earliest agents while the phase counter remains correct.
Fixed deduplication dropping tool-use IDs after 1000 resolutions, which could cause duplicate tool_result deliveries in long-running sessions.
Ensures the event is emitted for synced skills when the skill list resolves before the change-detector subscribes.
Fixed brief console window flashes on Windows when spawning CLI subprocesses.
Fast mode no longer reverts to standard after the first turn when settingSources includes user or project settings.
SDK-hosted Remote Control sessions no longer drop file_attachments from inbound user messages.
Fixed
-pmode exiting before a completed background agent's notification arrived, which could cause interim text to be delivered as the final result.The turn result is emitted at the turn boundary, and the session reports idle while background tasks continue.
Spawn failures on an existing native binary now explain a likely musl/glibc mismatch and suggest options.pathToClaudeCodeExecutable.
Hook block feedback is now emitted to the SDK event stream, so consumers can see why a prompt was blocked instead of encountering a silent hang.
Fixed background agent, remote agent, and MCP task state not being restored when resuming a session via the SDK.
Fixed turn result messages being dropped when multiple turns complete while a background agent or workflow is running.
Input such as
/ add testsis no longer silently dropped and is treated as a plain prompt.