# What changed in claude-agent-sdk

> 214 changes in claude-agent-sdk 0.1 to 0.2 from its official release notes, upgrade guides and advisories: 9 breaking, 2 deprecations, 2 security, 123 new APIs and options. Each one cited. Sources checked 2026-10-20. HTML: https://unstale.sh/pypi/claude-agent-sdk/

To see which of these apply to a repository, run `npx @unstale/cli init` in it.

## claude-agent-sdk 0.2

### Breaking changes

- Changed ignoreViolations to dict[str, list[str]] to match the CLI schema, allowing command-pattern substrings to map to violation-text substrings. (0.2.166) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.2.166)
- 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.129) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.2.129)
- On Windows, resume values containing cmd.exe metacharacters or newlines now raise ValueError, preventing injection if a cmd.exe hop is reintroduced. (0.2.124) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.2.124)
- 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.124) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.2.124)
- 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.124) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.2.124)
- 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.82) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.2.82)
- The field type is narrowed from list[Any] | None to list[dict[str, Any]] | None, enabling proper type-checking for consumers. (0.2.82) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.2.82)
- 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.82) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.2.82)

### Security

- 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.121) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.2.121), [security advisory](https://github.com/advisories/GHSA-H4MW-J7QP-8MWM)

### New APIs and options

- Added typed output classes and missing input fields for hooks, giving hook implementations precise type information instead of untyped dicts. (0.2.166) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.2.166)
- 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.166) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.2.166)
- Sets a bounded wait ceiling for background activity; the default is 10 minutes, preventing indefinite hangs. (0.2.160) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.2.160)
- Added verbatim_prompts, defaulting to False. When True, user messages reach the CLI unchanged, preventing @path expansion and slash-command dispatch. (0.2.158) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.2.158)
- Adds a new typed dict for custom system prompts. (0.2.153) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.2.153)
- 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.153) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.2.153)
- 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.140) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.2.140)
- 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.140) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.2.140)
- 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.140) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.2.140)
- SessionMessage gains a parent_agent_id field containing the spawning agent's id. (0.2.140) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.2.140)
- Adds a guard to validate that only entries from a specific turn are discarded during resume. (0.2.137) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.2.137)
- Adds an option to fork a session at an earlier transcript entry, enabling a rewind without silently dropping unobserved messages. (0.2.137) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.2.137)
- 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.137) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.2.137)
- Exports types for representing message origin and its kinds, including task notification subkinds. (0.2.137) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.2.137)
- Adds an origin field that identifies why a turn was initiated, distinguishing application-submitted prompts from session-injected turns. (0.2.137) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.2.137)
- Adds an origin field that identifies why a turn was initiated, distinguishing application-submitted prompts from session-injected turns. (0.2.137) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.2.137)
- Types model_usage as dict[str, ModelUsage] instead of dict[str, Any]; the new ModelUsage TypedDict includes optional canonicalModel and provider fields. (0.2.126) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.2.126)
- Adds terminal_reason to report why the query loop ended, including whether the turn was cancelled via ClaudeSDKClient.interrupt(). (0.2.126) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.2.126)
- Adds a type for task_updated status values, supporting reliable active-task bookkeeping. (0.2.101) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.2.101)
- A public type alias for Claude effort string levels is exported from the package root for downstream SDK wrappers and type annotations. (0.2.82) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.2.82)

### Behavior and default changes

- 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.140) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.2.140)
- ToolAnnotations accepts both camelCase and snake_case hint names on every mcp version. (0.2.140) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.2.140)

### Tooling

- The bundled Claude CLI was updated to version 2.1.300. (0.2.167) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.2.167)
- The bundled Claude CLI was updated, which may affect SDK users running it. (0.2.151) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.2.159), [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.2.151)
- The bundled Claude CLI was updated; the notes do not specify what changed for developers. (0.2.135) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.2.135)
- The bundled Claude CLI was updated, which may affect the CLI behavior used by the SDK. (0.2.106) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.2.106)
- The bundled Claude CLI was updated to version 2.1.172. (0.2.96) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.2.96)

### Fixes and other changes

- 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.160) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.2.160)
- 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.140) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.2.140)
- Pending control requests now receive the CLI's actual resume rejection error instead of a generic command-failed message. (0.2.137) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.2.137)
- Resuming from a SessionStore now copies settings files into the temporary config directory, preserving authentication, hooks, environment variables, and permissions. (0.2.137) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.2.137)
- 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.127) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.2.127)
- Values starting with - are now passed using --flag=value form, preventing them from being misinterpreted as separate CLI flags. (0.2.124) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.2.124)
- 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.121) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.2.121)
- 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.111) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.2.111)
- 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.111) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.2.111)
- 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.111) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.2.111)
- 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.111) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.2.111)
- 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.101) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.2.101)
- Adds a frozenset of terminal task statuses for reliable active-task bookkeeping. (0.2.101) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.2.101)
- 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.88) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.2.88)
- 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.82) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.2.82)

## claude-agent-sdk 0.1

### Breaking changes

- 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.65) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.65)

### Security

- Added tag_session() with Unicode sanitization. (0.1.49) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.49)

### Deprecations

- Using `Skill` in `allowed_tools` is deprecated in favor of the `skills` option on `ClaudeAgentOptions`. (0.1.77) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.77)
- The field is deprecated in favor of the new thinking field, which takes precedence. (0.1.36) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.36)

### New APIs and options

- The `skills` option provides more granular control over available skills. (0.1.77) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.77)
- 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.76) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.76)
- Added xhigh as an effort level, with fallback to high on models other than Opus 4.7. (0.1.74) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.74)
- Added xhigh as an effort level, with fallback to high on models other than Opus 4.7. (0.1.74) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.74)
- Added include_hook_events to emit hook events from the CLI and yield them from the message stream as HookEventMessage. (0.1.74) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.74)
- 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.74) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.74)
- Added updatedToolOutput to replace any tool's output before it reaches the model, not just MCP tools. (0.1.74) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.74)
- Added support for the defer hook decision in permissionDecision. (0.1.74) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.74)
- Added the DeferredToolUse dataclass on deferred_tool_use for deferred tool use round trips. (0.1.74) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.74)
- Added decision_reason, blocked_path, title, display_name, and description fields to enable richer permission prompts in can_use_tool callbacks. (0.1.74) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.74)
- 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.73) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.73)
- Added domain allowlist and network lookup fields, enabling Python SDK users to configure network allowlists with proper type hints. (0.1.71) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.71)
- Adds a content block type that surfaces results from server-executed tools that were previously silently dropped. (0.1.65) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.65)
- Adds a helper for O(1)-per-session list views using summary sidecars. (0.1.65) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.65)
- Replays a local on-disk session into any SessionStore adapter, enabling migration from local storage to remote stores. (0.1.65) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.65)
- Adds a content block type that surfaces server-executed tool calls, such as advisor and web_search, that were previously silently dropped. (0.1.65) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.65)
- 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.65) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.65)
- 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.65) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.65)
- Adds a store-backed helper for forking a session. (0.1.64) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.64)
- Adds an in-memory reference implementation of SessionStore. (0.1.64) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.64)
- Adds a store-backed helper for listing sessions. (0.1.64) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.64)
- Adds transcript mirroring via --session-mirror. (0.1.64) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.64)
- Adds the ability to resume a session from a SessionStore. (0.1.64) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.64)
- 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.64) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.64)
- 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.62) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.62)
- Adds a session helper for reading subagent transcripts and inspecting subagent message chains. (0.1.60) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.60)
- Adds a session helper for listing subagents spawned during a session. (0.1.60) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.60)
- Adds "auto" to PermissionMode, bringing parity with the TypeScript SDK and CLI v2.1.90+. (0.1.57) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.57)
- Adds exclude_dynamic_sections to move per-user dynamic sections out of the system prompt, enabling cross-user prompt cache hits. (0.1.57) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.57)
- Added a session_id option for specifying custom session IDs. (0.1.52) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.52)
- Added a ClaudeSDKClient method for querying context window usage by category. (0.1.52) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.52)
- Exposed agent_id in ToolPermissionContext to distinguish parallel permission requests. (0.1.52) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.52)
- Exposed tool_use_id in ToolPermissionContext to distinguish parallel permission requests. (0.1.52) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.52)
- The @tool decorator and create_sdk_mcp_server support per-parameter descriptions in JSON Schema using typing.Annotated. (0.1.52) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.52)
- Adds the disallowedTools field to AgentDefinition. (0.1.51) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.51)
- Adds the initialPrompt field to AgentDefinition. (0.1.51) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.51)
- Adds the maxTurns field to AgentDefinition. (0.1.51) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.51)
- Adds an API to delete a session. (0.1.51) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.51)
- Adds an API to fork a session. (0.1.51) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.51)
- Adds offset-based pagination for session listing. (0.1.51) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.51)
- Adds CLI support for specifying a system prompt file via SystemPromptFile. (0.1.51) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.51)
- Adds a task_budget option for token budget management. (0.1.51) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.51)
- Adds a function for retrieving session metadata. (0.1.50) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.50)
- Adds the created_at field to SDKSessionInfo for session metadata. (0.1.50) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.50)
- Adds the tag field to SDKSessionInfo for session metadata. (0.1.50) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.50)
- Added the mcpServers field to AgentDefinition. (0.1.49) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.49)
- Added the memory field to AgentDefinition. (0.1.49) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.49)
- Added the skills field to AgentDefinition. (0.1.49) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.49)
- Added a typed RateLimitEvent message. (0.1.49) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.49)
- Added rename_session() for session renaming. (0.1.49) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.49)
- Added a method for runtime MCP server management. (0.1.46) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.46)
- Added a top-level function for retrieving past session data. (0.1.46) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.46)
- Added a top-level function for retrieving past session data. (0.1.46) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.46)
- Added a typed status for runtime MCP server management. (0.1.46) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.46)
- Added the `agent_id` field to tool-lifecycle hook inputs. (0.1.46) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.46)
- Added the `agent_type` field to tool-lifecycle hook inputs. (0.1.46) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.46)
- Added the `agent_id` field to tool-lifecycle hook inputs. (0.1.46) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.46)
- Added the `agent_type` field to tool-lifecycle hook inputs. (0.1.46) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.46)
- Added the `agent_id` field to tool-lifecycle hook inputs. (0.1.46) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.46)
- Added the `agent_type` field to tool-lifecycle hook inputs. (0.1.46) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.46)
- Added a method for runtime MCP server management. (0.1.46) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.46)
- Added a field for inspecting why a conversation turn ended. (0.1.46) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.46)
- Added a message subclass for better type safety when handling task-related events. (0.1.46) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.46)
- Added a message subclass for better type safety when handling task-related events. (0.1.46) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.46)
- Added a message subclass for better type safety when handling task-related events. (0.1.46) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.46)
- Adds a ClaudeAgentOptions field accepting low, medium, high, or max to control thinking depth. (0.1.36) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.36)
- Adds a ClaudeAgentOptions field for fine-grained control over extended thinking, taking precedence over max_thinking_tokens. (0.1.36) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.36)
- The @tool decorator accepts an annotations parameter for MCP tool metadata hints such as readOnlyHint and destructiveHint. (0.1.31) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.31)
- ToolAnnotations is re-exported from claude_agent_sdk for convenient access to MCP tool annotation types. (0.1.31) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.31)
- Adds the Notification hook event, with NotificationHookInput and NotificationHookSpecificOutput, for handling notification events. (0.1.29) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.29)
- Adds the PermissionRequest hook event, with PermissionRequestHookInput and PermissionRequestHookSpecificOutput, for handling permission requests. (0.1.29) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.29)
- Adds the tool_use_id field to PostToolUseHookInput. (0.1.29) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.29)
- Adds the updatedMCPToolOutput field to PostToolUseHookSpecificOutput. (0.1.29) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.29)
- Adds the tool_use_id field to PreToolUseHookInput. (0.1.29) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.29)
- Adds the additionalContext field to PreToolUseHookSpecificOutput. (0.1.29) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.29)
- Adds the SubagentStart hook event, with SubagentStartHookInput and SubagentStartHookSpecificOutput, for handling subagent startup. (0.1.29) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.29)
- Adds the agent_id field to SubagentStopHookInput. (0.1.29) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.29)
- Adds the agent_transcript_path field to SubagentStopHookInput. (0.1.29) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.29)
- Adds the agent_type field to SubagentStopHookInput. (0.1.29) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.29)
- Adds a hook event for handling tool use failures. (0.1.26) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.26)
- Adds the input type for the PostToolUseFailure hook event. (0.1.26) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.26)
- Adds the hook-specific output type for the PostToolUseFailure event. (0.1.26) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.26)
- Added a public ClaudeSDKClient method for querying MCP server connection status without accessing private internals. (0.1.23) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.23)
- Adds a UUID to the UserMessage response type to improve developer experience for rewind. (0.1.17) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.17)
- Adds an option to enable file checkpointing. (0.1.15) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.15)
- Adds support for rewinding files. (0.1.15) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.15)
- Adds the betas option to support SDK betas. (0.1.12) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.12)
- Adds a tools option to ClaudeAgentOptions. (0.1.12) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.12)
- Adds the SdkBeta type for SDK beta support. (0.1.12) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.12)
- A sandbox adapter interface was created for the Python SDK. (0.1.11) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.11)
- When present, this environment variable overrides the initialize() timeout. (0.1.10) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.10)
- Adds the AssistantMessageError type. (0.1.9) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.9)
- Adds a timeout parameter to HookMatcher. (0.1.9) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.9)
- The pip package now bundles the Claude Code CLI, so installing the package includes the CLI. (0.1.8) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.8)
- The SDK now supports the Claude CLI located at ~/.claude/local/claude. (0.1.7) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.7)
- Structured output support was added. (0.1.7) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.7)
- Adds the max_thinking_tokens option to ClaudeAgentOptions. (0.1.6) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.6)
- Adds the /generate-changelog slash command. (0.1.6) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.6)
- Adds the max_budget_usd option to the Python SDK. (0.1.6) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.6)
- The Python SDK adds plugin support, allowing developers to use plugins with the SDK. (0.1.5) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.5)
- Adds base64 image handling to sdk_mcp_server tool calling. (0.1.4) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.4)
- Adds an environment variable for skipping the SDK version check. (0.1.4) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.4)
- Adds cli_path support to ClaudeAgentOptions, allowing developers to configure the CLI path. (0.1.4) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.4)

### Behavior and default changes

- Propagates TRACEPARENT and TRACESTATE to the CLI subprocess when an OpenTelemetry span is active, connecting SDK and CLI traces end-to-end. (0.1.60) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.60)
- Preserves dropped fields on AssistantMessage for forward compatibility. (0.1.51) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.51)
- Preserves dropped fields on ResultMessage for forward compatibility. (0.1.51) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.51)
- Fallback model handling was added for parity with the TypeScript SDK. (0.1.7) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.7)
- Uses an empty system prompt by default. (0.1.6) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.6)

### Tooling

- Adds a 13-contract conformance test harness for third-party SessionStore adapter authors. (0.1.64) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.64)
- Added a macOS x86_64 wheel to the published matrix. (0.1.49) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.49)
- The bundled Claude CLI was updated; SDK users receive the newer bundled version. (0.1.33) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.2.119), [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.33)
- The SDK now bundles Claude CLI version 2.1.9. (0.1.20) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.20)
- The claude code CLI is bundled for linux arm64. (0.1.11) — [release notes](https://github.com/anthropics/claude-agent-sdk-python/releases/tag/v0.1.11)

### Fixes and other changes

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