@anthropic-ai/claude-agent-sdk
0.3.330 · 20 Nov 2026SEE LICENSE IN README.md20.7M / weekRepositorynpmAtom feed
351 stable releases, newest first, by release line. Notes are quoted as the maintainers published them.
0.3.330
20 Nov 2026Summary· from the note as AI read it
Read before upgrading: 1 change to make.
What's changed
Added a
system/informationalwarning, taggedsettings_not_in_effect, whensettingsor a user, project or local settings file fails validation and is not in effectFixed Claude still waiting for a background agent that
stopTask()stopped just as it finishedFixed variables that a
SessionStarthook writes toCLAUDE_ENV_FILEnot reaching the Bash tool with thecontinueoptionFixed Google Cloud's Agent Platform sessions ignoring
fastModeinsettingswhen the model comes fromANTHROPIC_MODELor a settings file; such sessions now bill at the fast mode priceFixed the initialize response's
fast_mode_statedescribing the default model instead of the model the session runsFixed a lost or swapped tool result from an SDK MCP server when a call overlapped a reconnect; while an earlier request is unanswered, a new one can carry an
idof 1,048,576 or moreChanged the TypeScript SDK's
query()to fail with an error whensettingsis a JSON string that doesn't parseUpdated to parity with Claude Code v2.1.330
Update
npm install @anthropic-ai/claude-agent-sdk@0.3.330 # or yarn add @anthropic-ai/claude-agent-sdk@0.3.330 # or pnpm add @anthropic-ai/claude-agent-sdk@0.3.330 # or bun add @anthropic-ai/claude-agent-sdk@0.3.330
0.3.329
19 Nov 2026Added a
system/informationalwarning, taggedmanaged_hooks_not_loaded, when hooks in managed settings fail to loadAdded
permissions.workingDirectoriesExcludeto theSettingstype: paths, read only from--settingsand settings the host sends, that the working-directory read and write blocks treat as outsideFixed sessions bound with
SpareProcess.claim()ignoringautoCompactWindowfrom the folder's settings or the claim'ssettings
What's changed
Added a
system/informationalwarning, taggedmanaged_hooks_not_loaded, when hooks in managed settings fail to loadAdded
permissions.workingDirectoriesExcludeto theSettingstype: paths, read only from--settingsand settings the host sends, that the working-directory read and write blocks treat as outsideFixed sessions bound with
SpareProcess.claim()ignoringautoCompactWindowfrom the folder's settings or the claim'ssettingsFixed retained memory when an in-process MCP server does not answer its start-up handshake
Fixed memory growth in long sessions that use
--replay-user-messages: the SDK no longer keeps echoes of its own tool results and permission answersFixed an MCP server that a plugin started at launch staying connected after the plugin was disabled or uninstalled and
reload_pluginsran, in headless and SDK sessionsFixed
rewind_conversationremoving history under a message sent right after a model change: the request is now refused with "commands queued", and callers can send it againImproved memory use of idle SDK sessions: after 30 seconds idle, large tool result data that no model request reads is released, except while Remote Control is on
Changed the error when the macOS Keychain can't save a refreshed login:
erroris nowinvalid_request, notauthentication_failed, andapi_error_statusisnull, not 401Updated to parity with Claude Code v2.1.329
Update
npm install @anthropic-ai/claude-agent-sdk@0.3.329 # or yarn add @anthropic-ai/claude-agent-sdk@0.3.329 # or pnpm add @anthropic-ai/claude-agent-sdk@0.3.329 # or bun add @anthropic-ai/claude-agent-sdk@0.3.329
0.3.328
18 Nov 2026Added
onFailuretomcp_toolhooks in theSettingstype: with"block", a hook whose call fails blocks the action it guardsAdded
CLAUDE_CODE_DISABLE_DEFERRED_TOOL_RESUME: set it in theenvoption to stopresumeandcontinuefrom running a tool call that a hook deferred; settings can't set itAdded support for the policy plugin's
allowManagedModsOnlyoption in host-suppliedmanagedSettings; an admin's managed settings still win
What's changed
Added
onFailuretomcp_toolhooks in theSettingstype: with"block", a hook whose call fails blocks the action it guardsAdded
CLAUDE_CODE_DISABLE_DEFERRED_TOOL_RESUME: set it in theenvoption to stopresumeandcontinuefrom running a tool call that a hook deferred; settings can't set itAdded support for the policy plugin's
allowManagedModsOnlyoption in host-suppliedmanagedSettings; an admin's managed settings still winFixed the
agentoption: an inline definition inagentsnow wins over a user, project, plugin or built-in agent of the same name for model, prompt and hooksFixed the
agentoption: an agent from an agents directory now keeps its system prompt whensystemPromptis not setFixed the model saying background agents were still running after an SDK interrupt had stopped them
Changed subagents to wait for their own subagents by default when
CLAUDE_CODE_FORK_SUBAGENT=0is setChanged a shell command rewritten by a
PermissionRequesthook: the rewrite's own permission check now decides the sandbox, so a sandbox-excluded rewrite runs outside it;canUseToolis unchangedChanged
resolveSettings()on Windows to re-read registry policy every 6 hours while none is set (was 30 minutes)Updated to parity with Claude Code v2.1.328
Update
npm install @anthropic-ai/claude-agent-sdk@0.3.328 # or yarn add @anthropic-ai/claude-agent-sdk@0.3.328 # or pnpm add @anthropic-ai/claude-agent-sdk@0.3.328 # or bun add @anthropic-ai/claude-agent-sdk@0.3.328
0.3.327
17 Nov 2026Summary· from the note as AI read it
Read before upgrading: 5 changes to make.
- 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. - Deprecated
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.
What's changed
- 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 nopromptFixed Claude reporting a background agent as still running when its permission request had waited on
canUseToolfor 30 seconds or moreReverted 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 numberChanged 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
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
Update
npm install @anthropic-ai/claude-agent-sdk@0.3.327 # or yarn add @anthropic-ai/claude-agent-sdk@0.3.327 # or pnpm add @anthropic-ai/claude-agent-sdk@0.3.327 # or bun add @anthropic-ai/claude-agent-sdk@0.3.327
0.3.326
16 Nov 2026- Deprecated
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' Added
mcpServersDelivery: 'initialize': sendsmcpServersin the initialize request instead of on Claude Code's command line; needs the bundled Claude Code or newerAdded
getSessionInfo()to the/coreentry
What's changed
Added
mcpServersDelivery: 'initialize': sendsmcpServersin the initialize request instead of on Claude Code's command line; needs the bundled Claude Code or newerAdded
getSessionInfo()to the/coreentryAdded
message_uuidtocancel_async_messageresponses, naming the dropped messageAdded a warning on stderr and as a
system/informationalmessage when a tool list has an entry that doesn't look like a complete ruleAdded a
system/informationalwarning, taggedmanaged_mcp_arrived, when an administrator'smanaged-mcp.jsonarrives during a session and your own MCP servers stop loadingFixed 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 refusedFixed
resumeSessionAtfailing on an empty reply, and a resumed session losing recent turns after a crash when the previous turn ended with oneFixed 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 unchangedImproved 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 demandChanged the JSON-RPC
idof requests to an SDK MCP server from a number to a stringChanged
rewindFiles()on macOS, Linux and WSL to leave some files untouched when the sandbox is on, and report them as skippedChanged the
register_repo_rootcontrol request to refuse some folders it used to accept- Deprecated
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
Update
npm install @anthropic-ai/claude-agent-sdk@0.3.326 # or yarn add @anthropic-ai/claude-agent-sdk@0.3.326 # or pnpm add @anthropic-ai/claude-agent-sdk@0.3.326 # or bun add @anthropic-ai/claude-agent-sdk@0.3.326
0.3.325
13 Nov 2026Added
archiveSession()andunarchiveSession(), and anarchivedfield on the sessions thatlistSessions()andgetSessionInfo()returnAdded
refuseIfBusytoQuery.reloadPlugins()so a host can have a reload refused while the session is busyAdded
managed_locktoplugin_errorsentries onsystem/init, naming the managedenabledPluginsentry that dropped a plugin copy
What's changed
Added
archiveSession()andunarchiveSession(), and anarchivedfield on the sessions thatlistSessions()andgetSessionInfo()returnAdded
refuseIfBusytoQuery.reloadPlugins()so a host can have a reload refused while the session is busyAdded
managed_locktoplugin_errorsentries onsystem/init, naming the managedenabledPluginsentry that dropped a plugin copyAdded a
system/informationalwarning, taggedhook_no_verdict, when aPreToolUsehook can't run or answer, or times out, without refusing its tool callAdded
invalid_config_fileto theconfig_file_invalidstartup failure result: the broken config file's path and its backup's path as fieldsFixed 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/initFixed
supportedEffortLevelsin model info listing effort levels above the organization's effort cap or themaxEffortLevelsettingChanged the
sandboxoption: sandboxed Bash commands are no longer auto-approved unlessautoAllowBashIfSandboxed: trueis setChanged 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 callsChanged
suggestionsoncanUseToolfor Bash and Monitor: a list of rules alone is sent only when saving it would allow that commandChanged the
ProposeSkillsInputtype: a proposal can carryedits, andskillMdis optionalUpdated to parity with Claude Code v2.1.325
Update
npm install @anthropic-ai/claude-agent-sdk@0.3.325 # or yarn add @anthropic-ai/claude-agent-sdk@0.3.325 # or pnpm add @anthropic-ai/claude-agent-sdk@0.3.325 # or bun add @anthropic-ai/claude-agent-sdk@0.3.325
0.3.324
13 Nov 2026Updated to parity with Claude Code v2.1.324
0.3.323
12 Nov 2026Added
machinePolicy.didNotLoad(alpha) toresolveSettings()'s result, which tells a host when a machine policy source may be there and did not loadAdded
matchDeniedModels()(alpha), which tells a host which models adeniedModelslist blocks, by Claude Code's own entry rulesAdded 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
What's changed
Added
machinePolicy.didNotLoad(alpha) toresolveSettings()'s result, which tells a host when a machine policy source may be there and did not loadAdded
matchDeniedModels()(alpha), which tells a host which models adeniedModelslist blocks, by Claude Code's own entry rulesAdded 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 callAdded
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 nothingFixed 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 failedFixed
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 itFixed
getSessionMessagesleaving out a queued prompt that directly follows a compaction summaryFixed
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 requestFixed most
initializeoptions, such as agents and skills, being ignored when aSessionStarthook supplied the first messageFixed an MCP server removed and re-added with
setMcpServers()stayingneeds-authwith no tools when a tool call had tried to reach it in betweenFixed
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 commandChanged
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 parsedChanged 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 callbackUpdated to parity with Claude Code v2.1.323
Update
npm install @anthropic-ai/claude-agent-sdk@0.3.323 # or yarn add @anthropic-ai/claude-agent-sdk@0.3.323 # or pnpm add @anthropic-ai/claude-agent-sdk@0.3.323 # or bun add @anthropic-ai/claude-agent-sdk@0.3.323
0.3.322
10 Nov 2026Updated to parity with Claude Code v2.1.322
0.3.321
9 Nov 2026Fixed
canUseToolgetting the app's own PreToolUse hook reason indecisionReasonwhen another hook also askedFixed a PreToolUse hook's
askbeing lost when another hook'sdeferfinished first and could not be honoredFixed every hook being dropped when one event in the
hooksoption is set toundefined
What's changed
Fixed
canUseToolgetting the app's own PreToolUse hook reason indecisionReasonwhen another hook also askedFixed a PreToolUse hook's
askbeing lost when another hook'sdeferfinished first and could not be honoredFixed every hook being dropped when one event in the
hooksoption is set toundefinedFixed
WarmQuery.query()with a string prompt hanging afterstartup()withresumewhen the resumed session finished a turn of its own before the prompt was sentFixed
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 itFixed sessions hanging on save, and
importSessionToStore()never rejecting, when memory ran out while a transcript was being readImproved
resumeandcontinueon the bundled Claude Code binary:initializeis read during boot, so start-up work is less likely to run before your hooks are registeredChanged 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: 0Changed 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 connectedUpdated to parity with Claude Code v2.1.321
Update
npm install @anthropic-ai/claude-agent-sdk@0.3.321 # or yarn add @anthropic-ai/claude-agent-sdk@0.3.321 # or pnpm add @anthropic-ai/claude-agent-sdk@0.3.321 # or bun add @anthropic-ai/claude-agent-sdk@0.3.321
0.3.319
6 Nov 2026Added 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()succeedsFixed
session_writes_lostlisting the wrong session intranscript_session_idsafter/clearin a session resumed from a transcript file outside the projects folder
What's changed
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()succeedsFixed
session_writes_lostlisting the wrong session intranscript_session_idsafter/clearin a session resumed from a transcript file outside the projects folderImproved
deleteSession()to reject withENOTEMPTYif the session's folder could not be fully deletedChanged
session_writes_lostto be sent only when the CLI exits 0; a run that ends on an error result now gets only the stderr lineUpdated to parity with Claude Code v2.1.319
Update
npm install @anthropic-ai/claude-agent-sdk@0.3.319 # or yarn add @anthropic-ai/claude-agent-sdk@0.3.319 # or pnpm add @anthropic-ai/claude-agent-sdk@0.3.319 # or bun add @anthropic-ai/claude-agent-sdk@0.3.319
0.3.318
3 Nov 2026Added an optional
credential_expires_atfield to result messages: when the stored claude.ai sign-in in use endsAdded the
config_file_invalidstartup failure reason, reported when a configuration file read at startup isn't valid JSONFixed 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
What's changed
Added an optional
credential_expires_atfield to result messages: when the stored claude.ai sign-in in use endsAdded the
config_file_invalidstartup failure reason, reported when a configuration file read at startup isn't valid JSONFixed 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 isChanged
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 firstChanged
statusinPushNotificationInputto optionalUpdated to parity with Claude Code v2.1.318
Update
npm install @anthropic-ai/claude-agent-sdk@0.3.318 # or yarn add @anthropic-ai/claude-agent-sdk@0.3.318 # or pnpm add @anthropic-ai/claude-agent-sdk@0.3.318 # or bun add @anthropic-ai/claude-agent-sdk@0.3.318
0.3.317
3 Nov 2026Added
onFailureto hook matchers: with"block", a hook that throws or returns invalid output blocks the actionAdded 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
What's changed
Added
onFailureto hook matchers: with"block", a hook that throws or returns invalid output blocks the actionAdded 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.jsonAdded
initialize_not_firsttostartup_failure_reason, for a--await-initializelaunch whose first stdin line is not the initialize requestAdded
task.descriptionto the TaskCreate tool'stool_use_result: the description the task was created withAdded
lossytoreadFile()utf-8 answers:truewhen decoding replaced bytes that are not valid UTF-8Removed the
file_unchangedvariant ofFileReadOutputinsdk-tools.d.ts; a repeated Read now returns the file contentFixed
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
Update
npm install @anthropic-ai/claude-agent-sdk@0.3.317 # or yarn add @anthropic-ai/claude-agent-sdk@0.3.317 # or pnpm add @anthropic-ai/claude-agent-sdk@0.3.317 # or bun add @anthropic-ai/claude-agent-sdk@0.3.317
0.3.316
31 Oct 2026Added
permissions.blockReadsExemptPathsto theSettingstype: paths, read only from--settingsand settings the host sends, thatblockReadsOutsideWorkingDirectorieslets through without making them working directoriesUpdated to parity with Claude Code v2.1.316
0.3.315
30 Oct 2026Updated to parity with Claude Code v2.1.315
0.3.314
30 Oct 2026Added
sandbox_required_unavailabletostartup_failure_reason, for the result Claude Code writes when a required sandbox cannot runAdded
permissions.blockWritesOutsideWorkingDirectoriesto theSettingstypeAdded
prewarm()(alpha) to the@anthropic-ai/claude-agent-sdk/coreentry point
What's changed
Added
sandbox_required_unavailabletostartup_failure_reason, for the result Claude Code writes when a required sandbox cannot runAdded
permissions.blockWritesOutsideWorkingDirectoriesto theSettingstypeAdded
prewarm()(alpha) to the@anthropic-ai/claude-agent-sdk/coreentry pointFixed a settings file left out of
settingSourcesstill supplying some settings, such as auto mode rules and saved permission consentsUpdated to parity with Claude Code v2.1.314
Update
npm install @anthropic-ai/claude-agent-sdk@0.3.314 # or yarn add @anthropic-ai/claude-agent-sdk@0.3.314 # or pnpm add @anthropic-ai/claude-agent-sdk@0.3.314 # or bun add @anthropic-ai/claude-agent-sdk@0.3.314
0.3.312
27 Oct 2026Added
autoMode,skipAutoPermissionPrompt,useAutoModeDuringPlanandpermissions.disableAutoModeto theSettingstypeAdded
unanswered(skipped,replied_in_chatordismissed) to AskUserQuestion answers' per-questionannotations; send it only whensystem/initlists theask_user_question_unanswered_v1capabilityFixed
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
What's changed
Added
autoMode,skipAutoPermissionPrompt,useAutoModeDuringPlanandpermissions.disableAutoModeto theSettingstypeAdded
unanswered(skipped,replied_in_chatordismissed) to AskUserQuestion answers' per-questionannotations; send it only whensystem/initlists theask_user_question_unanswered_v1capabilityFixed
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 CLIUpdated to parity with Claude Code v2.1.312
Update
npm install @anthropic-ai/claude-agent-sdk@0.3.312 # or yarn add @anthropic-ai/claude-agent-sdk@0.3.312 # or pnpm add @anthropic-ai/claude-agent-sdk@0.3.312 # or bun add @anthropic-ai/claude-agent-sdk@0.3.312
0.3.311
26 Oct 2026- Breaking
Changed the minimum supported Node.js version from 18.0.0 to 18.14.0
Added
cacheCreationEphemeral5mInputTokensandcacheCreationEphemeral1hInputTokenstoModelUsage, splittingcacheCreationInputTokensby cache lifetimeChanged 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
What's changed
Added
cacheCreationEphemeral5mInputTokensandcacheCreationEphemeral1hInputTokenstoModelUsage, splittingcacheCreationInputTokensby cache lifetimeChanged 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
- Breaking
Changed the minimum supported Node.js version from 18.0.0 to 18.14.0
Updated to parity with Claude Code v2.1.311
Update
npm install @anthropic-ai/claude-agent-sdk@0.3.311 # or yarn add @anthropic-ai/claude-agent-sdk@0.3.311 # or pnpm add @anthropic-ai/claude-agent-sdk@0.3.311 # or bun add @anthropic-ai/claude-agent-sdk@0.3.311
0.3.310
23 Oct 2026Updated to parity with Claude Code v2.1.310
0.3.309
22 Oct 2026Fixed host-supplied
managedSettingsdroppingdisableAllHooks,disableSkillShellExecutionand emptyallowedHttpHookUrls/httpHookAllowedEnvVarslistsChanged
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 rootChanged
extractFromBunfs()to reuse an already-extracted file only when its bytes match the embedded binary, replacing it otherwise
What's changed
Fixed host-supplied
managedSettingsdroppingdisableAllHooks,disableSkillShellExecutionand emptyallowedHttpHookUrls/httpHookAllowedEnvVarslistsChanged
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 rootChanged
extractFromBunfs()to reuse an already-extracted file only when its bytes match the embedded binary, replacing it otherwiseUpdated to parity with Claude Code v2.1.309
Update
npm install @anthropic-ai/claude-agent-sdk@0.3.309 # or yarn add @anthropic-ai/claude-agent-sdk@0.3.309 # or pnpm add @anthropic-ai/claude-agent-sdk@0.3.309 # or bun add @anthropic-ai/claude-agent-sdk@0.3.309
0.3.308
22 Oct 2026Updated to parity with Claude Code v2.1.308
0.3.307
21 Oct 2026Added
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 firedAdded
supportedDialogKindsto browser SDKquery(), sent oninitialize; a non-empty list requiresonUserDialogUpdated to parity with Claude Code v2.1.307
0.3.306
21 Oct 2026Updated to parity with Claude Code v2.1.306
0.3.305
20 Oct 2026Added
recommendationsandfixto theget_usageresponse's behavior windowsFixed servers set with
setMcpServersbeing replaced later in the session by a same-named server from the user's own settingsFixed
startup()withinitializeTimeoutMs: nullcounting time spent in SessionStart or Setup hooks against its 60-second limit;nullnow works like leaving the option out
What's changed
Added
recommendationsandfixto theget_usageresponse's behavior windowsFixed servers set with
setMcpServersbeing replaced later in the session by a same-named server from the user's own settingsFixed
startup()withinitializeTimeoutMs: nullcounting time spent in SessionStart or Setup hooks against its 60-second limit;nullnow works like leaving the option outChanged 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 networkUpdated to parity with Claude Code v2.1.305
Update
npm install @anthropic-ai/claude-agent-sdk@0.3.305 # or yarn add @anthropic-ai/claude-agent-sdk@0.3.305 # or pnpm add @anthropic-ai/claude-agent-sdk@0.3.305 # or bun add @anthropic-ai/claude-agent-sdk@0.3.305
0.3.304
19 Oct 2026Added
suspendSseStream(query)andresumeSseStream(query)to the browser SDK: close a query's event stream and reopen it later without ending the queryAdded 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 sharesFixed
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
What's changed
Added
suspendSseStream(query)andresumeSseStream(query)to the browser SDK: close a query's event stream and reopen it later without ending the queryAdded 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 sharesFixed
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 reportedFixed
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 hookUpdated to parity with Claude Code v2.1.304
Update
npm install @anthropic-ai/claude-agent-sdk@0.3.304 # or yarn add @anthropic-ai/claude-agent-sdk@0.3.304 # or pnpm add @anthropic-ai/claude-agent-sdk@0.3.304 # or bun add @anthropic-ai/claude-agent-sdk@0.3.304
0.3.303
18 Oct 2026Updated to parity with Claude Code v2.1.303
0.3.302
16 Oct 2026Fixed structured output results delivering a response's output as
structured_outputwhen the API refused that response; the result is now an error with no payloadChanged an omitted
permissionModeto start indefaultmode on third-party providers, with telemetry off or on a fresh install; passpermissionMode: 'auto'to keep auto modeChanged 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
What's changed
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 payloadChanged an omitted
permissionModeto start indefaultmode on third-party providers, with telemetry off or on a fresh install; passpermissionMode: 'auto'to keep auto modeChanged 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 offUpdated to parity with Claude Code v2.1.302
Update
npm install @anthropic-ai/claude-agent-sdk@0.3.302 # or yarn add @anthropic-ai/claude-agent-sdk@0.3.302 # or pnpm add @anthropic-ai/claude-agent-sdk@0.3.302 # or bun add @anthropic-ai/claude-agent-sdk@0.3.302
0.3.301
15 Oct 2026Added 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 settingsAdded
addPluginstoQuery.reloadPlugins()so a host can load more plugin folders into a running session
What's changed
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 settingsAdded
addPluginstoQuery.reloadPlugins()so a host can load more plugin folders into a running sessionFixed
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 limitChanged the error when a full disk keeps the login from being refreshed:
erroris nowinvalid_request, notauthentication_failed, andapi_error_statusisnull, not 401Changed
mcpServerStatus()to still report a tool's_meta.ui.visibilitywhen the rest of its_meta.uifails validationUpdated to parity with Claude Code v2.1.301
Update
npm install @anthropic-ai/claude-agent-sdk@0.3.301 # or yarn add @anthropic-ai/claude-agent-sdk@0.3.301 # or pnpm add @anthropic-ai/claude-agent-sdk@0.3.301 # or bun add @anthropic-ai/claude-agent-sdk@0.3.301
0.3.300
14 Oct 2026Fixed
importSessionToStoreskipping transcript rows that contain a Unicode line or paragraph separator (U+2028, U+2029) on Node 24 and BunFixed 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"
What's changed
Fixed
importSessionToStoreskipping transcript rows that contain a Unicode line or paragraph separator (U+2028, U+2029) on Node 24 and BunFixed 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 NodecryptopolyfillChanged
thinking: { type: 'disabled' }andmaxThinkingTokens: 0to run as adaptive thinking on models that can't turn thinking offChanged
updatedInputfrom PreToolUse and PermissionRequest hook callbacks: it is now validated like Claude's own input and unknown keys are dropped;canUseToolis unchangedUpdated to parity with Claude Code v2.1.300
Update
npm install @anthropic-ai/claude-agent-sdk@0.3.300 # or yarn add @anthropic-ai/claude-agent-sdk@0.3.300 # or pnpm add @anthropic-ai/claude-agent-sdk@0.3.300 # or bun add @anthropic-ai/claude-agent-sdk@0.3.300
0.3.299
14 Oct 2026Added an optional
nextFireAt(epoch ms of the next run) to the CronCreate and CronList tool outputsAdded
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 orderFixed
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
What's changed
Added an optional
nextFireAt(epoch ms of the next run) to the CronCreate and CronList tool outputsAdded
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 orderFixed
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 nullprefillTextFixed 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 omittedChanged
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
Update
npm install @anthropic-ai/claude-agent-sdk@0.3.299 # or yarn add @anthropic-ai/claude-agent-sdk@0.3.299 # or pnpm add @anthropic-ai/claude-agent-sdk@0.3.299 # or bun add @anthropic-ai/claude-agent-sdk@0.3.299
0.3.296
9 Oct 2026Added
claude_code_versionto theinitializecontrol response so clients know the CLI version before the first turnAdded
autoCompactWindowtoAgentDefinition, so a subagent can auto-compact earlier than the main conversation's windowFixed 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
What's changed
Added
claude_code_versionto theinitializecontrol response so clients know the CLI version before the first turnAdded
autoCompactWindowtoAgentDefinition, so a subagent can auto-compact earlier than the main conversation's windowFixed the
sandboxoption discarding an inlinesettings.sandboxblock: the two now merge, the option's values win, and deny and credential lists from both sides are combinedChanged 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 wholeUpdated to parity with Claude Code v2.1.296
Update
npm install @anthropic-ai/claude-agent-sdk@0.3.296 # or yarn add @anthropic-ai/claude-agent-sdk@0.3.296 # or pnpm add @anthropic-ai/claude-agent-sdk@0.3.296 # or bun add @anthropic-ai/claude-agent-sdk@0.3.296
0.3.295
8 Oct 2026Added
overageEnabledtoSDKRateLimitInfo: on usage-limit warnings, whether the account has extra usage turned onFixed an MCP server added with
mcp_set_serverssometimes keeping an outdated tool list when another server in the same request connected laterFixed assistant text blocks losing their
citationsin streamed responses
What's changed
Added
overageEnabledtoSDKRateLimitInfo: on usage-limit warnings, whether the account has extra usage turned onFixed an MCP server added with
mcp_set_serverssometimes keeping an outdated tool list when another server in the same request connected laterFixed assistant text blocks losing their
citationsin streamed responsesFixed 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 carryChanged 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 denialChanged
tool_result_meta.non_execution_kindto be absent when a mod withheld the result of a tool that ran without error; it waspermission-ruleChanged
pasted_contenton user messages to be ignored when it holds over 1,000 entries and blocks in allChanged 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 capsChanged
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 muchChanged
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,536Updated to parity with Claude Code v2.1.295
Update
npm install @anthropic-ai/claude-agent-sdk@0.3.295 # or yarn add @anthropic-ai/claude-agent-sdk@0.3.295 # or pnpm add @anthropic-ai/claude-agent-sdk@0.3.295 # or bun add @anthropic-ai/claude-agent-sdk@0.3.295
0.3.294
8 Oct 2026Updated to parity with Claude Code v2.1.294
0.3.293
7 Oct 2026Added an optional
subagent_typetobackground_tasks_changedtask entries, so hosts can name each subagent's type without pairing withtask_startedUpdated to parity with Claude Code v2.1.293
0.3.292
6 Oct 2026Added
agent_idto theassistantandusermessages a subagent produces; it equals thetask_idon that subagent's task events and stays the same when the subagent is resumedAdded
parent_task_idtotask_startedevents andbackground_tasks_changedentries, naming the subagent task that launched a taskAdded
run_idto background task events andorigin.runIdto task notifications, so a host can tell a resumed task's runs apart
What's changed
Added
agent_idto theassistantandusermessages a subagent produces; it equals thetask_idon that subagent's task events and stays the same when the subagent is resumedAdded
parent_task_idtotask_startedevents andbackground_tasks_changedentries, naming the subagent task that launched a taskAdded
run_idto background task events andorigin.runIdto task notifications, so a host can tell a resumed task's runs apartAdded typed
sectionsandnotesto theListAgentstool'stool_use_result, so hosts can list agents without parsing its textAdded
recipient_kindto SendMessagetool_useinputs on assistant messages, and their top-levelapproveis now always a boolean, so hosts no longer infer them from the raw inputAdded 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 sessionFixed 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_notificationChanged
canUseTooloptions to carrysuppressAlwaysAllowRule: truefor connector tools that an organization set to require approval, so hosts can hide their "always allow" choiceUpdated to parity with Claude Code v2.1.292
Update
npm install @anthropic-ai/claude-agent-sdk@0.3.292 # or yarn add @anthropic-ai/claude-agent-sdk@0.3.292 # or pnpm add @anthropic-ai/claude-agent-sdk@0.3.292 # or bun add @anthropic-ai/claude-agent-sdk@0.3.292
0.3.291
6 Oct 2026Updated to parity with Claude Code v2.1.291
0.3.290
5 Oct 2026Added an optional
offsetfield to the WebFetch tool input for reading on through long pagesFixed 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 toolsFixed 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
What's changed
Added an optional
offsetfield to the WebFetch tool input for reading on through long pagesFixed 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 toolsFixed 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 indisallowedToolsFixed 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 itFixed
includePartialMessagesstreams leaving a message withoutmessage_stopwhen the stream was cut, interrupted or fell back to non-streamingChanged
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 flightUpdated to parity with Claude Code v2.1.290
Update
npm install @anthropic-ai/claude-agent-sdk@0.3.290 # or yarn add @anthropic-ai/claude-agent-sdk@0.3.290 # or pnpm add @anthropic-ai/claude-agent-sdk@0.3.290 # or bun add @anthropic-ai/claude-agent-sdk@0.3.290
0.3.289
3 Oct 2026Updated to parity with Claude Code v2.1.289
0.3.288
2 Oct 2026Updated to parity with Claude Code v2.1.288
0.3.287
1 Oct 2026Added optional remote-session latency fields (
first_text_post_queue_wait_ms,first_text_post_queued_behind) to the success result messageFixed
includePartialMessagesstreams sending a cut-short reply'smessage_stoplate or never, so apps could show the reply as still in progressFixed 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
What's changed
Added optional remote-session latency fields (
first_text_post_queue_wait_ms,first_text_post_queued_behind) to the success result messageFixed
includePartialMessagesstreams sending a cut-short reply'smessage_stoplate or never, so apps could show the reply as still in progressFixed 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 itFixed
commands_changedarriving beforeinit, or twice, at session start: theinitializeresponse now includes commands registered at startupChanged
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 turnChanged
tool_use_resultfor MCP tools:structuredContentover 1,048,576 JSON characters is left off andstructuredContentOmitted: trueset, except for SDK-server and MCP Apps toolsUpdated to parity with Claude Code v2.1.287
Update
npm install @anthropic-ai/claude-agent-sdk@0.3.287 # or yarn add @anthropic-ai/claude-agent-sdk@0.3.287 # or pnpm add @anthropic-ai/claude-agent-sdk@0.3.287 # or bun add @anthropic-ai/claude-agent-sdk@0.3.287
0.3.286
30 Sep 2026Added the initialize response field
sdk_mcp_manifests_parkedand thesystem/initcapabilitiessdk_mcp_manifestsandsdk_mcp_tools_list_changedFixed foreground subagents sometimes not receiving the task-tracking tools listed in
toolsorallowedToolsFixed 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
What's changed
Added the initialize response field
sdk_mcp_manifests_parkedand thesystem/initcapabilitiessdk_mcp_manifestsandsdk_mcp_tools_list_changedFixed foreground subagents sometimes not receiving the task-tracking tools listed in
toolsorallowedToolsFixed 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-chromeChanged 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 itChanged 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 approvalsUpdated to parity with Claude Code v2.1.286
Update
npm install @anthropic-ai/claude-agent-sdk@0.3.286 # or yarn add @anthropic-ai/claude-agent-sdk@0.3.286 # or pnpm add @anthropic-ai/claude-agent-sdk@0.3.286 # or bun add @anthropic-ai/claude-agent-sdk@0.3.286
0.3.285
29 Sep 2026Added an optional
read.title(the artifact's stored title) to the Artifact tool's structured read resultAdded
provider_not_allowedtostartup_failure_reasonandallowedProvidersto theSettingstypeFixed 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
What's changed
Added an optional
read.title(the artifact's stored title) to the Artifact tool's structured read resultAdded
provider_not_allowedtostartup_failure_reasonandallowedProvidersto theSettingstypeFixed 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 resultFixed
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 betweenFixed
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 connectedFixed
rewind_conversationleaving a backgrounded MCP tool call running after the message that started it was removedChanged Bash/PowerShell
timeoutto bound arun_in_backgroundcommand (was ignored; default 30 min, max 2 h); thestoppedtask notification for a stop at that limit says whyChanged
getSubagentMessages()to also return the messages a subagent read while it ran, such as a message sent to it;offsetandlimitcount these rowsUpdated to parity with Claude Code v2.1.285
Update
npm install @anthropic-ai/claude-agent-sdk@0.3.285 # or yarn add @anthropic-ai/claude-agent-sdk@0.3.285 # or pnpm add @anthropic-ai/claude-agent-sdk@0.3.285 # or bun add @anthropic-ai/claude-agent-sdk@0.3.285
0.3.284
28 Sep 2026Added a renamed skill's directory name to its
SlashCommandaliaseswhen the name is plain and Claude Code ships no command by that nameAdded
applied.ultracodeAvailableandapplied.ultracodeRequestedtogetSettings(): whether this session can run Ultracode, and whether it is requested, independent of whether it is in effectFixed
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
What's changed
Added a renamed skill's directory name to its
SlashCommandaliaseswhen the name is plain and Claude Code ships no command by that nameAdded
applied.ultracodeAvailableandapplied.ultracodeRequestedtogetSettings(): whether this session can run Ultracode, and whether it is requested, independent of whether it is in effectFixed
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 keptFixed
getSessionMessages()leaving out messages from other agents, sessions and channels that the CLI transcript showsFixed
{ decision: 'block' }returned by Elicitation and ElicitationResult hook callbacks being ignored; it now declines the MCP elicitationFixed
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 to0Changed
applyFlagSettings({ ultracode: true })to keep the current effort level instead of switching toxhigh; aneffortLevelthat changes the level withoutultracodeturns Ultracode offUpdated to parity with Claude Code v2.1.284
Update
npm install @anthropic-ai/claude-agent-sdk@0.3.284 # or yarn add @anthropic-ai/claude-agent-sdk@0.3.284 # or pnpm add @anthropic-ai/claude-agent-sdk@0.3.284 # or bun add @anthropic-ai/claude-agent-sdk@0.3.284
0.3.283
25 Sep 2026Added
plugin_errorsto theSDKSystemMessagetype (system/init), includingpathfor a--plugin-direntry that did not loadFixed
getSessionMessages()returning, andforkSession()copying, a rewound-away branch when the newest branch ends at a meta row or a local command's rowsChanged stream-json output to include warnings and notices raised during a turn as
system/informationalmessages; it previously dropped them
What's changed
Added
plugin_errorsto theSDKSystemMessagetype (system/init), includingpathfor a--plugin-direntry that did not loadFixed
getSessionMessages()returning, andforkSession()copying, a rewound-away branch when the newest branch ends at a meta row or a local command's rowsChanged stream-json output to include warnings and notices raised during a turn as
system/informationalmessages; it previously dropped themChanged the
set_max_thinking_tokenscontrol request: omittingmax_thinking_tokensnow leaves the session's thinking budget unchanged; sendnullto reset it to the session defaultUpdated to parity with Claude Code v2.1.283
Update
npm install @anthropic-ai/claude-agent-sdk@0.3.283 # or yarn add @anthropic-ai/claude-agent-sdk@0.3.283 # or pnpm add @anthropic-ai/claude-agent-sdk@0.3.283 # or bun add @anthropic-ai/claude-agent-sdk@0.3.283
0.3.282
24 Sep 2026Added support for
strictKnownMarketplacesandblockedMarketplacesin host-suppliedmanagedSettings: the allowlist applies only where admin policy sets none; the blocklist adds to the admin'sAdded
@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 SDKAdded
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
What's changed
Added support for
strictKnownMarketplacesandblockedMarketplacesin host-suppliedmanagedSettings: the allowlist applies only where admin policy sets none; the blocklist adds to the admin'sAdded
@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 SDKAdded
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 laterFixed
readMcpResource()relaying content_metakeys under the CLI-reservedcom.anthropic/prefix; they are now dropped, as for tool resultsUpdated to parity with Claude Code v2.1.282
Update
npm install @anthropic-ai/claude-agent-sdk@0.3.282 # or yarn add @anthropic-ai/claude-agent-sdk@0.3.282 # or pnpm add @anthropic-ai/claude-agent-sdk@0.3.282 # or bun add @anthropic-ai/claude-agent-sdk@0.3.282
0.3.281
23 Sep 2026Added 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 happenedFixed 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
What's changed
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 happenedFixed 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 answeredImproved 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 themImproved 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 narrowUpdated to parity with Claude Code v2.1.281
Update
npm install @anthropic-ai/claude-agent-sdk@0.3.281 # or yarn add @anthropic-ai/claude-agent-sdk@0.3.281 # or pnpm add @anthropic-ai/claude-agent-sdk@0.3.281 # or bun add @anthropic-ai/claude-agent-sdk@0.3.281
0.3.280
22 Sep 2026Added 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=1Added
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
What's changed
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=1Added
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://resourceAdded
readMcpResource()(alpha) to read an MCP Appsui://resource from an MCP server that Claude Code connectedImproved
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 turnImproved 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 waitsChanged
session_state_changedevents (CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS=1) to reportrequires_actionwhile an MCP elicitation waits on the user, as for permission promptsChanged headless sessions to cancel an MCP server's pending form question when the tool call that drew it ends
Updated to parity with Claude Code v2.1.280
Update
npm install @anthropic-ai/claude-agent-sdk@0.3.280 # or yarn add @anthropic-ai/claude-agent-sdk@0.3.280 # or pnpm add @anthropic-ai/claude-agent-sdk@0.3.280 # or bun add @anthropic-ai/claude-agent-sdk@0.3.280
0.3.278
19 Sep 2026Updated to parity with Claude Code v2.1.278
0.3.277
18 Sep 2026Added an optional
builtinfield toSlashCommand, set when a command is built into Claude CodeAdded
pasted_contenttoSDKUserMessage: text the user pasted rather than typed, appended after the typed promptAdded 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
What's changed
Added an optional
builtinfield toSlashCommand, set when a command is built into Claude CodeAdded
pasted_contenttoSDKUserMessage: text the user pasted rather than typed, appended after the typed promptAdded 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 messageAdded
'userSettings'as anupdateSettings()source, accepting onlyeffortLevel, which is saved for the session's current model as/effortsaves itFixed 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 failingUpdated to parity with Claude Code v2.1.277
Update
npm install @anthropic-ai/claude-agent-sdk@0.3.277 # or yarn add @anthropic-ai/claude-agent-sdk@0.3.277 # or pnpm add @anthropic-ai/claude-agent-sdk@0.3.277 # or bun add @anthropic-ai/claude-agent-sdk@0.3.277
0.3.276
18 Sep 2026Updated to parity with Claude Code v2.1.276
A whole project to check? Paste its package.json in the dependency check: every deprecated, outdated or vulnerable dependency, with what to upgrade to. Free, no account.