PackageTrack

npm · #3768

@anthropic-ai/claude-agent-sdk

0.3.247anthropics/claude-agent-sdk-typescript ↗

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.

Release timeline

279 releases since 2025
2026

Releases

  1. 0.3.17916 Jun 2026
    Release notes

    What's changed

    • Added optional tool_use_meta sidecar to assistant messages with display-friendly names for tool calls, so SDK consumers can render human-readable labels instead of raw wire names
    • Fixed -p mode exiting before a completed background agent's notification was delivered, causing interim text to ship as the final result
    • Fixed remote (stream-json) sessions appearing busy for the entire duration of a background workflow — the turn result is now emitted at the turn boundary and the session reports idle while background tasks continue

    Update

    npm install @anthropic-ai/[email protected]
# or
yarn add @anthropic-ai/[email protected]
# or
pnpm add @anthropic-ai/[email protected]
# or
bun add @anthropic-ai/[email protected]
    Open source →
    Release notes
    • Added optional tool_use_meta sidecar to assistant messages with display-friendly names for tool calls, so SDK consumers can render human-readable labels instead of raw wire names
    • Fixed -p mode exiting before a completed background agent's notification was delivered, causing interim text to ship as the final result
    • Fixed remote (stream-json) sessions appearing busy for the entire duration of a background workflow — the turn result is now emitted at the turn boundary and the session reports idle while background tasks continue
    Open source →
  2. 0.3.17815 Jun 2026
    Release notes

    What's changed

    • Spawn failures on an existing native binary now explain the likely libc mismatch (musl binary on a glibc host) and suggest options.pathToClaudeCodeExecutable
    • Permission-denied advisory messages now carry typed denial reasons (safetyCheck, asyncAgent), enabling SDK consumers to programmatically match denial causes
    • Fixed UserPromptSubmit hook block feedback not being emitted to the SDK event stream — consumers can now see why a prompt was blocked by a hook instead of a silent hang
    • Remote Control workers now send a worker_shutting_down system message on graceful exit so remote clients can show why the session ended
    • Fixed MCP server-level specs (mcp__server, mcp__server__*) in disallowedTools being silently ignored — they now correctly remove all tools from the named server

    Update

    npm install @anthropic-ai/[email protected]
# or
yarn add @anthropic-ai/[email protected]
# or
pnpm add @anthropic-ai/[email protected]
# or
bun add @anthropic-ai/[email protected]
    Open source →
    Release notes
    • Spawn failures on an existing native binary now explain the likely libc mismatch (musl binary on a glibc host) and suggest options.pathToClaudeCodeExecutable
    • Permission-denied advisory messages now carry typed denial reasons (safetyCheck, asyncAgent), enabling SDK consumers to programmatically match denial causes
    • Fixed UserPromptSubmit hook block feedback not being emitted to the SDK event stream — consumers can now see why a prompt was blocked by a hook instead of a silent hang
    • Remote Control workers now send a worker_shutting_down system message on graceful exit so remote clients can show why the session ended
    • Fixed MCP server-level specs (mcp__server, mcp__server__*) in disallowedTools being silently ignored — they now correctly remove all tools from the named server
    Open source →
  3. 0.3.17713 Jun 2026
    Release notes

    What's changed

    • Updated to parity with Claude Code v2.1.177

    Update

    npm install @anthropic-ai/[email protected]
# or
yarn add @anthropic-ai/[email protected]
# or
pnpm add @anthropic-ai/[email protected]
# or
bun add @anthropic-ai/[email protected]
    Open source →
    Release notes
    • Updated to parity with Claude Code v2.1.177
    Open source →
  4. 0.3.17612 Jun 2026
    Release notes

    What's changed

    • Fixed turn result messages being dropped when multiple turns complete while a background agent or workflow is running
    • Fixed background agent, remote agent, and MCP task state not being restored when resuming a session via the SDK

    Update

    npm install @anthropic-ai/[email protected]
# or
yarn add @anthropic-ai/[email protected]
# or
pnpm add @anthropic-ai/[email protected]
# or
bun add @anthropic-ai/[email protected]
    Open source →
    Release notes
    • Fixed turn result messages being dropped when multiple turns complete while a background agent or workflow is running
    • Fixed background agent, remote agent, and MCP task state not being restored when resuming a session via the SDK
    Open source →
  5. 0.3.17512 Jun 2026
    Release notes

    What's changed

    • Updated to parity with Claude Code v2.1.175

    Update

    npm install @anthropic-ai/[email protected]
# or
yarn add @anthropic-ai/[email protected]
# or
pnpm add @anthropic-ai/[email protected]
# or
bun add @anthropic-ai/[email protected]
    Open source →
    Release notes
    • Updated to parity with Claude Code v2.1.175
    Open source →
  6. 0.3.17411 Jun 2026
    Release notes

    What's changed

    • SDK consumers now receive the system/model_fallback message for all fallback triggers — overloaded, server_error, and last_resort in addition to model_not_found and permission_denied — and the message's trigger field gained the server_error and last_resort values

    Update

    npm install @anthropic-ai/[email protected]
# or
yarn add @anthropic-ai/[email protected]
# or
pnpm add @anthropic-ai/[email protected]
# or
bun add @anthropic-ai/[email protected]
    Open source →
    Release notes
    • SDK consumers now receive the system/model_fallback message for all fallback triggers — overloaded, server_error, and last_resort in addition to model_not_found and permission_denied — and the message's trigger field gained the server_error and last_resort values
    Open source →
  7. 0.3.17311 Jun 2026
    Release notes

    What's changed

    • Updated to parity with Claude Code v2.1.173

    Update

    npm install @anthropic-ai/[email protected]
# or
yarn add @anthropic-ai/[email protected]
# or
pnpm add @anthropic-ai/[email protected]
# or
bun add @anthropic-ai/[email protected]
    Open source →
    Release notes
    • Updated to parity with Claude Code v2.1.173
    Open source →
  8. 0.3.17210 Jun 2026
    Release notes

    What's changed

    • SDK plugins option now accepts skipMcpDiscovery: true per plugin, so a host that manages a plugin's MCP connections itself can load skills/hooks from the plugin path without the engine re-reading its .mcp.json
    • Fixed slash-followed-by-whitespace input (e.g. / add tests) being silently dropped instead of treated as a plain prompt

    Update

    npm install @anthropic-ai/[email protected]
# or
yarn add @anthropic-ai/[email protected]
# or
pnpm add @anthropic-ai/[email protected]
# or
bun add @anthropic-ai/[email protected]
    Open source →
    Release notes
    • SDK plugins option now accepts skipMcpDiscovery: true per plugin, so a host that manages a plugin's MCP connections itself can load skills/hooks from the plugin path without the engine re-reading its .mcp.json
    • Fixed slash-followed-by-whitespace input (e.g. / add tests) being silently dropped instead of treated as a plain prompt
    Open source →
  9. 0.3.1709 Jun 2026
    Release notes

    What's changed

    • Added claude-fable-5 model and the fable alias to SDK model types. https://www.anthropic.com/news/claude-fable-5-mythos-5
    • Updated to parity with Claude Code v2.1.170

    Update

    npm install @anthropic-ai/[email protected]
# or
yarn add @anthropic-ai/[email protected]
# or
pnpm add @anthropic-ai/[email protected]
# or
bun add @anthropic-ai/[email protected]
    Open source →
    Release notes
    • Added claude-fable-5 model and the fable alias to SDK model types. https://www.anthropic.com/news/claude-fable-5-mythos-5
    • Updated to parity with Claude Code v2.1.170
    Open source →
  10. 0.3.1698 Jun 2026
    Release notes

    What's changed

    • Added an experimental usage_EXPERIMENTAL_MAY_CHANGE_DO_NOT_RELY_ON_THIS_API_YET() method on Query returning structured session cost, plan rate-limit, and local usage-behaviors data
    • Added an sse option (SSEOptions) to BrowserQueryOptions as an alternative to websocket, for browser SDK consumers who prefer Server-Sent Events

    Update

    npm install @anthropic-ai/[email protected]
# or
yarn add @anthropic-ai/[email protected]
# or
pnpm add @anthropic-ai/[email protected]
# or
bun add @anthropic-ai/[email protected]
    Open source →
    Release notes
    • Added an experimental usage_EXPERIMENTAL_MAY_CHANGE_DO_NOT_RELY_ON_THIS_API_YET() method on Query returning structured session cost, plan rate-limit, and local usage-behaviors data
    • Added an sse option (SSEOptions) to BrowserQueryOptions as an alternative to websocket, for browser SDK consumers who prefer Server-Sent Events
    Open source →
  11. 0.3.1686 Jun 2026
    Release notes

    What's changed

    • Updated to parity with Claude Code v2.1.168

    Update

    npm install @anthropic-ai/[email protected]
# or
yarn add @anthropic-ai/[email protected]
# or
pnpm add @anthropic-ai/[email protected]
# or
bun add @anthropic-ai/[email protected]
    Open source →
    Release notes
    • Updated to parity with Claude Code v2.1.168
    Open source →
  12. 0.3.1676 Jun 2026
    Release notes

    What's changed

    • Updated to parity with Claude Code v2.1.167

    Update

    npm install @anthropic-ai/[email protected]
# or
yarn add @anthropic-ai/[email protected]
# or
pnpm add @anthropic-ai/[email protected]
# or
bun add @anthropic-ai/[email protected]
    Open source →
    Release notes
    • Updated to parity with Claude Code v2.1.167
    Open source →
  13. 0.3.1665 Jun 2026
    Release notes

    What's changed

    • Fixed MCP resource tools not being injected for servers added at runtime via the mcp_set_servers control request

    Update

    npm install @anthropic-ai/[email protected]
# or
yarn add @anthropic-ai/[email protected]
# or
pnpm add @anthropic-ai/[email protected]
# or
bun add @anthropic-ai/[email protected]
    Open source →
    Release notes
    • Fixed MCP resource tools not being injected for servers added at runtime via the mcp_set_servers control request
    Open source →
  14. 0.3.1655 Jun 2026
    Release notes

    What's changed

    • Updated to parity with Claude Code v2.1.165

    Update

    npm install @anthropic-ai/[email protected]
# or
yarn add @anthropic-ai/[email protected]
# or
pnpm add @anthropic-ai/[email protected]
# or
bun add @anthropic-ai/[email protected]
    Open source →
    Release notes
    • Updated to parity with Claude Code v2.1.165
    Open source →
  15. 0.3.1634 Jun 2026
    Release notes

    What's changed

    • stop_task control requests now return success when the target task is already gone (not_found or not_running), so SDK clients can reliably prune stale task chips
    • Fixed SDK hosts being unable to add builtin MCP servers (e.g. claude-in-chrome) via setMcpServers when the CLI was launched without them
    • Stop and SubagentStop hook events now support additionalContext in hookSpecificOutput, enabling non-error feedback that continues the turn

    Update

    npm install @anthropic-ai/[email protected]
# or
yarn add @anthropic-ai/[email protected]
# or
pnpm add @anthropic-ai/[email protected]
# or
bun add @anthropic-ai/[email protected]
    Open source →
    Release notes
    • stop_task control requests now return success when the target task is already gone (not_found or not_running), so SDK clients can reliably prune stale task chips
    • Fixed SDK hosts being unable to add builtin MCP servers (e.g. claude-in-chrome) via setMcpServers when the CLI was launched without them
    • Stop and SubagentStop hook events now support additionalContext in hookSpecificOutput, enabling non-error feedback that continues the turn
    Open source →
  16. 0.3.1623 Jun 2026
    Release notes

    What's changed

    • Refusal error messages now carry stop_reason: "refusal" and stop_details on the assistant message and in session transcripts, so SDK consumers can detect refusals without text-matching the error content
    • Agent SDK sessions on native builds now default to fast embedded find/grep search in Bash, matching the interactive CLI, instead of always registering the dedicated Grep/Glob tools. To keep the dedicated tools (e.g. to intercept searches via canUseTool or hooks), name them in the tools option or reference them in allowedTools

    Update

    npm install @anthropic-ai/[email protected]
# or
yarn add @anthropic-ai/[email protected]
# or
pnpm add @anthropic-ai/[email protected]
# or
bun add @anthropic-ai/[email protected]
    Open source →
    Release notes
    • Refusal error messages now carry stop_reason: "refusal" and stop_details on the assistant message and in session transcripts, so SDK consumers can detect refusals without text-matching the error content
    • Agent SDK sessions on native builds now default to fast embedded find/grep search in Bash, matching the interactive CLI, instead of always registering the dedicated Grep/Glob tools. To keep the dedicated tools (e.g. to intercept searches via canUseTool or hooks), name them in the tools option or reference them in allowedTools
    Open source →
  17. 0.3.1612 Jun 2026
    Release notes

    What's changed

    • The initialize control request is now idempotent: a second initialize returns the same success payload instead of an Already initialized error. ControlResponse gains an optional pending_permission_requests field, mirroring ControlErrorResponse
    • applyFlagSettings now live-applies agent changes: switching the active agent (or passing null to reset) takes effect on the next turn in a running session

    Update

    npm install @anthropic-ai/[email protected]
# or
yarn add @anthropic-ai/[email protected]
# or
pnpm add @anthropic-ai/[email protected]
# or
bun add @anthropic-ai/[email protected]
    Open source →
    Release notes
    • The initialize control request is now idempotent: a second initialize returns the same success payload instead of an Already initialized error. ControlResponse gains an optional pending_permission_requests field, mirroring ControlErrorResponse
    • applyFlagSettings now live-applies agent changes: switching the active agent (or passing null to reset) takes effect on the next turn in a running session
    Open source →
  18. 0.3.1601 Jun 2026
    Release notes

    What's changed

    • Fixed SDK hook callbacks swallowing abort signals: aborting during a PostToolUse hook now ends the turn with a final result message instead of hanging the calling process

    Update

    npm install @anthropic-ai/[email protected]
# or
yarn add @anthropic-ai/[email protected]
# or
pnpm add @anthropic-ai/[email protected]
# or
bun add @anthropic-ai/[email protected]
    Open source →
    Release notes
    • Fixed SDK hook callbacks swallowing abort signals: aborting during a PostToolUse hook now ends the turn with a final result message instead of hanging the calling process
    Open source →
  19. 0.3.15931 May 2026
    Release notes

    What's changed

    • Updated to parity with Claude Code v2.1.159

    Update

    npm install @anthropic-ai/[email protected]
# or
yarn add @anthropic-ai/[email protected]
# or
pnpm add @anthropic-ai/[email protected]
# or
bun add @anthropic-ai/[email protected]
    Open source →
    Release notes
    • Updated to parity with Claude Code v2.1.159
    Open source →
  20. 0.3.15830 May 2026
    Release notes

    What's changed

    • Updated to parity with Claude Code v2.1.158

    Update

    npm install @anthropic-ai/[email protected]
# or
yarn add @anthropic-ai/[email protected]
# or
pnpm add @anthropic-ai/[email protected]
# or
bun add @anthropic-ai/[email protected]
    Open source →
    Release notes
    • Updated to parity with Claude Code v2.1.158
    Open source →
  21. 0.3.15729 May 2026
    Release notes

    What's changed

    • Updated to parity with Claude Code v2.1.157

    Update

    npm install @anthropic-ai/[email protected]
# or
yarn add @anthropic-ai/[email protected]
# or
pnpm add @anthropic-ai/[email protected]
# or
bun add @anthropic-ai/[email protected]
    Open source →
    Release notes
    • Updated to parity with Claude Code v2.1.157
    Open source →
  22. 0.3.15628 May 2026
    Release notes

    What's changed

    • Updated to parity with Claude Code v2.1.156

    Update

    npm install @anthropic-ai/[email protected]
# or
yarn add @anthropic-ai/[email protected]
# or
pnpm add @anthropic-ai/[email protected]
# or
bun add @anthropic-ai/[email protected]
    Open source →
    Release notes
    • Updated to parity with Claude Code v2.1.156
    Open source →
  23. 0.3.15428 May 2026
    Release notes

    What's changed

    • Fixed stdio MCP servers being incorrectly restarted on every reconcile pass due to config-equality false positives

    Update

    npm install @anthropic-ai/[email protected]
# or
yarn add @anthropic-ai/[email protected]
# or
pnpm add @anthropic-ai/[email protected]
# or
bun add @anthropic-ai/[email protected]
    Open source →
    Release notes
    • Fixed stdio MCP servers being incorrectly restarted on every reconcile pass due to config-equality false positives
    Open source →
  24. 0.3.15327 May 2026
    Release notes

    What's changed

    • Updated to parity with Claude Code v2.1.153

    Update

    npm install @anthropic-ai/[email protected]
# or
yarn add @anthropic-ai/[email protected]
# or
pnpm add @anthropic-ai/[email protected]
# or
bun add @anthropic-ai/[email protected]
    Open source →
    Release notes
    • Updated to parity with Claude Code v2.1.153
    Open source →
  25. 0.3.15226 May 2026
    Release notes

    What's changed

    • SessionStart hooks can now return reloadSkills: true to trigger a skill re-scan, and set the session title via hookSpecificOutput.sessionTitle
    • Added a MessageDisplay hook event that lets hooks transform or hide assistant message text as it is displayed

    Update

    npm install @anthropic-ai/[email protected]
# or
yarn add @anthropic-ai/[email protected]
# or
pnpm add @anthropic-ai/[email protected]
# or
bun add @anthropic-ai/[email protected]
    Open source →
    Release notes
    • SessionStart hooks can now return reloadSkills: true to trigger a skill re-scan, and set the session title via hookSpecificOutput.sessionTitle
    • Added a MessageDisplay hook event that lets hooks transform or hide assistant message text as it is displayed
    Open source →
  26. 0.3.15023 May 2026
    Release notes

    What's changed

    • Updated to parity with Claude Code v2.1.150

    Update

    npm install @anthropic-ai/[email protected]
# or
yarn add @anthropic-ai/[email protected]
# or
pnpm add @anthropic-ai/[email protected]
# or
bun add @anthropic-ai/[email protected]
    Open source →
    Release notes
    • The api_retry system message now reports error: 'overloaded' for 529 responses, instead of 'rate_limit' (which is now reserved for 429). Consumers that handled 529 via error === 'rate_limit' should also match 'overloaded', or switch to error_status === 529.
    • Updated to parity with Claude Code v2.1.150
    Open source →
  27. 0.3.14922 May 2026
    Release notes

    What's changed

    • Fixed options.env dropping CLAUDE_AGENT_SDK_VERSION (used for User-Agent and telemetry) when a custom environment is supplied, and corrected the Options.env docs to state that the value replaces the subprocess environment rather than merging with process.env

    Update

    npm install @anthropic-ai/[email protected]
# or
yarn add @anthropic-ai/[email protected]
# or
pnpm add @anthropic-ai/[email protected]
# or
bun add @anthropic-ai/[email protected]
    Open source →
    Release notes
    • Fixed options.env dropping CLAUDE_AGENT_SDK_VERSION (used for User-Agent and telemetry) when a custom environment is supplied, and corrected the Options.env docs to state that the value replaces the subprocess environment rather than merging with process.env
    Open source →
  28. 0.3.14822 May 2026
    Release notes

    What's changed

    • Updated to parity with Claude Code v2.1.148

    Update

    npm install @anthropic-ai/[email protected]
# or
yarn add @anthropic-ai/[email protected]
# or
pnpm add @anthropic-ai/[email protected]
# or
bun add @anthropic-ai/[email protected]
    Open source →
    Release notes
    • Updated to parity with Claude Code v2.1.148
    Open source →
  29. 0.3.14721 May 2026
    Release notes

    What's changed

    • Updated to parity with Claude Code v2.1.147

    Update

    npm install @anthropic-ai/[email protected]
# or
yarn add @anthropic-ai/[email protected]
# or
pnpm add @anthropic-ai/[email protected]
# or
bun add @anthropic-ai/[email protected]
    Open source →
    Release notes
    • Updated to parity with Claude Code v2.1.147
    Open source →
  30. 0.3.14620 May 2026
    Release notes

    What's changed

    • Updated to parity with Claude Code v2.1.146

    Update

    npm install @anthropic-ai/[email protected]
# or
yarn add @anthropic-ai/[email protected]
# or
pnpm add @anthropic-ai/[email protected]
# or
bun add @anthropic-ai/[email protected]
    Open source →
    Release notes
    • Updated to parity with Claude Code v2.1.146
    Open source →
  31. 0.3.14519 May 2026
    Release notes

    What's changed

    • Updated to parity with Claude Code v2.1.145

    Update

    npm install @anthropic-ai/[email protected]
# or
yarn add @anthropic-ai/[email protected]
# or
pnpm add @anthropic-ai/[email protected]
# or
bun add @anthropic-ai/[email protected]
    Open source →
    Release notes
    • Updated to parity with Claude Code v2.1.145
    Open source →
  32. 0.3.14418 May 2026
    Release notes

    What's changed

    • Assistant messages and StopFailure hooks now report error: 'model_not_found' when the selected model doesn't exist or isn't available, instead of the generic 'invalid_request'. The api_error_status field on result messages is now documented.
    • Added @anthropic-ai/claude-agent-sdk/extract export for bun build --compile consumers: import the platform native binary with with { type: 'file' }, call extractFromBunfs(binPath) to copy it out of the compiled executable's virtual filesystem, and pass the result to options.pathToClaudeCodeExecutable

    Update

    npm install @anthropic-ai/[email protected]
# or
yarn add @anthropic-ai/[email protected]
# or
pnpm add @anthropic-ai/[email protected]
# or
bun add @anthropic-ai/[email protected]
    Open source →
    Release notes
    • Assistant messages and StopFailure hooks now report error: 'model_not_found' when the selected model doesn't exist or isn't available, instead of the generic 'invalid_request'. The api_error_status field on result messages is now documented.
    • Added @anthropic-ai/claude-agent-sdk/extract export for bun build --compile consumers: import the platform native binary with with { type: 'file' }, call extractFromBunfs(binPath) to copy it out of the compiled executable's virtual filesystem, and pass the result to options.pathToClaudeCodeExecutable
    Open source →
  33. 0.3.14315 May 2026
    Release notes

    What's changed

    • @anthropic-ai/sdk and @modelcontextprotocol/sdk are now peerDependencies instead of dependencies. Runtime is unaffected (both are bundled); npm/bun/pnpm auto-install them. yarn classic users should add them explicitly for full TypeScript type resolution

    Update

    npm install @anthropic-ai/[email protected]
# or
yarn add @anthropic-ai/[email protected]
# or
pnpm add @anthropic-ai/[email protected]
# or
bun add @anthropic-ai/[email protected]
    Open source →
    Release notes
    • @anthropic-ai/sdk and @modelcontextprotocol/sdk are now peerDependencies instead of dependencies. Runtime is unaffected (both are bundled); npm/bun/pnpm auto-install them. yarn classic users should add them explicitly for full TypeScript type resolution
    Open source →
  34. 0.3.14214 May 2026
    Release notes

    What's changed

    • Breaking: Removed the v2 session API (unstable_v2_createSession, unstable_v2_resumeSession, unstable_v2_prompt, SDKSession, SDKSessionOptions), deprecated since 0.2.133. Use query() — pass an AsyncIterable<SDKUserMessage> for multi-turn, or options.resume to continue a session.
    • Breaking: MCP servers now connect in the background by default; sessions start immediately and slow servers report status: "pending" in init until ready. Set MCP_CONNECTION_NONBLOCKING=0 to restore the old behavior of waiting up to 5s before the first query, or mark a server alwaysLoad: true to require it in turn 1.
    • Breaking: Headless and SDK sessions now use Task tools (TaskCreate / TaskUpdate / TaskGet / TaskList) instead of TodoWrite, deprecated since 0.2.136. Tool consumers should accumulate by task ID instead of replacing a snapshot list.
    • Surfaced request_id, subagent_type, and task_description on SDK message types and task system events
    • Headless --sdk-url sessions now exit non-zero with a stderr diagnostic when the remote transport closes permanently (401/403/404 or WS permanent close), instead of silently exiting 0

    Update

    npm install @anthropic-ai/[email protected]
# or
yarn add @anthropic-ai/[email protected]
# or
pnpm add @anthropic-ai/[email protected]
# or
bun add @anthropic-ai/[email protected]
    Open source →
    Release notes
    • Breaking: Removed the v2 session API (unstable_v2_createSession, unstable_v2_resumeSession, unstable_v2_prompt, SDKSession, SDKSessionOptions), deprecated since 0.2.133. Use query() — pass an AsyncIterable<SDKUserMessage> for multi-turn, or options.resume to continue a session.
    • Breaking: MCP servers now connect in the background by default; sessions start immediately and slow servers report status: "pending" in init until ready. Set MCP_CONNECTION_NONBLOCKING=0 to restore the old behavior of waiting up to 5s before the first query, or mark a server alwaysLoad: true to require it in turn 1.
    • Breaking: Headless and SDK sessions now use Task tools (TaskCreate / TaskUpdate / TaskGet / TaskList) instead of TodoWrite, deprecated since 0.2.136. Tool consumers should accumulate by task ID instead of replacing a snapshot list.
    • Surfaced request_id, subagent_type, and task_description on SDK message types and task system events
    • Headless --sdk-url sessions now exit non-zero with a stderr diagnostic when the remote transport closes permanently (401/403/404 or WS permanent close), instead of silently exiting 0
    Open source →
  35. 0.2.14113 May 2026
    Release notes

    What's changed

    • TaskCreateInput, TaskCreateOutput, TaskGetInput, TaskGetOutput, TaskUpdateInput, TaskUpdateOutput, TaskListInput, and TaskListOutput types are now exported from @anthropic-ai/claude-agent-sdk/sdk-tools and included in the ToolInputSchemas/ToolOutputSchemas unions
    • Aligned @anthropic-ai/sdk dependency to ^0.93.0

    Update

    npm install @anthropic-ai/[email protected]
# or
yarn add @anthropic-ai/[email protected]
# or
pnpm add @anthropic-ai/[email protected]
# or
bun add @anthropic-ai/[email protected]
    Open source →
    Release notes
    • TaskCreateInput, TaskCreateOutput, TaskGetInput, TaskGetOutput, TaskUpdateInput, TaskUpdateOutput, TaskListInput, and TaskListOutput types are now exported from @anthropic-ai/claude-agent-sdk/sdk-tools and included in the ToolInputSchemas/ToolOutputSchemas unions
    • Aligned @anthropic-ai/sdk dependency to ^0.93.0
    Open source →
  36. 0.2.14012 May 2026
    Release notes

    What's changed

    • Updated to parity with Claude Code v2.1.140

    Update

    npm install @anthropic-ai/[email protected]
# or
yarn add @anthropic-ai/[email protected]
# or
pnpm add @anthropic-ai/[email protected]
# or
bun add @anthropic-ai/[email protected]
    Open source →
    Release notes
    • Updated to parity with Claude Code v2.1.140
    Open source →
  37. 0.2.13911 May 2026
    Release notes

    What's changed

    • Updated to parity with Claude Code v2.1.139

    Update

    npm install @anthropic-ai/[email protected]
# or
yarn add @anthropic-ai/[email protected]
# or
pnpm add @anthropic-ai/[email protected]
# or
bun add @anthropic-ai/[email protected]
    Open source →
    Release notes
    • Updated to parity with Claude Code v2.1.139
    Open source →
  38. 0.2.1389 May 2026
    Release notes

    What's changed

    • Updated to parity with Claude Code v2.1.138

    Update

    npm install @anthropic-ai/[email protected]
# or
yarn add @anthropic-ai/[email protected]
# or
pnpm add @anthropic-ai/[email protected]
# or
bun add @anthropic-ai/[email protected]
    Open source →
    Release notes
    • Updated to parity with Claude Code v2.1.138
    Open source →
  39. 0.2.1379 May 2026
    Release notes

    What's changed

    • Updated to parity with Claude Code v2.1.137

    Update

    npm install @anthropic-ai/[email protected]
# or
yarn add @anthropic-ai/[email protected]
# or
pnpm add @anthropic-ai/[email protected]
# or
bun add @anthropic-ai/[email protected]
    Open source →
    Release notes
    • Updated to parity with Claude Code v2.1.137
    Open source →
  40. 0.2.1368 May 2026
    Release notes

    What's changed

    • Added resolveSettings() (alpha) to inspect effective merged settings without spawning the Claude CLI; reads MDM (plist/HKLM/HKCU) for parity with CLI startup
    • Deprecated TodoWrite tool — future versions will switch to Task tools (TaskCreate, TaskGet, TaskUpdate, TaskList)

    Update

    npm install @anthropic-ai/[email protected]
# or
yarn add @anthropic-ai/[email protected]
# or
pnpm add @anthropic-ai/[email protected]
# or
bun add @anthropic-ai/[email protected]
    Open source →
    Release notes
    • Added resolveSettings() (alpha) to inspect effective merged settings without spawning the Claude CLI; reads MDM (plist/HKLM/HKCU) for parity with CLI startup
    • Deprecated TodoWrite tool — future versions will switch to Task tools (TaskCreate, TaskGet, TaskUpdate, TaskList)
    Open source →
  41. 0.2.1337 May 2026
    Release notes

    What's changed

    • Deprecated the unstable V2 session API (unstable_v2_createSession / unstable_v2_resumeSession / unstable_v2_prompt) — use query() instead
    • Deprecated passing 'Skill' in allowedTools — use the skills option instead
    • Updated to parity with Claude Code v2.1.133

    Update

    npm install @anthropic-ai/[email protected]
# or
yarn add @anthropic-ai/[email protected]
# or
pnpm add @anthropic-ai/[email protected]
# or
bun add @anthropic-ai/[email protected]
    Open source →
    Release notes
    • Deprecated the unstable V2 session API (unstable_v2_createSession / unstable_v2_resumeSession / unstable_v2_prompt) — use query() instead
    • Deprecated passing 'Skill' in allowedTools — use the skills option instead
    • Updated to parity with Claude Code v2.1.133
    Open source →
  42. 0.2.1326 May 2026
    Release notes

    What's changed

    • Documented applyFlagSettings() in the TypeScript Agent SDK reference and added support for null on top-level keys to clear flag-settings overrides
    • Updated to parity with Claude Code v2.1.132

    Update

    npm install @anthropic-ai/[email protected]
# or
yarn add @anthropic-ai/[email protected]
# or
pnpm add @anthropic-ai/[email protected]
# or
bun add @anthropic-ai/[email protected]
    Open source →
    Release notes
    • Documented applyFlagSettings() in the TypeScript Agent SDK reference and added support for null on top-level keys to clear flag-settings overrides
    • Updated to parity with Claude Code v2.1.132
    Open source →
  43. 0.2.1316 May 2026
    Release notes

    What's changed

    • Updated to parity with Claude Code v2.1.131

    Update

    npm install @anthropic-ai/[email protected]
# or
yarn add @anthropic-ai/[email protected]
# or
pnpm add @anthropic-ai/[email protected]
# or
bun add @anthropic-ai/[email protected]
    Open source →
    Release notes
    • Updated to parity with Claude Code v2.1.131
    Open source →
  44. 0.2.1295 May 2026
    Release notes

    What's changed

    • Updated to parity with Claude Code v2.1.129

    Update

    npm install @anthropic-ai/[email protected]
# or
yarn add @anthropic-ai/[email protected]
# or
pnpm add @anthropic-ai/[email protected]
# or
bun add @anthropic-ai/[email protected]
    Open source →
    Release notes
    • Updated to parity with Claude Code v2.1.129
    Open source →
  45. 0.2.1284 May 2026
    Release notes

    What's changed

    • Updated to parity with Claude Code v2.1.128

    Update

    npm install @anthropic-ai/[email protected]
# or
yarn add @anthropic-ai/[email protected]
# or
pnpm add @anthropic-ai/[email protected]
# or
bun add @anthropic-ai/[email protected]
    Open source →
    Release notes
    • Updated to parity with Claude Code v2.1.128
    Open source →
  46. 0.2.12630 Apr 2026
    Release notes

    What's changed

    • Added origin to result messages (SDKResultSuccess / SDKResultError) — forwards the triggering message's SDKMessageOrigin so consumers can distinguish user-prompted results from task-notification followups

    Update

    npm install @anthropic-ai/[email protected]
# or
yarn add @anthropic-ai/[email protected]
# or
pnpm add @anthropic-ai/[email protected]
# or
bun add @anthropic-ai/[email protected]
    Open source →
    Release notes
    • Added origin to result messages (SDKResultSuccess / SDKResultError) — forwards the triggering message's SDKMessageOrigin so consumers can distinguish user-prompted results from task-notification followups
    Open source →
  47. 0.2.12430 Apr 2026
    Release notes
    • Updated to parity with Claude Code v2.1.124
    Open source →
  48. 0.2.12329 Apr 2026
    Release notes

    What's changed

    • Updated to parity with Claude Code v2.1.123

    Update

    npm install @anthropic-ai/[email protected]
# or
yarn add @anthropic-ai/[email protected]
# or
pnpm add @anthropic-ai/[email protected]
# or
bun add @anthropic-ai/[email protected]
    Open source →
    Release notes
    • Updated to parity with Claude Code v2.1.123
    Open source →
  49. 0.2.12228 Apr 2026
    Release notes

    What's changed

    • Updated to parity with Claude Code v2.1.122

    Update

    npm install @anthropic-ai/[email protected]
# or
yarn add @anthropic-ai/[email protected]
# or
pnpm add @anthropic-ai/[email protected]
# or
bun add @anthropic-ai/[email protected]
    Open source →
    Release notes
    • Updated to parity with Claude Code v2.1.122
    Open source →
  50. 0.2.12127 Apr 2026
    Release notes

    What's changed

    • Added updatedToolOutput to PostToolUseHookSpecificOutput for replacing tool output on all tools. updatedMCPToolOutput is deprecated.

    Update

    npm install @anthropic-ai/[email protected]
# or
yarn add @anthropic-ai/[email protected]
# or
pnpm add @anthropic-ai/[email protected]
# or
bun add @anthropic-ai/[email protected]
    Open source →
    Release notes
    • Added updatedToolOutput to PostToolUseHookSpecificOutput for replacing tool output on all tools. updatedMCPToolOutput is deprecated.
    Open source →
  51. 0.2.12024 Apr 2026
    Release notes
    • Added skills option (string[] | 'all') to control which Skills are loaded into the main session, matching the Python SDK
    Open source →
  52. 0.2.11923 Apr 2026
    Release notes

    What's changed

    • excludeDynamicSections now keeps static auto-memory instructions in the cacheable system-prompt block; only the per-user memory directory path and per-machine environment values are relocated to the first user message
    • Long-running SDK sessions now reconnect claude.ai-proxied MCP servers after a transport-stream abort
    • SessionStore.append() failures are now retried up to 3 times with short backoff before the batch is dropped and mirror_error is emitted

    Update

    npm install @anthropic-ai/[email protected]
# or
yarn add @anthropic-ai/[email protected]
# or
pnpm add @anthropic-ai/[email protected]
# or
bun add @anthropic-ai/[email protected]
    Open source →
    Release notes
    • Added forwardSubagentText option to stream subagent text deltas to SDK consumers
    • excludeDynamicSections now keeps static auto-memory instructions in the cacheable system-prompt block; only the per-user memory directory path and per-machine environment values are relocated to the first user message
    • Long-running SDK sessions now reconnect claude.ai-proxied MCP servers after a transport-stream abort
    • SessionStore.append() failures are now retried up to 3 times with short backoff before the batch is dropped and mirror_error is emitted
    Open source →
  53. 0.2.11822 Apr 2026
    Release notes

    What's changed

    • Added Options.managedSettings for embedders to pass policy-tier settings to the spawned CLI in-memory, honored below IT-controlled managed sources

    Update

    npm install @anthropic-ai/[email protected]
# or
yarn add @anthropic-ai/[email protected]
# or
pnpm add @anthropic-ai/[email protected]
# or
bun add @anthropic-ai/[email protected]
    Open source →
    Release notes
    • Added Options.managedSettings for embedders to pass policy-tier settings to the spawned CLI in-memory, honored below IT-controlled managed sources
    Open source →
  54. 0.2.11721 Apr 2026
    Release notes

    What's changed

    • Updated to parity with Claude Code v2.1.117

    Update

    npm install @anthropic-ai/[email protected]
# or
yarn add @anthropic-ai/[email protected]
# or
pnpm add @anthropic-ai/[email protected]
# or
bun add @anthropic-ai/[email protected]
    Open source →
    Release notes
    • Updated to parity with Claude Code v2.1.117
    Open source →
  55. 0.2.11620 Apr 2026
    Release notes

    What's changed

    • Updated to parity with Claude Code v2.1.116

    Update

    npm install @anthropic-ai/[email protected]
# or
yarn add @anthropic-ai/[email protected]
# or
pnpm add @anthropic-ai/[email protected]
# or
bun add @anthropic-ai/[email protected]
    Open source →
    Release notes
    • Updated to parity with Claude Code v2.1.116
    Open source →
  56. 0.2.11417 Apr 2026
    Release notes

    What's changed

    • Updated to parity with Claude Code v2.1.114

    Update

    npm install @anthropic-ai/[email protected]
# or
yarn add @anthropic-ai/[email protected]
# or
pnpm add @anthropic-ai/[email protected]
# or
bun add @anthropic-ai/[email protected]
    Open source →
    Release notes
    • Updated to parity with Claude Code v2.1.114
    Open source →
  57. 0.2.11317 Apr 2026
    Release notes

    What's changed

    • Changed the SDK to spawn a native Claude Code binary (via a per-platform optional dependency) instead of bundled JavaScript
    • Added sessionStore option (alpha) to query() and session helpers for mirroring session transcripts to external storage, with SessionStore/SessionKey/SessionStoreEntry types, InMemorySessionStore reference implementation, and importSessionToStore() for migrating existing sessions
    • Added deleteSession() for removing a session from disk or a SessionStore
    • Added SDKMirrorErrorMessage (subtype: 'mirror_error') to the SDKMessage union — emitted when a sessionStore.append() batch fails
    • Breaking: options.env once again replaces process.env for the CLI subprocess instead of overlaying it. To add or override individual variables, pass env: { ...process.env, MY_VAR: "x" }
    • Added title option to query() — sets the session title and skips auto-generation
    • Added OpenTelemetry trace context propagation — the caller's active trace context is forwarded to the CLI subprocess so spans parent under your distributed trace

    Update

    npm install @anthropic-ai/[email protected]
# or
yarn add @anthropic-ai/[email protected]
# or
pnpm add @anthropic-ai/[email protected]
# or
bun add @anthropic-ai/[email protected]
    Open source →
    Release notes
    • Changed the SDK to spawn a native Claude Code binary (via a per-platform optional dependency) instead of bundled JavaScript
    • Added sessionStore option (alpha) to query() and session helpers for mirroring session transcripts to external storage, with SessionStore/SessionKey/SessionStoreEntry types, InMemorySessionStore reference implementation, and importSessionToStore() for migrating existing sessions
    • Added deleteSession() for removing a session from disk or a SessionStore
    • Added SDKMirrorErrorMessage (subtype: 'mirror_error') to the SDKMessage union — emitted when a sessionStore.append() batch fails
    • Breaking: options.env once again replaces process.env for the CLI subprocess instead of overlaying it. To add or override individual variables, pass env: { ...process.env, MY_VAR: "x" }
    • Added title option to query() — sets the session title and skips auto-generation
    • Added OpenTelemetry trace context propagation — the caller's active trace context is forwarded to the CLI subprocess so spans parent under your distributed trace
    Open source →
  58. 0.2.11216 Apr 2026
    Release notes

    What's changed

    • Updated to parity with Claude Code v2.1.112

    Update

    npm install @anthropic-ai/[email protected]
# or
yarn add @anthropic-ai/[email protected]
# or
pnpm add @anthropic-ai/[email protected]
# or
bun add @anthropic-ai/[email protected]
    Open source →
    Release notes
    • Updated to parity with Claude Code v2.1.112
    Open source →
  59. 0.2.11116 Apr 2026
    Release notes

    What's changed

    • Opus 4.7 is now available! This version of the SDK is required to use it.
    • mcp_set_servers control request: remote (http/sse) server entries can now carry per-tool permission_policy values, which are applied to the session's allow/deny rules
    • startup() and WarmQuery are now part of the public TypeScript API
    • Changed options.env to overlay the inherited process.env instead of replacing it

    Update

    npm install @anthropic-ai/[email protected]
# or
yarn add @anthropic-ai/[email protected]
# or
pnpm add @anthropic-ai/[email protected]
# or
bun add @anthropic-ai/[email protected]
    Open source →
    Release notes
    • Opus 4.7 is now available! This version of the SDK is required to use it.
    • mcp_set_servers control request: remote (http/sse) server entries can now carry per-tool permission_policy values, which are applied to the session's allow/deny rules
    • startup() and WarmQuery are now part of the public TypeScript API
    • Changed options.env to overlay the inherited process.env instead of replacing it
    Open source →
  60. 0.2.11015 Apr 2026
    Release notes

    What's changed

    • Fixed unstable_v2_createSession not respecting cwd, settingSources, and allowDangerouslySkipPermissions options
    • Added optional shouldQuery field to SDKUserMessage — set to false to append a user message without triggering an assistant turn; fixed shouldQuery: false messages incorrectly triggering auto-title generation, prompt suggestions, and UserPromptSubmit hooks
    • Auto session-title generation now respects CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC and CLAUDE_CODE_DISABLE_TERMINAL_TITLE

    Update

    npm install @anthropic-ai/[email protected]
# or
yarn add @anthropic-ai/[email protected]
# or
pnpm add @anthropic-ai/[email protected]
# or
bun add @anthropic-ai/[email protected]
    Open source →
    Release notes
    • Fixed unstable_v2_createSession not respecting cwd, settingSources, and allowDangerouslySkipPermissions options
    • Added optional shouldQuery field to SDKUserMessage — set to false to append a user message without triggering an assistant turn; fixed shouldQuery: false messages incorrectly triggering auto-title generation, prompt suggestions, and UserPromptSubmit hooks
    • Auto session-title generation now respects CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC and CLAUDE_CODE_DISABLE_TERMINAL_TITLE
    Open source →