claude-agent-sdk 0.1.2__py3-none-any.whl → 0.1.3__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
@@ -307,8 +315,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/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/_version.py

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

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],
 ]
 

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: claude-agent-sdk
-Version: 0.1.2
+Version: 0.1.3
 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

{claude_agent_sdk-0.1.2.dist-info → claude_agent_sdk-0.1.3.dist-info}/RECORD

@@ -1,17 +1,17 @@
-claude_agent_sdk/__init__.py,sha256=QRRGe-x2Hi5OhaWijWFmkdNj8KGTCWZSLnY1joHxRvo,11626
+claude_agent_sdk/__init__.py,sha256=6bpu7xdAzyHRRgxdXGBFbZgS-sVq2bvC7s2Z_whog7c,12035
 claude_agent_sdk/_errors.py,sha256=nSdJNNeszvXG1PfnXd2sQpVNORqMct-MfPaiM3XeJL4,1579
-claude_agent_sdk/_version.py,sha256=gH3XIeCoHbr7H3mMURVo0sN_jBTdSnmewcxVv7F24Kc,71
+claude_agent_sdk/_version.py,sha256=E5buSXiVJIZpoi3ylyUDKfQutllqoNUPcsm7cW4lC70,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/types.py,sha256=0CJP14sf1PJm1NdpLYvFQ_8bUrtuQMWaOPHsmvxB040,16646
 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/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=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,,
+claude_agent_sdk-0.1.3.dist-info/METADATA,sha256=UieBXMnHeT5-bVpX8aJWQtph4MtLpf4hL8O-vL1up-8,9648
+claude_agent_sdk-0.1.3.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+claude_agent_sdk-0.1.3.dist-info/licenses/LICENSE,sha256=zr3eio-57lnl6q7RlXi_gIWqcEdWIlnDHzjyJcJvaBI,1070
+claude_agent_sdk-0.1.3.dist-info/RECORD,,