feat: support "defer" hook decision and ResultMessage.deferred_tool_use (#865)

## Summary

Brings the Python SDK to parity with the TypeScript SDK for the
PreToolUse `"defer"` round trip. The CLI has emitted `deferred_tool_use`
on result messages since v2.1.89, but the Python SDK was dropping it.

- `PreToolUseHookSpecificOutput.permissionDecision` now accepts
`"defer"` alongside `"allow" | "deny" | "ask"`
- New `DeferredToolUse` dataclass (`id`, `name`, `input`) — mirrors the
TS `SDKDeferredToolUse` type
- `ResultMessage.deferred_tool_use: DeferredToolUse | None` — populated
when a PreToolUse hook deferred a tool call
- `message_parser` extracts the field from CLI result output
- `DeferredToolUse` exported from the package root

`DeferredToolUse` is intentionally a separate type from `ToolUseBlock`
(despite identical fields) to keep `ContentBlock` isinstance checks
unambiguous and match the TS SDK's typing.

## Test plan

- [x] `ruff check` / `ruff format` — clean
- [x] `mypy src/` — clean
- [x] `pytest tests/test_message_parser.py tests/test_types.py` — 94
passed
- [x] New test `test_parse_result_message_with_deferred_tool_use` covers
the parse path
- [x] Existing `test_parse_result_message_optional_fields_absent`
extended to assert `deferred_tool_use is None` when absent

Author: sarahdeaton

src/claude_agent_sdk/__init__.py

@@ -64,6 +64,7 @@
     ContentBlock,
     ContextUsageCategory,
     ContextUsageResponse,
+    DeferredToolUse,
     HookCallback,
     HookContext,
     HookInput,
@@ -544,6 +545,7 @@ async def call_tool(name: str, arguments: dict[str, Any]) -> Any:
     "TaskNotificationStatus",
     "TaskUsage",
     "ResultMessage",
+    "DeferredToolUse",
     "RateLimitEvent",
     "RateLimitInfo",
     "RateLimitStatus",

src/claude_agent_sdk/_internal/message_parser.py

@@ -7,6 +7,7 @@
 from ..types import (
     AssistantMessage,
     ContentBlock,
+    DeferredToolUse,
     Message,
     MirrorErrorMessage,
     RateLimitEvent,
@@ -221,6 +222,7 @@ def parse_message(data: dict[str, Any]) -> Message | None:
 
         case "result":
             try:
+                deferred = data.get("deferred_tool_use")
                 return ResultMessage(
                     subtype=data["subtype"],
                     duration_ms=data["duration_ms"],
@@ -235,6 +237,13 @@ def parse_message(data: dict[str, Any]) -> Message | None:
                     structured_output=data.get("structured_output"),
                     model_usage=data.get("modelUsage"),
                     permission_denials=data.get("permission_denials"),
+                    deferred_tool_use=DeferredToolUse(
+                        id=deferred["id"],
+                        name=deferred["name"],
+                        input=deferred["input"],
+                    )
+                    if deferred
+                    else None,
                     errors=data.get("errors"),
                     uuid=data.get("uuid"),
                 )

src/claude_agent_sdk/types.py

@@ -390,7 +390,7 @@ class PreToolUseHookSpecificOutput(TypedDict):
     """Hook-specific output for PreToolUse events."""
 
     hookEventName: Literal["PreToolUse"]
-    permissionDecision: NotRequired[Literal["allow", "deny", "ask"]]
+    permissionDecision: NotRequired[Literal["allow", "deny", "ask", "defer"]]
     permissionDecisionReason: NotRequired[str]
     updatedInput: NotRequired[dict[str, Any]]
     additionalContext: NotRequired[str]
@@ -1104,6 +1104,20 @@ class MirrorErrorMessage(SystemMessage):
     error: str = ""
 
 
+@dataclass
+class DeferredToolUse:
+    """Tool use that was deferred by a PreToolUse hook returning ``"defer"``.
+
+    When a PreToolUse hook returns ``permissionDecision: "defer"``, the run
+    stops and the result message carries the deferred tool call here so the
+    caller can inspect it and decide whether to resume.
+    """
+
+    id: str
+    name: str
+    input: dict[str, Any]
+
+
 @dataclass
 class ResultMessage:
     """Result message with cost and usage information."""
@@ -1121,6 +1135,7 @@ class ResultMessage:
     structured_output: Any = None
     model_usage: dict[str, Any] | None = None
     permission_denials: list[Any] | None = None
+    deferred_tool_use: DeferredToolUse | None = None
     errors: list[str] | None = None
     uuid: str | None = None
 

tests/test_message_parser.py

@@ -6,6 +6,7 @@
 from claude_agent_sdk._internal.message_parser import parse_message
 from claude_agent_sdk.types import (
     AssistantMessage,
+    DeferredToolUse,
     RateLimitEvent,
     ResultMessage,
     ServerToolResultBlock,
@@ -914,9 +915,33 @@ def test_parse_result_message_optional_fields_absent(self):
         assert isinstance(message, ResultMessage)
         assert message.model_usage is None
         assert message.permission_denials is None
+        assert message.deferred_tool_use is None
         assert message.errors is None
         assert message.uuid is None
 
+    def test_parse_result_message_with_deferred_tool_use(self):
+        """ResultMessage parses deferred_tool_use into a DeferredToolUse."""
+        data = {
+            "type": "result",
+            "subtype": "success",
+            "duration_ms": 1200,
+            "duration_api_ms": 900,
+            "is_error": False,
+            "num_turns": 1,
+            "session_id": "session_123",
+            "deferred_tool_use": {
+                "id": "toolu_01abc",
+                "name": "Bash",
+                "input": {"command": "rm -rf /tmp/scratch"},
+            },
+        }
+        message = parse_message(data)
+        assert isinstance(message, ResultMessage)
+        assert isinstance(message.deferred_tool_use, DeferredToolUse)
+        assert message.deferred_tool_use.id == "toolu_01abc"
+        assert message.deferred_tool_use.name == "Bash"
+        assert message.deferred_tool_use.input == {"command": "rm -rf /tmp/scratch"}
+
     def test_parse_result_message_with_errors(self):
         """Test that ResultMessage preserves the errors field from error results.