Agent SDK リファレンス - TypeScript

インストール

npm install @anthropic-ai/claude-agent-sdk

関数

`query()`

Claude Code と対話するための主要な関数です。メッセージがストリーミングされるときに非同期ジェネレータを作成します。

function query({
  prompt,
  options
}: {
  prompt: string | AsyncIterable<SDKUserMessage>;
  options?: Options;
}): Query

パラメータ

パラメータ	型	説明
`prompt`	`string \| AsyncIterable<SDKUserMessage>`	文字列またはストリーミングモード用の非同期イテラブルとしての入力プロンプト
`options`	`Options`	オプションの設定オブジェクト（以下の Options 型を参照）

戻り値

追加のメソッドを持つ AsyncGenerator<SDKMessage, void> を拡張する Query オブジェクトを返します。

`tool()`

SDK MCP サーバーで使用するためのタイプセーフな MCP ツール定義を作成します。

function tool<Schema extends ZodRawShape>(
  name: string,
  description: string,
  inputSchema: Schema,
  handler: (args: z.infer<ZodObject<Schema>>, extra: unknown) => Promise<CallToolResult>
): SdkMcpToolDefinition<Schema>

パラメータ

パラメータ	型	説明
`name`	`string`	ツールの名前
`description`	`string`	ツールが何をするかの説明
`inputSchema`	`Schema extends ZodRawShape`	ツールの入力パラメータを定義する Zod スキーマ
`handler`	`(args, extra) => Promise<CallToolResult>`	ツールロジックを実行する非同期関数

`createSdkMcpServer()`

アプリケーションと同じプロセスで実行される MCP サーバーインスタンスを作成します。

function createSdkMcpServer(options: {
  name: string;
  version?: string;
  tools?: Array<SdkMcpToolDefinition<any>>;
}): McpSdkServerConfigWithInstance

パラメータ

パラメータ	型	説明
`options.name`	`string`	MCP サーバーの名前
`options.version`	`string`	オプションのバージョン文字列
`options.tools`	`Array<SdkMcpToolDefinition>`	`tool()` で作成されたツール定義の配列

型

`Options`

query() 関数の設定オブジェクト。

プロパティ	型	デフォルト	説明
`abortController`	`AbortController`	`new AbortController()`	操作をキャンセルするためのコントローラー
`additionalDirectories`	`string[]`	`[]`	Claude がアクセスできる追加ディレクトリ
`agents`	`Record<string, [`AgentDefinition`](#agentdefinition)>`	`undefined`	プログラムでサブエージェントを定義
`allowedTools`	`string[]`	すべてのツール	許可されたツール名のリスト
`canUseTool`	`CanUseTool`	`undefined`	ツール使用のためのカスタム権限関数
`continue`	`boolean`	`false`	最新の会話を続行
`cwd`	`string`	`process.cwd()`	現在の作業ディレクトリ
`disallowedTools`	`string[]`	`[]`	許可されていないツール名のリスト
`env`	`Dict<string>`	`process.env`	環境変数
`executable`	`'bun' \| 'deno' \| 'node'`	自動検出	使用する JavaScript ランタイム
`executableArgs`	`string[]`	`[]`	実行ファイルに渡す引数
`extraArgs`	`Record<string, string \| null>`	`{}`	追加の引数
`fallbackModel`	`string`	`undefined`	プライマリが失敗した場合に使用するモデル
`forkSession`	`boolean`	`false`	`resume` で再開するときに、元のセッションを続行する代わりに新しいセッション ID にフォークする
`hooks`	`Partial<Record<HookEvent,` `HookCallbackMatcher[]>>`	`{}`	イベント用のフックコールバック
`includePartialMessages`	`boolean`	`false`	部分的なメッセージイベントを含める
`maxThinkingTokens`	`number`	`undefined`	思考プロセスの最大トークン数
`maxTurns`	`number`	`undefined`	最大会話ターン数
`mcpServers`	`Record<string, [`McpServerConfig`](#mcpserverconfig)>`	`{}`	MCP サーバー設定
`model`	`string`	CLI からのデフォルト	使用する Claude モデル
`pathToClaudeCodeExecutable`	`string`	自動検出	Claude Code 実行ファイルへのパス
`permissionMode`	`PermissionMode`	`'default'`	セッションの権限モード
`permissionPromptToolName`	`string`	`undefined`	権限プロンプト用の MCP ツール名
`plugins`	`SdkPluginConfig[]`	`[]`	ローカルパスからカスタムプラグインを読み込みます。詳細は Plugins を参照してください
`resume`	`string`	`undefined`	再開するセッション ID
`settingSources`	`SettingSource[]`	`[]` (設定なし)	どのファイルシステム設定を読み込むかを制御します。省略された場合、設定は読み込まれません。注: CLAUDE.md ファイルを読み込むには `'project'` を含める必要があります
`stderr`	`(data: string) => void`	`undefined`	stderr 出力用のコールバック
`strictMcpConfig`	`boolean`	`false`	厳密な MCP 検証を強制
`systemPrompt`	`string \| { type: 'preset'; preset: 'claude_code'; append?: string }`	`undefined` (空のプロンプト)	システムプロンプト設定。カスタムプロンプト用に文字列を渡すか、Claude Code のシステムプロンプトを使用するために `{ type: 'preset', preset: 'claude_code' }` を渡します。プリセットオブジェクト形式を使用する場合、`append` を追加してシステムプロンプトを追加の指示で拡張します

`Query`

query() 関数によって返されるインターフェース。

interface Query extends AsyncGenerator<SDKMessage, void> {
  interrupt(): Promise<void>;
  setPermissionMode(mode: PermissionMode): Promise<void>;
}

メソッド

メソッド	説明
`interrupt()`	クエリを中断します（ストリーミング入力モードでのみ利用可能）
`setPermissionMode()`	権限モードを変更します（ストリーミング入力モードでのみ利用可能）

`AgentDefinition`

プログラムで定義されたサブエージェントの設定。

type AgentDefinition = {
  description: string;
  tools?: string[];
  prompt: string;
  model?: 'sonnet' | 'opus' | 'haiku' | 'inherit';
}

フィールド	必須	説明
`description`	はい	このエージェントを使用する時期の自然言語説明
`tools`	いいえ	許可されたツール名の配列。省略された場合、すべてのツールを継承します
`prompt`	はい	エージェントのシステムプロンプト
`model`	いいえ	このエージェントのモデルオーバーライド。省略された場合、メインモデルを使用します

`SettingSource`

SDK が設定を読み込むファイルシステムベースの設定ソースを制御します。

type SettingSource = 'user' | 'project' | 'local';

値	説明	場所
`'user'`	グローバルユーザー設定	`~/.claude/settings.json`
`'project'`	共有プロジェクト設定（バージョン管理対象）	`.claude/settings.json`
`'local'`	ローカルプロジェクト設定（gitignore対象）	`.claude/settings.local.json`

デフォルト動作

settingSources が省略または undefined の場合、SDK はファイルシステム設定を読み込み ません。これにより SDK アプリケーションの分離が提供されます。

settingSources を使用する理由

すべてのファイルシステム設定を読み込む（レガシー動作）:

// SDK v0.0.x のようにすべての設定を読み込む
const result = query({
  prompt: "Analyze this code",
  options: {
    settingSources: ['user', 'project', 'local']  // すべての設定を読み込む
  }
});

特定の設定ソースのみを読み込む:

// プロジェクト設定のみを読み込み、ユーザーとローカルを無視
const result = query({
  prompt: "Run CI checks",
  options: {
    settingSources: ['project']  // .claude/settings.json のみ
  }
});

テストと CI 環境:

// ローカル設定を除外して CI で一貫した動作を確保
const result = query({
  prompt: "Run tests",
  options: {
    settingSources: ['project'],  // チーム共有設定のみ
    permissionMode: 'bypassPermissions'
  }
});

SDK のみのアプリケーション:

// すべてをプログラムで定義（デフォルト動作）
// ファイルシステムの依存関係なし - settingSources はデフォルトで []
const result = query({
  prompt: "Review this PR",
  options: {
    // settingSources: [] がデフォルトなので指定する必要はありません
    agents: { /* ... */ },
    mcpServers: { /* ... */ },
    allowedTools: ['Read', 'Grep', 'Glob']
  }
});

CLAUDE.md プロジェクト指示を読み込む:

// プロジェクト設定を読み込んで CLAUDE.md ファイルを含める
const result = query({
  prompt: "Add a new feature following project conventions",
  options: {
    systemPrompt: {
      type: 'preset',
      preset: 'claude_code'  // CLAUDE.md を使用するために必須
    },
    settingSources: ['project'],  // プロジェクトディレクトリから CLAUDE.md を読み込む
    allowedTools: ['Read', 'Write', 'Edit']
  }
});

設定の優先順位

複数のソースが読み込まれる場合、設定は次の優先順位（高から低）でマージされます：

ローカル設定（.claude/settings.local.json）
プロジェクト設定（.claude/settings.json）
ユーザー設定（~/.claude/settings.json）

プログラムオプション（agents、allowedTools など）は常にファイルシステム設定をオーバーライドします。

`PermissionMode`

type PermissionMode =
  | 'default'           // 標準的な権限動作
  | 'acceptEdits'       // ファイル編集を自動受け入れ
  | 'bypassPermissions' // すべての権限チェックをバイパス
  | 'plan'              // 計画モード - 実行なし

`CanUseTool`

ツール使用を制御するためのカスタム権限関数型。

type CanUseTool = (
  toolName: string,
  input: ToolInput,
  options: {
    signal: AbortSignal;
    suggestions?: PermissionUpdate[];
  }
) => Promise<PermissionResult>;

`PermissionResult`

権限チェックの結果。

type PermissionResult = 
  | {
      behavior: 'allow';
      updatedInput: ToolInput;
      updatedPermissions?: PermissionUpdate[];
    }
  | {
      behavior: 'deny';
      message: string;
      interrupt?: boolean;
    }

`McpServerConfig`

MCP サーバーの設定。

type McpServerConfig = 
  | McpStdioServerConfig
  | McpSSEServerConfig
  | McpHttpServerConfig
  | McpSdkServerConfigWithInstance;

`McpStdioServerConfig`

type McpStdioServerConfig = {
  type?: 'stdio';
  command: string;
  args?: string[];
  env?: Record<string, string>;
}

`McpSSEServerConfig`

type McpSSEServerConfig = {
  type: 'sse';
  url: string;
  headers?: Record<string, string>;
}

`McpHttpServerConfig`

type McpHttpServerConfig = {
  type: 'http';
  url: string;
  headers?: Record<string, string>;
}

`McpSdkServerConfigWithInstance`

type McpSdkServerConfigWithInstance = {
  type: 'sdk';
  name: string;
  instance: McpServer;
}

`SdkPluginConfig`

SDK でプラグインを読み込むための設定。

type SdkPluginConfig = {
  type: 'local';
  path: string;
}

フィールド	型	説明
`type`	`'local'`	`'local'` である必要があります（現在ローカルプラグインのみサポート）
`path`	`string`	プラグインディレクトリへの絶対パスまたは相対パス

例:

plugins: [
  { type: 'local', path: './my-plugin' },
  { type: 'local', path: '/absolute/path/to/plugin' }
]

プラグインの作成と使用に関する完全な情報については、Plugins を参照してください。

メッセージ型

`SDKMessage`

クエリによって返されるすべての可能なメッセージの共用体型。

type SDKMessage = 
  | SDKAssistantMessage
  | SDKUserMessage
  | SDKUserMessageReplay
  | SDKResultMessage
  | SDKSystemMessage
  | SDKPartialAssistantMessage
  | SDKCompactBoundaryMessage;

`SDKAssistantMessage`

アシスタント応答メッセージ。

type SDKAssistantMessage = {
  type: 'assistant';
  uuid: UUID;
  session_id: string;
  message: APIAssistantMessage; // Anthropic SDK から
  parent_tool_use_id: string | null;
}

`SDKUserMessage`

ユーザー入力メッセージ。

type SDKUserMessage = {
  type: 'user';
  uuid?: UUID;
  session_id: string;
  message: APIUserMessage; // Anthropic SDK から
  parent_tool_use_id: string | null;
}

`SDKUserMessageReplay`

必須の UUID を持つ再生されたユーザーメッセージ。

type SDKUserMessageReplay = {
  type: 'user';
  uuid: UUID;
  session_id: string;
  message: APIUserMessage;
  parent_tool_use_id: string | null;
}

`SDKResultMessage`

最終結果メッセージ。

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`

システム初期化メッセージ。

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`

ストリーミング部分メッセージ（includePartialMessages が true の場合のみ）。

type SDKPartialAssistantMessage = {
  type: 'stream_event';
  event: RawMessageStreamEvent; // Anthropic SDK から
  parent_tool_use_id: string | null;
  uuid: UUID;
  session_id: string;
}

`SDKCompactBoundaryMessage`

会話圧縮境界を示すメッセージ。

type SDKCompactBoundaryMessage = {
  type: 'system';
  subtype: 'compact_boundary';
  uuid: UUID;
  session_id: string;
  compact_metadata: {
    trigger: 'manual' | 'auto';
    pre_tokens: number;
  };
}

`SDKPermissionDenial`

拒否されたツール使用に関する情報。

type SDKPermissionDenial = {
  tool_name: string;
  tool_use_id: string;
  tool_input: ToolInput;
}

フック型

`HookEvent`

利用可能なフックイベント。

type HookEvent = 
  | 'PreToolUse'
  | 'PostToolUse'
  | 'Notification'
  | 'UserPromptSubmit'
  | 'SessionStart'
  | 'SessionEnd'
  | 'Stop'
  | 'SubagentStop'
  | 'PreCompact';

`HookCallback`

フックコールバック関数型。

type HookCallback = (
  input: HookInput, // すべてのフック入力型の共用体
  toolUseID: string | undefined,
  options: { signal: AbortSignal }
) => Promise<HookJSONOutput>;

`HookCallbackMatcher`

オプションのマッチャーを持つフック設定。

interface HookCallbackMatcher {
  matcher?: string;
  hooks: HookCallback[];
}

`HookInput`

すべてのフック入力型の共用体型。

type HookInput = 
  | PreToolUseHookInput
  | PostToolUseHookInput
  | NotificationHookInput
  | UserPromptSubmitHookInput
  | SessionStartHookInput
  | SessionEndHookInput
  | StopHookInput
  | SubagentStopHookInput
  | PreCompactHookInput;

`BaseHookInput`

すべてのフック入力型が拡張する基本インターフェース。

type BaseHookInput = {
  session_id: string;
  transcript_path: string;
  cwd: string;
  permission_mode?: string;
}

`PreToolUseHookInput`

type PreToolUseHookInput = BaseHookInput & {
  hook_event_name: 'PreToolUse';
  tool_name: string;
  tool_input: ToolInput;
}

`PostToolUseHookInput`

type PostToolUseHookInput = BaseHookInput & {
  hook_event_name: 'PostToolUse';
  tool_name: string;
  tool_input: ToolInput;
  tool_response: ToolOutput;
}

`NotificationHookInput`

type NotificationHookInput = BaseHookInput & {
  hook_event_name: 'Notification';
  message: string;
  title?: string;
}

`UserPromptSubmitHookInput`

type UserPromptSubmitHookInput = BaseHookInput & {
  hook_event_name: 'UserPromptSubmit';
  prompt: string;
}

`SessionStartHookInput`

type SessionStartHookInput = BaseHookInput & {
  hook_event_name: 'SessionStart';
  source: 'startup' | 'resume' | 'clear' | 'compact';
}

`SessionEndHookInput`

type SessionEndHookInput = BaseHookInput & {
  hook_event_name: 'SessionEnd';
  reason: 'clear' | 'logout' | 'prompt_input_exit' | 'other';
}

`StopHookInput`

type StopHookInput = BaseHookInput & {
  hook_event_name: 'Stop';
  stop_hook_active: boolean;
}

`SubagentStopHookInput`

type SubagentStopHookInput = BaseHookInput & {
  hook_event_name: 'SubagentStop';
  stop_hook_active: boolean;
}

`PreCompactHookInput`

type PreCompactHookInput = BaseHookInput & {
  hook_event_name: 'PreCompact';
  trigger: 'manual' | 'auto';
  custom_instructions: string | null;
}

`HookJSONOutput`

フック戻り値。

type HookJSONOutput = AsyncHookJSONOutput | SyncHookJSONOutput;

`AsyncHookJSONOutput`

type AsyncHookJSONOutput = {
  async: true;
  asyncTimeout?: number;
}

`SyncHookJSONOutput`

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;
      };
}

ツール入力型

すべての組み込み Claude Code ツールの入力スキーマのドキュメント。これらの型は @anthropic-ai/claude-agent-sdk からエクスポートされ、タイプセーフなツール相互作用に使用できます。

`ToolInput`

注: これはわかりやすくするためのドキュメント専用型です。すべてのツール入力型の共用体を表します。

type ToolInput = 
  | AgentInput
  | BashInput
  | BashOutputInput
  | FileEditInput
  | FileReadInput
  | FileWriteInput
  | GlobInput
  | GrepInput
  | KillShellInput
  | NotebookEditInput
  | WebFetchInput
  | WebSearchInput
  | TodoWriteInput
  | ExitPlanModeInput
  | ListMcpResourcesInput
  | ReadMcpResourceInput;

Task

ツール名: Task

interface AgentInput {
  /**
   * タスクの短い説明（3～5語）
   */
  description: string;
  /**
   * エージェントが実行するタスク
   */
  prompt: string;
  /**
   * このタスクに使用する特殊なエージェントのタイプ
   */
  subagent_type: string;
}

複雑なマルチステップタスクを自律的に処理するための新しいエージェントを起動します。

Bash

ツール名: Bash

interface BashInput {
  /**
   * 実行するコマンド
   */
  command: string;
  /**
   * オプションのタイムアウト（ミリ秒単位、最大 600000）
   */
  timeout?: number;
  /**
   * このコマンドが何をするかの明確で簡潔な説明（5～10語）
   */
  description?: string;
  /**
   * このコマンドをバックグラウンドで実行する場合は true に設定
   */
  run_in_background?: boolean;
}

オプションのタイムアウトとバックグラウンド実行を備えた永続的なシェルセッションで bash コマンドを実行します。

BashOutput

ツール名: BashOutput

interface BashOutputInput {
  /**
   * 出力を取得するバックグラウンドシェルの ID
   */
  bash_id: string;
  /**
   * 出力行をフィルタリングするオプションの正規表現
   */
  filter?: string;
}

実行中または完了したバックグラウンド bash シェルから出力を取得します。

Edit

ツール名: Edit

interface FileEditInput {
  /**
   * 変更するファイルの絶対パス
   */
  file_path: string;
  /**
   * 置き換えるテキスト
   */
  old_string: string;
  /**
   * 置き換えるテキスト（old_string と異なる必要があります）
   */
  new_string: string;
  /**
   * old_string のすべての出現を置き換える（デフォルト false）
   */
  replace_all?: boolean;
}

ファイル内で正確な文字列置換を実行します。

Read

ツール名: Read

interface FileReadInput {
  /**
   * 読み込むファイルの絶対パス
   */
  file_path: string;
  /**
   * 読み込みを開始する行番号
   */
  offset?: number;
  /**
   * 読み込む行数
   */
  limit?: number;
}

テキスト、画像、PDF、Jupyter ノートブックを含むローカルファイルシステムからファイルを読み込みます。

Write

ツール名: Write

interface FileWriteInput {
  /**
   * 書き込むファイルの絶対パス
   */
  file_path: string;
  /**
   * ファイルに書き込むコンテンツ
   */
  content: string;
}

ローカルファイルシステムにファイルを書き込み、存在する場合は上書きします。

Glob

ツール名: Glob

interface GlobInput {
  /**
   * ファイルと照合するグロブパターン
   */
  pattern: string;
  /**
   * 検索するディレクトリ（デフォルトは cwd）
   */
  path?: string;
}

任意のコードベースサイズで機能する高速ファイルパターンマッチング。

Grep

ツール名: Grep

interface GrepInput {
  /**
   * 検索する正規表現パターン
   */
  pattern: string;
  /**
   * 検索するファイルまたはディレクトリ（デフォルトは cwd）
   */
  path?: string;
  /**
   * ファイルをフィルタリングするグロブパターン（例："*.js"）
   */
  glob?: string;
  /**
   * 検索するファイルタイプ（例："js"、"py"、"rust"）
   */
  type?: string;
  /**
   * 出力モード："content"、"files_with_matches"、または "count"
   */
  output_mode?: 'content' | 'files_with_matches' | 'count';
  /**
   * 大文字と小文字を区別しない検索
   */
  '-i'?: boolean;
  /**
   * 行番号を表示（コンテンツモード用）
   */
  '-n'?: boolean;
  /**
   * 各マッチの前に表示する行数
   */
  '-B'?: number;
  /**
   * 各マッチの後に表示する行数
   */
  '-A'?: number;
  /**
   * 各マッチの前後に表示する行数
   */
  '-C'?: number;
  /**
   * 出力を最初の N 行/エントリに制限
   */
  head_limit?: number;
  /**
   * マルチラインモードを有効化
   */
  multiline?: boolean;
}

正規表現サポート付き ripgrep 上に構築された強力な検索ツール。

KillBash

ツール名: KillBash

interface KillShellInput {
  /**
   * 終了するバックグラウンドシェルの ID
   */
  shell_id: string;
}

ID で実行中のバックグラウンド bash シェルを終了します。

NotebookEdit

ツール名: NotebookEdit

interface NotebookEditInput {
  /**
   * Jupyter ノートブックファイルの絶対パス
   */
  notebook_path: string;
  /**
   * 編集するセルの ID
   */
  cell_id?: string;
  /**
   * セルの新しいソース
   */
  new_source: string;
  /**
   * セルのタイプ（code または markdown）
   */
  cell_type?: 'code' | 'markdown';
  /**
   * 編集のタイプ（replace、insert、delete）
   */
  edit_mode?: 'replace' | 'insert' | 'delete';
}

Jupyter ノートブックファイル内のセルを編集します。

WebFetch

ツール名: WebFetch

interface WebFetchInput {
  /**
   * コンテンツを取得する URL
   */
  url: string;
  /**
   * 取得したコンテンツで実行するプロンプト
   */
  prompt: string;
}

URL からコンテンツを取得し、AI モデルで処理します。

WebSearch

ツール名: WebSearch

interface WebSearchInput {
  /**
   * 使用する検索クエリ
   */
  query: string;
  /**
   * これらのドメインからのみ結果を含める
   */
  allowed_domains?: string[];
  /**
   * これらのドメインからの結果を決して含めない
   */
  blocked_domains?: string[];
}

ウェブを検索し、フォーマットされた結果を返します。

TodoWrite

ツール名: TodoWrite

interface TodoWriteInput {
  /**
   * 更新されたタスクリスト
   */
  todos: Array<{
    /**
     * タスクの説明
     */
    content: string;
    /**
     * タスクのステータス
     */
    status: 'pending' | 'in_progress' | 'completed';
    /**
     * タスク説明のアクティブ形式
     */
    activeForm: string;
  }>;
}

進捗を追跡するための構造化されたタスクリストを作成および管理します。

ExitPlanMode

ツール名: ExitPlanMode

interface ExitPlanModeInput {
  /**
   * ユーザーの承認を得るために実行する計画
   */
  plan: string;
}

計画モードを終了し、ユーザーに計画の承認を促します。

ListMcpResources

ツール名: ListMcpResources

interface ListMcpResourcesInput {
  /**
   * リソースをフィルタリングするオプションのサーバー名
   */
  server?: string;
}

接続されたサーバーから利用可能な MCP リソースをリストします。

ReadMcpResource

ツール名: ReadMcpResource

interface ReadMcpResourceInput {
  /**
   * MCP サーバー名
   */
  server: string;
  /**
   * 読み込むリソース URI
   */
  uri: string;
}

サーバーから特定の MCP リソースを読み込みます。

ツール出力型

すべての組み込み Claude Code ツールの出力スキーマのドキュメント。これらの型は各ツールによって返される実際の応答データを表します。

`ToolOutput`

注: これはわかりやすくするためのドキュメント専用型です。すべてのツール出力型の共用体を表します。

type ToolOutput = 
  | TaskOutput
  | BashOutput
  | BashOutputToolOutput
  | EditOutput
  | ReadOutput
  | WriteOutput
  | GlobOutput
  | GrepOutput
  | KillBashOutput
  | NotebookEditOutput
  | WebFetchOutput
  | WebSearchOutput
  | TodoWriteOutput
  | ExitPlanModeOutput
  | ListMcpResourcesOutput
  | ReadMcpResourceOutput;

Task

ツール名: Task

interface TaskOutput {
  /**
   * サブエージェントからの最終結果メッセージ
   */
  result: string;
  /**
   * トークン使用統計
   */
  usage?: {
    input_tokens: number;
    output_tokens: number;
    cache_creation_input_tokens?: number;
    cache_read_input_tokens?: number;
  };
  /**
   * USD での総コスト
   */
  total_cost_usd?: number;
  /**
   * 実行期間（ミリ秒単位）
   */
  duration_ms?: number;
}

委任されたタスクを完了した後、サブエージェントからの最終結果を返します。

Bash

ツール名: Bash

interface BashOutput {
  /**
   * stdout と stderr の結合出力
   */
  output: string;
  /**
   * コマンドの終了コード
   */
  exitCode: number;
  /**
   * タイムアウトによってコマンドが終了されたかどうか
   */
  killed?: boolean;
  /**
   * バックグラウンドプロセス用のシェル ID
   */
  shellId?: string;
}

終了ステータス付きのコマンド出力を返します。バックグラウンドコマンドは shellId で即座に返されます。

BashOutput

ツール名: BashOutput

interface BashOutputToolOutput {
  /**
   * 最後のチェック以降の新しい出力
   */
  output: string;
  /**
   * 現在のシェルステータス
   */
  status: 'running' | 'completed' | 'failed';
  /**
   * 終了コード（完了時）
   */
  exitCode?: number;
}

バックグラウンドシェルからの増分出力を返します。

Edit

ツール名: Edit

interface EditOutput {
  /**
   * 確認メッセージ
   */
  message: string;
  /**
   * 実行された置換の数
   */
  replacements: number;
  /**
   * 編集されたファイルパス
   */
  file_path: string;
}

成功した編集の確認と置換数を返します。

Read

ツール名: Read

type ReadOutput = 
  | TextFileOutput
  | ImageFileOutput
  | PDFFileOutput
  | NotebookFileOutput;

interface TextFileOutput {
  /**
   * 行番号付きのファイルコンテンツ
   */
  content: string;
  /**
   * ファイル内の総行数
   */
  total_lines: number;
  /**
   * 実際に返された行数
   */
  lines_returned: number;
}

interface ImageFileOutput {
  /**
   * Base64 エンコードされた画像データ
   */
  image: string;
  /**
   * 画像 MIME タイプ
   */
  mime_type: string;
  /**
   * ファイルサイズ（バイト単位）
   */
  file_size: number;
}

interface PDFFileOutput {
  /**
   * ページコンテンツの配列
   */
  pages: Array<{
    page_number: number;
    text?: string;
    images?: Array<{
      image: string;
      mime_type: string;
    }>;
  }>;
  /**
   * 総ページ数
   */
  total_pages: number;
}

interface NotebookFileOutput {
  /**
   * Jupyter ノートブックセル
   */
  cells: Array<{
    cell_type: 'code' | 'markdown';
    source: string;
    outputs?: any[];
    execution_count?: number;
  }>;
  /**
   * ノートブックメタデータ
   */
  metadata?: Record<string, any>;
}

ファイルタイプに適切な形式でファイルコンテンツを返します。

Write

ツール名: Write

interface WriteOutput {
  /**
   * 成功メッセージ
   */
  message: string;
  /**
   * 書き込まれたバイト数
   */
  bytes_written: number;
  /**
   * 書き込まれたファイルパス
   */
  file_path: string;
}

ファイルの書き込みに成功した後の確認を返します。

Glob

ツール名: Glob

interface GlobOutput {
  /**
   * マッチしたファイルパスの配列
   */
  matches: string[];
  /**
   * 見つかったマッチ数
   */
  count: number;
  /**
   * 使用された検索ディレクトリ
   */
  search_path: string;
}

グロブパターンにマッチするファイルパスを返します（変更時刻でソート）。

Grep

ツール名: Grep

type GrepOutput = 
  | GrepContentOutput
  | GrepFilesOutput
  | GrepCountOutput;

interface GrepContentOutput {
  /**
   * コンテキスト付きのマッチング行
   */
  matches: Array<{
    file: string;
    line_number?: number;
    line: string;
    before_context?: string[];
    after_context?: string[];
  }>;
  /**
   * マッチの総数
   */
  total_matches: number;
}

interface GrepFilesOutput {
  /**
   * マッチを含むファイル
   */
  files: string[];
  /**
   * マッチを含むファイル数
   */
  count: number;
}

interface GrepCountOutput {
  /**
   * ファイルごとのマッチ数
   */
  counts: Array<{
    file: string;
    count: number;
  }>;
  /**
   * すべてのファイル全体のマッチ総数
   */
  total: number;
}

output_mode で指定された形式で検索結果を返します。

KillBash

ツール名: KillBash

interface KillBashOutput {
  /**
   * 成功メッセージ
   */
  message: string;
  /**
   * 終了されたシェルの ID
   */
  shell_id: string;
}

バックグラウンドシェルの終了後の確認を返します。

NotebookEdit

ツール名: NotebookEdit

interface NotebookEditOutput {
  /**
   * 成功メッセージ
   */
  message: string;
  /**
   * 実行された編集のタイプ
   */
  edit_type: 'replaced' | 'inserted' | 'deleted';
  /**
   * 影響を受けたセルの ID
   */
  cell_id?: string;
  /**
   * 編集後のノートブック内の総セル数
   */
  total_cells: number;
}

Jupyter ノートブックの変更後の確認を返します。

WebFetch

ツール名: WebFetch

interface WebFetchOutput {
  /**
   * プロンプトに対する AI モデルの応答
   */
  response: string;
  /**
   * 取得された URL
   */
  url: string;
  /**
   * リダイレクト後の最終 URL
   */
  final_url?: string;
  /**
   * HTTP ステータスコード
   */
  status_code?: number;
}

取得した Web コンテンツの AI の分析を返します。

WebSearch

ツール名: WebSearch

interface WebSearchOutput {
  /**
   * 検索結果
   */
  results: Array<{
    title: string;
    url: string;
    snippet: string;
    /**
     * 利用可能な場合の追加メタデータ
     */
    metadata?: Record<string, any>;
  }>;
  /**
   * 結果の総数
   */
  total_results: number;
  /**
   * 検索されたクエリ
   */
  query: string;
}

ウェブからのフォーマットされた検索結果を返します。

TodoWrite

ツール名: TodoWrite

interface TodoWriteOutput {
  /**
   * 成功メッセージ
   */
  message: string;
  /**
   * 現在のタスク統計
   */
  stats: {
    total: number;
    pending: number;
    in_progress: number;
    completed: number;
  };
}

現在のタスク統計を含む確認を返します。

ExitPlanMode

ツール名: ExitPlanMode

interface ExitPlanModeOutput {
  /**
   * 確認メッセージ
   */
  message: string;
  /**
   * ユーザーが計画を承認したかどうか
   */
  approved?: boolean;
}

計画モード終了後の確認を返します。

ListMcpResources

ツール名: ListMcpResources

interface ListMcpResourcesOutput {
  /**
   * 利用可能なリソース
   */
  resources: Array<{
    uri: string;
    name: string;
    description?: string;
    mimeType?: string;
    server: string;
  }>;
  /**
   * リソースの総数
   */
  total: number;
}

利用可能な MCP リソースのリストを返します。

ReadMcpResource

ツール名: ReadMcpResource

interface ReadMcpResourceOutput {
  /**
   * リソースコンテンツ
   */
  contents: Array<{
    uri: string;
    mimeType?: string;
    text?: string;
    blob?: string;
  }>;
  /**
   * リソースを提供したサーバー
   */
  server: string;
}

要求された MCP リソースのコンテンツを返します。

権限型

`PermissionUpdate`

権限を更新するための操作。

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`

type PermissionBehavior = 'allow' | 'deny' | 'ask';

`PermissionUpdateDestination`

type PermissionUpdateDestination = 
  | 'userSettings'     // グローバルユーザー設定
  | 'projectSettings'  // ディレクトリごとのプロジェクト設定
  | 'localSettings'    // Gitignore 対象のローカル設定
  | 'session'          // 現在のセッションのみ

`PermissionRuleValue`

type PermissionRuleValue = {
  toolName: string;
  ruleContent?: string;
}

その他の型

`ApiKeySource`

type ApiKeySource = 'user' | 'project' | 'org' | 'temporary';

`ConfigScope`

type ConfigScope = 'local' | 'user' | 'project';

`NonNullableUsage`

すべてのヌル許容フィールドがヌル許容でなくなった Usage のバージョン。

type NonNullableUsage = {
  [K in keyof Usage]: NonNullable<Usage[K]>;
}

`Usage`

トークン使用統計（@anthropic-ai/sdk から）。

type Usage = {
  input_tokens: number | null;
  output_tokens: number | null;
  cache_creation_input_tokens?: number | null;
  cache_read_input_tokens?: number | null;
}

`CallToolResult`

MCP ツール結果型（@modelcontextprotocol/sdk/types.js から）。

type CallToolResult = {
  content: Array<{
    type: 'text' | 'image' | 'resource';
    // 追加フィールドはタイプによって異なります
  }>;
  isError?: boolean;
}

`AbortError`

中止操作用のカスタムエラークラス。

class AbortError extends Error {}

はじめの一歩

モデルと価格

Claudeで構築

機能

ツール

エージェントスキル

Agent SDK

API内のMCP

Claude on 3rd-party platforms

プロンプトエンジニアリング

テストと評価

ガードレールを強化

管理とモニタリング

​インストール

​関数

​query()

​パラメータ

​戻り値

​tool()

​パラメータ

​createSdkMcpServer()

​パラメータ

​型

​Options

​Query

​メソッド

​AgentDefinition

​SettingSource

​デフォルト動作

​settingSources を使用する理由

​設定の優先順位

​PermissionMode

​CanUseTool

​PermissionResult

​McpServerConfig

​McpStdioServerConfig

​McpSSEServerConfig

​McpHttpServerConfig

​McpSdkServerConfigWithInstance

​SdkPluginConfig

​メッセージ型

​SDKMessage

​SDKAssistantMessage

​SDKUserMessage

​SDKUserMessageReplay

​SDKResultMessage

​SDKSystemMessage

​SDKPartialAssistantMessage

​SDKCompactBoundaryMessage

​SDKPermissionDenial

​フック型

​HookEvent

​HookCallback

​HookCallbackMatcher

​HookInput

​BaseHookInput

​PreToolUseHookInput

​PostToolUseHookInput

​NotificationHookInput

​UserPromptSubmitHookInput

​SessionStartHookInput

​SessionEndHookInput

​StopHookInput

​SubagentStopHookInput

​PreCompactHookInput

​HookJSONOutput

​AsyncHookJSONOutput

​SyncHookJSONOutput

​ツール入力型

​ToolInput

​Task

​Bash

​BashOutput

​Edit

​Read

​Write

​Glob

​Grep

​KillBash

​NotebookEdit

インストール

関数

`query()`

パラメータ

戻り値

`tool()`

パラメータ

`createSdkMcpServer()`

パラメータ

型

`Options`

`Query`

メソッド

`AgentDefinition`

`SettingSource`

デフォルト動作

settingSources を使用する理由

設定の優先順位

`PermissionMode`

`CanUseTool`

`PermissionResult`

`McpServerConfig`

`McpStdioServerConfig`

`McpSSEServerConfig`

`McpHttpServerConfig`

`McpSdkServerConfigWithInstance`

`SdkPluginConfig`

メッセージ型

`SDKMessage`

`SDKAssistantMessage`

`SDKUserMessage`

`SDKUserMessageReplay`

`SDKResultMessage`

`SDKSystemMessage`

`SDKPartialAssistantMessage`

`SDKCompactBoundaryMessage`

`SDKPermissionDenial`

フック型

`HookEvent`

`HookCallback`

`HookCallbackMatcher`

`HookInput`

`BaseHookInput`

`PreToolUseHookInput`

`PostToolUseHookInput`

`NotificationHookInput`

`UserPromptSubmitHookInput`

`SessionStartHookInput`

`SessionEndHookInput`

`StopHookInput`

`SubagentStopHookInput`

`PreCompactHookInput`

`HookJSONOutput`

`AsyncHookJSONOutput`

`SyncHookJSONOutput`

ツール入力型

`ToolInput`

Task

Bash

BashOutput

Edit

Read

Write

Glob

Grep

KillBash

NotebookEdit

WebFetch

WebSearch

TodoWrite

ExitPlanMode

ListMcpResources

ReadMcpResource

ツール出力型

`ToolOutput`

Task

Bash

BashOutput

Edit

Read