NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
PyPI
PyPI, #601 most downloaded on PyPI
Python SDK for Claude Code
Latest stable
0.2.180
Last release 13 days ago
09 Nov 2026
Ships on a steady schedule
a new release about every 9 days
Nearly every release is documented
notes for 59 of the last 60 stable releases
55 versions withdrawn
withdrawn after publishing
1 years old
182 releases · first in 2025
Drag across the ruler to compare, or tap a release to open it.
PyPI: https://pypi.org/project/claude-agent-sdk/0.2.180/
PyPI: https://pypi.org/project/claude-agent-sdk/0.2.180/
pip install claude-agent-sdk==0.2.180
PyPI: https://pypi.org/project/claude-agent-sdk/0.2.179/
PyPI: https://pypi.org/project/claude-agent-sdk/0.2.179/
pip install claude-agent-sdk==0.2.179
Updated bundled Claude CLI to version 2.1.318
PyPI: https://pypi.org/project/claude-agent-sdk/0.2.178/
pip install claude-agent-sdk==0.2.178
Your coding agent can read these notes before it upgrades. Set up the MCP server →
`on_failure` option for `HookMatcher`: Control what happens when a hook callback fails. Set on_failure="block" to block the action when a callback rai
on_failure option for HookMatcher: Control what happens when a hook callback fails. Set on_failure="block" to block the action when a callback raises, returns None, or returns a value the CLI rejects. Defaults to "continue" (treat failure as no decision). Requires a CLI version that supports this option; connecting to an older CLI with on_failure="block" raises CLIConnectionError (#1460)Bash or PowerShell tool in shell-dependent tests, fixing intermittent failures on Windows (#1467)PyPI: https://pypi.org/project/claude-agent-sdk/0.2.177/
pip install claude-agent-sdk==0.2.177
Updated bundled Claude CLI to version 2.1.316
PyPI: https://pypi.org/project/claude-agent-sdk/0.2.176/
pip install claude-agent-sdk==0.2.176
Updated bundled Claude CLI to version 2.1.314
PyPI: https://pypi.org/project/claude-agent-sdk/0.2.175/
pip install claude-agent-sdk==0.2.175
Updated bundled Claude CLI to version 2.1.310
PyPI: https://pypi.org/project/claude-agent-sdk/0.2.174/
pip install claude-agent-sdk==0.2.174
Updated bundled Claude CLI to version 2.1.309
PyPI: https://pypi.org/project/claude-agent-sdk/0.2.173/
pip install claude-agent-sdk==0.2.173
Updated bundled Claude CLI to version 2.1.308
PyPI: https://pypi.org/project/claude-agent-sdk/0.2.172/
pip install claude-agent-sdk==0.2.172
Updated bundled Claude CLI to version 2.1.307
PyPI: https://pypi.org/project/claude-agent-sdk/0.2.171/
pip install claude-agent-sdk==0.2.171
Fixed parallel tool calls missing from session messages: get_session_messages and get_session_messages_from_store now return every tool call and resul
get_session_messages and get_session_messages_from_store now return every tool call and result from turns that ran tools in parallel. Previously only one branch of the forked transcript was followed, dropping some calls and results (#1422)PyPI: https://pypi.org/project/claude-agent-sdk/0.2.170/
pip install claude-agent-sdk==0.2.170
Clarified that include_hook_events does not suppress SessionStart and Setup hook events, which the CLI emits regardless of the setting
include_hook_events does not suppress SessionStart and Setup hook events, which the CLI emits regardless of the setting (#1336)build, twine, wheel, hatchling) so a tampered or unexpected download stops the job (#1415)PyPI: https://pypi.org/project/claude-agent-sdk/0.2.169/
pip install claude-agent-sdk==0.2.169
Updated bundled Claude CLI to version 2.1.301
PyPI: https://pypi.org/project/claude-agent-sdk/0.2.168/
pip install claude-agent-sdk==0.2.168
Updated bundled Claude CLI to version 2.1.300
PyPI: https://pypi.org/project/claude-agent-sdk/0.2.167/
pip install claude-agent-sdk==0.2.167
Hook-specific output types: Added typed output classes and missing input fields for hooks, giving hook implementations precise type information instea
SystemInitData TypedDict: The init system message payload is now fully typed via SystemInitData, along with nested types SystemInitMcpServer, SystemInitPlugin, SystemInitPluginError, and FastModeState/FastModeDisabledReason literals. Use cast(SystemInitData, msg.data) to access typed fields like capabilities, model, mcp_servers, and more (#1332)SandboxSettings.ignoreViolations type: Changed from a TypedDict with file/network keys to dict[str, list[str]] to match the CLI's actual schema — a map from command-pattern substring to violation-text substrings. The old type caused "file" and "network" to be interpreted as command patterns, and strict type checkers rejected the correct {"*": [...]} shape (#1380)PyPI: https://pypi.org/project/claude-agent-sdk/0.2.166/
pip install claude-agent-sdk==0.2.166
Updated bundled Claude CLI to version 2.1.294
PyPI: https://pypi.org/project/claude-agent-sdk/0.2.165/
pip install claude-agent-sdk==0.2.165
Updated bundled Claude CLI to version 2.1.292
PyPI: https://pypi.org/project/claude-agent-sdk/0.2.164/
pip install claude-agent-sdk==0.2.164
Updated bundled Claude CLI to version 2.1.286
PyPI: https://pypi.org/project/claude-agent-sdk/0.2.163/
pip install claude-agent-sdk==0.2.163
Updated bundled Claude CLI to version 2.1.285
PyPI: https://pypi.org/project/claude-agent-sdk/0.2.162/
pip install claude-agent-sdk==0.2.162
Updated bundled Claude CLI to version 2.1.284
PyPI: https://pypi.org/project/claude-agent-sdk/0.2.161/
pip install claude-agent-sdk==0.2.161
Fixed follow-up turns failing after background subagents: When using query() with hooks, can_use_tool, or SDK MCP servers, stdin was closed too early
query() with hooks, can_use_tool, or SDK MCP servers, stdin was closed too early if a subagent finished just before the turn's result arrived. Follow-up turns would then fail with "Stream closed" and the model would report the tool as refused. The SDK now listens for the CLI's session_state_changed messages and keeps stdin open until the CLI reports idle, matching the TypeScript SDK's behavior. A bounded wait ceiling (configurable via CLAUDE_CODE_PRINT_BG_WAIT_CEILING_MS, default 10 minutes) prevents indefinite hangs. Older CLIs without state events fall back to the previous close-at-first-result behavior. (#1190, #1279)PyPI: https://pypi.org/project/claude-agent-sdk/0.2.160/
pip install claude-agent-sdk==0.2.160
Updated bundled Claude CLI to version 2.1.281
claude-opus-5 to work around CI failures with the CLI's new default model (#1287)PyPI: https://pypi.org/project/claude-agent-sdk/0.2.159/
pip install claude-agent-sdk==0.2.159
`verbatim_prompts` option: Added ClaudeAgentOptions.verbatim_prompts (default False). When True, user messages are delivered to the CLI exactly as wri
verbatim_prompts option: Added ClaudeAgentOptions.verbatim_prompts (default False). When True, user messages are delivered to the CLI exactly as written — no @path file expansion and no slash-command dispatch. This prevents untrusted text inlined into prompts from triggering unintended file reads or command execution. Works with query(), ClaudeSDKClient.connect(), and ClaudeSDKClient.query() for both string and async-iterable prompts. Requires CLI 2.1.248+; a warning is logged on older CLIs. (#1269)PyPI: https://pypi.org/project/claude-agent-sdk/0.2.158/
pip install claude-agent-sdk==0.2.158
Nothing published for this version
Updated bundled Claude CLI to version 2.1.276
PyPI: https://pypi.org/project/claude-agent-sdk/0.2.156/
pip install claude-agent-sdk==0.2.156
Updated bundled Claude CLI to version 2.1.275
PyPI: https://pypi.org/project/claude-agent-sdk/0.2.155/
pip install claude-agent-sdk==0.2.155
Updated bundled Claude CLI to version 2.1.274
PyPI: https://pypi.org/project/claude-agent-sdk/0.2.154/
pip install claude-agent-sdk==0.2.154
`snapshot` option for system prompts: Added a snapshot field to SystemPromptPreset and a new SystemPromptCustom typed dict. When snapshot is True, the
snapshot option for system prompts: Added a snapshot field to SystemPromptPreset and a new SystemPromptCustom typed dict. When snapshot is True, the session keeps the system prompt recorded on its first request, improving prompt-caching behavior across resumed sessions. When False, the prompt is rebuilt on every request, useful for iterating on append text. Requires CLI 2.1.257+ (#1268)PyPI: https://pypi.org/project/claude-agent-sdk/0.2.153/
pip install claude-agent-sdk==0.2.153
Updated bundled Claude CLI to version 2.1.259
PyPI: https://pypi.org/project/claude-agent-sdk/0.2.152/
pip install claude-agent-sdk==0.2.152
Updated bundled Claude CLI to version 2.1.258
PyPI: https://pypi.org/project/claude-agent-sdk/0.2.151/
pip install claude-agent-sdk==0.2.151
Updated bundled Claude CLI to version 2.1.257
PyPI: https://pypi.org/project/claude-agent-sdk/0.2.150/
pip install claude-agent-sdk==0.2.150
Updated bundled Claude CLI to version 2.1.252
PyPI: https://pypi.org/project/claude-agent-sdk/0.2.149/
pip install claude-agent-sdk==0.2.149
Updated bundled Claude CLI to version 2.1.251
PyPI: https://pypi.org/project/claude-agent-sdk/0.2.148/
pip install claude-agent-sdk==0.2.148
Updated bundled Claude CLI to version 2.1.250
PyPI: https://pypi.org/project/claude-agent-sdk/0.2.147/
pip install claude-agent-sdk==0.2.147
Updated bundled Claude CLI to version 2.1.248
PyPI: https://pypi.org/project/claude-agent-sdk/0.2.146/
pip install claude-agent-sdk==0.2.146
Updated bundled Claude CLI to version 2.1.247
PyPI: https://pypi.org/project/claude-agent-sdk/0.2.145/
pip install claude-agent-sdk==0.2.145
Updated bundled Claude CLI to version 2.1.246
PyPI: https://pypi.org/project/claude-agent-sdk/0.2.144/
pip install claude-agent-sdk==0.2.144
Updated bundled Claude CLI to version 2.1.238
PyPI: https://pypi.org/project/claude-agent-sdk/0.2.143/
pip install claude-agent-sdk==0.2.143
Updated bundled Claude CLI to version 2.1.237
PyPI: https://pypi.org/project/claude-agent-sdk/0.2.142/
pip install claude-agent-sdk==0.2.142
Updated bundled Claude CLI to version 2.1.236
PyPI: https://pypi.org/project/claude-agent-sdk/0.2.141/
pip install claude-agent-sdk==0.2.141
MCP 2.x support for in-process SDK MCP servers: The SDK now supports mcp 2.x alongside 1.x (dependency widened to mcp>=1.23.0,<3.0.0). In-process serv
mcp 2.x alongside 1.x (dependency widened to mcp>=1.23.0,<3.0.0). In-process servers are served over mcp's own in-memory transport instead of hand-rolled JSON-RPC dispatch, so hand-built mcp.server.Server instances now work at full fidelity — resources, prompts, and all result content types reach the CLI verbatim. Tool cancellation on interrupt is supported on mcp 2.x. claude_agent_sdk.ToolAnnotations accepts both camelCase and snake_case hint names on every mcp version (#1218)forward_subagent_text option: New forward_subagent_text boolean on ClaudeAgentOptions forwards a subagent's text and thinking blocks as messages in the stream, so consumers can render the full nested transcript. Matches the TypeScript SDK's forwardSubagentText (#1206)ResultError exception with structured error payload: When the CLI exits after a terminal error result, the SDK now raises ResultError (a subclass of ProcessError) instead of a bare "exit code 1" error. Carries subtype, errors, result, api_error_status, terminal_reason, session_id, and the raw data dict so callers can branch on failure reason without string matching. New exported types: ResultError (#1205)can_use_tool callback support for query() and string prompts: The can_use_tool permission callback now works with string prompts (not just ClaudeSDKClient), and stdin is kept open so the CLI can send permission requests over the control protocol (#1204)parent_tool_use_id when reading subagent transcripts: get_subagent_messages() and get_subagent_messages_from_store() now recover the parent_tool_use_id from the subagent's metadata, linking each subagent's messages to the Agent tool_use block in the parent session. SessionMessage also gains a parent_agent_id field for the spawning agent's id (#1207)PyPI: https://pypi.org/project/claude-agent-sdk/0.2.140/
pip install claude-agent-sdk==0.2.140
Updated bundled Claude CLI to version 2.1.233
PyPI: https://pypi.org/project/claude-agent-sdk/0.2.139/
pip install claude-agent-sdk==0.2.139
Updated bundled Claude CLI to version 2.1.232
PyPI: https://pypi.org/project/claude-agent-sdk/0.2.138/
pip install claude-agent-sdk==0.2.138
`ConversationResetMessage` for conversation reset events: The SDK now surfaces the CLI's conversation_reset frame as a ConversationResetMessage datacl
ConversationResetMessage for conversation reset events: The SDK now surfaces the CLI's conversation_reset frame as a ConversationResetMessage dataclass, letting applications detect when a /clear or other transcript-discarding flow resets the conversation mid-session. Includes new_conversation_id, uuid, and session_id fields. This widens the Message union — code that exhaustively matches with assert_never will need updating (#1196)UserMessage and ResultMessage: New origin: MessageOrigin | None field on UserMessage and ResultMessage surfaces why a turn was initiated — distinguishing application-submitted prompts ("human") from background-task notifications, scheduled triggers, peer messages, and other session-injected turns. New exported types: MessageOrigin, MessageOriginKind, TaskNotificationOriginSubkind (#1199)resume_session_at / resume_drops_turn options for truncating resume: ClaudeAgentOptions now supports resume_session_at (fork a session at an earlier transcript entry) and resume_drops_turn (validate that only entries from a specific turn are discarded). Enables safe rewind-to-before-last-prompt without silently dropping unobserved messages (#1198)settings.json into temp config dir on SessionStore resume: Resuming from a SessionStore now copies settings.json and cowork_settings.json into the temporary config directory, preserving apiKeyHelper auth, user hooks, env vars, and permissions. Previously, hosts authenticating solely via apiKeyHelper would fail with "Not logged in" on resume (#1197)resume_drops_turn guard failure), pending control requests like initialize() now receive the actual error text instead of a generic "Command failed with exit code 1" (#1198)PyPI: https://pypi.org/project/claude-agent-sdk/0.2.137/
pip install claude-agent-sdk==0.2.137
Updated bundled Claude CLI to version 2.1.228
PyPI: https://pypi.org/project/claude-agent-sdk/0.2.136/
pip install claude-agent-sdk==0.2.136
Updated bundled Claude CLI to version 2.1.227
PyPI: https://pypi.org/project/claude-agent-sdk/0.2.135/
pip install claude-agent-sdk==0.2.135
Updated bundled Claude CLI to version 2.1.226
PyPI: https://pypi.org/project/claude-agent-sdk/0.2.134/
pip install claude-agent-sdk==0.2.134
Updated bundled Claude CLI to version 2.1.225
PyPI: https://pypi.org/project/claude-agent-sdk/0.2.133/
pip install claude-agent-sdk==0.2.133
Updated bundled Claude CLI to version 2.1.224
PyPI: https://pypi.org/project/claude-agent-sdk/0.2.132/
pip install claude-agent-sdk==0.2.132
Updated bundled Claude CLI to version 2.1.223
PyPI: https://pypi.org/project/claude-agent-sdk/0.2.131/
pip install claude-agent-sdk==0.2.131
Updated bundled Claude CLI to version 2.1.222
PyPI: https://pypi.org/project/claude-agent-sdk/0.2.130/
pip install claude-agent-sdk==0.2.130
Skill name validation in `ClaudeAgentOptions.skills`: Skill names containing parentheses, commas, control characters, wildcards (*, :*), leading /, su
ClaudeAgentOptions.skills: Skill names containing parentheses, commas, control characters, wildcards (*, :*), leading /, surrounding whitespace, or surrogate code points now raise ValueError at connect time. skills=["plugin:*"] and skills=["*"] should be replaced with skills="all" or a Skill(...) rule in allowed_tools. Names with leading whitespace or / previously built rules that could never match (silently disabling the skill) and now raise explicitly (#1145)--allowedTools injection: Skill names from ClaudeAgentOptions(skills=[...]) were passed unchecked into the CLI's --allowedTools value, which splits on commas and spaces. A crafted name could inject extra permission rules. The transport now validates each name and rejects delimiter-carrying or malformed values (#1145)PyPI: https://pypi.org/project/claude-agent-sdk/0.2.129/
pip install claude-agent-sdk==0.2.129
Updated bundled Claude CLI to version 2.1.220
PyPI: https://pypi.org/project/claude-agent-sdk/0.2.128/
pip install claude-agent-sdk==0.2.128
Fixed premature stdin closure when background tasks are in flight: query() no longer closes stdin on the first result frame when background tasks (e.g
query() no longer closes stdin on the first result frame when background tasks (e.g. run_in_background: true subagents) are still running. Previously, closing stdin too early caused SDK-MCP tool calls from background tasks to fail with "Stream closed" and silently bypassed PreToolUse hooks. Stdin now stays open until all in-flight tasks complete and the final result frame arrives (#1103)PyPI: https://pypi.org/project/claude-agent-sdk/0.2.127/
pip install claude-agent-sdk==0.2.127
`terminal_reason` on ResultMessage: ResultMessage.terminal_reason now surfaces why the query loop ended ("completed", "max_turns", "aborted_streaming"
terminal_reason on ResultMessage: ResultMessage.terminal_reason now surfaces why the query loop ended ("completed", "max_turns", "aborted_streaming", "aborted_tools", etc.). A value of "aborted_streaming" or "aborted_tools" means the turn was cancelled via ClaudeSDKClient.interrupt(). Mirrors the TypeScript SDK's SDKResultMessage.terminal_reason (#1142)model_usage on ResultMessage: ResultMessage.model_usage is now typed as dict[str, ModelUsage] instead of dict[str, Any], with a new ModelUsage TypedDict that mirrors the TypeScript SDK's shape. Includes optional canonicalModel and provider fields for stable model identification across provider-specific aliases (#1143)PyPI: https://pypi.org/project/claude-agent-sdk/0.2.126/
pip install claude-agent-sdk==0.2.126
Updated bundled Claude CLI to version 2.1.217
PyPI: https://pypi.org/project/claude-agent-sdk/0.2.125/
pip install claude-agent-sdk==0.2.125
…cmd.exe metacharacter re-parsing (BatBadBut / CVE-2024-27980 class). Windows users relying on the npm shim should switch to the native installer, an e…
.bat/.cmd CLI scripts (including npm's claude.cmd shim) on Windows to prevent command injection via cmd.exe metacharacter re-parsing (BatBadBut / CVE-2024-27980 class). Windows users relying on the npm shim should switch to the native installer, an explicit claude.exe path, or a platform wheel that bundles the CLI (#1127)resume and session_id values containing cmd.exe metacharacters (& | < > ^ % ! ") or newlines now raise ValueError on Windows, preventing injection even if a cmd.exe hop is reintroduced. POSIX behavior is unchanged (#1127)extra_args value binding: extra_args now uses --flag=value form when the value starts with -, preventing a dash-leading value from being misinterpreted as a separate CLI flag (#1127)PyPI: https://pypi.org/project/claude-agent-sdk/0.2.124/
pip install claude-agent-sdk==0.2.124
Updated bundled Claude CLI to version 2.1.215
PyPI: https://pypi.org/project/claude-agent-sdk/0.2.123/
pip install claude-agent-sdk==0.2.123
Updated bundled Claude CLI to version 2.1.214
PyPI: https://pypi.org/project/claude-agent-sdk/0.2.122/
pip install claude-agent-sdk==0.2.122
Fixed argv flag injection via `resume` and `session_id` options: --resume and --session-id are now passed as single =-joined argv tokens (e.g. --resum
resume and session_id options: --resume and --session-id are now passed as single =-joined argv tokens (e.g. --resume=<value>) so that a dash-prefixed value is never misinterpreted as an independent CLI flag (#1123)CLAUDE_CLI_VERSION: Added version validation (_cli_version_validation.py) and eliminated shell interpolation in download_cli.py and update_cli_version.py so that a malformed version string cannot inject shell or Python code during builds (#1117)scripts/ alongside src/ and tests/curl errors (added shell: bash for pipefail)PyPI: https://pypi.org/project/claude-agent-sdk/0.2.121/
pip install claude-agent-sdk==0.2.121
One column per month.