Merge origin/main into feat/include-hook-events

Author: qing-ant

src/claude_agent_sdk/__init__.py

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

src/claude_agent_sdk/_internal/client.py

@@ -227,3 +227,4 @@ async def _on_mirror_error(key: Any, error: str) -> None:
 
         finally:
             await query.close()
+            query.close_receive_stream()

src/claude_agent_sdk/_internal/message_parser.py

@@ -7,6 +7,7 @@
 from ..types import (
     AssistantMessage,
     ContentBlock,
+    DeferredToolUse,
     HookEventMessage,
     Message,
     MirrorErrorMessage,
@@ -244,6 +245,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"],
@@ -258,6 +260,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/_internal/query.py

@@ -354,6 +354,11 @@ async def _handle_control_request(self, request: SDKControlRequest) -> None:
                     or [],
                     tool_use_id=permission_request.get("tool_use_id"),
                     agent_id=permission_request.get("agent_id"),
+                    blocked_path=permission_request.get("blocked_path"),
+                    decision_reason=permission_request.get("decision_reason"),
+                    title=permission_request.get("title"),
+                    display_name=permission_request.get("display_name"),
+                    description=permission_request.get("description"),
                 )
 
                 response = await self.can_use_tool(
@@ -823,10 +828,21 @@ async def close(self) -> None:
         # checks _closed before the buffer, so closing it here would make a
         # non-parked consumer drop buffered messages with
         # ClosedResourceError. _message_send.close() alone yields
-        # EndOfStream after the buffer drains.
+        # EndOfStream after the buffer drains; the consumer calls
+        # close_receive_stream() once it's done iterating (#859).
         self._message_send.close()
         await self.transport.close()
 
+    def close_receive_stream(self) -> None:
+        """Close the receive side of the message stream.
+
+        Call once the consumer has finished iterating ``receive_messages()``.
+        ``close()`` leaves this open so a still-draining consumer can read
+        buffered messages; the consumer is responsible for closing it to
+        avoid a ``ResourceWarning`` from anyio's ``__del__``.
+        """
+        self._message_receive.close()
+
     # Make Query an async iterator
     def __aiter__(self) -> AsyncIterator[dict[str, Any]]:
         """Return async iterator for messages."""

src/claude_agent_sdk/client.py

@@ -609,6 +609,7 @@ async def disconnect(self) -> None:
         """Disconnect from Claude."""
         if self._query:
             await self._query.close()
+            self._query.close_receive_stream()
             self._query = None
         self._transport = None
         if self._materialized is not None:

src/claude_agent_sdk/types.py

@@ -95,7 +95,7 @@ class AgentDefinition:
     initialPrompt: str | None = None  # noqa: N815
     maxTurns: int | None = None  # noqa: N815
     background: bool | None = None
-    effort: Literal["low", "medium", "high", "max"] | int | None = None
+    effort: Literal["low", "medium", "high", "xhigh", "max"] | int | None = None
     permissionMode: PermissionMode | None = None  # noqa: N815
 
 
@@ -181,9 +181,29 @@ class ToolPermissionContext:
     )  # Permission suggestions from CLI
     tool_use_id: str | None = None
     """Unique identifier for this specific tool call within the assistant message.
-    Multiple tool calls in the same assistant message will have different tool_use_ids."""
+    Multiple tool calls in the same assistant message will have different tool_use_ids.
+
+    Always a non-empty string when delivered to a ``can_use_tool`` callback (the
+    wire protocol guarantees it); the ``Optional`` is only for dataclass
+    field-ordering compatibility, so callers do not need to handle ``None``."""
     agent_id: str | None = None
     """If running within the context of a sub-agent, the sub-agent's ID."""
+    blocked_path: str | None = None
+    """The file path that triggered the permission request, if applicable.
+    For example, when a Bash command tries to access a path outside allowed directories."""
+    decision_reason: str | None = None
+    """Explains why this permission request was triggered.
+    When a PreToolUse hook returns ``permissionDecision: "ask"`` with a
+    ``permissionDecisionReason``, that reason is forwarded here."""
+    title: str | None = None
+    """Full permission prompt sentence (e.g. "Claude wants to read foo.txt").
+    Use this as the primary prompt text when present instead of reconstructing
+    from tool name + input."""
+    display_name: str | None = None
+    """Short noun phrase for the tool action (e.g. "Read file"), suitable for
+    button labels or compact UI."""
+    description: str | None = None
+    """Human-readable subtitle for the permission UI."""
 
 
 # Match TypeScript's PermissionResult structure
@@ -370,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]
@@ -381,7 +401,17 @@ class PostToolUseHookSpecificOutput(TypedDict):
 
     hookEventName: Literal["PostToolUse"]
     additionalContext: NotRequired[str]
+    updatedToolOutput: NotRequired[Any]
+    """Replaces the tool output before it is sent to the model.
+
+    For built-in tools (Bash, Read, Edit, etc.) the value must match the tool's
+    output schema (e.g. ``{"stdout": ..., "stderr": ..., "interrupted": ...}``
+    for Bash); a mismatched shape is rejected and the original output is kept.
+    """
     updatedMCPToolOutput: NotRequired[Any]
+    """Replaces the output for MCP tools only. Prefer ``updatedToolOutput``,
+    which works for all tools.
+    """
 
 
 class PostToolUseFailureHookSpecificOutput(TypedDict):
@@ -1074,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."""
@@ -1091,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
 
@@ -1669,10 +1714,15 @@ class ClaudeAgentOptions:
     """
 
     can_use_tool: CanUseTool | None = None
-    """Custom permission handler for controlling tool usage.
+    """Custom permission handler for tool calls that would otherwise prompt the user.
 
-    Called before each tool execution to determine if it should be allowed,
-    denied, or prompt the user.
+    Invoked when the CLI's permission rules evaluate to "ask" for a tool call —
+    it is the SDK replacement for the interactive permission prompt. It is *not*
+    invoked for tool calls already permitted by ``allowed_tools``,
+    ``permission_mode`` (e.g. ``"acceptEdits"`` / ``"bypassPermissions"``), or
+    ``permissions.allow`` rules in settings, since those never reach a prompt.
+    To observe or gate *every* tool call regardless of permission rules, use a
+    ``PreToolUse`` hook via ``hooks`` instead.
     """
 
     hooks: dict[HookEvent, list[HookMatcher]] | None = None
@@ -1783,14 +1833,16 @@ class ClaudeAgentOptions:
     See https://docs.anthropic.com/en/docs/build-with-claude/adaptive-thinking.
     """
 
-    effort: Literal["low", "medium", "high", "max"] | None = None
+    effort: Literal["low", "medium", "high", "xhigh", "max"] | None = None
     """Controls how much effort Claude puts into its response.
 
     Works with adaptive thinking to guide thinking depth.
 
     - ``"low"`` — Minimal thinking, fastest responses.
     - ``"medium"`` — Moderate thinking.
     - ``"high"`` — Deep reasoning (default).
+    - ``"xhigh"`` — Extended reasoning depth (Opus 4.7 only; falls back to
+      ``"high"`` on other models).
     - ``"max"`` — Maximum effort.
 
     See https://docs.anthropic.com/en/docs/build-with-claude/effort.
@@ -1861,6 +1913,10 @@ class SDKControlPermissionRequest(TypedDict):
     # TODO: Add PermissionUpdate type here
     permission_suggestions: list[Any] | None
     blocked_path: str | None
+    decision_reason: NotRequired[str]
+    title: NotRequired[str]
+    display_name: NotRequired[str]
+    description: NotRequired[str]
     tool_use_id: str
     agent_id: NotRequired[str]
 

tests/test_client.py

@@ -154,6 +154,7 @@ async def _test():
                 mock_query.start = AsyncMock()
                 mock_query.initialize = AsyncMock()
                 mock_query.close = AsyncMock()
+                mock_query.close_receive_stream = Mock()
                 mock_query._tg = None
 
                 def _consume_coro(coro):
@@ -225,6 +226,7 @@ async def _test():
                 mock_query.start = AsyncMock()
                 mock_query.initialize = AsyncMock()
                 mock_query.close = AsyncMock()
+                mock_query.close_receive_stream = Mock()
                 mock_query._tg = None
 
                 def _consume_coro(coro):
@@ -258,9 +260,6 @@ async def mock_receive():
         anyio.run(_test)
 
 
-@pytest.mark.filterwarnings(
-    "ignore:Unclosed <MemoryObjectReceiveStream:ResourceWarning"
-)
 class TestClaudeSDKClientTrioBackend:
     """Regression test: ClaudeSDKClient must work under trio.
 
@@ -325,3 +324,43 @@ async def _test():
             mock_transport.close.assert_called_once()
 
         anyio.run(_test, backend="trio")
+
+
+class TestClaudeSDKClientResourceCleanup:
+    """Regression for #859: disconnect() must close the receive stream.
+
+    ``Query.close()`` deliberately leaves ``_message_receive`` open so a
+    concurrently-draining consumer can finish (see
+    ``test_buffered_messages_drain_after_close_*``). The owning consumer
+    is responsible for closing it once done; ``disconnect()`` is that
+    consumer for ``ClaudeSDKClient``. Before the fix, ``__aexit__`` left
+    the stream open and anyio's ``__del__`` emitted ``ResourceWarning:
+    Unclosed <MemoryObjectReceiveStream>`` under PYTHONDEVMODE.
+    """
+
+    def test_disconnect_closes_receive_stream(self):
+        from anyio import ClosedResourceError
+
+        from claude_agent_sdk import ClaudeSDKClient
+        from claude_agent_sdk._internal.query import Query
+
+        async def _test():
+            mock_transport = AsyncMock()
+            mock_transport.is_ready = Mock(return_value=True)
+
+            async def read_messages():
+                return
+                yield
+
+            mock_transport.read_messages = read_messages
+
+            client = ClaudeSDKClient(transport=mock_transport)
+            client._transport = mock_transport
+            client._query = Query(transport=mock_transport, is_streaming_mode=True)
+            await client._query.start()
+            receive_stream = client._query._message_receive
+            await client.disconnect()
+            with pytest.raises(ClosedResourceError):
+                receive_stream.receive_nowait()
+
+        anyio.run(_test)

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,
     HookEventMessage,
     RateLimitEvent,
     ResultMessage,
@@ -915,9 +916,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.