- Breaking: Changed
query(),startup()andprewarm()to refuse options that can't be sent to Claude Code, such as an agent with a circular or BigInt field. Fix the named option. - Breaking: Changed hook options to require arrays: a hook event's value and a matcher's
hooks. A Set, generator, plain object,trueor number is now refused. - Fixed
task_startedsending Claude Code's own text, such as a task notification, aspromptwhen a background subagent is woken; such an event now has noprompt - Fixed Claude reporting a background agent as still running when its permission request had waited on
canUseToolfor 30 seconds or more - Reverted 0.3.326's fix for a tool result from an SDK MCP server being lost, or delivered to another call, after a reconnect
- Changed the JSON-RPC
idof requests to an SDK MCP server back from a string to a number - Changed background retries for most MCP servers on other machines, reached by hostname over https, to go on for about a day after a drop, up from at most about 27 minutes
- Deprecated
createSdkMcpServer()servers in an agent'smcpServers: ignored with a warning, and other options apply. Move them to top-levelmcpServers, which gives the main session their tools. - Updated to parity with Claude Code v2.1.327
- Added
mcpServersDelivery: 'initialize': sendsmcpServersin the initialize request instead of on Claude Code's command line; needs the bundled Claude Code or newer - Added
getSessionInfo()to the/coreentry - Added
message_uuidtocancel_async_messageresponses, naming the dropped message - Added a warning on stderr and as a
system/informationalmessage when a tool list has an entry that doesn't look like a complete rule - Added a
system/informationalwarning, taggedmanaged_mcp_arrived, when an administrator'smanaged-mcp.jsonarrives during a session and your own MCP servers stop loading - Fixed a tool call in a running turn reconnecting to an MCP server just removed with
setMcpServers(), or reporting that it needs authentication; the call is now refused - Fixed
resumeSessionAtfailing on an empty reply, and a resumed session losing recent turns after a crash when the previous turn ended with one - Fixed a tool result from an SDK MCP server being lost, or delivered to another call, when a long call overlapped a reconnect of the SDK MCP servers
- Fixed a hook request that arrives while the SDK is still starting up being refused instead of answered
- Improved how secrets are masked in the
descriptionpassed tocanUseTool;inputitself is unchanged - Improved the first turn after
SpareProcess.claim(): it no longer waits up to 500 ms for the stdio MCP servers the claim starts, where tool search loads their tools on demand - Changed the JSON-RPC
idof requests to an SDK MCP server from a number to a string - Changed
rewindFiles()on macOS, Linux and WSL to leave some files untouched when the sandbox is on, and report them as skipped - Changed the
register_repo_rootcontrol request to refuse some folders it used to accept - Deprecated sending
mcpServerson Claude Code's command line (today's default,'argv'): a future release defaults to'initialize'; apps running an older Claude Code must update it or set'argv' - Updated to parity with Claude Code v2.1.326
- Added
archiveSession()andunarchiveSession(), and anarchivedfield on the sessions thatlistSessions()andgetSessionInfo()return - Added
refuseIfBusytoQuery.reloadPlugins()so a host can have a reload refused while the session is busy - Added
managed_locktoplugin_errorsentries onsystem/init, naming the managedenabledPluginsentry that dropped a plugin copy - Added a
system/informationalwarning, taggedhook_no_verdict, when aPreToolUsehook can't run or answer, or times out, without refusing its tool call - Added
invalid_config_fileto theconfig_file_invalidstartup failure result: the broken config file's path and its backup's path as fields - Fixed deny rules (
disallowedTools,permissions.deny,always_deny) that name an in-process SDK MCP tool or its server, or match it with a glob, leaving it in Claude's tool list andsystem/init - Fixed
supportedEffortLevelsin model info listing effort levels above the organization's effort cap or themaxEffortLevelsetting - Changed the
sandboxoption: sandboxed Bash commands are no longer auto-approved unlessautoAllowBashIfSandboxed: trueis set - Changed read-only git commands in a repository that isn't the working directory's, an additional directory's or a trusted one to go through the permission flow instead of being auto-approved
- Changed
applyFlagSettings()to reject when a value would make Claude Code discard its settings layer, applying nothing and keeping settings from earlier calls - Changed
suggestionsoncanUseToolfor Bash and Monitor: a list of rules alone is sent only when saving it would allow that command - Changed the
ProposeSkillsInputtype: a proposal can carryedits, andskillMdis optional - Updated to parity with Claude Code v2.1.325
- Updated to parity with Claude Code v2.1.324
- Added
machinePolicy.didNotLoad(alpha) toresolveSettings()'s result, which tells a host when a machine policy source may be there and did not load - Added
matchDeniedModels()(alpha), which tells a host which models adeniedModelslist blocks, by Claude Code's own entry rules - Added the periodic
tool_progressheartbeat while a turn waits on long-running hooks;tool_nameis the hook event,tool_use_idbeginshook-,parent_tool_use_idmay name no tool call - Added
CLAUDE_CODE_DISABLE_AGENT_PROGRESS_SUMMARIES: set to1to turn off subagent progress summaries even whenagentProgressSummariesistrue(available since 0.3.318) - Added
tool_use_resultto a subagent's WebSearch result message when the search did not run or found nothing - Fixed progress notifications from SDK MCP servers being dropped for tool calls that were still running when the set of SDK MCP servers changed
- Fixed
resolveSettings()keeping its first reading of a macOS MDM profile or Windows registry policy for the life of the process: it now re-reads after 30 minutes, and sooner after a read that failed - Fixed
forkSession()withupToMessageId: forking at a compaction summary no longer brings back the messages kept after it, and forking at a compaction boundary keeps the conversation before it - Fixed
getSessionMessagesleaving out a queued prompt that directly follows a compaction summary - Fixed
canUseToolsuggestions including a Bash allow rule for commands that write to sensitive paths such as.gitor.claude, where the rule did not stop the next request - Fixed most
initializeoptions, such as agents and skills, being ignored when aSessionStarthook supplied the first message - Fixed an MCP server removed and re-added with
setMcpServers()stayingneeds-authwith no tools when a tool call had tried to reach it in between - Fixed
init.plugin_errorsomitting a plugin that only project settings enable but that isn't installed; it now reports it as not installed, with the install command - Changed
init.plugin_errorsto also list load errors of plugins that managed settings enable; a check on it can trip before the background install ends (CLAUDE_CODE_SYNC_PLUGIN_INSTALL=1waits) - Changed
supersedeson assistant messages to also be sent after a response whose tool call could not be parsed - Changed what happens when a tool's permission check fails with an error after a
PreToolUsehook allowed the call: it now goes tocanUseTool, or is refused when there is no callback - Updated to parity with Claude Code v2.1.323
- Updated to parity with Claude Code v2.1.322
- Fixed
canUseToolgetting the app's own PreToolUse hook reason indecisionReasonwhen another hook also asked - Fixed a PreToolUse hook's
askbeing lost when another hook'sdeferfinished first and could not be honored - Fixed every hook being dropped when one event in the
hooksoption is set toundefined - Fixed
WarmQuery.query()with a string prompt hanging afterstartup()withresumewhen the resumed session finished a turn of its own before the prompt was sent - Fixed
setMcpServersclosing a folder's.mcp.jsonor local-scope MCP server when passed an in-process server of the same name, in sessions bound withSpareProcess.claim() - Fixed
reloadSkills(),reloadPlugins()andsystem/initdropping project skills, commands or agents that a worktree lacks after Claude entered it - Fixed sessions hanging on save, and
importSessionToStore()never rejecting, when memory ran out while a transcript was being read - Improved
resumeandcontinueon the bundled Claude Code binary:initializeis read during boot, so start-up work is less likely to run before your hooks are registered - Changed queued subagent reports in auto mode to share one model call: each keeps its own message and result, and all but the last end in an empty
resultwithnum_turns: 0 - Changed an SDK MCP server named
claude-in-chrometo follow the organization's Claude in Chrome policy: where the policy denies it, the server is not connected - Updated to parity with Claude Code v2.1.321
- Updated to parity with Claude Code v2.1.320
- Added MCP task support in SDK sessions (not on Bedrock, Vertex or Foundry): with
CLAUDE_AUTO_BACKGROUND_TASKS=1and streaming input, an MCP task runs in the background withtask_type"mcp_task" - Fixed the OpenTelemetry
claude_code.session.countmetric countingprewarm()processes that were never claimed; a pre-started process now counts once, whenSpareProcess.claim()succeeds - Fixed
session_writes_lostlisting the wrong session intranscript_session_idsafter/clearin a session resumed from a transcript file outside the projects folder - Improved
deleteSession()to reject withENOTEMPTYif the session's folder could not be fully deleted - Changed
session_writes_lostto be sent only when the CLI exits 0; a run that ends on an error result now gets only the stderr line - Updated to parity with Claude Code v2.1.319
- Added an optional
credential_expires_atfield to result messages: when the stored claude.ai sign-in in use ends - Added the
config_file_invalidstartup failure reason, reported when a configuration file read at startup isn't valid JSON - Fixed the interrupt response missing a message held behind a model change: it is now listed, cancelled with
cancel_queued, and stopped at start-up as a queued message is - Changed
agentProgressSummaries: while the subagent waits for a response on a likely-cold prompt cache, a summary can wait up to 5 minutes, and is not sent if the subagent ends first - Changed
statusinPushNotificationInputto optional - Updated to parity with Claude Code v2.1.318
- Added
onFailureto hook matchers: with"block", a hook that throws or returns invalid output blocks the action - Added a warning message in the stream when a hook callback fails
- Added a
session_writes_lostsystem message, sent after the last result when a full disk or disk quota kept the CLI from saving the session transcript or ~/.claude.json - Added
initialize_not_firsttostartup_failure_reason, for a--await-initializelaunch whose first stdin line is not the initialize request - Added
task.descriptionto the TaskCreate tool'stool_use_result: the description the task was created with - Added
lossytoreadFile()utf-8 answers:truewhen decoding replaced bytes that are not valid UTF-8 - Removed the
file_unchangedvariant ofFileReadOutputinsdk-tools.d.ts; a repeated Read now returns the file content - Fixed
setMcpServersclosing a folder's.mcp.jsonand local-scope MCP servers in sessions started withprewarm()and bound withSpareProcess.claim() - Updated to parity with Claude Code v2.1.317
- Added
permissions.blockReadsExemptPathsto theSettingstype: paths, read only from--settingsand settings the host sends, thatblockReadsOutsideWorkingDirectorieslets through without making them working directories - Updated to parity with Claude Code v2.1.316
- Updated to parity with Claude Code v2.1.315
- Added
sandbox_required_unavailabletostartup_failure_reason, for the result Claude Code writes when a required sandbox cannot run - Added
permissions.blockWritesOutsideWorkingDirectoriesto theSettingstype - Added
prewarm()(alpha) to the@anthropic-ai/claude-agent-sdk/coreentry point - Fixed a settings file left out of
settingSourcesstill supplying some settings, such as auto mode rules and saved permission consents - Updated to parity with Claude Code v2.1.314
- Updated to parity with Claude Code v2.1.313
- Added
autoMode,skipAutoPermissionPrompt,useAutoModeDuringPlanandpermissions.disableAutoModeto theSettingstype - Added
unanswered(skipped,replied_in_chatordismissed) to AskUserQuestion answers' per-questionannotations; send it only whensystem/initlists theask_user_question_unanswered_v1capability - Fixed
resolveSettings()returning mistyped managed auto-mode settings, such aspermissions.disableAutoMode: true, as written instead of reading them as the CLI does; a user or project settings file whose auto-mode keys hold an invalid value is now skipped, as in the CLI - Updated to parity with Claude Code v2.1.312
- Added
cacheCreationEphemeral5mInputTokensandcacheCreationEphemeral1hInputTokenstoModelUsage, splittingcacheCreationInputTokensby cache lifetime - Changed background start-up work to wait until the first model request is sent, for about 10 seconds at most, when the first message arrives during start-up
- Changed the minimum supported Node.js version from 18.0.0 to 18.14.0
- Updated to parity with Claude Code v2.1.311
- Updated to parity with Claude Code v2.1.310
- Fixed host-supplied
managedSettingsdroppingdisableAllHooks,disableSkillShellExecutionand emptyallowedHttpHookUrls/httpHookAllowedEnvVarslists - Changed
extractFromBunfs()to extract the embedded CLI into its own per-user temp directory (claude-agent-sdk-<uid>, orclaude-agent-sdkon Windows) instead of Claude Code's temp root - Changed
extractFromBunfs()to reuse an already-extracted file only when its bytes match the embedded binary, replacing it otherwise - Updated to parity with Claude Code v2.1.309
- Updated to parity with Claude Code v2.1.308
- Added
wakeup_sourceto thecommand_lifecyclestartedframe of a scheduled wakeup or task, andscheduled_forfor a wakeup (capabilitylifecycle_wakeup_source_v1), so a host can tell which one fired - Added
supportedDialogKindsto browser SDKquery(), sent oninitialize; a non-empty list requiresonUserDialog - Updated to parity with Claude Code v2.1.307
- Updated to parity with Claude Code v2.1.306
- Added
recommendationsandfixto theget_usageresponse's behavior windows - Fixed servers set with
setMcpServersbeing replaced later in the session by a same-named server from the user's own settings - Fixed
startup()withinitializeTimeoutMs: nullcounting time spent in SessionStart or Setup hooks against its 60-second limit;nullnow works like leaving the option out - Changed the
startup()andprewarm()timeout error for a start with no open SessionStart or Setup hook: it lists possible causes and no longer says to check authentication and network - Updated to parity with Claude Code v2.1.305
- Added
suspendSseStream(query)andresumeSseStream(query)to the browser SDK: close a query's event stream and reopen it later without ending the query - Added stable row ids to
getContextUsage(), and, when the CLI answers on its own stdio, plugin ids, agent and skill file paths, and per-server MCP instruction token shares - Fixed
startup()timing out while a SessionStart or Setup command hook was running when noinitializeTimeoutMsis passed: up to 10 minutes of that time no longer counts toward the 60-second limit, and the timeout error now says what the process reported - Fixed
startup()keeping everyhook_progressmessage of a running SessionStart or Setup hook in memory until it resolved; it now keeps only the newest one for each hook - Updated to parity with Claude Code v2.1.304
- Updated to parity with Claude Code v2.1.303
- Fixed structured output results delivering a response's output as
structured_outputwhen the API refused that response; the result is now an error with no payload - Changed an omitted
permissionModeto start indefaultmode on third-party providers, with telemetry off or on a fresh install; passpermissionMode: 'auto'to keep auto mode - Changed fork subagents (
subagent_type: "fork") to be on by default in SDK sessions, as in the terminal;run_in_backgroundis still offered, andCLAUDE_CODE_FORK_SUBAGENT=0turns them off - Updated to parity with Claude Code v2.1.302
- Added per-tool permission policies to sdk-type MCP server configs:
toolsentries withpermission_policyalways_askoralways_deny, applied oninitializeandsetMcpServers() - Added
BUILTIN_TOOL_NAMESandLEGACY_TOOL_NAME_ALIASESexports: the public built-in tool names and their earlier names, for checking permission rules and tool settings - Added
addPluginstoQuery.reloadPlugins()so a host can load more plugin folders into a running session - Fixed
setModel()with a model ID failing while the account is at its five-hour or weekly usage limit; the model now applies and the next message reports the limit - Changed the error when a full disk keeps the login from being refreshed:
erroris nowinvalid_request, notauthentication_failed, andapi_error_statusisnull, not 401 - Changed
mcpServerStatus()to still report a tool's_meta.ui.visibilitywhen the rest of its_meta.uifails validation - Updated to parity with Claude Code v2.1.301
- Fixed
importSessionToStoreskipping transcript rows that contain a Unicode line or paragraph separator (U+2028, U+2029) on Node 24 and Bun - Fixed a background subagent's final report in auto mode being joined into one turn with another message from the same subagent; the report now always runs as its own turn
- Fixed
rewind_conversationwithinterrupt_if_runningstopping the running turn before refusing with "unseen later turn" - Reverted
canUseTooloptions carryingsuppressAlwaysAllowRule: truefor connector tools that an organization set to require approval (added in 0.3.292) - Improved the browser SDK bundle (
@anthropic-ai/claude-agent-sdk/browser): 40% smaller to download, by no longer bundling a Nodecryptopolyfill - Changed
thinking: { type: 'disabled' }andmaxThinkingTokens: 0to run as adaptive thinking on models that can't turn thinking off - Changed
updatedInputfrom PreToolUse and PermissionRequest hook callbacks: it is now validated like Claude's own input and unknown keys are dropped;canUseToolis unchanged - Updated to parity with Claude Code v2.1.300
- Added an optional
nextFireAt(epoch ms of the next run) to the CronCreate and CronList tool outputs - Added
property_orderto theelicitationcontrol request: a form's field names in the order the MCP server listed them, for hosts whose transport keeps no JSON object key order - Fixed
rewind_conversationanswering "target not found" for a message stopped during its prompt hooks or plugins: until a reply or input follows, it answersrewound: truewith a nullprefillText - Fixed in-process SDK MCP servers named
constructorortoStringbeing silently dropped when aprewarm()process is claimed withSpareProcess.claim() - Fixed queued user messages with content-block arrays running together without a line break when merged into one turn
- Fixed
origin.bodyon a user message that merges several queued peer messages (from other sessions or agents) carrying only the first message's text; it is now omitted - Changed
initialize,mcp_set_serversandclaim_sessionto refuse the reserved MCP server names__proto__,__defineGetter__,__defineSetter__,__lookupGetter__,__lookupSetter__ - Updated to parity with Claude Code v2.1.299
- Updated to parity with Claude Code v2.1.298
- Updated to parity with Claude Code v2.1.297
- Added
claude_code_versionto theinitializecontrol response so clients know the CLI version before the first turn - Added
autoCompactWindowtoAgentDefinition, so a subagent can auto-compact earlier than the main conversation's window - Fixed the
sandboxoption discarding an inlinesettings.sandboxblock: the two now merge, the option's values win, and deny and credential lists from both sides are combined - Changed the default limit on MCP tool descriptions sent up front and on MCP server instructions, in-process SDK servers included, from 2,048 to 4,096 characters
- Changed permission answers that arrive after a restart to be parsed like live ones: over 4,096
updatedPermissionsentries count as a denial, and a malformed list is ignored as a whole - Updated to parity with Claude Code v2.1.296
- Added
overageEnabledtoSDKRateLimitInfo: on usage-limit warnings, whether the account has extra usage turned on - Fixed an MCP server added with
mcp_set_serverssometimes keeping an outdated tool list when another server in the same request connected later - Fixed assistant text blocks losing their
citationsin streamed responses - Fixed Claude being told "disabled by the user" about an in-process MCP server that was switched off with
toggleMcpServer() - Fixed
rate_limit_eventwith statusallowed_warningomittingoverageStatus,overageResetsAtandoverageDisabledReason, whichallowedandrejectedevents already carry - Changed MCP tool descriptions the model loads through tool search, including those from in-process SDK servers, to be cut at 16,384 characters instead of 2,048
- Changed a permission answer whose
updatedPermissionsholds over 4,096 updates, rules and directories to count as a denial - Changed
tool_result_meta[].non_execution_kindto be absent when a mod withheld the result of a tool that ran without error; it waspermission-rule - Changed
pasted_contenton user messages to be ignored when it holds over 1,000 entries and blocks in all - Changed how the SDK passes option values to Claude Code: the values of its named options are now sent in the same argument as their flag (
--flag=value) - Changed
tool_use_resultfor MCP Apps tools:structuredContentor_metaover 8,388,608 JSON characters is left off, and_meta.uiwith noui://resource no longer lifts the ordinary caps - Changed
tool_use_resultfor MCP tools: when a long result is saved to a file, or cut because it could not be, the text kept past 500,000 characters is dropped, with a note of how much - Changed
tool_use_resultfor MCP tools: a result_metaover 1,048,576 JSON characters is left off, except for SDK-server tools; so is text blocks'_metathat totals over 65,536 - Updated to parity with Claude Code v2.1.295
- Updated to parity with Claude Code v2.1.294
- Added an optional
subagent_typetobackground_tasks_changedtask entries, so hosts can name each subagent's type without pairing withtask_started - Updated to parity with Claude Code v2.1.293
- Added
agent_idto theassistantandusermessages a subagent produces; it equals thetask_idon that subagent's task events and stays the same when the subagent is resumed - Added
parent_task_idtotask_startedevents andbackground_tasks_changedentries, naming the subagent task that launched a task - Added
run_idto background task events andorigin.runIdto task notifications, so a host can tell a resumed task's runs apart - Added typed
sectionsandnotesto theListAgentstool'stool_use_result, so hosts can list agents without parsing its text - Added
recipient_kindto SendMessagetool_useinputs on assistant messages, and their top-levelapproveis now always a boolean, so hosts no longer infer them from the raw input - Added two optional fields to the
ReadNotificationstool output:read_at, when the tool read the session's queued notifications, andarrived_aton each notification, when it reached the session - Fixed subagents with a declared auto permission mode having their tool calls decided by the auto-mode classifier instead of the canUseTool callback when auto mode is unavailable
- Changed
background_tasks_changedfor a finishing background task to arrive after that task'stask_updatedandtask_notification - Changed
canUseTooloptions to carrysuppressAlwaysAllowRule: truefor connector tools that an organization set to require approval, so hosts can hide their "always allow" choice - Updated to parity with Claude Code v2.1.292
- Updated to parity with Claude Code v2.1.291
- Added an optional
offsetfield to the WebFetch tool input for reading on through long pages - Fixed failed Claude in Chrome tool calls dropping the result's
_meta: when the result has one,tool_use_resultis now{ content, _meta }, as for other MCP tools - Fixed deny and ask rules missing
toolAliasestools when written with a wildcard (Bash*), a match-all pattern (Bash(**), also on the mapped name), or an input field also indisallowedTools - Fixed a user message sent again under the same
uuidbeing replayed (--replay-user-messages) while the first copy still waited for its turn; its replay now comes when a turn takes it - Fixed
includePartialMessagesstreams leaving a message withoutmessage_stopwhen the stream was cut, interrupted or fell back to non-streaming - Changed
user_message_uuid,user_message_uuidsandresume_reasonto also be set on a turn a restarted worker resumes from a permission answer or from tool calls still in flight - Updated to parity with Claude Code v2.1.290
- Updated to parity with Claude Code v2.1.289
- Updated to parity with Claude Code v2.1.288
- Added optional remote-session latency fields (
first_text_post_queue_wait_ms,first_text_post_queued_behind) to the success result message - Fixed
includePartialMessagesstreams sending a cut-short reply'smessage_stoplate 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 orsetMcpServers()removed it - Fixed
commands_changedarriving beforeinit, or twice, at session start: theinitializeresponse now includes commands registered at startup - Changed
tool_use_resultfor 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_resultfor MCP tools:structuredContentover 1,048,576 JSON characters is left off andstructuredContentOmitted: trueset, except for SDK-server and MCP Apps tools - Updated to parity with Claude Code v2.1.287
- Added the initialize response field
sdk_mcp_manifests_parkedand thesystem/initcapabilitiessdk_mcp_manifestsandsdk_mcp_tools_list_changed - Fixed foreground subagents sometimes not receiving the task-tracking tools listed in
toolsorallowedTools - 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 withcreateSdkMcpServer(), except one namedclaude-in-chrome - Changed a person's priority
nowmessage 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
permissionModeto Claude Code, so a settingsdefaultModenow applies and, on third-party providers or with telemetry off, the session starts in auto mode likeclaude -p; passpermissionMode: 'default'for manual approvals - Updated to parity with Claude Code v2.1.286
- Added an optional
read.title(the artifact's stored title) to the Artifact tool's structured read result - Added
provider_not_allowedtostartup_failure_reasonandallowedProvidersto theSettingstype - 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_conversationleaving a backgrounded MCP tool call running after the message that started it was removed - Changed Bash/PowerShell
timeoutto bound arun_in_backgroundcommand (was ignored; default 30 min, max 2 h); thestoppedtask 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;offsetandlimitcount these rows - Updated to parity with Claude Code v2.1.285
- Added a renamed skill's directory name to its
SlashCommandaliaseswhen the name is plain and Claude Code ships no command by that name - Added
applied.ultracodeAvailableandapplied.ultracodeRequestedtogetSettings(): 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,canUseTooland SDK MCP calls with "Stream closed" - Changed the first turn to still wait up to 2s for connecting MCP servers named in
allowedToolsor by anmcp_toolhook, even withCLAUDE_CODE_MCP_STARTUP_WAIT_MSset to0 - Changed
applyFlagSettings({ ultracode: true })to keep the current effort level instead of switching toxhigh; aneffortLevelthat changes the level withoutultracodeturns Ultracode off - Updated to parity with Claude Code v2.1.284
- Added
plugin_errorsto theSDKSystemMessagetype (system/init), includingpathfor a--plugin-direntry that did not load - Fixed
getSessionMessages()returning, andforkSession()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/informationalmessages; it previously dropped them - Changed the
set_max_thinking_tokenscontrol request: omittingmax_thinking_tokensnow leaves the session's thinking budget unchanged; sendnullto reset it to the session default - Updated to parity with Claude Code v2.1.283
- Added support for
strictKnownMarketplacesandblockedMarketplacesin host-suppliedmanagedSettings: 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()andSpareProcess.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_metakeys under the CLI-reservedcom.anthropic/prefix; they are now dropped, as for tool results - Updated to parity with Claude Code v2.1.282
- Added optional
trigger,user_message_uuidandtimestampfields to theconversation_resetmessage 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_changedstaying atrequires_actionafter an overlapping permission prompt and sandbox network-access prompt were both answered - Improved SDK package size and load time:
sdk.mjsno 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;initializemay 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
Settingstype'sattributionfield toboolean | {...}; TypeScript code that readsattribution.commitfrom returned settings needs a type narrow - Updated to parity with Claude Code v2.1.281
- Added optional
fireReasonto the task-notificationSDKMessageOrigin; a local host's declared scheduled-task fire is honored only in a process it started withCLAUDE_CODE_HOST_SCHEDULED_RUN=1 - Added
verbatimPromptsoption: prompts are delivered as written — no@pathexpansion, no slash-command dispatch and, on current CLIs, no ambient attachments with the prompt (Claude Code 2.1.248+) - Added
_metatomcpServerStatus()tool entries, carrying a tool's MCP Appsuimetadata so a host can find itsui://resource - Added
readMcpResource()(alpha) to read an MCP Appsui://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 emitsrate_limit_event(rejected,resetsAt) as it begins;api_retryheartbeats continue while sub-agent work waits - Changed
session_state_changedevents (CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS=1) to reportrequires_actionwhile 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
- Updated to parity with Claude Code v2.1.279
- Updated to parity with Claude Code v2.1.278
- Added an optional
builtinfield toSlashCommand, set when a command is built into Claude Code - Added
pasted_contenttoSDKUserMessage: 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 anupdateSettings()source, accepting onlyeffortLevel, which is saved for the session's current model as/effortsaves it - Fixed a resumed or forked session's
total_cost_usd,modelUsageandget_usagetotals starting at zero instead of continuing from the earlier turns (maxBudgetUsdis unchanged) - Changed
SDKUsageReportusage rows to always carryseverityandis_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
- Updated to parity with Claude Code v2.1.276
- Fixed a deferred tool call's result being emitted with internal keys such as
toolUseResultinstead oftool_use_resultwhen the tool re-runs at the start of a resumed turn - Fixed
getSessionMessages()andforkSession()sometimes missing a turn's assistant message when called right after the turn'sresultmessage - Fixed
forkSession({ upToMessageId })rejecting a client-suppliedSDKUserMessage.uuidthat is not in UUID format - Fixed
forkSessionrejecting the id thatgetSessionMessagesreturns 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
- Added
startup_failure_reasonto the error result a stream-json run writes before exiting on a known startup failure - Added
mcpServer: {name, source}tocanUseTooloptions,mcp_serverto tool hook inputs, andsourceto MCP server status rows, so hosts can key trust onsource === "sdk" - Added
CLAUDE_CODE_MCP_STARTUP_WAIT_MS(pass viaenv) to bound or disable (0) the first-turn wait for connecting MCP servers - Added
CLAUDE_CODE_EMIT_STARTUP_TIMING=1for stream-json hosts: the session's firstsystem/initthen carries the per-phasestartup_timingbreakdown 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.mcpServersservers are still awaited - Changed queued background-task completions to share one model call: each still gets its own
result, all but the last empty withnum_turns: 0 - Updated to parity with Claude Code v2.1.274
- Added a
usage_reportsibling (SDKUsageReport: session totals, the plan's usage rows as the server sends them, extra usage) on the assistant message that delivers a headless/usageresult - Added
reason: "worker_restart"totask_notificationmessages when a background task was stopped by a worker process restart - Added a one-line transcript notice when the SDK host's
StoporSessionStarthook callback times out, shown once until the host answers again - Fixed a
Stop,SubagentStoporSessionStarthook 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
- Updated to parity with Claude Code v2.1.272
- Added optional
omitClaudeMdtoAgentDefinitionin theagentsoption, so a subagent can run without user, project and local CLAUDE.md files; managed policy files still load - Fixed
listSessions,getSessionMessagesandgetSessionInfowithdiron Windows not finding sessions for a directory on a mapped network drive or SUBST drive - Fixed
sessionStoreresume losing the global config when it is stored under the legacy.config.jsonname or an OAuth-suffixed file name - Removed
persistentfrom theMonitorInputtool type - Updated to parity with Claude Code v2.1.271
- Updated to parity with Claude Code v2.1.270
- Changed
user_message_uuid,user_message_uuidsandresume_reasonto 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_denialsomitting 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_idontask_started/task_notificationwhen 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
canUseTooleven whenallowDangerouslySkipPermissionsis set; the flag now only enables switching tobypassPermissionslater - Updated to parity with Claude Code v2.1.269
- Added
result_indexto result messages: the result's position in delivery order within the run, from 0 - Added
local_commandto 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_impactto thereload_pluginscontrol request (Query.reloadPlugins({ holdOnCacheImpact: true })): holds a reload that would invalidate the session's prompt cache - Added
resume_reasonto 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 theget_context_usagecontrol response, matching the/contextresult'scontext_usagerows - Added optional
defaultToNoandsuppressAlwaysAllowRulehints tocanUseTooloptions: 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_uuidon the automatic re-run of an interrupted turn to name that turn's last user prompt - Changed the
initializesuccess response to always includepending_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
- Added
getCcrEvent(query, message)andgetSseLastSequenceNum(query)to the browser SDK's SSE transport, plusfromSequenceNum,onCatchUpTruncatedandonDeliveryUpdateSSE options - Changed
systemPromptrecording to default on for custom prompts and appends (a mid-session prompt change takes effect at the next compaction); passsnapshot: falseto keep per-request rendering - Updated to parity with Claude Code v2.1.267
- Updated to parity with Claude Code v2.1.266
- Added
user_message_uuidanduser_message_uuidsto a synthetic turn's first reply and result for a message sent withisSynthetic: trueand auuid, naming the message that started it - Added
user_message_uuidanduser_message_uuidsto 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_uuidmissing 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
cwdoption at each new user message; acdmade by the agent now persists across turns, as in the interactive app - Changed
user_message_uuidto 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
- Updated to parity with Claude Code v2.1.264
- Updated to parity with Claude Code v2.1.263
- Updated to parity with Claude Code v2.1.262
- Added
pluginDelivery: 'initialize'to sendpluginsover 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 nativeSymbol.dispose, such as Node ≤22vmcontexts (Jest'snodeenvironment, vitestvmThreads/vmForks) and Node <18.18 - Updated to parity with Claude Code v2.1.261
- Added optional
user_message_uuidtothinking_tokenssystem 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_msandfirst_stream_post_wall_msfields to the success result message for remote-session latency breakdowns - Fixed
managedSettingsdisableAutoMode: "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_retriesresults to append the last StructuredOutput tool error; validation errors now name the offending key, allowed values, and actual length or count - Changed
rate_limit_eventto 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
- Added
user_message_uuidsbesideuser_message_uuidon 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
- Updated to parity with Claude Code v2.1.258
- Added
thinkingTokenstoModelUsage(a subset ofoutputTokens), and fixed result-messageusage.output_tokens_details.thinking_tokensreporting 0 instead of the session's real count - Added
tool_use_result.resourceLinkson user messages carrying MCP tool results: theresource_linkblocks the tool returned, so hosts can render returned files without parsing the result text - Added optional
resource_linkstotask_notificationfor an auto-backgrounded MCP tool call that completed, listing the files it returned by reference; join to the call viatool_use_id - Fixed
mcp_reconnectandmcp_toggleacting on a same-named.mcp.json/~/.claude.jsonserver instead of the--mcp-configormcp_set_serversone - Fixed
mcp_toggledisable also removing the tools of a sibling MCP server whose name extends the disabled one's (disablingfoodroppedfoo__bar's tools) - Changed
mcp_set_serversto also list a server whose connection attempt throws underadded(with afailedrow inmcp_status), not only undererrors - Changed Agent tool calls to emit the periodic
tool_progressheartbeat (heartbeat: true) like other long tools; heartbeat frames never clear asubagent_retryindicator - Fixed the browser SDK bundle (
@anthropic-ai/claude-agent-sdk/browser) never streaming any messages on engines without nativeSymbol.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
-pgiving up on a long-running background subagent without actually stopping it, sobackground_tasks_changedkept listing it and events for it arrived after itsstoppednotification - Added
detailoption toQuery.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
- Updated to parity with Claude Code v2.1.256
- Updated to parity with Claude Code v2.1.255
- Updated to parity with Claude Code v2.1.254
- Updated to parity with Claude Code v2.1.253
- Updated to parity with Claude Code v2.1.252
- Updated to parity with Claude Code v2.1.251
- Updated to parity with Claude Code v2.1.250
- Updated to parity with Claude Code v2.1.249
- Added a per-server
timeoutfor SDK-hosted MCP servers (createSdkMcpServer({ timeout })), overridingMCP_TOOL_TIMEOUTfor that server's tool calls
- Added an optional
ambientflag totask_started,task_notificationandbackground_tasks_changedtask entries so hosts can exclude housekeeping tasks from activity indicators - Fixed the
permissionModeon per-turnsystem/initframes reporting the mode at turn start instead of the live mode, so a mode switch right after submitting no longer sends a stale value
- Added optional
user_message_uuidto error result messages and to the first assistant message orstream_eventof 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'scostUSDwas computed from - Added
modelPricingsupport in themanagedSettingsoption for hosts that setCLAUDE_CODE_PROVIDER_MANAGED_BY_HOST; an admin-managed settings source that setsmodelPricingstill wins - Added
perTaskStopAffordanceoption: when set,interrupt()aborts only the current turn and keeps background agents and workflows running; otherwise (and for one-shot string prompts) they stop
- Updated to parity with Claude Code v2.1.245
- Updated to parity with Claude Code v2.1.244
- Added optional
queued_turn_countto 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_statusreporting a remote MCP server as connected after its connection dropped; it now reports pending while reconnecting, then connected or failed - Fixed managed
disableAllHooksalso disabling hook callbacks registered through thehooksoption; they now keep running, matchingallowManagedHooksOnly - Changed Read tool PDF results: the
documentblock (or pageimageblocks forpagesreads) now arrives inside thetool_resultcontent instead of as a separateusermessage after it - Updated to parity with Claude Code v2.1.243
- Updated to parity with Claude Code v2.1.242
- Updated to parity with Claude Code v2.1.241
- Updated to parity with Claude Code v2.1.240
total_cost_usd/modelUsage.costUSDnow include the 1.1× US-only-inference (data residency) multiplier when the response reportsinference_geo: "us"- A result held back for background subagents in one-shot mode now reports
total_cost_usd,duration_api_msandmodelUsageas of its release, not the turn-end snapshot - Fixed
SYSTEM_PROMPT_DYNAMIC_BOUNDARYin an arraysystemPromptbeing sent to the model as literal text on Bedrock, Vertex, Foundry, and gateway providers - A repeated
initializeon a running process is now followed by abackground_tasks_changedsnapshot of the live background tasks, so reconnecting hosts see work that is still running
- Added
is_backgroundedandspawn_depthtotask_startedevents for subagent tasks (is_backgroundedalso on background Bash tasks) - Added
suppressOriginalPrompttoUserPromptExpansionhook output, matchingUserPromptSubmit - Added
command_lifecyclestaterefused: 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
initializeto an already-running CLI; the response now reportshooks_applied - Fixed
CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION=truenot keepingprompt_suggestionmessages on when the account is near, but not over, its usage limit - Changed
vcs_state_changedpush events to emit one event per pushed branch
- Updated to parity with Claude Code v2.1.237
PostToolUsehooks can returnhookSpecificOutput.classifierContext, a short host-asserted note about a tool call's result that the auto mode permission classifier reads alongside that result
- Updated to parity with Claude Code v2.1.235
- Removed unused
bypass_permissions_disabledfromExitReasontype; the value was never emitted — TypeScript consumers with an explicitcasebranch get a compile error on upgrade (runtime unaffected) - Updated the
ApiKeySourcetype to include the valuessystem/initactually reports (ANTHROPIC_API_KEY,apiKeyHelper,/login managed key,none) vcs_state_changedevents report the directory the shell finished in (an innercdis reflected)- A peer
origininjected 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 optionaleffortfield: the session's applied effort level, ornullwhen none is sent. Set on Remote Control bridge init frames
- 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 thetoolsoption or reference them inallowedTools(or setCLAUDE_CODE_ENABLE_TODO_TOOLS=1) to keep them
- Subagent MCP
tool_resultframes whose result carries_metanow emittool_use_resultas{ content, _meta }(matching main-loop frames) instead of a bare value /contextresult messages now carry a structuredcontext_usagepayload (newSDKContextUsagetype), so consumers can render the context-usage card without parsing the markdown tablevcs_state_changedevents now populate thebranchfield for push operations, sourced from the pushed ref
- Updated to parity with Claude Code v2.1.231
- Updated to parity with Claude Code v2.1.230
- Added
terminal_slash_commandsto 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";StopFailureerror_detailsis"request_body_over_limit: …"
- Agent tool results (
AgentOutput):usage.output_tokens_detailsis now carried through
- Updated to parity with Claude Code v2.1.227
- Updated to parity with Claude Code v2.1.226
- Fixed background subagents in headless/SDK sessions never resuming when a background shell command or Monitor they left running completed, so the subagent never saw the result
- Added
crossSessionInboundanddialogExpirysettings: 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 thetask-notificationmember ofSDKMessageOrigin, marking a notification raised by a cross-sessionSendMessage - Added
source: 'archive'plugin config variant toSettings, withurland optionalsha256, for installing plugins from a zip over HTTPS - Added sandbox credential-masking fields to
Settings:decode: 'jwt'withmaskClaims,extract/onExtractNoMatchonenvVars, andawsPairs/sigv4for 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
/resumeno longer cross projects
- Added
resumeDropsTurnoption: withresumeSessionAt, 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/ SDKquery()withoutcanUseTool) now emitssystem/permission_deniedstream events when a tool call is auto-denied - Documented
usagevsmodelUsageon stream-json results:usageis main-loop-only and per-turn;modelUsageis cumulative, covers all query-pipeline calls, and is the field for cost accounting
- Fixed
query({ sessionStore, resume })not carrying usersettings.json(apiKeyHelper,env,hooks,permissions) into the resumed subprocess
- Improved
skillsoption validation: malformed names (delimiters or control characters) and wildcard-form names are rejected with a clear error; useskills: 'all'to enable every skill - Fixed external MCP servers passed via the
mcpServersoption not being connected before the first turn, which caused the model to emit tool calls as literal text
- Updated to parity with Claude Code v2.1.220
- Added opt-in
cancel_queuedto the interrupt control request (capabilityinterrupt_cancel_queued_v1): cancels queued and pending-dispatch messages alongside the abort - Added
fast_mode_disabled_reasonto result and init messages so SDK hosts can explain why fast mode is off - Added
DirectoryAddedlifecycle hook event to the control protocol, fired when a new working directory is registered mid-session - Fixed the initialize response reporting
fast_mode_statefrom the spawn-time model after a model switch - Added
sandbox.network.strictAllowlistto SDK settings types for deterministically denying non-allowlisted hosts in sandboxed commands - Added
workflowSizeGuidelineto SDK settings types for setting the advisory dynamic-workflow size guideline
SkillToolOutputnow reportsbackground: truewhen a forked skill was dispatched as a detached background agent- Fixed the result event's
api_error_statusreporting null for rate-limit and overloaded errors delivered mid-stream; it now reports 429/529 - Added
canonicalModelandproviderto eachmodelUsageentry in result messages so downstream billing can look up the correct rate table forcostUSD
- Changed subagents to no longer spawn nested subagents by default (depth cap lowered from 5 to 1); set
CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTHto allow deeper nesting - Added a cap on concurrently-running subagents (default 20, override with
CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS) - Fixed Remote Control sessions not re-sending pending permission prompts to clients that connect after the prompt appeared
- Added optional
skippedLinkscount torewindFilesresponses for paths the rewind safety guards refused to restore or delete - Added
tool_result_metasidecar to user messages (non_execution_kind,user_feedback) so consumers can classify denied, interrupted, or cancelled tool calls without string-matching result prose - Added optional
user_message_uuidandrequest_sent_wall_msfields to the success result message for cross-host request-latency correlation
- Updated to parity with Claude Code v2.1.215
set_permission_modenow rejects unrecognized permission modes with an error instead of silently adopting them; the'manual'alias is accepted at every ingress- Added optional
subkind: 'scheduled-trigger'to thetask-notificationmember ofSDKMessageOrigin, marking deliveries that are the fired prompt of a user-configured scheduled task applyFlagSettings({effortLevel})now accepts'max'in its TypeScript type (runtime already supported it)- Assistant messages truncated by
interrupt()now carryaborted: true, so consumers can distinguish a mid-stream partial from a completed message - Added optional
subagent_typeandsubagent_retryfields totool_progressmessages so clients can show a subagent waiting out an API rate-limit retry - The
system/initmessage'spluginsentries and thereload_pluginsresponse now include each plugin's manifestversion - SessionStart hooks now report source
"fork"instead of"resume"when the session begins as a fork
- Updated to parity with Claude Code v2.1.213
- Fixed dash-leading
resumeSessionAtandsessionIdvalues being passed to the CLI as separate argv tokens; both now use equals-form (--flag=value) - Agent tool output now includes the resolved model when a mid-turn model swap changed the subagent's model
- Fixed
--replay-user-messageswith--include-partial-messagesemitting the turn-start user replay after the first content block instead of before the turn's content events - Added
SDKAssistantMessage.timestamp(ISO-8601) to the live stream, matchingSDKUserMessage; older emitters omit it, consumers should fall back to receive time - Added rate-limit message prefix buckets (
USAGE_LIMIT_ERROR_PREFIXESand siblings) as@alphaexports for classifying rate-limit messages without hand-mirrored lists - Improved process-exit errors to include the CLI's stderr output, so a failed child reports its actual cause instead of only an exit code
- Added
timedOutAfterMstoBashToolOutput, set when a command is auto-backgrounded on timeout
- Updated to parity with Claude Code v2.1.209
- Fixed a caller abort during a pending SDK hook callback being converted into hook success, which let PreToolUse-gated tools execute after the abort
- Fixed a per-query resource leak in the SDK's process tracking when spawning the CLI fails (nonexistent or inaccessible executable path)
- Fixed an SDK
UserPromptSubmithook callback exceeding its timeout killing the entire query with an empty error; it now blocks the prompt with a clear timeout message and the session continues - Fixed
extraArgsvalues that look like flags (e.g.resume: '--version') being parsed as their own CLI flags; dash-leading values are now bound with equals-form argv - Fixed an abort-listener leak: streaming queries sharing one
AbortControllerno longer accumulateabortlisteners on its signal after each completed query - Fixed
createSdkMcpServerdocs pointing at a nonexistent env var; the MCP tool-call timeout knob isMCP_TOOL_TIMEOUT - Fixed an uncaught exception when writing to stdin after the Claude Code subprocess has exited
- Fixed
canUseToolreturning{behavior: 'allow'}withoutupdatedInputbeing rejected as a deny with a raw ZodError message; the tool now runs with the original input per the documented contract - The Agent tool's structured result now has a published SDK type (
AgentToolCompletedOutput) that matches the emitted object exactly
- Added
command_lifecycleframes to stream-json and SDK sessions, reporting each uuid-stamped message's terminal state (queued/started/completed/cancelled/discarded); zero-API results no longer report staleduration_api_ms
- Interrupt control responses now include
still_queued(UUIDs of queued async messages that will still run),Query.interrupt()returns the typed receipt, andsystem/initadvertises aninterrupt_receipt_v1capability for feature detection - Added structured
nameandbodyfields to peer-message session events, exposing the sender display name and decoded message body
- Added
terminal_reasonvaluestool_deferred_unavailable(deferred tool resume found the tool gone — previously anis_errorresult with no reason, read as a clean completion by lifecycle sweeps) andturn_setup_failed(the turn-input builder threw before the turn started). Both classify as dead turns, so commands consumed by them reportcommand_lifecyclestatecancelled - Fixed the post-merge cancel backstop cancelling every member of a coalesced prompt batch when a cancel named only one: uncancelled siblings now re-merge and run (previously they were reported
cancelled— on remote transports that acknowledged them as processed, silently dropping messages nobody cancelled) - Added
terminal_reasonvaluesapi_error,malformed_tool_use_exhausted,budget_exhausted, andstructured_output_retry_exhausted. Turns that die on an exhausted-API-retry or malformed-tool-use give-up previously reportedcompleted; budget and structured-output exhaustion results previously omittedterminal_reason. Commands consumed by such turns now reportcommand_lifecyclestatecancelledinstead ofcompleted(dup-over-loss) - Updated to parity with Claude Code v2.1.204
- Added a
background_tasks_changedsystem message with the full set of live background tasks on every membership change, so consumers can track background activity as a level instead of pairingtask_started/task_notificationedges - Fixed stable releases shipping a
sdk.d.tswith unresolved type references that broke consumer typechecking withskipLibCheckdisabled
- Added
parent_agent_idfield to subagent session messages for building depth-2+ agent trees from disk-persisted metadata - Fixed
apply_flag_settingswith a non-object settings value crashing the session instead of returning a control error
- Updated to parity with Claude Code v2.1.201
- Added
'manual'as an accepted alias for the'default'permission mode in SDK inputs - Fixed
onSetPermissionModecallback not firing for SDK-hosted Remote Control sessions - Fixed
set_modelcontrol request accepting unrecognized model strings; invalid models are now rejected before latching
- Added
requestIdtocanUseToolcallback options for correlating out-of-band permission responses, and support for returningnullto suppress the SDK's automatic control response - Added
blockedfield toworkflow_agentprogress events indicating when an agent was blocked by the auto-mode safety classifier - Added
mode:"mask"and per-credentialinjectHoststosandbox.credentialssettings types for injecting masked credentials into sandboxed commands
- Added a runtime warning when
canUseToolis configured alongsideallowedToolsorbypassPermissions, which shadow the callback - Added per-server
request_timeout_msoption tomcp_set_serverscontrol request - Fixed
SDKUserMessage.isSyntheticnot being mapped toisMetaon ingestion, which could cause synthetic messages to be treated as real user messages - Fixed workflow progress events silently dropping earliest agents from the list while the phase counter remained correct
- Updated to parity with Claude Code v2.1.197
- Added
prompt_idfield to hook input payloads for correlating hook events with OpenTelemetry prompt-level events - Fixed control protocol deduplication dropping tool-use IDs after 1000 resolutions, which could cause duplicate
tool_resultdeliveries in long-running sessions
- Added
Query.reinitialize()to re-send the initialize control request and redeliver pending permission/dialog prompts after a transport gap - Fixed
commands_changedevent not being emitted for synced skills when the skill list resolves before the change-detector subscribes
- Updated to parity with Claude Code v2.1.194
- Added
promptSuggestionsoption to Browser SDKquery()to opt the remote CLI into emitting follow-up suggestions - Fixed brief console window flashes on Windows when spawning CLI subprocesses
- Updated to parity with Claude Code v2.1.192
- Added
old_sourcefield toNotebookEdittool results forreplaceanddeleteoperations, enabling inline diffs - Added
seven_day_overage_includedtoSDKRateLimitInfo.rateLimitTypefor per-model weekly usage limits - Added
model_scopedarray to usage response for per-model weekly limit windows with utilization and reset times - Fixed fast mode reverting to standard after the first turn when
settingSourcesincludes user/project settings
- Updated to parity with Claude Code v2.1.190
- Updated to parity with Claude Code v2.1.188
- Added
sandbox.credentialsto SDK settings types for configuring credential file and environment variable denial in sandboxed commands
- Added
agent_idfield tocan_use_toolcontrol requests — background agents now forward permission prompts tocanUseToolinstead of auto-denying, and stdin stays open while background tasks are running - Added
ReadMcpResourceDirTooltool type to SDK schemas — MCP resource directory listing is now a dedicated tool instead of a fallback insideReadMcpResourceTool - Added
rewind_conversationcontrol request for rewinding a conversation to a previous point with durable resume anchor support
- Updated to parity with Claude Code v2.1.185
- Updated to parity with Claude Code v2.1.184
- Updated to parity with Claude Code v2.1.183
- Updated to parity with Claude Code v2.1.182
- Added
errorCode,canUserPurchaseCredits, andhasChargeableSavedPaymentMethodfields toSDKRateLimitInfofor detecting credits-required rate limits - Added
tool_use_meta.icon_urlto assistant messages, populated from MCP server directory metadata - Fixed SDK-hosted Remote Control sessions dropping
file_attachmentsfrom inbound user messages
- Updated to parity with Claude Code v2.1.180
- Added optional
tool_use_metasidecar to assistant messages with display-friendly names for tool calls, so SDK consumers can render human-readable labels instead of raw wire names - Fixed
-pmode exiting before a completed background agent's notification was delivered, causing interim text to ship as the final result - Fixed remote (stream-json) sessions appearing busy for the entire duration of a background workflow — the turn result is now emitted at the turn boundary and the session reports idle while background tasks continue
- Spawn failures on an existing native binary now explain the likely libc mismatch (musl binary on a glibc host) and suggest
options.pathToClaudeCodeExecutable - Permission-denied advisory messages now carry typed denial reasons (
safetyCheck,asyncAgent), enabling SDK consumers to programmatically match denial causes - Fixed
UserPromptSubmithook block feedback not being emitted to the SDK event stream — consumers can now see why a prompt was blocked by a hook instead of a silent hang - Remote Control workers now send a
worker_shutting_downsystem message on graceful exit so remote clients can show why the session ended - Fixed MCP server-level specs (
mcp__server,mcp__server__*) indisallowedToolsbeing silently ignored — they now correctly remove all tools from the named server
- Updated to parity with Claude Code v2.1.177
- Fixed turn
resultmessages being dropped when multiple turns complete while a background agent or workflow is running - Fixed background agent, remote agent, and MCP task state not being restored when resuming a session via the SDK
- Updated to parity with Claude Code v2.1.175
- SDK consumers now receive the
system/model_fallbackmessage for all fallback triggers —overloaded,server_error, andlast_resortin addition tomodel_not_foundandpermission_denied— and the message'striggerfield gained theserver_errorandlast_resortvalues
- Updated to parity with Claude Code v2.1.173
- SDK
pluginsoption now acceptsskipMcpDiscovery: trueper plugin, so a host that manages a plugin's MCP connections itself can load skills/hooks from the plugin path without the engine re-reading its.mcp.json - Fixed slash-followed-by-whitespace input (e.g.
/ add tests) being silently dropped instead of treated as a plain prompt
- Updated to parity with Claude Code v2.1.171
- Added claude-fable-5 model and the fable alias to SDK model types. https://www.anthropic.com/news/claude-fable-5-mythos-5
- Updated to parity with Claude Code v2.1.170
- Added an experimental
usage_EXPERIMENTAL_MAY_CHANGE_DO_NOT_RELY_ON_THIS_API_YET()method onQueryreturning structured session cost, plan rate-limit, and local usage-behaviors data - Added an
sseoption (SSEOptions) toBrowserQueryOptionsas an alternative towebsocket, for browser SDK consumers who prefer Server-Sent Events
- Updated to parity with Claude Code v2.1.168
- Updated to parity with Claude Code v2.1.167
- Fixed MCP resource tools not being injected for servers added at runtime via the
mcp_set_serverscontrol request
- Updated to parity with Claude Code v2.1.165
- Updated to parity with Claude Code v2.1.164
stop_taskcontrol requests now return success when the target task is already gone (not_foundornot_running), so SDK clients can reliably prune stale task chips- Fixed SDK hosts being unable to add builtin MCP servers (e.g.
claude-in-chrome) viasetMcpServerswhen the CLI was launched without them - Stop and SubagentStop hook events now support
additionalContextinhookSpecificOutput, enabling non-error feedback that continues the turn
- Refusal error messages now carry
stop_reason: "refusal"andstop_detailson the assistant message and in session transcripts, so SDK consumers can detect refusals without text-matching the error content - Agent SDK sessions on native builds now default to fast embedded
find/grepsearch in Bash, matching the interactive CLI, instead of always registering the dedicated Grep/Glob tools. To keep the dedicated tools (e.g. to intercept searches viacanUseToolor hooks), name them in thetoolsoption or reference them inallowedTools
- The
initializecontrol request is now idempotent: a secondinitializereturns the same success payload instead of anAlready initializederror.ControlResponsegains an optionalpending_permission_requestsfield, mirroringControlErrorResponse applyFlagSettingsnow live-appliesagentchanges: switching the active agent (or passingnullto reset) takes effect on the next turn in a running session
- Fixed SDK hook callbacks swallowing abort signals: aborting during a PostToolUse hook now ends the turn with a final
resultmessage instead of hanging the calling process
- Updated to parity with Claude Code v2.1.159
- Updated to parity with Claude Code v2.1.158
- Updated to parity with Claude Code v2.1.157
- Updated to parity with Claude Code v2.1.156
- Updated to parity with Claude Code v2.1.155
- Fixed stdio MCP servers being incorrectly restarted on every reconcile pass due to config-equality false positives
- Updated to parity with Claude Code v2.1.153
SessionStarthooks can now returnreloadSkills: trueto trigger a skill re-scan, and set the session title viahookSpecificOutput.sessionTitle- Added a
MessageDisplayhook event that lets hooks transform or hide assistant message text as it is displayed
- Updated to parity with Claude Code v2.1.151
- The
api_retrysystem message now reportserror: 'overloaded'for 529 responses, instead of'rate_limit'(which is now reserved for 429). Consumers that handled 529 viaerror === 'rate_limit'should also match'overloaded', or switch toerror_status === 529. - Updated to parity with Claude Code v2.1.150
- Fixed
options.envdroppingCLAUDE_AGENT_SDK_VERSION(used forUser-Agentand telemetry) when a custom environment is supplied, and corrected theOptions.envdocs to state that the value replaces the subprocess environment rather than merging withprocess.env
- Updated to parity with Claude Code v2.1.148
- Updated to parity with Claude Code v2.1.147
- Updated to parity with Claude Code v2.1.146
- Updated to parity with Claude Code v2.1.145
- Assistant messages and
StopFailurehooks now reporterror: 'model_not_found'when the selected model doesn't exist or isn't available, instead of the generic'invalid_request'. Theapi_error_statusfield on result messages is now documented. - Added
@anthropic-ai/claude-agent-sdk/extractexport forbun build --compileconsumers: import the platform native binary withwith { type: 'file' }, callextractFromBunfs(binPath)to copy it out of the compiled executable's virtual filesystem, and pass the result tooptions.pathToClaudeCodeExecutable
@anthropic-ai/sdkand@modelcontextprotocol/sdkare nowpeerDependenciesinstead ofdependencies. Runtime is unaffected (both are bundled); npm/bun/pnpm auto-install them. yarn classic users should add them explicitly for full TypeScript type resolution
- Breaking: Removed the v2 session API (
unstable_v2_createSession,unstable_v2_resumeSession,unstable_v2_prompt,SDKSession,SDKSessionOptions), deprecated since 0.2.133. Usequery()— pass anAsyncIterable<SDKUserMessage>for multi-turn, oroptions.resumeto continue a session. - Breaking: MCP servers now connect in the background by default; sessions start immediately and slow servers report
status: "pending"ininituntil ready. SetMCP_CONNECTION_NONBLOCKING=0to restore the old behavior of waiting up to 5s before the first query, or mark a serveralwaysLoad: trueto require it in turn 1. - Breaking: Headless and SDK sessions now use Task tools (
TaskCreate/TaskUpdate/TaskGet/TaskList) instead ofTodoWrite, deprecated since 0.2.136. Tool consumers should accumulate by task ID instead of replacing a snapshot list. - Surfaced
request_id,subagent_type, andtask_descriptionon SDK message types and task system events - Headless
--sdk-urlsessions now exit non-zero with a stderr diagnostic when the remote transport closes permanently (401/403/404 or WS permanent close), instead of silently exiting 0
TaskCreateInput,TaskCreateOutput,TaskGetInput,TaskGetOutput,TaskUpdateInput,TaskUpdateOutput,TaskListInput, andTaskListOutputtypes are now exported from@anthropic-ai/claude-agent-sdk/sdk-toolsand included in theToolInputSchemas/ToolOutputSchemasunions- Aligned
@anthropic-ai/sdkdependency to ^0.93.0
- Updated to parity with Claude Code v2.1.140
- Updated to parity with Claude Code v2.1.139
- Updated to parity with Claude Code v2.1.138
- Updated to parity with Claude Code v2.1.137
- Added
resolveSettings()(alpha) to inspect effective merged settings without spawning the Claude CLI; reads MDM (plist/HKLM/HKCU) for parity with CLI startup - Deprecated
TodoWritetool — future versions will switch to Task tools (TaskCreate,TaskGet,TaskUpdate,TaskList)
- Updated to parity with Claude Code v2.1.135
- Updated to parity with Claude Code v2.1.134
- Deprecated the unstable V2 session API (
unstable_v2_createSession/unstable_v2_resumeSession/unstable_v2_prompt) — usequery()instead - Deprecated passing
'Skill'inallowedTools— use theskillsoption instead - Updated to parity with Claude Code v2.1.133
- Documented
applyFlagSettings()in the TypeScript Agent SDK reference and added support fornullon top-level keys to clear flag-settings overrides - Updated to parity with Claude Code v2.1.132
- Updated to parity with Claude Code v2.1.131
- Updated to parity with Claude Code v2.1.130
- Updated to parity with Claude Code v2.1.129
- Updated to parity with Claude Code v2.1.128
- Updated to parity with Claude Code v2.1.127
- Added
originto result messages (SDKResultSuccess/SDKResultError) — forwards the triggering message'sSDKMessageOriginso consumers can distinguish user-prompted results fromtask-notificationfollowups
- Updated to parity with Claude Code v2.1.125
- Updated to parity with Claude Code v2.1.124
- Updated to parity with Claude Code v2.1.123
- Updated to parity with Claude Code v2.1.122
- Added
updatedToolOutputtoPostToolUseHookSpecificOutputfor replacing tool output on all tools.updatedMCPToolOutputis deprecated.
- Added
skillsoption (string[] | 'all') to control which Skills are loaded into the main session, matching the Python SDK
- Added
forwardSubagentTextoption to stream subagent text deltas to SDK consumers excludeDynamicSectionsnow keeps static auto-memory instructions in the cacheable system-prompt block; only the per-user memory directory path and per-machine environment values are relocated to the first user message- Long-running SDK sessions now reconnect claude.ai-proxied MCP servers after a transport-stream abort
SessionStore.append()failures are now retried up to 3 times with short backoff before the batch is dropped andmirror_erroris emitted
- Added
Options.managedSettingsfor embedders to pass policy-tier settings to the spawned CLI in-memory, honored below IT-controlled managed sources
- Updated to parity with Claude Code v2.1.117
- Updated to parity with Claude Code v2.1.116
- Updated to parity with Claude Code v2.1.115
- Updated to parity with Claude Code v2.1.114
- Changed the SDK to spawn a native Claude Code binary (via a per-platform optional dependency) instead of bundled JavaScript
- Added
sessionStoreoption (alpha) toquery()and session helpers for mirroring session transcripts to external storage, withSessionStore/SessionKey/SessionStoreEntrytypes,InMemorySessionStorereference implementation, andimportSessionToStore()for migrating existing sessions - Added
deleteSession()for removing a session from disk or aSessionStore - Added
SDKMirrorErrorMessage(subtype: 'mirror_error') to theSDKMessageunion — emitted when asessionStore.append()batch fails - Breaking:
options.envonce again replacesprocess.envfor the CLI subprocess instead of overlaying it. To add or override individual variables, passenv: { ...process.env, MY_VAR: "x" } - Added
titleoption toquery()— sets the session title and skips auto-generation - Added OpenTelemetry trace context propagation — the caller's active trace context is forwarded to the CLI subprocess so spans parent under your distributed trace
- Updated to parity with Claude Code v2.1.112
- Opus 4.7 is now available! This version of the SDK is required to use it.
mcp_set_serverscontrol request: remote (http/sse) server entries can now carry per-toolpermission_policyvalues, which are applied to the session's allow/deny rulesstartup()andWarmQueryare now part of the public TypeScript API- Changed
options.envto overlay the inheritedprocess.envinstead of replacing it
- Fixed
unstable_v2_createSessionnot respectingcwd,settingSources, andallowDangerouslySkipPermissionsoptions - Added optional
shouldQueryfield toSDKUserMessage— set tofalseto append a user message without triggering an assistant turn; fixedshouldQuery: falsemessages incorrectly triggering auto-title generation, prompt suggestions, andUserPromptSubmithooks - Auto session-title generation now respects
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFICandCLAUDE_CODE_DISABLE_TERMINAL_TITLE
- Updated to parity with Claude Code v2.1.109
SDKStatusnow includes'requesting'; whenincludePartialMessagesis enabled, a{type:'system', subtype:'status', status:'requesting'}message is emitted before each API request in the stream
- Updated to parity with Claude Code v2.1.107
- Updated to parity with Claude Code v2.1.106
- Added
system/memory_recallevent andmemory_pathsonsystem/initfor SDK renderers to surface memory operations - Fixed
error_max_structured_output_retriesbeing emitted when the final retry attempt succeeded, discarding valid structured output
- Updated to parity with Claude Code v2.1.102
- Security: bumped
@anthropic-ai/sdkto^0.81.0and@modelcontextprotocol/sdkto^1.29.0to resolve GHSA-5474-4w2j-mq4c and transitive hono advisories - Fixed resume-session temp directory leaking on Windows when subprocess file handles weren't released before cleanup, and on macOS/APFS when
await usingdisposal raced its own cleanup callback - Fixed
MaxListenersExceededWarningwhen running 11+ concurrentquery()calls
- Updated to parity with Claude Code v2.1.100
- Updated to parity with Claude Code v2.1.99
- Updated to parity with Claude Code v2.1.98
- Updated to parity with Claude Code v2.1.97
- Updated to parity with Claude Code v2.1.96
- Updated to parity with Claude Code v2.1.95
- Fixed
getContextUsage()to include agents passed viaoptions.agentsin theagentsbreakdown - Fixed CJK and other multibyte text being corrupted with U+FFFD in stream-json input/output when chunk boundaries split a UTF-8 sequence
- Fixed MCP server child processes not being cleaned up when an SDK
query()session ends - Fixed a failed error-report write crashing the SDK process with
unhandledRejection - Updated to parity with Claude Code v2.1.94
- Updated to parity with Claude Code v2.1.93
- Updated to parity with Claude Code v2.1.92
- Added optional
terminal_reasonfield to result messages, exposing why the query loop terminated (completed,aborted_tools,max_turns,blocking_limit, etc.) - Added
'auto'to the publicPermissionModetype - Changed
sandboxoption to defaultfailIfUnavailabletotruewhenenabled: trueis passed —query()will emit an error result and exit if sandbox dependencies are missing, instead of silently running unsandboxed. SetfailIfUnavailable: falseto allow graceful degradation. - Updated to parity with Claude Code v2.1.91
- Updated to parity with Claude Code v2.1.90
- Added
startup()to pre-warm the CLI subprocess beforequery(), making the first query ~20x faster when startup cost can be paid upfront - Added
includeSystemMessagesoption togetSessionMessages()to optionally include system messages in session history - Added
listSubagents()andgetSubagentMessages()functions to retrieve subagent conversation history from sessions - Added
includeHookEventsoption to enable hook lifecycle messages (hook_started,hook_progress,hook_response) for all hook event types - Fixed
ERR_STREAM_WRITE_AFTER_ENDerrors when single-turn queries with SDK MCP servers or hooks have control responses arriving after the result message - Fixed Zod v4 field
.describe()metadata being dropped fromcreateSdkMcpServertool schemas - Fixed
side_questionreturning null on resume before the first turn completes - Fixed
settingSourcesempty array causing--setting-sources ""to consume the next CLI flag - Fixed error result messages (
error_during_execution,error_max_turns,error_max_budget_usd) to correctly setis_error: truewith descriptive messages - Fixed MCP servers getting permanently stuck in a failed state after a connection race — they now retry on the next message
- Updated to parity with Claude Code v2.1.87
- Added
getContextUsage()control method to retrieve a breakdown of context window usage by category - Made
session_idoptional inSDKUserMessagetype — callers no longer need to provide a session ID when sending user messages, as the SDK assigns one automatically - Fixed TypeScript types resolving to
anyby adding@anthropic-ai/sdkand@modelcontextprotocol/sdkas dependencies - Updated to parity with Claude Code v2.1.86
- Added
reloadPlugins()SDK method to reload plugins and receive refreshed commands, agents, and MCP server status - Fixed PreToolUse hooks with
permissionDecision: "ask"being ignored in SDK mode - Updated to parity with Claude Code v2.1.85
- Added
taskBudgetoption for API-side token budget awareness, allowing the model to pace tool use within a token limit - Added
enableChannel()method andcapabilitiesfield onMcpServerStatusfor SDK-driven MCP channel activation - Exported
EffortLeveltype ('low' | 'medium' | 'high' | 'max') for consumers to reference effort values directly - Fixed showing "[Request interrupted by user]" for errors that were not caused by user interruption
- Updated to parity with Claude Code v2.1.84
- Added
seed_read_statecontrol subtype to seedreadFileStatewith{path, mtime}soEditworks after the originatingReadwas removed from context - Changed
session_state_changedevents to opt-in: setCLAUDE_CODE_EMIT_SESSION_STATE_EVENTS=1to receive them - Updated to parity with Claude Code v2.1.83
- Updated to parity with Claude Code v2.1.82
- Fixed
canUseToolnot providing a workingaddRulessuggestion when a write under.claude/skills/{name}/hits the bypass-immune safety check - Updated to parity with Claude Code v2.1.81
- Fixed
getSessionMessages()dropping parallel tool results — sessions with parallel tool calls now return all tool_use/tool_result pairs - Updated to parity with Claude Code v2.1.80
- Added
'resume'to theExitReasontype for distinguishing resume-triggered session ends in hooks - Updated to parity with Claude Code v2.1.79
- Updated to parity with Claude Code v2.1.78
- Added
api_retrysystem messages when retrying transient API errors, exposing attempt count, max retries, delay, and error status - Updated to parity with Claude Code v2.1.77
- Added
forkSession(sessionId, opts?)for branching conversations from a point - Added
cancel_async_messagecontrol subtype to drop a queued user message by UUID before execution - Added
planFilePathfield toExitPlanModetool input for hooks and SDK consumers - Added MCP elicitation hook types and
SDKElicitationCompleteMessagesystem message for handling MCP server input requests programmatically - Updated to parity with Claude Code v2.1.76
- Added
tagandcreatedAtfields toSDKSessionInfo - Added
getSessionInfo(sessionId, opts?)for single-session metadata lookup - Added
offsetoption tolistSessionsfor pagination - Added
tagSession(sessionId, tag, opts?)for tagging session files - Added
queued_to_runningstatus toAgentToolOutput— returned whenAgent({resume})targets a still-running agent - Improved error messages when the Claude Code subprocess returns an error result — the SDK now surfaces the actual error text instead of a generic "process exited with code 1"
- Updated to parity with Claude Code v2.1.75
- Added
renameSession(sessionId, title, opts?)for renaming session files - Fixed
import typefrom@anthropic-ai/claude-agent-sdk/sdk-toolsfailing under NodeNext/Bundler module resolution (missing exports map entry since v0.2.69) - Fixed skills with
user-invocable: falsebeing included insupportedCommands()and thesystem:initmessage'sslash_commands/skillslists - Updated to parity with Claude Code v2.1.74
- Fixed
options.envbeing overridden by the~/.claude/settings.jsonenv block when not usinguseras asettingSourcesoption - Updated to parity with Claude Code v2.1.73
- Added
agentProgressSummariesoption to enable periodic AI-generated progress summaries for running subagents (foreground and background), emitted ontask_progressevents via the newsummaryfield - Added
getSettings()appliedsection with runtime-resolvedmodelandeffortvalues - Fixed
toggleMcpServerandreconnectMcpServerfailing with "Server not found" for servers passed viaquery({mcpServers}) - Updated to parity with Claude Code v2.1.72
- Updated to parity with Claude Code v2.1.71
- Fixed
type: "http"MCP servers failing with HTTP 406 "Not Acceptable" on Streamable HTTP servers that strictly enforce theAccept: application/json, text/event-streamheader - Changed
AgentToolInput.subagent_typeto optional — defaults to thegeneral-purposeagent when omitted - Updated to parity with Claude Code v2.1.70
- Added
toolConfig.askUserQuestion.previewFormatoption to configure the content format ('markdown'or'html') for thepreviewfield on AskUserQuestion tool options. Thepreviewfield andannotationsoutput are now exposed in the public SDK types. - Added
supportsFastModefield toModelInfoindicating whether a model supports fast mode - Added
agent_id(for subagents) andagent_type(for subagents and--agent) fields to hook events - Fixed SDK-mode MCP servers (registered via
sdkMcpServersin theinitializecontrol request) getting disconnected when background plugin installation refreshes project MCP config - Fixed breaking change:
system:initandresultevents now emit'Task'as the Agent tool name again (reverted from'Agent', which was an unintentional breaking change in a patch release). The wire name will migrate to'Agent'in the next minor release. - Fixed control responses with malformed
updatedPermissionsfrom SDK hosts blocking tool calls with a ZodError; the invalid field is now stripped and a warning is logged instead. - Improved memory usage of
getSessionMessages()for large sessions with compacted history
- Updated to parity with Claude Code v2.1.68
- Updated to parity with Claude Code v2.1.66
- SDK: Fixed
pathToClaudeCodeExecutablefailing when set to a bare command name (e.g.,"claude") that should resolve via PATH - Added
supportedAgents()method to the Query interface to view available subagents - Fixed MCP replacement tools being incorrectly denied in subagents when using unprefixed MCP tool names
- Updated to parity with Claude Code v2.1.61
- Added
getSessionMessages()function for reading a session's conversation history from its transcript file, with support for pagination vialimitandoffsetoptions
- Updated to parity with Claude Code v2.1.58
- Updated to parity with Claude Code v2.1.56
- Updated to parity with Claude Code v2.1.55
- Updated to parity with Claude Code v2.1.54
- Added
listSessions()for discovering and listing past sessions with light metadata
- Updated to parity with Claude Code v2.1.52
- Updated to parity with Claude Code v2.1.51
- Fixed SDK crashing with
ReferenceErrorwhen used inside compiled Bun binaries (bun build --compile) - Fixed unbounded memory growth in long-running SDK sessions caused by message UUID tracking never evicting old entries
- Fixed local slash command output not being returned to SDK clients
- Added
task_progressevents for real-time background agent progress reporting with cumulative usage metrics, tool counts, and duration - Fixed
session.close()in the v2 session API killing the subprocess before it could persist session data, which brokeresumeSession()
- Updated to parity with Claude Code v2.1.50
- Updated to parity with Claude Code v2.1.49
- SDK model info now includes
supportsEffort,supportedEffortLevels, andsupportsAdaptiveThinkingfields so consumers can discover model capabilities. - Permission suggestions are now populated when safety checks trigger an ask response, enabling SDK consumers to display permission options.
- Added
ConfigChangehook event that fires when configuration files change during a session, enabling enterprise security auditing and optional blocking of settings changes.
- Updated to parity with Claude Code v2.1.47
- Added
promptSuggestion()method onQueryto request prompt suggestions based on the current conversation context - Added
tool_use_idfield totask_notificationevents for correlating task completions with originating tool calls
- Updated to parity with Claude Code v2.1.46
- Added support for Claude Sonnet 4.6
- Added
task_startedsystem message to the SDK stream, emitted when subagent tasks are registered - Fixed
Session.stream()returning prematurely when background subagents are still running, by holding back intermediate result messages until all tasks complete - Improved memory usage for shell commands that produce large output — RSS no longer grows unboundedly with command output size
- Updated to parity with Claude Code v2.1.44
- Updated to parity with Claude Code v2.1.43
- Updated to parity with Claude Code v2.1.42
- Updated to parity with Claude Code v2.1.41
- Updated to parity with Claude Code v2.1.40
- Updated to parity with Claude Code v2.1.39
- Updated to parity with Claude Code v2.1.38
- Updated to parity with Claude Code v2.1.37
- Updated to parity with Claude Code v2.1.36
- Updated to parity with Claude Code v2.1.35
- Updated to parity with Claude Code v2.1.34
- Added
TeammateIdleandTaskCompletedhook events with correspondingTeammateIdleHookInputandTaskCompletedHookInputtypes - Added
sessionIdoption to specify a custom UUID for conversations instead of auto-generated ones - Updated to parity with Claude Code v2.1.33
- Updated to parity with Claude Code v2.1.32
- Added
stop_reasonfield toSDKResultSuccessandSDKResultErrorto indicate why the model stopped generating
- Added
debuganddebugFileoptions for programmatic control of debug logging - Added optional
pagesfield toFileReadToolInputfor reading specific PDF page ranges - Added
partsoutput type toFileReadToolOutputfor page-extracted PDF results - Fixed "(no content)" placeholder messages being included in SDK output
- Updated to parity with Claude Code v2.1.29
- Added optional
annotationssupport to thetool()helper function for specifying MCP tool hints (readOnlyHint, destructiveHint, openWorldHint, idempotentHint) - Fixed
mcpServerStatus()to include tools from SDK and dynamically-added MCP servers - Updated to parity with Claude Code v2.1.27
- Updated to parity with Claude Code v2.1.25
- Fixed structured output validation errors not being reported correctly
- Updated to parity with Claude Code v2.1.23
- Fixed structured outputs to handle empty assistant messsages
- Updated to parity with Claude Code v2.1.22
- Added
config,scope, andtoolsfields toMcpServerStatusfor richer server introspection - Added
reconnectMcpServer()andtoggleMcpServer()methods for managing MCP server connections - Added
disabledstatus toMcpServerStatus - Fixed PermissionRequest hooks not being executed in SDK mode (e.g., VS Code extension)
- Updated to parity with Claude Code v2.1.21
- Added support for loading CLAUDE.md files from directories specified via
additionalDirectoriesoption (requires settingCLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1in theenvoption) - Added
CLAUDE_CODE_ENABLE_TASKSenv var, set totrueto opt into the new task system - Updated to parity with Claude Code v2.1.20
- Added
CLAUDE_CODE_ENABLE_TASKSenv var, set totrueto opt into the new task system
- Updated to parity with Claude Code v2.1.17
- Updated to parity with Claude Code v2.1.16
- Added notification hook support
- Added
close()method to Query interface for forcefully terminating running queries - Updated to parity with Claude Code v2.1.15
- Updated to parity with Claude Code v2.1.14
- Updated to parity with Claude Code v2.1.12
- Updated to parity with Claude Code v2.1.11
- Added
skillsandmaxTurnsconfiguration options to custom agent definitions.
- Updated to parity with Claude Code v2.1.9
- Updated to parity with Claude Code v2.1.8
- Updated to parity with Claude Code v2.1.7
- Updated to parity with Claude Code v2.1.6
- Added
claudeCodeVersionfield topackage.jsonfor programmatically determining compatible CLI version
- Updated to parity with Claude Code v2.1.5
- Updated to parity with Claude Code v2.1.4
- Updated to parity with Claude Code v2.1.3
- Added
errorfield toMcpServerStatusfor failed MCP server connections - Updated to parity with Claude Code v2.1.0
- Updated to parity with Claude Code v2.0.78
- Updated to parity with Claude Code v2.0.75
- Updated to parity with Claude Code v2.0.74
- Fixed a bug where Stop hooks would not consistently run due to
Stream closederror - Updated to parity with Claude Code v2.0.73
- Fixed
/contextcommand not respecting custom system prompts - Fixed non-streaming single-turn queries to close immediately on first result instead of waiting for inactivity timeout
- Changed V2 session API method
receive()tostream()for consistency with Anthropic SDK patterns - Updated to parity with Claude Code v2.0.72
- Added zod
^4.0.0as peer dependency option in addition to zod^3.24.1 - Added support for AskUserQuestion tool. If using
toolsoption, enable by including'AskUserQuestion'in list - Fixed visible console window appearing when spawning Claude subprocess on Windows
- Fixed spawn message being sent to stderr callback (#45)
- Updated to parity with Claude Code v2.0.71
- Updated to parity with Claude Code v2.0.69
- Fixed a bug where disallowed MCP tools were visible to the model
- Updated to parity with Claude Code v2.0.68
- Updated to parity with Claude Code v2.0.67
- Fixed project MCP servers from
.mcp.jsonnot being available whensettingSourcesincludesproject - Updated to parity with Claude Code v2.0.66
- Updated to parity with Claude Code v2.0.66
- Fixed issues where SDK MCP servers, hooks, or canUseTool callbacks could fail when stdin was closed too early after the first result
- Updated to parity with Claude Code v2.0.64
- Updated to parity with Claude Code v2.0.63
- Updated to parity with Claude Code v2.0.61
- Updated to parity with Claude Code v2.0.60
- Updated to parity with Claude Code v2.0.59
- Updated to parity with Claude Code v2.0.58
- Added
betasoption to enable beta features. Currently supports'context-1m-2025-08-07'for 1M token context window on Sonnet 4/4.5. See https://platform.claude.com/docs/en/api/beta-headers for more details.
- Updated to parity with Claude Code v2.0.57
- Added
toolsoption to specify the exact set of built-in tools available to the agent. Usetools: ['Bash', 'Read', 'Edit']for a strict allowlist,tools: []to disable all built-in tools, ortools: { type: 'preset', preset: 'claude_code' }for all default tools. Omitting this option preserves existing behavior where all built-in tools are available (and can be filtered withdisallowedTools).
- Updated to parity with Claude Code v2.0.56
- Update to parity with Claude Code v2.0.55
- Updated to parity with Claude Code v2.0.54
- Added experimental v2 session APIs (
unstable_v2_createSession,unstable_v2_resumeSession,unstable_v2_prompt) for simpler multi-turn conversations - Fixed a bug where ExitPlanMode tool input was empty
- Updated to parity with Claude Code v2.0.53
- Updated to parity with Claude Code v2.0.52
- Updated to parity with Claude Code v2.0.51
- Added support for Opus 4.5! https://www.anthropic.com/news/claude-opus-4-5
- Updated to parity with Claude Code v2.0.50
- Updated to parity with Claude Code v2.0.49
- Updated to parity with Claude Code v2.0.47
- Add
errorfield to some messages
- Updated to parity with Claude Code v2.0.46
- Add support for Microsoft Foundry! See https://code.claude.com/docs/en/azure-ai-foundry
- Structured outputs support. Agents can now return validated JSON matching your schema. See https://platform.claude.com/docs/en/agent-sdk/structured-outputs.
- Updated to parity with Claude Code v2.0.45
- Updated to parity with Claude Code v2.0.44
- Updated to parity with Claude Code v2.0.43
- Updated to parity with Claude Code v2.0.42
- Updated to parity with Claude Code v2.0.41
- Updated to parity with Claude Code v2.0.37
- Updated to parity with Claude Code v2.0.36
- Updated to parity with Claude Code v2.0.35
- Updated to parity with Claude Code v2.0.34
- Updated to parity with Claude Code v2.0.33
- Updated to parity with Claude Code v2.0.32
- Added --max-budget-usd flag
- Fixed a bug where hooks were sometimes failing in stream mode
- Updated to parity with Claude Code v2.0.31
- Updated to parity with Claude Code v2.0.29
- Updated to parity with Claude Code v2.0.28
- Fixed a bug where custom tools were timing out after 30 seconds instead of respecting
MCP_TOOL_TIMEOUT(#42)
- Updated to parity with Claude Code v2.0.27
- Added
pluginsfield toOptions
- Updated to parity with Claude Code v2.0.26
- Updated to parity with Claude Code v2.0.25
- Fixed a bug where project-level skills were not loading when
'project'settings source was specified - Added
skillsfield toSDKSystemMessagewith list of available skills - Fixed a bug where some exported types were not importing correctly (#39)
- Updated to parity with Claude Code v2.0.22
- Updated to parity with Claude Code v2.0.21
- Updated to parity with Claude Code v2.0.20
- Updated to parity with Claude Code v2.0.19
- Updated to parity with Claude Code v2.0.18
- Updated to parity with Claude Code v2.0.17
- Updated to parity with Claude Code v2.0.15
- Updated
envtype to not use BunDicttype - Startup performance improvements when using multiple SDK MCP servers
- Updated to parity with Claude Code v2.0.14
- Updated to parity with Claude Code v2.0.13
- Updated to parity with Claude Code v2.0.12
- Increased SDK MCP channel closure timeout to 60s, addressing #15
- Updated to parity with Claude Code v2.0.11
- Updated to parity with Claude Code v2.0.10
- Added zod ^3.24.1 as peer dependency
- Fixed a bug where system prompt was sometimes not getting set correctly: #8
- Updated to parity with Claude Code v2.0.1
- Merged prompt options: The
customSystemPromptandappendSystemPromptfields have been merged into a singlesystemPromptfield for simpler configuration - No default system prompt: The Claude Code system prompt is no longer included by default, giving you full control over agent behavior. To use the Claude Code system prompt, explicitly set:
- No filesystem settings by default: Settings files (
settings.json,CLAUDE.md), slash commands, and subagents are no longer loaded automatically. This ensures SDK applications have predictable behavior independent of local filesystem configurations - Explicit settings control: Use the new
settingSourcesfield to specify which settings locations to load:["user", "project", "local"] - Programmatic subagents: Subagents can now be defined inline in code using the
agentsoption, enabling dynamic agent creation without filesystem dependencies. Learn more - Session forking: Resume sessions with the new
forkSessionoption to branch conversations and explore different approaches from the same starting point. Learn more - Granular settings control: The
settingSourcesoption gives you fine-grained control over which filesystem settings to load, improving isolation for CI/CD, testing, and production deployments - Comprehensive documentation now available in the API Guide
- New guides for Custom Tools, Permissions, Session Management, and more
- Complete TypeScript API reference