From 36ef10b5dbf92cc432f759cdb5b2fb8ed5520b00 Mon Sep 17 00:00:00 2001
From: Philipp Temminghoff <philipptemminghoff@googlemail.com>
Date: Tue, 6 Jan 2026 07:18:33 +0100
Subject: [PATCH] feat: add tool_use_id and blocked_path to
 ToolPermissionContext

Add tool_use_id and blocked_path fields to ToolPermissionContext to match
the TypeScript SDK's CanUseTool callback signature.

This allows permission callbacks to know which specific tool call is being
authorized, enabling proper tracking and UI correlation (e.g., for ACP
permission dialogs that need to reference the tool call).

Changes:
- Add tool_use_id (required) and blocked_path (optional) to ToolPermissionContext
- Add tool_use_id to SDKControlPermissionRequest TypedDict
- Update _handle_control_request to pass these fields to the callback
---
 src/claude_agent_sdk/_internal/query.py |  2 ++
 src/claude_agent_sdk/types.py           | 17 ++++++++++++++++-
 2 files changed, 18 insertions(+), 1 deletion(-)

diff --git a/src/claude_agent_sdk/_internal/query.py b/src/claude_agent_sdk/_internal/query.py
index c30fc159..12822e58 100644
--- a/src/claude_agent_sdk/_internal/query.py
+++ b/src/claude_agent_sdk/_internal/query.py
@@ -242,9 +242,11 @@ async def _handle_control_request(self, request: SDKControlRequest) -> None:
                     raise Exception("canUseTool callback is not provided")
 
                 context = ToolPermissionContext(
+                    tool_use_id=permission_request.get("tool_use_id", ""),
                     signal=None,  # TODO: Add abort signal support
                     suggestions=permission_request.get("permission_suggestions", [])
                     or [],
+                    blocked_path=permission_request.get("blocked_path"),
                 )
 
                 response = await self.can_use_tool(
diff --git a/src/claude_agent_sdk/types.py b/src/claude_agent_sdk/types.py
index 9c09345f..0292386f 100644
--- a/src/claude_agent_sdk/types.py
+++ b/src/claude_agent_sdk/types.py
@@ -123,12 +123,26 @@ def to_dict(self) -> dict[str, Any]:
 # Tool callback types
 @dataclass
 class ToolPermissionContext:
-    """Context information for tool permission callbacks."""
+    """Context information for tool permission callbacks.
 
+    Attributes:
+        tool_use_id: 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.
+        signal: Reserved for future abort signal support. Currently always None.
+        suggestions: Permission suggestions from CLI for updating permissions
+            so the user won't be prompted again for this tool during this session.
+        blocked_path: The file path that triggered the permission request, if
+            applicable. For example, when a Bash command tries to access a path
+            outside allowed directories.
+    """
+
+    tool_use_id: str
     signal: Any | None = None  # Future: abort signal support
     suggestions: list[PermissionUpdate] = field(
         default_factory=list
     )  # Permission suggestions from CLI
+    blocked_path: str | None = None
 
 
 # Match TypeScript's PermissionResult structure
@@ -689,6 +703,7 @@ class SDKControlPermissionRequest(TypedDict):
     subtype: Literal["can_use_tool"]
     tool_name: str
     input: dict[str, Any]
+    tool_use_id: str  # Unique identifier for this tool call
     # TODO: Add PermissionUpdate type here
     permission_suggestions: list[Any] | None
     blocked_path: str | None