What this read moved
1–9 of 9agent-sdk/hooks Changed · +5 / -6 lines
from line 553
553553
554554### Make HTTP requests from hooks
555555
556Hooks can perform asynchronous operations like HTTP requests. Catch errors inside your hook instead of letting them propagate, since an unhandled exception can interrupt the agent.
556Hooks can perform asynchronous operations like HTTP requests. Catch errors inside your hook instead of letting them propagate.
557557
558This example sends a webhook after each tool completes, logging which tool ran and when. The hook catches errors so a failed webhook doesn't interrupt the agent:
558This example sends a webhook after each tool completes, logging which tool ran and when. The hook catches errors from a failed webhook:
559559
560560<CodeGroup>
561561 ```python Python theme={null}
from line 591
591591 # Run the blocking HTTP call in a thread to avoid blocking the event loop
592592 await asyncio.to_thread(_send_webhook, input_data["tool_name"])
593593 except Exception as e:
594 # Log the error but don't raise. A failed webhook shouldn't stop the agent
594 # Log the error but don't raise
595595 print(f"Webhook request failed: {e}")
596596
597597 return {}
from line 620
620620 if (error instanceof Error && error.name === "AbortError") {
621621 console.log("Webhook request cancelled");
622622 }
623 // Don't re-throw. A failed webhook shouldn't stop the agent
623 // Don't re-throw
624624 }
625625
626626 return {};
from line 845
845845
846846A `UserPromptSubmit` hook that spawns subagents can create infinite loops if those subagents trigger the same hook. To prevent this:
847847
848* Check for a subagent indicator in the hook input before spawning
849848* Use a shared variable or session state to track whether you're already inside a subagent
850849* Scope hooks to only run for the top-level agent session
851850
agent-sdk/python Changed · +23 / -16 lines
from line 248
248248
249249#### Return type: `SDKSessionInfo`
250250
251| Property | Type | Description |
252| :-------------- | :------------ | :------------------------------------------------------------------- |
253| `session_id` | `str` | Unique session identifier |
254| `summary` | `str` | Display title: custom title, auto-generated summary, or first prompt |
255| `last_modified` | `int` | Last modified time in milliseconds since epoch |
256| `file_size` | `int \| None` | Session file size in bytes (`None` for remote storage backends) |
257| `custom_title` | `str \| None` | User-set session title |
258| `first_prompt` | `str \| None` | First meaningful user prompt in the session |
259| `git_branch` | `str \| None` | Git branch at the end of the session |
260| `cwd` | `str \| None` | Working directory for the session |
261| `tag` | `str \| None` | User-set session tag (see [`tag_session()`](#tag_session)) |
262| `created_at` | `int \| None` | Session creation time in milliseconds since epoch |
251| Property | Type | Description |
252| :-------------- | :------------ | :------------------------------------------------------------------------------ |
253| `session_id` | `str` | Unique session identifier |
254| `summary` | `str` | Display title: custom title, auto-generated summary, or first prompt |
255| `last_modified` | `int` | Last modified time in milliseconds since epoch |
256| `file_size` | `int \| None` | Session file size in bytes (`None` for remote storage backends) |
257| `custom_title` | `str \| None` | Session title: the user-set title, or the auto-generated title when none is set |
258| `first_prompt` | `str \| None` | First meaningful user prompt in the session |
259| `git_branch` | `str \| None` | Git branch at the end of the session |
260| `cwd` | `str \| None` | Working directory for the session |
261| `tag` | `str \| None` | User-set session tag (see [`tag_session()`](#tag_session)) |
262| `created_at` | `int \| None` | Session creation time in milliseconds since epoch |
263263
264264#### Example
265265
from line 437
437437 async def receive_messages(self) -> AsyncIterator[Message]
438438 async def receive_response(self) -> AsyncIterator[Message]
439439 async def interrupt(self) -> None
440 async def set_permission_mode(self, mode: str) -> None
440 async def set_permission_mode(self, mode: PermissionMode) -> None
441441 async def set_model(self, model: str | None = None) -> None
442442 async def rewind_files(self, user_message_id: str) -> None
443443 async def get_mcp_status(self) -> McpStatusResponse
from line 465
465465| `reconnect_mcp_server(server_name)` | Retry connecting to an MCP server that failed or was disconnected |
466466| `toggle_mcp_server(server_name, enabled)` | Enable or disable an MCP server mid-session. Disabling removes its tools |
467467| `stop_task(task_id)` | Stop a running background task. A [`TaskNotificationMessage`](#tasknotificationmessage) with status `"stopped"` follows in the message stream |
468| `get_server_info()` | Get server information including session ID and capabilities |
468| `get_server_info()` | Get the server's initialization info, including available commands and output styles |
469469| `disconnect()` | Disconnect from Claude |
470470
471471#### Context Manager Support
from line 1814
18141814Union type of all content blocks.
18151815
18161816```python theme={null}
1817ContentBlock = TextBlock | ThinkingBlock | ToolUseBlock | ToolResultBlock
1817ContentBlock = (
1818 TextBlock
1819 | ThinkingBlock
1820 | ToolUseBlock
1821 | ToolResultBlock
1822 | ServerToolUseBlock
1823 | ServerToolResultBlock
1824)
18181825```
18191826
18201827### `TextBlock`
from line 3368
33613368| `allowedDomains` | `list[str]` | `[]` | Domain names that sandboxed processes can access |
33623369| `deniedDomains` | `list[str]` | `[]` | Domain names that sandboxed processes cannot access. Takes precedence over `allowedDomains` |
33633370| `allowManagedDomainsOnly` | `bool` | `False` | Managed-settings only: when set in managed settings, ignore `allowedDomains` and `WebFetch(domain:...)` allow rules from non-managed settings sources. Has no effect when set via SDK options |
3364| `allowUnixSockets` | `list[str]` | `[]` | Unix socket paths that processes can access (e.g., Docker socket) |
3371| `allowUnixSockets` | `list[str]` | `[]` | macOS only: Unix socket paths that processes can access, such as the Docker socket. Ignored on Linux |
33653372| `allowAllUnixSockets` | `bool` | `False` | Allow access to all Unix sockets |
33663373| `allowLocalBinding` | `bool` | `False` | Allow processes to bind to local ports (e.g., for dev servers) |
33673374| `allowMachLookup` | `list[str]` | `[]` | macOS only: XPC/Mach service names to allow. Supports a trailing wildcard |
agent-sdk/skills Changed · +4 / -4 lines
from line 91
9191
9292### Confirm skills loaded
9393
94Near the start of the stream, the SDK yields a system message with subtype `init`. Check its `skills` array to confirm your skills loaded before Claude starts working. The array includes the user-invocable skills that you have defined, along with [bundled skills included with Claude Code](/docs/en/skills#bundled-skills).
94Near the start of the stream, the SDK yields a system message with subtype `init`. Check its `skills` array to confirm your skills loaded before Claude starts working. The array includes the user-invocable skills that you have defined with a `description` or `when_to_use` frontmatter field, along with [bundled skills included with Claude Code](/docs/en/skills#bundled-skills).
9595
96The array lists user-invocable skills only. A skill with [`user-invocable: false`](/docs/en/skills#control-who-invokes-a-skill) in its frontmatter loads and remains available to Claude, but doesn't appear in the array. The array reflects what the session discovered and lists the same skills whether or not they're in your `skills` list.
96The array lists user-invocable skills only. A skill with [`user-invocable: false`](/docs/en/skills#control-who-invokes-a-skill) in its frontmatter loads and remains available to Claude, but doesn't appear in the array. The array lists the same skills whether or not they're in your `skills` list.
9797
9898### Allow only specific skills
9999
from line 155
155155Available commands: ["clear", "compact", "context", "usage", "code-review", "verify", "security-check", ...]
156156```
157157
158Your user-invocable skills appear in both this list and the `skills` array from [Confirm skills loaded](#confirm-skills-loaded). The `slash_commands` list adds the rest of the commands available in your session. A skill with [`user-invocable: false`](/docs/en/skills#control-who-invokes-a-skill) in its frontmatter doesn't appear in either. Sessions that configure [MCP servers](/docs/en/agent-sdk/mcp) can also expose [MCP prompts as commands](/docs/en/mcp#use-mcp-prompts-as-commands).
158A skill with [`user-invocable: false`](/docs/en/skills#control-who-invokes-a-skill) in its frontmatter doesn't appear in this list or in the `skills` array from [Confirm skills loaded](#confirm-skills-loaded). Sessions that configure [MCP servers](/docs/en/agent-sdk/mcp) can also expose [MCP prompts as commands](/docs/en/mcp#use-mcp-prompts-as-commands).
159159
160160### Dispatch commands by name
161161
agent-sdk/streaming-output Changed · +4 / -27 lines
from line 71
7171
7272When partial messages are enabled, you receive raw Claude API streaming events wrapped in an object. The type has different names in each SDK:
7373
74* **Python**: `StreamEvent` (import from `claude_agent_sdk.types`)
75* **TypeScript**: `SDKPartialAssistantMessage` with `type: 'stream_event'`
74* **Python**: [`StreamEvent`](/docs/en/agent-sdk/python#streamevent) (import from `claude_agent_sdk.types`)
75* **TypeScript**: [`SDKPartialAssistantMessage`](/docs/en/agent-sdk/typescript#sdkpartialassistantmessage) with `type: 'stream_event'`
7676
77Both contain raw Claude API events, not accumulated text. You need to extract and accumulate text deltas yourself. Here's the structure of each type:
78
79<CodeGroup>
80 ```python Python theme={null}
81 @dataclass
82 class StreamEvent:
83 uuid: str # Unique identifier for this event
84 session_id: str # Session identifier
85 event: dict[str, Any] # The raw Claude API stream event
86 parent_tool_use_id: str | None # Always None
87 ```
88
89 ```typescript TypeScript theme={null}
90 type SDKPartialAssistantMessage = {
91 type: "stream_event";
92 event: BetaRawMessageStreamEvent; // From Anthropic SDK
93 parent_tool_use_id: string | null;
94 uuid: UUID;
95 session_id: string;
96 ttft_ms?: number; // Time to first token in ms, present only on message_start events
97 user_message_uuid?: string;
98 };
99 ```
100</CodeGroup>
77Both contain raw Claude API events, not accumulated text. You need to extract and accumulate text deltas yourself.
10178
10279The `parent_tool_use_id` field is always `None` in Python and `null` in TypeScript. Stream events are emitted for the main session only; token-level deltas from subagents aren't forwarded. To attribute output to a subagent, use complete messages, which carry `parent_tool_use_id`. See [Detect subagent invocation](/docs/en/agent-sdk/subagents#detect-subagent-invocation).
10380
agent-sdk/claude-code-features Changed · +0 / -2 lines
from line 180
180180* **Filesystem hooks:** shell commands defined in `settings.json`, loaded when `settingSources` includes the relevant source. These are the same hooks you'd configure for [interactive Claude Code sessions](/docs/en/hooks-guide).
181181* **Programmatic hooks:** callback functions passed directly to `query()`. These run in your application process and can return structured decisions. See [Control execution with hooks](/docs/en/agent-sdk/hooks).
182182
183Both types execute during the same hook lifecycle. If you already have hooks in your project's `.claude/settings.json` and you set `settingSources: ["project"]`, those hooks run automatically in the SDK with no extra configuration.
184
185183Hook callbacks receive the tool input and return a decision dict. Returning `{}` means allow the tool to proceed. To block execution, return a `hookSpecificOutput` object with `permissionDecision: "deny"` and a `permissionDecisionReason`. The reason is sent to Claude as the tool result. See the [hooks guide](/docs/en/agent-sdk/hooks) for the full callback signature and return types.
186184
187185<CodeGroup>
agent-sdk/mcp Changed · +1 / -1 lines
from line 148
148148| :------------------------------------------------------------------------------------- | :----------------------------------------------------- | :------------------------------------------------------------------------------------------ |
149149| stdio server, or HTTP/SSE server without a cached tool list | Yes, until it connects | [`MCP_TIMEOUT`](/docs/en/env-vars), 30 seconds by default; the connection fails at that deadline |
150150| Remote server with a cached tool list, saved by Claude Code from a previous connection | No; the cached tools are available from the first turn | None; connects on its first tool call, and that deferred connect has its own timeout |
151| In-process [SDK server](#sdk-mcp-servers) | No; never delays the first turn | None |
151| In-process [SDK server](#sdk-mcp-servers) | Yes, until it connects and lists its tools | None; the connect and tool listing requests each have their own timeout |
152152
153153To block startup itself at a separate, earlier phase than the first-turn wait, before the init message is sent:
154154
agent-sdk/modifying-system-prompts Changed · +1 / -1 lines
from line 140
140140 const options = { settings: { outputStyle: "Explanatory" } };
141141 ```
142142
143The Python SDK does not have an option to select an output style programmatically. For code-only deployments where you can't write to `.claude/settings.local.json`, use `append` or a custom prompt string instead.
143In the Python SDK, set `outputStyle` through the `settings` option, which takes a JSON string such as `'{"outputStyle": "Explanatory"}'` or a path to a settings file that sets it.
144144
145145**Note for SDK users:** Output styles are loaded when you include `settingSources: ['user']` or `settingSources: ['project']` (TypeScript) / `setting_sources=["user"]` or `setting_sources=["project"]` (Python) in your options.
146146
agent-sdk/overview Changed · +1 / -1 lines
from line 10
1010
1111| If you're... | Use | Why |
1212| ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
13| Building an agent without implementing the tool loop yourself | **Agent SDK** | A library that runs the agent loop in your own process, in Python or TypeScript. |
13| Building an agent without implementing the tool loop yourself | **Agent SDK** | A Python or TypeScript library that runs the agent loop for you. |
1414| Doing interactive development or running one-off tasks from a terminal | [**Claude Code CLI**](/docs/en/overview) | The terminal interface, built for daily interactive use. |
1515| Calling the API directly and implementing the tool loop yourself | [**Client SDK**](https://platform.claude.com/docs/en/api/client-sdks) | Direct access to the Anthropic API rather than to Claude Code. You implement the tool loop yourself. |
1616| Running long-running or asynchronous agents without managing your own sandbox or session infrastructure | [**Managed Agents**](https://platform.claude.com/docs/en/managed-agents/overview) | Hosted REST API, a separate product from the Agent SDK. Anthropic runs the agent and the sandbox. |
github-enterprise-server Changed · +1 / -1 lines
from line 100
100100claude --cloud "Add retry logic to the payment webhook handler"
101101```
102102
103The session clones your repository from GHES and pushes changes back to a branch. Monitor progress with `/tasks` or at [claude.ai/code](https://claude.ai/code). See [Claude Code on the web](/docs/en/claude-code-on-the-web) for the full cloud session workflow including diff review, auto-fix, and routines.
103The session clones your repository from GHES and pushes changes back to a branch. Monitor progress at [claude.ai/code](https://claude.ai/code). See [Claude Code on the web](/docs/en/claude-code-on-the-web) for the full cloud session workflow including diff review, auto-fix, and routines.
104104
105105### Teleport sessions to your terminal
106106