Packages

@anthropic-ai/claude-agent-sdk

0.3.330 · 20 Nov 2026SEE LICENSE IN README.md20.7M / weekRepositorynpmAtom feed

Your version

351 stable releases, newest first, by release line. Notes are quoted as the maintainers published them.

  1. 0.3.330

    20 Nov 2026

    Summary· from the note as AI read it

    Read before upgrading: 1 change to make.

  2. 0.3.329

    19 Nov 2026
    • Added a system/informational warning, tagged managed_hooks_not_loaded, when hooks in managed settings fail to load

    • Added permissions.workingDirectoriesExclude to the Settings type: paths, read only from --settings and settings the host sends, that the working-directory read and write blocks treat as outside

    • Fixed sessions bound with SpareProcess.claim() ignoring autoCompactWindow from the folder's settings or the claim's settings

  3. 0.3.328

    18 Nov 2026
    • Added onFailure to mcp_tool hooks in the Settings type: with "block", a hook whose call fails blocks the action it guards

    • Added CLAUDE_CODE_DISABLE_DEFERRED_TOOL_RESUME: set it in the env option to stop resume and continue from running a tool call that a hook deferred; settings can't set it

    • Added support for the policy plugin's allowManagedModsOnly option in host-supplied managedSettings; an admin's managed settings still win

  4. 0.3.327

    17 Nov 2026

    Summary· from the note as AI read it

    Read before upgrading: 5 changes to make.

    • Breaking

      Changed query(), startup() and prewarm() to refuse options that can't be sent to Claude Code, such as an agent with a circular or BigInt field. Fix the named option.

    • Breaking

      Changed hook options to require arrays: a hook event's value and a matcher's hooks. A Set, generator, plain object, true or number is now refused.

    • Deprecated

      Deprecated createSdkMcpServer() servers in an agent's mcpServers: ignored with a warning, and other options apply. Move them to top-level mcpServers, which gives the main session their tools.

  5. 0.3.326

    16 Nov 2026
    • Deprecated

      Deprecated sending mcpServers on Claude Code's command line (today's default, 'argv'): a future release defaults to 'initialize'; apps running an older Claude Code must update it or set 'argv'

    • Added mcpServersDelivery: 'initialize': sends mcpServers in the initialize request instead of on Claude Code's command line; needs the bundled Claude Code or newer

    • Added getSessionInfo() to the /core entry

  6. 0.3.325

    13 Nov 2026
    • Added archiveSession() and unarchiveSession(), and an archived field on the sessions that listSessions() and getSessionInfo() return

    • Added refuseIfBusy to Query.reloadPlugins() so a host can have a reload refused while the session is busy

    • Added managed_lock to plugin_errors entries on system/init, naming the managed enabledPlugins entry that dropped a plugin copy

  7. 0.3.324

    13 Nov 2026
    • Updated to parity with Claude Code v2.1.324

  8. 0.3.323

    12 Nov 2026
    • Added machinePolicy.didNotLoad (alpha) to resolveSettings()'s result, which tells a host when a machine policy source may be there and did not load

    • Added matchDeniedModels() (alpha), which tells a host which models a deniedModels list blocks, by Claude Code's own entry rules

    • Added the periodic tool_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 call

  9. 0.3.322

    10 Nov 2026
    • Updated to parity with Claude Code v2.1.322

  10. 0.3.321

    9 Nov 2026
    • Fixed canUseTool getting the app's own PreToolUse hook reason in decisionReason when another hook also asked

    • Fixed a PreToolUse hook's ask being lost when another hook's defer finished first and could not be honored

    • Fixed every hook being dropped when one event in the hooks option is set to undefined

  11. 0.3.319

    6 Nov 2026
    • Added 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 in the background with task_type "mcp_task"

    • Fixed the OpenTelemetry claude_code.session.count metric counting prewarm() processes that were never claimed; a pre-started process now counts once, when SpareProcess.claim() succeeds

    • Fixed session_writes_lost listing the wrong session in transcript_session_ids after /clear in a session resumed from a transcript file outside the projects folder

  12. 0.3.318

    3 Nov 2026
    • Added an optional credential_expires_at field to result messages: when the stored claude.ai sign-in in use ends

    • Added the config_file_invalid startup failure reason, reported when a configuration file read at startup isn't valid JSON

    • Fixed the interrupt response missing a message held behind a model change: it is now listed, cancelled with cancel_queued, and stopped at start-up as a queued message is

  13. 0.3.317

    3 Nov 2026
    • Added onFailure to hook matchers: with "block", a hook that throws or returns invalid output blocks the action

    • Added a warning message in the stream when a hook callback fails

    • Added a session_writes_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.json

  14. 0.3.316

    31 Oct 2026
    • Added permissions.blockReadsExemptPaths to the Settings type: paths, read only from --settings and settings the host sends, that blockReadsOutsideWorkingDirectories lets through without making them working directories

    • Updated to parity with Claude Code v2.1.316

  15. 0.3.315

    30 Oct 2026
    • Updated to parity with Claude Code v2.1.315

  16. 0.3.314

    30 Oct 2026
    • Added sandbox_required_unavailable to startup_failure_reason, for the result Claude Code writes when a required sandbox cannot run

    • Added permissions.blockWritesOutsideWorkingDirectories to the Settings type

    • Added prewarm() (alpha) to the @anthropic-ai/claude-agent-sdk/core entry point

  17. 0.3.312

    27 Oct 2026
    • Added autoMode, skipAutoPermissionPrompt, useAutoModeDuringPlan and permissions.disableAutoMode to the Settings type

    • Added unanswered (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 capability

    • Fixed resolveSettings() 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 CLI

  18. 0.3.311

    26 Oct 2026
    • Breaking

      Changed the minimum supported Node.js version from 18.0.0 to 18.14.0

    • Added cacheCreationEphemeral5mInputTokens and cacheCreationEphemeral1hInputTokens to ModelUsage, splitting cacheCreationInputTokens by cache lifetime

    • Changed background start-up work to wait until the first model request is sent, for about 10 seconds at most, when the first message arrives during start-up

  19. 0.3.310

    23 Oct 2026
    • Updated to parity with Claude Code v2.1.310

  20. 0.3.309

    22 Oct 2026
    • Fixed host-supplied managedSettings dropping disableAllHooks, disableSkillShellExecution and empty allowedHttpHookUrls / httpHookAllowedEnvVars lists

    • Changed extractFromBunfs() 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 root

    • Changed extractFromBunfs() to reuse an already-extracted file only when its bytes match the embedded binary, replacing it otherwise

  21. 0.3.308

    22 Oct 2026
    • Updated to parity with Claude Code v2.1.308

  22. 0.3.307

    21 Oct 2026
    • Added 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 fired

    • Added supportedDialogKinds to browser SDK query(), sent on initialize; a non-empty list requires onUserDialog

    • Updated to parity with Claude Code v2.1.307

  23. 0.3.306

    21 Oct 2026
    • Updated to parity with Claude Code v2.1.306

  24. 0.3.305

    20 Oct 2026
    • Added recommendations and fix to the get_usage response's behavior windows

    • Fixed servers set with setMcpServers being replaced later in the session by a same-named server from the user's own settings

    • Fixed startup() with initializeTimeoutMs: null counting time spent in SessionStart or Setup hooks against its 60-second limit; null now works like leaving the option out

  25. 0.3.304

    19 Oct 2026
    • Added suspendSseStream(query) and resumeSseStream(query) to the browser SDK: close a query's event stream and reopen it later without ending the query

    • Added stable row ids to getContextUsage(), and, when the CLI answers on its own stdio, plugin ids, agent and skill file paths, and per-server MCP instruction token shares

    • Fixed startup() timing out while a SessionStart or Setup command hook was running when 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 reported

  26. 0.3.303

    18 Oct 2026
    • Updated to parity with Claude Code v2.1.303

  27. 0.3.302

    16 Oct 2026
    • Fixed structured output results delivering a response's output as structured_output when the API refused that response; the result is now an error with no payload

    • Changed an omitted permissionMode to start in default mode on third-party providers, with telemetry off or on a fresh install; pass permissionMode: 'auto' to keep auto mode

    • Changed fork subagents (subagent_type: "fork") to be on by default in SDK sessions, as in the terminal; run_in_background is still offered, and CLAUDE_CODE_FORK_SUBAGENT=0 turns them off

  28. 0.3.301

    15 Oct 2026
    • Added per-tool permission policies to sdk-type MCP server configs: tools entries with permission_policy always_ask or always_deny, applied on initialize and setMcpServers()

    • Added 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 settings

    • Added addPlugins to Query.reloadPlugins() so a host can load more plugin folders into a running session

  29. 0.3.300

    14 Oct 2026
    • Fixed importSessionToStore skipping transcript rows that contain a Unicode line or paragraph separator (U+2028, U+2029) on Node 24 and Bun

    • Fixed a background subagent's final report in auto mode being joined into one turn with another message from the same subagent; the report now always runs as its own turn

    • Fixed rewind_conversation with interrupt_if_running stopping the running turn before refusing with "unseen later turn"

  30. 0.3.299

    14 Oct 2026
    • Added an optional nextFireAt (epoch ms of the next run) to the CronCreate and CronList tool outputs

    • Added property_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 order

    • Fixed rewind_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 prefillText

  31. 0.3.296

    9 Oct 2026
    • Added claude_code_version to the initialize control response so clients know the CLI version before the first turn

    • Added autoCompactWindow to AgentDefinition, so a subagent can auto-compact earlier than the main conversation's window

    • Fixed the sandbox 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 combined

  32. 0.3.295

    8 Oct 2026
    • Added overageEnabled to SDKRateLimitInfo: on usage-limit warnings, whether the account has extra usage turned on

    • Fixed an MCP server added with mcp_set_servers sometimes keeping an outdated tool list when another server in the same request connected later

    • Fixed assistant text blocks losing their citations in streamed responses

  33. 0.3.294

    8 Oct 2026
    • Updated to parity with Claude Code v2.1.294

  34. 0.3.293

    7 Oct 2026
    • Added an optional subagent_type to background_tasks_changed task entries, so hosts can name each subagent's type without pairing with task_started

    • Updated to parity with Claude Code v2.1.293

  35. 0.3.292

    6 Oct 2026
    • 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 the subagent is resumed

    • Added parent_task_id to task_started events and background_tasks_changed entries, naming the subagent task that launched a task

    • Added run_id to background task events and origin.runId to task notifications, so a host can tell a resumed task's runs apart

  36. 0.3.291

    6 Oct 2026
    • Updated to parity with Claude Code v2.1.291

  37. 0.3.290

    5 Oct 2026
    • Added an optional offset field to the WebFetch tool input for reading on through long pages

    • Fixed failed Claude in Chrome tool calls dropping the result's _meta: when the result has one, tool_use_result is now { content, _meta }, as for other MCP tools

    • Fixed deny and ask rules missing toolAliases tools when written with a wildcard (Bash*), a match-all pattern (Bash(**), also on the mapped name), or an input field also in disallowedTools

  38. 0.3.289

    3 Oct 2026
    • Updated to parity with Claude Code v2.1.289

  39. 0.3.288

    2 Oct 2026
    • Updated to parity with Claude Code v2.1.288

  40. 0.3.287

    1 Oct 2026
    • Added optional remote-session latency fields (first_text_post_queue_wait_ms, first_text_post_queued_behind) to the success result message

    • Fixed includePartialMessages streams sending a cut-short reply's message_stop late or never, so apps could show the reply as still in progress

    • Fixed the error for a revoked claude.ai login, which now reads "Failed to authenticate: OAuth token revoked" instead of a generic or "does not have access" message

  41. 0.3.286

    30 Sep 2026
    • Added the initialize response field sdk_mcp_manifests_parked and the system/init capabilities sdk_mcp_manifests and sdk_mcp_tools_list_changed

    • Fixed foreground subagents sometimes not receiving the task-tracking tools listed in tools or allowedTools

    • Fixed an SDK MCP server listing no tools when one tool's schema cannot be converted to JSON Schema; that tool is now left out with a warning naming it

  42. 0.3.285

    29 Sep 2026
    • Added an optional read.title (the artifact's stored title) to the Artifact tool's structured read result

    • Added provider_not_allowed to startup_failure_reason and allowedProviders to the Settings type

    • Fixed sessions with CLAUDE_CODE_FORK_SUBAGENT=1: a subagent's own Agent call now runs in the foreground, so the subagent gets the child's result

  43. 0.3.284

    28 Sep 2026
    • 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

    • Added applied.ultracodeAvailable and applied.ultracodeRequested to getSettings(): whether this session can run Ultracode, and whether it is requested, independent of whether it is in effect

    • Fixed forkSession() copies reading back the wrong history when cut at a progress row or fork briefing after a rewind, or when the session was compacted with some messages kept

  44. 0.3.283

    25 Sep 2026
    • Added plugin_errors to the SDKSystemMessage type (system/init), including path for a --plugin-dir entry that did not load

    • Fixed getSessionMessages() returning, and forkSession() copying, a rewound-away branch when the newest branch ends at a meta row or a local command's rows

    • Changed stream-json output to include warnings and notices raised during a turn as system/informational messages; it previously dropped them

  45. 0.3.282

    24 Sep 2026
    • Added support for strictKnownMarketplaces and blockedMarketplaces in host-supplied managedSettings: the allowlist applies only where admin policy sets none; the blocklist adds to the admin's

    • Added @anthropic-ai/claude-agent-sdk/core, a smaller entry point for apps that bundle the SDK (query, MCP tool helpers, session mutations, resolveSettings); it uses your installed zod and MCP SDK

    • Added prewarm() 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 later

  46. 0.3.281

    23 Sep 2026
    • Added optional 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 happened

    • Fixed permission and dialog callbacks still being invoked for requests that arrived after close()

    • Fixed control requests issued after a query closed hanging or leaking, and permission prompts that could not be cancelled after a cancelled request was redelivered

  47. 0.3.280

    22 Sep 2026
    • Added optional 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=1

    • Added verbatimPrompts 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+)

    • Added _meta to mcpServerStatus() tool entries, carrying a tool's MCP Apps ui metadata so a host can find its ui:// resource

  48. 0.3.278

    19 Sep 2026
    • Updated to parity with Claude Code v2.1.278

  49. 0.3.277

    18 Sep 2026
    • Added an optional builtin field to SlashCommand, set when a command is built into Claude Code

    • Added pasted_content to SDKUserMessage: text the user pasted rather than typed, appended after the typed prompt

    • Added optional remote-session latency fields (first_text_post_ms, first_text_post_wall_ms, first_stream_post_queue_wait_ms, first_stream_post_queued_behind) to the success result message

  50. 0.3.276

    18 Sep 2026
    • Updated to parity with Claude Code v2.1.276

A whole project to check? Paste its package.json in the dependency check: every deprecated, outdated or vulnerable dependency, with what to upgrade to. Free, no account.