clawd-code-sdk 0.3.8__tar.gz → 0.4.0__tar.gz

{clawd_code_sdk-0.3.8 → clawd_code_sdk-0.4.0}/.gitignore

@@ -27,7 +27,7 @@ ENV/
 env/
 .venv
 uv.lock
-
+.env
 # IDEs
 .vscode/
 .idea/

{clawd_code_sdk-0.3.8 → clawd_code_sdk-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: clawd-code-sdk
-Version: 0.3.8
+Version: 0.4.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
@@ -21,6 +21,7 @@ Requires-Dist: anthropic>=0.77.0
 Requires-Dist: anyenv>=2.0.15
 Requires-Dist: anyio>=4.0.0
 Requires-Dist: mcp>=0.1.0
+Requires-Dist: python-dotenv>=1.2.1
 Provides-Extra: dev
 Requires-Dist: anyio[trio]>=4.0.0; extra == 'dev'
 Requires-Dist: mypy>=1.0.0; extra == 'dev'

{clawd_code_sdk-0.3.8 → clawd_code_sdk-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "clawd-code-sdk"
-version = "0.3.8"
+version = "0.4.0"
 description = "Python SDK for Claude Code"
 readme = "README.md"
 requires-python = ">=3.13"
@@ -23,6 +23,7 @@ dependencies = [
   "anyenv>=2.0.15",
   "anyio>=4.0.0",
   "mcp>=0.1.0",
+  "python-dotenv>=1.2.1",
 ]
 
 [project.urls]

{clawd_code_sdk-0.3.8 → clawd_code_sdk-0.4.0}/src/clawd_code_sdk/__init__.py

@@ -2,6 +2,10 @@
 
 from __future__ import annotations
 
+from dotenv import load_dotenv
+
+load_dotenv()
+
 
 from ._errors import (
     APIError,
@@ -22,6 +26,7 @@ from .anthropic_types import ToolResultContentBlock
 from .client import ClaudeSDKClient
 from .list_sessions import list_sessions
 from .models import (
+    AccumulatedUsage,
     AgentDefinition,
     AgentHookHandler,
     AgentHooksConfig,
@@ -85,9 +90,11 @@ from .models import (
     ToolResultBlock,
     ToolUseBlock,
     UserMessage,
-    UserPromptMessage,
-    UserPromptMessageContent,
     UserPromptSubmitHookInput,
+    UserTextPrompt,
+    UserImagePrompt,
+    UserPrompt,
+    ImageMediaType,
     FromPR,
     NewSession,
     ResumeSession,
@@ -113,6 +120,7 @@ __cli_version__ = "2.1.11"
 __all__ = [
     # API Errors
     "APIError",
+    "AccumulatedUsage",
     # Agent support
     "AgentDefinition",
     # Hook support
@@ -146,6 +154,7 @@ __all__ = [
     "HookJSONOutput",
     "HookMatcher",
     "HookMatcherConfig",
+    "ImageMediaType",
     "InitSystemMessage",
     "InvalidRequestError",
     "ListSessionsOptions",
@@ -212,10 +221,11 @@ __all__ = [
     "ToolUseBlock",
     # Transport
     "Transport",
+    "UserImagePrompt",
     "UserMessage",
-    "UserPromptMessage",
-    "UserPromptMessageContent",
+    "UserPrompt",
     "UserPromptSubmitHookInput",
+    "UserTextPrompt",
     "__version__",
     # MCP Server Support
     "create_sdk_mcp_server",

{clawd_code_sdk-0.3.8 → clawd_code_sdk-0.4.0}/src/clawd_code_sdk/_internal/query.py

@@ -33,7 +33,7 @@ from clawd_code_sdk.models.server_info import ClaudeCodeServerInfo
 
 
 if TYPE_CHECKING:
-    from collections.abc import AsyncGenerator, AsyncIterable, AsyncIterator, Iterator
+    from collections.abc import AsyncGenerator, AsyncIterator, Iterator
 
     from anyio.abc import CancelScope, TaskGroup
     from mcp.server import Server as McpServer
@@ -45,7 +45,6 @@ if TYPE_CHECKING:
     from clawd_code_sdk.models.hooks import HookCallback, HookEvent, HookMatcher
     from clawd_code_sdk.models.input_types import AskUserQuestionInput
     from clawd_code_sdk.models.mcp import JSONRPCMessage, JSONRPCResponse, RequestId
-    from clawd_code_sdk.models.messages import UserPromptMessage
     from clawd_code_sdk.models.permissions import CanUseTool, OnUserQuestion, PermissionResult
 
 logger = logging.getLogger(__name__)
@@ -473,39 +472,6 @@ class Query:
         req = {"subtype": "rewind_files", "user_message_id": user_message_id}
         return await self._send_control_request(req)
 
-    async def stream_input(self, stream: AsyncIterable[UserPromptMessage]) -> None:
-        """Stream input messages to transport.
-
-        If SDK MCP servers or hooks are present, waits for the first result
-        before closing stdin to allow bidirectional control protocol communication.
-        """
-        try:
-            async for message in stream:
-                if self._closed:
-                    break
-                await self.transport.write(anyenv.dump_json(message) + "\n")
-
-            # If we have SDK MCP servers or hooks that need bidirectional communication,
-            # wait for first result before closing the channel
-            if self.sdk_mcp_servers or self.hooks:
-                logger.debug(
-                    "Waiting for first result before closing stdin "
-                    "(sdk_mcp_servers=%s, has_hooks=%s)",
-                    len(self.sdk_mcp_servers),
-                    bool(self.hooks),
-                )
-                try:
-                    with anyio.move_on_after(self._stream_close_timeout):
-                        await self._first_result_event.wait()
-                        logger.debug("Received first result, closing input stream")
-                except Exception:
-                    logger.debug("Timed out waiting for first result, closing input stream")
-
-            # After all messages sent (and result received if needed), end input
-            await self.transport.end_input()
-        except Exception as e:
-            logger.debug("Error streaming input: %s", e)
-
     async def receive_messages(self) -> AsyncGenerator[dict[str, Any]]:
         """Receive SDK messages (not control messages)."""
         async for message in self._message_receive:

{clawd_code_sdk-0.3.8 → clawd_code_sdk-0.4.0}/src/clawd_code_sdk/_internal/transport/subprocess_cli.py

@@ -26,15 +26,19 @@ from clawd_code_sdk._errors import (
 )
 from clawd_code_sdk._internal.transport import Transport
 from clawd_code_sdk._version import __version__
+from clawd_code_sdk.models.base import (
+    ThinkingConfigAdaptive,
+    ThinkingConfigDisabled,
+    ThinkingConfigEnabled,
+)
 
 
 if TYPE_CHECKING:
-    from collections.abc import AsyncIterable, AsyncIterator
+    from collections.abc import AsyncIterator
 
     from anyio.abc import Process
 
     from clawd_code_sdk.models import ClaudeAgentOptions
-    from clawd_code_sdk.models.messages import UserPromptMessage
 
 logger = logging.getLogger(__name__)
 
@@ -56,10 +60,8 @@ class SubprocessCLITransport(Transport):
 
     def __init__(
         self,
-        prompt: str | AsyncIterable[UserPromptMessage],
         options: ClaudeAgentOptions,
     ):
-        self._prompt = prompt
         self._options = options
         self._cli_path = str(options.cli_path) if options.cli_path is not None else _find_cli()
         self._cwd = str(options.cwd) if options.cwd else None
@@ -207,11 +209,11 @@ class SubprocessCLITransport(Transport):
 
         # Resolve thinking config → --max-thinking-tokens
         match self._options.thinking:
-            case {"type": "adaptive"}:
+            case ThinkingConfigAdaptive():
                 cmd.extend(["--max-thinking-tokens", "32000"])
-            case {"type": "enabled", "budget_tokens": budget}:
+            case ThinkingConfigEnabled(budget_tokens=budget):
                 cmd.extend(["--max-thinking-tokens", str(budget)])
-            case {"type": "disabled"}:
+            case ThinkingConfigDisabled():
                 cmd.extend(["--max-thinking-tokens", "0"])
 
         if self._options.effort is not None:

{clawd_code_sdk-0.3.8 → clawd_code_sdk-0.4.0}/src/clawd_code_sdk/client.py

@@ -2,7 +2,6 @@
 
 from __future__ import annotations
 
-from collections.abc import AsyncIterable
 from dataclasses import replace
 import os
 from typing import TYPE_CHECKING, Any, Self
@@ -12,12 +11,17 @@ from pydantic import TypeAdapter
 
 from clawd_code_sdk._errors import CLIConnectionError
 from clawd_code_sdk.models import (
+    AccumulatedUsage,
     ClaudeAgentOptions,
     ResultMessage,
-    UserPromptMessage,
 )
 from clawd_code_sdk.models.mcp import McpStatusResponse
-from clawd_code_sdk.models.messages import AssistantMessage
+from clawd_code_sdk.models.messages import (
+    AssistantMessage,
+    ResultErrorMessage,
+    ResultSuccessMessage,
+    UserTextPrompt,
+)
 
 
 if TYPE_CHECKING:
@@ -27,6 +31,9 @@ if TYPE_CHECKING:
     from clawd_code_sdk._internal.query import Query
     from clawd_code_sdk.models import Message, PermissionMode
     from clawd_code_sdk.models.mcp import McpServerConfig
+    from clawd_code_sdk.models.messages import (
+        UserImagePrompt,
+    )
     from clawd_code_sdk.models.server_info import ClaudeCodeServerInfo
 
 
@@ -59,6 +66,10 @@ class ClaudeSDKClient:
         self._custom_transport = transport
         self._transport: Transport | None = None
         self._query: Query | None = None
+        self.session_usage: AccumulatedUsage = AccumulatedUsage()
+        """Cumulative token usage across all queries in this session."""
+        self.query_usage: AccumulatedUsage = AccumulatedUsage()
+        """Token usage for the current/last query only (reset on each query() call)."""
         os.environ["CLAUDE_CODE_ENTRYPOINT"] = "sdk-py-client"
 
     def _ensure_connected(self) -> Query:
@@ -67,38 +78,22 @@ class ClaudeSDKClient:
             raise CLIConnectionError("Not connected. Call connect() first.")
         return self._query
 
-    async def connect(self, prompt: str | AsyncIterable[UserPromptMessage] | None = None) -> None:
-        """Connect to Claude with a prompt or message stream."""
+    async def connect(self) -> None:
+        """Connect to Claude Code CLI and initialize the session."""
         from clawd_code_sdk._internal.query import Query
         from clawd_code_sdk._internal.transport.subprocess_cli import SubprocessCLITransport
 
-        # Auto-connect with empty async iterable if no prompt is provided
-        async def _empty_stream() -> AsyncIterator[UserPromptMessage]:
-            # Never yields, but indicates that this function is an iterator and
-            # keeps the connection open.
-            # This yield is never reached but makes this an async generator
-            return
-            yield {}  # type: ignore[unreachable]
-
-        actual_prompt = _empty_stream() if prompt is None else prompt
         # Validate and configure permission settings (matching TypeScript SDK logic)
         self.options.validate()
 
         if self.options.can_use_tool:
-            # canUseTool callback requires streaming mode (AsyncIterable prompt)
-            if isinstance(prompt, str):
-                raise ValueError(
-                    "can_use_tool callback requires streaming mode. "
-                    "Please provide prompt as an AsyncIterable instead of a string."
-                )
-
             # Automatically set permission_prompt_tool_name to "stdio" for control protocol
             options = replace(self.options, permission_prompt_tool_name="stdio")
         else:
             options = self.options
 
         # Use provided custom transport or create subprocess transport
-        tp = self._custom_transport or SubprocessCLITransport(prompt=actual_prompt, options=options)
+        tp = self._custom_transport or SubprocessCLITransport(options=options)
         self._transport = tp
         await self._transport.connect()
         # Extract SDK MCP servers from options
@@ -151,12 +146,6 @@ class ClaudeSDKClient:
         # Start reading messages and initialize
         await self._query.start()
         await self._query.initialize()
-        # Send the initial prompt
-        match prompt:
-            case str() as text:
-                await self.query(text)
-            case AsyncIterable() if self._query._tg:
-                self._query._tg.start_soon(self._query.stream_input, prompt)
 
     async def receive_messages(self) -> AsyncIterator[Message]:
         """Receive all messages from Claude."""
@@ -165,34 +154,50 @@ class ClaudeSDKClient:
         query = self._ensure_connected()
         async for data in query.receive_messages():
             message = parse_message(data)
-            if isinstance(message, AssistantMessage):
-                message.raise_if_api_error()
+            match message:
+                case AssistantMessage():
+                    message.raise_if_api_error()
+                case ResultSuccessMessage() | ResultErrorMessage():
+                    self.query_usage.accumulate(message.usage)
+                    self.session_usage.accumulate(message.usage)
             yield message
 
     async def query(
         self,
-        prompt: str | AsyncIterable[UserPromptMessage],
+        *prompts: str | UserTextPrompt | UserImagePrompt,
         session_id: str = "default",
+        parent_tool_use_id: str | None = None,
     ) -> None:
-        """Send a new request in streaming mode."""
+        """Send a new user message with one or more content blocks.
+
+        Args:
+            *prompts: One or more content blocks. Strings are converted to
+                UserTextPrompt automatically. Pass multiple to combine, e.g.
+                ``query(image_prompt, "What's in this image?")``.
+            session_id: Session identifier for the message.
+            parent_tool_use_id: If responding to a tool use, the tool_use block ID.
+        """
+        self.query_usage.reset()
         self._ensure_connected()
         if not self._transport:
             raise CLIConnectionError("Not connected. Call connect() first.")
-        # Handle string prompts
-        if isinstance(prompt, str):
-            message = UserPromptMessage(
-                type="user",
-                message={"role": "user", "content": prompt},
-                parent_tool_use_id=None,
-                session_id=session_id,
-            )
-            await self._transport.write(anyenv.dump_json(message) + "\n")
+        if not prompts:
+            return
+        # Collect content blocks
+        blocks = [UserTextPrompt(text=p) if isinstance(p, str) else p for p in prompts]
+        # Single text block → plain string, otherwise list of content block dicts
+        message_content: str | list[dict[str, Any]]
+        if len(blocks) == 1 and isinstance(blocks[0], UserTextPrompt):
+            message_content = blocks[0].text
         else:
-            # Handle AsyncIterable prompts - stream them
-            async for msg in prompt:
-                # Ensure session_id is set on each message
-                msg.setdefault("session_id", session_id)
-                await self._transport.write(anyenv.dump_json(msg) + "\n")
+            message_content = [b.to_content_block() for b in blocks]
+        wire_message = {
+            "type": "user",
+            "message": {"role": "user", "content": message_content},
+            "parent_tool_use_id": parent_tool_use_id,
+            "session_id": session_id,
+        }
+        await self._transport.write(anyenv.dump_json(wire_message) + "\n")
 
     async def interrupt(self) -> None:
         """Send interrupt signal (only works with streaming mode)."""
@@ -390,7 +395,7 @@ if __name__ == "__main__":
     os.environ["ANTHROPIC_API_KEY"] = ""
 
     async def main() -> None:
-        opts = ClaudeAgentOptions(thinking=ThinkingConfigAdaptive(type="adaptive"))
+        opts = ClaudeAgentOptions(thinking=ThinkingConfigAdaptive())
         client = ClaudeSDKClient(opts)
         await client.connect()
         await client.query("ultrathink")

{clawd_code_sdk-0.3.8 → clawd_code_sdk-0.4.0}/src/clawd_code_sdk/models/__init__.py

@@ -210,6 +210,7 @@ from .content_blocks import (
 )
 
 from .messages import (
+    AccumulatedUsage,
     AssistantMessage,
     AssistantMessageError,
     BaseSystemMessage,
@@ -240,8 +241,10 @@ from .messages import (
     TriggerMetadata,
     Usage,
     UserMessage,
-    UserPromptMessage,
-    UserPromptMessageContent,
+    UserImagePrompt,
+    UserTextPrompt,
+    UserPrompt,
+    ImageMediaType,
     system_message_adapter,
 )
 from .options import ClaudeAgentOptions
@@ -272,14 +275,12 @@ __all__ = [
     # mcp
     "JSONRPC_VERSION",
     "TOOL_INPUT_TYPES",
-    # output_types (actual tool_use_result wire format)
     "TOOL_USE_RESULT_TYPES",
+    "AccumulatedUsage",
     "AgentAsyncLaunchedOutput",
     "AgentCacheCreation",
     "AgentCompletedOutput",
-    # agents
     "AgentDefinition",
-    # hooks
     "AgentHookHandler",
     "AgentHooksConfig",
     "AgentInput",
@@ -288,14 +289,12 @@ __all__ = [
     "AgentOutputUsage",
     "AgentServerToolUse",
     "AgentSubAgentEnteredOutput",
-    # base
     "ApiKeySource",
     "AskUserQuestion",
     "AskUserQuestionInput",
     "AskUserQuestionItem",
     "AskUserQuestionOption",
     "AskUserQuestionOutput",
-    # messages
     "AssistantMessage",
     "AssistantMessageError",
     "AsyncHookJSONOutput",
@@ -308,18 +307,14 @@ __all__ = [
     "BashOutput",
     "BashOutputInput",
     "BashOutputOutput",
-    # backwards-compat aliases (old tool_use_results.py names)
     "BashToolUseResult",
-    # permissions
     "CanUseTool",
-    # options
     "ClaudeAgentOptions",
     "CommandHookHandler",
     "CompactBoundarySystemMessage",
     "ConfigOutput",
     "ContentBlock",
     "ContinueLatest",
-    # control
     "ControlErrorResponse",
     "ControlRequestUnion",
     "ControlResponse",
@@ -352,6 +347,7 @@ __all__ = [
     "HookResponseSystemMessage",
     "HookSpecificOutput",
     "HookStartedSystemMessage",
+    "ImageMediaType",
     "InitSystemMessage",
     "JSONRPCError",
     "JSONRPCErrorResponse",
@@ -438,7 +434,6 @@ __all__ = [
     "SDKHookCallbackRequest",
     "SDKPermissionDenial",
     "SDKSessionInfo",
-    # sandbox
     "SandboxIgnoreViolations",
     "SandboxNetworkConfig",
     "SandboxSettings",
@@ -496,11 +491,12 @@ __all__ = [
     "UnsubscribeMcpResourceOutput",
     "UnsubscribePollingOutput",
     "Usage",
+    "UserImagePrompt",
     "UserMessage",
-    "UserPromptMessage",
-    "UserPromptMessageContent",
+    "UserPrompt",
     "UserPromptSubmitHookInput",
     "UserPromptSubmitHookSpecificOutput",
+    "UserTextPrompt",
     "WebFetchInput",
     "WebFetchOutput",
     "WebSearchHit",

{clawd_code_sdk-0.3.8 → clawd_code_sdk-0.4.0}/src/clawd_code_sdk/models/base.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 import sys
-from typing import Literal, TypedDict
+from typing import Literal
 
 from pydantic import BaseModel, ConfigDict
 from pydantic.alias_generators import to_camel
@@ -70,23 +70,23 @@ class ClaudeCodeBaseModel(BaseModel):
 
 
 # Thinking configuration types
-class ThinkingConfigAdaptive(TypedDict):
+class ThinkingConfigAdaptive(ClaudeCodeBaseModel):
     """Adaptive thinking configuration - model decides thinking budget."""
 
-    type: Literal["adaptive"]
+    type: Literal["adaptive"] = "adaptive"
 
 
-class ThinkingConfigEnabled(TypedDict):
+class ThinkingConfigEnabled(ClaudeCodeBaseModel):
     """Enabled thinking configuration with explicit token budget."""
 
-    type: Literal["enabled"]
+    type: Literal["enabled"] = "enabled"
     budget_tokens: int
 
 
-class ThinkingConfigDisabled(TypedDict):
+class ThinkingConfigDisabled(ClaudeCodeBaseModel):
     """Disabled thinking configuration."""
 
-    type: Literal["disabled"]
+    type: Literal["disabled"] = "disabled"
 
 
 ThinkingConfig = ThinkingConfigAdaptive | ThinkingConfigEnabled | ThinkingConfigDisabled

{clawd_code_sdk-0.3.8 → clawd_code_sdk-0.4.0}/src/clawd_code_sdk/models/messages.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 from collections.abc import Sequence  # noqa: TC003
 from dataclasses import dataclass
 import re
-from typing import TYPE_CHECKING, Annotated, Any, Literal, NotRequired, TypedDict
+from typing import TYPE_CHECKING, Annotated, Any, Literal, TypedDict
 
 # from anthropic.types import MessageParam
 from anthropic.types.model import Model  # noqa: TC002
@@ -58,29 +58,43 @@ ErrorSubType = Literal[
 Outcome = Literal["success", "error", "cancelled"]
 
 
-class UserPromptMessageContent(TypedDict):
-    """Inner message content for a user prompt."""
+ImageMediaType = Literal["image/png", "image/jpeg", "image/gif", "image/webp"]
 
-    role: Literal["user"]
-    """Message role, always 'user'."""
-    content: str
-    """The text content of the message."""
 
+@dataclass
+class UserTextPrompt:
+    """A text-only user prompt."""
 
-class UserPromptMessage(TypedDict):
-    """A user prompt message sent over the wire to the Claude Code CLI.
+    text: str
 
-    Used as the element type for streaming prompt iterables.
-    """
+    def to_content_block(self) -> dict[str, Any]:
+        """Return the Anthropic API content block dict."""
+        return {"type": "text", "text": self.text}
+
+
+@dataclass
+class UserImagePrompt:
+    """A user prompt containing a single base64-encoded image."""
+
+    image_data: str
+    """Base64-encoded image data."""
+    media_type: ImageMediaType
+    """MIME type of the image."""
 
-    type: Literal["user"]
-    """Message type, always 'user'."""
-    message: UserPromptMessageContent
-    """The message content."""
-    parent_tool_use_id: NotRequired[str | None]
-    """Optional parent tool use ID for tool result responses."""
-    session_id: NotRequired[str]
-    """Session identifier. Auto-injected if not provided."""
+    def to_content_block(self) -> dict[str, Any]:
+        """Return the Anthropic API content block dict."""
+        return {
+            "type": "image",
+            "source": {
+                "type": "base64",
+                "media_type": self.media_type,
+                "data": self.image_data,
+            },
+        }
+
+
+UserPrompt = UserTextPrompt | UserImagePrompt
+"""Union type for all user prompt dataclasses."""
 
 
 @dataclass(kw_only=True)
@@ -356,7 +370,7 @@ class HookResponseSystemMessage(BaseSystemMessage):
 
 
 class ModelUsage(TypedDict):
-    """Token usage from Claude API response."""
+    """Cumulative token usage per model, accumulated across the entire session."""
 
     inputTokens: int
     outputTokens: int
@@ -377,7 +391,7 @@ class SDKPermissionDenial(TypedDict):
 
 
 class Usage(TypedDict):
-    """Token usage from Claude API response."""
+    """Token usage from the last API call only (per-turn, not cumulative)."""
 
     input_tokens: int
     output_tokens: int
@@ -385,19 +399,62 @@ class Usage(TypedDict):
     cache_read_input_tokens: int
 
 
+@dataclass
+class AccumulatedUsage:
+    """Accumulated token usage, built by summing per-turn Usage values."""
+
+    input_tokens: int = 0
+    output_tokens: int = 0
+    cache_creation_input_tokens: int = 0
+    cache_read_input_tokens: int = 0
+
+    @property
+    def total_tokens(self) -> int:
+        """Sum of all token fields."""
+        return (
+            self.input_tokens
+            + self.output_tokens
+            + self.cache_creation_input_tokens
+            + self.cache_read_input_tokens
+        )
+
+    def accumulate(self, usage: Usage) -> None:
+        """Add a per-turn Usage to this accumulator."""
+        self.input_tokens += usage.get("input_tokens", 0)
+        self.output_tokens += usage.get("output_tokens", 0)
+        self.cache_creation_input_tokens += usage.get("cache_creation_input_tokens", 0)
+        self.cache_read_input_tokens += usage.get("cache_read_input_tokens", 0)
+
+    def reset(self) -> None:
+        """Reset all counters to zero."""
+        self.input_tokens = 0
+        self.output_tokens = 0
+        self.cache_creation_input_tokens = 0
+        self.cache_read_input_tokens = 0
+
+
 @dataclass(kw_only=True)
 class BaseResultMessage(BaseMessage):
-    """Base result message with cost and usage information."""
+    """Base result message with cost and usage information.
+
+    Note: Fields use inconsistent scoping. See per-field docs for details.
+    """
 
     type: Literal["result"] = "result"
     duration_ms: int
+    """Wall-clock time for this query only (per-query)."""
     duration_api_ms: int
+    """Cumulative API time across the entire session."""
     is_error: bool
     num_turns: int
+    """Number of model turns in this query only (per-query)."""
     total_cost_usd: float
+    """Cumulative cost across the entire session."""
     usage: Usage
+    """Token usage from the last API call only (per-turn)."""
     stop_reason: StopReason | None
     modelUsage: dict[str, ModelUsage]  # noqa: N815
+    """Cumulative token usage per model across the entire session."""
     permission_denials: list[SDKPermissionDenial]