Claude Agent SDK 0.3.296: latest version, API diff and gotchas

Claude Agent SDK 0.3.296 (2026-10-09 19:28 UTC)

• Added claude_code_version to the initialize control response so clients know the CLI version before the first turn. (source)
• Added autoCompactWindow to AgentDefinition, so a subagent can auto-compact earlier than the main conversation's window. (source)
• Fixed the sandbox option discarding an inline settings.sandbox block: the two now merge, option values win, and deny/credential lists combine. (source)
• Changed the default limit on MCP tool descriptions sent up front and on MCP server instructions from 2,048 to 4,096 characters. (source)
• Changed permission answers arriving after restart: over 4,096 updatedPermissions entries count as denial, and malformed lists are ignored as a whole. (source)

Claude Agent SDK 0.3.295 (2026-10-08 19:48 UTC)

• Added overageEnabled to SDKRateLimitInfo to indicate whether extra usage is enabled on usage-limit warnings. (source)
• Changed MCP tool descriptions loaded through tool search to be cut at 16,384 characters instead of 2,048. (source)
• Fixed assistant text blocks losing their citations in streamed responses. (source)
• Changed named option passing to Claude Code: named option values are now sent in the same argument as their flag (--flag=value). (source)
• Capped MCP Apps tool_use_result: structuredContent or _meta over 8,388,608 JSON characters is omitted. (source)

Claude Agent SDK 0.3.294 (2026-10-08 05:03 UTC)

• Updated to parity with Claude Code v2.1.294. (source)

Claude Agent SDK 0.3.293 (2026-10-07 18:10 UTC)

• Added an optional subagent_type to background_tasks_changed task entries, letting hosts inspect subagent types without pairing with task_started. (source)
• Updated to parity with Claude Code v2.1.293. (source)

Claude Agent SDK 0.3.292 (2026-10-06 18:59 UTC)

• Added agent_id to subagent assistant and user messages, matching the subagent's task_id and persisting across resumes. (source)
• Added parent_task_id to task_started events and background_tasks_changed entries, tracking the parent subagent. (source)
• Added typed sections and notes to the ListAgents tool's tool_use_result, removing the need to parse text output. (source)
• Fixed subagents with declared auto permission mode having tool calls evaluated by auto-mode classifier when auto mode is unavailable. (source)

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).

• 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

• 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).

`canUseTool` callback is bypassed when tool names are in `allowedTools` (Claude Agent SDK 0.3.296)

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) {}

(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)

`query()` fails immediately with `Not logged in` if credentials are not configured (Claude Agent SDK 0.3.296)

import { query } from "@anthropic-ai/claude-agent-sdk";
const q = query({ prompt: "hello" });
for await (const msg of q) {}

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)

Removed session and assistant imports fail to compile (Claude Agent SDK 0.3.296)

import { unstable_v2_createSession } from "@anthropic-ai/claude-agent-sdk";
import { AssistantSession } from "@anthropic-ai/claude-agent-sdk/assistant";

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)

2026-10:

• 0.3.296: Surfaced claude_code_version in initialize control response and added autoCompactWindow to AgentDefinition. (source)
• 0.3.295: Added overageEnabled to SDKRateLimitInfo and raised MCP tool search description limit to 16,384 characters. (source)
• 0.3.292: Added agent_id, parent_task_id, and run_id for tracking nested background subagent execution trees. (source)

2026-09:

• 0.3.286: Added sdk_mcp_manifests_parked initialize response field and priority message turn joining. (source)
• 0.3.257: Added thinkingTokens to ModelUsage and resourceLinks on MCP tool result blocks. (source)

2026-08:

• 0.3.221: Added strict skill option name validation and introduced skills: 'all' wildcard option. (source)
• 0.3.252: Updated to parity with Claude Code v2.1.252. (source)

2026-07:

• 0.3.198: Added runtime warning when canUseTool is shadowed by allowedTools or bypassPermissions. (source)
• 0.3.220: Updated to parity with Claude Code v2.1.220. (source)

2026-06:

• 0.3.160: Fixed SDK hook callbacks swallowing abort signals during PostToolUse execution. (source)
• 0.3.197: Updated to parity with Claude Code v2.1.197. (source)

2026-05:

• 0.3.142: Removed the legacy v2 session API in favor of query() and switched sessions to Task tools. (source)
• 0.2.141: Added Task tool schema type exports to sdk-tools union types. (source)