Skip to content

The agent that turns websites into APIs!

chore: update llm-docs with claude-sdk docs

kalil032179fa278b47ef
diff --git a/llm-docs/claude-agent-sdk/QUICKSTART.md b/llm-docs/claude-agent-sdk/QUICKSTART.md
new file mode 100644
index 0000000..da2eb31
--- /dev/null
+++ b/llm-docs/claude-agent-sdk/QUICKSTART.md
@@ -0,0 +1,2017 @@
+# Agent SDK reference - Python
+
+Complete API reference for the Python Agent SDK, including all functions, types, and classes.
+
+---
+
+## Installation
+
+```bash
+pip install claude-agent-sdk
+```
+
+## Choosing Between `query()` and `ClaudeSDKClient`
+
+The Python SDK provides two ways to interact with Claude Code:
+
+### Quick Comparison
+
+| Feature | `query()` | `ClaudeSDKClient` |
+| :------------------ | :---------------------------- | :--------------------------------- |
+| **Session** | Creates new session each time | Reuses same session |
+| **Conversation** | Single exchange | Multiple exchanges in same context |
+| **Connection** | Managed automatically | Manual control |
+| **Streaming Input** | ✅ Supported | ✅ Supported |
+| **Interrupts** | ❌ Not supported | ✅ Supported |
+| **Hooks** | ❌ Not supported | ✅ Supported |
+| **Custom Tools** | ❌ Not supported | ✅ Supported |
+| **Continue Chat** | ❌ New session each time | ✅ Maintains conversation |
+| **Use Case** | One-off tasks | Continuous conversations |
+
+### When to Use `query()` (New Session Each Time)
+
+**Best for:**
+
+- One-off questions where you don't need conversation history
+- Independent tasks that don't require context from previous exchanges
+- Simple automation scripts
+- When you want a fresh start each time
+
+### When to Use `ClaudeSDKClient` (Continuous Conversation)
+
+**Best for:**
+
+- **Continuing conversations** - When you need Claude to remember context
+- **Follow-up questions** - Building on previous responses
+- **Interactive applications** - Chat interfaces, REPLs
+- **Response-driven logic** - When next action depends on Claude's response
+- **Session control** - Managing conversation lifecycle explicitly
+
+## Functions
+
+### `query()`
+
+Creates a new session for each interaction with Claude Code. Returns an async iterator that yields messages as they arrive. Each call to `query()` starts fresh with no memory of previous interactions.
+
+```python
+async def query(
+ *,
+ prompt: str | AsyncIterable[dict[str, Any]],
+ options: ClaudeAgentOptions | None = None
+) -> AsyncIterator[Message]
+```
+
+#### Parameters
+
+| Parameter | Type | Description |
+| :-------- | :--------------------------- | :------------------------------------------------------------------------- |
+| `prompt` | `str \| AsyncIterable[dict]` | The input prompt as a string or async iterable for streaming mode |
+| `options` | `ClaudeAgentOptions \| None` | Optional configuration object (defaults to `ClaudeAgentOptions()` if None) |
+
+#### Returns
+
+Returns an `AsyncIterator[Message]` that yields messages from the conversation.
+
+#### Example - With options
+
+```python
+
+import asyncio
+from claude_agent_sdk import query, ClaudeAgentOptions
+
+async def main():
+ options = ClaudeAgentOptions(
+ system_prompt="You are an expert Python developer",
+ permission_mode='acceptEdits',
+ cwd="/home/user/project"
+ )
+
+ async for message in query(
+ prompt="Create a Python web server",
+ options=options
+ ):
+ print(message)
+
+
+asyncio.run(main())
+```
+
+### `tool()`
+
+Decorator for defining MCP tools with type safety.
+
+```python
+def tool(
+ name: str,
+ description: str,
+ input_schema: type | dict[str, Any]
+) -> Callable[[Callable[[Any], Awaitable[dict[str, Any]]]], SdkMcpTool[Any]]
+```
+
+#### Parameters
+
+| Parameter | Type | Description |
+| :------------- | :----------------------- | :------------------------------------------------------ |
+| `name` | `str` | Unique identifier for the tool |
+| `description` | `str` | Human-readable description of what the tool does |
+| `input_schema` | `type \| dict[str, Any]` | Schema defining the tool's input parameters (see below) |
+
+#### Input Schema Options
+
+1. **Simple type mapping** (recommended):
+
+ ```python
+ {"text": str, "count": int, "enabled": bool}
+ ```
+
+2. **JSON Schema format** (for complex validation):
+ ```python
+ {
+ "type": "object",
+ "properties": {
+ "text": {"type": "string"},
+ "count": {"type": "integer", "minimum": 0}
+ },
+ "required": ["text"]
+ }
+ ```
+
+#### Returns
+
+A decorator function that wraps the tool implementation and returns an `SdkMcpTool` instance.
+
+#### Example
+
+```python
+from claude_agent_sdk import tool
+from typing import Any
+
+@tool("greet", "Greet a user", {"name": str})
+async def greet(args: dict[str, Any]) -> dict[str, Any]:
+ return {
+ "content": [{
+ "type": "text",
+ "text": f"Hello, {args['name']}!"
+ }]
+ }
+```
+
+### `create_sdk_mcp_server()`
+
+Create an in-process MCP server that runs within your Python application.
+
+```python
+def create_sdk_mcp_server(
+ name: str,
+ version: str = "1.0.0",
+ tools: list[SdkMcpTool[Any]] | None = None
+) -> McpSdkServerConfig
+```
+
+#### Parameters
+
+| Parameter | Type | Default | Description |
+| :-------- | :------------------------------ | :-------- | :---------------------------------------------------- |
+| `name` | `str` | - | Unique identifier for the server |
+| `version` | `str` | `"1.0.0"` | Server version string |
+| `tools` | `list[SdkMcpTool[Any]] \| None` | `None` | List of tool functions created with `@tool` decorator |
+
+#### Returns
+
+Returns an `McpSdkServerConfig` object that can be passed to `ClaudeAgentOptions.mcp_servers`.
+
+#### Example
+
+```python
+from claude_agent_sdk import tool, create_sdk_mcp_server
+
+@tool("add", "Add two numbers", {"a": float, "b": float})
+async def add(args):
+ return {
+ "content": [{
+ "type": "text",
+ "text": f"Sum: {args['a'] + args['b']}"
+ }]
+ }
+
+@tool("multiply", "Multiply two numbers", {"a": float, "b": float})
+async def multiply(args):
+ return {
+ "content": [{
+ "type": "text",
+ "text": f"Product: {args['a'] * args['b']}"
+ }]
+ }
+
+calculator = create_sdk_mcp_server(
+ name="calculator",
+ version="2.0.0",
+ tools=[add, multiply] # Pass decorated functions
+)
+
+# Use with Claude
+options = ClaudeAgentOptions(
+ mcp_servers={"calc": calculator},
+ allowed_tools=["mcp__calc__add", "mcp__calc__multiply"]
+)
+```
+
+## Classes
+
+### `ClaudeSDKClient`
+
+**Maintains a conversation session across multiple exchanges.** This is the Python equivalent of how the TypeScript SDK's `query()` function works internally - it creates a client object that can continue conversations.
+
+#### Key Features
+
+- **Session Continuity**: Maintains conversation context across multiple `query()` calls
+- **Same Conversation**: Claude remembers previous messages in the session
+- **Interrupt Support**: Can stop Claude mid-execution
+- **Explicit Lifecycle**: You control when the session starts and ends
+- **Response-driven Flow**: Can react to responses and send follow-ups
+- **Custom Tools & Hooks**: Supports custom tools (created with `@tool` decorator) and hooks
+
+```python
+class ClaudeSDKClient:
+ def __init__(self, options: ClaudeAgentOptions | None = None)
+ async def connect(self, prompt: str | AsyncIterable[dict] | None = None) -> None
+ async def query(self, prompt: str | AsyncIterable[dict], session_id: str = "default") -> None
+ async def receive_messages(self) -> AsyncIterator[Message]
+ async def receive_response(self) -> AsyncIterator[Message]
+ async def interrupt(self) -> None
+ async def rewind_files(self, user_message_uuid: str) -> None
+ async def disconnect(self) -> None
+```
+
+#### Methods
+
+| Method | Description |
+| :-------------------------- | :------------------------------------------------------------------ |
+| `__init__(options)` | Initialize the client with optional configuration |
+| `connect(prompt)` | Connect to Claude with an optional initial prompt or message stream |
+| `query(prompt, session_id)` | Send a new request in streaming mode |
+| `receive_messages()` | Receive all messages from Claude as an async iterator |
+| `receive_response()` | Receive messages until and including a ResultMessage |
+| `interrupt()` | Send interrupt signal (only works in streaming mode) |
+| `rewind_files(user_message_uuid)` | Restore files to their state at the specified user message. Requires `enable_file_checkpointing=True`. See [File checkpointing](/docs/en/agent-sdk/file-checkpointing) |
+| `disconnect()` | Disconnect from Claude |
+
+#### Context Manager Support
+
+The client can be used as an async context manager for automatic connection management:
+
+```python
+async with ClaudeSDKClient() as client:
+ await client.query("Hello Claude")
+ async for message in client.receive_response():
+ print(message)
+```
+
+> **Important:** When iterating over messages, avoid using `break` to exit early as this can cause asyncio cleanup issues. Instead, let the iteration complete naturally or use flags to track when you've found what you need.
+
+#### Example - Continuing a conversation
+
+```python
+import asyncio
+from claude_agent_sdk import ClaudeSDKClient, AssistantMessage, TextBlock, ResultMessage
+
+async def main():
+ async with ClaudeSDKClient() as client:
+ # First question
+ await client.query("What's the capital of France?")
+
+ # Process response
+ async for message in client.receive_response():
+ if isinstance(message, AssistantMessage):
+ for block in message.content:
+ if isinstance(block, TextBlock):
+ print(f"Claude: {block.text}")
+
+ # Follow-up question - Claude remembers the previous context
+ await client.query("What's the population of that city?")
+
+ async for message in client.receive_response():
+ if isinstance(message, AssistantMessage):
+ for block in message.content:
+ if isinstance(block, TextBlock):
+ print(f"Claude: {block.text}")
+
+ # Another follow-up - still in the same conversation
+ await client.query("What are some famous landmarks there?")
+
+ async for message in client.receive_response():
+ if isinstance(message, AssistantMessage):
+ for block in message.content:
+ if isinstance(block, TextBlock):
+ print(f"Claude: {block.text}")
+
+asyncio.run(main())
+```
+
+#### Example - Streaming input with ClaudeSDKClient
+
+```python
+import asyncio
+from claude_agent_sdk import ClaudeSDKClient
+
+async def message_stream():
+ """Generate messages dynamically."""
+ yield {"type": "text", "text": "Analyze the following data:"}
+ await asyncio.sleep(0.5)
+ yield {"type": "text", "text": "Temperature: 25°C"}
+ await asyncio.sleep(0.5)
+ yield {"type": "text", "text": "Humidity: 60%"}
+ await asyncio.sleep(0.5)
+ yield {"type": "text", "text": "What patterns do you see?"}
+
+async def main():
+ async with ClaudeSDKClient() as client:
+ # Stream input to Claude
+ await client.query(message_stream())
+
+ # Process response
+ async for message in client.receive_response():
+ print(message)
+
+ # Follow-up in same session
+ await client.query("Should we be concerned about these readings?")
+
+ async for message in client.receive_response():
+ print(message)
+
+asyncio.run(main())
+```
+
+#### Example - Using interrupts
+
+```python
+import asyncio
+from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions
+
+async def interruptible_task():
+ options = ClaudeAgentOptions(
+ allowed_tools=["Bash"],
+ permission_mode="acceptEdits"
+ )
+
+ async with ClaudeSDKClient(options=options) as client:
+ # Start a long-running task
+ await client.query("Count from 1 to 100 slowly")
+
+ # Let it run for a bit
+ await asyncio.sleep(2)
+
+ # Interrupt the task
+ await client.interrupt()
+ print("Task interrupted!")
+
+ # Send a new command
+ await client.query("Just say hello instead")
+
+ async for message in client.receive_response():
+ # Process the new response
+ pass
+
+asyncio.run(interruptible_task())
+```
+
+#### Example - Advanced permission control
+
+```python
+from claude_agent_sdk import (
+ ClaudeSDKClient,
+ ClaudeAgentOptions
+)
+
+async def custom_permission_handler(
+ tool_name: str,
+ input_data: dict,
+ context: dict
+):
+ """Custom logic for tool permissions."""
+
+ # Block writes to system directories
+ if tool_name == "Write" and input_data.get("file_path", "").startswith("/system/"):
+ return {
+ "behavior": "deny",
+ "message": "System directory write not allowed",
+ "interrupt": True
+ }
+
+ # Redirect sensitive file operations
+ if tool_name in ["Write", "Edit"] and "config" in input_data.get("file_path", ""):
+ safe_path = f"./sandbox/{input_data['file_path']}"
+ return {
+ "behavior": "allow",
+ "updatedInput": {**input_data, "file_path": safe_path}
+ }
+
+ # Allow everything else
+ return {
+ "behavior": "allow",
+ "updatedInput": input_data
+ }
+
+async def main():
+ options = ClaudeAgentOptions(
+ can_use_tool=custom_permission_handler,
+ allowed_tools=["Read", "Write", "Edit"]
+ )
+
+ async with ClaudeSDKClient(options=options) as client:
+ await client.query("Update the system config file")
+
+ async for message in client.receive_response():
+ # Will use sandbox path instead
+ print(message)
+
+asyncio.run(main())
+```
+
+## Types
+
+### `SdkMcpTool`
+
+Definition for an SDK MCP tool created with the `@tool` decorator.
+
+```python
+@dataclass
+class SdkMcpTool(Generic[T]):
+ name: str
+ description: str
+ input_schema: type[T] | dict[str, Any]
+ handler: Callable[[T], Awaitable[dict[str, Any]]]
+```
+
+| Property | Type | Description |
+| :------------- | :----------------------------------------- | :----------------------------------------- |
+| `name` | `str` | Unique identifier for the tool |
+| `description` | `str` | Human-readable description |
+| `input_schema` | `type[T] \| dict[str, Any]` | Schema for input validation |
+| `handler` | `Callable[[T], Awaitable[dict[str, Any]]]` | Async function that handles tool execution |
+
+### `ClaudeAgentOptions`
+
+Configuration dataclass for Claude Code queries.
+
+```python
+@dataclass
+class ClaudeAgentOptions:
+ allowed_tools: list[str] = field(default_factory=list)
+ system_prompt: str | SystemPromptPreset | None = None
+ mcp_servers: dict[str, McpServerConfig] | str | Path = field(default_factory=dict)
+ permission_mode: PermissionMode | None = None
+ continue_conversation: bool = False
+ resume: str | None = None
+ max_turns: int | None = None
+ disallowed_tools: list[str] = field(default_factory=list)
+ model: str | None = None
+ output_format: OutputFormat | None = None
+ permission_prompt_tool_name: str | None = None
+ cwd: str | Path | None = None
+ settings: str | None = None
+ add_dirs: list[str | Path] = field(default_factory=list)
+ env: dict[str, str] = field(default_factory=dict)
+ extra_args: dict[str, str | None] = field(default_factory=dict)
+ max_buffer_size: int | None = None
+ debug_stderr: Any = sys.stderr # Deprecated
+ stderr: Callable[[str], None] | None = None
+ can_use_tool: CanUseTool | None = None
+ hooks: dict[HookEvent, list[HookMatcher]] | None = None
+ user: str | None = None
+ include_partial_messages: bool = False
+ fork_session: bool = False
+ agents: dict[str, AgentDefinition] | None = None
+ setting_sources: list[SettingSource] | None = None
+```
+
+| Property | Type | Default | Description |
+| :---------------------------- | :------------------------------------------- | :------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `allowed_tools` | `list[str]` | `[]` | List of allowed tool names |
+| `system_prompt` | `str \| SystemPromptPreset \| None` | `None` | System prompt configuration. Pass a string for custom prompt, or use `{"type": "preset", "preset": "claude_code"}` for Claude Code's system prompt. Add `"append"` to extend the preset |
+| `mcp_servers` | `dict[str, McpServerConfig] \| str \| Path` | `{}` | MCP server configurations or path to config file |
+| `permission_mode` | `PermissionMode \| None` | `None` | Permission mode for tool usage |
+| `continue_conversation` | `bool` | `False` | Continue the most recent conversation |
+| `resume` | `str \| None` | `None` | Session ID to resume |
+| `max_turns` | `int \| None` | `None` | Maximum conversation turns |
+| `disallowed_tools` | `list[str]` | `[]` | List of disallowed tool names |
+| `enable_file_checkpointing` | `bool` | `False` | Enable file change tracking for rewinding. See [File checkpointing](/docs/en/agent-sdk/file-checkpointing) |
+| `model` | `str \| None` | `None` | Claude model to use |
+| `output_format` | [`OutputFormat`](#outputformat) ` \| None` | `None` | Define output format for agent results. See [Structured outputs](/docs/en/agent-sdk/structured-outputs) for details |
+| `permission_prompt_tool_name` | `str \| None` | `None` | MCP tool name for permission prompts |
+| `cwd` | `str \| Path \| None` | `None` | Current working directory |
+| `settings` | `str \| None` | `None` | Path to settings file |
+| `add_dirs` | `list[str \| Path]` | `[]` | Additional directories Claude can access |
+| `env` | `dict[str, str]` | `{}` | Environment variables |
+| `extra_args` | `dict[str, str \| None]` | `{}` | Additional CLI arguments to pass directly to the CLI |
+| `max_buffer_size` | `int \| None` | `None` | Maximum bytes when buffering CLI stdout |
+| `debug_stderr` | `Any` | `sys.stderr` | _Deprecated_ - File-like object for debug output. Use `stderr` callback instead |
+| `stderr` | `Callable[[str], None] \| None` | `None` | Callback function for stderr output from CLI |
+| `can_use_tool` | `CanUseTool \| None` | `None` | Tool permission callback function |
+| `hooks` | `dict[HookEvent, list[HookMatcher]] \| None` | `None` | Hook configurations for intercepting events |
+| `user` | `str \| None` | `None` | User identifier |
+| `include_partial_messages` | `bool` | `False` | Include partial message streaming events |
+| `fork_session` | `bool` | `False` | When resuming with `resume`, fork to a new session ID instead of continuing the original session |
+| `agents` | `dict[str, AgentDefinition] \| None` | `None` | Programmatically defined subagents |
+| `plugins` | `list[SdkPluginConfig]` | `[]` | Load custom plugins from local paths. See [Plugins](/docs/en/agent-sdk/plugins) for details |
+| `sandbox` | [`SandboxSettings`](#sandboxsettings) ` \| None` | `None` | Configure sandbox behavior programmatically. See [Sandbox settings](#sandboxsettings) for details |
+| `setting_sources` | `list[SettingSource] \| None` | `None` (no settings) | Control which filesystem settings to load. When omitted, no settings are loaded. **Note:** Must include `"project"` to load CLAUDE.md files |
+
+### `OutputFormat`
+
+Configuration for structured output validation.
+
+```python
+class OutputFormat(TypedDict):
+ type: Literal["json_schema"]
+ schema: dict[str, Any]
+```
+
+| Field | Required | Description |
+| :------- | :------- | :--------------------------------------------- |
+| `type` | Yes | Must be `"json_schema"` for JSON Schema validation |
+| `schema` | Yes | JSON Schema definition for output validation |
+
+### `SystemPromptPreset`
+
+Configuration for using Claude Code's preset system prompt with optional additions.
+
+```python
+class SystemPromptPreset(TypedDict):
+ type: Literal["preset"]
+ preset: Literal["claude_code"]
+ append: NotRequired[str]
+```
+
+| Field | Required | Description |
+| :------- | :------- | :------------------------------------------------------------ |
+| `type` | Yes | Must be `"preset"` to use a preset system prompt |
+| `preset` | Yes | Must be `"claude_code"` to use Claude Code's system prompt |
+| `append` | No | Additional instructions to append to the preset system prompt |
+
+### `SettingSource`
+
+Controls which filesystem-based configuration sources the SDK loads settings from.
+
+```python
+SettingSource = Literal["user", "project", "local"]
+```
+
+| Value | Description | Location |
+| :---------- | :------------------------------------------- | :---------------------------- |
+| `"user"` | Global user settings | `~/.claude/settings.json` |
+| `"project"` | Shared project settings (version controlled) | `.claude/settings.json` |
+| `"local"` | Local project settings (gitignored) | `.claude/settings.local.json` |
+
+#### Default behavior
+
+When `setting_sources` is **omitted** or **`None`**, the SDK does **not** load any filesystem settings. This provides isolation for SDK applications.
+
+#### Why use setting_sources?
+
+**Load all filesystem settings (legacy behavior):**
+
+```python
+# Load all settings like SDK v0.0.x did
+from claude_agent_sdk import query, ClaudeAgentOptions
+
+async for message in query(
+ prompt="Analyze this code",
+ options=ClaudeAgentOptions(
+ setting_sources=["user", "project", "local"] # Load all settings
+ )
+):
+ print(message)
+```
+
+**Load only specific setting sources:**
+
+```python
+# Load only project settings, ignore user and local
+async for message in query(
+ prompt="Run CI checks",
+ options=ClaudeAgentOptions(
+ setting_sources=["project"] # Only .claude/settings.json
+ )
+):
+ print(message)
+```
+
+**Testing and CI environments:**
+
+```python
+# Ensure consistent behavior in CI by excluding local settings
+async for message in query(
+ prompt="Run tests",
+ options=ClaudeAgentOptions(
+ setting_sources=["project"], # Only team-shared settings
+ permission_mode="bypassPermissions"
+ )
+):
+ print(message)
+```
+
+**SDK-only applications:**
+
+```python
+# Define everything programmatically (default behavior)
+# No filesystem dependencies - setting_sources defaults to None
+async for message in query(
+ prompt="Review this PR",
+ options=ClaudeAgentOptions(
+ # setting_sources=None is the default, no need to specify
+ agents={ /* ... */ },
+ mcp_servers={ /* ... */ },
+ allowed_tools=["Read", "Grep", "Glob"]
+ )
+):
+ print(message)
+```
+
+**Loading CLAUDE.md project instructions:**
+
+```python
+# Load project settings to include CLAUDE.md files
+async for message in query(
+ prompt="Add a new feature following project conventions",
+ options=ClaudeAgentOptions(
+ system_prompt={
+ "type": "preset",
+ "preset": "claude_code" # Use Claude Code's system prompt
+ },
+ setting_sources=["project"], # Required to load CLAUDE.md from project
+ allowed_tools=["Read", "Write", "Edit"]
+ )
+):
+ print(message)
+```
+
+#### Settings precedence
+
+When multiple sources are loaded, settings are merged with this precedence (highest to lowest):
+
+1. Local settings (`.claude/settings.local.json`)
+2. Project settings (`.claude/settings.json`)
+3. User settings (`~/.claude/settings.json`)
+
+Programmatic options (like `agents`, `allowed_tools`) always override filesystem settings.
+
+### `AgentDefinition`
+
+Configuration for a subagent defined programmatically.
+
+```python
+@dataclass
+class AgentDefinition:
+ description: str
+ prompt: str
+ tools: list[str] | None = None
+ model: Literal["sonnet", "opus", "haiku", "inherit"] | None = None
+```
+
+| Field | Required | Description |
+| :------------ | :------- | :------------------------------------------------------------- |
+| `description` | Yes | Natural language description of when to use this agent |
+| `tools` | No | Array of allowed tool names. If omitted, inherits all tools |
+| `prompt` | Yes | The agent's system prompt |
+| `model` | No | Model override for this agent. If omitted, uses the main model |
+
+### `PermissionMode`
+
+Permission modes for controlling tool execution.
+
+```python
+PermissionMode = Literal[
+ "default", # Standard permission behavior
+ "acceptEdits", # Auto-accept file edits
+ "plan", # Planning mode - no execution
+ "bypassPermissions" # Bypass all permission checks (use with caution)
+]
+```
+
+### `McpSdkServerConfig`
+
+Configuration for SDK MCP servers created with `create_sdk_mcp_server()`.
+
+```python
+class McpSdkServerConfig(TypedDict):
+ type: Literal["sdk"]
+ name: str
+ instance: Any # MCP Server instance
+```
+
+### `McpServerConfig`
+
+Union type for MCP server configurations.
+
+```python
+McpServerConfig = McpStdioServerConfig | McpSSEServerConfig | McpHttpServerConfig | McpSdkServerConfig
+```
+
+#### `McpStdioServerConfig`
+
+```python
+class McpStdioServerConfig(TypedDict):
+ type: NotRequired[Literal["stdio"]] # Optional for backwards compatibility
+ command: str
+ args: NotRequired[list[str]]
+ env: NotRequired[dict[str, str]]
+```
+
+#### `McpSSEServerConfig`
+
+```python
+class McpSSEServerConfig(TypedDict):
+ type: Literal["sse"]
+ url: str
+ headers: NotRequired[dict[str, str]]
+```
+
+#### `McpHttpServerConfig`
+
+```python
+class McpHttpServerConfig(TypedDict):
+ type: Literal["http"]
+ url: str
+ headers: NotRequired[dict[str, str]]
+```
+
+### `SdkPluginConfig`
+
+Configuration for loading plugins in the SDK.
+
+```python
+class SdkPluginConfig(TypedDict):
+ type: Literal["local"]
+ path: str
+```
+
+| Field | Type | Description |
+|:------|:-----|:------------|
+| `type` | `Literal["local"]` | Must be `"local"` (only local plugins currently supported) |
+| `path` | `str` | Absolute or relative path to the plugin directory |
+
+**Example:**
+```python
+plugins=[
+ {"type": "local", "path": "./my-plugin"},
+ {"type": "local", "path": "/absolute/path/to/plugin"}
+]
+```
+
+For complete information on creating and using plugins, see [Plugins](/docs/en/agent-sdk/plugins).
+
+## Message Types
+
+### `Message`
+
+Union type of all possible messages.
+
+```python
+Message = UserMessage | AssistantMessage | SystemMessage | ResultMessage
+```
+
+### `UserMessage`
+
+User input message.
+
+```python
+@dataclass
+class UserMessage:
+ content: str | list[ContentBlock]
+```
+
+### `AssistantMessage`
+
+Assistant response message with content blocks.
+
+```python
+@dataclass
+class AssistantMessage:
+ content: list[ContentBlock]
+ model: str
+```
+
+### `SystemMessage`
+
+System message with metadata.
+
+```python
+@dataclass
+class SystemMessage:
+ subtype: str
+ data: dict[str, Any]
+```
+
+### `ResultMessage`
+
+Final result message with cost and usage information.
+
+```python
+@dataclass
+class ResultMessage:
+ subtype: str
+ duration_ms: int
+ duration_api_ms: int
+ is_error: bool
+ num_turns: int
+ session_id: str
+ total_cost_usd: float | None = None
+ usage: dict[str, Any] | None = None
+ result: str | None = None
+```
+
+## Content Block Types
+
+### `ContentBlock`
+
+Union type of all content blocks.
+
+```python
+ContentBlock = TextBlock | ThinkingBlock | ToolUseBlock | ToolResultBlock
+```
+
+### `TextBlock`
+
+Text content block.
+
+```python
+@dataclass
+class TextBlock:
+ text: str
+```
+
+### `ThinkingBlock`
+
+Thinking content block (for models with thinking capability).
+
+```python
+@dataclass
+class ThinkingBlock:
+ thinking: str
+ signature: str
+```
+
+### `ToolUseBlock`
+
+Tool use request block.
+
+```python
+@dataclass
+class ToolUseBlock:
+ id: str
+ name: str
+ input: dict[str, Any]
+```
+
+### `ToolResultBlock`
+
+Tool execution result block.
+
+```python
+@dataclass
+class ToolResultBlock:
+ tool_use_id: str
+ content: str | list[dict[str, Any]] | None = None
+ is_error: bool | None = None
+```
+
+## Error Types
+
+### `ClaudeSDKError`
+
+Base exception class for all SDK errors.
+
+```python
+class ClaudeSDKError(Exception):
+ """Base error for Claude SDK."""
+```
+
+### `CLINotFoundError`
+
+Raised when Claude Code CLI is not installed or not found.
+
+```python
+class CLINotFoundError(CLIConnectionError):
+ def __init__(self, message: str = "Claude Code not found", cli_path: str | None = None):
+ """
+ Args:
+ message: Error message (default: "Claude Code not found")
+ cli_path: Optional path to the CLI that was not found
+ """
+```
+
+### `CLIConnectionError`
+
+Raised when connection to Claude Code fails.
+
+```python
+class CLIConnectionError(ClaudeSDKError):
+ """Failed to connect to Claude Code."""
+```
+
+### `ProcessError`
+
+Raised when the Claude Code process fails.
+
+```python
+class ProcessError(ClaudeSDKError):
+ def __init__(self, message: str, exit_code: int | None = None, stderr: str | None = None):
+ self.exit_code = exit_code
+ self.stderr = stderr
+```
+
+### `CLIJSONDecodeError`
+
+Raised when JSON parsing fails.
+
+```python
+class CLIJSONDecodeError(ClaudeSDKError):
+ def __init__(self, line: str, original_error: Exception):
+ """
+ Args:
+ line: The line that failed to parse
+ original_error: The original JSON decode exception
+ """
+ self.line = line
+ self.original_error = original_error
+```
+
+## Hook Types
+
+For a comprehensive guide on using hooks with examples and common patterns, see the [Hooks guide](/en/docs/agent-sdk/hooks).
+
+### `HookEvent`
+
+Supported hook event types. Note that due to setup limitations, the Python SDK does not support SessionStart, SessionEnd, and Notification hooks.
+
+```python
+HookEvent = Literal[
+ "PreToolUse", # Called before tool execution
+ "PostToolUse", # Called after tool execution
+ "UserPromptSubmit", # Called when user submits a prompt
+ "Stop", # Called when stopping execution
+ "SubagentStop", # Called when a subagent stops
+ "PreCompact" # Called before message compaction
+]
+```
+
+### `HookCallback`
+
+Type definition for hook callback functions.
+
+```python
+HookCallback = Callable[
+ [dict[str, Any], str | None, HookContext],
+ Awaitable[dict[str, Any]]
+]
+```
+
+Parameters:
+
+- `input_data`: Hook-specific input data (see [Hooks guide](/docs/en/agent-sdk/hooks#input-data))
+- `tool_use_id`: Optional tool use identifier (for tool-related hooks)
+- `context`: Hook context with additional information
+
+Returns a dictionary that may contain:
+
+- `decision`: `"block"` to block the action
+- `systemMessage`: System message to add to the transcript
+- `hookSpecificOutput`: Hook-specific output data
+
+### `HookContext`
+
+Context information passed to hook callbacks.
+
+```python
+@dataclass
+class HookContext:
+ signal: Any | None = None # Future: abort signal support
+```
+
+### `HookMatcher`
+
+Configuration for matching hooks to specific events or tools.
+
+```python
+@dataclass
+class HookMatcher:
+ matcher: str | None = None # Tool name or pattern to match (e.g., "Bash", "Write|Edit")
+ hooks: list[HookCallback] = field(default_factory=list) # List of callbacks to execute
+ timeout: float | None = None # Timeout in seconds for all hooks in this matcher (default: 60)
+```
+
+### Hook Usage Example
+
+This example registers two hooks: one that blocks dangerous bash commands like `rm -rf /`, and another that logs all tool usage for auditing. The security hook only runs on Bash commands (via the `matcher`), while the logging hook runs on all tools.
+
+```python
+from claude_agent_sdk import query, ClaudeAgentOptions, HookMatcher, HookContext
+from typing import Any
+
+async def validate_bash_command(
+ input_data: dict[str, Any],
+ tool_use_id: str | None,
+ context: HookContext
+) -> dict[str, Any]:
+ """Validate and potentially block dangerous bash commands."""
+ if input_data['tool_name'] == 'Bash':
+ command = input_data['tool_input'].get('command', '')
+ if 'rm -rf /' in command:
+ return {
+ 'hookSpecificOutput': {
+ 'hookEventName': 'PreToolUse',
+ 'permissionDecision': 'deny',
+ 'permissionDecisionReason': 'Dangerous command blocked'
+ }
+ }
+ return {}
+
+async def log_tool_use(
+ input_data: dict[str, Any],
+ tool_use_id: str | None,
+ context: HookContext
+) -> dict[str, Any]:
+ """Log all tool usage for auditing."""
+ print(f"Tool used: {input_data.get('tool_name')}")
+ return {}
+
+options = ClaudeAgentOptions(
+ hooks={
+ 'PreToolUse': [
+ HookMatcher(matcher='Bash', hooks=[validate_bash_command], timeout=120), # 2 min for validation
+ HookMatcher(hooks=[log_tool_use]) # Applies to all tools (default 60s timeout)
+ ],
+ 'PostToolUse': [
+ HookMatcher(hooks=[log_tool_use])
+ ]
+ }
+)
+
+async for message in query(
+ prompt="Analyze this codebase",
+ options=options
+):
+ print(message)
+```
+
+## Tool Input/Output Types
+
+Documentation of input/output schemas for all built-in Claude Code tools. While the Python SDK doesn't export these as types, they represent the structure of tool inputs and outputs in messages.
+
+### Task
+
+**Tool name:** `Task`
+
+**Input:**
+
+```python
+{
+ "description": str, # A short (3-5 word) description of the task
+ "prompt": str, # The task for the agent to perform
+ "subagent_type": str # The type of specialized agent to use
+}
+```
+
+**Output:**
+
+```python
+{
+ "result": str, # Final result from the subagent
+ "usage": dict | None, # Token usage statistics
+ "total_cost_usd": float | None, # Total cost in USD
+ "duration_ms": int | None # Execution duration in milliseconds
+}
+```
+
+### Bash
+
+**Tool name:** `Bash`
+
+**Input:**
+
+```python
+{
+ "command": str, # The command to execute
+ "timeout": int | None, # Optional timeout in milliseconds (max 600000)
+ "description": str | None, # Clear, concise description (5-10 words)
+ "run_in_background": bool | None # Set to true to run in background
+}
+```
+
+**Output:**
+
+```python
+{
+ "output": str, # Combined stdout and stderr output
+ "exitCode": int, # Exit code of the command
+ "killed": bool | None, # Whether command was killed due to timeout
+ "shellId": str | None # Shell ID for background processes
+}
+```
+
+### Edit
+
+**Tool name:** `Edit`
+
+**Input:**
+
+```python
+{
+ "file_path": str, # The absolute path to the file to modify
+ "old_string": str, # The text to replace
+ "new_string": str, # The text to replace it with
+ "replace_all": bool | None # Replace all occurrences (default False)
+}
+```
+
+**Output:**
+
+```python
+{
+ "message": str, # Confirmation message
+ "replacements": int, # Number of replacements made
+ "file_path": str # File path that was edited
+}
+```
+
+### Read
+
+**Tool name:** `Read`
+
+**Input:**
+
+```python
+{
+ "file_path": str, # The absolute path to the file to read
+ "offset": int | None, # The line number to start reading from
+ "limit": int | None # The number of lines to read
+}
+```
+
+**Output (Text files):**
+
+```python
+{
+ "content": str, # File contents with line numbers
+ "total_lines": int, # Total number of lines in file
+ "lines_returned": int # Lines actually returned
+}
+```
+
+**Output (Images):**
+
+```python
+{
+ "image": str, # Base64 encoded image data
+ "mime_type": str, # Image MIME type
+ "file_size": int # File size in bytes
+}
+```
+
+### Write
+
+**Tool name:** `Write`
+
+**Input:**
+
+```python
+{
+ "file_path": str, # The absolute path to the file to write
+ "content": str # The content to write to the file
+}
+```
+
+**Output:**
+
+```python
+{
+ "message": str, # Success message
+ "bytes_written": int, # Number of bytes written
+ "file_path": str # File path that was written
+}
+```
+
+### Glob
+
+**Tool name:** `Glob`
+
+**Input:**
+
+```python
+{
+ "pattern": str, # The glob pattern to match files against
+ "path": str | None # The directory to search in (defaults to cwd)
+}
+```
+
+**Output:**
+
+```python
+{
+ "matches": list[str], # Array of matching file paths
+ "count": int, # Number of matches found
+ "search_path": str # Search directory used
+}
+```
+
+### Grep
+
+**Tool name:** `Grep`
+
+**Input:**
+
+```python
+{
+ "pattern": str, # The regular expression pattern
+ "path": str | None, # File or directory to search in
+ "glob": str | None, # Glob pattern to filter files
+ "type": str | None, # File type to search
+ "output_mode": str | None, # "content", "files_with_matches", or "count"
+ "-i": bool | None, # Case insensitive search
+ "-n": bool | None, # Show line numbers
+ "-B": int | None, # Lines to show before each match
+ "-A": int | None, # Lines to show after each match
+ "-C": int | None, # Lines to show before and after
+ "head_limit": int | None, # Limit output to first N lines/entries
+ "multiline": bool | None # Enable multiline mode
+}
+```
+
+**Output (content mode):**
+
+```python
+{
+ "matches": [
+ {
+ "file": str,
+ "line_number": int | None,
+ "line": str,
+ "before_context": list[str] | None,
+ "after_context": list[str] | None
+ }
+ ],
+ "total_matches": int
+}
+```
+
+**Output (files_with_matches mode):**
+
+```python
+{
+ "files": list[str], # Files containing matches
+ "count": int # Number of files with matches
+}
+```
+
+### NotebookEdit
+
+**Tool name:** `NotebookEdit`
+
+**Input:**
+
+```python
+{
+ "notebook_path": str, # Absolute path to the Jupyter notebook
+ "cell_id": str | None, # The ID of the cell to edit
+ "new_source": str, # The new source for the cell
+ "cell_type": "code" | "markdown" | None, # The type of the cell
+ "edit_mode": "replace" | "insert" | "delete" | None # Edit operation type
+}
+```
+
+**Output:**
+
+```python
+{
+ "message": str, # Success message
+ "edit_type": "replaced" | "inserted" | "deleted", # Type of edit performed
+ "cell_id": str | None, # Cell ID that was affected
+ "total_cells": int # Total cells in notebook after edit
+}
+```
+
+### WebFetch
+
+**Tool name:** `WebFetch`
+
+**Input:**
+
+```python
+{
+ "url": str, # The URL to fetch content from
+ "prompt": str # The prompt to run on the fetched content
+}
+```
+
+**Output:**
+
+```python
+{
+ "response": str, # AI model's response to the prompt
+ "url": str, # URL that was fetched
+ "final_url": str | None, # Final URL after redirects
+ "status_code": int | None # HTTP status code
+}
+```
+
+### WebSearch
+
+**Tool name:** `WebSearch`
+
+**Input:**
+
+```python
+{
+ "query": str, # The search query to use
+ "allowed_domains": list[str] | None, # Only include results from these domains
+ "blocked_domains": list[str] | None # Never include results from these domains
+}
+```
+
+**Output:**
+
+```python
+{
+ "results": [
+ {
+ "title": str,
+ "url": str,
+ "snippet": str,
+ "metadata": dict | None
+ }
+ ],
+ "total_results": int,
+ "query": str
+}
+```
+
+### TodoWrite
+
+**Tool name:** `TodoWrite`
+
+**Input:**
+
+```python
+{
+ "todos": [
+ {
+ "content": str, # The task description
+ "status": "pending" | "in_progress" | "completed", # Task status
+ "activeForm": str # Active form of the description
+ }
+ ]
+}
+```
+
+**Output:**
+
+```python
+{
+ "message": str, # Success message
+ "stats": {
+ "total": int,
+ "pending": int,
+ "in_progress": int,
+ "completed": int
+ }
+}
+```
+
+### BashOutput
+
+**Tool name:** `BashOutput`
+
+**Input:**
+
+```python
+{
+ "bash_id": str, # The ID of the background shell
+ "filter": str | None # Optional regex to filter output lines
+}
+```
+
+**Output:**
+
+```python
+{
+ "output": str, # New output since last check
+ "status": "running" | "completed" | "failed", # Current shell status
+ "exitCode": int | None # Exit code when completed
+}
+```
+
+### KillBash
+
+**Tool name:** `KillBash`
+
+**Input:**
+
+```python
+{
+ "shell_id": str # The ID of the background shell to kill
+}
+```
+
+**Output:**
+
+```python
+{
+ "message": str, # Success message
+ "shell_id": str # ID of the killed shell
+}
+```
+
+### ExitPlanMode
+
+**Tool name:** `ExitPlanMode`
+
+**Input:**
+
+```python
+{
+ "plan": str # The plan to run by the user for approval
+}
+```
+
+**Output:**
+
+```python
+{
+ "message": str, # Confirmation message
+ "approved": bool | None # Whether user approved the plan
+}
+```
+
+### ListMcpResources
+
+**Tool name:** `ListMcpResources`
+
+**Input:**
+
+```python
+{
+ "server": str | None # Optional server name to filter resources by
+}
+```
+
+**Output:**
+
+```python
+{
+ "resources": [
+ {
+ "uri": str,
+ "name": str,
+ "description": str | None,
+ "mimeType": str | None,
+ "server": str
+ }
+ ],
+ "total": int
+}
+```
+
+### ReadMcpResource
+
+**Tool name:** `ReadMcpResource`
+
+**Input:**
+
+```python
+{
+ "server": str, # The MCP server name
+ "uri": str # The resource URI to read
+}
+```
+
+**Output:**
+
+```python
+{
+ "contents": [
+ {
+ "uri": str,
+ "mimeType": str | None,
+ "text": str | None,
+ "blob": str | None
+ }
+ ],
+ "server": str
+}
+```
+
+## Advanced Features with ClaudeSDKClient
+
+### Building a Continuous Conversation Interface
+
+```python
+from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions, AssistantMessage, TextBlock
+import asyncio
+
+class ConversationSession:
+ """Maintains a single conversation session with Claude."""
+
+ def __init__(self, options: ClaudeAgentOptions = None):
+ self.client = ClaudeSDKClient(options)
+ self.turn_count = 0
+
+ async def start(self):
+ await self.client.connect()
+ print("Starting conversation session. Claude will remember context.")
+ print("Commands: 'exit' to quit, 'interrupt' to stop current task, 'new' for new session")
+
+ while True:
+ user_input = input(f"\n[Turn {self.turn_count + 1}] You: ")
+
+ if user_input.lower() == 'exit':
+ break
+ elif user_input.lower() == 'interrupt':
+ await self.client.interrupt()
+ print("Task interrupted!")
+ continue
+ elif user_input.lower() == 'new':
+ # Disconnect and reconnect for a fresh session
+ await self.client.disconnect()
+ await self.client.connect()
+ self.turn_count = 0
+ print("Started new conversation session (previous context cleared)")
+ continue
+
+ # Send message - Claude remembers all previous messages in this session
+ await self.client.query(user_input)
+ self.turn_count += 1
+
+ # Process response
+ print(f"[Turn {self.turn_count}] Claude: ", end="")
+ async for message in self.client.receive_response():
+ if isinstance(message, AssistantMessage):
+ for block in message.content:
+ if isinstance(block, TextBlock):
+ print(block.text, end="")
+ print() # New line after response
+
+ await self.client.disconnect()
+ print(f"Conversation ended after {self.turn_count} turns.")
+
+async def main():
+ options = ClaudeAgentOptions(
+ allowed_tools=["Read", "Write", "Bash"],
+ permission_mode="acceptEdits"
+ )
+ session = ConversationSession(options)
+ await session.start()
+
+# Example conversation:
+# Turn 1 - You: "Create a file called hello.py"
+# Turn 1 - Claude: "I'll create a hello.py file for you..."
+# Turn 2 - You: "What's in that file?"
+# Turn 2 - Claude: "The hello.py file I just created contains..." (remembers!)
+# Turn 3 - You: "Add a main function to it"
+# Turn 3 - Claude: "I'll add a main function to hello.py..." (knows which file!)
+
+asyncio.run(main())
+```
+
+### Using Hooks for Behavior Modification
+
+```python
+from claude_agent_sdk import (
+ ClaudeSDKClient,
+ ClaudeAgentOptions,
+ HookMatcher,
+ HookContext
+)
+import asyncio
+from typing import Any
+
+async def pre_tool_logger(
+ input_data: dict[str, Any],
+ tool_use_id: str | None,
+ context: HookContext
+) -> dict[str, Any]:
+ """Log all tool usage before execution."""
+ tool_name = input_data.get('tool_name', 'unknown')
+ print(f"[PRE-TOOL] About to use: {tool_name}")
+
+ # You can modify or block the tool execution here
+ if tool_name == "Bash" and "rm -rf" in str(input_data.get('tool_input', {})):
+ return {
+ 'hookSpecificOutput': {
+ 'hookEventName': 'PreToolUse',
+ 'permissionDecision': 'deny',
+ 'permissionDecisionReason': 'Dangerous command blocked'
+ }
+ }
+ return {}
+
+async def post_tool_logger(
+ input_data: dict[str, Any],
+ tool_use_id: str | None,
+ context: HookContext
+) -> dict[str, Any]:
+ """Log results after tool execution."""
+ tool_name = input_data.get('tool_name', 'unknown')
+ print(f"[POST-TOOL] Completed: {tool_name}")
+ return {}
+
+async def user_prompt_modifier(
+ input_data: dict[str, Any],
+ tool_use_id: str | None,
+ context: HookContext
+) -> dict[str, Any]:
+ """Add context to user prompts."""
+ original_prompt = input_data.get('prompt', '')
+
+ # Add timestamp to all prompts
+ from datetime import datetime
+ timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+
+ return {
+ 'hookSpecificOutput': {
+ 'hookEventName': 'UserPromptSubmit',
+ 'updatedPrompt': f"[{timestamp}] {original_prompt}"
+ }
+ }
+
+async def main():
+ options = ClaudeAgentOptions(
+ hooks={
+ 'PreToolUse': [
+ HookMatcher(hooks=[pre_tool_logger]),
+ HookMatcher(matcher='Bash', hooks=[pre_tool_logger])
+ ],
+ 'PostToolUse': [
+ HookMatcher(hooks=[post_tool_logger])
+ ],
+ 'UserPromptSubmit': [
+ HookMatcher(hooks=[user_prompt_modifier])
+ ]
+ },
+ allowed_tools=["Read", "Write", "Bash"]
+ )
+
+ async with ClaudeSDKClient(options=options) as client:
+ await client.query("List files in current directory")
+
+ async for message in client.receive_response():
+ # Hooks will automatically log tool usage
+ pass
+
+asyncio.run(main())
+```
+
+### Real-time Progress Monitoring
+
+```python
+from claude_agent_sdk import (
+ ClaudeSDKClient,
+ ClaudeAgentOptions,
+ AssistantMessage,
+ ToolUseBlock,
+ ToolResultBlock,
+ TextBlock
+)
+import asyncio
+
+async def monitor_progress():
+ options = ClaudeAgentOptions(
+ allowed_tools=["Write", "Bash"],
+ permission_mode="acceptEdits"
+ )
+
+ async with ClaudeSDKClient(options=options) as client:
+ await client.query(
+ "Create 5 Python files with different sorting algorithms"
+ )
+
+ # Monitor progress in real-time
+ files_created = []
+ async for message in client.receive_messages():
+ if isinstance(message, AssistantMessage):
+ for block in message.content:
+ if isinstance(block, ToolUseBlock):
+ if block.name == "Write":
+ file_path = block.input.get("file_path", "")
+ print(f"🔨 Creating: {file_path}")
+ elif isinstance(block, ToolResultBlock):
+ print(f"✅ Completed tool execution")
+ elif isinstance(block, TextBlock):
+ print(f"💭 Claude says: {block.text[:100]}...")
+
+ # Check if we've received the final result
+ if hasattr(message, 'subtype') and message.subtype in ['success', 'error']:
+ print(f"\n🎯 Task completed!")
+ break
+
+asyncio.run(monitor_progress())
+```
+
+## Example Usage
+
+### Basic file operations (using query)
+
+```python
+from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ToolUseBlock
+import asyncio
+
+async def create_project():
+ options = ClaudeAgentOptions(
+ allowed_tools=["Read", "Write", "Bash"],
+ permission_mode='acceptEdits',
+ cwd="/home/user/project"
+ )
+
+ async for message in query(
+ prompt="Create a Python project structure with setup.py",
+ options=options
+ ):
+ if isinstance(message, AssistantMessage):
+ for block in message.content:
+ if isinstance(block, ToolUseBlock):
+ print(f"Using tool: {block.name}")
+
+asyncio.run(create_project())
+```
+
+### Error handling
+
+```python
+from claude_agent_sdk import (
+ query,
+ CLINotFoundError,
+ ProcessError,
+ CLIJSONDecodeError
+)
+
+try:
+ async for message in query(prompt="Hello"):
+ print(message)
+except CLINotFoundError:
+ print("Please install Claude Code: npm install -g @anthropic-ai/claude-code")
+except ProcessError as e:
+ print(f"Process failed with exit code: {e.exit_code}")
+except CLIJSONDecodeError as e:
+ print(f"Failed to parse response: {e}")
+```
+
+### Streaming mode with client
+
+```python
+from claude_agent_sdk import ClaudeSDKClient
+import asyncio
+
+async def interactive_session():
+ async with ClaudeSDKClient() as client:
+ # Send initial message
+ await client.query("What's the weather like?")
+
+ # Process responses
+ async for msg in client.receive_response():
+ print(msg)
+
+ # Send follow-up
+ await client.query("Tell me more about that")
+
+ # Process follow-up response
+ async for msg in client.receive_response():
+ print(msg)
+
+asyncio.run(interactive_session())
+```
+
+### Using custom tools with ClaudeSDKClient
+
+```python
+from claude_agent_sdk import (
+ ClaudeSDKClient,
+ ClaudeAgentOptions,
+ tool,
+ create_sdk_mcp_server,
+ AssistantMessage,
+ TextBlock
+)
+import asyncio
+from typing import Any
+
+# Define custom tools with @tool decorator
+@tool("calculate", "Perform mathematical calculations", {"expression": str})
+async def calculate(args: dict[str, Any]) -> dict[str, Any]:
+ try:
+ result = eval(args["expression"], {"__builtins__": {}})
+ return {
+ "content": [{
+ "type": "text",
+ "text": f"Result: {result}"
+ }]
+ }
+ except Exception as e:
+ return {
+ "content": [{
+ "type": "text",
+ "text": f"Error: {str(e)}"
+ }],
+ "is_error": True
+ }
+
+@tool("get_time", "Get current time", {})
+async def get_time(args: dict[str, Any]) -> dict[str, Any]:
+ from datetime import datetime
+ current_time = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+ return {
+ "content": [{
+ "type": "text",
+ "text": f"Current time: {current_time}"
+ }]
+ }
+
+async def main():
+ # Create SDK MCP server with custom tools
+ my_server = create_sdk_mcp_server(
+ name="utilities",
+ version="1.0.0",
+ tools=[calculate, get_time]
+ )
+
+ # Configure options with the server
+ options = ClaudeAgentOptions(
+ mcp_servers={"utils": my_server},
+ allowed_tools=[
+ "mcp__utils__calculate",
+ "mcp__utils__get_time"
+ ]
+ )
+
+ # Use ClaudeSDKClient for interactive tool usage
+ async with ClaudeSDKClient(options=options) as client:
+ await client.query("What's 123 * 456?")
+
+ # Process calculation response
+ async for message in client.receive_response():
+ if isinstance(message, AssistantMessage):
+ for block in message.content:
+ if isinstance(block, TextBlock):
+ print(f"Calculation: {block.text}")
+
+ # Follow up with time query
+ await client.query("What time is it now?")
+
+ async for message in client.receive_response():
+ if isinstance(message, AssistantMessage):
+ for block in message.content:
+ if isinstance(block, TextBlock):
+ print(f"Time: {block.text}")
+
+asyncio.run(main())
+```
+
+## Sandbox Configuration
+
+### `SandboxSettings`
+
+Configuration for sandbox behavior. Use this to enable command sandboxing and configure network restrictions programmatically.
+
+```python
+class SandboxSettings(TypedDict, total=False):
+ enabled: bool
+ autoAllowBashIfSandboxed: bool
+ excludedCommands: list[str]
+ allowUnsandboxedCommands: bool
+ network: SandboxNetworkConfig
+ ignoreViolations: SandboxIgnoreViolations
+ enableWeakerNestedSandbox: bool
+```
+
+| Property | Type | Default | Description |
+| :------- | :--- | :------ | :---------- |
+| `enabled` | `bool` | `False` | Enable sandbox mode for command execution |
+| `autoAllowBashIfSandboxed` | `bool` | `False` | Auto-approve bash commands when sandbox is enabled |
+| `excludedCommands` | `list[str]` | `[]` | Commands that always bypass sandbox restrictions (e.g., `["docker"]`). These run unsandboxed automatically without model involvement |
+| `allowUnsandboxedCommands` | `bool` | `False` | Allow the model to request running commands outside the sandbox. When `True`, the model can set `dangerouslyDisableSandbox` in tool input, which falls back to the [permissions system](#permissions-fallback-for-unsandboxed-commands) |
+| `network` | [`SandboxNetworkConfig`](#sandboxnetworkconfig) | `None` | Network-specific sandbox configuration |
+| `ignoreViolations` | [`SandboxIgnoreViolations`](#sandboxignoreviolations) | `None` | Configure which sandbox violations to ignore |
+| `enableWeakerNestedSandbox` | `bool` | `False` | Enable a weaker nested sandbox for compatibility |
+
+<Note>
+**Filesystem and network access restrictions** are NOT configured via sandbox settings. Instead, they are derived from [permission rules](https://code.claude.com/docs/en/settings#permission-settings):
+
+- **Filesystem read restrictions**: Read deny rules
+- **Filesystem write restrictions**: Edit allow/deny rules
+- **Network restrictions**: WebFetch allow/deny rules
+
+Use sandbox settings for command execution sandboxing, and permission rules for filesystem and network access control.
+</Note>
+
+#### Example usage
+
+```python
+from claude_agent_sdk import query, ClaudeAgentOptions, SandboxSettings
+
+sandbox_settings: SandboxSettings = {
+ "enabled": True,
+ "autoAllowBashIfSandboxed": True,
+ "excludedCommands": ["docker"],
+ "network": {
+ "allowLocalBinding": True,
+ "allowUnixSockets": ["/var/run/docker.sock"]
+ }
+}
+
+async for message in query(
+ prompt="Build and test my project",
+ options=ClaudeAgentOptions(sandbox=sandbox_settings)
+):
+ print(message)
+```
+
+### `SandboxNetworkConfig`
+
+Network-specific configuration for sandbox mode.
+
+```python
+class SandboxNetworkConfig(TypedDict, total=False):
+ allowLocalBinding: bool
+ allowUnixSockets: list[str]
+ allowAllUnixSockets: bool
+ httpProxyPort: int
+ socksProxyPort: int
+```
+
+| Property | Type | Default | Description |
+| :------- | :--- | :------ | :---------- |
+| `allowLocalBinding` | `bool` | `False` | Allow processes to bind to local ports (e.g., for dev servers) |
+| `allowUnixSockets` | `list[str]` | `[]` | Unix socket paths that processes can access (e.g., Docker socket) |
+| `allowAllUnixSockets` | `bool` | `False` | Allow access to all Unix sockets |
+| `httpProxyPort` | `int` | `None` | HTTP proxy port for network requests |
+| `socksProxyPort` | `int` | `None` | SOCKS proxy port for network requests |
+
+### `SandboxIgnoreViolations`
+
+Configuration for ignoring specific sandbox violations.
+
+```python
+class SandboxIgnoreViolations(TypedDict, total=False):
+ file: list[str]
+ network: list[str]
+```
+
+| Property | Type | Default | Description |
+| :------- | :--- | :------ | :---------- |
+| `file` | `list[str]` | `[]` | File path patterns to ignore violations for |
+| `network` | `list[str]` | `[]` | Network patterns to ignore violations for |
+
+### Permissions Fallback for Unsandboxed Commands
+
+When `allowUnsandboxedCommands` is enabled, the model can request to run commands outside the sandbox by setting `dangerouslyDisableSandbox: True` in the tool input. These requests fall back to the existing permissions system, meaning your `can_use_tool` handler will be invoked, allowing you to implement custom authorization logic.
+
+<Note>
+**`excludedCommands` vs `allowUnsandboxedCommands`:**
+- `excludedCommands`: A static list of commands that always bypass the sandbox automatically (e.g., `["docker"]`). The model has no control over this.
+- `allowUnsandboxedCommands`: Lets the model decide at runtime whether to request unsandboxed execution by setting `dangerouslyDisableSandbox: True` in the tool input.
+</Note>
+
+```python
+from claude_agent_sdk import query, ClaudeAgentOptions
+
+async def can_use_tool(tool: str, input: dict) -> bool:
+ # Check if the model is requesting to bypass the sandbox
+ if tool == "Bash" and input.get("dangerouslyDisableSandbox"):
+ # The model wants to run this command outside the sandbox
+ print(f"Unsandboxed command requested: {input.get('command')}")
+
+ # Return True to allow, False to deny
+ return is_command_authorized(input.get("command"))
+ return True
+
+async def main():
+ async for message in query(
+ prompt="Deploy my application",
+ options=ClaudeAgentOptions(
+ sandbox={
+ "enabled": True,
+ "allowUnsandboxedCommands": True # Model can request unsandboxed execution
+ },
+ permission_mode="default",
+ can_use_tool=can_use_tool
+ )
+ ):
+ print(message)
+```
+
+This pattern enables you to:
+
+- **Audit model requests**: Log when the model requests unsandboxed execution
+- **Implement allowlists**: Only permit specific commands to run unsandboxed
+- **Add approval workflows**: Require explicit authorization for privileged operations
+
+<Warning>
+Commands running with `dangerouslyDisableSandbox: True` have full system access. Ensure your `can_use_tool` handler validates these requests carefully.
+</Warning>
+
+## See also
+
+- [Python SDK guide](/docs/en/agent-sdk/python) - Tutorial and examples
+- [SDK overview](/docs/en/agent-sdk/overview) - General SDK concepts
+- [TypeScript SDK reference](/docs/en/agent-sdk/typescript) - TypeScript SDK documentation
+- [CLI reference](https://code.claude.com/docs/en/cli-reference) - Command-line interface
+- [Common workflows](https://code.claude.com/docs/en/common-workflows) - Step-by-step guides
\ No newline at end of file
diff --git a/llm-docs/claude-agent-sdk/TODO_LIST.md b/llm-docs/claude-agent-sdk/TODO_LIST.md
new file mode 100644
index 0000000..edea46d
--- /dev/null
+++ b/llm-docs/claude-agent-sdk/TODO_LIST.md
@@ -0,0 +1,176 @@
+# Todo Lists
+
+Track and display todos using the Claude Agent SDK for organized task management
+
+---
+
+Todo tracking provides a structured way to manage tasks and display progress to users. The Claude Agent SDK includes built-in todo functionality that helps organize complex workflows and keep users informed about task progression.
+
+### Todo Lifecycle
+
+Todos follow a predictable lifecycle:
+1. **Created** as `pending` when tasks are identified
+2. **Activated** to `in_progress` when work begins
+3. **Completed** when the task finishes successfully
+4. **Removed** when all tasks in a group are completed
+
+### When Todos Are Used
+
+The SDK automatically creates todos for:
+- **Complex multi-step tasks** requiring 3 or more distinct actions
+- **User-provided task lists** when multiple items are mentioned
+- **Non-trivial operations** that benefit from progress tracking
+- **Explicit requests** when users ask for todo organization
+
+## Examples
+
+### Monitoring Todo Changes
+
+<CodeGroup>
+
+```typescript TypeScript
+import { query } from "@anthropic-ai/claude-agent-sdk";
+
+for await (const message of query({
+ prompt: "Optimize my React app performance and track progress with todos",
+ options: { maxTurns: 15 }
+})) {
+ // Todo updates are reflected in the message stream
+ if (message.type === "assistant") {
+ for (const block of message.message.content) {
+ if (block.type === "tool_use" && block.name === "TodoWrite") {
+ const todos = block.input.todos;
+
+ console.log("Todo Status Update:");
+ todos.forEach((todo, index) => {
+ const status = todo.status === "completed" ? "✅" :
+ todo.status === "in_progress" ? "🔧" : "❌";
+ console.log(`${index + 1}. ${status} ${todo.content}`);
+ });
+ }
+ }
+ }
+}
+```
+
+```python Python
+from claude_agent_sdk import query, AssistantMessage, ToolUseBlock
+
+async for message in query(
+ prompt="Optimize my React app performance and track progress with todos",
+ options={"max_turns": 15}
+):
+ # Todo updates are reflected in the message stream
+ if isinstance(message, AssistantMessage):
+ for block in message.content:
+ if isinstance(block, ToolUseBlock) and block.name == "TodoWrite":
+ todos = block.input["todos"]
+
+ print("Todo Status Update:")
+ for i, todo in enumerate(todos):
+ status = "✅" if todo["status"] == "completed" else \
+ "🔧" if todo["status"] == "in_progress" else "❌"
+ print(f"{i + 1}. {status} {todo['content']}")
+```
+
+</CodeGroup>
+
+### Real-time Progress Display
+
+<CodeGroup>
+
+```typescript TypeScript
+import { query } from "@anthropic-ai/claude-agent-sdk";
+
+class TodoTracker {
+ private todos: any[] = [];
+
+ displayProgress() {
+ if (this.todos.length === 0) return;
+
+ const completed = this.todos.filter(t => t.status === "completed").length;
+ const inProgress = this.todos.filter(t => t.status === "in_progress").length;
+ const total = this.todos.length;
+
+ console.log(`\nProgress: ${completed}/${total} completed`);
+ console.log(`Currently working on: ${inProgress} task(s)\n`);
+
+ this.todos.forEach((todo, index) => {
+ const icon = todo.status === "completed" ? "✅" :
+ todo.status === "in_progress" ? "🔧" : "❌";
+ const text = todo.status === "in_progress" ? todo.activeForm : todo.content;
+ console.log(`${index + 1}. ${icon} ${text}`);
+ });
+ }
+
+ async trackQuery(prompt: string) {
+ for await (const message of query({
+ prompt,
+ options: { maxTurns: 20 }
+ })) {
+ if (message.type === "assistant") {
+ for (const block of message.message.content) {
+ if (block.type === "tool_use" && block.name === "TodoWrite") {
+ this.todos = block.input.todos;
+ this.displayProgress();
+ }
+ }
+ }
+ }
+ }
+}
+
+// Usage
+const tracker = new TodoTracker();
+await tracker.trackQuery("Build a complete authentication system with todos");
+```
+
+```python Python
+from claude_agent_sdk import query, AssistantMessage, ToolUseBlock
+from typing import List, Dict
+
+class TodoTracker:
+ def __init__(self):
+ self.todos: List[Dict] = []
+
+ def display_progress(self):
+ if not self.todos:
+ return
+
+ completed = len([t for t in self.todos if t["status"] == "completed"])
+ in_progress = len([t for t in self.todos if t["status"] == "in_progress"])
+ total = len(self.todos)
+
+ print(f"\nProgress: {completed}/{total} completed")
+ print(f"Currently working on: {in_progress} task(s)\n")
+
+ for i, todo in enumerate(self.todos):
+ icon = "✅" if todo["status"] == "completed" else \
+ "🔧" if todo["status"] == "in_progress" else "❌"
+ text = todo["activeForm"] if todo["status"] == "in_progress" else todo["content"]
+ print(f"{i + 1}. {icon} {text}")
+
+ async def track_query(self, prompt: str):
+ async for message in query(
+ prompt=prompt,
+ options={"max_turns": 20}
+ ):
+ if isinstance(message, AssistantMessage):
+ for block in message.content:
+ if isinstance(block, ToolUseBlock) and block.name == "TodoWrite":
+ self.todos = block.input["todos"]
+ self.display_progress()
+
+# Usage
+tracker = TodoTracker()
+await tracker.track_query("Build a complete authentication system with todos")
+```
+
+</CodeGroup>
+
+## Related Documentation
+
+- [TypeScript SDK Reference](/docs/en/agent-sdk/typescript)
+- [Python SDK Reference](/docs/en/agent-sdk/python)
+- [Streaming vs Single Mode](/docs/en/agent-sdk/streaming-vs-single-mode)
+- [Custom Tools](/docs/en/agent-sdk/custom-tools)
\ No newline at end of file
diff --git a/llm-docs/claude-agent-sdk/TOOLS.md b/llm-docs/claude-agent-sdk/TOOLS.md
new file mode 100644
index 0000000..e69de29