pypi / claude-agent-sdk

claude-agent-sdk

What changed in claude-agent-sdk 0.1 to 0.2, from its official release notes, upgrade guides and advisories. Sources checked 2026-10-20.

9 breaking2 security2 deprecations123 new APIs and options7 behavior and defaults10 tooling61 fixes and other

See which of these apply to your code, ranked, in your agent:

npx @unstale/cli init

@unstale/cli on npm

claude-agent-sdk 0.251 changes

Breaking changes 8

Changed ignoreViolations to dict[str, list[str]] to match the CLI schema, allowing command-pattern substrings to map to violation-text substrings.
0.2.166release notes
Skill names are validated at connect time and malformed or delimiter-carrying values raise ValueError, preventing --allowedTools injection; replace wildcard strings with skills="all" or a Skill(...) rule in allowed_tools.
0.2.129release notes
On Windows, resume values containing cmd.exe metacharacters or newlines now raise ValueError, preventing injection if a cmd.exe hop is reintroduced.
0.2.124release notes
On Windows, session_id values containing cmd.exe metacharacters or newlines now raise ValueError, preventing injection if a cmd.exe hop is reintroduced.
0.2.124release notes
Spawning .bat and .cmd CLI scripts is blocked on Windows to prevent command injection; users of npm's claude.cmd shim should switch to a native installer, explicit claude.exe path, or platform wheel that bundles the CLI.
0.2.124release notes
MCP servers connect in the background by default, so sessions start immediately and slow servers report status: "pending" in init. Set MCP_CONNECTION_NONBLOCKING=0 to restore waiting up to 5s, or use alwaysLoad: true to require a server in turn 1.
0.2.82release notes
The field type is narrowed from list[Any] | None to list[dict[str, Any]] | None, enabling proper type-checking for consumers.
0.2.82release notes
Headless and SDK sessions use Task tools instead of TodoWrite. Tool consumers should accumulate tasks by task ID rather than replacing a snapshot list.
0.2.82release notes

Security 1

The --resume value is passed as a single =-joined argv token so a dash-prefixed value is not misinterpreted as an independent CLI flag.
0.2.121release notes security advisory

New APIs and options 20

Added typed output classes and missing input fields for hooks, giving hook implementations precise type information instead of untyped dicts.
0.2.166release notes
Typed the init system message payload, including nested types, so developers can cast msg.data and access fields such as capabilities, model, and mcp_servers.
0.2.166release notes
Sets a bounded wait ceiling for background activity; the default is 10 minutes, preventing indefinite hangs.
0.2.160release notes
Added verbatim_prompts, defaulting to False. When True, user messages reach the CLI unchanged, preventing @path expansion and slash-command dispatch.
0.2.158release notes
Adds a new typed dict for custom system prompts.
0.2.153release notes
Adds a snapshot field to control whether resumed sessions keep the system prompt from the first request or rebuild it on every request.
0.2.153release notes
A new ClaudeAgentOptions boolean forwards a subagent's text and thinking blocks as stream messages, allowing consumers to render the full nested transcript.
0.2.140release notes
In-process SDK MCP servers support mcp 2.x alongside 1.x, using mcp's in-memory transport so hand-built servers work at full fidelity; tool cancellation on interrupt is also supported on mcp 2.x.
0.2.140release notes
The SDK raises ResultError, a ProcessError subclass, after the CLI exits following a terminal error result; its structured payload lets callers branch on failure reason without string matching.
0.2.140release notes
SessionMessage gains a parent_agent_id field containing the spawning agent's id.
0.2.140release notes
Adds a guard to validate that only entries from a specific turn are discarded during resume.
0.2.137release notes
Adds an option to fork a session at an earlier transcript entry, enabling a rewind without silently dropping unobserved messages.
0.2.137release notes
The SDK surfaces conversation reset events as a message with conversation and session identifiers, so applications can detect transcript-discarding flows. The Message union is widened.
0.2.137release notes
Exports types for representing message origin and its kinds, including task notification subkinds.
0.2.137release notes
Adds an origin field that identifies why a turn was initiated, distinguishing application-submitted prompts from session-injected turns.
0.2.137release notes
Adds an origin field that identifies why a turn was initiated, distinguishing application-submitted prompts from session-injected turns.
0.2.137release notes
Types model_usage as dict[str, ModelUsage] instead of dict[str, Any]; the new ModelUsage TypedDict includes optional canonicalModel and provider fields.
0.2.126release notes
Adds terminal_reason to report why the query loop ended, including whether the turn was cancelled via ClaudeSDKClient.interrupt().
0.2.126release notes
Adds a type for task_updated status values, supporting reliable active-task bookkeeping.
0.2.101release notes
A public type alias for Claude effort string levels is exported from the package root for downstream SDK wrappers and type annotations.
0.2.82release notes

Behavior and default changes 2

The permission callback now works with string prompts as well as ClaudeSDKClient; stdin remains open so the CLI can send permission requests over the control protocol.
0.2.140release notes
ToolAnnotations accepts both camelCase and snake_case hint names on every mcp version.
0.2.140release notes

Tooling 5

The bundled Claude CLI was updated to version 2.1.300.
0.2.167release notes
The bundled Claude CLI was updated, which may affect SDK users running it.
0.2.151release notes release notes
The bundled Claude CLI was updated; the notes do not specify what changed for developers.
0.2.135release notes
The bundled Claude CLI was updated, which may affect the CLI behavior used by the SDK.
0.2.106release notes
The bundled Claude CLI was updated to version 2.1.172.
0.2.96release notes

Fixes and other changes 15

The SDK keeps stdin open until the CLI reports idle, preventing follow-up turns from failing when a background subagent finishes just before the turn result arrives.
0.2.160release notes
Subagent transcript readers now recover parent_tool_use_id from metadata, linking each subagent's messages to the Agent tool_use block in the parent session.
0.2.140release notes
Pending control requests now receive the CLI's actual resume rejection error instead of a generic command-failed message.
0.2.137release notes
Resuming from a SessionStore now copies settings files into the temporary config directory, preserving authentication, hooks, environment variables, and permissions.
0.2.137release notes
Keeps stdin open until all in-flight background tasks complete and the final result frame arrives, preventing SDK-MCP tool calls from failing and PreToolUse hooks from being bypassed.
0.2.127release notes
Values starting with - are now passed using --flag=value form, preventing them from being misinterpreted as separate CLI flags.
0.2.124release notes
The --session-id value is passed as a single =-joined argv token so a dash-prefixed value is not misinterpreted as an independent CLI flag.
0.2.121release notes
A runtime warning is now emitted when a can_use_tool callback is registered alongside allowed_tools or bypassPermissions, which silently prevents the callback from firing.
0.2.111release notes
Fixed an uncaught TypeError when the CLI emits a message whose content is a plain string or another non-dict value instead of a list of content blocks.
0.2.111release notes
Fixed whitespace loss when a single NDJSON line exceeds the 64 KiB stream buffer, avoiding corruption of tool output or assistant message content.
0.2.111release notes
Subprocess cleanup is shielded from asyncio cancellation so SIGTERM/SIGKILL teardown runs and prevents orphaned claude child processes when the parent task is cancelled.
0.2.111release notes
Terminal system/task_updated events are exposed as typed messages with task_id, patch, status, session_id, and uuid fields, preventing active-task tracking from hanging when no TaskNotificationMessage follows.
0.2.101release notes
Adds a frozenset of terminal task statuses for reliable active-task bookkeeping.
0.2.101release notes
Fixed crashes when passing session_store= to query() or ClaudeSDKClient under trio by porting session store code paths from asyncio primitives to anyio.
0.2.88release notes
Exceptions from a user-provided stderr callback are caught per line, so a failing callback no longer stops delivery of subsequent stderr lines for the session.
0.2.82release notes

claude-agent-sdk 0.1163 changes

Breaking changes 1

Stderr piping now depends solely on whether a stderr callback is registered; detection of --debug-to-stderr was dropped from the transport layer.
0.1.65release notes

Security 1

Added tag_session() with Unicode sanitization.
0.1.49release notes

Deprecations 2

Using Skill in allowed_tools is deprecated in favor of the skills option on ClaudeAgentOptions.
0.1.77release notes
The field is deprecated in favor of the new thinking field, which takes precedence.
0.1.36release notes

New APIs and options 103

The skills option provides more granular control over available skills.
0.1.77release notes
Adds the HTTP status code from failing API calls to result messages, providing a safe-to-log field for classifying errors when is_error=True.
0.1.76release notes
Added xhigh as an effort level, with fallback to high on models other than Opus 4.7.
0.1.74release notes
Added xhigh as an effort level, with fallback to high on models other than Opus 4.7.
0.1.74release notes
Added include_hook_events to emit hook events from the CLI and yield them from the message stream as HookEventMessage.
0.1.74release notes
When True, the CLI uses only MCP servers passed via mcp_servers, ignoring project, user, and global MCP configurations for deterministic server sets.
0.1.74release notes
Added updatedToolOutput to replace any tool's output before it reaches the model, not just MCP tools.
0.1.74release notes
Added support for the defer hook decision in permissionDecision.
0.1.74release notes
Added the DeferredToolUse dataclass on deferred_tool_use for deferred tool use round trips.
0.1.74release notes
Added decision_reason, blocked_path, title, display_name, and description fields to enable richer permission prompts in can_use_tool callbacks.
0.1.74release notes
Adds the session_store_flush option with batched or eager modes; eager delivers transcript frames to SessionStore.append() in near-real-time instead of waiting for the end-of-turn flush.
0.1.73release notes
Added domain allowlist and network lookup fields, enabling Python SDK users to configure network allowlists with proper type hints.
0.1.71release notes
Adds a content block type that surfaces results from server-executed tools that were previously silently dropped.
0.1.65release notes
Adds a helper for O(1)-per-session list views using summary sidecars.
0.1.65release notes
Replays a local on-disk session into any SessionStore adapter, enabling migration from local storage to remote stores.
0.1.65release notes
Adds a content block type that surfaces server-executed tool calls, such as advisor and web_search, that were previously silently dropped.
0.1.65release notes
Adds an optional protocol method so stores with append-time summary sidecars can serve list_session_summaries without loading full transcripts, reducing round-trips from N to 1 for N sessions.
0.1.65release notes
Adds a display field forwarded as --thinking-display, letting callers override Opus 4.7's default "omitted" behavior and receive summarized thinking text.
0.1.65release notes
Adds a store-backed helper for forking a session.
0.1.64release notes
Adds an in-memory reference implementation of SessionStore.
0.1.64release notes
Adds a store-backed helper for listing sessions.
0.1.64release notes
Adds transcript mirroring via --session-mirror.
0.1.64release notes
Adds the ability to resume a session from a SessionStore.
0.1.64release notes
Adds a SessionStore protocol with append, load, list_sessions, delete, and list_subkeys methods, bringing Python support to parity with the TypeScript SDK.
0.1.64release notes
Added a top-level ClaudeAgentOptions parameter to enable all discovered skills, selected named skills, or no skills without manually configuring allowed_tools and setting_sources.
0.1.62release notes
Adds a session helper for reading subagent transcripts and inspecting subagent message chains.
0.1.60release notes
Adds a session helper for listing subagents spawned during a session.
0.1.60release notes
Adds "auto" to PermissionMode, bringing parity with the TypeScript SDK and CLI v2.1.90+.
0.1.57release notes
Adds exclude_dynamic_sections to move per-user dynamic sections out of the system prompt, enabling cross-user prompt cache hits.
0.1.57release notes
Added a session_id option for specifying custom session IDs.
0.1.52release notes
Added a ClaudeSDKClient method for querying context window usage by category.
0.1.52release notes
Exposed agent_id in ToolPermissionContext to distinguish parallel permission requests.
0.1.52release notes
Exposed tool_use_id in ToolPermissionContext to distinguish parallel permission requests.
0.1.52release notes
The @tool decorator and create_sdk_mcp_server support per-parameter descriptions in JSON Schema using typing.Annotated.
0.1.52release notes
Adds the disallowedTools field to AgentDefinition.
0.1.51release notes
Adds the initialPrompt field to AgentDefinition.
0.1.51release notes
Adds the maxTurns field to AgentDefinition.
0.1.51release notes
Adds an API to delete a session.
0.1.51release notes
Adds an API to fork a session.
0.1.51release notes
Adds offset-based pagination for session listing.
0.1.51release notes
Adds CLI support for specifying a system prompt file via SystemPromptFile.
0.1.51release notes
Adds a task_budget option for token budget management.
0.1.51release notes
Adds a function for retrieving session metadata.
0.1.50release notes
Adds the created_at field to SDKSessionInfo for session metadata.
0.1.50release notes
Adds the tag field to SDKSessionInfo for session metadata.
0.1.50release notes
Added the mcpServers field to AgentDefinition.
0.1.49release notes
Added the memory field to AgentDefinition.
0.1.49release notes
Added the skills field to AgentDefinition.
0.1.49release notes
Added a typed RateLimitEvent message.
0.1.49release notes
Added rename_session() for session renaming.
0.1.49release notes
Added a method for runtime MCP server management.
0.1.46release notes
Added a top-level function for retrieving past session data.
0.1.46release notes
Added a top-level function for retrieving past session data.
0.1.46release notes
Added a typed status for runtime MCP server management.
0.1.46release notes
Added the agent_id field to tool-lifecycle hook inputs.
0.1.46release notes
Added the agent_type field to tool-lifecycle hook inputs.
0.1.46release notes
Added the agent_id field to tool-lifecycle hook inputs.
0.1.46release notes
Added the agent_type field to tool-lifecycle hook inputs.
0.1.46release notes
Added the agent_id field to tool-lifecycle hook inputs.
0.1.46release notes
Added the agent_type field to tool-lifecycle hook inputs.
0.1.46release notes
Added a method for runtime MCP server management.
0.1.46release notes
Added a field for inspecting why a conversation turn ended.
0.1.46release notes
Added a message subclass for better type safety when handling task-related events.
0.1.46release notes
Added a message subclass for better type safety when handling task-related events.
0.1.46release notes
Added a message subclass for better type safety when handling task-related events.
0.1.46release notes
Adds a ClaudeAgentOptions field accepting low, medium, high, or max to control thinking depth.
0.1.36release notes
Adds a ClaudeAgentOptions field for fine-grained control over extended thinking, taking precedence over max_thinking_tokens.
0.1.36release notes
The @tool decorator accepts an annotations parameter for MCP tool metadata hints such as readOnlyHint and destructiveHint.
0.1.31release notes
ToolAnnotations is re-exported from claude_agent_sdk for convenient access to MCP tool annotation types.
0.1.31release notes
Adds the Notification hook event, with NotificationHookInput and NotificationHookSpecificOutput, for handling notification events.
0.1.29release notes
Adds the PermissionRequest hook event, with PermissionRequestHookInput and PermissionRequestHookSpecificOutput, for handling permission requests.
0.1.29release notes
Adds the tool_use_id field to PostToolUseHookInput.
0.1.29release notes
Adds the updatedMCPToolOutput field to PostToolUseHookSpecificOutput.
0.1.29release notes
Adds the tool_use_id field to PreToolUseHookInput.
0.1.29release notes
Adds the additionalContext field to PreToolUseHookSpecificOutput.
0.1.29release notes
Adds the SubagentStart hook event, with SubagentStartHookInput and SubagentStartHookSpecificOutput, for handling subagent startup.
0.1.29release notes
Adds the agent_id field to SubagentStopHookInput.
0.1.29release notes
Adds the agent_transcript_path field to SubagentStopHookInput.
0.1.29release notes
Adds the agent_type field to SubagentStopHookInput.
0.1.29release notes
Adds a hook event for handling tool use failures.
0.1.26release notes
Adds the input type for the PostToolUseFailure hook event.
0.1.26release notes
Adds the hook-specific output type for the PostToolUseFailure event.
0.1.26release notes
Added a public ClaudeSDKClient method for querying MCP server connection status without accessing private internals.
0.1.23release notes
Adds a UUID to the UserMessage response type to improve developer experience for rewind.
0.1.17release notes
Adds an option to enable file checkpointing.
0.1.15release notes
Adds support for rewinding files.
0.1.15release notes
Adds the betas option to support SDK betas.
0.1.12release notes
Adds a tools option to ClaudeAgentOptions.
0.1.12release notes
Adds the SdkBeta type for SDK beta support.
0.1.12release notes
A sandbox adapter interface was created for the Python SDK.
0.1.11release notes
When present, this environment variable overrides the initialize() timeout.
0.1.10release notes
Adds the AssistantMessageError type.
0.1.9release notes
Adds a timeout parameter to HookMatcher.
0.1.9release notes
The pip package now bundles the Claude Code CLI, so installing the package includes the CLI.
0.1.8release notes
The SDK now supports the Claude CLI located at ~/.claude/local/claude.
0.1.7release notes
Structured output support was added.
0.1.7release notes
Adds the max_thinking_tokens option to ClaudeAgentOptions.
0.1.6release notes
Adds the /generate-changelog slash command.
0.1.6release notes
Adds the max_budget_usd option to the Python SDK.
0.1.6release notes
The Python SDK adds plugin support, allowing developers to use plugins with the SDK.
0.1.5release notes
Adds base64 image handling to sdk_mcp_server tool calling.
0.1.4release notes
Adds an environment variable for skipping the SDK version check.
0.1.4release notes
Adds cli_path support to ClaudeAgentOptions, allowing developers to configure the CLI path.
0.1.4release notes

Behavior and default changes 5

Propagates TRACEPARENT and TRACESTATE to the CLI subprocess when an OpenTelemetry span is active, connecting SDK and CLI traces end-to-end.
0.1.60release notes
Preserves dropped fields on AssistantMessage for forward compatibility.
0.1.51release notes
Preserves dropped fields on ResultMessage for forward compatibility.
0.1.51release notes
Fallback model handling was added for parity with the TypeScript SDK.
0.1.7release notes
Uses an empty system prompt by default.
0.1.6release notes

Tooling 5

Adds a 13-contract conformance test harness for third-party SessionStore adapter authors.
0.1.64release notes
Added a macOS x86_64 wheel to the published matrix.
0.1.49release notes
The bundled Claude CLI was updated; SDK users receive the newer bundled version.
0.1.33release notes release notes
The SDK now bundles Claude CLI version 2.1.9.
0.1.20release notes
The claude code CLI is bundled for linux arm64.
0.1.11release notes

Fixes and other changes 46

Exceptions raised after an error result now carry the result's actual error text instead of the generic exit-code message.
0.1.77release notes
Suggestions are deserialized as PermissionUpdate instances instead of raw dicts, so they can be inspected and echoed back in PermissionResultAllow without AttributeError.
0.1.76release notes
Fixed an unclosed MemoryObjectReceiveStream ResourceWarning on disconnect by closing the receive stream at the consumer boundary.
0.1.74release notes
An atexit handler terminates live CLI subprocesses when the parent process exits, preventing orphaned claude processes from leaking.
0.1.74release notes
Fixed list_sessions returning created_at=None when the first JSONL record lacks a timestamp, by scanning the full head buffer.
0.1.74release notes
Fixed a Trio nursery stack corruption error when breaking out of query() iteration inside a nursery with options.stderr set.
0.1.70release notes
Fixed a no-running-event-loop error when using ClaudeSDKClient or query() under trio.
0.1.67release notes
Deleting a session now also removes its sibling subagent transcript directory.
0.1.60release notes
An empty list now passes --setting-sources= to disable all filesystem settings instead of loading default settings.
0.1.60release notes
Adaptive and disabled thinking configurations now map to the corresponding --thinking CLI arguments instead of --max-thinking-tokens values.
0.1.57release notes
Forwards maxResultSizeChars from ToolAnnotations via _meta, preventing silent truncation of large MCP tool results in the CLI.
0.1.55release notes
Using query() with a string prompt no longer deadlocks when hooks or MCP servers trigger many tool calls.
0.1.53release notes
When omitted, --setting-sources is no longer passed as an empty string, preventing the CLI from misparsing subsequent flags.
0.1.53release notes
Fixed connect(prompt="...") silently dropping the string prompt, which caused receive_messages() to hang indefinitely.
0.1.52release notes
In-flight hook callbacks are properly cancelled when the CLI abandons them.
0.1.52release notes
Fixes a cross-task cancel scope RuntimeError during async generator cleanup.
0.1.51release notes
Filters the CLAUDECODE environment variable from the subprocess environment.
0.1.51release notes
Defers CLI discovery to connect() to avoid blocking async event loops.
0.1.51release notes
Skips non-JSON lines on CLI stdout to prevent buffer corruption.
0.1.51release notes
Adds a SIGKILL fallback when the SIGTERM handler blocks during close().
0.1.51release notes
Adds the missing dontAsk permission mode to the types.
0.1.51release notes
Passes initialize_timeout from the environment variable in query().
0.1.51release notes
Converts TypedDict input_schema values to proper JSON Schema in SDK MCP tools.
0.1.51release notes
Retries install.sh fetches on HTTP 429 with pipefail and jitter.
0.1.51release notes
Propagates the is_error flag from SDK MCP tool results.
0.1.51release notes
Uses typing_extensions.TypedDict on Python 3.10 to support NotRequired.
0.1.51release notes
Handles resource_link and embedded resource content types in SDK MCP tools.
0.1.51release notes
Adds the missing errors field to ResultMessage.
0.1.51release notes
Removes the stdin timeout for hooks and SDK MCP servers.
0.1.51release notes
Removes a duplicate version warning and includes the CLI path.
0.1.51release notes
Per-turn usage is now preserved on AssistantMessage.
0.1.49release notes
Now uses default-if-absent semantics to match the TS SDK.
0.1.49release notes
The env-var workaround was reverted; partial-message delivery is now handled upstream.
0.1.49release notes
Fixed include_partial_messages=True not delivering input_json_delta events by enabling fine-grained tool streaming in the subprocess.
0.1.48release notes
Fixed string prompts closing stdin before MCP server initialization completed, which caused MCP servers to fail to register.
0.1.46release notes
Unrecognized CLI message types are now silently skipped instead of raising MessageParseError and crashing the session, enabling forward compatibility with future CLI message types.
0.1.40release notes
Large agent definitions are sent through the initialize control request via stdin, avoiding platform-specific CLI argument size limits that could silently prevent registration.
0.1.31release notes
Fixed the error field not being populated; it is now read from the top level of the response.
0.1.28release notes
The error field is parsed, enabling rate limit detection.
0.1.16release notes
CLI errors are propagated to pending control requests.
0.1.13release notes
A write lock prevents concurrent transport writes.
0.1.13release notes
Adds a runtime placeholder for Pydantic 2.12+ compatibility.
0.1.13release notes
When SDK MCP is present, the SDK waits for the first result before closing stdin.
0.1.11release notes
Fixes the type of HookMatcher.timeout to float.
0.1.10release notes
Windows CLI downloads now use the PowerShell installer.
0.1.8release notes
Handles the Windows command line length limit for the --agents option.
0.1.4release notes