claude-agent-sdk 0.0.23__py3-none-any.whl

claude_agent_sdk/types.py

@@ -0,0 +1,412 @@
+"""Type definitions for Claude SDK."""
+
+import sys
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Literal, TypedDict
+
+from typing_extensions import NotRequired
+
+if TYPE_CHECKING:
+    from mcp.server import Server as McpServer
+
+# Permission modes
+PermissionMode = Literal["default", "acceptEdits", "plan", "bypassPermissions"]
+
+# Agent definitions
+SettingSource = Literal["user", "project", "local"]
+
+
+class SystemPromptPreset(TypedDict):
+    """System prompt preset configuration."""
+
+    type: Literal["preset"]
+    preset: Literal["claude_code"]
+    append: NotRequired[str]
+
+
+@dataclass
+class AgentDefinition:
+    """Agent definition configuration."""
+
+    description: str
+    prompt: str
+    tools: list[str] | None = None
+    model: Literal["sonnet", "opus", "haiku", "inherit"] | None = None
+
+
+# Permission Update types (matching TypeScript SDK)
+PermissionUpdateDestination = Literal[
+    "userSettings", "projectSettings", "localSettings", "session"
+]
+
+PermissionBehavior = Literal["allow", "deny", "ask"]
+
+
+@dataclass
+class PermissionRuleValue:
+    """Permission rule value."""
+
+    tool_name: str
+    rule_content: str | None = None
+
+
+@dataclass
+class PermissionUpdate:
+    """Permission update configuration."""
+
+    type: Literal[
+        "addRules",
+        "replaceRules",
+        "removeRules",
+        "setMode",
+        "addDirectories",
+        "removeDirectories",
+    ]
+    rules: list[PermissionRuleValue] | None = None
+    behavior: PermissionBehavior | None = None
+    mode: PermissionMode | None = None
+    directories: list[str] | None = None
+    destination: PermissionUpdateDestination | None = None
+
+
+# Tool callback types
+@dataclass
+class ToolPermissionContext:
+    """Context information for tool permission callbacks."""
+
+    signal: Any | None = None  # Future: abort signal support
+    suggestions: list[PermissionUpdate] = field(
+        default_factory=list
+    )  # Permission suggestions from CLI
+
+
+# Match TypeScript's PermissionResult structure
+@dataclass
+class PermissionResultAllow:
+    """Allow permission result."""
+
+    behavior: Literal["allow"] = "allow"
+    updated_input: dict[str, Any] | None = None
+    updated_permissions: list[PermissionUpdate] | None = None
+
+
+@dataclass
+class PermissionResultDeny:
+    """Deny permission result."""
+
+    behavior: Literal["deny"] = "deny"
+    message: str = ""
+    interrupt: bool = False
+
+
+PermissionResult = PermissionResultAllow | PermissionResultDeny
+
+CanUseTool = Callable[
+    [str, dict[str, Any], ToolPermissionContext], Awaitable[PermissionResult]
+]
+
+
+##### Hook types
+# Supported hook event types. Due to setup limitations, the Python SDK does not
+# support SessionStart, SessionEnd, and Notification hooks.
+HookEvent = (
+    Literal["PreToolUse"]
+    | Literal["PostToolUse"]
+    | Literal["UserPromptSubmit"]
+    | Literal["Stop"]
+    | Literal["SubagentStop"]
+    | Literal["PreCompact"]
+)
+
+
+# See https://docs.anthropic.com/en/docs/claude-code/hooks#advanced%3A-json-output
+# for documentation of the output types. Currently, "continue", "stopReason",
+# and "suppressOutput" are not supported in the Python SDK.
+class HookJSONOutput(TypedDict):
+    # Whether to block the action related to the hook.
+    decision: NotRequired[Literal["block"]]
+    # Optionally add a system message that is not visible to Claude but saved in
+    # the chat transcript.
+    systemMessage: NotRequired[str]
+    # See each hook's individual "Decision Control" section in the documentation
+    # for guidance.
+    hookSpecificOutput: NotRequired[Any]
+
+
+@dataclass
+class HookContext:
+    """Context information for hook callbacks."""
+
+    signal: Any | None = None  # Future: abort signal support
+
+
+HookCallback = Callable[
+    # HookCallback input parameters:
+    # - input
+    #   See https://docs.anthropic.com/en/docs/claude-code/hooks#hook-input for
+    #   the type of 'input', the first value.
+    # - tool_use_id
+    # - context
+    [dict[str, Any], str | None, HookContext],
+    Awaitable[HookJSONOutput],
+]
+
+
+# Hook matcher configuration
+@dataclass
+class HookMatcher:
+    """Hook matcher configuration."""
+
+    # See https://docs.anthropic.com/en/docs/claude-code/hooks#structure for the
+    # expected string value. For example, for PreToolUse, the matcher can be
+    # a tool name like "Bash" or a combination of tool names like
+    # "Write|MultiEdit|Edit".
+    matcher: str | None = None
+
+    # A list of Python functions with function signature HookCallback
+    hooks: list[HookCallback] = field(default_factory=list)
+
+
+# MCP Server config
+class McpStdioServerConfig(TypedDict):
+    """MCP stdio server configuration."""
+
+    type: NotRequired[Literal["stdio"]]  # Optional for backwards compatibility
+    command: str
+    args: NotRequired[list[str]]
+    env: NotRequired[dict[str, str]]
+
+
+class McpSSEServerConfig(TypedDict):
+    """MCP SSE server configuration."""
+
+    type: Literal["sse"]
+    url: str
+    headers: NotRequired[dict[str, str]]
+
+
+class McpHttpServerConfig(TypedDict):
+    """MCP HTTP server configuration."""
+
+    type: Literal["http"]
+    url: str
+    headers: NotRequired[dict[str, str]]
+
+
+class McpSdkServerConfig(TypedDict):
+    """SDK MCP server configuration."""
+
+    type: Literal["sdk"]
+    name: str
+    instance: "McpServer"
+
+
+McpServerConfig = (
+    McpStdioServerConfig | McpSSEServerConfig | McpHttpServerConfig | McpSdkServerConfig
+)
+
+
+# Content block types
+@dataclass
+class TextBlock:
+    """Text content block."""
+
+    text: str
+
+
+@dataclass
+class ThinkingBlock:
+    """Thinking content block."""
+
+    thinking: str
+    signature: str
+
+
+@dataclass
+class ToolUseBlock:
+    """Tool use content block."""
+
+    id: str
+    name: str
+    input: dict[str, Any]
+
+
+@dataclass
+class ToolResultBlock:
+    """Tool result content block."""
+
+    tool_use_id: str
+    content: str | list[dict[str, Any]] | None = None
+    is_error: bool | None = None
+
+
+ContentBlock = TextBlock | ThinkingBlock | ToolUseBlock | ToolResultBlock
+
+
+# Message types
+@dataclass
+class UserMessage:
+    """User message."""
+
+    content: str | list[ContentBlock]
+    parent_tool_use_id: str | None = None
+
+
+@dataclass
+class AssistantMessage:
+    """Assistant message with content blocks."""
+
+    content: list[ContentBlock]
+    model: str
+    parent_tool_use_id: str | None = None
+
+
+@dataclass
+class SystemMessage:
+    """System message with metadata."""
+
+    subtype: str
+    data: dict[str, Any]
+
+
+@dataclass
+class ResultMessage:
+    """Result message with cost and usage information."""
+
+    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
+
+
+@dataclass
+class StreamEvent:
+    """Stream event for partial message updates during streaming."""
+
+    uuid: str
+    session_id: str
+    event: dict[str, Any]  # The raw Anthropic API stream event
+    parent_tool_use_id: str | None = None
+
+
+Message = UserMessage | AssistantMessage | SystemMessage | ResultMessage | StreamEvent
+
+
+@dataclass
+class ClaudeAgentOptions:
+    """Query options for Claude SDK."""
+
+    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
+    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
+    )  # Pass arbitrary CLI flags
+    debug_stderr: Any = (
+        sys.stderr
+    )  # Deprecated: File-like object for debug output. Use stderr callback instead.
+    stderr: Callable[[str], None] | None = None  # Callback for stderr output from CLI
+
+    # Tool permission callback
+    can_use_tool: CanUseTool | None = None
+
+    # Hook configurations
+    hooks: dict[HookEvent, list[HookMatcher]] | None = None
+
+    user: str | None = None
+
+    # Partial message streaming support
+    include_partial_messages: bool = False
+    # When true resumed sessions will fork to a new session ID rather than
+    # continuing the previous session.
+    fork_session: bool = False
+    # Agent definitions for custom agents
+    agents: dict[str, AgentDefinition] | None = None
+    # Setting sources to load (user, project, local)
+    setting_sources: list[SettingSource] | None = None
+
+
+# SDK Control Protocol
+class SDKControlInterruptRequest(TypedDict):
+    subtype: Literal["interrupt"]
+
+
+class SDKControlPermissionRequest(TypedDict):
+    subtype: Literal["can_use_tool"]
+    tool_name: str
+    input: dict[str, Any]
+    # TODO: Add PermissionUpdate type here
+    permission_suggestions: list[Any] | None
+    blocked_path: str | None
+
+
+class SDKControlInitializeRequest(TypedDict):
+    subtype: Literal["initialize"]
+    hooks: dict[HookEvent, Any] | None
+
+
+class SDKControlSetPermissionModeRequest(TypedDict):
+    subtype: Literal["set_permission_mode"]
+    # TODO: Add PermissionMode
+    mode: str
+
+
+class SDKHookCallbackRequest(TypedDict):
+    subtype: Literal["hook_callback"]
+    callback_id: str
+    input: Any
+    tool_use_id: str | None
+
+
+class SDKControlMcpMessageRequest(TypedDict):
+    subtype: Literal["mcp_message"]
+    server_name: str
+    message: Any
+
+
+class SDKControlRequest(TypedDict):
+    type: Literal["control_request"]
+    request_id: str
+    request: (
+        SDKControlInterruptRequest
+        | SDKControlPermissionRequest
+        | SDKControlInitializeRequest
+        | SDKControlSetPermissionModeRequest
+        | SDKHookCallbackRequest
+        | SDKControlMcpMessageRequest
+    )
+
+
+class ControlResponse(TypedDict):
+    subtype: Literal["success"]
+    request_id: str
+    response: dict[str, Any] | None
+
+
+class ControlErrorResponse(TypedDict):
+    subtype: Literal["error"]
+    request_id: str
+    error: str
+
+
+class SDKControlResponse(TypedDict):
+    type: Literal["control_response"]
+    response: ControlResponse | ControlErrorResponse

claude_agent_sdk-0.0.23.dist-info/METADATA

@@ -0,0 +1,309 @@
+Metadata-Version: 2.4
+Name: claude-agent-sdk
+Version: 0.0.23
+Summary: Python SDK for Claude Code
+Project-URL: Homepage, https://github.com/anthropics/claude-agent-sdk-python
+Project-URL: Documentation, https://docs.anthropic.com/en/docs/claude-code/sdk
+Project-URL: Issues, https://github.com/anthropics/claude-agent-sdk-python/issues
+Author-email: Anthropic <support@anthropic.com>
+License: MIT
+License-File: LICENSE
+Keywords: ai,anthropic,claude,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: anyio>=4.0.0
+Requires-Dist: mcp>=0.1.0
+Requires-Dist: typing-extensions>=4.0.0; python_version < '3.11'
+Provides-Extra: dev
+Requires-Dist: anyio[trio]>=4.0.0; extra == 'dev'
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.20.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Claude Agent SDK for Python
+
+Python SDK for Claude Agent. See the [Claude Agent SDK documentation](https://docs.anthropic.com/en/docs/claude-code/sdk/sdk-python) for more information.
+
+## Installation
+
+```bash
+pip install claude-agent-sdk
+```
+
+**Prerequisites:**
+- Python 3.10+
+- Node.js 
+- Claude Code: `npm install -g @anthropic-ai/claude-code`
+
+## Quick Start
+
+```python
+import anyio
+from claude_agent_sdk import query
+
+async def main():
+    async for message in query(prompt="What is 2 + 2?"):
+        print(message)
+
+anyio.run(main)
+```
+
+## Basic Usage: query()
+
+`query()` is an async function for querying Claude Code. It returns an `AsyncIterator` of response messages. See [src/claude_agent_sdk/query.py](src/claude_agent_sdk/query.py).
+
+```python
+from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, TextBlock
+
+# Simple query
+async for message in query(prompt="Hello Claude"):
+    if isinstance(message, AssistantMessage):
+        for block in message.content:
+            if isinstance(block, TextBlock):
+                print(block.text)
+
+# With options
+options = ClaudeAgentOptions(
+    system_prompt="You are a helpful assistant",
+    max_turns=1
+)
+
+async for message in query(prompt="Tell me a joke", options=options):
+    print(message)
+```
+
+### Using Tools
+
+```python
+options = ClaudeAgentOptions(
+    allowed_tools=["Read", "Write", "Bash"],
+    permission_mode='acceptEdits'  # auto-accept file edits
+)
+
+async for message in query(
+    prompt="Create a hello.py file", 
+    options=options
+):
+    # Process tool use and results
+    pass
+```
+
+### Working Directory
+
+```python
+from pathlib import Path
+
+options = ClaudeAgentOptions(
+    cwd="/path/to/project"  # or Path("/path/to/project")
+)
+```
+
+## ClaudeSDKClient
+
+`ClaudeSDKClient` supports bidirectional, interactive conversations with Claude
+Code. See [src/claude_agent_sdk/client.py](src/claude_agent_sdk/client.py).
+
+Unlike `query()`, `ClaudeSDKClient` additionally enables **custom tools** and **hooks**, both of which can be defined as Python functions.
+
+### Custom Tools (as In-Process SDK MCP Servers)
+
+A **custom tool** is a Python function that you can offer to Claude, for Claude to invoke as needed.
+
+Custom tools are implemented in-process MCP servers that run directly within your Python application, eliminating the need for separate processes that regular MCP servers require.
+
+For an end-to-end example, see [MCP Calculator](examples/mcp_calculator.py).
+
+#### Creating a Simple Tool
+
+```python
+from claude_agent_sdk import tool, create_sdk_mcp_server, ClaudeAgentOptions, ClaudeSDKClient
+
+# Define a tool using the @tool decorator
+@tool("greet", "Greet a user", {"name": str})
+async def greet_user(args):
+    return {
+        "content": [
+            {"type": "text", "text": f"Hello, {args['name']}!"}
+        ]
+    }
+
+# Create an SDK MCP server
+server = create_sdk_mcp_server(
+    name="my-tools",
+    version="1.0.0",
+    tools=[greet_user]
+)
+
+# Use it with Claude
+options = ClaudeAgentOptions(
+    mcp_servers={"tools": server},
+    allowed_tools=["mcp__tools__greet"]
+)
+
+async with ClaudeSDKClient(options=options) as client:
+    await client.query("Greet Alice")
+
+    # Extract and print response
+    async for msg in client.receive_response():
+        print(msg)
+```
+
+#### Benefits Over External MCP Servers
+
+- **No subprocess management** - Runs in the same process as your application
+- **Better performance** - No IPC overhead for tool calls
+- **Simpler deployment** - Single Python process instead of multiple
+- **Easier debugging** - All code runs in the same process
+- **Type safety** - Direct Python function calls with type hints
+
+#### Migration from External Servers
+
+```python
+# BEFORE: External MCP server (separate process)
+options = ClaudeAgentOptions(
+    mcp_servers={
+        "calculator": {
+            "type": "stdio",
+            "command": "python",
+            "args": ["-m", "calculator_server"]
+        }
+    }
+)
+
+# AFTER: SDK MCP server (in-process)
+from my_tools import add, subtract  # Your tool functions
+
+calculator = create_sdk_mcp_server(
+    name="calculator",
+    tools=[add, subtract]
+)
+
+options = ClaudeAgentOptions(
+    mcp_servers={"calculator": calculator}
+)
+```
+
+#### Mixed Server Support
+
+You can use both SDK and external MCP servers together:
+
+```python
+options = ClaudeAgentOptions(
+    mcp_servers={
+        "internal": sdk_server,      # In-process SDK server
+        "external": {                # External subprocess server
+            "type": "stdio",
+            "command": "external-server"
+        }
+    }
+)
+```
+
+### Hooks
+
+A **hook** is a Python function that the Claude Code *application* (*not* Claude) invokes at specific points of the Claude agent loop. Hooks can provide deterministic processing and automated feedback for Claude. Read more in [Claude Code Hooks Reference](https://docs.anthropic.com/en/docs/claude-code/hooks).
+
+For more examples, see examples/hooks.py.
+
+#### Example
+
+```python
+from claude_agent_sdk import ClaudeAgentOptions, ClaudeSDKClient, HookMatcher
+
+async def check_bash_command(input_data, tool_use_id, context):
+    tool_name = input_data["tool_name"]
+    tool_input = input_data["tool_input"]
+    if tool_name != "Bash":
+        return {}
+    command = tool_input.get("command", "")
+    block_patterns = ["foo.sh"]
+    for pattern in block_patterns:
+        if pattern in command:
+            return {
+                "hookSpecificOutput": {
+                    "hookEventName": "PreToolUse",
+                    "permissionDecision": "deny",
+                    "permissionDecisionReason": f"Command contains invalid pattern: {pattern}",
+                }
+            }
+    return {}
+
+options = ClaudeAgentOptions(
+    allowed_tools=["Bash"],
+    hooks={
+        "PreToolUse": [
+            HookMatcher(matcher="Bash", hooks=[check_bash_command]),
+        ],
+    }
+)
+
+async with ClaudeSDKClient(options=options) as client:
+    # Test 1: Command with forbidden pattern (will be blocked)
+    await client.query("Run the bash command: ./foo.sh --help")
+    async for msg in client.receive_response():
+        print(msg)
+
+    print("\n" + "=" * 50 + "\n")
+
+    # Test 2: Safe command that should work
+    await client.query("Run the bash command: echo 'Hello from hooks example!'")
+    async for msg in client.receive_response():
+        print(msg)
+```
+
+
+## Types
+
+See [src/claude_agent_sdk/types.py](src/claude_agent_sdk/types.py) for complete type definitions:
+- `ClaudeAgentOptions` - Configuration options
+- `AssistantMessage`, `UserMessage`, `SystemMessage`, `ResultMessage` - Message types
+- `TextBlock`, `ToolUseBlock`, `ToolResultBlock` - Content blocks
+
+## Error Handling
+
+```python
+from claude_agent_sdk import (
+    ClaudeSDKError,      # Base error
+    CLINotFoundError,    # Claude Code not installed
+    CLIConnectionError,  # Connection issues
+    ProcessError,        # Process failed
+    CLIJSONDecodeError,  # JSON parsing issues
+)
+
+try:
+    async for message in query(prompt="Hello"):
+        pass
+except CLINotFoundError:
+    print("Please install 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}")
+```
+
+See [src/claude_agent_sdk/_errors.py](src/claude_agent_sdk/_errors.py) for all error types.
+
+## Available Tools
+
+See the [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code/settings#tools-available-to-claude) for a complete list of available tools.
+
+## Examples
+
+See [examples/quick_start.py](examples/quick_start.py) for a complete working example.
+
+See [examples/streaming_mode.py](examples/streaming_mode.py) for comprehensive examples involving `ClaudeSDKClient`. You can even run interactive examples in IPython from [examples/streaming_mode_ipython.py](examples/streaming_mode_ipython.py).
+
+## License
+
+MIT