[DOCS] Python SDK Reference example uses `context: dict` but type definition specifies `ToolPermissionContext`

Documentation Type

unclear/confusing documentation

Documentation Location

https://platform.claude.com/docs/en/agent-sdk/python

Section/Topic

"Example - Advanced permission control" section

Current Documentation

async def custom_permission_handler(
tool_name: str,
input_data: dict,
context: dict  # Incorrect type hint
) -> PermissionResultAllow | PermissionResultDeny:
"""Custom logic for tool permissions."""

What's Wrong or Missing?

The context parameter is typed as dict, but the CanUseTool type definition on the same page specifies ToolPermissionContext:

CanUseTool = Callable[
[str, dict[str, Any], ToolPermissionContext],  # <-- Third param is ToolPermissionContext
Awaitable[PermissionResult]
]

And ToolPermissionContext is a proper dataclass:

@dataclass
class ToolPermissionContext:
signal: Any | None = None
suggestions: list[PermissionUpdate] = field(default_factory=list)

The user-input guide correctly uses ToolPermissionContext:

async def can_use_tool(
tool_name: str, input_data: dict, context: ToolPermissionContext
) -> PermissionResultAllow | PermissionResultDeny:

Affected Pages:

| Page | Line(s) |
|------|---------|
| platform.claude.com/docs/en/agent-sdk/python | 390 |

Total scope: 1 page, 1 occurrence

Suggested Improvement

Update the type hint to match the type definition:

from claude_agent_sdk import ToolPermissionContext, PermissionResultAllow, PermissionResultDeny

async def custom_permission_handler(
tool_name: str,
input_data: dict,
context: ToolPermissionContext  # Correct type hint
) -> PermissionResultAllow | PermissionResultDeny:
"""Custom logic for tool permissions."""

Impact

Medium - Makes feature difficult to understand

Additional Context

• The ToolPermissionContext dataclass provides typed access to signal and suggestions properties
• Using dict loses this type information and IDE autocomplete
• The user-input.md guide at lines 82, 87 correctly uses ToolPermissionContext