clawd-code-sdk 0.1.89__tar.gz → 0.2.0__tar.gz

{clawd_code_sdk-0.1.89 → clawd_code_sdk-0.2.0}/PKG-INFO

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

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

{clawd_code_sdk-0.1.89 → clawd_code_sdk-0.2.0}/src/clawd_code_sdk/__init__.py

@@ -22,6 +22,7 @@ from .anthropic_types import ToolResultContentBlock
 from .client import ClaudeSDKClient
 from .models import (
     AgentDefinition,
+    ContinueLatest,
     AssistantMessage,
     BaseHookInput,
     CanUseTool,
@@ -74,6 +75,9 @@ from .models import (
     UserPromptMessage,
     UserPromptMessageContent,
     UserPromptSubmitHookInput,
+    NewSession,
+    ResumeSession,
+    SessionConfig,
 )
 from .query import query
 from .mcp_utils import SdkMcpTool, tool, create_sdk_mcp_server
@@ -98,6 +102,11 @@ __all__ = [
     # Transport
     "Transport",
     "ClaudeSDKClient",
+    # Session config
+    "ContinueLatest",
+    "NewSession",
+    "ResumeSession",
+    "SessionConfig",
     # Types
     "PermissionMode",
     "McpServerConfig",

{clawd_code_sdk-0.1.89 → clawd_code_sdk-0.2.0}/src/clawd_code_sdk/_internal/transport/subprocess_cli.py

@@ -115,14 +115,40 @@ class SubprocessCLITransport(Transport):
         if self._options.permission_mode:
             cmd.extend(["--permission-mode", self._options.permission_mode])
 
-        if self._options.continue_conversation:
-            cmd.append("--continue")
-
-        if self._options.resume:
-            cmd.extend(["--resume", self._options.resume])
-
-        if self._options.session_id:
-            cmd.extend(["--session-id", self._options.session_id])
+        # Session configuration
+        from clawd_code_sdk.models.options import (
+            ContinueLatest,
+            NewSession,
+            ResumeSession,
+            resolve_session_config,
+        )
+
+        session = resolve_session_config(self._options.session)
+        match session:
+            case NewSession(session_id=sid, persist=persist):
+                if sid is not None:
+                    cmd.extend(["--session-id", sid])
+                if not persist:
+                    cmd.append("--no-persist-session")
+            case ResumeSession(
+                session_id=sid,
+                fork=fork,
+                at_message=at_msg,
+                persist=persist,
+            ):
+                cmd.extend(["--resume", sid])
+                if fork:
+                    cmd.append("--fork-session")
+                if at_msg is not None:
+                    cmd.extend(["--resume-session-at", at_msg])
+                if not persist:
+                    cmd.append("--no-persist-session")
+            case ContinueLatest(fork=fork, persist=persist):
+                cmd.append("--continue")
+                if fork:
+                    cmd.append("--fork-session")
+                if not persist:
+                    cmd.append("--no-persist-session")
 
         # Handle settings and sandbox: merge sandbox into settings if both are provided
         if settings_value := self._options.build_settings_value():
@@ -149,18 +175,9 @@ class SubprocessCLITransport(Transport):
         if self._options.agent:
             cmd.extend(["--agent", self._options.agent])
 
-        if self._options.fork_session:
-            cmd.append("--fork-session")
-
-        if self._options.persist_session is False:
-            cmd.append("--no-persist-session")
-
         if self._options.allow_dangerously_skip_permissions:
             cmd.append("--dangerously-skip-permissions")
 
-        if self._options.resume_session_at:
-            cmd.extend(["--resume-session-at", self._options.resume_session_at])
-
         if self._options.debug_file:
             cmd.extend(["--debug-file", self._options.debug_file])
 

{clawd_code_sdk-0.1.89 → clawd_code_sdk-0.2.0}/src/clawd_code_sdk/models/__init__.py

@@ -228,6 +228,13 @@ from .messages import (
     system_message_adapter,
 )
 from .options import ClaudeAgentOptions
+from .options import (
+    ContinueLatest,
+    NewSession,
+    ResumeSession,
+    SessionConfig,
+    resolve_session_config,
+)
 from .permissions import (
     CanUseTool,
     PermissionResult,
@@ -364,6 +371,11 @@ __all__ = [
     "system_message_adapter",
     # options
     "ClaudeAgentOptions",
+    "ContinueLatest",
+    "NewSession",
+    "ResumeSession",
+    "SessionConfig",
+    "resolve_session_config",
     # control
     "ControlErrorResponse",
     "ControlRequestUnion",

{clawd_code_sdk-0.1.89 → clawd_code_sdk-0.2.0}/src/clawd_code_sdk/models/options.py

@@ -1,4 +1,4 @@
-"""ClaudeAgentOptions - main options dataclass."""
+"""ClaudeAgentOptions and session configuration types."""
 
 from __future__ import annotations
 
@@ -6,7 +6,7 @@ from dataclasses import dataclass, field
 import json
 import logging
 from pathlib import Path
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, Literal
 
 
 if TYPE_CHECKING:
@@ -24,64 +24,161 @@ if TYPE_CHECKING:
 logger = logging.getLogger(__name__)
 
 
+# ============================================================================
+# Session configuration
+# ============================================================================
+
+
+@dataclass(kw_only=True)
+class NewSession:
+    """Start a fresh session.
+
+    Attributes:
+        session_id: Deterministic session ID, or None to auto-generate a UUID.
+        persist: Whether to persist the session to disk.
+    """
+
+    mode: Literal["new"] = "new"
+    session_id: str | None = None
+    persist: bool = True
+
+
+@dataclass(kw_only=True)
+class ResumeSession:
+    """Resume an existing session by ID.
+
+    Attributes:
+        session_id: The session ID to resume.
+        fork: If True, fork to a new session ID instead of continuing in-place.
+        at_message: Resume from a specific message UUID within the session.
+        persist: Whether to persist the session to disk.
+    """
+
+    mode: Literal["resume"] = "resume"
+    session_id: str
+    fork: bool = False
+    at_message: str | None = None
+    persist: bool = True
+
+
+@dataclass(kw_only=True)
+class ContinueLatest:
+    """Continue the most recent conversation.
+
+    Attributes:
+        fork: If True, fork to a new session ID instead of continuing in-place.
+        persist: Whether to persist the session to disk.
+    """
+
+    mode: Literal["continue"] = "continue"
+    fork: bool = False
+    persist: bool = True
+
+
+SessionConfig = NewSession | ResumeSession | ContinueLatest
+"""Union of all session configuration types.
+
+Can also be specified as a plain ``str``, which is a shortcut for
+``ResumeSession(session_id=str)``.
+"""
+
+
+def resolve_session_config(value: str | SessionConfig | None) -> SessionConfig:
+    """Normalize a session config value.
+
+    Args:
+        value: A SessionConfig instance, a session ID string (shortcut for
+            ResumeSession), or None (defaults to NewSession).
+
+    Returns:
+        A concrete SessionConfig instance.
+    """
+    match value:
+        case None:
+            return NewSession()
+        case str() as session_id:
+            return ResumeSession(session_id=session_id)
+        case NewSession() | ResumeSession() | ContinueLatest() as config:
+            return config
+
+
+# ============================================================================
+# Main options
+# ============================================================================
+
+
 @dataclass
 class ClaudeAgentOptions:
     """Query options for Claude SDK."""
 
+    # Tools
     tools: list[str] | ToolsPreset | None = None
     """Tools available to the agent."""
     allowed_tools: list[str] | None = None
     """Tools which execute without prompting for permission."""
-    system_prompt: str | SystemPromptPreset | None = None
-    """System prompt for the agent."""
+    disallowed_tools: list[str] | None = None
+    """Tools that are removed from agent context and cant be used."""
+    # MCP
     mcp_servers: dict[str, McpServerConfig] | str | Path = field(default_factory=dict)
     """MCP servers for the agent."""
+    chrome: bool = False
+    """Add the chrome-tools MCP server (-> Claude Code browser extension) to the agent."""
+    strict_mcp_config: bool = False
+    """Enforce strict validation of MCP server configurations."""
+    # Permissions
     permission_mode: PermissionMode | None = None
     """Permission mode."""
-    session_id: str | None = None
-    """Deterministic session ID for a new session."""
-    continue_conversation: bool = False
-    """Continue most recent conversation."""
-    resume: str | None = None
-    """Resume a conversation by session id."""
+    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."""
+    # Session
+    session: str | SessionConfig | None = None
+    """Session configuration.
+
+    Controls how the CLI session is started:
+    - ``None`` or ``NewSession()``: Start a fresh session.
+    - ``"session-id"`` or ``ResumeSession(session_id="...")``: Resume by ID.
+    - ``ContinueLatest()``: Continue the most recent conversation.
+    """
+    # Limits
     max_turns: int | None = None
     """Maximum allowed amount of agentic turns."""
     max_budget_usd: float | None = None
     """Maximum amount of USD budget which may be consumed."""
-    disallowed_tools: list[str] | None = None
-    """Tools that are removed from agent context and cant be used."""
+    # Model
     model: ModelName | str | None = None
     """Session model."""
     fallback_model: ModelName | str | None = None
     """Fallback model in case default one is overloaded."""
-    permission_prompt_tool_name: str | None = None
-    """MCP tool to handle permission prompts."""
-    cwd: str | Path | None = None
-    """The working directory for the agent."""
+    # Thinking
+    thinking: ThinkingConfig | None = None
+    """Controls thinking behavior."""
+    effort: ReasoningEffort | None = None
+    """Effort level for thinking depth."""
+    # CLI SubProcess
     cli_path: str | Path | None = None
     """CLI path override (auto-detects by default)."""
-    settings: str | None = None
-    """Path to a settings JSON file or a JSON string."""
-    add_dirs: list[str | Path] = field(default_factory=list)
-    """Add additional working directories."""
-    env: dict[str, str] = field(default_factory=dict)
-    """Environment variables for the CLI subprocess."""
     extra_args: dict[str, str | None] = field(default_factory=dict)
     """Arbitrary extra CLI flags."""
     max_buffer_size: int | None = None
     """Max bytes when buffering CLI stdout."""
     stderr: Callable[[str], None] | None = None
     """Callback for stderr output from CLI."""
-    can_use_tool: CanUseTool | None = None
-    """Tool permission callback."""
-    hooks: dict[HookEvent, list[HookMatcher]] | None = None
-    """Hook configurations."""
+    env: dict[str, str] = field(default_factory=dict)
+    """Environment variables for the CLI subprocess."""
     user: str | None = None
     """User for the AnyIO process."""
-    fork_session: bool = False
-    """Make resumed sessions forked to a new session ID instead of continuing."""
-    agents: dict[str, AgentDefinition] | None = None
-    """SubAgent definitions."""
+    # CWD
+    add_dirs: list[str | Path] = field(default_factory=list)
+    """Add additional working directories."""
+    cwd: str | Path | None = None
+    """The working directory for the agent."""
+    # Settings
+    settings: str | None = None
+    """Path to a settings JSON file or a JSON string."""
     setting_sources: list[SettingSource] | None = None
     """List of sources to load settings from."""
     sandbox: SandboxSettings | None = None
@@ -90,17 +187,23 @@ class ClaudeAgentOptions:
     Filesystem and network restrictions are derived from permission rules (Read/Edit/WebFetch),
     not from these sandbox settings.
     """
+    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 for the agent."""
+    hooks: dict[HookEvent, list[HookMatcher]] | None = None
+    """Hook configurations."""
+    agents: dict[str, AgentDefinition] | None = None
+    """SubAgent definitions."""
     plugins: list[SdkPluginConfig] = field(default_factory=list)
     """"Plugin configurations to load."""
-    thinking: ThinkingConfig | None = None
-    """Controls thinking behavior."""
-    effort: ReasoningEffort | None = None
-    """Effort level for thinking depth."""
     output_format: dict[str, Any] | None = None
     """Output format for structured outputs (matches Messages API structure)
 
     Example: {"type": "json_schema", "schema": {"type": "object", "properties": {...}}}
     """
+    # Other
     enable_file_checkpointing: bool = False
     """Enable file checkpointing to track file changes during the session.
 
@@ -109,24 +212,12 @@ class ClaudeAgentOptions:
     """
     agent: str | None = None
     """Agent name for the main thread. The agent must be defined in `agents` or settings."""
-    persist_session: bool | None = None
-    """Whether to persist the session to disk."""
-    allow_dangerously_skip_permissions: bool = False
-    """Must be True when using permission_mode='bypassPermissions'."""
-    resume_session_at: str | None = None
-    """Resume from a specific message UUID (use with `resume`)."""
-    debug_file: str | None = None
-    """Write debug logs to a specific file path. Implicitly enables debug mode."""
-    strict_mcp_config: bool = False
-    """Enforce strict validation of MCP server configurations."""
     context_1m: bool = False
     """Enable 1M token context window (Sonnet 4/4.5 only)."""
     prompt_suggestions: bool | None = None
     """Whether to  create prompt suggestions."""
     worktree: bool | str = False
     """Create a new git worktree for the session (with optional name)."""
-    chrome: bool = False
-    """Add the chrome-tools MCP server (-> Claude Code browser extension) to the agent."""
 
     def build_settings_value(self) -> str | None:
         """Build settings value, merging sandbox settings if provided.

{clawd_code_sdk-0.1.89 → clawd_code_sdk-0.2.0}/src/clawd_code_sdk/session.py

@@ -311,20 +311,21 @@ class SessionManager:
     ) -> Session:
         """Resume a previously persisted session by ID.
 
-        Sets ``continue_conversation=True`` and ``session_id`` on the options,
+        Sets ``session`` to a :class:`ResumeSession` config on the options,
         then connects.
 
         Args:
             session_id: The session ID to resume.
-            options: Session-specific options (``session_id`` and
-                ``continue_conversation`` are set automatically).
+            options: Session-specific options (``session`` is set automatically).
             transport: Optional custom transport.
 
         Raises:
             ValueError: If session_id already exists in this manager.
         """
+        from clawd_code_sdk.models.options import ResumeSession
+
         base = options or Opts()
-        merged = replace(base, session_id=session_id, continue_conversation=True)
+        merged = replace(base, session=ResumeSession(session_id=session_id))
         return await self.create_session(
             session_id=session_id,
             options=merged,

{clawd_code_sdk-0.1.89 → clawd_code_sdk-0.2.0}/tests/test_integration.py

@@ -14,6 +14,7 @@ from clawd_code_sdk import (
     AssistantMessage,
     ClaudeAgentOptions,
     CLINotFoundError,
+    ContinueLatest,
     ResultMessage,
     query,
 )
@@ -226,7 +227,7 @@ class TestIntegration:
             messages = []
             async for msg in query(
                 prompt="Continue",
-                options=ClaudeAgentOptions(continue_conversation=True),
+                options=ClaudeAgentOptions(session=ContinueLatest()),
                 transport=mock_transport,
             ):
                 messages.append(msg)

{clawd_code_sdk-0.1.89 → clawd_code_sdk-0.2.0}/tests/test_session.py

@@ -563,7 +563,8 @@ class TestSessionManager:
         anyio.run(_test)
 
     def test_resume_session(self):
-        """resume_session() sets continue_conversation and session_id."""
+        """resume_session() sets session to ResumeSession."""
+        from clawd_code_sdk.models.options import ResumeSession
 
         async def _test():
             transport = _create_mock_transport_with_messages([])
@@ -571,14 +572,15 @@ class TestSessionManager:
             async with SessionManager() as mgr:
                 session = await mgr.resume_session("prev-session-id", transport=transport)
                 assert session.session_id == "prev-session-id"
-                assert session.client.options.session_id == "prev-session-id"
-                assert session.client.options.continue_conversation is True
+                assert isinstance(session.client.options.session, ResumeSession)
+                assert session.client.options.session.session_id == "prev-session-id"
                 assert session.state == "idle"
 
         anyio.run(_test)
 
     def test_resume_session_with_options(self):
         """resume_session() merges caller options with resume fields."""
+        from clawd_code_sdk.models.options import ResumeSession
 
         async def _test():
             transport = _create_mock_transport_with_messages([])
@@ -587,7 +589,7 @@ class TestSessionManager:
             async with SessionManager() as mgr:
                 session = await mgr.resume_session("prev-id", options=opts, transport=transport)
                 assert session.client.options.model == "claude-sonnet-4-5-20250514"
-                assert session.client.options.session_id == "prev-id"
-                assert session.client.options.continue_conversation is True
+                assert isinstance(session.client.options.session, ResumeSession)
+                assert session.client.options.session.session_id == "prev-id"
 
         anyio.run(_test)

{clawd_code_sdk-0.1.89 → clawd_code_sdk-0.2.0}/tests/test_transport.py

@@ -181,23 +181,77 @@ class TestSubprocessCLITransport:
         assert dir1 in dirs_in_cmd
         assert str(dir2) in dirs_in_cmd
 
-    def test_session_continuation(self):
-        """Test session continuation options."""
-        opts = make_options(continue_conversation=True, resume="session-123")
+    def test_session_resume(self):
+        """Test resume session options."""
+        from clawd_code_sdk.models.options import ResumeSession
+
+        opts = make_options(session=ResumeSession(session_id="session-123"))
+        transport = SubprocessCLITransport(prompt="Continue from before", options=opts)
+        cmd = transport._build_command()
+        assert "--resume" in cmd
+        assert "session-123" in cmd
+
+    def test_session_resume_shortcut(self):
+        """Test resume session with string shortcut."""
+        opts = make_options(session="session-123")
         transport = SubprocessCLITransport(prompt="Continue from before", options=opts)
         cmd = transport._build_command()
-        assert "--continue" in cmd
         assert "--resume" in cmd
         assert "session-123" in cmd
 
-    def test_build_command_with_session_id(self):
-        """Test building CLI command with session_id option."""
-        opts = make_options(session_id="my-session-uuid")
+    def test_session_continue_latest(self):
+        """Test continue latest session option."""
+        from clawd_code_sdk.models.options import ContinueLatest
+
+        opts = make_options(session=ContinueLatest())
+        transport = SubprocessCLITransport(prompt="Continue", options=opts)
+        cmd = transport._build_command()
+        assert "--continue" in cmd
+
+    def test_session_resume_with_fork(self):
+        """Test resume session with fork."""
+        from clawd_code_sdk.models.options import ResumeSession
+
+        opts = make_options(session=ResumeSession(session_id="prev-id", fork=True))
+        transport = SubprocessCLITransport(prompt="test", options=opts)
+        cmd = transport._build_command()
+        assert "--resume" in cmd
+        assert "prev-id" in cmd
+        assert "--fork-session" in cmd
+
+    def test_session_resume_at_message(self):
+        """Test resume session at a specific message."""
+        from clawd_code_sdk.models.options import ResumeSession
+
+        opts = make_options(
+            session=ResumeSession(session_id="prev-id", at_message="msg-uuid"),
+        )
+        transport = SubprocessCLITransport(prompt="test", options=opts)
+        cmd = transport._build_command()
+        assert "--resume" in cmd
+        assert "prev-id" in cmd
+        assert "--resume-session-at" in cmd
+        assert "msg-uuid" in cmd
+
+    def test_build_command_with_new_session_id(self):
+        """Test building CLI command with explicit new session ID."""
+        from clawd_code_sdk.models.options import NewSession
+
+        opts = make_options(session=NewSession(session_id="my-session-uuid"))
         transport = SubprocessCLITransport(prompt="test", options=opts)
         cmd = transport._build_command()
         assert "--session-id" in cmd
         assert "my-session-uuid" in cmd
 
+    def test_session_no_persist(self):
+        """Test session with persist=False."""
+        from clawd_code_sdk.models.options import NewSession
+
+        opts = make_options(session=NewSession(persist=False))
+        transport = SubprocessCLITransport(prompt="test", options=opts)
+        cmd = transport._build_command()
+        assert "--no-persist-session" in cmd
+
     def test_connect_close(self):
         """Test connect and close lifecycle."""