clawd-code-sdk 1.0.3__tar.gz → 1.0.5__tar.gz

{clawd_code_sdk-1.0.3 → clawd_code_sdk-1.0.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: clawd-code-sdk
-Version: 1.0.3
+Version: 1.0.5
 Summary: Python SDK for Claude Code
 Project-URL: Documentation, https://github.com/phil65/claude-agent-sdk-python
 Project-URL: Homepage, https://github.com/phil65/claude-agent-sdk-python

{clawd_code_sdk-1.0.3 → clawd_code_sdk-1.0.5}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "clawd-code-sdk"
-version = "1.0.3"
+version = "1.0.5"
 description = "Python SDK for Claude Code"
 readme = "README.md"
 requires-python = ">=3.13"

{clawd_code_sdk-1.0.3 → clawd_code_sdk-1.0.5}/src/clawd_code_sdk/_internal/transport/subprocess_cli.py

@@ -469,8 +469,8 @@ def to_cli_args(options: ClaudeAgentOptions) -> list[str]:
     if options.context_1m:
         cmd.extend(["--betas", "context-1m-2025-08-07"])
 
-    if options.permission_prompt_tool_name:
-        cmd.extend(["--permission-prompt-tool", options.permission_prompt_tool_name])
+    if isinstance(options.on_permission, str):
+        cmd.extend(["--permission-prompt-tool", options.on_permission])
 
     if options.permission_mode:
         cmd.extend(["--permission-mode", options.permission_mode])

clawd_code_sdk-1.0.5/src/clawd_code_sdk/anthropic_types.py

@@ -0,0 +1,39 @@
+"""Anthropic SDK types for tool result content blocks.
+
+This module re-exports BetaContentBlock from the Anthropic SDK as the
+canonical union type for content blocks in tool results. BetaImageBlockParam
+is included because image content in MCP tool results uses the input
+(Param) type rather than an output block type.
+"""
+
+from __future__ import annotations
+
+from anthropic.types.beta import BetaContentBlock, BetaImageBlockParam
+from pydantic import TypeAdapter
+
+
+# Union of content types that can appear in tool results.
+# BetaContentBlock covers all server-side tool output blocks.
+# BetaImageBlockParam covers image content from MCP tools (TypedDict, not a model).
+ToolResultContentBlock = BetaContentBlock | BetaImageBlockParam
+
+_tool_result_content_adapter: TypeAdapter[list[ToolResultContentBlock]] | None = None
+
+
+def _get_adapter() -> TypeAdapter[list[ToolResultContentBlock]]:
+    global _tool_result_content_adapter  # noqa: PLW0603
+    if _tool_result_content_adapter is None:
+        _tool_result_content_adapter = TypeAdapter(list[ToolResultContentBlock])
+    return _tool_result_content_adapter
+
+
+def validate_tool_result_content(content: list[dict[str, object]]) -> list[ToolResultContentBlock]:
+    """Validate and parse raw tool result content into typed blocks.
+
+    Args:
+        content: Raw list of content block dictionaries from CLI output
+
+    Returns:
+        List of validated and typed content blocks
+    """
+    return _get_adapter().validate_python(content)

{clawd_code_sdk-1.0.3 → clawd_code_sdk-1.0.5}/src/clawd_code_sdk/client.py

@@ -94,10 +94,13 @@ class ClaudeSDKClient:
         # Validate and configure permission settings (matching TypeScript SDK logic)
         self.options.validate()
 
-        if self.options.can_use_tool:
-            # Automatically set permission_prompt_tool_name to "stdio" for control protocol
-            options = replace(self.options, permission_prompt_tool_name="stdio")
+        # If on_permission is a callback, extract it for Query and replace with
+        # "stdio" so the CLI routes permission requests through the control protocol.
+        if callable(self.options.on_permission):
+            can_use_tool = self.options.on_permission
+            options = replace(self.options, on_permission="stdio")
         else:
+            can_use_tool = None
             options = self.options
 
         # Use provided custom transport or create subprocess transport
@@ -140,7 +143,7 @@ class ClaudeSDKClient:
         # Create Query to handle control protocol
         self._query = Query(
             transport=self._transport,
-            can_use_tool=self.options.can_use_tool,
+            can_use_tool=can_use_tool,
             on_user_question=self.options.on_user_question,
             on_elicitation=self.options.on_elicitation,
             hooks=self.options.hooks,

{clawd_code_sdk-1.0.3 → clawd_code_sdk-1.0.5}/src/clawd_code_sdk/list_sessions.py

@@ -8,7 +8,6 @@ from typing import TYPE_CHECKING
 
 import anyenv
 
-from clawd_code_sdk.models import SDKSessionInfo
 from clawd_code_sdk.storage.helpers import (
     decode_project_path,
     get_claude_projects_dir,
@@ -17,7 +16,8 @@ from clawd_code_sdk.storage.helpers import (
 
 
 if TYPE_CHECKING:
-    from clawd_code_sdk.models.options import ListSessionsOptions
+    from clawd_code_sdk.models import SDKSessionInfo
+    from clawd_code_sdk.models.session import ListSessionsOptions
 
 logger = logging.getLogger(__name__)
 
@@ -53,10 +53,9 @@ def _read_git_branch_from_tail(path: Path) -> str | None:
                 if "gitBranch" not in stripped and "git_branch" not in stripped:
                     continue
                 try:
-                    entry: dict[str, object] = anyenv.load_json(stripped, return_type=dict)
-                    branch = entry.get("gitBranch") or entry.get("git_branch")
-                    if isinstance(branch, str) and branch:
-                        return branch
+                    match anyenv.load_json(stripped, return_type=dict):
+                        case {"gitBranch": str(branch)} | {"git_branch": str(branch)} if branch:
+                            return branch
                 except anyenv.JsonLoadError:
                     continue
     except OSError:
@@ -85,7 +84,7 @@ def _extract_session_metadata(session_path: Path) -> tuple[str | None, str | Non
             for line in fp:
                 if '"type":"summary"' in line or '"type": "summary"' in line:
                     try:
-                        entry: dict[str, object] = anyenv.load_json(line, return_type=dict)
+                        entry = anyenv.load_json(line, return_type=dict)
                         if summary := entry.get("summary"):
                             custom_title = str(summary)
                     except anyenv.JsonLoadError:
@@ -93,15 +92,10 @@ def _extract_session_metadata(session_path: Path) -> tuple[str | None, str | Non
 
                 elif first_prompt is None and ('"type":"user"' in line or '"type": "user"' in line):
                     try:
-                        entry = anyenv.load_json(line, return_type=dict)
-                        msg = entry.get("message")
-                        if (
-                            isinstance(msg, dict)
-                            and (content := msg.get("content"))
-                            and isinstance(content, str)
-                            and (first_line := content.split("\n")[0].strip())
-                        ):
-                            first_prompt = first_line
+                        match anyenv.load_json(line, return_type=dict):
+                            case {"message": {"content": str(content)}}:
+                                if first_line := content.split("\n")[0].strip():
+                                    first_prompt = first_line
                     except anyenv.JsonLoadError:
                         pass
 
@@ -114,45 +108,6 @@ def _extract_session_metadata(session_path: Path) -> tuple[str | None, str | Non
     return custom_title, first_prompt
 
 
-def _build_session_info(session_path: Path, project_cwd: str | None) -> SDKSessionInfo | None:
-    """Build an SDKSessionInfo from a session JSONL file.
-
-    Args:
-        session_path: Path to the ``.jsonl`` session file.
-        project_cwd: Working directory derived from the project folder name,
-            or None if unknown.
-
-    Returns:
-        Populated SDKSessionInfo, or None if the file cannot be read.
-    """
-    try:
-        stat = session_path.stat()
-    except OSError:
-        return None
-
-    session_id = session_path.stem
-    last_modified = int(stat.st_mtime * 1000)  # milliseconds since epoch
-    file_size = stat.st_size
-    custom_title, first_prompt = _extract_session_metadata(session_path)
-    # Get git branch from the tail of the file.
-    # The raw JSONL uses camelCase ("gitBranch") per ClaudeCodeBaseModel alias config.
-    # Not all entry types carry gitBranch, so we scan backward until we find one.
-    git_branch = _read_git_branch_from_tail(session_path)
-    # Build display summary: prefer custom title, then first prompt, then session ID
-    summary = custom_title or first_prompt or session_id
-
-    return SDKSessionInfo(
-        session_id=session_id,
-        summary=summary,
-        last_modified=last_modified,
-        file_size=file_size,
-        custom_title=custom_title,
-        first_prompt=first_prompt,
-        git_branch=git_branch,
-        cwd=project_cwd,
-    )
-
-
 def _list_session_files_for_dir(directory: str) -> list[tuple[Path, str | None]]:
     """List session files for a specific project directory.
 
@@ -213,27 +168,15 @@ def list_sessions(options: ListSessionsOptions | None = None) -> list[SDKSession
         # List all sessions across all projects
         all_sessions = list_sessions()
     """
+    from clawd_code_sdk.models import SDKSessionInfo
+
     opts = options or {}
-    directory = opts.get("dir")
+    dir_ = opts.get("dir")
     limit = opts.get("limit")
-
     # Collect session files
-    session_files: list[tuple[Path, str | None]]
-    if directory is not None:
-        session_files = _list_session_files_for_dir(directory)
-    else:
-        session_files = _list_all_session_files()
-
-    # Build session info for each file
-    sessions: list[SDKSessionInfo] = []
-    for session_path, cwd in session_files:
-        if info := _build_session_info(session_path, cwd):
-            sessions.append(info)
-
-    # Sort by last_modified descending (newest first)
+    files = _list_all_session_files() if dir_ is None else _list_session_files_for_dir(dir_)
+    sessions = [SDKSessionInfo.from_session_file(p, cwd) for p, cwd in files if p.exists()]
     sessions.sort(key=lambda s: s.last_modified, reverse=True)
-    # Apply limit
     if limit is not None and limit > 0:
         sessions = sessions[:limit]
-
     return sessions

{clawd_code_sdk-1.0.3 → clawd_code_sdk-1.0.5}/src/clawd_code_sdk/mcp_utils.py

@@ -247,8 +247,52 @@ def create_sdk_mcp_server(
     return McpSdkServerConfigWithInstance(type="sdk", name=name, instance=server)
 
 
+def _detect_capabilities(server: McpServer) -> dict[str, Any]:
+    """Detect which MCP capabilities a server supports based on registered handlers."""
+    from mcp.types import (
+        CallToolRequest,
+        GetPromptRequest,
+        ListPromptsRequest,
+        ListResourcesRequest,
+        ListResourceTemplatesRequest,
+        ListToolsRequest,
+        ReadResourceRequest,
+    )
+
+    capabilities: dict[str, Any] = {}
+    handlers = server.request_handlers
+    if handlers.get(ListToolsRequest) or handlers.get(CallToolRequest):
+        capabilities["tools"] = {}
+    if (
+        handlers.get(ListResourcesRequest)
+        or handlers.get(ReadResourceRequest)
+        or handlers.get(ListResourceTemplatesRequest)
+    ):
+        capabilities["resources"] = {}
+    if handlers.get(ListPromptsRequest) or handlers.get(GetPromptRequest):
+        capabilities["prompts"] = {}
+    return capabilities
+
+
 async def process_mcp_request(message: JSONRPCMessage, server: McpServer) -> JSONRPCResponse:
-    from mcp.types import CallToolRequest, CallToolRequestParams, CallToolResult, ListToolsRequest
+    from mcp.types import (
+        CallToolRequest,
+        CallToolRequestParams,
+        CallToolResult,
+        GetPromptRequest,
+        GetPromptRequestParams,
+        GetPromptResult,
+        ListPromptsRequest,
+        ListPromptsResult,
+        ListResourcesRequest,
+        ListResourcesResult,
+        ListResourceTemplatesRequest,
+        ListResourceTemplatesResult,
+        ListToolsRequest,
+        ReadResourceRequest,
+        ReadResourceRequestParams,
+        ReadResourceResult,
+    )
 
     raw_id = message.get("id")
     msg_id = raw_id if isinstance(raw_id, str | int) else 0
@@ -264,7 +308,7 @@ async def process_mcp_request(message: JSONRPCMessage, server: McpServer) -> JSO
                 # Handle MCP initialization - hardcoded for tools only, no listChanged
                 init_result = {
                     "protocolVersion": "2024-11-05",
-                    "capabilities": {"tools": {}},  # Tools capability without listChanged
+                    "capabilities": _detect_capabilities(server),
                     "serverInfo": {"name": server.name, "version": server.version or "1.0.0"},
                 }
                 return JSONRPCResultResponse(jsonrpc="2.0", id=msg_id, result=init_result)
@@ -291,11 +335,70 @@ async def process_mcp_request(message: JSONRPCMessage, server: McpServer) -> JSO
                 if result.root.isError:
                     response_data["is_error"] = True
                 return JSONRPCResultResponse(jsonrpc="2.0", id=msg_id, result=response_data)
+            case {"method": "resources/list"} if handler := server.request_handlers.get(
+                ListResourcesRequest
+            ):
+                list_resources_request = ListResourcesRequest()
+                result = await handler(list_resources_request)
+                assert isinstance(result.root, ListResourcesResult)
+                data = [
+                    r.model_dump(exclude_none=True, by_alias=True) for r in result.root.resources
+                ]
+                return JSONRPCResultResponse(jsonrpc="2.0", id=msg_id, result={"resources": data})
+
+            case {"method": "resources/read", "params": dict() as params} if (
+                handler := server.request_handlers.get(ReadResourceRequest)
+            ):
+                read_params = ReadResourceRequestParams(**params)
+                read_resource_request = ReadResourceRequest(params=read_params)
+                result = await handler(read_resource_request)
+                assert isinstance(result.root, ReadResourceResult)
+                contents = [
+                    c.model_dump(exclude_none=True, by_alias=True) for c in result.root.contents
+                ]
+                return JSONRPCResultResponse(
+                    jsonrpc="2.0", id=msg_id, result={"contents": contents}
+                )
+
+            case {"method": "resources/templates/list"} if handler := server.request_handlers.get(
+                ListResourceTemplatesRequest
+            ):
+                list_templates_request = ListResourceTemplatesRequest()
+                result = await handler(list_templates_request)
+                assert isinstance(result.root, ListResourceTemplatesResult)
+                data = [
+                    t.model_dump(exclude_none=True, by_alias=True)
+                    for t in result.root.resourceTemplates
+                ]
+                return JSONRPCResultResponse(
+                    jsonrpc="2.0", id=msg_id, result={"resourceTemplates": data}
+                )
+
+            case {"method": "prompts/list"} if handler := server.request_handlers.get(
+                ListPromptsRequest
+            ):
+                list_prompts_request = ListPromptsRequest()
+                result = await handler(list_prompts_request)
+                assert isinstance(result.root, ListPromptsResult)
+                data = [p.model_dump(exclude_none=True, by_alias=True) for p in result.root.prompts]
+                return JSONRPCResultResponse(jsonrpc="2.0", id=msg_id, result={"prompts": data})
+
+            case {"method": "prompts/get", "params": dict() as params} if (
+                handler := server.request_handlers.get(GetPromptRequest)
+            ):
+                get_params = GetPromptRequestParams(**params)
+                get_prompt_request = GetPromptRequest(params=get_params)
+                result = await handler(get_prompt_request)
+                assert isinstance(result.root, GetPromptResult)
+                return JSONRPCResultResponse(
+                    jsonrpc="2.0",
+                    id=msg_id,
+                    result=result.root.model_dump(exclude_none=True, by_alias=True),
+                )
+
             case {"method": "notifications/initialized"}:
                 # Handle initialized notification - just acknowledge it
                 return JSONRPCResultResponse(jsonrpc="2.0", id=msg_id, result={})
-            # Add more methods here as MCP SDK adds them (resources, prompts, etc.)
-            # This is the limitation Ashwin pointed out - we have to manually update
             case {"method": method}:
                 error = JSONRPCError(code=-32601, message=f"Method '{method}' not found")
                 return JSONRPCErrorResponse(jsonrpc="2.0", id=msg_id, error=error)

{clawd_code_sdk-1.0.3 → clawd_code_sdk-1.0.5}/src/clawd_code_sdk/models/__init__.py

@@ -216,7 +216,7 @@ from .content_blocks import (
     ToolUseBlock,
     content_block_adapter,
 )
-
+from .session import SDKSessionInfo, ListSessionsOptions
 from .messages import (
     AssistantMessage,
     AssistantMessageError,
@@ -229,7 +229,6 @@ from .messages import (
     ResultMessage,
     ResultSuccessMessage,
     SDKPermissionDenial,
-    SDKSessionInfo,
     StreamEvent,
     AuthStatusMessage,
     ToolProgressMessage,
@@ -257,7 +256,6 @@ from .options import (
     BaseSessionConfig,
     ContinueLatest,
     FromPR,
-    ListSessionsOptions,
     NewSession,
     ResumeSession,
     SessionConfig,

{clawd_code_sdk-1.0.3 → clawd_code_sdk-1.0.5}/src/clawd_code_sdk/models/content_blocks.py

@@ -68,6 +68,7 @@ class ToolResultBlock(BaseContentBlock):
     is_error: bool | None = None
 
     def get_parsed_content(self) -> list[ToolResultContentBlock] | str | None:
+        # TODO: or is it anthropic.types.beta.beta_tool_result_block_param.Content?
         from clawd_code_sdk.anthropic_types import validate_tool_result_content
 
         if self.content is None or isinstance(self.content, str):

{clawd_code_sdk-1.0.3 → clawd_code_sdk-1.0.5}/src/clawd_code_sdk/models/messages.py

@@ -80,42 +80,6 @@ OverAgeDisabledReason = Literal[
 ]
 
 
-class SDKSessionInfo(BaseModel):
-    """Session metadata returned by list_sessions."""
-
-    model_config = ConfigDict(extra="forbid")
-
-    session_id: str
-    """Unique session identifier (UUID)."""
-
-    summary: str
-    """Display title for the session: custom title, auto-generated summary, or first prompt."""
-
-    last_modified: int
-    """Last modified time in milliseconds since epoch."""
-
-    file_size: int | None = None
-    """Session file size in bytes."""
-
-    custom_title: str | None = None
-    """User-set session title via /rename."""
-
-    first_prompt: str | None = None
-    """First meaningful user prompt in the session."""
-
-    git_branch: str | None = None
-    """Git branch at the end of the session."""
-
-    cwd: str | None = None
-    """Working directory for the session."""
-
-    tag: str | None = None
-    """User-set session tag."""
-
-    created_at: float | None = None
-    """Creation time in milliseconds since epoch."""
-
-
 class RateLimitInfo(TypedDict):
     """Rate limit information."""
 

{clawd_code_sdk-1.0.3 → clawd_code_sdk-1.0.5}/src/clawd_code_sdk/models/options.py

@@ -6,7 +6,7 @@ from dataclasses import dataclass, field
 import json
 import logging
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, Literal, TypedDict, assert_never
+from typing import TYPE_CHECKING, Any, Literal, assert_never
 
 
 if TYPE_CHECKING:
@@ -101,25 +101,6 @@ Can also be specified as a plain ``str``, which is a shortcut for
 """
 
 
-class ListSessionsOptions(TypedDict, total=False):
-    """Options for listing sessions.
-
-    When ``dir`` is provided, returns sessions for that project directory
-    and its git worktrees. When omitted, returns sessions across all projects.
-    """
-
-    dir: str
-    """Directory to list sessions for.
-
-    When provided, returns sessions for this project directory
-    (and its git worktrees). When omitted, returns sessions
-    across all projects.
-    """
-
-    limit: int
-    """Maximum number of sessions to return."""
-
-
 @dataclass
 class ClaudeAgentOptions:
     """Query options for Claude SDK."""
@@ -131,6 +112,27 @@ class ClaudeAgentOptions:
     """Tools which execute without prompting for permission."""
     disallowed_tools: list[str] | None = None
     """Tools that are removed from agent context and cant be used."""
+    enable_agent_teams: bool = False
+    """Enable the experimental agent teams feature."""
+    disable_parallel_tool_use: bool = False
+    """Disable parallel too use (only one tool_use block per response)."""
+    tool_config: ToolConfig | None = None
+    """Per-tool configuration for built-in tools."""
+    enable_tool_search: bool | int | Literal["auto"] | None = None
+    """Enable or disable MCP tool search.
+
+    When many MCP tools are configured, tool definitions can consume a
+    significant portion of the context window. Tool search dynamically
+    loads tools on-demand instead of preloading all of them.
+
+    - ``True``: Always enabled.
+    - ``False``: Always disabled, all MCP tools loaded upfront.
+    - ``"auto"``: Activates when MCP tools exceed 10% of context (default behavior).
+    - ``int``: Auto-activates at this percentage threshold (e.g. ``5`` for 5%).
+    - ``None`` (default): Uses Claude Code's default (auto at 10%).
+
+    Requires models that support ``tool_reference`` blocks (Sonnet 4+, Opus 4+).
+    """
     # MCP
     mcp_servers: dict[str, McpServerConfig] | str | Path = field(default_factory=dict)
     """MCP servers for the agent."""
@@ -143,25 +145,27 @@ class ClaudeAgentOptions:
     """Permission mode."""
     allow_dangerously_skip_permissions: bool = False
     """Must be True when using permission_mode='bypassPermissions'."""
-    permission_prompt_tool_name: str | None = None
-    """MCP tool to handle permission prompts."""
-    can_use_tool: CanUseTool | None = None
-    """Tool permission callback.
+    on_permission: CanUseTool | str | None = None
+    """Permission handler for tool execution.
 
-    When set, the SDK automatically adds ``--permission-prompt-tool stdio`` to
-    the CLI, which tells the CLI to route permission requests through the
-    control protocol to this callback.
+    Accepts either:
+    - A callback function (``CanUseTool``): The SDK routes permission requests
+      through the control protocol to this callback. Automatically adds
+      ``--permission-prompt-tool stdio`` to the CLI.
+    - A string: Name of an MCP tool to handle permission prompts
+      (passed as ``--permission-prompt-tool <name>`` to the CLI).
+    - ``None``: Default behavior.
 
     Interaction with ``permission_mode``:
 
-    - ``"default"``: All tool calls are routed to this callback.
-    - ``"acceptEdits"``: All tool calls are routed to this callback.
-      The callback is responsible for implementing the auto-approve-edits policy.
+    - ``"default"``: All tool calls are routed to this handler.
+    - ``"acceptEdits"``: All tool calls are routed to this handler.
+      The handler is responsible for implementing the auto-approve-edits policy.
     - ``"plan"``: Only the synthetic ``ExitPlanMode`` tool is routed here.
-      Actual modification tools are blocked by the CLI before reaching the callback.
-    - ``"dontAsk"``: This callback is NEVER invoked. The CLI auto-denies all
+      Actual modification tools are blocked by the CLI before reaching the handler.
+    - ``"dontAsk"``: This handler is NEVER invoked. The CLI auto-denies all
       tools not pre-approved via the permissions config internally.
-    - ``"bypassPermissions"``: This callback is NEVER invoked. The CLI
+    - ``"bypassPermissions"``: This handler is NEVER invoked. The CLI
       auto-approves all tools internally.
     """
     on_user_question: OnUserQuestion | None = None
@@ -169,7 +173,7 @@ class ClaudeAgentOptions:
 
     Called when Claude asks the user a clarifying question via the
     AskUserQuestion tool. If not set, these requests fall through
-    to can_use_tool (if set) for backwards compatibility.
+    to on_permission (if it's a callback) for backwards compatibility.
     """
     on_elicitation: OnElicitation | None = None
     """Callback for handling MCP elicitation requests.
@@ -278,8 +282,6 @@ class ClaudeAgentOptions:
     When enabled, files can be rewound to their state at any user message
     using `ClaudeSDKClient.rewind_files()`.
     """
-    tool_config: ToolConfig | None = None
-    """Per-tool configuration for built-in tools."""
     agent: str | None = None
     """Agent name for the main thread. The agent must be defined in `agents` or settings."""
     context_1m: bool = False
@@ -298,25 +300,6 @@ class ClaudeAgentOptions:
     """
     worktree: bool | str = False
     """Create a new git worktree for the session (with optional name)."""
-    enable_agent_teams: bool = False
-    """Enable the experimental agent teams feature."""
-    disable_parallel_tool_use: bool = False
-    """Disable parallel too use (only one tool_use block per response)."""
-    enable_tool_search: bool | int | Literal["auto"] | None = None
-    """Enable or disable MCP tool search.
-
-    When many MCP tools are configured, tool definitions can consume a
-    significant portion of the context window. Tool search dynamically
-    loads tools on-demand instead of preloading all of them.
-
-    - ``True``: Always enabled.
-    - ``False``: Always disabled, all MCP tools loaded upfront.
-    - ``"auto"``: Activates when MCP tools exceed 10% of context (default behavior).
-    - ``int``: Auto-activates at this percentage threshold (e.g. ``5`` for 5%).
-    - ``None`` (default): Uses Claude Code's default (auto at 10%).
-
-    Requires models that support ``tool_reference`` blocks (Sonnet 4+, Opus 4+).
-    """
 
     def build_settings_value(self) -> str | None:
         """Build the CLI ``--settings`` value, merging sandbox if provided.
@@ -328,20 +311,14 @@ class ClaudeAgentOptions:
 
         from clawd_code_sdk.models.settings import ClaudeCodeSettings as _Settings
 
-        has_settings = self.settings is not None
-        has_sandbox = self.sandbox is not None
-
-        if not has_settings and not has_sandbox:
-            return None
-
         # Resolve settings to a dict (or pass through as file path)
         match self.settings:
             case _Settings() as model:
                 settings_obj = model.model_dump(by_alias=True, exclude_none=True)
-            case str() | Path() as path if has_sandbox and Path(path).exists():
+            case str() | Path() as path if self.sandbox and Path(path).exists():
                 with Path(path).open(encoding="utf-8") as f:
                     settings_obj = json.load(f)
-            case str() | Path() as path if has_sandbox:
+            case str() | Path() as path if self.sandbox:
                 logger.warning("Settings file not found: %s", path)
                 settings_obj = {}
             case str() | Path() as path:  # No sandbox to merge, pass file path directly to CLI
@@ -352,21 +329,10 @@ class ClaudeAgentOptions:
                 assert_never(unreachable)
 
         # Merge sandbox settings
-        if has_sandbox:
-            assert self.sandbox is not None
+        if self.sandbox is not None:
             settings_obj["sandbox"] = self.sandbox.model_dump(by_alias=True, exclude_none=True)
 
-        return anyenv.dump_json(settings_obj)
+        return anyenv.dump_json(settings_obj) if settings_obj else None
 
     def validate(self) -> None:
-        """Validate option constraints.
-
-        Raises:
-            ValueError: If mutually exclusive options are set.
-        """
-        if self.can_use_tool and self.permission_prompt_tool_name:
-            msg = (
-                "can_use_tool callback cannot be used with permission_prompt_tool_name. "
-                "Please use one or the other."
-            )
-            raise ValueError(msg)
+        """Validate option constraints."""