NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
PyPI, #601 most downloaded on PyPI
Python SDK for Claude Code
Latest stable
0.2.180
Last release 12 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.
Subagent transcript helpers: Added list_subagents() and get_subagent_messages() session helpers for reading subagent transcripts, enabling inspection
list_subagents() and get_subagent_messages() session helpers for reading subagent transcripts, enabling inspection of subagent message chains spawned during a session (#825)TRACEPARENT/TRACESTATE) to the CLI subprocess when an OpenTelemetry span is active, connecting SDK and CLI traces end-to-end. Install with pip install claude-agent-sdk[otel] for optional OpenTelemetry support (#821)delete_session() now removes the sibling subagent transcript directory alongside the session file, matching TypeScript SDK behavior (#805)setting_sources=[] being silently dropped (treated as falsy), which caused the CLI to load default settings instead of disabling all filesystem settings. An empty list now correctly passes --setting-sources= to disable all sources (#822)PyPI: https://pypi.org/project/claude-agent-sdk/0.1.60/
pip install claude-agent-sdk==0.1.60
Your coding agent can read these notes before it upgrades. Set up the MCP server →
Updated bundled Claude CLI to version 2.1.105
PyPI: https://pypi.org/project/claude-agent-sdk/0.1.59/
pip install claude-agent-sdk==0.1.59
Updated bundled Claude CLI to version 2.1.97
PyPI: https://pypi.org/project/claude-agent-sdk/0.1.58/
pip install claude-agent-sdk==0.1.58
Cross-user prompt caching: Added exclude_dynamic_sections option to SystemPromptPreset, enabling cross-user prompt cache hits by moving per-user dynam
exclude_dynamic_sections option to SystemPromptPreset, enabling cross-user prompt cache hits by moving per-user dynamic sections (working directory, memory, git status) out of the system prompt (#797)"auto" to the PermissionMode type, bringing parity with the TypeScript SDK and CLI v2.1.90+ (#785)thinking={"type": "adaptive"} incorrectly mapping to --max-thinking-tokens 32000 instead of --thinking adaptive. The disabled type similarly now uses --thinking disabled instead of --max-thinking-tokens 0, matching the TypeScript SDK behavior (#796)PyPI: https://pypi.org/project/claude-agent-sdk/0.1.57/
pip install claude-agent-sdk==0.1.57
Updated bundled Claude CLI to version 2.1.92
PyPI: https://pypi.org/project/claude-agent-sdk/0.1.56/
pip install claude-agent-sdk==0.1.56
MCP large tool results: Forward maxResultSizeChars from ToolAnnotations via _meta to bypass Zod annotation stripping in the CLI, fixing silent truncat
maxResultSizeChars from ToolAnnotations via _meta to bypass Zod annotation stripping in the CLI, fixing silent truncation of large MCP tool results (>50K chars) (#756)PyPI: https://pypi.org/project/claude-agent-sdk/0.1.55/
pip install claude-agent-sdk==0.1.55
PyPI: https://pypi.org/project/claude-agent-sdk/0.1.54/
PyPI: https://pypi.org/project/claude-agent-sdk/0.1.54/
pip install claude-agent-sdk==0.1.54
Setting sources flag: Fixed --setting-sources being passed as an empty string when not provided, which caused the CLI to misparse subsequent flags
--setting-sources being passed as an empty string when not provided, which caused the CLI to misparse subsequent flags (#778)query() with a string prompt and hooks/MCP servers that trigger many tool calls, by spawning wait_for_result_and_end_input() as a background task (#780)PyPI: https://pypi.org/project/claude-agent-sdk/0.1.53/
pip install claude-agent-sdk==0.1.53
Context usage: Added get_context_usage() method to ClaudeSDKClient for querying context window usage by category
get_context_usage() method to ClaudeSDKClient for querying context window usage by category (#764)@tool decorator and create_sdk_mcp_server now support typing.Annotated for per-parameter descriptions in JSON Schema (#762)tool_use_id and agent_id in ToolPermissionContext for distinguishing parallel permission requests (#754)session_id option to ClaudeAgentOptions for specifying custom session IDs (#750)connect(prompt="...") silently dropping the string prompt, causing receive_messages() to hang indefinitely (#769)control_cancel_request handling so in-flight hook callbacks are properly cancelled when the CLI abandons them (#751)PyPI: https://pypi.org/project/claude-agent-sdk/0.1.52/
pip install claude-agent-sdk==0.1.52
Session management: Added fork_session(), delete_session(), and offset-based pagination for session listing
fork_session(), delete_session(), and offset-based pagination for session listing (#744)task_budget option for token budget management (#747)--system-prompt-file CLI flag via SystemPromptFile (#591)disallowedTools, maxTurns, and initialPrompt to AgentDefinition (#759)AssistantMessage and ResultMessage for forward compatibility (#718)typing_extensions.TypedDict on Python 3.10 for NotRequired support (#761)errors field to ResultMessage (#749)RuntimeError on async generator cleanup (#746)TypedDict input_schema to proper JSON Schema in SDK MCP tools (#736)initialize_timeout from env var in query() (#743)connect() to avoid blocking async event loops (#722)dontAsk permission mode to types (#719)CLAUDECODE env var from subprocess environment (#732)SIGKILL fallback when SIGTERM handler blocks in close() (#729)resource_link and embedded resource content types in SDK MCP tools (#725)is_error flag from SDK MCP tool results (#717)install.sh fetch on 429 with pipefail + jitter (#708)PyPI: https://pypi.org/project/claude-agent-sdk/0.1.51/
pip install claude-agent-sdk==0.1.51
Session info: Added tag and created_at fields to SDKSessionInfo and new get_session_info() function for retrieving session metadata
tag and created_at fields to SDKSessionInfo and new get_session_info() function for retrieving session metadata (#667)PyPI: https://pypi.org/project/claude-agent-sdk/0.1.50/
pip install claude-agent-sdk==0.1.50
AgentDefinition: Added skills, memory, and mcpServers fields
skills, memory, and mcpServers fields (#684)usage on AssistantMessage (#685)tag_session() with Unicode sanitization (#670)rename_session() (#668)RateLimitEvent message (#648)allowed_tools as a permission allowlist (#649)PyPI: https://pypi.org/project/claude-agent-sdk/0.1.49/
pip install claude-agent-sdk==0.1.49
Fine-grained tool streaming: Fixed include_partial_messages=True not delivering input_json_delta events by enabling the CLAUDE_CODE_ENABLE_FINE_GRAINE
include_partial_messages=True not delivering input_json_delta events by enabling the CLAUDE_CODE_ENABLE_FINE_GRAINED_TOOL_STREAMING environment variable in the subprocess. This regression affected versions 0.1.36 through 0.1.47 for users without the server-side feature flag (#644)PyPI: https://pypi.org/project/claude-agent-sdk/0.1.48/
pip install claude-agent-sdk==0.1.48
Updated bundled Claude CLI to version 2.1.70
PyPI: https://pypi.org/project/claude-agent-sdk/0.1.47/
pip install claude-agent-sdk==0.1.47
Session history functions: Added list_sessions() and get_session_messages() top-level functions for retrieving past session data
list_sessions() and get_session_messages() top-level functions for retrieving past session data (#622)add_mcp_server(), remove_mcp_server(), and typed McpServerStatus for runtime MCP server management (#620)TaskStarted, TaskProgress, and TaskNotification message subclasses for better type safety when handling task-related events (#621)stop_reason field to ResultMessage for inspecting why a conversation turn ended (#619)agent_id and agent_type fields to tool-lifecycle hook inputs (PreToolUseHookInput, PostToolUseHookInput, PostToolUseFailureHookInput) (#628)PyPI: https://pypi.org/project/claude-agent-sdk/0.1.46/
pip install claude-agent-sdk==0.1.46
Updated bundled Claude CLI to version 2.1.63
PyPI: https://pypi.org/project/claude-agent-sdk/0.1.45/
pip install claude-agent-sdk==0.1.45
Updated bundled Claude CLI to version 2.1.59
PyPI: https://pypi.org/project/claude-agent-sdk/0.1.44/
pip install claude-agent-sdk==0.1.44
Updated bundled Claude CLI to version 2.1.56
PyPI: https://pypi.org/project/claude-agent-sdk/0.1.43/
pip install claude-agent-sdk==0.1.43
Updated bundled Claude CLI to version 2.1.55
PyPI: https://pypi.org/project/claude-agent-sdk/0.1.42/
pip install claude-agent-sdk==0.1.42
Updated bundled Claude CLI to version 2.1.52
PyPI: https://pypi.org/project/claude-agent-sdk/0.1.41/
pip install claude-agent-sdk==0.1.41
Unknown message type handling: Fixed an issue where unrecognized CLI message types (e.g., rate_limit_event) would crash the session by raising Message
rate_limit_event) would crash the session by raising MessageParseError. Unknown message types are now silently skipped, making the SDK forward-compatible with future CLI message types (#598)PyPI: https://pypi.org/project/claude-agent-sdk/0.1.40/
pip install claude-agent-sdk==0.1.40
Updated bundled Claude CLI to version 2.1.49
PyPI: https://pypi.org/project/claude-agent-sdk/0.1.39/
pip install claude-agent-sdk==0.1.39
Updated bundled Claude CLI to version 2.1.47
PyPI: https://pypi.org/project/claude-agent-sdk/0.1.38/
pip install claude-agent-sdk==0.1.38
Updated bundled Claude CLI to version 2.1.44
PyPI: https://pypi.org/project/claude-agent-sdk/0.1.37/
pip install claude-agent-sdk==0.1.37
The new thinking field takes precedence over the now-deprecated max_thinking_tokens field
ThinkingConfig types (ThinkingConfigAdaptive, ThinkingConfigEnabled, ThinkingConfigDisabled) and thinking field to ClaudeAgentOptions for fine-grained control over extended thinking behavior. The new thinking field takes precedence over the now-deprecated max_thinking_tokens field (#565)effort field to ClaudeAgentOptions supporting "low", "medium", "high", and "max" values for controlling thinking depth (#565)PyPI: https://pypi.org/project/claude-agent-sdk/0.1.36/
pip install claude-agent-sdk==0.1.36
Updated bundled Claude CLI to version 2.1.39
PyPI: https://pypi.org/project/claude-agent-sdk/0.1.35/
pip install claude-agent-sdk==0.1.35
Updated bundled Claude CLI to version 2.1.38
PyPI: https://pypi.org/project/claude-agent-sdk/0.1.34/
pip install claude-agent-sdk==0.1.34
Updated bundled Claude CLI to version 2.1.37
PyPI: https://pypi.org/project/claude-agent-sdk/0.1.33/
pip install claude-agent-sdk==0.1.33
Updated bundled Claude CLI to version 2.1.36
PyPI: https://pypi.org/project/claude-agent-sdk/0.1.32/
pip install claude-agent-sdk==0.1.32
MCP tool annotations support: Added support for MCP tool annotations via the @tool decorator's new annotations parameter, allowing developers to speci
@tool decorator's new annotations parameter, allowing developers to specify metadata hints like readOnlyHint, destructiveHint, idempotentHint, and openWorldHint. Re-exported ToolAnnotations from claude_agent_sdk for convenience (#551)PyPI: https://pypi.org/project/claude-agent-sdk/0.1.31/
pip install claude-agent-sdk==0.1.31
Updated bundled Claude CLI to version 2.1.32
PyPI: https://pypi.org/project/claude-agent-sdk/0.1.30/
pip install claude-agent-sdk==0.1.30
New hook events: Added support for three new hook event types (#545):
New hook events: Added support for three new hook event types (#545):
Notification — for handling notification events with NotificationHookInput and NotificationHookSpecificOutputSubagentStart — for handling subagent startup with SubagentStartHookInput and SubagentStartHookSpecificOutputPermissionRequest — for handling permission requests with PermissionRequestHookInput and PermissionRequestHookSpecificOutputEnhanced hook input/output types: Added missing fields to existing hook types (#545):
PreToolUseHookInput: added tool_use_idPostToolUseHookInput: added tool_use_idSubagentStopHookInput: added agent_id, agent_transcript_path, agent_typePreToolUseHookSpecificOutput: added additionalContextPostToolUseHookSpecificOutput: added updatedMCPToolOutputPyPI: https://pypi.org/project/claude-agent-sdk/0.1.29/
pip install claude-agent-sdk==0.1.29
AssistantMessage error field: Fixed AssistantMessage.error field not being populated due to incorrect data path. The error field is now correctly read
AssistantMessage.error field not being populated due to incorrect data path. The error field is now correctly read from the top level of the response (#506)PyPI: https://pypi.org/project/claude-agent-sdk/0.1.28/
pip install claude-agent-sdk==0.1.28
Updated bundled Claude CLI to version 2.1.29
PyPI: https://pypi.org/project/claude-agent-sdk/0.1.27/
pip install claude-agent-sdk==0.1.27
PostToolUseFailure hook event: Added PostToolUseFailure hook event type for handling tool use failures, including PostToolUseFailureHookInput and Post
PostToolUseFailure hook event type for handling tool use failures, including PostToolUseFailureHookInput and PostToolUseFailureHookSpecificOutput types (#535)PyPI: https://pypi.org/project/claude-agent-sdk/0.1.26/
pip install claude-agent-sdk==0.1.26
Updated bundled Claude CLI to version 2.1.23
PyPI: https://pypi.org/project/claude-agent-sdk/0.1.25/
pip install claude-agent-sdk==0.1.25
Updated bundled Claude CLI to version 2.1.22
PyPI: https://pypi.org/project/claude-agent-sdk/0.1.24/
pip install claude-agent-sdk==0.1.24
MCP status querying: Added public get_mcp_status() method to ClaudeSDKClient for querying MCP server connection status without accessing private inter
get_mcp_status() method to ClaudeSDKClient for querying MCP server connection status without accessing private internals (#516)PyPI: https://pypi.org/project/claude-agent-sdk/0.1.23/
pip install claude-agent-sdk==0.1.23
Added tool_use_result field to UserMessage
tool_use_result field to UserMessage (#495)Updated bundled Claude CLI to version 2.1.15
PyPI: https://pypi.org/project/claude-agent-sdk/0.1.21/
pip install claude-agent-sdk==0.1.21
Permission callback test reliability: Improved robustness of permission callback end-to-end tests
PyPI: https://pypi.org/project/claude-agent-sdk/0.1.20/
pip install claude-agent-sdk==0.1.20
Updated bundled Claude CLI to version 2.1.1
PyPI: https://pypi.org/project/claude-agent-sdk/0.1.19/
pip install claude-agent-sdk==0.1.19
Docker-based test infrastructure: Added Docker support for running e2e tests in containerized environments, helping catch Docker-specific issues
Published to PyPI: https://pypi.org/project/claude-agent-sdk/0.1.17/
Published to PyPI: https://pypi.org/project/claude-agent-sdk/0.1.17/
pip install claude-agent-sdk==0.1.17
Full Changelog: https://github.com/anthropics/claude-agent-sdk-python/compare/v0.1.16...v0.1.17
uuid field to UserMessage response type, making it easier to use the rewind_files() method by providing direct access to message identifiers needed for file checkpointing (#418)Published to PyPI: https://pypi.org/project/claude-agent-sdk/0.1.16/
Published to PyPI: https://pypi.org/project/claude-agent-sdk/0.1.16/
pip install claude-agent-sdk==0.1.16
Full Changelog: https://github.com/anthropics/claude-agent-sdk-python/compare/v0.1.15...v0.1.16
error field in AssistantMessage, enabling applications to detect and handle API errors like rate limits. Previously, the error field was defined but never populated from CLI responses (#405)Published to PyPI: https://pypi.org/project/claude-agent-sdk/0.1.15/
Published to PyPI: https://pypi.org/project/claude-agent-sdk/0.1.15/
pip install claude-agent-sdk==0.1.15
Full Changelog: https://github.com/anthropics/claude-agent-sdk-python/compare/v0.1.14...v0.1.15
enable_file_checkpointing option to ClaudeAgentOptions and rewind_files(user_message_id) method to ClaudeSDKClient and Query. This enables reverting file changes made during a session back to a specific checkpoint, useful for exploring different approaches or recovering from unwanted modifications (#395)Published to PyPI: https://pypi.org/project/claude-agent-sdk/0.1.14/
Published to PyPI: https://pypi.org/project/claude-agent-sdk/0.1.14/
pip install claude-agent-sdk==0.1.14
Full Changelog: https://github.com/anthropics/claude-agent-sdk-python/compare/v0.1.13...v0.1.14
Published to PyPI: https://pypi.org/project/claude-agent-sdk/0.1.13/
Published to PyPI: https://pypi.org/project/claude-agent-sdk/0.1.13/
pip install claude-agent-sdk==0.1.13
Full Changelog: https://github.com/anthropics/claude-agent-sdk-python/compare/v0.1.12...v0.1.13
PydanticUserError caused by McpServer type only being imported under TYPE_CHECKING (#385)BusyResourceError when multiple subagents invoke MCP tools in parallel (#391)Published to PyPI: https://pypi.org/project/claude-agent-sdk/0.1.12/
Published to PyPI: https://pypi.org/project/claude-agent-sdk/0.1.12/
pip install claude-agent-sdk==0.1.12
Full Changelog: https://github.com/anthropics/claude-agent-sdk-python/compare/v0.1.11...v0.1.12
tools option to ClaudeAgentOptions for controlling the base set of available tools, matching the TypeScript SDK functionality. Supports three modes:
["Read", "Edit", "Bash"])[] to disable all built-in tools{"type": "preset", "preset": "claude_code"} to use the default Claude Code toolsetbetas option to ClaudeAgentOptions for enabling Anthropic API beta features. Currently supports "context-1m-2025-08-07" for extended context windowPublished to PyPI: https://pypi.org/project/claude-agent-sdk/0.1.11/
Published to PyPI: https://pypi.org/project/claude-agent-sdk/0.1.11/
pip install claude-agent-sdk==0.1.11
Full Changelog: https://github.com/anthropics/claude-agent-sdk-python/compare/v0.1.10...v0.1.11
Published to PyPI: https://pypi.org/project/claude-agent-sdk/0.1.10/
Published to PyPI: https://pypi.org/project/claude-agent-sdk/0.1.10/
pip install claude-agent-sdk==0.1.10
HookMatcher.timeout type to float by @harupy in https://github.com/anthropics/claude-agent-sdk-python/pull/357Full Changelog: https://github.com/anthropics/claude-agent-sdk-python/compare/v0.1.9...v0.1.10
Published to PyPI: https://pypi.org/project/claude-agent-sdk/0.1.9/
Published to PyPI: https://pypi.org/project/claude-agent-sdk/0.1.9/
pip install claude-agent-sdk==0.1.9
Full Changelog: https://github.com/anthropics/claude-agent-sdk-python/compare/v0.1.8...v0.1.9
Published to PyPI: https://pypi.org/project/claude-agent-sdk/0.1.8/
Published to PyPI: https://pypi.org/project/claude-agent-sdk/0.1.8/
pip install claude-agent-sdk==0.1.8
Full Changelog: https://github.com/anthropics/claude-agent-sdk-python/compare/v0.1.7...v0.1.8
cli_path field in Options.Published to PyPI: https://pypi.org/project/claude-agent-sdk/0.1.7/
Published to PyPI: https://pypi.org/project/claude-agent-sdk/0.1.7/
pip install claude-agent-sdk==0.1.7
Full Changelog: https://github.com/anthropics/claude-agent-sdk-python/compare/v0.1.6...v0.1.7
~/.claude/local/claude, enabling development and testing with custom Claude CLI builds (#302)Published to PyPI: https://pypi.org/project/claude-agent-sdk/0.1.6/
Published to PyPI: https://pypi.org/project/claude-agent-sdk/0.1.6/
pip install claude-agent-sdk==0.1.6
Full Changelog: https://github.com/anthropics/claude-agent-sdk-python/compare/v0.1.5...v0.1.6
max_budget_usd option to set a maximum spending limit in USD for SDK sessions. When the budget is exceeded, the session will automatically terminate, helping prevent unexpected costs (#293)max_thinking_tokens option to control the maximum number of tokens allocated for Claude's internal reasoning process. This allows fine-tuning of the balance between response quality and token usage (#298)Published to PyPI: https://pypi.org/project/claude-agent-sdk/0.1.5/
Published to PyPI: https://pypi.org/project/claude-agent-sdk/0.1.5/
pip install claude-agent-sdk==0.1.5
Full Changelog: https://github.com/anthropics/claude-agent-sdk-python/compare/v0.1.4...v0.1.5
plugins field in ClaudeAgentOptions with a SdkPluginConfig type that supports loading local plugins by path. This enables SDK applications to extend functionality with custom commands and capabilities defined in plugin directoriesPublished to PyPI: https://pypi.org/project/claude-agent-sdk/0.1.4/
Published to PyPI: https://pypi.org/project/claude-agent-sdk/0.1.4/
pip install claude-agent-sdk==0.1.4
Full Changelog: https://github.com/anthropics/claude-agent-sdk-python/compare/v0.1.3...v0.1.4
CLAUDE_AGENT_SDK_SKIP_VERSION_CHECK environment variable to allow users to disable the Claude Code version check. Set this environment variable to skip the minimum version validation when the SDK connects to Claude Code. (Only recommended if you already have Claude Code 2.0.0 or higher installed, otherwise some functionality may break)Published to PyPI: https://pypi.org/project/claude-agent-sdk/0.1.3/
Published to PyPI: https://pypi.org/project/claude-agent-sdk/0.1.3/
pip install claude-agent-sdk==0.1.3
Full Changelog: https://github.com/anthropics/claude-agent-sdk-python/compare/v0.1.2...v0.1.3
PreToolUseHookInput, PostToolUseHookInput, UserPromptSubmitHookInput, etc.) using TypedDict for better IDE autocomplete and type safety. Hook callbacks now receive fully typed input parametersasync_, continue_) in hook outputs were not being converted to CLI format (async, continue). This caused hook control fields to be silently ignored, preventing proper hook behavior. The SDK now automatically converts field names when communicating with the CLIPublished to PyPI: https://pypi.org/project/claude-agent-sdk/0.1.2/
Published to PyPI: https://pypi.org/project/claude-agent-sdk/0.1.2/
pip install claude-agent-sdk==0.1.2
Full Changelog: https://github.com/anthropics/claude-agent-sdk-python/compare/v0.1.1...v0.1.2
reason, continue_, suppressOutput, and stopReason. The decision field now properly supports both "approve" and "block" values. Added AsyncHookJSONOutput type for deferred hook execution and proper typing for hookSpecificOutput with discriminated unionsPublished to PyPI: https://pypi.org/project/claude-agent-sdk/0.1.1/
Published to PyPI: https://pypi.org/project/claude-agent-sdk/0.1.1/
pip install claude-agent-sdk==0.1.1
Full Changelog: https://github.com/anthropics/claude-agent-sdk-python/compare/v0.1.0...v0.1.1
claude-sonnet-4-5 model identifier instead of dated version stringsOne column per month.