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.mdnew file mode 100644index 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 filediff --git a/llm-docs/claude-agent-sdk/TODO_LIST.md b/llm-docs/claude-agent-sdk/TODO_LIST.mdnew file mode 100644index 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 filediff --git a/llm-docs/claude-agent-sdk/TOOLS.md b/llm-docs/claude-agent-sdk/TOOLS.mdnew file mode 100644index 0000000..e69de29