From c76ddc2f8320d8fba3b77f9f57a2a3afc09d776e Mon Sep 17 00:00:00 2001
From: Alex Newman <thedotmack@gmail.com>
Date: Mon, 10 Nov 2025 15:04:44 -0500
Subject: [PATCH] Add TypeScript Agent SDK reference documentation

- Introduced comprehensive API reference for the TypeScript Agent SDK.
- Documented key functions including `query()`, `tool()`, and `createSdkMcpServer()`.
- Detailed types such as `Options`, `Query`, `AgentDefinition`, and various tool input/output types.
- Included examples and descriptions for configuration options and permission handling.
- Added sections for hook types, tool input/output types, and permission types.
---
 context/agent-sdk-ts-reference.md | 1797 +++++++++++++++++++++++++++++
 1 file changed, 1797 insertions(+)
 create mode 100644 context/agent-sdk-ts-reference.md

diff --git a/context/agent-sdk-ts-reference.md b/context/agent-sdk-ts-reference.md
new file mode 100644
index 00000000..ea7710be
--- /dev/null
+++ b/context/agent-sdk-ts-reference.md
@@ -0,0 +1,1797 @@
+# Agent SDK reference - TypeScript
+
+> Complete API reference for the TypeScript Agent SDK, including all functions, types, and interfaces.
+
+<script src="/components/typescript-sdk-type-links.js" defer />
+
+## Installation
+
+```bash  theme={null}
+npm install @anthropic-ai/claude-agent-sdk
+```
+
+## Functions
+
+### `query()`
+
+The primary function for interacting with Claude Code. Creates an async generator that streams messages as they arrive.
+
+```ts  theme={null}
+function query({
+  prompt,
+  options
+}: {
+  prompt: string | AsyncIterable<SDKUserMessage>;
+  options?: Options;
+}): Query
+```
+
+#### Parameters
+
+| Parameter | Type                                                             | Description                                                       |
+| :-------- | :--------------------------------------------------------------- | :---------------------------------------------------------------- |
+| `prompt`  | `string \| AsyncIterable<`[`SDKUserMessage`](#sdkusermessage)`>` | The input prompt as a string or async iterable for streaming mode |
+| `options` | [`Options`](#options)                                            | Optional configuration object (see Options type below)            |
+
+#### Returns
+
+Returns a [`Query`](#query-1) object that extends `AsyncGenerator<`[`SDKMessage`](#sdkmessage)`, void>` with additional methods.
+
+### `tool()`
+
+Creates a type-safe MCP tool definition for use with SDK MCP servers.
+
+```ts  theme={null}
+function tool<Schema extends ZodRawShape>(
+  name: string,
+  description: string,
+  inputSchema: Schema,
+  handler: (args: z.infer<ZodObject<Schema>>, extra: unknown) => Promise<CallToolResult>
+): SdkMcpToolDefinition<Schema>
+```
+
+#### Parameters
+
+| Parameter     | Type                                                              | Description                                     |
+| :------------ | :---------------------------------------------------------------- | :---------------------------------------------- |
+| `name`        | `string`                                                          | The name of the tool                            |
+| `description` | `string`                                                          | A description of what the tool does             |
+| `inputSchema` | `Schema extends ZodRawShape`                                      | Zod schema defining the tool's input parameters |
+| `handler`     | `(args, extra) => Promise<`[`CallToolResult`](#calltoolresult)`>` | Async function that executes the tool logic     |
+
+### `createSdkMcpServer()`
+
+Creates an MCP server instance that runs in the same process as your application.
+
+```ts  theme={null}
+function createSdkMcpServer(options: {
+  name: string;
+  version?: string;
+  tools?: Array<SdkMcpToolDefinition<any>>;
+}): McpSdkServerConfigWithInstance
+```
+
+#### Parameters
+
+| Parameter         | Type                          | Description                                              |
+| :---------------- | :---------------------------- | :------------------------------------------------------- |
+| `options.name`    | `string`                      | The name of the MCP server                               |
+| `options.version` | `string`                      | Optional version string                                  |
+| `options.tools`   | `Array<SdkMcpToolDefinition>` | Array of tool definitions created with [`tool()`](#tool) |
+
+## Types
+
+### `Options`
+
+Configuration object for the `query()` function.
+
+| Property                     | Type                                                                                              | Default                    | Description                                                                                                                                                                                                                                               |
+| :--------------------------- | :------------------------------------------------------------------------------------------------ | :------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `abortController`            | `AbortController`                                                                                 | `new AbortController()`    | Controller for cancelling operations                                                                                                                                                                                                                      |
+| `additionalDirectories`      | `string[]`                                                                                        | `[]`                       | Additional directories Claude can access                                                                                                                                                                                                                  |
+| `agents`                     | `Record<string, [`AgentDefinition`](#agentdefinition)>`                                           | `undefined`                | Programmatically define subagents                                                                                                                                                                                                                         |
+| `allowedTools`               | `string[]`                                                                                        | All tools                  | List of allowed tool names                                                                                                                                                                                                                                |
+| `canUseTool`                 | [`CanUseTool`](#canusetool)                                                                       | `undefined`                | Custom permission function for tool usage                                                                                                                                                                                                                 |
+| `continue`                   | `boolean`                                                                                         | `false`                    | Continue the most recent conversation                                                                                                                                                                                                                     |
+| `cwd`                        | `string`                                                                                          | `process.cwd()`            | Current working directory                                                                                                                                                                                                                                 |
+| `disallowedTools`            | `string[]`                                                                                        | `[]`                       | List of disallowed tool names                                                                                                                                                                                                                             |
+| `env`                        | `Dict<string>`                                                                                    | `process.env`              | Environment variables                                                                                                                                                                                                                                     |
+| `executable`                 | `'bun' \| 'deno' \| 'node'`                                                                       | Auto-detected              | JavaScript runtime to use                                                                                                                                                                                                                                 |
+| `executableArgs`             | `string[]`                                                                                        | `[]`                       | Arguments to pass to the executable                                                                                                                                                                                                                       |
+| `extraArgs`                  | `Record<string, string \| null>`                                                                  | `{}`                       | Additional arguments                                                                                                                                                                                                                                      |
+| `fallbackModel`              | `string`                                                                                          | `undefined`                | Model to use if primary fails                                                                                                                                                                                                                             |
+| `forkSession`                | `boolean`                                                                                         | `false`                    | When resuming with `resume`, fork to a new session ID instead of continuing the original session                                                                                                                                                          |
+| `hooks`                      | `Partial<Record<`[`HookEvent`](#hookevent)`, `[`HookCallbackMatcher`](#hookcallbackmatcher)`[]>>` | `{}`                       | Hook callbacks for events                                                                                                                                                                                                                                 |
+| `includePartialMessages`     | `boolean`                                                                                         | `false`                    | Include partial message events                                                                                                                                                                                                                            |
+| `maxThinkingTokens`          | `number`                                                                                          | `undefined`                | Maximum tokens for thinking process                                                                                                                                                                                                                       |
+| `maxTurns`                   | `number`                                                                                          | `undefined`                | Maximum conversation turns                                                                                                                                                                                                                                |
+| `mcpServers`                 | `Record<string, [`McpServerConfig`](#mcpserverconfig)>`                                           | `{}`                       | MCP server configurations                                                                                                                                                                                                                                 |
+| `model`                      | `string`                                                                                          | Default from CLI           | Claude model to use                                                                                                                                                                                                                                       |
+| `pathToClaudeCodeExecutable` | `string`                                                                                          | Auto-detected              | Path to Claude Code executable                                                                                                                                                                                                                            |
+| `permissionMode`             | [`PermissionMode`](#permissionmode)                                                               | `'default'`                | Permission mode for the session                                                                                                                                                                                                                           |
+| `permissionPromptToolName`   | `string`                                                                                          | `undefined`                | MCP tool name for permission prompts                                                                                                                                                                                                                      |
+| `plugins`                    | [`SdkPluginConfig`](#sdkpluginconfig)`[]`                                                         | `[]`                       | Load custom plugins from local paths. See [Plugins](/en/docs/agent-sdk/plugins) for details                                                                                                                                                               |
+| `resume`                     | `string`                                                                                          | `undefined`                | Session ID to resume                                                                                                                                                                                                                                      |
+| `settingSources`             | [`SettingSource`](#settingsource)`[]`                                                             | `[]` (no settings)         | Control which filesystem settings to load. When omitted, no settings are loaded. **Note:** Must include `'project'` to load CLAUDE.md files                                                                                                               |
+| `stderr`                     | `(data: string) => void`                                                                          | `undefined`                | Callback for stderr output                                                                                                                                                                                                                                |
+| `strictMcpConfig`            | `boolean`                                                                                         | `false`                    | Enforce strict MCP validation                                                                                                                                                                                                                             |
+| `systemPrompt`               | `string \| { type: 'preset'; preset: 'claude_code'; append?: string }`                            | `undefined` (empty prompt) | System prompt configuration. Pass a string for custom prompt, or `{ type: 'preset', preset: 'claude_code' }` to use Claude Code's system prompt. When using the preset object form, add `append` to extend the system prompt with additional instructions |
+
+### `Query`
+
+Interface returned by the `query()` function.
+
+```ts  theme={null}
+interface Query extends AsyncGenerator<SDKMessage, void> {
+  interrupt(): Promise<void>;
+  setPermissionMode(mode: PermissionMode): Promise<void>;
+}
+```
+
+#### Methods
+
+| Method                | Description                                                          |
+| :-------------------- | :------------------------------------------------------------------- |
+| `interrupt()`         | Interrupts the query (only available in streaming input mode)        |
+| `setPermissionMode()` | Changes the permission mode (only available in streaming input mode) |
+
+### `AgentDefinition`
+
+Configuration for a subagent defined programmatically.
+
+```ts  theme={null}
+type AgentDefinition = {
+  description: string;
+  tools?: string[];
+  prompt: string;
+  model?: 'sonnet' | 'opus' | 'haiku' | 'inherit';
+}
+```
+
+| Field         | Required | Description                                                    |
+| :------------ | :------- | :------------------------------------------------------------- |
+| `description` | Yes      | Natural language description of when to use this agent         |
+| `tools`       | No       | Array of allowed tool names. If omitted, inherits all tools    |
+| `prompt`      | Yes      | The agent's system prompt                                      |
+| `model`       | No       | Model override for this agent. If omitted, uses the main model |
+
+### `SettingSource`
+
+Controls which filesystem-based configuration sources the SDK loads settings from.
+
+```ts  theme={null}
+type SettingSource = 'user' | 'project' | 'local';
+```
+
+| Value       | Description                                  | Location                      |
+| :---------- | :------------------------------------------- | :---------------------------- |
+| `'user'`    | Global user settings                         | `~/.claude/settings.json`     |
+| `'project'` | Shared project settings (version controlled) | `.claude/settings.json`       |
+| `'local'`   | Local project settings (gitignored)          | `.claude/settings.local.json` |
+
+#### Default behavior
+
+When `settingSources` is **omitted** or **undefined**, the SDK does **not** load any filesystem settings. This provides isolation for SDK applications.
+
+#### Why use settingSources?
+
+**Load all filesystem settings (legacy behavior):**
+
+```typescript  theme={null}
+// Load all settings like SDK v0.0.x did
+const result = query({
+  prompt: "Analyze this code",
+  options: {
+    settingSources: ['user', 'project', 'local']  // Load all settings
+  }
+});
+```
+
+**Load only specific setting sources:**
+
+```typescript  theme={null}
+// Load only project settings, ignore user and local
+const result = query({
+  prompt: "Run CI checks",
+  options: {
+    settingSources: ['project']  // Only .claude/settings.json
+  }
+});
+```
+
+**Testing and CI environments:**
+
+```typescript  theme={null}
+// Ensure consistent behavior in CI by excluding local settings
+const result = query({
+  prompt: "Run tests",
+  options: {
+    settingSources: ['project'],  // Only team-shared settings
+    permissionMode: 'bypassPermissions'
+  }
+});
+```
+
+**SDK-only applications:**
+
+```typescript  theme={null}
+// Define everything programmatically (default behavior)
+// No filesystem dependencies - settingSources defaults to []
+const result = query({
+  prompt: "Review this PR",
+  options: {
+    // settingSources: [] is the default, no need to specify
+    agents: { /* ... */ },
+    mcpServers: { /* ... */ },
+    allowedTools: ['Read', 'Grep', 'Glob']
+  }
+});
+```
+
+**Loading CLAUDE.md project instructions:**
+
+```typescript  theme={null}
+// Load project settings to include CLAUDE.md files
+const result = query({
+  prompt: "Add a new feature following project conventions",
+  options: {
+    systemPrompt: {
+      type: 'preset',
+      preset: 'claude_code'  // Required to use CLAUDE.md
+    },
+    settingSources: ['project'],  // Loads CLAUDE.md from project directory
+    allowedTools: ['Read', 'Write', 'Edit']
+  }
+});
+```
+
+#### Settings precedence
+
+When multiple sources are loaded, settings are merged with this precedence (highest to lowest):
+
+1. Local settings (`.claude/settings.local.json`)
+2. Project settings (`.claude/settings.json`)
+3. User settings (`~/.claude/settings.json`)
+
+Programmatic options (like `agents`, `allowedTools`) always override filesystem settings.
+
+### `PermissionMode`
+
+```ts  theme={null}
+type PermissionMode =
+  | 'default'           // Standard permission behavior
+  | 'acceptEdits'       // Auto-accept file edits
+  | 'bypassPermissions' // Bypass all permission checks
+  | 'plan'              // Planning mode - no execution
+```
+
+### `CanUseTool`
+
+Custom permission function type for controlling tool usage.
+
+```ts  theme={null}
+type CanUseTool = (
+  toolName: string,
+  input: ToolInput,
+  options: {
+    signal: AbortSignal;
+    suggestions?: PermissionUpdate[];
+  }
+) => Promise<PermissionResult>;
+```
+
+### `PermissionResult`
+
+Result of a permission check.
+
+```ts  theme={null}
+type PermissionResult = 
+  | {
+      behavior: 'allow';
+      updatedInput: ToolInput;
+      updatedPermissions?: PermissionUpdate[];
+    }
+  | {
+      behavior: 'deny';
+      message: string;
+      interrupt?: boolean;
+    }
+```
+
+### `McpServerConfig`
+
+Configuration for MCP servers.
+
+```ts  theme={null}
+type McpServerConfig = 
+  | McpStdioServerConfig
+  | McpSSEServerConfig
+  | McpHttpServerConfig
+  | McpSdkServerConfigWithInstance;
+```
+
+#### `McpStdioServerConfig`
+
+```ts  theme={null}
+type McpStdioServerConfig = {
+  type?: 'stdio';
+  command: string;
+  args?: string[];
+  env?: Record<string, string>;
+}
+```
+
+#### `McpSSEServerConfig`
+
+```ts  theme={null}
+type McpSSEServerConfig = {
+  type: 'sse';
+  url: string;
+  headers?: Record<string, string>;
+}
+```
+
+#### `McpHttpServerConfig`
+
+```ts  theme={null}
+type McpHttpServerConfig = {
+  type: 'http';
+  url: string;
+  headers?: Record<string, string>;
+}
+```
+
+#### `McpSdkServerConfigWithInstance`
+
+```ts  theme={null}
+type McpSdkServerConfigWithInstance = {
+  type: 'sdk';
+  name: string;
+  instance: McpServer;
+}
+```
+
+### `SdkPluginConfig`
+
+Configuration for loading plugins in the SDK.
+
+```ts  theme={null}
+type SdkPluginConfig = {
+  type: 'local';
+  path: string;
+}
+```
+
+| Field  | Type      | Description                                                |
+| :----- | :-------- | :--------------------------------------------------------- |
+| `type` | `'local'` | Must be `'local'` (only local plugins currently supported) |
+| `path` | `string`  | Absolute or relative path to the plugin directory          |
+
+**Example:**
+
+```ts  theme={null}
+plugins: [
+  { type: 'local', path: './my-plugin' },
+  { type: 'local', path: '/absolute/path/to/plugin' }
+]
+```
+
+For complete information on creating and using plugins, see [Plugins](/en/docs/agent-sdk/plugins).
+
+## Message Types
+
+### `SDKMessage`
+
+Union type of all possible messages returned by the query.
+
+```ts  theme={null}
+type SDKMessage = 
+  | SDKAssistantMessage
+  | SDKUserMessage
+  | SDKUserMessageReplay
+  | SDKResultMessage
+  | SDKSystemMessage
+  | SDKPartialAssistantMessage
+  | SDKCompactBoundaryMessage;
+```
+
+### `SDKAssistantMessage`
+
+Assistant response message.
+
+```ts  theme={null}
+type SDKAssistantMessage = {
+  type: 'assistant';
+  uuid: UUID;
+  session_id: string;
+  message: APIAssistantMessage; // From Anthropic SDK
+  parent_tool_use_id: string | null;
+}
+```
+
+### `SDKUserMessage`
+
+User input message.
+
+```ts  theme={null}
+type SDKUserMessage = {
+  type: 'user';
+  uuid?: UUID;
+  session_id: string;
+  message: APIUserMessage; // From Anthropic SDK
+  parent_tool_use_id: string | null;
+}
+```
+
+### `SDKUserMessageReplay`
+
+Replayed user message with required UUID.
+
+```ts  theme={null}
+type SDKUserMessageReplay = {
+  type: 'user';
+  uuid: UUID;
+  session_id: string;
+  message: APIUserMessage;
+  parent_tool_use_id: string | null;
+}
+```
+
+### `SDKResultMessage`
+
+Final result message.
+
+```ts  theme={null}
+type SDKResultMessage = 
+  | {
+      type: 'result';
+      subtype: 'success';
+      uuid: UUID;
+      session_id: string;
+      duration_ms: number;
+      duration_api_ms: number;
+      is_error: boolean;
+      num_turns: number;
+      result: string;
+      total_cost_usd: number;
+      usage: NonNullableUsage;
+      permission_denials: SDKPermissionDenial[];
+    }
+  | {
+      type: 'result';
+      subtype: 'error_max_turns' | 'error_during_execution';
+      uuid: UUID;
+      session_id: string;
+      duration_ms: number;
+      duration_api_ms: number;
+      is_error: boolean;
+      num_turns: number;
+      total_cost_usd: number;
+      usage: NonNullableUsage;
+      permission_denials: SDKPermissionDenial[];
+    }
+```
+
+### `SDKSystemMessage`
+
+System initialization message.
+
+```ts  theme={null}
+type SDKSystemMessage = {
+  type: 'system';
+  subtype: 'init';
+  uuid: UUID;
+  session_id: string;
+  apiKeySource: ApiKeySource;
+  cwd: string;
+  tools: string[];
+  mcp_servers: {
+    name: string;
+    status: string;
+  }[];
+  model: string;
+  permissionMode: PermissionMode;
+  slash_commands: string[];
+  output_style: string;
+}
+```
+
+### `SDKPartialAssistantMessage`
+
+Streaming partial message (only when `includePartialMessages` is true).
+
+```ts  theme={null}
+type SDKPartialAssistantMessage = {
+  type: 'stream_event';
+  event: RawMessageStreamEvent; // From Anthropic SDK
+  parent_tool_use_id: string | null;
+  uuid: UUID;
+  session_id: string;
+}
+```
+
+### `SDKCompactBoundaryMessage`
+
+Message indicating a conversation compaction boundary.
+
+```ts  theme={null}
+type SDKCompactBoundaryMessage = {
+  type: 'system';
+  subtype: 'compact_boundary';
+  uuid: UUID;
+  session_id: string;
+  compact_metadata: {
+    trigger: 'manual' | 'auto';
+    pre_tokens: number;
+  };
+}
+```
+
+### `SDKPermissionDenial`
+
+Information about a denied tool use.
+
+```ts  theme={null}
+type SDKPermissionDenial = {
+  tool_name: string;
+  tool_use_id: string;
+  tool_input: ToolInput;
+}
+```
+
+## Hook Types
+
+### `HookEvent`
+
+Available hook events.
+
+```ts  theme={null}
+type HookEvent = 
+  | 'PreToolUse'
+  | 'PostToolUse'
+  | 'Notification'
+  | 'UserPromptSubmit'
+  | 'SessionStart'
+  | 'SessionEnd'
+  | 'Stop'
+  | 'SubagentStop'
+  | 'PreCompact';
+```
+
+### `HookCallback`
+
+Hook callback function type.
+
+```ts  theme={null}
+type HookCallback = (
+  input: HookInput, // Union of all hook input types
+  toolUseID: string | undefined,
+  options: { signal: AbortSignal }
+) => Promise<HookJSONOutput>;
+```
+
+### `HookCallbackMatcher`
+
+Hook configuration with optional matcher.
+
+```ts  theme={null}
+interface HookCallbackMatcher {
+  matcher?: string;
+  hooks: HookCallback[];
+}
+```
+
+### `HookInput`
+
+Union type of all hook input types.
+
+```ts  theme={null}
+type HookInput = 
+  | PreToolUseHookInput
+  | PostToolUseHookInput
+  | NotificationHookInput
+  | UserPromptSubmitHookInput
+  | SessionStartHookInput
+  | SessionEndHookInput
+  | StopHookInput
+  | SubagentStopHookInput
+  | PreCompactHookInput;
+```
+
+### `BaseHookInput`
+
+Base interface that all hook input types extend.
+
+```ts  theme={null}
+type BaseHookInput = {
+  session_id: string;
+  transcript_path: string;
+  cwd: string;
+  permission_mode?: string;
+}
+```
+
+#### `PreToolUseHookInput`
+
+```ts  theme={null}
+type PreToolUseHookInput = BaseHookInput & {
+  hook_event_name: 'PreToolUse';
+  tool_name: string;
+  tool_input: ToolInput;
+}
+```
+
+#### `PostToolUseHookInput`
+
+```ts  theme={null}
+type PostToolUseHookInput = BaseHookInput & {
+  hook_event_name: 'PostToolUse';
+  tool_name: string;
+  tool_input: ToolInput;
+  tool_response: ToolOutput;
+}
+```
+
+#### `NotificationHookInput`
+
+```ts  theme={null}
+type NotificationHookInput = BaseHookInput & {
+  hook_event_name: 'Notification';
+  message: string;
+  title?: string;
+}
+```
+
+#### `UserPromptSubmitHookInput`
+
+```ts  theme={null}
+type UserPromptSubmitHookInput = BaseHookInput & {
+  hook_event_name: 'UserPromptSubmit';
+  prompt: string;
+}
+```
+
+#### `SessionStartHookInput`
+
+```ts  theme={null}
+type SessionStartHookInput = BaseHookInput & {
+  hook_event_name: 'SessionStart';
+  source: 'startup' | 'resume' | 'clear' | 'compact';
+}
+```
+
+#### `SessionEndHookInput`
+
+```ts  theme={null}
+type SessionEndHookInput = BaseHookInput & {
+  hook_event_name: 'SessionEnd';
+  reason: 'clear' | 'logout' | 'prompt_input_exit' | 'other';
+}
+```
+
+#### `StopHookInput`
+
+```ts  theme={null}
+type StopHookInput = BaseHookInput & {
+  hook_event_name: 'Stop';
+  stop_hook_active: boolean;
+}
+```
+
+#### `SubagentStopHookInput`
+
+```ts  theme={null}
+type SubagentStopHookInput = BaseHookInput & {
+  hook_event_name: 'SubagentStop';
+  stop_hook_active: boolean;
+}
+```
+
+#### `PreCompactHookInput`
+
+```ts  theme={null}
+type PreCompactHookInput = BaseHookInput & {
+  hook_event_name: 'PreCompact';
+  trigger: 'manual' | 'auto';
+  custom_instructions: string | null;
+}
+```
+
+### `HookJSONOutput`
+
+Hook return value.
+
+```ts  theme={null}
+type HookJSONOutput = AsyncHookJSONOutput | SyncHookJSONOutput;
+```
+
+#### `AsyncHookJSONOutput`
+
+```ts  theme={null}
+type AsyncHookJSONOutput = {
+  async: true;
+  asyncTimeout?: number;
+}
+```
+
+#### `SyncHookJSONOutput`
+
+```ts  theme={null}
+type SyncHookJSONOutput = {
+  continue?: boolean;
+  suppressOutput?: boolean;
+  stopReason?: string;
+  decision?: 'approve' | 'block';
+  systemMessage?: string;
+  reason?: string;
+  hookSpecificOutput?:
+    | {
+        hookEventName: 'PreToolUse';
+        permissionDecision?: 'allow' | 'deny' | 'ask';
+        permissionDecisionReason?: string;
+      }
+    | {
+        hookEventName: 'UserPromptSubmit';
+        additionalContext?: string;
+      }
+    | {
+        hookEventName: 'SessionStart';
+        additionalContext?: string;
+      }
+    | {
+        hookEventName: 'PostToolUse';
+        additionalContext?: string;
+      };
+}
+```
+
+## Tool Input Types
+
+Documentation of input schemas for all built-in Claude Code tools. These types are exported from `@anthropic-ai/claude-agent-sdk` and can be used for type-safe tool interactions.
+
+### `ToolInput`
+
+**Note:** This is a documentation-only type for clarity. It represents the union of all tool input types.
+
+```ts  theme={null}
+type ToolInput = 
+  | AgentInput
+  | BashInput
+  | BashOutputInput
+  | FileEditInput
+  | FileReadInput
+  | FileWriteInput
+  | GlobInput
+  | GrepInput
+  | KillShellInput
+  | NotebookEditInput
+  | WebFetchInput
+  | WebSearchInput
+  | TodoWriteInput
+  | ExitPlanModeInput
+  | ListMcpResourcesInput
+  | ReadMcpResourceInput;
+```
+
+### Task
+
+**Tool name:** `Task`
+
+```ts  theme={null}
+interface AgentInput {
+  /**
+   * A short (3-5 word) description of the task
+   */
+  description: string;
+  /**
+   * The task for the agent to perform
+   */
+  prompt: string;
+  /**
+   * The type of specialized agent to use for this task
+   */
+  subagent_type: string;
+}
+```
+
+Launches a new agent to handle complex, multi-step tasks autonomously.
+
+### Bash
+
+**Tool name:** `Bash`
+
+```ts  theme={null}
+interface BashInput {
+  /**
+   * The command to execute
+   */
+  command: string;
+  /**
+   * Optional timeout in milliseconds (max 600000)
+   */
+  timeout?: number;
+  /**
+   * Clear, concise description of what this command does in 5-10 words
+   */
+  description?: string;
+  /**
+   * Set to true to run this command in the background
+   */
+  run_in_background?: boolean;
+}
+```
+
+Executes bash commands in a persistent shell session with optional timeout and background execution.
+
+### BashOutput
+
+**Tool name:** `BashOutput`
+
+```ts  theme={null}
+interface BashOutputInput {
+  /**
+   * The ID of the background shell to retrieve output from
+   */
+  bash_id: string;
+  /**
+   * Optional regex to filter output lines
+   */
+  filter?: string;
+}
+```
+
+Retrieves output from a running or completed background bash shell.
+
+### Edit
+
+**Tool name:** `Edit`
+
+```ts  theme={null}
+interface FileEditInput {
+  /**
+   * The absolute path to the file to modify
+   */
+  file_path: string;
+  /**
+   * The text to replace
+   */
+  old_string: string;
+  /**
+   * The text to replace it with (must be different from old_string)
+   */
+  new_string: string;
+  /**
+   * Replace all occurrences of old_string (default false)
+   */
+  replace_all?: boolean;
+}
+```
+
+Performs exact string replacements in files.
+
+### Read
+
+**Tool name:** `Read`
+
+```ts  theme={null}
+interface FileReadInput {
+  /**
+   * The absolute path to the file to read
+   */
+  file_path: string;
+  /**
+   * The line number to start reading from
+   */
+  offset?: number;
+  /**
+   * The number of lines to read
+   */
+  limit?: number;
+}
+```
+
+Reads files from the local filesystem, including text, images, PDFs, and Jupyter notebooks.
+
+### Write
+
+**Tool name:** `Write`
+
+```ts  theme={null}
+interface FileWriteInput {
+  /**
+   * The absolute path to the file to write
+   */
+  file_path: string;
+  /**
+   * The content to write to the file
+   */
+  content: string;
+}
+```
+
+Writes a file to the local filesystem, overwriting if it exists.
+
+### Glob
+
+**Tool name:** `Glob`
+
+```ts  theme={null}
+interface GlobInput {
+  /**
+   * The glob pattern to match files against
+   */
+  pattern: string;
+  /**
+   * The directory to search in (defaults to cwd)
+   */
+  path?: string;
+}
+```
+
+Fast file pattern matching that works with any codebase size.
+
+### Grep
+
+**Tool name:** `Grep`
+
+```ts  theme={null}
+interface GrepInput {
+  /**
+   * The regular expression pattern to search for
+   */
+  pattern: string;
+  /**
+   * File or directory to search in (defaults to cwd)
+   */
+  path?: string;
+  /**
+   * Glob pattern to filter files (e.g. "*.js")
+   */
+  glob?: string;
+  /**
+   * File type to search (e.g. "js", "py", "rust")
+   */
+  type?: string;
+  /**
+   * Output mode: "content", "files_with_matches", or "count"
+   */
+  output_mode?: 'content' | 'files_with_matches' | 'count';
+  /**
+   * Case insensitive search
+   */
+  '-i'?: boolean;
+  /**
+   * Show line numbers (for content mode)
+   */
+  '-n'?: boolean;
+  /**
+   * Lines to show before each match
+   */
+  '-B'?: number;
+  /**
+   * Lines to show after each match
+   */
+  '-A'?: number;
+  /**
+   * Lines to show before and after each match
+   */
+  '-C'?: number;
+  /**
+   * Limit output to first N lines/entries
+   */
+  head_limit?: number;
+  /**
+   * Enable multiline mode
+   */
+  multiline?: boolean;
+}
+```
+
+Powerful search tool built on ripgrep with regex support.
+
+### KillBash
+
+**Tool name:** `KillBash`
+
+```ts  theme={null}
+interface KillShellInput {
+  /**
+   * The ID of the background shell to kill
+   */
+  shell_id: string;
+}
+```
+
+Kills a running background bash shell by its ID.
+
+### NotebookEdit
+
+**Tool name:** `NotebookEdit`
+
+```ts  theme={null}
+interface NotebookEditInput {
+  /**
+   * The absolute path to the Jupyter notebook file
+   */
+  notebook_path: string;
+  /**
+   * The ID of the cell to edit
+   */
+  cell_id?: string;
+  /**
+   * The new source for the cell
+   */
+  new_source: string;
+  /**
+   * The type of the cell (code or markdown)
+   */
+  cell_type?: 'code' | 'markdown';
+  /**
+   * The type of edit (replace, insert, delete)
+   */
+  edit_mode?: 'replace' | 'insert' | 'delete';
+}
+```
+
+Edits cells in Jupyter notebook files.
+
+### WebFetch
+
+**Tool name:** `WebFetch`
+
+```ts  theme={null}
+interface WebFetchInput {
+  /**
+   * The URL to fetch content from
+   */
+  url: string;
+  /**
+   * The prompt to run on the fetched content
+   */
+  prompt: string;
+}
+```
+
+Fetches content from a URL and processes it with an AI model.
+
+### WebSearch
+
+**Tool name:** `WebSearch`
+
+```ts  theme={null}
+interface WebSearchInput {
+  /**
+   * The search query to use
+   */
+  query: string;
+  /**
+   * Only include results from these domains
+   */
+  allowed_domains?: string[];
+  /**
+   * Never include results from these domains
+   */
+  blocked_domains?: string[];
+}
+```
+
+Searches the web and returns formatted results.
+
+### TodoWrite
+
+**Tool name:** `TodoWrite`
+
+```ts  theme={null}
+interface TodoWriteInput {
+  /**
+   * The updated todo list
+   */
+  todos: Array<{
+    /**
+     * The task description
+     */
+    content: string;
+    /**
+     * The task status
+     */
+    status: 'pending' | 'in_progress' | 'completed';
+    /**
+     * Active form of the task description
+     */
+    activeForm: string;
+  }>;
+}
+```
+
+Creates and manages a structured task list for tracking progress.
+
+### ExitPlanMode
+
+**Tool name:** `ExitPlanMode`
+
+```ts  theme={null}
+interface ExitPlanModeInput {
+  /**
+   * The plan to run by the user for approval
+   */
+  plan: string;
+}
+```
+
+Exits planning mode and prompts the user to approve the plan.
+
+### ListMcpResources
+
+**Tool name:** `ListMcpResources`
+
+```ts  theme={null}
+interface ListMcpResourcesInput {
+  /**
+   * Optional server name to filter resources by
+   */
+  server?: string;
+}
+```
+
+Lists available MCP resources from connected servers.
+
+### ReadMcpResource
+
+**Tool name:** `ReadMcpResource`
+
+```ts  theme={null}
+interface ReadMcpResourceInput {
+  /**
+   * The MCP server name
+   */
+  server: string;
+  /**
+   * The resource URI to read
+   */
+  uri: string;
+}
+```
+
+Reads a specific MCP resource from a server.
+
+## Tool Output Types
+
+Documentation of output schemas for all built-in Claude Code tools. These types represent the actual response data returned by each tool.
+
+### `ToolOutput`
+
+**Note:** This is a documentation-only type for clarity. It represents the union of all tool output types.
+
+```ts  theme={null}
+type ToolOutput = 
+  | TaskOutput
+  | BashOutput
+  | BashOutputToolOutput
+  | EditOutput
+  | ReadOutput
+  | WriteOutput
+  | GlobOutput
+  | GrepOutput
+  | KillBashOutput
+  | NotebookEditOutput
+  | WebFetchOutput
+  | WebSearchOutput
+  | TodoWriteOutput
+  | ExitPlanModeOutput
+  | ListMcpResourcesOutput
+  | ReadMcpResourceOutput;
+```
+
+### Task
+
+**Tool name:** `Task`
+
+```ts  theme={null}
+interface TaskOutput {
+  /**
+   * Final result message from the subagent
+   */
+  result: string;
+  /**
+   * Token usage statistics
+   */
+  usage?: {
+    input_tokens: number;
+    output_tokens: number;
+    cache_creation_input_tokens?: number;
+    cache_read_input_tokens?: number;
+  };
+  /**
+   * Total cost in USD
+   */
+  total_cost_usd?: number;
+  /**
+   * Execution duration in milliseconds
+   */
+  duration_ms?: number;
+}
+```
+
+Returns the final result from the subagent after completing the delegated task.
+
+### Bash
+
+**Tool name:** `Bash`
+
+```ts  theme={null}
+interface BashOutput {
+  /**
+   * Combined stdout and stderr output
+   */
+  output: string;
+  /**
+   * Exit code of the command
+   */
+  exitCode: number;
+  /**
+   * Whether the command was killed due to timeout
+   */
+  killed?: boolean;
+  /**
+   * Shell ID for background processes
+   */
+  shellId?: string;
+}
+```
+
+Returns command output with exit status. Background commands return immediately with a shellId.
+
+### BashOutput
+
+**Tool name:** `BashOutput`
+
+```ts  theme={null}
+interface BashOutputToolOutput {
+  /**
+   * New output since last check
+   */
+  output: string;
+  /**
+   * Current shell status
+   */
+  status: 'running' | 'completed' | 'failed';
+  /**
+   * Exit code (when completed)
+   */
+  exitCode?: number;
+}
+```
+
+Returns incremental output from background shells.
+
+### Edit
+
+**Tool name:** `Edit`
+
+```ts  theme={null}
+interface EditOutput {
+  /**
+   * Confirmation message
+   */
+  message: string;
+  /**
+   * Number of replacements made
+   */
+  replacements: number;
+  /**
+   * File path that was edited
+   */
+  file_path: string;
+}
+```
+
+Returns confirmation of successful edits with replacement count.
+
+### Read
+
+**Tool name:** `Read`
+
+```ts  theme={null}
+type ReadOutput = 
+  | TextFileOutput
+  | ImageFileOutput
+  | PDFFileOutput
+  | NotebookFileOutput;
+
+interface TextFileOutput {
+  /**
+   * File contents with line numbers
+   */
+  content: string;
+  /**
+   * Total number of lines in file
+   */
+  total_lines: number;
+  /**
+   * Lines actually returned
+   */
+  lines_returned: number;
+}
+
+interface ImageFileOutput {
+  /**
+   * Base64 encoded image data
+   */
+  image: string;
+  /**
+   * Image MIME type
+   */
+  mime_type: string;
+  /**
+   * File size in bytes
+   */
+  file_size: number;
+}
+
+interface PDFFileOutput {
+  /**
+   * Array of page contents
+   */
+  pages: Array<{
+    page_number: number;
+    text?: string;
+    images?: Array<{
+      image: string;
+      mime_type: string;
+    }>;
+  }>;
+  /**
+   * Total number of pages
+   */
+  total_pages: number;
+}
+
+interface NotebookFileOutput {
+  /**
+   * Jupyter notebook cells
+   */
+  cells: Array<{
+    cell_type: 'code' | 'markdown';
+    source: string;
+    outputs?: any[];
+    execution_count?: number;
+  }>;
+  /**
+   * Notebook metadata
+   */
+  metadata?: Record<string, any>;
+}
+```
+
+Returns file contents in format appropriate to file type.
+
+### Write
+
+**Tool name:** `Write`
+
+```ts  theme={null}
+interface WriteOutput {
+  /**
+   * Success message
+   */
+  message: string;
+  /**
+   * Number of bytes written
+   */
+  bytes_written: number;
+  /**
+   * File path that was written
+   */
+  file_path: string;
+}
+```
+
+Returns confirmation after successfully writing the file.
+
+### Glob
+
+**Tool name:** `Glob`
+
+```ts  theme={null}
+interface GlobOutput {
+  /**
+   * Array of matching file paths
+   */
+  matches: string[];
+  /**
+   * Number of matches found
+   */
+  count: number;
+  /**
+   * Search directory used
+   */
+  search_path: string;
+}
+```
+
+Returns file paths matching the glob pattern, sorted by modification time.
+
+### Grep
+
+**Tool name:** `Grep`
+
+```ts  theme={null}
+type GrepOutput = 
+  | GrepContentOutput
+  | GrepFilesOutput
+  | GrepCountOutput;
+
+interface GrepContentOutput {
+  /**
+   * Matching lines with context
+   */
+  matches: Array<{
+    file: string;
+    line_number?: number;
+    line: string;
+    before_context?: string[];
+    after_context?: string[];
+  }>;
+  /**
+   * Total number of matches
+   */
+  total_matches: number;
+}
+
+interface GrepFilesOutput {
+  /**
+   * Files containing matches
+   */
+  files: string[];
+  /**
+   * Number of files with matches
+   */
+  count: number;
+}
+
+interface GrepCountOutput {
+  /**
+   * Match counts per file
+   */
+  counts: Array<{
+    file: string;
+    count: number;
+  }>;
+  /**
+   * Total matches across all files
+   */
+  total: number;
+}
+```
+
+Returns search results in the format specified by output\_mode.
+
+### KillBash
+
+**Tool name:** `KillBash`
+
+```ts  theme={null}
+interface KillBashOutput {
+  /**
+   * Success message
+   */
+  message: string;
+  /**
+   * ID of the killed shell
+   */
+  shell_id: string;
+}
+```
+
+Returns confirmation after terminating the background shell.
+
+### NotebookEdit
+
+**Tool name:** `NotebookEdit`
+
+```ts  theme={null}
+interface NotebookEditOutput {
+  /**
+   * Success message
+   */
+  message: string;
+  /**
+   * Type of edit performed
+   */
+  edit_type: 'replaced' | 'inserted' | 'deleted';
+  /**
+   * Cell ID that was affected
+   */
+  cell_id?: string;
+  /**
+   * Total cells in notebook after edit
+   */
+  total_cells: number;
+}
+```
+
+Returns confirmation after modifying the Jupyter notebook.
+
+### WebFetch
+
+**Tool name:** `WebFetch`
+
+```ts  theme={null}
+interface WebFetchOutput {
+  /**
+   * AI model's response to the prompt
+   */
+  response: string;
+  /**
+   * URL that was fetched
+   */
+  url: string;
+  /**
+   * Final URL after redirects
+   */
+  final_url?: string;
+  /**
+   * HTTP status code
+   */
+  status_code?: number;
+}
+```
+
+Returns the AI's analysis of the fetched web content.
+
+### WebSearch
+
+**Tool name:** `WebSearch`
+
+```ts  theme={null}
+interface WebSearchOutput {
+  /**
+   * Search results
+   */
+  results: Array<{
+    title: string;
+    url: string;
+    snippet: string;
+    /**
+     * Additional metadata if available
+     */
+    metadata?: Record<string, any>;
+  }>;
+  /**
+   * Total number of results
+   */
+  total_results: number;
+  /**
+   * The query that was searched
+   */
+  query: string;
+}
+```
+
+Returns formatted search results from the web.
+
+### TodoWrite
+
+**Tool name:** `TodoWrite`
+
+```ts  theme={null}
+interface TodoWriteOutput {
+  /**
+   * Success message
+   */
+  message: string;
+  /**
+   * Current todo statistics
+   */
+  stats: {
+    total: number;
+    pending: number;
+    in_progress: number;
+    completed: number;
+  };
+}
+```
+
+Returns confirmation with current task statistics.
+
+### ExitPlanMode
+
+**Tool name:** `ExitPlanMode`
+
+```ts  theme={null}
+interface ExitPlanModeOutput {
+  /**
+   * Confirmation message
+   */
+  message: string;
+  /**
+   * Whether user approved the plan
+   */
+  approved?: boolean;
+}
+```
+
+Returns confirmation after exiting plan mode.
+
+### ListMcpResources
+
+**Tool name:** `ListMcpResources`
+
+```ts  theme={null}
+interface ListMcpResourcesOutput {
+  /**
+   * Available resources
+   */
+  resources: Array<{
+    uri: string;
+    name: string;
+    description?: string;
+    mimeType?: string;
+    server: string;
+  }>;
+  /**
+   * Total number of resources
+   */
+  total: number;
+}
+```
+
+Returns list of available MCP resources.
+
+### ReadMcpResource
+
+**Tool name:** `ReadMcpResource`
+
+```ts  theme={null}
+interface ReadMcpResourceOutput {
+  /**
+   * Resource contents
+   */
+  contents: Array<{
+    uri: string;
+    mimeType?: string;
+    text?: string;
+    blob?: string;
+  }>;
+  /**
+   * Server that provided the resource
+   */
+  server: string;
+}
+```
+
+Returns the contents of the requested MCP resource.
+
+## Permission Types
+
+### `PermissionUpdate`
+
+Operations for updating permissions.
+
+```ts  theme={null}
+type PermissionUpdate = 
+  | {
+      type: 'addRules';
+      rules: PermissionRuleValue[];
+      behavior: PermissionBehavior;
+      destination: PermissionUpdateDestination;
+    }
+  | {
+      type: 'replaceRules';
+      rules: PermissionRuleValue[];
+      behavior: PermissionBehavior;
+      destination: PermissionUpdateDestination;
+    }
+  | {
+      type: 'removeRules';
+      rules: PermissionRuleValue[];
+      behavior: PermissionBehavior;
+      destination: PermissionUpdateDestination;
+    }
+  | {
+      type: 'setMode';
+      mode: PermissionMode;
+      destination: PermissionUpdateDestination;
+    }
+  | {
+      type: 'addDirectories';
+      directories: string[];
+      destination: PermissionUpdateDestination;
+    }
+  | {
+      type: 'removeDirectories';
+      directories: string[];
+      destination: PermissionUpdateDestination;
+    }
+```
+
+### `PermissionBehavior`
+
+```ts  theme={null}
+type PermissionBehavior = 'allow' | 'deny' | 'ask';
+```
+
+### `PermissionUpdateDestination`
+
+```ts  theme={null}
+type PermissionUpdateDestination = 
+  | 'userSettings'     // Global user settings
+  | 'projectSettings'  // Per-directory project settings
+  | 'localSettings'    // Gitignored local settings
+  | 'session'          // Current session only
+```
+
+### `PermissionRuleValue`
+
+```ts  theme={null}
+type PermissionRuleValue = {
+  toolName: string;
+  ruleContent?: string;
+}
+```
+
+## Other Types
+
+### `ApiKeySource`
+
+```ts  theme={null}
+type ApiKeySource = 'user' | 'project' | 'org' | 'temporary';
+```
+
+### `ConfigScope`
+
+```ts  theme={null}
+type ConfigScope = 'local' | 'user' | 'project';
+```
+
+### `NonNullableUsage`
+
+A version of [`Usage`](#usage) with all nullable fields made non-nullable.
+
+```ts  theme={null}
+type NonNullableUsage = {
+  [K in keyof Usage]: NonNullable<Usage[K]>;
+}
+```
+
+### `Usage`
+
+Token usage statistics (from `@anthropic-ai/sdk`).
+
+```ts  theme={null}
+type Usage = {
+  input_tokens: number | null;
+  output_tokens: number | null;
+  cache_creation_input_tokens?: number | null;
+  cache_read_input_tokens?: number | null;
+}
+```
+
+### `CallToolResult`
+
+MCP tool result type (from `@modelcontextprotocol/sdk/types.js`).
+
+```ts  theme={null}
+type CallToolResult = {
+  content: Array<{
+    type: 'text' | 'image' | 'resource';
+    // Additional fields vary by type
+  }>;
+  isError?: boolean;
+}
+```
+
+### `AbortError`
+
+Custom error class for abort operations.
+
+```ts  theme={null}
+class AbortError extends Error {}
+```
+
+## See also
+
+* [SDK overview](/en/docs/agent-sdk/overview) - General SDK concepts
+* [Python SDK reference](/en/docs/agent-sdk/python) - Python SDK documentation
+* [CLI reference](https://code.claude.com/docs/en/cli-reference) - Command-line interface
+* [Common workflows](https://code.claude.com/docs/en/common-workflows) - Step-by-step guides