anthropics · dicksontsai · Sep 27, 2025 · Sep 27, 2025 · Sep 27, 2025
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -9,12 +9,12 @@
 
 ## 0.0.19
 
-- Add `ClaudeCodeOptions.add_dirs` for `--add-dir`
+- Add `ClaudeAgentOptions.add_dirs` for `--add-dir`
 - Fix ClaudeCodeSDK hanging when MCP servers log to Claude Code stderr
 
 ## 0.0.18
 
-- Add `ClaudeCodeOptions.settings` for `--settings`
+- Add `ClaudeAgentOptions.settings` for `--settings`
 
 ## 0.0.17
 

diff --git a/README.md b/README.md
@@ -31,7 +31,7 @@ anyio.run(main)
 `query()` is an async function for querying Claude Code. It returns an `AsyncIterator` of response messages. See [src/claude_code_sdk/query.py](src/claude_code_sdk/query.py).
 
 ```python
-from claude_code_sdk import query, ClaudeCodeOptions, AssistantMessage, TextBlock
+from claude_code_sdk import query, ClaudeAgentOptions, AssistantMessage, TextBlock
 
 # Simple query
 async for message in query(prompt="Hello Claude"):
@@ -41,7 +41,7 @@ async for message in query(prompt="Hello Claude"):
                 print(block.text)
 
 # With options
-options = ClaudeCodeOptions(
+options = ClaudeAgentOptions(
     system_prompt="You are a helpful assistant",
     max_turns=1
 )
@@ -53,7 +53,7 @@ async for message in query(prompt="Tell me a joke", options=options):
 ### Using Tools
 
 ```python
-options = ClaudeCodeOptions(
+options = ClaudeAgentOptions(
     allowed_tools=["Read", "Write", "Bash"],
     permission_mode='acceptEdits'  # auto-accept file edits
 )
@@ -71,7 +71,7 @@ async for message in query(
 ```python
 from pathlib import Path
 
-options = ClaudeCodeOptions(
+options = ClaudeAgentOptions(
     cwd="/path/to/project"  # or Path("/path/to/project")
 )
 ```
@@ -94,7 +94,7 @@ For an end-to-end example, see [MCP Calculator](examples/mcp_calculator.py).
 #### Creating a Simple Tool
 
 ```python
-from claude_code_sdk import tool, create_sdk_mcp_server, ClaudeCodeOptions, ClaudeSDKClient
+from claude_code_sdk import tool, create_sdk_mcp_server, ClaudeAgentOptions, ClaudeSDKClient
 
 # Define a tool using the @tool decorator
 @tool("greet", "Greet a user", {"name": str})
@@ -113,7 +113,7 @@ server = create_sdk_mcp_server(
 )
 
 # Use it with Claude
-options = ClaudeCodeOptions(
+options = ClaudeAgentOptions(
     mcp_servers={"tools": server},
     allowed_tools=["mcp__tools__greet"]
 )
@@ -138,7 +138,7 @@ async with ClaudeSDKClient(options=options) as client:
 
 ```python
 # BEFORE: External MCP server (separate process)
-options = ClaudeCodeOptions(
+options = ClaudeAgentOptions(
     mcp_servers={
         "calculator": {
             "type": "stdio",
@@ -156,7 +156,7 @@ calculator = create_sdk_mcp_server(
     tools=[add, subtract]
 )
 
-options = ClaudeCodeOptions(
+options = ClaudeAgentOptions(
     mcp_servers={"calculator": calculator}
 )
 ```
@@ -166,7 +166,7 @@ options = ClaudeCodeOptions(
 You can use both SDK and external MCP servers together:
 
 ```python
-options = ClaudeCodeOptions(
+options = ClaudeAgentOptions(
     mcp_servers={
         "internal": sdk_server,      # In-process SDK server
         "external": {                # External subprocess server
@@ -186,7 +186,7 @@ For more examples, see examples/hooks.py.
 #### Example
 
 ```python
-from claude_code_sdk import ClaudeCodeOptions, ClaudeSDKClient, HookMatcher
+from claude_code_sdk import ClaudeAgentOptions, ClaudeSDKClient, HookMatcher
 
 async def check_bash_command(input_data, tool_use_id, context):
     tool_name = input_data["tool_name"]
@@ -206,7 +206,7 @@ async def check_bash_command(input_data, tool_use_id, context):
             }
     return {}
 
-options = ClaudeCodeOptions(
+options = ClaudeAgentOptions(
     allowed_tools=["Bash"],
     hooks={
         "PreToolUse": [
@@ -233,7 +233,7 @@ async with ClaudeSDKClient(options=options) as client:
 ## Types
 
 See [src/claude_code_sdk/types.py](src/claude_code_sdk/types.py) for complete type definitions:
-- `ClaudeCodeOptions` - Configuration options
+- `ClaudeAgentOptions` - Configuration options
 - `AssistantMessage`, `UserMessage`, `SystemMessage`, `ResultMessage` - Message types
 - `TextBlock`, `ToolUseBlock`, `ToolResultBlock` - Content blocks
 

diff --git a/e2e-tests/test_agents_and_settings.py b/e2e-tests/test_agents_and_settings.py
@@ -7,7 +7,7 @@
 
 from claude_code_sdk import (
     AgentDefinition,
-    ClaudeCodeOptions,
+    ClaudeAgentOptions,
     ClaudeSDKClient,
     SystemMessage,
 )
@@ -17,7 +17,7 @@
 @pytest.mark.asyncio
 async def test_agent_definition():
     """Test that custom agent definitions work."""
-    options = ClaudeCodeOptions(
+    options = ClaudeAgentOptions(
         agents={
             "test-agent": AgentDefinition(
                 description="A test agent for verification",
@@ -60,7 +60,7 @@ async def test_setting_sources_default():
         settings_file.write_text('{"outputStyle": "local-test-style"}')
 
         # Don't provide setting_sources - should default to no settings
-        options = ClaudeCodeOptions(
+        options = ClaudeAgentOptions(
             cwd=project_dir,
             max_turns=1,
         )
@@ -102,7 +102,7 @@ async def test_setting_sources_user_only():
         )
 
         # Use setting_sources=["user"] to exclude project settings
-        options = ClaudeCodeOptions(
+        options = ClaudeAgentOptions(
             setting_sources=["user"],
             cwd=project_dir,
             max_turns=1,
@@ -136,7 +136,7 @@ async def test_setting_sources_project_included():
         settings_file.write_text('{"outputStyle": "local-test-style"}')
 
         # Use setting_sources=["user", "project", "local"] to include local settings
-        options = ClaudeCodeOptions(
+        options = ClaudeAgentOptions(
             setting_sources=["user", "project", "local"],
             cwd=project_dir,
             max_turns=1,

diff --git a/e2e-tests/test_include_partial_messages.py b/e2e-tests/test_include_partial_messages.py
@@ -11,7 +11,7 @@
 
 from claude_code_sdk import ClaudeSDKClient
 from claude_code_sdk.types import (
-    ClaudeCodeOptions,
+    ClaudeAgentOptions,
     StreamEvent,
     AssistantMessage,
     SystemMessage,
@@ -26,7 +26,7 @@
 async def test_include_partial_messages_stream_events():
     """Test that include_partial_messages produces StreamEvent messages."""
 
-    options = ClaudeCodeOptions(
+    options = ClaudeAgentOptions(
         include_partial_messages=True,
         model="claude-sonnet-4-20250514",
         max_turns=2,
@@ -92,7 +92,7 @@ async def test_include_partial_messages_stream_events():
 async def test_include_partial_messages_thinking_deltas():
     """Test that thinking content is streamed incrementally via deltas."""
 
-    options = ClaudeCodeOptions(
+    options = ClaudeAgentOptions(
         include_partial_messages=True,
         model="claude-sonnet-4-20250514",
         max_turns=2,
@@ -130,7 +130,7 @@ async def test_include_partial_messages_thinking_deltas():
 async def test_partial_messages_disabled_by_default():
     """Test that partial messages are not included when option is not set."""
 
-    options = ClaudeCodeOptions(
+    options = ClaudeAgentOptions(
         # include_partial_messages not set (defaults to False)
         model="claude-sonnet-4-20250514",
         max_turns=2,

diff --git a/e2e-tests/test_sdk_mcp_tools.py b/e2e-tests/test_sdk_mcp_tools.py
@@ -9,7 +9,7 @@
 import pytest
 
 from claude_code_sdk import (
-    ClaudeCodeOptions,
+    ClaudeAgentOptions,
     ClaudeSDKClient,
     create_sdk_mcp_server,
     tool,
@@ -34,7 +34,7 @@ async def echo_tool(args: dict[str, Any]) -> dict[str, Any]:
         tools=[echo_tool],
     )
 
-    options = ClaudeCodeOptions(
+    options = ClaudeAgentOptions(
         mcp_servers={"test": server},
         allowed_tools=["mcp__test__echo"],
     )
@@ -73,7 +73,7 @@ async def greet_tool(args: dict[str, Any]) -> dict[str, Any]:
         tools=[echo_tool, greet_tool],
     )
 
-    options = ClaudeCodeOptions(
+    options = ClaudeAgentOptions(
         mcp_servers={"test": server},
         disallowed_tools=["mcp__test__echo"],  # Block echo tool
         allowed_tools=["mcp__test__greet"],  # But allow greet
@@ -116,7 +116,7 @@ async def greet_tool(args: dict[str, Any]) -> dict[str, Any]:
         tools=[echo_tool, greet_tool],
     )
 
-    options = ClaudeCodeOptions(
+    options = ClaudeAgentOptions(
         mcp_servers={"multi": server},
         allowed_tools=["mcp__multi__echo", "mcp__multi__greet"],
     )
@@ -153,7 +153,7 @@ async def echo_tool(args: dict[str, Any]) -> dict[str, Any]:
     )
 
     # No allowed_tools specified
-    options = ClaudeCodeOptions(
+    options = ClaudeAgentOptions(
         mcp_servers={"noperm": server},
     )
 

diff --git a/e2e-tests/test_tool_permissions.py b/e2e-tests/test_tool_permissions.py
@@ -3,7 +3,7 @@
 import pytest
 
 from claude_code_sdk import (
-    ClaudeCodeOptions,
+    ClaudeAgentOptions,
     ClaudeSDKClient,
     PermissionResultAllow,
     PermissionResultDeny,
@@ -27,7 +27,7 @@ async def permission_callback(
         callback_invocations.append(tool_name)
         return PermissionResultAllow()
 
-    options = ClaudeCodeOptions(
+    options = ClaudeAgentOptions(
         can_use_tool=permission_callback,
     )
 

diff --git a/examples/agents.py b/examples/agents.py
@@ -13,7 +13,7 @@
 from claude_code_sdk import (
     AgentDefinition,
     AssistantMessage,
-    ClaudeCodeOptions,
+    ClaudeAgentOptions,
     ResultMessage,
     TextBlock,
     query,
@@ -24,7 +24,7 @@ async def code_reviewer_example():
     """Example using a custom code reviewer agent."""
     print("=== Code Reviewer Agent Example ===")
 
-    options = ClaudeCodeOptions(
+    options = ClaudeAgentOptions(
         agents={
             "code-reviewer": AgentDefinition(
                 description="Reviews code for best practices and potential issues",
@@ -54,7 +54,7 @@ async def documentation_writer_example():
     """Example using a documentation writer agent."""
     print("=== Documentation Writer Agent Example ===")
 
-    options = ClaudeCodeOptions(
+    options = ClaudeAgentOptions(
         agents={
             "doc-writer": AgentDefinition(
                 description="Writes comprehensive documentation",
@@ -83,7 +83,7 @@ async def multiple_agents_example():
     """Example with multiple custom agents."""
     print("=== Multiple Agents Example ===")
 
-    options = ClaudeCodeOptions(
+    options = ClaudeAgentOptions(
         agents={
             "analyzer": AgentDefinition(
                 description="Analyzes code structure and patterns",

diff --git a/examples/hooks.py b/examples/hooks.py
@@ -1,8 +1,8 @@
 #!/usr/bin/env python
-"""Example of using hooks with Claude Code SDK via ClaudeCodeOptions.
+"""Example of using hooks with Claude Code SDK via ClaudeAgentOptions.
 
 This file demonstrates various hook patterns using the hooks parameter
-in ClaudeCodeOptions instead of decorator-based hooks.
+in ClaudeAgentOptions instead of decorator-based hooks.
 
 Usage:
 ./examples/hooks.py - List the examples
@@ -15,7 +15,7 @@
 import sys
 from typing import Any
 
-from claude_code_sdk import ClaudeCodeOptions, ClaudeSDKClient
+from claude_code_sdk import ClaudeAgentOptions, ClaudeSDKClient
 from claude_code_sdk.types import (
     AssistantMessage,
     HookContext,
@@ -86,8 +86,8 @@ async def example_pretooluse() -> None:
     print("=== PreToolUse Example ===")
     print("This example demonstrates how PreToolUse can block some bash commands but not others.\n")
 
-    # Configure hooks using ClaudeCodeOptions
-    options = ClaudeCodeOptions(
+    # Configure hooks using ClaudeAgentOptions
+    options = ClaudeAgentOptions(
         allowed_tools=["Bash"],
         hooks={
             "PreToolUse": [
@@ -125,7 +125,7 @@ async def example_userpromptsubmit() -> None:
     print("=== UserPromptSubmit Example ===")
     print("This example shows how a UserPromptSubmit hook can add context.\n")
 
-    options = ClaudeCodeOptions(
+    options = ClaudeAgentOptions(
         hooks={
             "UserPromptSubmit": [
                 HookMatcher(matcher=None, hooks=[add_custom_instructions]),

diff --git a/examples/include_partial_messages.py b/examples/include_partial_messages.py
@@ -16,7 +16,7 @@
 import asyncio
 from claude_code_sdk import ClaudeSDKClient
 from claude_code_sdk.types import (
-    ClaudeCodeOptions,
+    ClaudeAgentOptions,
     StreamEvent,
     AssistantMessage,
     UserMessage,
@@ -27,7 +27,7 @@
 
 async def main():
     # Enable partial message streaming
-    options = ClaudeCodeOptions(
+    options = ClaudeAgentOptions(
         include_partial_messages=True,
         model="claude-sonnet-4-20250514",
         max_turns=2,

diff --git a/examples/mcp_calculator.py b/examples/mcp_calculator.py
@@ -13,7 +13,7 @@
 from typing import Any
 
 from claude_code_sdk import (
-    ClaudeCodeOptions,
+    ClaudeAgentOptions,
     create_sdk_mcp_server,
     tool,
 )
@@ -155,7 +155,7 @@ async def main():
 
     # Configure Claude to use the calculator server with allowed tools
     # Pre-approve all calculator MCP tools so they can be used without permission prompts
-    options = ClaudeCodeOptions(
+    options = ClaudeAgentOptions(
         mcp_servers={"calc": calculator},
         allowed_tools=[
             "mcp__calc__add",