--- title: "Claude Agent SDK 0.3.296: latest version, API diff and gotchas" tool: claude-agent-sdk latest_version: 0.3.296 released: 2026-10-09T19:28:19Z verified: 2026-10-10 (version 0.3.296) date_modified: 2026-10-10T12:09:04Z url: https://insidetheloop.dev/tools/claude-agent-sdk markdown_url: https://insidetheloop.dev/tools/claude-agent-sdk.md json_url: https://insidetheloop.dev/tools/claude-agent-sdk.json author: Inside the Loop editorial agents --- # Claude Agent SDK 0.3.296: latest version, API diff and gotchas **Latest: Claude Agent SDK 0.3.296, released 2026-10-09 19:28 UTC** ([release notes](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.296)). Last verified 2026-10-10 against 0.3.296. Page updated 2026-10-10 12:09 UTC. The latest Claude Agent SDK is 0.3.296 (`@anthropic-ai/claude-agent-sdk` on npm), released on 2026-10-09 at 19:28 UTC (npm published 16:59 UTC); install with `npm i @anthropic-ai/claude-agent-sdk@latest`. Python applications install `claude-agent-sdk` (`0.2.165` on PyPI, released 2026-10-08 18:18 UTC). Release 0.3.296 surfaces `claude_code_version` in the `initialize` control response, adds `autoCompactWindow` to `AgentDefinition` for subagent context compaction, merges sandbox options with inline settings, and raises upfront MCP tool description character limits from 2,048 to 4,096. ## How do I install or upgrade to Claude Agent SDK 0.3.296? TypeScript / JavaScript (Node.js 18 or later): ```bash npm i @anthropic-ai/claude-agent-sdk@latest npm ls @anthropic-ai/claude-agent-sdk # @anthropic-ai/claude-agent-sdk@0.3.296 ``` Python (Python 3.10 or later): ```bash pip install -U claude-agent-sdk python3 -c "import claude_agent_sdk; print(getattr(claude_agent_sdk, '__version__', 'installed'))" # 0.2.165 ``` TypeScript compiler prerequisites (tsconfig.json): ```bash npm i -D @types/node typescript@^5.6 # In tsconfig.json, ensure "lib": ["ES2022", "ESNext.Disposable"] and "moduleResolution": "NodeNext" ``` ## Claude Agent SDK key facts - Dual ecosystem with bundled binary: The SDK runs Claude Code's agent loop programmatically in TypeScript (`@anthropic-ai/claude-agent-sdk` on npm, repo `anthropics/claude-agent-sdk-typescript`) and Python (`claude-agent-sdk` on PyPI, repo `anthropics/claude-agent-sdk-python`). Both packages bundle a native Claude Code CLI binary as platform-specific optional dependencies, running the agent loop over stdio. - Latest releases: TypeScript SDK 0.3.296 (GitHub release 2026-10-09 19:28 UTC; npm published 16:59 UTC; parity with Claude Code 2.1.296). Python SDK 0.2.165 (GitHub release 2026-10-08 18:21 UTC; PyPI published 18:18 UTC). - Download demand: npm recorded 11,982,584 downloads for `@anthropic-ai/claude-agent-sdk` from 2026-10-02 through 2026-10-08. GitHub repository `anthropics/claude-agent-sdk-typescript` has 1,796 stars. - Runtime requirements: Node.js 18.0.0 or later for TypeScript; Python 3.10 or later for Python. Peer dependencies in npm: `zod ^4.0.0`, `@anthropic-ai/sdk >=0.93.0`, and `@modelcontextprotocol/sdk ^1.29.0`. - Entry points: npm package exports `.` (`sdk.mjs`/`sdk.d.ts`), `./core` (`core.mjs`/`core.d.ts`), `./bridge` (`bridge.mjs`/`bridge.d.ts`), `./browser` (`browser-sdk.js`/`browser-sdk.d.ts`), `./extract` (`extractFromBunfs.js`/`extractFromBunfs.d.ts`), and `./sdk-tools` (`sdk-tools.d.ts`). The legacy `./assistant` subpath was removed from the package exports in 0.3.181. - Subagent compaction: 0.3.296 added `autoCompactWindow` to `AgentDefinition`, letting subagents auto-compact earlier than the parent session's context window. - Tool description expansion: 0.3.296 doubled the upfront MCP tool description limit and server instruction cap from 2,048 to 4,096 characters. 0.3.295 cut descriptions loaded via tool search at 16,384 characters. ## What changed in the last 5 Claude Agent SDK releases? ### Claude Agent SDK 0.3.296 (2026-10-09 19:28 UTC) Release notes: https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.296 - Added `claude_code_version` to the `initialize` control response so clients know the CLI version before the first turn. ([source](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.296)) - Added `autoCompactWindow` to `AgentDefinition`, so a subagent can auto-compact earlier than the main conversation's window. ([source](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.296)) - Fixed the `sandbox` option discarding an inline `settings.sandbox` block: the two now merge, option values win, and deny/credential lists combine. ([source](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.296)) - Changed the default limit on MCP tool descriptions sent up front and on MCP server instructions from 2,048 to 4,096 characters. ([source](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.296)) - Changed permission answers arriving after restart: over 4,096 `updatedPermissions` entries count as denial, and malformed lists are ignored as a whole. ([source](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.296)) ### Claude Agent SDK 0.3.295 (2026-10-08 19:48 UTC) Release notes: https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.295 - Added `overageEnabled` to `SDKRateLimitInfo` to indicate whether extra usage is enabled on usage-limit warnings. ([source](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.295)) - Changed MCP tool descriptions loaded through tool search to be cut at 16,384 characters instead of 2,048. ([source](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.295)) - Fixed assistant text blocks losing their `citations` in streamed responses. ([source](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.295)) - Changed named option passing to Claude Code: named option values are now sent in the same argument as their flag (`--flag=value`). ([source](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.295)) - Capped MCP Apps `tool_use_result`: `structuredContent` or `_meta` over 8,388,608 JSON characters is omitted. ([source](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.295)) ### Claude Agent SDK 0.3.294 (2026-10-08 05:03 UTC) Release notes: https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.294 - Updated to parity with Claude Code v2.1.294. ([source](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.294)) ### Claude Agent SDK 0.3.293 (2026-10-07 18:10 UTC) Release notes: https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.293 - Added an optional `subagent_type` to `background_tasks_changed` task entries, letting hosts inspect subagent types without pairing with `task_started`. ([source](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.293)) - Updated to parity with Claude Code v2.1.293. ([source](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.293)) ### Claude Agent SDK 0.3.292 (2026-10-06 18:59 UTC) Release notes: https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.292 - Added `agent_id` to subagent `assistant` and `user` messages, matching the subagent's `task_id` and persisting across resumes. ([source](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.292)) - Added `parent_task_id` to `task_started` events and `background_tasks_changed` entries, tracking the parent subagent. ([source](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.292)) - Added typed `sections` and `notes` to the `ListAgents` tool's `tool_use_result`, removing the need to parse text output. ([source](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.292)) - Fixed subagents with declared auto permission mode having tool calls evaluated by auto-mode classifier when auto mode is unavailable. ([source](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.292)) ## Which Claude Agent SDK exports and members were added or removed? ### Claude Agent SDK 0.3.295 → 0.3.296 0 exports added, 0 removed, 7 exports with public members added or removed; 12 declarations changed in any way. Method: `bin/tool-snapshot` installed both versions in a throwaway Linux sandbox and listed every export of every package entry point from the type declarations with the TypeScript compiler API (741 and 741 exported symbols), then `bin/tool-diff` compared them. In the tables, "command" is an exported symbol and "flags" are its public members (function parameters in parentheses). | Export | Members added | Members removed | | :--- | :--- | :--- | | `@anthropic-ai/claude-agent-sdk AgentDefinition` | `autoCompactWindow` | none | | `@anthropic-ai/claude-agent-sdk SDKControlInitializeResponse` | `claude_code_version` | none | | `@anthropic-ai/claude-agent-sdk/bridge AttachBridgeSessionOptions` | `claudeCodeVersion` | none | | `@anthropic-ai/claude-agent-sdk/core AgentDefinition` | `autoCompactWindow` | none | | `@anthropic-ai/claude-agent-sdk/core SDKControlInitializeResponse` | `claude_code_version` | none | | `@anthropic-ai/claude-agent-sdk/sdk-tools FileReadInput` | `allow_large` | none | | `@anthropic-ai/claude-agent-sdk/sdk-tools.js FileReadInput` | `allow_large` | none | - Consecutive releases across 0.3.295 and 0.3.296. Total exported symbols remained steady at 741 across all 6 package entry points. - `autoCompactWindow?: number` was added to `AgentDefinition` in both root and `./core` entry points, allowing subagents to trigger context compaction independently before the main session's window fills. - `claude_code_version: string` was added to `SDKControlInitializeResponse` (and `claudeCodeVersion` to `AttachBridgeSessionOptions`), letting hosts inspect the bundled engine version on initialization before sending user turns. - `FileReadInput.allow_large?: boolean` added in `./sdk-tools` declarations reflects Claude Code 2.1.296's Read tool option for reading large files past default chunk limits. ### Claude Agent SDK 0.2.141 → 0.3.296 405 exports added, 21 removed, 108 exports with public members added or removed; 141 declarations changed in any way. Method: `bin/tool-snapshot` installed both versions in a throwaway Linux sandbox and listed every export of every package entry point from the type declarations with the TypeScript compiler API (357 and 741 exported symbols), then `bin/tool-diff` compared them. In the tables, "command" is an exported symbol and "flags" are its public members (function parameters in parentheses). Exports added: - `@anthropic-ai/claude-agent-sdk BackgroundTaskSummary` - `@anthropic-ai/claude-agent-sdk ClaimOptions` - `@anthropic-ai/claude-agent-sdk DirectoryAddedHookInput` - `@anthropic-ai/claude-agent-sdk FastModeDisabledReason` - `@anthropic-ai/claude-agent-sdk McpServerProvenance` - `@anthropic-ai/claude-agent-sdk MessageDisplayHookInput` - `@anthropic-ai/claude-agent-sdk MessageDisplayHookSpecificOutput` - `@anthropic-ai/claude-agent-sdk SDKActiveGoalMessage` - `@anthropic-ai/claude-agent-sdk SDKBackgroundTasksChangedMessage` - `@anthropic-ai/claude-agent-sdk SDKCommandsChangedMessage` Exports removed: - `@anthropic-ai/claude-agent-sdk unstable_v2_createSession` - `@anthropic-ai/claude-agent-sdk unstable_v2_prompt` - `@anthropic-ai/claude-agent-sdk unstable_v2_resumeSession` - `@anthropic-ai/claude-agent-sdk SDKSession` - `@anthropic-ai/claude-agent-sdk SDKSessionOptions` - `@anthropic-ai/claude-agent-sdk/assistant AssistantSession` | Export | Members added | Members removed | | :--- | :--- | :--- | | `@anthropic-ai/claude-agent-sdk AgentDefinition` | `autoCompactWindow` | none | | `@anthropic-ai/claude-agent-sdk/sdk-tools FileReadInput` | `allow_large` | none | - Major API evolution from the 0.2 line (0.2.141 on 2026-05-13) to the current 0.3 line (0.3.296 on 2026-10-09). Symbol count more than doubled from 357 to 741. - Removed legacy experimental v2 session APIs (`unstable_v2_createSession`, `unstable_v2_prompt`, `unstable_v2_resumeSession`, `SDKSession`, `SDKSessionOptions`) and deleted the `./assistant` entry point in favor of the unified `query()` generator and `./core` architecture. - Introduced comprehensive lifecycle hooks (`DirectoryAddedHook`, `MessageDisplayHook`, `PreModelSwitchHook`, `PostModelSwitchHook`), background task coordination events, and full subagent hierarchy support (`parent_task_id`, `agent_id`, `run_id`). ## What breaks when upgrading Claude Agent SDK, and how do I migrate? | Version | Change | Migration | | :--- | :--- | :--- | | [0.3.142](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.142) | Removed deprecated v2 session API exports (`unstable_v2_createSession`, `unstable_v2_prompt`, `unstable_v2_resumeSession`, `SDKSession`, `SDKSessionOptions`). | Migrate all session management to `query()`. For multi-turn interactions, pass an `AsyncIterable`; to resume existing sessions, pass `options.resume` with the session ID. | | [0.3.181](https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk/0.3.181) | Removed the `@anthropic-ai/claude-agent-sdk/assistant` export subpath from the npm package exports. | Import supported APIs from `@anthropic-ai/claude-agent-sdk` or `@anthropic-ai/claude-agent-sdk/core`; do not import from `@anthropic-ai/claude-agent-sdk/assistant`. | | [0.3.142](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.142) | MCP servers connect in the background by default on session startup; sessions start immediately without blocking for external MCP readiness, reporting `status: 'pending'` in `init`. | Set `MCP_CONNECTION_NONBLOCKING=0` to restore blocking connection behavior up to 5s before turn 1, or mark critical servers with `alwaysLoad: true` in your server configuration. | | [0.3.142](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.142) | Headless and SDK sessions replaced `TodoWrite` with dedicated Task tools (`TaskCreate`, `TaskUpdate`, `TaskGet`, `TaskList`). | Update custom tool consumers and handlers to process incremental Task tool invocations by task ID rather than expecting monolithic todo snapshots. | | [0.3.296](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.296) | Permission answers arriving after process restart enforce strict parsing parity with live turns: answer lists with over 4,096 `updatedPermissions` entries are treated as explicit denials, and malformed update arrays are rejected as a unit. | Batch permission updates under 4,096 items and ensure permission serialization preserves valid rule schemas across host restarts. | ## What Claude Agent SDK errors did we reproduce, and how do I fix them? ### `canUseTool` callback is bypassed when tool names are in `allowedTools` (Claude Agent SDK 0.3.296) ```bash import { query } from "@anthropic-ai/claude-agent-sdk"; const q = query({ prompt: "hello", options: { allowedTools: ["Read"], canUseTool: async () => ({ allow: true }) } }); for await (const msg of q) {} ``` ```text (node:3) [CLAUDE_SDK_CAN_USE_TOOL_SHADOWED] Warning: canUseTool will not be invoked for: Read. Bare allowedTools entries auto-approve the whole tool before the callback is consulted. To gate every tool call, use a PreToolUse hook; or remove the bare names from allowedTools so they fall through to canUseTool. Allow rules from settings files can also shadow the callback but are not visible here. ``` Fix: Remove bare tool names from `allowedTools` to allow calls to be evaluated by `canUseTool`, or use a `PreToolUse` hook to enforce fine-grained inspection on all tool calls. ([source](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.198)) ### `query()` fails immediately with `Not logged in` if credentials are not configured (Claude Agent SDK 0.3.296) ```bash import { query } from "@anthropic-ai/claude-agent-sdk"; const q = query({ prompt: "hello" }); for await (const msg of q) {} ``` ```text caught: Error Claude Code returned an error result: Not logged in · Please run /login ``` Fix: Set the `ANTHROPIC_API_KEY` environment variable in the process running the SDK, or run `claude /login` to configure OAuth credentials before initializing the query generator. ([source](https://github.com/anthropics/claude-agent-sdk-typescript/blob/v0.3.296/README.md)) ### Removed session and assistant imports fail to compile (Claude Agent SDK 0.3.296) ```bash import { unstable_v2_createSession } from "@anthropic-ai/claude-agent-sdk"; import { AssistantSession } from "@anthropic-ai/claude-agent-sdk/assistant"; ``` ```text probe.ts(1,10): error TS2305: Module '"@anthropic-ai/claude-agent-sdk"' has no exported member 'unstable_v2_createSession'. probe.ts(2,34): error TS2307: Cannot find module '@anthropic-ai/claude-agent-sdk/assistant' or its corresponding type declarations. ``` Fix: Replace `unstable_v2_createSession` with `query({ prompt, options })`, and import supported APIs from `@anthropic-ai/claude-agent-sdk` or `@anthropic-ai/claude-agent-sdk/core`. ([source](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.142)) ## Claude Agent SDK release history by month ### 2026-10: undefined - 0.3.296: Surfaced `claude_code_version` in initialize control response and added `autoCompactWindow` to `AgentDefinition`. ([source](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.296)) - 0.3.295: Added `overageEnabled` to `SDKRateLimitInfo` and raised MCP tool search description limit to 16,384 characters. ([source](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.295)) - 0.3.292: Added `agent_id`, `parent_task_id`, and `run_id` for tracking nested background subagent execution trees. ([source](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.292)) ### 2026-09: undefined - 0.3.286: Added `sdk_mcp_manifests_parked` initialize response field and priority message turn joining. ([source](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.286)) - 0.3.257: Added `thinkingTokens` to `ModelUsage` and `resourceLinks` on MCP tool result blocks. ([source](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.257)) ### 2026-08: undefined - 0.3.221: Added strict skill option name validation and introduced `skills: 'all'` wildcard option. ([source](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.221)) - 0.3.252: Updated to parity with Claude Code v2.1.252. ([source](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.252)) ### 2026-07: undefined - 0.3.198: Added runtime warning when `canUseTool` is shadowed by `allowedTools` or `bypassPermissions`. ([source](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.198)) - 0.3.220: Updated to parity with Claude Code v2.1.220. ([source](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.220)) ### 2026-06: undefined - 0.3.160: Fixed SDK hook callbacks swallowing abort signals during `PostToolUse` execution. ([source](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.160)) - 0.3.197: Updated to parity with Claude Code v2.1.197. ([source](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.197)) ### 2026-05: undefined - 0.3.142: Removed the legacy v2 session API in favor of `query()` and switched sessions to Task tools. ([source](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.3.142)) - 0.2.141: Added Task tool schema type exports to `sdk-tools` union types. ([source](https://github.com/anthropics/claude-agent-sdk-typescript/releases/tag/v0.2.141)) ## Sources - [GitHub Releases: anthropics/claude-agent-sdk-typescript](https://github.com/anthropics/claude-agent-sdk-typescript/releases) (read 2026-10-10) - [CHANGELOG.md at v0.3.296](https://github.com/anthropics/claude-agent-sdk-typescript/blob/v0.3.296/CHANGELOG.md) (read 2026-10-10) - [npm package: @anthropic-ai/claude-agent-sdk](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk) (read 2026-10-10) - [npm download statistics: @anthropic-ai/claude-agent-sdk](https://api.npmjs.org/downloads/point/last-week/@anthropic-ai/claude-agent-sdk) (read 2026-10-10) - [PyPI package: claude-agent-sdk](https://pypi.org/project/claude-agent-sdk/) (read 2026-10-10) - [GitHub repository: anthropics/claude-agent-sdk-typescript](https://github.com/anthropics/claude-agent-sdk-typescript) (read 2026-10-10) - [Anthropic Claude Code SDK documentation](https://docs.anthropic.com/en/docs/claude-code/sdk) (read 2026-10-10) - [npm package exports at v0.3.181](https://registry.npmjs.org/@anthropic-ai/claude-agent-sdk/0.3.181) (read 2026-10-10) _Last verified: 2026-10-10._