• Fine-grained tool streaming: Fixed 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)

• Updated bundled Claude CLI to version 2.1.71

• Updated bundled Claude CLI to version 2.1.70

• Session history functions: Added list_sessions() and get_session_messages() top-level functions for retrieving past session data (#622)
• MCP control methods: Added add_mcp_server(), remove_mcp_server(), and typed McpServerStatus for runtime MCP server management (#620)
• Typed task messages: Added TaskStarted, TaskProgress, and TaskNotification message subclasses for better type safety when handling task-related events (#621)
• ResultMessage stop_reason: Added stop_reason field to ResultMessage for inspecting why a conversation turn ended (#619)
• Hook input enhancements: Added agent_id and agent_type fields to tool-lifecycle hook inputs (PreToolUseHookInput, PostToolUseHookInput, PostToolUseFailureHookInput) (#628)

• String prompt MCP initialization: Fixed an issue where passing a string prompt would close stdin before MCP server initialization completed, causing MCP servers to fail to register (#630)

• Updated bundled Claude CLI to version 2.1.69

• Updated bundled Claude CLI to version 2.1.63

• Updated bundled Claude CLI to version 2.1.59

• Updated bundled Claude CLI to version 2.1.56

• Updated bundled Claude CLI to version 2.1.55

• Updated bundled Claude CLI to version 2.1.52

• Unknown message type handling: Fixed an issue where unrecognized CLI message types (e.g., 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)

• Updated bundled Claude CLI to version 2.1.51

• Updated bundled Claude CLI to version 2.1.49

• Updated bundled Claude CLI to version 2.1.47

• Updated bundled Claude CLI to version 2.1.44

• Thinking configuration: Added 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 option: Added effort field to ClaudeAgentOptions supporting "low", "medium", "high", and "max" values for controlling thinking depth (#565)

• Updated bundled Claude CLI to version 2.1.42

• Updated bundled Claude CLI to version 2.1.39

• Updated bundled Claude CLI to version 2.1.38
• Updated CI workflows to use Claude Opus 4.6 model (#556)

• Updated bundled Claude CLI to version 2.1.37

• Updated bundled Claude CLI to version 2.1.36

• MCP tool annotations support: Added support for MCP tool annotations via the @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)

• Large agent definitions: Fixed an issue where large agent definitions would silently fail to register due to platform-specific CLI argument size limits (ARG_MAX). Agent definitions are now sent via the initialize control request through stdin, matching the TypeScript SDK approach and allowing arbitrarily large agent payloads (#468)

• Updated bundled Claude CLI to version 2.1.33

• Updated bundled Claude CLI to version 2.1.32

• New hook events: Added support for three new hook event types (#545):

  • Notification — for handling notification events with NotificationHookInput and NotificationHookSpecificOutput
  • SubagentStart — for handling subagent startup with SubagentStartHookInput and SubagentStartHookSpecificOutput
  • PermissionRequest — for handling permission requests with PermissionRequestHookInput and PermissionRequestHookSpecificOutput

• Enhanced hook input/output types: Added missing fields to existing hook types (#545):

  • PreToolUseHookInput: added tool_use_id
  • PostToolUseHookInput: added tool_use_id
  • SubagentStopHookInput: added agent_id, agent_transcript_path, agent_type
  • PreToolUseHookSpecificOutput: added additionalContext
  • PostToolUseHookSpecificOutput: added updatedMCPToolOutput

• Updated bundled Claude CLI to version 2.1.31

• AssistantMessage error field: Fixed 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)

• Updated bundled Claude CLI to version 2.1.30

• Updated bundled Claude CLI to version 2.1.29

• PostToolUseFailure hook event: Added PostToolUseFailure hook event type for handling tool use failures, including PostToolUseFailureHookInput and PostToolUseFailureHookSpecificOutput types (#535)

• Updated bundled Claude CLI to version 2.1.27

• Updated bundled Claude CLI to version 2.1.23

• Updated bundled Claude CLI to version 2.1.22

• MCP status querying: Added public get_mcp_status() method to ClaudeSDKClient for querying MCP server connection status without accessing private internals (#516)

• Updated bundled Claude CLI to version 2.1.20

• Added tool_use_result field to UserMessage (#495)

• Added permissions to release job in auto-release workflow (#504)

• Updated bundled Claude CLI to version 2.1.19
• Extracted build-and-publish workflow into reusable component (#488)

• Updated bundled Claude CLI to version 2.1.15

• Permission callback test reliability: Improved robustness of permission callback end-to-end tests (#485)

• Updated Claude Agent SDK documentation link (#442)

• Updated bundled Claude CLI to version 2.1.9
• CI improvements: Updated claude-code actions from @beta to @v1 (#467)

• Updated bundled Claude CLI to version 2.1.1
• CI improvements: Jobs requiring secrets now skip when running from forks (#451)
• Fixed YAML syntax error in create-release-tag workflow (#429)

• Docker-based test infrastructure: Added Docker support for running e2e tests in containerized environments, helping catch Docker-specific issues (#424)
• Updated bundled Claude CLI to version 2.0.72

• UserMessage UUID field: Added 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)

• Updated bundled Claude CLI to version 2.0.70

• Rate limit detection: Fixed parsing of the 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)

• Updated bundled Claude CLI to version 2.0.68

• File checkpointing and rewind: Added 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)

• Added license and terms section to README (#399)

• Updated bundled Claude CLI to version 2.0.62

• Faster error handling: CLI errors (e.g., invalid session ID) now propagate to pending requests immediately instead of waiting for the 60-second timeout (#388)
• Pydantic 2.12+ compatibility: Fixed PydanticUserError caused by McpServer type only being imported under TYPE_CHECKING (#385)
• Concurrent subagent writes: Added write lock to prevent BusyResourceError when multiple subagents invoke MCP tools in parallel (#391)

• Updated bundled Claude CLI to version 2.0.59

• Tools option: Added tools option to ClaudeAgentOptions for controlling the base set of available tools, matching the TypeScript SDK functionality. Supports three modes:
  • Array of tool names to specify which tools should be available (e.g., ["Read", "Edit", "Bash"])
  • Empty array [] to disable all built-in tools
  • Preset object {"type": "preset", "preset": "claude_code"} to use the default Claude Code toolset
• SDK beta support: Added betas option to ClaudeAgentOptions for enabling Anthropic API beta features. Currently supports "context-1m-2025-08-07" for extended context window

• Updated bundled Claude CLI to version 2.0.57

• Updated bundled Claude CLI to version 2.0.53

• Updated bundled Claude CLI to version 2.0.49

• Claude Code is now included by default in the package, removing the requirement to install it separately. If you do wish to use a separately installed build, use the cli_path field in Options.

• Structured outputs support: Agents can now return validated JSON matching your schema. See https://docs.claude.com/en/docs/agent-sdk/structured-outputs. (#340)
• Fallback model handling: Added automatic fallback model handling for improved reliability and parity with the TypeScript SDK. When the primary model is unavailable, the SDK will automatically use a fallback model (#317)
• Local Claude CLI support: Added support for using a locally installed Claude CLI from ~/.claude/local/claude, enabling development and testing with custom Claude CLI builds (#302)

• Max budget control: Added 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)
• Extended thinking configuration: Added 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)

• System prompt defaults: Fixed issue where a default system prompt was being used when none was specified. The SDK now correctly uses an empty system prompt by default, giving users full control over agent behavior (#290)

• Plugin support: Added the ability to load Claude Code plugins programmatically through the SDK. Plugins can be specified using the new 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 directories

• Skip version check: Added 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)
• SDK MCP server tool calls can now return image content blocks

• Strongly-typed hook inputs: Added typed hook input structures (PreToolUseHookInput, PostToolUseHookInput, UserPromptSubmitHookInput, etc.) using TypedDict for better IDE autocomplete and type safety. Hook callbacks now receive fully typed input parameters

• Hook output field conversion: Fixed bug where Python-safe field names (async_, 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 CLI

• CI/CD: Re-enabled Windows testing in the end-to-end test workflow. Windows CI had been temporarily disabled but is now fully operational across all test suites

• Hook output fields: Added missing hook output fields to match the TypeScript SDK, including 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 unions

• Minimum Claude Code version check: Added version validation to ensure Claude Code 2.0.0+ is installed. The SDK will display a warning if an older version is detected, helping prevent compatibility issues
• Updated PermissionResult types: Aligned permission result types with the latest control protocol for better type safety and compatibility

• Model references: Updated all examples and tests to use the simplified claude-sonnet-4-5 model identifier instead of dated version strings

Introducing the Claude Agent SDK! The Claude Code SDK has been renamed to better reflect its capabilities for building AI agents across all domains, not just coding.

• ClaudeCodeOptions renamed to ClaudeAgentOptions: The options type has been renamed to match the new SDK branding. Update all imports and type references:

  # Before
  from claude_agent_sdk import query, ClaudeCodeOptions
  options = ClaudeCodeOptions(...)
  
  # After
  from claude_agent_sdk import query, ClaudeAgentOptions
  options = ClaudeAgentOptions(...)

• Merged prompt options: The custom_system_prompt and append_system_prompt fields have been merged into a single system_prompt field for simpler configuration
• No default system prompt: The Claude Code system prompt is no longer included by default, giving you full control over agent behavior. To use the Claude Code system prompt, explicitly set:

  system_prompt={"type": "preset", "preset": "claude_code"}

• No filesystem settings by default: Settings files (settings.json, CLAUDE.md), slash commands, and subagents are no longer loaded automatically. This ensures SDK applications have predictable behavior independent of local filesystem configurations
• Explicit settings control: Use the new setting_sources field to specify which settings locations to load: ["user", "project", "local"]

For full migration instructions, see our migration guide.

• Programmatic subagents: Subagents can now be defined inline in code using the agents option, enabling dynamic agent creation without filesystem dependencies. Learn more
• Session forking: Resume sessions with the new fork_session option to branch conversations and explore different approaches from the same starting point. Learn more
• Granular settings control: The setting_sources option gives you fine-grained control over which filesystem settings to load, improving isolation for CI/CD, testing, and production deployments

• Comprehensive documentation now available in the API Guide
• New guides for Custom Tools, Permissions, Session Management, and more
• Complete Python API reference

• Introduce custom tools, implemented as in-process MCP servers.
• Introduce hooks.
• Update internal Transport class to lower-level interface.
• ClaudeSDKClient can no longer be run in different async contexts.

• Add ClaudeCodeOptions.add_dirs for --add-dir
• Fix ClaudeCodeSDK hanging when MCP servers log to Claude Code stderr

• Add ClaudeCodeOptions.settings for --settings

• Remove dependency on asyncio for Trio compatibility

• Introduce ClaudeSDKClient for bidirectional streaming conversation
• Support Message input, not just string prompts, in query()
• Raise explicit error if the cwd does not exist

• Add safety limits to Claude Code CLI stderr reading
• Improve handling of output JSON messages split across multiple stream reads

• Update MCP (Model Context Protocol) types to align with Claude Code expectations
• Fix multi-line buffering issue
• Rename cost_usd to total_cost_usd in API responses
• Fix optional cost fields handling