types: use PermissionUpdate/PermissionMode in control protocol; docs: document 'plan' permission mode; client: type-safe set_permission_mode

src/claude_agent_sdk/client.py

@@ -203,25 +203,17 @@ class ClaudeSDKClient:
             raise CLIConnectionError("Not connected. Call connect() first.")
         await self._query.interrupt()
 
-    async def set_permission_mode(self, mode: str) -> None:
+    from .types import PermissionMode
+
+    async def set_permission_mode(self, mode: PermissionMode) -> None:
         """Change permission mode during conversation (only works with streaming mode).
 
         Args:
             mode: The permission mode to set. Valid options:
                 - 'default': CLI prompts for dangerous tools
                 - 'acceptEdits': Auto-accept file edits
+                - 'plan': Plan-only (no edits; generates plans)
                 - 'bypassPermissions': Allow all tools (use with caution)
-
-        Example:
-            ```python
-            async with ClaudeSDKClient() as client:
-                # Start with default permissions
-                await client.query("Help me analyze this codebase")
-
-                # Review mode done, switch to auto-accept edits
-                await client.set_permission_mode('acceptEdits')
-                await client.query("Now implement the fix we discussed")
-            ```
         """
         if not self._query:
             raise CLIConnectionError("Not connected. Call connect() first.")

src/claude_agent_sdk/query.py

@@ -55,8 +55,7 @@ async def query(
         options: Optional configuration (defaults to ClaudeAgentOptions() if None).
                  Set options.permission_mode to control tool execution:
                  - 'default': CLI prompts for dangerous tools
-                 - 'acceptEdits': Auto-accept file edits
-                 - 'bypassPermissions': Allow all tools (use with caution)
+                 - 'accept
                  Set options.cwd for working directory.
         transport: Optional transport implementation. If provided, this will be used
                   instead of the default transport selection based on options.

src/claude_agent_sdk/types.py

@@ -565,24 +565,29 @@ class SDKControlInterruptRequest(TypedDict):
     subtype: Literal["interrupt"]
 
 
-class SDKControlPermissionRequest(TypedDict):
-    subtype: Literal["can_use_tool"]
-    tool_name: str
-    input: dict[str, Any]
-    # TODO: Add PermissionUpdate type here
-    permission_suggestions: list[Any] | None
-    blocked_path: str | None
-
 
 class SDKControlInitializeRequest(TypedDict):
     subtype: Literal["initialize"]
     hooks: dict[HookEvent, Any] | None
 
 
+class BaseHookInput(TypedDict):
+    """Base hook input fields present across many hook events."""
+    session_id: str
+    transcript_path: str
+    cwd: str
+    permission_mode: NotRequired[PermissionMode]
+
+class SDKControlPermissionRequest(TypedDict):
+    subtype: Literal["can_use_tool"]
+    tool_name: str
+    input: dict[str, Any]
+    permission_suggestions: list[PermissionUpdate] | None
+    blocked_path: str | None
+
 class SDKControlSetPermissionModeRequest(TypedDict):
     subtype: Literal["set_permission_mode"]
-    # TODO: Add PermissionMode
-    mode: str
+    mode: PermissionMode
 
 
 class SDKHookCallbackRequest(TypedDict):