chore: update claude-api skill [auto-sync] (#729)

co-sign Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
2026-08-02 13:05:28 +08:00 · 2026-03-22 12:16:01 -04:00
parent b0cbd3df15
commit 887114fd09
24 changed files with 1625 additions and 169 deletions
@@ -115,8 +115,7 @@ Permission modes:
 - `"default"`: Prompt for dangerous operations
 - `"plan"`: Planning only, no execution
 - `"acceptEdits"`: Auto-accept file edits
- `"dontAsk"`: Don't prompt (useful for CI/CD)
- `"bypassPermissions"`: Skip all prompts (requires `allow_dangerously_skip_permissions=True` in options)
+- `"bypassPermissions"`: Skip all prompts (use with caution)

 ---

@@ -164,7 +163,9 @@ async for message in query(
        print(message.result)
 ```

-Available hook events: `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `Notification`, `UserPromptSubmit`, `SessionStart`, `SessionEnd`, `Stop`, `SubagentStart`, `SubagentStop`, `PreCompact`, `PermissionRequest`, `Setup`, `TeammateIdle`, `TaskCompleted`, `ConfigChange`
+Hook callback inputs for tool-lifecycle events (`PreToolUse`, `PostToolUse`, `PostToolUseFailure`) include `agent_id` and `agent_type` fields, allowing hooks to identify which agent (main or subagent) triggered the tool call.
+
+Available hook events: `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `UserPromptSubmit`, `Stop`, `SubagentStop`, `PreCompact`, `Notification`, `SubagentStart`, `PermissionRequest`

 ---

@@ -183,7 +184,6 @@ async for message in query(prompt="...", options=ClaudeAgentOptions(...)):
 | `tools`                             | list   | Built-in tools to make available (restricts the default set)               |
 | `disallowed_tools`                  | list   | Tools to explicitly disallow                                               |
 | `permission_mode`                   | string | How to handle permission prompts                                           |
-| `allow_dangerously_skip_permissions`| bool   | Must be `True` to use `permission_mode="bypassPermissions"`                |
 | `mcp_servers`                       | dict   | MCP servers to connect to                                                  |
 | `hooks`                             | dict   | Hooks for customizing behavior                                             |
 | `system_prompt`                     | string | Custom system prompt                                                       |
@@ -210,8 +210,26 @@ async for message in query(
 ):
    if isinstance(message, ResultMessage):
        print(message.result)
+        print(f"Stop reason: {message.stop_reason}")  # e.g., "end_turn", "max_turns"
    elif isinstance(message, SystemMessage) and message.subtype == "init":
-        session_id = message.session_id  # Capture for resuming later
+        session_id = message.data.get("session_id")  # Capture for resuming later
+```
+
+Typed task message subclasses are available for better type safety when handling subagent task events:
+- `TaskStartedMessage` — emitted when a subagent task is registered
+- `TaskProgressMessage` — real-time progress updates with cumulative usage metrics
+- `TaskNotificationMessage` — task completion notifications
+
+`RateLimitEvent` is emitted when the rate limit status transitions (e.g., from `allowed` to `allowed_warning` or `rejected`). Use it to warn users or back off gracefully:
+
+```python
+from claude_agent_sdk import query, ClaudeAgentOptions, RateLimitEvent
+
+async for message in query(prompt="...", options=ClaudeAgentOptions()):
+    if isinstance(message, RateLimitEvent):
+        print(f"Rate limit status: {message.rate_limit_info.status}")
+        if message.rate_limit_info.resets_at:
+            print(f"Resets at: {message.rate_limit_info.resets_at}")
 ```

 ---
@@ -260,6 +278,64 @@ except CLIConnectionError as e:

 ---

+## Session History
+
+Retrieve past session data with top-level functions:
+
+```python
+from claude_agent_sdk import list_sessions, get_session_messages
+
+# List all past sessions (sync function — no await)
+sessions = list_sessions()
+for session in sessions:
+    print(f"{session.session_id}: {session.cwd}")
+
+# Get messages from a specific session (sync function — no await)
+messages = get_session_messages(session_id="...")
+for msg in messages:
+    print(msg)
+```
+
+### Session Mutations
+
+Rename or tag sessions (sync functions — no await):
+
+```python
+from claude_agent_sdk import rename_session, tag_session
+
+# Rename a session
+rename_session(session_id="...", title="My refactoring session")
+
+# Tag a session (tags are Unicode-sanitized automatically)
+tag_session(session_id="...", tag="experiment")
+
+# Clear a tag
+tag_session(session_id="...", tag=None)
+
+# Optionally scope to a specific project directory
+rename_session(session_id="...", title="New title", directory="/path/to/project")
+```
+
+---
+
+## MCP Server Management
+
+Manage MCP servers at runtime using `ClaudeSDKClient`:
+
+```python
+async with ClaudeSDKClient(options=options) as client:
+    # Reconnect a disconnected MCP server
+    await client.reconnect_mcp_server("my-server")
+
+    # Toggle an MCP server on/off
+    await client.toggle_mcp_server("my-server", enabled=False)
+
+    # Get status of all MCP servers
+    status = await client.get_mcp_status()  # returns McpStatusResponse
+```
+
+---
+
 ## Best Practices

 1. **Always specify allowed_tools** — Explicitly list which tools the agent can use