feat: forward decision_reason and permission-display fields to ToolPermissionContext (#909)

Fixes #816.

## Summary

The CLI already includes `decision_reason`, `blocked_path`, `title`,
`display_name`, and `description` on the `can_use_tool` control request
— and the TypeScript SDK already exposes them on its
`ToolPermissionContext`. The Python SDK was dropping them on the floor.

This adds the five fields to `ToolPermissionContext` and
`SDKControlPermissionRequest`, and populates them in
`Query._handle_control_request`. Now a `can_use_tool` callback can:

- Show users *why* they're being prompted (`decision_reason` — e.g. a
PreToolUse hook's `permissionDecisionReason`)
- Render a richer permission prompt (`title` / `display_name` /
`description`) without reconstructing it from `tool_name` + `input`
- See which path triggered the prompt (`blocked_path`)

All fields are optional (`str | None = None`), so this is
backward-compatible.

## Testing

- New unit test `test_permission_callback_receives_decision_reason` —
fails on `main` with `AttributeError: 'ToolPermissionContext' object has
no attribute 'blocked_path'`, passes here.
- Full suite: 716 passed, 2 pre-existing failures in
`test_transcript_mirror.py` (eager-flush, unrelated to this change).
- `ruff check` / `ruff format`: clean.
- `mypy src/`: 2 pre-existing errors in `_task_compat.py` (trio
import-not-found), none introduced.
- Live e2e proof in PR comment below.

---
_Generated by [Claude
Code](https://claude.ai/code/session_013yvWPbykUnMTtyRxaa51sK)_

Co-authored-by: Claude <noreply@anthropic.com>

Author: qing-ant

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(

src/claude_agent_sdk/types.py

@@ -188,6 +188,22 @@ class ToolPermissionContext:
     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
@@ -1838,6 +1854,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_tool_callbacks.py

@@ -249,6 +249,56 @@ async def capture_callback(
         assert received_context.tool_use_id == "toolu_01XYZ789"
         assert received_context.agent_id is None
 
+    @pytest.mark.asyncio
+    async def test_permission_callback_receives_decision_reason(self):
+        """Test that decision_reason and permission-display fields are forwarded
+        to the context (TS SDK parity, #816)."""
+        received_context = None
+
+        async def capture_callback(
+            tool_name: str, input_data: dict, context: ToolPermissionContext
+        ) -> PermissionResultAllow:
+            nonlocal received_context
+            received_context = context
+            return PermissionResultAllow()
+
+        transport = MockTransport()
+        query = Query(
+            transport=transport,
+            is_streaming_mode=True,
+            can_use_tool=capture_callback,
+            hooks=None,
+        )
+
+        request = {
+            "type": "control_request",
+            "request_id": "test-reason",
+            "request": {
+                "subtype": "can_use_tool",
+                "tool_name": "Bash",
+                "input": {"command": "rm -rf /tmp/x"},
+                "permission_suggestions": [],
+                "tool_use_id": "toolu_01DEF456",
+                "blocked_path": "/tmp/x",
+                "decision_reason": "PreToolUse hook flagged this as destructive",
+                "title": "Claude wants to run a Bash command",
+                "display_name": "Bash",
+                "description": "rm -rf /tmp/x",
+            },
+        }
+
+        await query._handle_control_request(request)
+
+        assert received_context is not None
+        assert received_context.blocked_path == "/tmp/x"
+        assert (
+            received_context.decision_reason
+            == "PreToolUse hook flagged this as destructive"
+        )
+        assert received_context.title == "Claude wants to run a Bash command"
+        assert received_context.display_name == "Bash"
+        assert received_context.description == "rm -rf /tmp/x"
+
     @pytest.mark.asyncio
     async def test_callback_exception_handling(self):
         """Test that callback exceptions are properly handled."""