NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
npm
npm, #3768 most downloaded on npm
SDK for building AI agents with Claude Code's capabilities. Programmatically interact with Claude to build autonomous agents that can understand codebases, edit files, and execute workflows.
Latest stable
0.3.325
Last release 9 days ago
13 Nov 2026
Ships on a steady schedule
a new release about every 8 days
Nearly every release is documented
notes for 60 of the last 60 stable releases
Nothing withdrawn
no release was ever pulled
1 years old
345 releases · first in 2025
Drag across the ruler to compare, or tap a release to open it.
Added archiveSession() and unarchiveSession() , and an archived field on the sessions that listSessions() and getSessionInfo() return
archiveSession() and unarchiveSession(), and an archived field on the sessions that listSessions() and getSessionInfo() returnrefuseIfBusy to Query.reloadPlugins() so a host can have a reload refused while the session is busymanaged_lock to plugin_errors entries on system/init, naming the managed enabledPlugins entry that dropped a plugin copysystem/informational warning, tagged hook_no_verdict, when a PreToolUse hook can't run or answer, or times out, without refusing its tool callinvalid_config_file to the config_file_invalid startup failure result: the broken config file's path and its backup's path as fieldsdisallowedTools, 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 and system/initsupportedEffortLevels in model info listing effort levels above the organization's effort cap or the maxEffortLevel settingsandbox option: sandboxed Bash commands are no longer auto-approved unless autoAllowBashIfSandboxed: true is setapplyFlagSettings() to reject when a value would make Claude Code discard its settings layer, applying nothing and keeping settings from earlier callssuggestions on canUseTool for Bash and Monitor: a list of rules alone is sent only when saving it would allow that commandProposeSkillsInput type: a proposal can carry edits, and skillMd is optionalnpm 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.325Your coding agent can read these notes before it upgrades. Set up the MCP server →
Updated to parity with Claude Code v2.1.324
Added machinePolicy.didNotLoad (alpha) to resolveSettings() 's result, which tells a host when a machine policy source may be there and did not load
machinePolicy.didNotLoad (alpha) to resolveSettings()'s result, which tells a host when a machine policy source may be there and did not loadmatchDeniedModels() (alpha), which tells a host which models a deniedModels list blocks, by Claude Code's own entry rulestool_progress heartbeat while a turn waits on long-running hooks; tool_name is the hook event, tool_use_id begins hook-, parent_tool_use_id may name no tool callCLAUDE_CODE_DISABLE_AGENT_PROGRESS_SUMMARIES: set to 1 to turn off subagent progress summaries even when agentProgressSummaries is true (available since 0.3.318)tool_use_result to a subagent's WebSearch result message when the search did not run or found nothingresolveSettings() 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 failedforkSession() with upToMessageId: forking at a compaction summary no longer brings back the messages kept after it, and forking at a compaction boundary keeps the conversation before itgetSessionMessages leaving out a queued prompt that directly follows a compaction summarycanUseTool suggestions including a Bash allow rule for commands that write to sensitive paths such as .git or .claude, where the rule did not stop the next requestinitialize options, such as agents and skills, being ignored when a SessionStart hook supplied the first messagesetMcpServers() staying needs-auth with no tools when a tool call had tried to reach it in betweeninit.plugin_errors omitting a plugin that only project settings enable but that isn't installed; it now reports it as not installed, with the install commandinit.plugin_errors to 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=1 waits)supersedes on assistant messages to also be sent after a response whose tool call could not be parsedPreToolUse hook allowed the call: it now goes to canUseTool, or is refused when there is no callbacknpm 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.323Updated to parity with Claude Code v2.1.322
npm install @anthropic-ai/claude-agent-sdk@0.3.322
# or
yarn add @anthropic-ai/claude-agent-sdk@0.3.322
# or
pnpm add @anthropic-ai/claude-agent-sdk@0.3.322
# or
bun add @anthropic-ai/claude-agent-sdk@0.3.322Fixed canUseTool getting the app's own PreToolUse hook reason in decisionReason when another hook also asked
canUseTool getting the app's own PreToolUse hook reason in decisionReason when another hook also askedask being lost when another hook's defer finished first and could not be honoredhooks option is set to undefinedWarmQuery.query() with a string prompt hanging after startup() with resume when the resumed session finished a turn of its own before the prompt was sentsetMcpServers closing a folder's .mcp.json or local-scope MCP server when passed an in-process server of the same name, in sessions bound with SpareProcess.claim()reloadSkills(), reloadPlugins() and system/init dropping project skills, commands or agents that a worktree lacks after Claude entered itimportSessionToStore() never rejecting, when memory ran out while a transcript was being readresume and continue on the bundled Claude Code binary: initialize is read during boot, so start-up work is less likely to run before your hooks are registeredresult with num_turns: 0claude-in-chrome to follow the organization's Claude in Chrome policy: where the policy denies it, the server is not connectednpm 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.321Added MCP task support in SDK sessions (not on Bedrock, Vertex or Foundry): with CLAUDE_AUTO_BACKGROUND_TASKS=1 and streaming input, an MCP task runs
CLAUDE_AUTO_BACKGROUND_TASKS=1 and streaming input, an MCP task runs in the background with task_type "mcp_task"claude_code.session.count metric counting prewarm() processes that were never claimed; a pre-started process now counts once, when SpareProcess.claim() succeedssession_writes_lost listing the wrong session in transcript_session_ids after /clear in a session resumed from a transcript file outside the projects folderdeleteSession() to reject with ENOTEMPTY if the session's folder could not be fully deletedsession_writes_lost to be sent only when the CLI exits 0; a run that ends on an error result now gets only the stderr linenpm 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.319Added an optional credential_expires_at field to result messages: when the stored claude.ai sign-in in use ends
credential_expires_at field to result messages: when the stored claude.ai sign-in in use endsconfig_file_invalid startup failure reason, reported when a configuration file read at startup isn't valid JSONcancel_queued, and stopped at start-up as a queued message isagentProgressSummaries: 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 firststatus in PushNotificationInput to optionalnpm 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.318Added onFailure to hook matchers: with "block" , a hook that throws or returns invalid output blocks the action
onFailure to hook matchers: with "block", a hook that throws or returns invalid output blocks the actionsession_writes_lost system message, sent after the last result when a full disk or disk quota kept the CLI from saving the session transcript or ~/.claude.jsoninitialize_not_first to startup_failure_reason, for a --await-initialize launch whose first stdin line is not the initialize requesttask.description to the TaskCreate tool's tool_use_result: the description the task was created withlossy to readFile() utf-8 answers: true when decoding replaced bytes that are not valid UTF-8file_unchanged variant of FileReadOutput in sdk-tools.d.ts; a repeated Read now returns the file contentsetMcpServers closing a folder's .mcp.json and local-scope MCP servers in sessions started with prewarm() and bound with SpareProcess.claim()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.317Added permissions.blockReadsExemptPaths to the Settings type: paths, read only from --settings and settings the host sends, that blockReadsOutsideWork
permissions.blockReadsExemptPaths to the Settings type: paths, read only from --settings and settings the host sends, that blockReadsOutsideWorkingDirectories lets through without making them working directoriesnpm install @anthropic-ai/claude-agent-sdk@0.3.316
# or
yarn add @anthropic-ai/claude-agent-sdk@0.3.316
# or
pnpm add @anthropic-ai/claude-agent-sdk@0.3.316
# or
bun add @anthropic-ai/claude-agent-sdk@0.3.316Updated to parity with Claude Code v2.1.315
Added sandbox_required_unavailable to startup_failure_reason , for the result Claude Code writes when a required sandbox cannot run
sandbox_required_unavailable to startup_failure_reason, for the result Claude Code writes when a required sandbox cannot runpermissions.blockWritesOutsideWorkingDirectories to the Settings typeprewarm() (alpha) to the @anthropic-ai/claude-agent-sdk/core entry pointsettingSources still supplying some settings, such as auto mode rules and saved permission consentsnpm 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.314Added autoMode , skipAutoPermissionPrompt , useAutoModeDuringPlan and permissions.disableAutoMode to the Settings type
autoMode, skipAutoPermissionPrompt, useAutoModeDuringPlan and permissions.disableAutoMode to the Settings typeunanswered (skipped, replied_in_chat or dismissed) to AskUserQuestion answers' per-question annotations; send it only when system/init lists the ask_user_question_unanswered_v1 capabilityresolveSettings() returning mistyped managed auto-mode settings, such as permissions.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 CLInpm 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.312Added cacheCreationEphemeral5mInputTokens and cacheCreationEphemeral1hInputTokens to ModelUsage, splitting cacheCreationInputTokens by cache lifetime
cacheCreationEphemeral5mInputTokens and cacheCreationEphemeral1hInputTokens to ModelUsage, splitting cacheCreationInputTokens by cache lifetimenpm 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
Updated to parity with Claude Code v2.1.310
npm install @anthropic-ai/claude-agent-sdk@0.3.310
# or
yarn add @anthropic-ai/claude-agent-sdk@0.3.310
# or
pnpm add @anthropic-ai/claude-agent-sdk@0.3.310
# or
bun add @anthropic-ai/claude-agent-sdk@0.3.310
Fixed host-supplied managedSettings dropping disableAllHooks, disableSkillShellExecution and empty allowedHttpHookUrls / httpHookAllowedEnvVars lists
managedSettings dropping disableAllHooks, disableSkillShellExecution and empty allowedHttpHookUrls / httpHookAllowedEnvVars listsextractFromBunfs() to extract the embedded CLI into its own per-user temp directory (claude-agent-sdk-<uid>, or claude-agent-sdk on Windows) instead of Claude Code's temp rootextractFromBunfs() to reuse an already-extracted file only when its bytes match the embedded binary, replacing it otherwisenpm 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
Updated to parity with Claude Code v2.1.308
npm install @anthropic-ai/claude-agent-sdk@0.3.308
# or
yarn add @anthropic-ai/claude-agent-sdk@0.3.308
# or
pnpm add @anthropic-ai/claude-agent-sdk@0.3.308
# or
bun add @anthropic-ai/claude-agent-sdk@0.3.308
Added wakeup_source to the command_lifecycle started frame of a scheduled wakeup or task, and scheduled_for for a wakeup (capability lifecycle_wakeup_
wakeup_source to the command_lifecycle started frame of a scheduled wakeup or task, and scheduled_for for a wakeup (capability lifecycle_wakeup_source_v1), so a host can tell which one firedsupportedDialogKinds to browser SDK query(), sent on initialize; a non-empty list requires onUserDialognpm install @anthropic-ai/claude-agent-sdk@0.3.307
# or
yarn add @anthropic-ai/claude-agent-sdk@0.3.307
# or
pnpm add @anthropic-ai/claude-agent-sdk@0.3.307
# or
bun add @anthropic-ai/claude-agent-sdk@0.3.307
Updated to parity with Claude Code v2.1.306
npm install @anthropic-ai/claude-agent-sdk@0.3.306
# or
yarn add @anthropic-ai/claude-agent-sdk@0.3.306
# or
pnpm add @anthropic-ai/claude-agent-sdk@0.3.306
# or
bun add @anthropic-ai/claude-agent-sdk@0.3.306
Added recommendations and fix to the get_usage response's behavior windows
recommendations and fix to the get_usage response's behavior windowssetMcpServers being replaced later in the session by a same-named server from the user's own settingsstartup() with initializeTimeoutMs: null counting time spent in SessionStart or Setup hooks against its 60-second limit; null now works like leaving the option outstartup() and prewarm() timeout error for a start with no open SessionStart or Setup hook: it lists possible causes and no longer says to check authentication and networknpm 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
Added suspendSseStream(query) and resumeSseStream(query) to the browser SDK: close a query's event stream and reopen it later without ending the query
suspendSseStream(query) and resumeSseStream(query) to the browser SDK: close a query's event stream and reopen it later without ending the querygetContextUsage(), and, when the CLI answers on its own stdio, plugin ids, agent and skill file paths, and per-server MCP instruction token sharesstartup() timing out while a SessionStart or Setup command hook was running when no initializeTimeoutMs is 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 reportedstartup() keeping every hook_progress message of a running SessionStart or Setup hook in memory until it resolved; it now keeps only the newest one for each hooknpm 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
Updated to parity with Claude Code v2.1.303
npm install @anthropic-ai/claude-agent-sdk@0.3.303
# or
yarn add @anthropic-ai/claude-agent-sdk@0.3.303
# or
pnpm add @anthropic-ai/claude-agent-sdk@0.3.303
# or
bun add @anthropic-ai/claude-agent-sdk@0.3.303
Fixed structured output results delivering a response's output as structured_output when the API refused that response; the result is now an error wit
structured_output when the API refused that response; the result is now an error with no payloadpermissionMode to start in default mode on third-party providers, with telemetry off or on a fresh install; pass permissionMode: 'auto' to keep auto modesubagent_type: "fork") to be on by default in SDK sessions, as in the terminal; run_in_background is still offered, and CLAUDE_CODE_FORK_SUBAGENT=0 turns them offnpm 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
Added per-tool permission policies to sdk-type MCP server configs: tools entries with permission_policy always_ask or always_deny, applied on initiali
tools entries with permission_policy always_ask or always_deny, applied on initialize and setMcpServers()BUILTIN_TOOL_NAMES and LEGACY_TOOL_NAME_ALIASES exports: the public built-in tool names and their earlier names, for checking permission rules and tool settingsaddPlugins to Query.reloadPlugins() so a host can load more plugin folders into a running sessionsetModel() 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 limiterror is now invalid_request, not authentication_failed, and api_error_status is null, not 401mcpServerStatus() to still report a tool's _meta.ui.visibility when the rest of its _meta.ui fails validationnpm 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
Fixed importSessionToStore skipping transcript rows that contain a Unicode line or paragraph separator (U+2028, U+2029) on Node 24 and Bun
importSessionToStore skipping transcript rows that contain a Unicode line or paragraph separator (U+2028, U+2029) on Node 24 and Bunrewind_conversation with interrupt_if_running stopping the running turn before refusing with "unseen later turn"canUseTool options carrying suppressAlwaysAllowRule: true for connector tools that an organization set to require approval (added in 0.3.292)@anthropic-ai/claude-agent-sdk/browser): 40% smaller to download, by no longer bundling a Node crypto polyfillthinking: { type: 'disabled' } and maxThinkingTokens: 0 to run as adaptive thinking on models that can't turn thinking offupdatedInput from PreToolUse and PermissionRequest hook callbacks: it is now validated like Claude's own input and unknown keys are dropped; canUseTool is unchangednpm 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
Added an optional nextFireAt (epoch ms of the next run) to the CronCreate and CronList tool outputs
nextFireAt (epoch ms of the next run) to the CronCreate and CronList tool outputsproperty_order to the elicitation control request: a form's field names in the order the MCP server listed them, for hosts whose transport keeps no JSON object key orderrewind_conversation answering "target not found" for a message stopped during its prompt hooks or plugins: until a reply or input follows, it answers rewound: true with a null prefillTextconstructor or toString being silently dropped when a prewarm() process is claimed with SpareProcess.claim()origin.body on a user message that merges several queued peer messages (from other sessions or agents) carrying only the first message's text; it is now omittedinitialize, mcp_set_servers and claim_session to refuse the reserved MCP server names __proto__, __defineGetter__, __defineSetter__, __lookupGetter__, __lookupSetter__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
Added claude_code_version to the initialize control response so clients know the CLI version before the first turn
claude_code_version to the initialize control response so clients know the CLI version before the first turnautoCompactWindow to AgentDefinition, so a subagent can auto-compact earlier than the main conversation's windowsandbox option discarding an inline settings.sandbox block: the two now merge, the option's values win, and deny and credential lists from both sides are combinedupdatedPermissions entries count as a denial, and a malformed list is ignored as a wholenpm 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
Added overageEnabled to SDKRateLimitInfo: on usage-limit warnings, whether the account has extra usage turned on
overageEnabled to SDKRateLimitInfo: on usage-limit warnings, whether the account has extra usage turned onmcp_set_servers sometimes keeping an outdated tool list when another server in the same request connected latercitations in streamed responsestoggleMcpServer()rate_limit_event with status allowed_warning omitting overageStatus, overageResetsAt and overageDisabledReason, which allowed and rejected events already carryupdatedPermissions holds over 4,096 updates, rules and directories to count as a denialtool_result_meta[].non_execution_kind to be absent when a mod withheld the result of a tool that ran without error; it was permission-rulepasted_content on user messages to be ignored when it holds over 1,000 entries and blocks in all--flag=value)tool_use_result for MCP Apps tools: structuredContent or _meta over 8,388,608 JSON characters is left off, and _meta.ui with no ui:// resource no longer lifts the ordinary capstool_use_result for 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 muchtool_use_result for MCP tools: a result _meta over 1,048,576 JSON characters is left off, except for SDK-server tools; so is text blocks' _meta that totals over 65,536npm 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
Updated to parity with Claude Code v2.1.294
npm install @anthropic-ai/claude-agent-sdk@0.3.294
# or
yarn add @anthropic-ai/claude-agent-sdk@0.3.294
# or
pnpm add @anthropic-ai/claude-agent-sdk@0.3.294
# or
bun add @anthropic-ai/claude-agent-sdk@0.3.294
Added an optional subagent_type to background_tasks_changed task entries, so hosts can name each subagent's type without pairing with task_started
subagent_type to background_tasks_changed task entries, so hosts can name each subagent's type without pairing with task_startednpm install @anthropic-ai/claude-agent-sdk@0.3.293
# or
yarn add @anthropic-ai/claude-agent-sdk@0.3.293
# or
pnpm add @anthropic-ai/claude-agent-sdk@0.3.293
# or
bun add @anthropic-ai/claude-agent-sdk@0.3.293
Added agent_id to the assistant and user messages a subagent produces; it equals the task_id on that subagent's task events and stays the same when th
agent_id to the assistant and user messages a subagent produces; it equals the task_id on that subagent's task events and stays the same when the subagent is resumedparent_task_id to task_started events and background_tasks_changed entries, naming the subagent task that launched a taskrun_id to background task events and origin.runId to task notifications, so a host can tell a resumed task's runs apartsections and notes to the ListAgents tool's tool_use_result, so hosts can list agents without parsing its textrecipient_kind to SendMessage tool_use inputs on assistant messages, and their top-level approve is now always a boolean, so hosts no longer infer them from the raw inputReadNotifications tool output: read_at, when the tool read the session's queued notifications, and arrived_at on each notification, when it reached the sessionbackground_tasks_changed for a finishing background task to arrive after that task's task_updated and task_notificationcanUseTool options to carry suppressAlwaysAllowRule: true for connector tools that an organization set to require approval, so hosts can hide their "always allow" choicenpm 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
Updated to parity with Claude Code v2.1.291
npm install @anthropic-ai/claude-agent-sdk@0.3.291
# or
yarn add @anthropic-ai/claude-agent-sdk@0.3.291
# or
pnpm add @anthropic-ai/claude-agent-sdk@0.3.291
# or
bun add @anthropic-ai/claude-agent-sdk@0.3.291
Added an optional offset field to the WebFetch tool input for reading on through long pages
offset field to the WebFetch tool input for reading on through long pages_meta: when the result has one, tool_use_result is now { content, _meta }, as for other MCP toolstoolAliases tools when written with a wildcard (Bash*), a match-all pattern (Bash(**), also on the mapped name), or an input field also in disallowedToolsuuid being replayed (--replay-user-messages) while the first copy still waited for its turn; its replay now comes when a turn takes itincludePartialMessages streams leaving a message without message_stop when the stream was cut, interrupted or fell back to non-streaminguser_message_uuid, user_message_uuids and resume_reason to also be set on a turn a restarted worker resumes from a permission answer or from tool calls still in flightnpm 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
Updated to parity with Claude Code v2.1.289
npm install @anthropic-ai/claude-agent-sdk@0.3.289
# or
yarn add @anthropic-ai/claude-agent-sdk@0.3.289
# or
pnpm add @anthropic-ai/claude-agent-sdk@0.3.289
# or
bun add @anthropic-ai/claude-agent-sdk@0.3.289
Updated to parity with Claude Code v2.1.288
npm install @anthropic-ai/claude-agent-sdk@0.3.288
# or
yarn add @anthropic-ai/claude-agent-sdk@0.3.288
# or
pnpm add @anthropic-ai/claude-agent-sdk@0.3.288
# or
bun add @anthropic-ai/claude-agent-sdk@0.3.288
Added optional remote-session latency fields (first_text_post_queue_wait_ms, first_text_post_queued_behind) to the success result message
first_text_post_queue_wait_ms, first_text_post_queued_behind) to the success result messageincludePartialMessages streams sending a cut-short reply's message_stop late or never, so apps could show the reply as still in progresstoggleMcpServer() disabled the server or setMcpServers() removed itcommands_changed arriving before init, or twice, at session start: the initialize response now includes commands registered at startuptool_use_result for a WebFetch or WebSearch call that steps aside for a priority "now" message to { detachedToolCall: true }; the result follows in a later turntool_use_result for MCP tools: structuredContent over 1,048,576 JSON characters is left off and structuredContentOmitted: true set, except for SDK-server and MCP Apps toolsnpm 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
Added the initialize response field sdk_mcp_manifests_parked and the system/init capabilities sdk_mcp_manifests and sdk_mcp_tools_list_changed
sdk_mcp_manifests_parked and the system/init capabilities sdk_mcp_manifests and sdk_mcp_tools_list_changedtools or allowedToolstoggleMcpServer() not disconnecting, and failing to re-enable, an in-process MCP server created with createSdkMcpServer(), except one named claude-in-chromenow message to move running shell commands, agents and MCP calls to the background and join the running turn instead of stopping itpermissionMode to Claude Code, so a settings defaultMode now applies and, on third-party providers or with telemetry off, the session starts in auto mode like claude -p; pass permissionMode: 'default' for manual approvalsnpm 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
Added an optional read.title (the artifact's stored title) to the Artifact tool's structured read result
read.title (the artifact's stored title) to the Artifact tool's structured read resultprovider_not_allowed to startup_failure_reason and allowedProviders to the Settings typeCLAUDE_CODE_FORK_SUBAGENT=1: a subagent's own Agent call now runs in the foreground, so the subagent gets the child's resultgetSessionMessages() 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 betweentoggleMcpServer(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 connectedrewind_conversation leaving a backgrounded MCP tool call running after the message that started it was removedtimeout to bound a run_in_background command (was ignored; default 30 min, max 2 h); the stopped task notification for a stop at that limit says whygetSubagentMessages() to also return the messages a subagent read while it ran, such as a message sent to it; offset and limit count these rowsnpm 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
Added a renamed skill's directory name to its SlashCommand aliases when the name is plain and Claude Code ships no command by that name
SlashCommand aliases when the name is plain and Claude Code ships no command by that nameapplied.ultracodeAvailable and applied.ultracodeRequested to getSettings(): whether this session can run Ultracode, and whether it is requested, independent of whether it is in effectforkSession() 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 keptgetSessionMessages() leaving out messages from other agents, sessions and channels that the CLI transcript shows{ decision: 'block' } returned by Elicitation and ElicitationResult hook callbacks being ignored; it now declines the MCP elicitationquery() closing stdin before a follow-up turn woken by a finished background agent, which failed that turn's hooks, canUseTool and SDK MCP calls with "Stream closed"allowedTools or by an mcp_tool hook, even with CLAUDE_CODE_MCP_STARTUP_WAIT_MS set to 0applyFlagSettings({ ultracode: true }) to keep the current effort level instead of switching to xhigh; an effortLevel that changes the level without ultracode turns Ultracode offnpm 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
Added plugin_errors to the SDKSystemMessage type (system/init), including path for a --plugin-dir entry that did not load
plugin_errors to the SDKSystemMessage type (system/init), including path for a --plugin-dir entry that did not loadgetSessionMessages() returning, and forkSession() copying, a rewound-away branch when the newest branch ends at a meta row or a local command's rowssystem/informational messages; it previously dropped themset_max_thinking_tokens control request: omitting max_thinking_tokens now leaves the session's thinking budget unchanged; send null to reset it to the session defaultnpm 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
Added support for strictKnownMarketplaces and blockedMarketplaces in host-supplied managedSettings: the allowlist applies only where admin policy sets
strictKnownMarketplaces and blockedMarketplaces in host-supplied managedSettings: the allowlist applies only where admin policy sets none; the blocklist adds to the admin's@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 SDKprewarm() and SpareProcess.claim() (alpha): start a Claude Code process before its session is known and bind it to a folder and its per-session options laterreadMcpResource() relaying content _meta keys under the CLI-reserved com.anthropic/ prefix; they are now dropped, as for tool resultsnpm 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
Added optional trigger, user_message_uuid and timestamp fields to the conversation_reset message so clients can tell what reset the conversation, matc
trigger, user_message_uuid and timestamp fields to the conversation_reset message so clients can tell what reset the conversation, match a /clear to its message, and show when the reset happenedclose()session_state_changed staying at requires_action after an overlapping permission prompt and sandbox network-access prompt were both answeredsdk.mjs no longer bundles unused dependencies (1.47 MB → 0.97 MB)query() sessions with in-process MCP servers (createSdkMcpServer) by running their handshake inside the SDK; initialize may now wait up to 250 ms for themSettings type's attribution field to boolean | {...}; TypeScript code that reads attribution.commit from returned settings needs a type narrownpm 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
Added optional fireReason to the task-notification SDKMessageOrigin; a local host's declared scheduled-task fire is honored only in a process it start
fireReason to the task-notification SDKMessageOrigin; a local host's declared scheduled-task fire is honored only in a process it started with CLAUDE_CODE_HOST_SCHEDULED_RUN=1verbatimPrompts option: prompts are delivered as written — no @path expansion, no slash-command dispatch and, on current CLIs, no ambient attachments with the prompt (Claude Code 2.1.248+)_meta to mcpServerStatus() tool entries, carrying a tool's MCP Apps ui metadata so a host can find its ui:// resourcereadMcpResource() (alpha) to read an MCP Apps ui:// resource from an MCP server that Claude Code connectedaskSideQuestion(): 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 turnCLAUDE_CODE_RETRY_WATCHDOG): a usage-limit wait emits rate_limit_event (rejected, resetsAt) as it begins; api_retry heartbeats continue while sub-agent work waitssession_state_changed events (CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS=1) to report requires_action while an MCP elicitation waits on the user, as for permission promptsnpm 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
Updated to parity with Claude Code v2.1.278
npm install @anthropic-ai/claude-agent-sdk@0.3.278
# or
yarn add @anthropic-ai/claude-agent-sdk@0.3.278
# or
pnpm add @anthropic-ai/claude-agent-sdk@0.3.278
# or
bun add @anthropic-ai/claude-agent-sdk@0.3.278
Added an optional builtin field to SlashCommand, set when a command is built into Claude Code
builtin field to SlashCommand, set when a command is built into Claude Codepasted_content to SDKUserMessage: text the user pasted rather than typed, appended after the typed promptfirst_text_post_ms, first_text_post_wall_ms, first_stream_post_queue_wait_ms, first_stream_post_queued_behind) to the success result message'userSettings' as an updateSettings() source, accepting only effortLevel, which is saved for the session's current model as /effort saves ittotal_cost_usd, modelUsage and get_usage totals starting at zero instead of continuing from the earlier turns (maxBudgetUsd is unchanged)SDKUsageReport usage rows to always carry severity and is_active: the report relays only rows from a live server reply, and none while the usage fetch is failingnpm 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
Updated to parity with Claude Code v2.1.276
npm install @anthropic-ai/claude-agent-sdk@0.3.276
# or
yarn add @anthropic-ai/claude-agent-sdk@0.3.276
# or
pnpm add @anthropic-ai/claude-agent-sdk@0.3.276
# or
bun add @anthropic-ai/claude-agent-sdk@0.3.276
Fixed a deferred tool call's result being emitted with internal keys such as toolUseResult instead of tool_use_result when the tool re-runs at the sta
toolUseResult instead of tool_use_result when the tool re-runs at the start of a resumed turngetSessionMessages() and forkSession() sometimes missing a turn's assistant message when called right after the turn's result messageforkSession({ upToMessageId }) rejecting a client-supplied SDKUserMessage.uuid that is not in UUID formatforkSession rejecting the id that getSessionMessages returns for a message sent while Claude was working, and a fork showing a re-run prompt twicegetSessionMessages() omitting a task notification or other queued message that Claude read while running a tool; it now comes back where Claude read itnpm install @anthropic-ai/claude-agent-sdk@0.3.275
# or
yarn add @anthropic-ai/claude-agent-sdk@0.3.275
# or
pnpm add @anthropic-ai/claude-agent-sdk@0.3.275
# or
bun add @anthropic-ai/claude-agent-sdk@0.3.275
Added startup_failure_reason to the error result a stream-json run writes before exiting on a known startup failure
startup_failure_reason to the error result a stream-json run writes before exiting on a known startup failuremcpServer: {name, source} to canUseTool options, mcp_server to tool hook inputs, and source to MCP server status rows, so hosts can key trust on source === "sdk"CLAUDE_CODE_MCP_STARTUP_WAIT_MS (pass via env) to bound or disable (0) the first-turn wait for connecting MCP serversCLAUDE_CODE_EMIT_STARTUP_TIMING=1 for stream-json hosts: the session's first system/init then carries the per-phase startup_timing breakdown that cloud sessions already emitgetSessionMessages() omitting a message the user sent while Claude was running a tool; it now comes back as a user message where Claude read itorigin: {kind: 'task-notification'} on the replayed user message when a background task finishes during a running turn (--replay-user-messages)options.mcpServers servers are still awaitedresult, all but the last empty with num_turns: 0npm install @anthropic-ai/claude-agent-sdk@0.3.274
# or
yarn add @anthropic-ai/claude-agent-sdk@0.3.274
# or
pnpm add @anthropic-ai/claude-agent-sdk@0.3.274
# or
bun add @anthropic-ai/claude-agent-sdk@0.3.274
Added a usage_report sibling (SDKUsageReport: session totals, the plan's usage rows as the server sends them, extra usage) on the assistant message th
usage_report sibling (SDKUsageReport: session totals, the plan's usage rows as the server sends them, extra usage) on the assistant message that delivers a headless /usage resultreason: "worker_restart" to task_notification messages when a background task was stopped by a worker process restartStop or SessionStart hook callback times out, shown once until the host answers againStop, SubagentStop or SessionStart hook callback that exceeds its timeout being reported as a hook failure and discarding other hooks' decisions; it now counts as no decisionsystem/commands_changed)npm install @anthropic-ai/claude-agent-sdk@0.3.273
# or
yarn add @anthropic-ai/claude-agent-sdk@0.3.273
# or
pnpm add @anthropic-ai/claude-agent-sdk@0.3.273
# or
bun add @anthropic-ai/claude-agent-sdk@0.3.273
Updated to parity with Claude Code v2.1.272
npm install @anthropic-ai/claude-agent-sdk@0.3.272
# or
yarn add @anthropic-ai/claude-agent-sdk@0.3.272
# or
pnpm add @anthropic-ai/claude-agent-sdk@0.3.272
# or
bun add @anthropic-ai/claude-agent-sdk@0.3.272
Added optional omitClaudeMd to AgentDefinition in the agents option, so a subagent can run without user, project and local CLAUDE.md files; managed po
omitClaudeMd to AgentDefinition in the agents option, so a subagent can run without user, project and local CLAUDE.md files; managed policy files still loadlistSessions, getSessionMessages and getSessionInfo with dir on Windows not finding sessions for a directory on a mapped network drive or SUBST drivesessionStore resume losing the global config when it is stored under the legacy .config.json name or an OAuth-suffixed file namepersistent from the MonitorInput tool typenpm install @anthropic-ai/claude-agent-sdk@0.3.271
# or
yarn add @anthropic-ai/claude-agent-sdk@0.3.271
# or
pnpm add @anthropic-ai/claude-agent-sdk@0.3.271
# or
bun add @anthropic-ai/claude-agent-sdk@0.3.271
Updated to parity with Claude Code v2.1.270
npm install @anthropic-ai/claude-agent-sdk@0.3.270
# or
yarn add @anthropic-ai/claude-agent-sdk@0.3.270
# or
pnpm add @anthropic-ai/claude-agent-sdk@0.3.270
# or
bun add @anthropic-ai/claude-agent-sdk@0.3.270
Changed user_message_uuid, user_message_uuids and resume_reason to be stamped on a turn's first complete assistant message as well as its first stream
user_message_uuid, user_message_uuids and resume_reason to be stamped on a turn's first complete assistant message as well as its first stream event when partial messages are onresult.permission_denials omitting Read, Edit and Write calls blocked by a path-scoped deny ruletool_use_id on task_started / task_notification when the CLI resumes a background subagent on its own; they now carry the agent's last call idcanUseTool even when allowDangerouslySkipPermissions is set; the flag now only enables switching to bypassPermissions laternpm install @anthropic-ai/claude-agent-sdk@0.3.269
# or
yarn add @anthropic-ai/claude-agent-sdk@0.3.269
# or
pnpm add @anthropic-ai/claude-agent-sdk@0.3.269
# or
bun add @anthropic-ai/claude-agent-sdk@0.3.269
Added result_index to result messages: the result's position in delivery order within the run, from 0
result_index to result messages: the result's position in delivery order within the run, from 0local_command to the result message of a turn that ran a slash command without entering the model loop, carrying the command's namehold_on_cache_impact to the reload_plugins control request (Query.reloadPlugins({ holdOnCacheImpact: true })): holds a reload that would invalidate the session's prompt cacheresume_reason to assistant, stream-event and result messages, set only on the automatic re-run of a turn a host restart interruptedkind (used, free, buffer, deferred) to each category in the get_context_usage control response, matching the /context result's context_usage rowsdefaultToNo and suppressAlwaysAllowRule hints to canUseTool options: the prompt should open on its decline option, or offer no persistent "always allow" choicesetModel() 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 unrecognizeduser_message_uuid on the automatic re-run of an interrupted turn to name that turn's last user promptinitialize success response to always include pending_permission_requests (empty when nothing is pending), so clients can tell that apart from an older CLItools/allowedToolsnpm install @anthropic-ai/claude-agent-sdk@0.3.268
# or
yarn add @anthropic-ai/claude-agent-sdk@0.3.268
# or
pnpm add @anthropic-ai/claude-agent-sdk@0.3.268
# or
bun add @anthropic-ai/claude-agent-sdk@0.3.268
Added getCcrEvent(query, message) and getSseLastSequenceNum(query) to the browser SDK's SSE transport, plus fromSequenceNum, onCatchUpTruncated and on
getCcrEvent(query, message) and getSseLastSequenceNum(query) to the browser SDK's SSE transport, plus fromSequenceNum, onCatchUpTruncated and onDeliveryUpdate SSE optionssystemPrompt recording to default on for custom prompts and appends (a mid-session prompt change takes effect at the next compaction); pass snapshot: false to keep per-request renderingnpm install @anthropic-ai/claude-agent-sdk@0.3.267
# or
yarn add @anthropic-ai/claude-agent-sdk@0.3.267
# or
pnpm add @anthropic-ai/claude-agent-sdk@0.3.267
# or
bun add @anthropic-ai/claude-agent-sdk@0.3.267
Updated to parity with Claude Code v2.1.266
npm install @anthropic-ai/claude-agent-sdk@0.3.266
# or
yarn add @anthropic-ai/claude-agent-sdk@0.3.266
# or
pnpm add @anthropic-ai/claude-agent-sdk@0.3.266
# or
bun add @anthropic-ai/claude-agent-sdk@0.3.266
Added user_message_uuid and user_message_uuids to a synthetic turn's first reply and result for a message sent with isSynthetic: true and a uuid, nami
user_message_uuid and user_message_uuids to a synthetic turn's first reply and result for a message sent with isSynthetic: true and a uuid, naming the message that started ituser_message_uuid and user_message_uuids to the first reply and the result of a turn Claude Code started itself, such as a resume, naming the messages you sent that it picked up mid-turnuser_message_uuid missing from the success result of a turn that sent no API request, such as a slash commandcwd option at each new user message; a cd made by the agent now persists across turns, as in the interactive appuser_message_uuid to be set on the first reply after each change of the message a turn is answering, instead of on one reply frame per turnnpm install @anthropic-ai/claude-agent-sdk@0.3.265
# or
yarn add @anthropic-ai/claude-agent-sdk@0.3.265
# or
pnpm add @anthropic-ai/claude-agent-sdk@0.3.265
# or
bun add @anthropic-ai/claude-agent-sdk@0.3.265
Updated to parity with Claude Code v2.1.263
npm install @anthropic-ai/claude-agent-sdk@0.3.263
# or
yarn add @anthropic-ai/claude-agent-sdk@0.3.263
# or
pnpm add @anthropic-ai/claude-agent-sdk@0.3.263
# or
bun add @anthropic-ai/claude-agent-sdk@0.3.263
Added pluginDelivery: 'initialize' to send plugins over stdin so the launch command line no longer grows with the plugin count (fixes Windows start fa
pluginDelivery: 'initialize' to send plugins over stdin so the launch command line no longer grows with the plugin count (fixes Windows start failures with many plugins)query() throwing "Object not disposable" in runtimes without a native Symbol.dispose, such as Node ≤22 vm contexts (Jest's node environment, vitest vmThreads/vmForks) and Node <18.18npm install @anthropic-ai/claude-agent-sdk@0.3.261
# or
yarn add @anthropic-ai/claude-agent-sdk@0.3.261
# or
pnpm add @anthropic-ai/claude-agent-sdk@0.3.261
# or
bun add @anthropic-ai/claude-agent-sdk@0.3.261
Added optional user_message_uuid to thinking_tokens system messages, linking thinking progress to the user message that triggered the turn
user_message_uuid to thinking_tokens system messages, linking thinking progress to the user message that triggered the turnfirst_content_frame_ms, first_stream_post_ms, first_stream_post_ack_ms and first_stream_post_wall_ms fields to the success result message for remote-session latency breakdownsmanagedSettings disableAutoMode: "disable" (either spelling) being dropped by the restrictive-only filter instead of turning auto mode off for the spawned sessionrewindFiles() reporting success when no files could be restored (for example when checkpoint backups are missing); it now failserror_max_structured_output_retries results to append the last StructuredOutput tool error; validation errors now name the offending key, allowed values, and actual length or countrate_limit_event to also re-emit during an exceeded window on repeat 429s (about once per 30 seconds per limit window), so stream consumers can refresh stale rate-limit statenpm install @anthropic-ai/claude-agent-sdk@0.3.260
# or
yarn add @anthropic-ai/claude-agent-sdk@0.3.260
# or
pnpm add @anthropic-ai/claude-agent-sdk@0.3.260
# or
bun add @anthropic-ai/claude-agent-sdk@0.3.260
Added user_message_uuids beside user_message_uuid on a turn's first reply frame and result: every user message the turn answered, so a reply to severa
user_message_uuids beside user_message_uuid on a turn's first reply frame and result: every user message the turn answered, so a reply to several merged messages can be matched to eachpermissionPrompts: 'none' option to auto-deny permission prompts in sessions with nobody to answer them, without disabling auto mode's classifiernpm install @anthropic-ai/claude-agent-sdk@0.3.259
# or
yarn add @anthropic-ai/claude-agent-sdk@0.3.259
# or
pnpm add @anthropic-ai/claude-agent-sdk@0.3.259
# or
bun add @anthropic-ai/claude-agent-sdk@0.3.259
One column per month.