types: tighten permission/control protocol typing; docs: include 'plan' mode

src/claude_agent_sdk/client.py

@@ -8,7 +8,14 @@ from typing import Any
 
 from . import Transport
 from ._errors import CLIConnectionError
-from .types import ClaudeAgentOptions, HookEvent, HookMatcher, Message, ResultMessage
+from .types import (
+    ClaudeAgentOptions,
+    HookEvent,
+    HookMatcher,
+    Message,
+    PermissionMode,
+    ResultMessage,
+)
 
 
 class ClaudeSDKClient:
@@ -203,8 +210,6 @@ class ClaudeSDKClient:
             raise CLIConnectionError("Not connected. Call connect() first.")
         await self._query.interrupt()
 
-    from .types import PermissionMode
-
     async def set_permission_mode(self, mode: PermissionMode) -> None:
         """Change permission mode during conversation (only works with streaming mode).
 

src/claude_agent_sdk/query.py

@@ -55,7 +55,9 @@ 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
-                 - 'accept
+                 - 'acceptEdits': Auto-accept file edits
+                 - 'plan': Plan-only (no edits)
+                 - 'bypassPermissions': Allow all tools (use with caution)
                  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

@@ -164,7 +164,7 @@ class BaseHookInput(TypedDict):
     session_id: str
     transcript_path: str
     cwd: str
-    permission_mode: NotRequired[str]
+    permission_mode: NotRequired[PermissionMode]
 
 
 class PreToolUseHookInput(BaseHookInput):
@@ -571,13 +571,6 @@ class SDKControlInitializeRequest(TypedDict):
     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