claude-agent-sdk 0.1.2__py3-none-any.whl → 0.1.4__py3-none-any.whl

claude_agent_sdk/__init__.py

@@ -18,11 +18,13 @@ from .query import query
 from .types import (
     AgentDefinition,
     AssistantMessage,
+    BaseHookInput,
     CanUseTool,
     ClaudeAgentOptions,
     ContentBlock,
     HookCallback,
     HookContext,
+    HookInput,
     HookJSONOutput,
     HookMatcher,
     McpSdkServerConfig,
@@ -33,8 +35,13 @@ from .types import (
     PermissionResultAllow,
     PermissionResultDeny,
     PermissionUpdate,
+    PostToolUseHookInput,
+    PreCompactHookInput,
+    PreToolUseHookInput,
     ResultMessage,
     SettingSource,
+    StopHookInput,
+    SubagentStopHookInput,
     SystemMessage,
     TextBlock,
     ThinkingBlock,
@@ -42,6 +49,7 @@ from .types import (
     ToolResultBlock,
     ToolUseBlock,
     UserMessage,
+    UserPromptSubmitHookInput,
 )
 
 # MCP Server Support
@@ -195,7 +203,7 @@ def create_sdk_mcp_server(
         - ClaudeAgentOptions: Configuration for using servers with query()
     """
     from mcp.server import Server
-    from mcp.types import TextContent, Tool
+    from mcp.types import ImageContent, TextContent, Tool
 
     # Create MCP server instance
     server = Server(name, version=version)
@@ -265,11 +273,19 @@ def create_sdk_mcp_server(
             # Convert result to MCP format
             # The decorator expects us to return the content, not a CallToolResult
             # It will wrap our return value in CallToolResult
-            content = []
+            content: list[TextContent | ImageContent] = []
             if "content" in result:
                 for item in result["content"]:
                     if item.get("type") == "text":
                         content.append(TextContent(type="text", text=item["text"]))
+                    if item.get("type") == "image":
+                        content.append(
+                            ImageContent(
+                                type="image",
+                                data=item["data"],
+                                mimeType=item["mimeType"],
+                            )
+                        )
 
             # Return just the content list - the decorator wraps it
             return content
@@ -307,8 +323,17 @@ __all__ = [
     "PermissionResultAllow",
     "PermissionResultDeny",
     "PermissionUpdate",
+    # Hook support
     "HookCallback",
     "HookContext",
+    "HookInput",
+    "BaseHookInput",
+    "PreToolUseHookInput",
+    "PostToolUseHookInput",
+    "UserPromptSubmitHookInput",
+    "StopHookInput",
+    "SubagentStopHookInput",
+    "PreCompactHookInput",
     "HookJSONOutput",
     "HookMatcher",
     # Agent support

claude_agent_sdk/_internal/client.py

@@ -71,7 +71,8 @@ class InternalClient:
             chosen_transport = transport
         else:
             chosen_transport = SubprocessCLITransport(
-                prompt=prompt, options=configured_options
+                prompt=prompt,
+                options=configured_options,
             )
 
         # Connect transport

claude_agent_sdk/_internal/query.py

@@ -31,6 +31,25 @@ if TYPE_CHECKING:
 logger = logging.getLogger(__name__)
 
 
+def _convert_hook_output_for_cli(hook_output: dict[str, Any]) -> dict[str, Any]:
+    """Convert Python-safe field names to CLI-expected field names.
+
+    The Python SDK uses `async_` and `continue_` to avoid keyword conflicts,
+    but the CLI expects `async` and `continue`. This function performs the
+    necessary conversion.
+    """
+    converted = {}
+    for key, value in hook_output.items():
+        # Convert Python-safe names to JavaScript names
+        if key == "async_":
+            converted["async"] = value
+        elif key == "continue_":
+            converted["continue"] = value
+        else:
+            converted[key] = value
+    return converted
+
+
 class Query:
     """Handles bidirectional control protocol on top of Transport.
 
@@ -244,11 +263,13 @@ class Query:
                 if not callback:
                     raise Exception(f"No hook callback found for ID: {callback_id}")
 
-                response_data = await callback(
+                hook_output = await callback(
                     request_data.get("input"),
                     request_data.get("tool_use_id"),
                     {"signal": None},  # TODO: Add abort signal support
                 )
+                # Convert Python-safe field names (async_, continue_) to CLI-expected names (async, continue)
+                response_data = _convert_hook_output_for_cli(hook_output)
 
             elif subtype == "mcp_message":
                 # Handle SDK MCP request

claude_agent_sdk/_internal/transport/subprocess_cli.py

@@ -37,12 +37,13 @@ class SubprocessCLITransport(Transport):
         self,
         prompt: str | AsyncIterable[dict[str, Any]],
         options: ClaudeAgentOptions,
-        cli_path: str | Path | None = None,
     ):
         self._prompt = prompt
         self._is_streaming = not isinstance(prompt, str)
         self._options = options
-        self._cli_path = str(cli_path) if cli_path else self._find_cli()
+        self._cli_path = (
+            str(options.cli_path) if options.cli_path is not None else self._find_cli()
+        )
         self._cwd = str(options.cwd) if options.cwd else None
         self._process: Process | None = None
         self._stdout_stream: TextReceiveStream | None = None
@@ -79,8 +80,8 @@ class SubprocessCLITransport(Transport):
             "  npm install -g @anthropic-ai/claude-code\n"
             "\nIf already installed locally, try:\n"
             '  export PATH="$HOME/node_modules/.bin:$PATH"\n'
-            "\nOr specify the path when creating transport:\n"
-            "  SubprocessCLITransport(..., cli_path='/path/to/claude')"
+            "\nOr provide the path via ClaudeAgentOptions:\n"
+            "  ClaudeAgentOptions(cli_path='/path/to/claude')"
         )
 
     def _build_command(self) -> list[str]:
@@ -205,7 +206,8 @@ class SubprocessCLITransport(Transport):
         if self._process:
             return
 
-        await self._check_claude_version()
+        if not os.environ.get("CLAUDE_AGENT_SDK_SKIP_VERSION_CHECK"):
+            await self._check_claude_version()
 
         cmd = self._build_command()
         try:

claude_agent_sdk/_version.py

@@ -1,3 +1,3 @@
 """Version information for claude-agent-sdk."""
 
-__version__ = "0.1.2"
+__version__ = "0.1.4"

claude_agent_sdk/types.py

@@ -157,6 +157,73 @@ HookEvent = (
 )
 
 
+# Hook input types - strongly typed for each hook event
+class BaseHookInput(TypedDict):
+    """Base hook input fields present across many hook events."""
+
+    session_id: str
+    transcript_path: str
+    cwd: str
+    permission_mode: NotRequired[str]
+
+
+class PreToolUseHookInput(BaseHookInput):
+    """Input data for PreToolUse hook events."""
+
+    hook_event_name: Literal["PreToolUse"]
+    tool_name: str
+    tool_input: dict[str, Any]
+
+
+class PostToolUseHookInput(BaseHookInput):
+    """Input data for PostToolUse hook events."""
+
+    hook_event_name: Literal["PostToolUse"]
+    tool_name: str
+    tool_input: dict[str, Any]
+    tool_response: Any
+
+
+class UserPromptSubmitHookInput(BaseHookInput):
+    """Input data for UserPromptSubmit hook events."""
+
+    hook_event_name: Literal["UserPromptSubmit"]
+    prompt: str
+
+
+class StopHookInput(BaseHookInput):
+    """Input data for Stop hook events."""
+
+    hook_event_name: Literal["Stop"]
+    stop_hook_active: bool
+
+
+class SubagentStopHookInput(BaseHookInput):
+    """Input data for SubagentStop hook events."""
+
+    hook_event_name: Literal["SubagentStop"]
+    stop_hook_active: bool
+
+
+class PreCompactHookInput(BaseHookInput):
+    """Input data for PreCompact hook events."""
+
+    hook_event_name: Literal["PreCompact"]
+    trigger: Literal["manual", "auto"]
+    custom_instructions: str | None
+
+
+# Union type for all hook inputs
+HookInput = (
+    PreToolUseHookInput
+    | PostToolUseHookInput
+    | UserPromptSubmitHookInput
+    | StopHookInput
+    | SubagentStopHookInput
+    | PreCompactHookInput
+)
+
+
 # Hook-specific output types
 class PreToolUseHookSpecificOutput(TypedDict):
     """Hook-specific output for PreToolUse events."""
@@ -198,18 +265,56 @@ HookSpecificOutput = (
 
 # See https://docs.anthropic.com/en/docs/claude-code/hooks#advanced%3A-json-output
 # for documentation of the output types.
+#
+# IMPORTANT: The Python SDK uses `async_` and `continue_` (with underscores) to avoid
+# Python keyword conflicts. These fields are automatically converted to `async` and
+# `continue` when sent to the CLI. You should use the underscore versions in your
+# Python code.
 class AsyncHookJSONOutput(TypedDict):
-    """Async hook output that defers hook execution."""
+    """Async hook output that defers hook execution.
 
-    async_: Literal[True]  # Using async_ to avoid Python keyword
+    Fields:
+        async_: Set to True to defer hook execution. Note: This is converted to
+            "async" when sent to the CLI - use "async_" in your Python code.
+        asyncTimeout: Optional timeout in milliseconds for the async operation.
+    """
+
+    async_: Literal[
+        True
+    ]  # Using async_ to avoid Python keyword (converted to "async" for CLI)
     asyncTimeout: NotRequired[int]
 
 
 class SyncHookJSONOutput(TypedDict):
-    """Synchronous hook output with control and decision fields."""
+    """Synchronous hook output with control and decision fields.
+
+    This defines the structure for hook callbacks to control execution and provide
+    feedback to Claude.
+
+    Common Control Fields:
+        continue_: Whether Claude should proceed after hook execution (default: True).
+            Note: This is converted to "continue" when sent to the CLI.
+        suppressOutput: Hide stdout from transcript mode (default: False).
+        stopReason: Message shown when continue is False.
+
+    Decision Fields:
+        decision: Set to "block" to indicate blocking behavior.
+        systemMessage: Warning message displayed to the user.
+        reason: Feedback message for Claude about the decision.
+
+    Hook-Specific Output:
+        hookSpecificOutput: Event-specific controls (e.g., permissionDecision for
+            PreToolUse, additionalContext for PostToolUse).
+
+    Note: The CLI documentation shows field names without underscores ("async", "continue"),
+    but Python code should use the underscore versions ("async_", "continue_") as they
+    are automatically converted.
+    """
 
     # Common control fields
-    continue_: NotRequired[bool]  # Using continue_ to avoid Python keyword
+    continue_: NotRequired[
+        bool
+    ]  # Using continue_ to avoid Python keyword (converted to "continue" for CLI)
     suppressOutput: NotRequired[bool]
     stopReason: NotRequired[str]
 
@@ -227,21 +332,22 @@ class SyncHookJSONOutput(TypedDict):
 HookJSONOutput = AsyncHookJSONOutput | SyncHookJSONOutput
 
 
-@dataclass
-class HookContext:
-    """Context information for hook callbacks."""
+class HookContext(TypedDict):
+    """Context information for hook callbacks.
 
-    signal: Any | None = None  # Future: abort signal support
+    Fields:
+        signal: Reserved for future abort signal support. Currently always None.
+    """
+
+    signal: Any | None  # Future: abort signal support
 
 
 HookCallback = Callable[
     # HookCallback input parameters:
-    # - input
-    #   See https://docs.anthropic.com/en/docs/claude-code/hooks#hook-input for
-    #   the type of 'input', the first value.
-    # - tool_use_id
-    # - context
-    [dict[str, Any], str | None, HookContext],
+    # - input: Strongly-typed hook input with discriminated unions based on hook_event_name
+    # - tool_use_id: Optional tool use identifier
+    # - context: Hook context with abort signal support (currently placeholder)
+    [HookInput, str | None, HookContext],
     Awaitable[HookJSONOutput],
 ]
 
@@ -406,6 +512,7 @@ class ClaudeAgentOptions:
     model: str | None = None
     permission_prompt_tool_name: str | None = None
     cwd: str | Path | None = None
+    cli_path: str | Path | None = None
     settings: str | None = None
     add_dirs: list[str | Path] = field(default_factory=list)
     env: dict[str, str] = field(default_factory=dict)

{claude_agent_sdk-0.1.2.dist-info → claude_agent_sdk-0.1.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-agent-sdk
-Version: 0.1.2
+Version: 0.1.4
 Summary: Python SDK for Claude Code
 Project-URL: Homepage, https://github.com/anthropics/claude-agent-sdk-python
 Project-URL: Documentation, https://docs.anthropic.com/en/docs/claude-code/sdk
@@ -313,6 +313,16 @@ If you're upgrading from the Claude Code SDK (versions < 0.1.0), please see the
 - Settings isolation and explicit control
 - New programmatic subagents and session forking features
 
+## Development
+
+If you're contributing to this project, run the initial setup script to install git hooks:
+
+```bash
+./scripts/initial-setup.sh
+```
+
+This installs a pre-push hook that runs lint checks before pushing, matching the CI workflow. To skip the hook temporarily, use `git push --no-verify`.
+
 ## License
 
 MIT

claude_agent_sdk-0.1.4.dist-info/RECORD

@@ -0,0 +1,17 @@
+claude_agent_sdk/__init__.py,sha256=6yJ1bjfcLc0oMo-EesY19-uSi-B5dBIZDrCYkwyegXs,12429
+claude_agent_sdk/_errors.py,sha256=nSdJNNeszvXG1PfnXd2sQpVNORqMct-MfPaiM3XeJL4,1579
+claude_agent_sdk/_version.py,sha256=8-5mrhPr_CAF6E5TLSV6Klk6VLu4QNMtphl-yDq8qCg,71
+claude_agent_sdk/client.py,sha256=Bye3QKb-iTg6Yq34ZPGHzaMg1isT9RvyHs5TkC2jWDI,13926
+claude_agent_sdk/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+claude_agent_sdk/query.py,sha256=WebhztsMZPdaxyy1LBEZv4_j23vjp_ceX9DtrBsZqCA,4530
+claude_agent_sdk/types.py,sha256=7rrnHBG7279wWPtor8b7vpIekSzZcUriSbvNBHXoAcE,16685
+claude_agent_sdk/_internal/__init__.py,sha256=zDdgjqp8SI9mTnwZbP2Be-w4LWlv4a3kA-TS2i75jsM,39
+claude_agent_sdk/_internal/client.py,sha256=ySaWYtZUrYMwN93r7qANaD-RGiFlkB49j0njQNVPHRM,4620
+claude_agent_sdk/_internal/message_parser.py,sha256=xxpOU3E8X21FCoy2OtLWKfEQr3AFYM454qJt6Xa0tmc,6475
+claude_agent_sdk/_internal/query.py,sha256=mfSiIfs58U1LYMnbj5GeLATvdI_cRVIxStV1He-cMTE,22015
+claude_agent_sdk/_internal/transport/__init__.py,sha256=sv8Iy1b9YmPlXu4XsdN98gJIlyrLtwq8PKQyF4qnQLk,1978
+claude_agent_sdk/_internal/transport/subprocess_cli.py,sha256=FaVKvXJ9hAbBG-aCnPwUkXxa096DEw_zjI38aiiDiaU,19169
+claude_agent_sdk-0.1.4.dist-info/METADATA,sha256=YRlqbPASEmldUn9VotzoaiOc8fMyR4eOGvc7deGal-M,9949
+claude_agent_sdk-0.1.4.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+claude_agent_sdk-0.1.4.dist-info/licenses/LICENSE,sha256=zr3eio-57lnl6q7RlXi_gIWqcEdWIlnDHzjyJcJvaBI,1070
+claude_agent_sdk-0.1.4.dist-info/RECORD,,

claude_agent_sdk-0.1.2.dist-info/RECORD

@@ -1,17 +0,0 @@
-claude_agent_sdk/__init__.py,sha256=QRRGe-x2Hi5OhaWijWFmkdNj8KGTCWZSLnY1joHxRvo,11626
-claude_agent_sdk/_errors.py,sha256=nSdJNNeszvXG1PfnXd2sQpVNORqMct-MfPaiM3XeJL4,1579
-claude_agent_sdk/_version.py,sha256=gH3XIeCoHbr7H3mMURVo0sN_jBTdSnmewcxVv7F24Kc,71
-claude_agent_sdk/client.py,sha256=Bye3QKb-iTg6Yq34ZPGHzaMg1isT9RvyHs5TkC2jWDI,13926
-claude_agent_sdk/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-claude_agent_sdk/query.py,sha256=WebhztsMZPdaxyy1LBEZv4_j23vjp_ceX9DtrBsZqCA,4530
-claude_agent_sdk/types.py,sha256=x_0tT1ZfisSUrcMdyWRIrrPNe1gWW1zU-T8onoMauxY,13308
-claude_agent_sdk/_internal/__init__.py,sha256=zDdgjqp8SI9mTnwZbP2Be-w4LWlv4a3kA-TS2i75jsM,39
-claude_agent_sdk/_internal/client.py,sha256=Z06Fj4t5mHkKHKBUwxmHMTEo7lzs3X4_D_c-xq6Wg4I,4603
-claude_agent_sdk/_internal/message_parser.py,sha256=xxpOU3E8X21FCoy2OtLWKfEQr3AFYM454qJt6Xa0tmc,6475
-claude_agent_sdk/_internal/query.py,sha256=miJS8pS215PFXirmdfgS2D5FFz4G9Dk25IHyeXUPeqQ,21165
-claude_agent_sdk/_internal/transport/__init__.py,sha256=sv8Iy1b9YmPlXu4XsdN98gJIlyrLtwq8PKQyF4qnQLk,1978
-claude_agent_sdk/_internal/transport/subprocess_cli.py,sha256=ViZxmHoAx3NdFNgLUFgNYuCjJZdVqKk2sxHlB57Z2ng,19097
-claude_agent_sdk-0.1.2.dist-info/METADATA,sha256=ZcJHSdWOTUETMnexdpm_QhqiyZfJP8nSj3XnIKDJ7D0,9648
-claude_agent_sdk-0.1.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
-claude_agent_sdk-0.1.2.dist-info/licenses/LICENSE,sha256=zr3eio-57lnl6q7RlXi_gIWqcEdWIlnDHzjyJcJvaBI,1070
-claude_agent_sdk-0.1.2.dist-info/RECORD,,