The agent that turns websites into APIs!
chore: remove outdated claude agent sdk docs
kalil0321ee8ef9ff52cf
diff --git a/llm-docs/claude-agent-sdk/QUICKSTART.md b/llm-docs/claude-agent-sdk/QUICKSTART.mddeleted file mode 100644index da2eb31..0000000--- a/llm-docs/claude-agent-sdk/QUICKSTART.md+++ /dev/null@@ -1,2017 +0,0 @@-# 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.mddeleted file mode 100644index edea46d..0000000--- a/llm-docs/claude-agent-sdk/TODO_LIST.md+++ /dev/null@@ -1,176 +0,0 @@-# 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.mddeleted file mode 100644index e69de29..0000000