clawd-code-sdk 0.3.5__tar.gz → 0.3.7__tar.gz

{clawd_code_sdk-0.3.5 → clawd_code_sdk-0.3.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: clawd-code-sdk
-Version: 0.3.5
+Version: 0.3.7
 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-0.3.5 → clawd_code_sdk-0.3.7}/pyproject.toml

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

{clawd_code_sdk-0.3.5 → clawd_code_sdk-0.3.7}/src/clawd_code_sdk/client.py

@@ -118,13 +118,14 @@ class ClaudeSDKClient:
         # Extract system prompt for initialize request
         system_prompt: str | None = None
         append_system_prompt: str | None = None
-        match self.options.system_prompt:
-            case None:
-                system_prompt = ""  # Explicitly clear default system prompt
-            case str() as prompt_str:
-                system_prompt = prompt_str
-            case {"type": "preset", "append": str() as append}:
-                append_system_prompt = append
+        if self.options.system_prompt is None:
+            if not self.options.include_builtin_system_prompt:
+                system_prompt = ""  # Clear the builtin prompt
+            # else: send nothing, CLI uses its default builtin prompt
+        elif self.options.include_builtin_system_prompt:
+            append_system_prompt = self.options.system_prompt
+        else:
+            system_prompt = self.options.system_prompt
 
         # JSON schema for structured output
         json_schema: dict[str, Any] | None

{clawd_code_sdk-0.3.5 → clawd_code_sdk-0.3.7}/src/clawd_code_sdk/models/__init__.py

@@ -90,6 +90,7 @@ from .input_types import (
     AskUserQuestionOption,
     BashInput,
     BashOutputInput,
+    EnterPlanModeInput,
     ExitPlanModeInput,
     FileEditInput,
     FileReadInput,
@@ -100,6 +101,7 @@ from .input_types import (
     ListMcpResourcesInput,
     NotebookEditInput,
     ReadMcpResourceInput,
+    SkillInput,
     TodoItem,
     TodoWriteInput,
     ToolInput,
@@ -141,11 +143,14 @@ from .output_types import (
     AskUserQuestionItem,
     AskUserQuestionOutput,
     BashOutput,
+    BashOutputOutput,
     BashToolUseResult,
     ConfigOutput,
     EditOutput,
     EditToolUseResult,
+    EnterPlanModeOutput,
     EnterWorktreeOutput,
+    KillShellOutput,
     ExitPlanModeOutput,
     GitDiff,
     GlobOutput,
@@ -169,6 +174,7 @@ from .output_types import (
     ReadPdfOutput,
     ReadTextOutput,
     ReadToolUseResult,
+    SkillOutput,
     StructuredPatchHunk,
     SubscribeMcpResourceOutput,
     SubscribePollingOutput,
@@ -426,9 +432,11 @@ __all__ = [
     "WebSearchInput",
     "TodoItem",
     "TodoWriteInput",
+    "EnterPlanModeInput",
     "ExitPlanModeInput",
     "ListMcpResourcesInput",
     "ReadMcpResourceInput",
+    "SkillInput",
     # output_types (actual tool_use_result wire format)
     "TOOL_USE_RESULT_TYPES",
     "AgentAsyncLaunchedOutput",
@@ -442,9 +450,12 @@ __all__ = [
     "AskUserQuestionItem",
     "AskUserQuestionOutput",
     "BashOutput",
+    "BashOutputOutput",
     "ConfigOutput",
     "EditOutput",
+    "EnterPlanModeOutput",
     "EnterWorktreeOutput",
+    "KillShellOutput",
     "ExitPlanModeOutput",
     "GitDiff",
     "GlobOutput",
@@ -467,6 +478,7 @@ __all__ = [
     "ReadPdfFileInfo",
     "ReadPdfOutput",
     "ReadTextOutput",
+    "SkillOutput",
     "StructuredPatchHunk",
     "SubscribeMcpResourceOutput",
     "SubscribePollingOutput",

{clawd_code_sdk-0.3.5 → clawd_code_sdk-0.3.7}/src/clawd_code_sdk/models/agents.py

@@ -53,6 +53,7 @@ class AgentDefinition:
     critical_system_reminder_experimental: str | None = None
     skills: list[str] | None = None
     max_turns: int | None = None
+    background: bool | None = None
     # permission_mode: PermissionMode | None = None
     # hooks: dict[HookEvent, list[HookMatcher]] | None = None
 

{clawd_code_sdk-0.3.5 → clawd_code_sdk-0.3.7}/src/clawd_code_sdk/models/base.py

@@ -22,6 +22,8 @@ ModelName = Literal["sonnet", "opus", "haiku"]
 PermissionBehavior = Literal["allow", "deny", "ask"]
 ReasoningEffort = Literal["low", "medium", "high", "max"]
 TaskStatus = Literal["completed", "failed", "stopped"]
+CompactionTrigger = Literal["auto", "manual"]
+
 StopReason = Literal[
     "end_turn",
     "max_tokens",

{clawd_code_sdk-0.3.5 → clawd_code_sdk-0.3.7}/src/clawd_code_sdk/models/hooks.py

@@ -6,6 +6,8 @@ from collections.abc import Awaitable, Callable
 from dataclasses import dataclass, field
 from typing import TYPE_CHECKING, Any, Literal, NotRequired, TypedDict
 
+from clawd_code_sdk.models.base import CompactionTrigger  # noqa: TC001
+
 
 if TYPE_CHECKING:
     from collections.abc import Sequence
@@ -101,7 +103,7 @@ class PreCompactHookInput(BaseHookInput):
     """Input data for PreCompact hook events."""
 
     hook_event_name: Literal["PreCompact"]
-    trigger: Literal["manual", "auto"]
+    trigger: CompactionTrigger
     custom_instructions: str | None
 
 

{clawd_code_sdk-0.3.5 → clawd_code_sdk-0.3.7}/src/clawd_code_sdk/models/input_types.py

@@ -252,6 +252,29 @@ class EnterWorktreeInput(TypedDict):
     """Optional name for the worktree. A random name is generated if not provided."""
 
 
+@_extra_allow
+class SkillInput(TypedDict):
+    """Input for the Skill tool. Invokes a named skill (slash command).
+
+    Not part of the official SDK ToolInputSchemas as of SDK v0.2.62.
+    Shape derived from empirical testing.
+    """
+
+    skill: str
+    """The skill name (e.g., "commit", "review", "debug")."""
+    args: NotRequired[str]
+    """Optional arguments for the skill."""
+
+
+@_extra_allow
+class EnterPlanModeInput(TypedDict):
+    """Input for the EnterPlanMode tool. Enters planning mode.
+
+    Not part of the official SDK ToolInputSchemas as of SDK v0.2.62.
+    Shape derived from empirical testing.
+    """
+
+
 @_extra_allow
 class ExitPlanModeInput(TypedDict):
     """Input for the ExitPlanMode tool. Exits planning mode for user approval."""
@@ -297,6 +320,8 @@ ToolInput = (
     | ExitPlanModeInput
     | ListMcpResourcesInput
     | ReadMcpResourceInput
+    | SkillInput
+    | EnterPlanModeInput
 )
 
 #: Mapping from tool name to its input type.
@@ -319,4 +344,6 @@ TOOL_INPUT_TYPES: dict[str, type[ToolInput]] = {
     "ExitPlanMode": ExitPlanModeInput,
     "ListMcpResources": ListMcpResourcesInput,
     "ReadMcpResource": ReadMcpResourceInput,
+    "Skill": SkillInput,
+    "EnterPlanMode": EnterPlanModeInput,
 }

{clawd_code_sdk-0.3.5 → clawd_code_sdk-0.3.7}/src/clawd_code_sdk/models/messages.py

@@ -23,7 +23,14 @@ from clawd_code_sdk.models.content_blocks import ContentBlock, TextBlock  # noqa
 from clawd_code_sdk.models.mcp import McpConnectionStatus  # noqa: TC001
 from clawd_code_sdk.models.output_types import ToolUseResult  # noqa: TC001
 
-from .base import ApiKeySource, PermissionMode, StopReason, TaskStatus, ToolName  # noqa: TC001
+from .base import (  # noqa: TC001
+    ApiKeySource,
+    CompactionTrigger,
+    PermissionMode,
+    StopReason,
+    TaskStatus,
+    ToolName,
+)
 
 
 if TYPE_CHECKING:
@@ -178,14 +185,14 @@ class InitSystemMessage(BaseSystemMessage):
     """System init message with session metadata."""
 
     subtype: Literal["init"] = "init"
-    apiKeySource: ApiKeySource | None = None  # noqa: N815
+    apiKeySource: ApiKeySource | None  # noqa: N815
     cwd: str
     tools: list[str]
     mcp_servers: list[McpServerStatus]
     model: Model
     permissionMode: PermissionMode  # noqa: N815
     slash_commands: list[str]
-    output_style: Literal["default", "json"]
+    output_style: Literal["default", "json"] | str
     claude_code_version: str
     agents: list[str]
     skills: list[str]
@@ -213,7 +220,7 @@ class StatusSystemMessage(BaseSystemMessage):
 
 
 class TriggerMetadata(TypedDict):
-    trigger: Literal["auto", "manual"]
+    trigger: CompactionTrigger
     pre_tokens: int
 
 
@@ -338,21 +345,6 @@ class HookResponseSystemMessage(BaseSystemMessage):
     output: str
 
 
-class CacheCreation(TypedDict):
-    ephemeral_1h_input_tokens: int
-    ephemeral_5m_input_tokens: int
-
-
-class ServerToolUse(TypedDict):
-    web_search_requests: int
-    web_fetch_requests: int
-    service_tier: Literal["standard", "priority"]
-    cache_creation: CacheCreation
-    inference_geo: Literal["not_available"] | str
-    iterations: list[Any]
-    speed: str
-
-
 class ModelUsage(TypedDict):
     inputTokens: int
     outputTokens: int
@@ -362,13 +354,12 @@ class ModelUsage(TypedDict):
     costUSD: float
     contextWindow: int
     maxOutputTokens: int
-    server_tool_use: ServerToolUse
 
 
 class SDKPermissionDenial(TypedDict):
     tool_name: ToolName | str
     tool_use_id: str
-    tool_input: ToolInput
+    tool_input: ToolInput | dict[str, Any]
 
 
 class Usage(TypedDict):
@@ -391,9 +382,9 @@ class BaseResultMessage(BaseMessage):
     num_turns: int
     total_cost_usd: float
     usage: Usage
-    stop_reason: StopReason | None = None
-    modelUsage: dict[str, ModelUsage] | None = None  # noqa: N815
-    permission_denials: list[SDKPermissionDenial] | None = None
+    stop_reason: StopReason | None
+    modelUsage: dict[str, ModelUsage]  # noqa: N815
+    permission_denials: list[SDKPermissionDenial]
 
 
 @dataclass(kw_only=True)

{clawd_code_sdk-0.3.5 → clawd_code_sdk-0.3.7}/src/clawd_code_sdk/models/options.py

@@ -10,12 +10,12 @@ from typing import TYPE_CHECKING, Any, Literal, TypedDict
 
 
 if TYPE_CHECKING:
-    from collections.abc import Callable
+    from collections.abc import Callable, Sequence
 
     from clawd_code_sdk.models.base import ModelName
     from clawd_code_sdk.models.permissions import OnUserQuestion
 
-    from .agents import AgentDefinition, SystemPromptPreset, ToolsPreset
+    from .agents import AgentDefinition, ToolsPreset
     from .base import PermissionMode, ReasoningEffort, SettingSource, ThinkingConfig
     from .hooks import HookEvent, HookMatcher
     from .mcp import McpServerConfig, SdkPluginConfig
@@ -192,7 +192,7 @@ class ClaudeAgentOptions:
     """CLI path override (auto-detects by default)."""
     extra_args: dict[str, str | None] = field(default_factory=dict)
     """Arbitrary extra CLI flags."""
-    max_buffer_size: int | None = None
+    max_buffer_size: int = 10 * 1024 * 1024
     """Max bytes when buffering CLI stdout."""
     stderr: Callable[[str], None] | None = None
     """Callback for stderr output from CLI."""
@@ -201,7 +201,7 @@ class ClaudeAgentOptions:
     user: str | None = None
     """User for the AnyIO process."""
     # CWD
-    add_dirs: list[str | Path] = field(default_factory=list)
+    add_dirs: Sequence[str | Path] = field(default_factory=list)
     """Add additional working directories."""
     cwd: str | Path | None = None
     """The working directory for the agent."""
@@ -219,8 +219,14 @@ class ClaudeAgentOptions:
     debug_file: str | None = None
     """Write debug logs to a specific file path. Implicitly enables debug mode."""
     # Agent config
-    system_prompt: str | SystemPromptPreset | None = None
+    system_prompt: str | None = None
     """System prompt for the agent."""
+    include_builtin_system_prompt: bool = True
+    """Whether to include Claude Code's builtin system prompt.
+
+    When True (default) and system_prompt is set, it is appended to the
+    builtin system prompt. When False, the system_prompt replaces it entirely.
+    """
     hooks: dict[HookEvent, list[HookMatcher]] | None = None
     """Hook configurations."""
     agents: dict[str, AgentDefinition] | None = None

{clawd_code_sdk-0.3.5 → clawd_code_sdk-0.3.7}/src/clawd_code_sdk/models/output_types.py

@@ -94,6 +94,8 @@ class AgentAsyncLaunchedOutput(TypedDict):
 
     status: Literal["async_launched"]
     """Indicates the agent was launched in the background."""
+    isAsync: Literal[True]
+    """Always True for async-launched agents."""
     agentId: str
     """The ID of the async agent."""
     description: str
@@ -165,8 +167,8 @@ class TaskInfo(TypedDict):
     """Information about a background task."""
 
     task_id: str
-    task_type: str
-    status: str
+    task_type: Literal["local_bash", "agent"]
+    status: Literal["running", "completed", "failed"]
     description: str
     output: str
     exitCode: int | None
@@ -175,11 +177,61 @@ class TaskInfo(TypedDict):
 class TaskOutputResult(TypedDict):
     """``tool_use_result`` for the TaskOutput tool (background task polling)."""
 
-    retrieval_status: str
-    """Status of the retrieval: ``"not_ready"``, ``"ready"``, etc."""
+    retrieval_status: Literal["completed", "timeout", "running"]
+    """Status of the retrieval."""
     task: TaskInfo
 
 
+# ---------------------------------------------------------------------------
+# BashOutput (checking background shells — tool name "BashOutput")
+# ---------------------------------------------------------------------------
+
+
+class BashOutputOutput(TypedDict):
+    """``tool_use_result`` for the BashOutput tool (background shell output retrieval).
+
+    Not part of the official SDK ToolOutputSchemas as of SDK v0.2.62.
+    Shape derived from: https://github.com/kzahel/yepanywhere/blob/main/packages/shared/src/claude-sdk-schema/tool/ToolResultSchemas.ts
+    """
+
+    shellId: NotRequired[str]
+    """ID of the background shell."""
+    command: NotRequired[str]
+    """The command that was executed."""
+    status: NotRequired[Literal["running", "completed", "failed"]]
+    """Current status of the command."""
+    exitCode: NotRequired[int | None]
+    """Exit code of the command, or None if still running."""
+    stdout: NotRequired[str]
+    """Standard output."""
+    stderr: NotRequired[str]
+    """Standard error."""
+    stdoutLines: NotRequired[int]
+    """Number of lines in stdout."""
+    stderrLines: NotRequired[int]
+    """Number of lines in stderr."""
+    timestamp: NotRequired[str]
+    """Timestamp of the output."""
+
+
+# ---------------------------------------------------------------------------
+# KillShell (kill background shell — tool name "KillBash")
+# ---------------------------------------------------------------------------
+
+
+class KillShellOutput(TypedDict):
+    """``tool_use_result`` for the KillBash tool.
+
+    Not part of the official SDK ToolOutputSchemas as of SDK v0.2.62.
+    Shape derived from: https://github.com/kzahel/yepanywhere/blob/main/packages/shared/src/claude-sdk-schema/tool/ToolResultSchemas.ts
+    """
+
+    message: NotRequired[str]
+    """Status message."""
+    shell_id: NotRequired[str]
+    """ID of the shell that was killed."""
+
+
 # ---------------------------------------------------------------------------
 # TaskStop
 # ---------------------------------------------------------------------------
@@ -616,6 +668,42 @@ class ConfigOutput(TypedDict):
     """Error message if the operation failed."""
 
 
+# ---------------------------------------------------------------------------
+# Skill
+# ---------------------------------------------------------------------------
+
+
+class SkillOutput(TypedDict):
+    """``tool_use_result`` for the Skill tool.
+
+    Not part of the official SDK ToolOutputSchemas as of SDK v0.2.62.
+    Shape derived from empirical testing.
+    """
+
+    success: bool
+    """Whether the skill was invoked successfully."""
+    commandName: str
+    """The name of the skill that was invoked."""
+    allowedTools: list[str]
+    """Tools that the skill is allowed to use."""
+
+
+# ---------------------------------------------------------------------------
+# EnterPlanMode
+# ---------------------------------------------------------------------------
+
+
+class EnterPlanModeOutput(TypedDict):
+    """``tool_use_result`` for the EnterPlanMode tool.
+
+    Not part of the official SDK ToolOutputSchemas as of SDK v0.2.62.
+    Shape derived from empirical testing.
+    """
+
+    message: str
+    """A message indicating that plan mode was entered."""
+
+
 # ---------------------------------------------------------------------------
 # EnterWorktree
 # ---------------------------------------------------------------------------
@@ -639,6 +727,8 @@ class EnterWorktreeOutput(TypedDict):
 ToolUseResult = (
     AgentOutput
     | BashOutput
+    | BashOutputOutput
+    | KillShellOutput
     | TaskOutputResult
     | TaskStopOutput
     | ExitPlanModeOutput
@@ -659,6 +749,8 @@ ToolUseResult = (
     | UnsubscribePollingOutput
     | ConfigOutput
     | EnterWorktreeOutput
+    | SkillOutput
+    | EnterPlanModeOutput
 )
 
 #: Backwards-compatible aliases for names previously in ``tool_use_results.py``.
@@ -674,6 +766,8 @@ TodoWriteToolUseResult = TodoWriteOutput
 TOOL_USE_RESULT_TYPES: dict[str, type[Any]] = {
     "Task": AgentCompletedOutput,
     "Bash": BashOutput,
+    "BashOutput": BashOutputOutput,
+    "KillBash": KillShellOutput,
     "TaskOutput": TaskOutputResult,
     "TaskStop": TaskStopOutput,
     "ExitPlanMode": ExitPlanModeOutput,
@@ -695,4 +789,6 @@ TOOL_USE_RESULT_TYPES: dict[str, type[Any]] = {
     "UnsubscribePolling": UnsubscribePollingOutput,
     "Config": ConfigOutput,
     "EnterWorktree": EnterWorktreeOutput,
+    "Skill": SkillOutput,
+    "EnterPlanMode": EnterPlanModeOutput,
 }

{clawd_code_sdk-0.3.5 → clawd_code_sdk-0.3.7}/tests/e2e/test_agents_and_settings.py

@@ -188,7 +188,7 @@ You are a simple test agent. When asked a question, provide a brief, helpful ans
             f"Missing AssistantMessage - got only: {message_types}. "
             "This may indicate issue #406 (silent failure with filesystem agents)."
         )
-        assert "ResultMessage" in message_types, "Missing ResultMessage"
+        assert "ResultSuccessMessage" in message_types, "Missing ResultMessage"
 
         # Find the init message and check for the filesystem agent
         for msg in messages:
@@ -517,4 +517,4 @@ async def test_agent_definition_with_mcp_servers():
 
 
 if __name__ == "__main__":
-    pytest.main([__file__, "-vv"])
+    pytest.main([__file__, "-vv", "-m", "e2e"])

{clawd_code_sdk-0.3.5 → clawd_code_sdk-0.3.7}/tests/e2e/test_dynamic_control.py

@@ -2,10 +2,7 @@
 
 import pytest
 
-from clawd_code_sdk import (
-    ClaudeAgentOptions,
-    ClaudeSDKClient,
-)
+from clawd_code_sdk import ClaudeAgentOptions, ClaudeSDKClient
 
 
 @pytest.mark.e2e
@@ -13,27 +10,21 @@ from clawd_code_sdk import (
 async def test_set_permission_mode():
     """Test that permission mode can be changed dynamically during a session."""
 
-    options = ClaudeAgentOptions(
-        permission_mode="default",
-    )
+    options = ClaudeAgentOptions(permission_mode="default")
 
     async with ClaudeSDKClient(options=options) as client:
         # Change permission mode to acceptEdits
         await client.set_permission_mode("acceptEdits")
-
         # Make a query that would normally require permission
         await client.query("What is 2+2? Just respond with the number.")
-
         async for message in client.receive_response():
             print(f"Got message: {message}")
             pass  # Just consume messages
 
         # Change back to default
         await client.set_permission_mode("default")
-
         # Make another query
         await client.query("What is 3+3? Just respond with the number.")
-
         async for message in client.receive_response():
             print(f"Got message: {message}")
             pass  # Just consume messages
@@ -43,31 +34,22 @@ async def test_set_permission_mode():
 @pytest.mark.asyncio
 async def test_set_model():
     """Test that model can be changed dynamically during a session."""
-
-    options = ClaudeAgentOptions()
-
-    async with ClaudeSDKClient(options=options) as client:
+    async with ClaudeSDKClient() as client:
         # Start with default model
         await client.query("What is 1+1? Just the number.")
-
         async for message in client.receive_response():
             print(f"Default model response: {message}")
             pass
-
         # Switch to Haiku model
-        await client.set_model("claude-3-5-haiku-20241022")
-
+        await client.set_model("claude-haiku-4-5")
         await client.query("What is 2+2? Just the number.")
-
         async for message in client.receive_response():
             print(f"Haiku model response: {message}")
             pass
 
         # Switch back to default (None means default)
         await client.set_model(None)
-
         await client.query("What is 3+3? Just the number.")
-
         async for message in client.receive_response():
             print(f"Back to default model: {message}")
             pass
@@ -78,12 +60,9 @@ async def test_set_model():
 async def test_interrupt():
     """Test that interrupt can be sent during a session."""
 
-    options = ClaudeAgentOptions()
-
-    async with ClaudeSDKClient(options=options) as client:
+    async with ClaudeSDKClient() as client:
         # Start a query
         await client.query("Count from 1 to 100 slowly.")
-
         # Send interrupt (may or may not stop the response depending on timing)
         try:
             await client.interrupt()
@@ -98,4 +77,4 @@ async def test_interrupt():
 
 
 if __name__ == "__main__":
-    pytest.main([__file__, "-vv"])
+    pytest.main([__file__, "-vv", "-m", "e2e"])

{clawd_code_sdk-0.3.5 → clawd_code_sdk-0.3.7}/tests/e2e/test_hook_events.py

@@ -196,4 +196,4 @@ async def test_multiple_hooks_together():
 
 
 if __name__ == "__main__":
-    pytest.main([__file__, "-vv"])
+    pytest.main([__file__, "-vv", "-m", "e2e"])

{clawd_code_sdk-0.3.5 → clawd_code_sdk-0.3.7}/tests/e2e/test_hooks.py

@@ -158,4 +158,4 @@ async def test_hook_with_additional_context():
 
 
 if __name__ == "__main__":
-    pytest.main([__file__, "-vv"])
+    pytest.main([__file__, "-vv", "-m", "e2e"])