186 console.error("Claim failed:", error.message);186 console.error("Claim failed:", error.message);
187});187});
188 188
189for await (const message of claimedQuery) {189try {
190 for await (const message of claimedQuery) {
190 console.log(message);191 console.log(message);
192 }
193} catch (error) {
194 // クレームが拒否された場合、クレームされたクエリはエラー結果を生成した後にスローします
195 console.error(`Session ended with an error: ${error}`);
191}196}
192```197```
193 198
539| プロパティ | 型 | デフォルト | 説明 |544| プロパティ | 型 | デフォルト | 説明 |
540| :- | :- | :- | :- |545| :- | :- | :- | :- |
541| `abortController` | `AbortController` | `new AbortController()` | 操作をキャンセルするためのコントローラー |546| `abortController` | `AbortController` | `new AbortController()` | 操作をキャンセルするためのコントローラー |
542| `additionalDirectories` | `string[]` | `[]` | Claude がアクセスできる追加のディレクトリ。SDK は各エントリを `--add-dir` として Claude Code に渡すため、`project` 設定ソースを使用している場合、Claude Code は[そのディレクトリのスキル、コマンド、サブエージェントも読み込みます](/docs/ja/permissions#additional-directories-grant-file-access-not-configuration) |547| `additionalDirectories` | `string[]` | `[]` | Claude がアクセスできる追加のディレクトリ。SDK は各エントリを `--add-dir` として Claude Code に渡すため、`project` 設定ソースを使用すると、Claude Code は[そのディレクトリのスキル、コマンド、サブエージェントも読み込みます](/docs/ja/permissions#additional-directories-grant-file-access-not-configuration) |
543| `agent` | `string` | `undefined` | メインスレッドのエージェント名。エージェントは `agents` オプションまたは設定で定義されている必要があります |548| `agent` | `string` | `undefined` | メインスレッドのエージェント名。エージェントは `agents` オプションまたは設定で定義されている必要があります |
544| `agents` | `Record<string, [`AgentDefinition`](#agentdefinition)>` | `undefined` | サブエージェントをプログラムで定義します |549| `agents` | `Record<string, [`AgentDefinition`](#agentdefinition)>` | `undefined` | サブエージェントをプログラムで定義します |
545| `agentProgressSummaries` | `boolean` | `false` | `true` の場合、サブエージェントの 1 行の進捗サマリーを生成し、`summary` フィールドを介して [`task_progress`](#sdktaskprogressmessage) イベントで転送します。フォアグラウンドとバックグラウンドの両方のサブエージェントに適用されます |550| `agentProgressSummaries` | `boolean` | `false` | `true` の場合、サブエージェントの 1 行の進捗サマリーを生成し、`summary` フィールドを介して [`task_progress`](#sdktaskprogressmessage) イベントで転送します。フォアグラウンドとバックグラウンドの両方のサブエージェントに適用されます |
546| `allowDangerouslySkipPermissions` | `boolean` | `false` | 権限のバイパスを有効にします。起動時、または後から `setPermissionMode()` を通じて `permissionMode: 'bypassPermissions'` を使用する場合に必須です。`permissionMode: 'plan'` との相互作用については [plan モード](/docs/ja/agent-sdk/permissions#plan-mode-plan)を参照してください |551| `allowDangerouslySkipPermissions` | `boolean` | `false` | 権限のバイパスを有効にします。起動時、または後から `setPermissionMode()` を介して `permissionMode: 'bypassPermissions'` を使用する場合に必要です。`permissionMode: 'plan'` との相互作用については [plan モード](/docs/ja/agent-sdk/permissions#plan-mode-plan)を参照してください |
547| `allowedTools` | `string[]` | `[]` | プロンプトを表示せずに自動承認するツール。これは Claude をこれらのツールのみに制限するものではありません。ここで[タスク追跡ツール](/docs/ja/agent-sdk/todo-tracking#model-availability)のいずれかを指定すると、Claude Code はセッションでもその機能を有効にします。リストにないその他のツールは `permissionMode` と `canUseTool` にフォールスルーします。ツールをブロックするには `disallowedTools` を使用します。[権限](/docs/ja/agent-sdk/permissions#allow-and-deny-rules)を参照してください |552| `allowedTools` | `string[]` | `[]` | 確認なしで自動承認するツール。これは Claude をこれらのツールのみに制限するものではありません。ここで[タスク追跡ツール](/docs/ja/agent-sdk/todo-tracking#model-availability)のいずれかを指定すると、Claude Code はセッションでもその機能を有効にします。リストにないその他のツールは `permissionMode` と `canUseTool` に処理が委ねられます。ツールをブロックするには `disallowedTools` を使用してください。[権限](/docs/ja/agent-sdk/permissions#allow-and-deny-rules)を参照してください |
548| `betas` | [`SdkBeta`](#sdkbeta)`[]` | `[]` | ベータ機能を有効にします |553| `betas` | [`SdkBeta`](#sdkbeta)`[]` | `[]` | ベータ機能を有効にします |
549| `canUseTool` | [`CanUseTool`](#canusetool) | `undefined` | カスタム権限関数。[権限フロー](/docs/ja/agent-sdk/permissions#how-permissions-are-evaluated)がプロンプトにフォールスルーした場合にのみ呼び出されます。`allowedTools`、許可ルール、または `permissionMode` によって自動承認された呼び出しでは呼び出されません。許可ルールは[どのモードでも自動承認されないアクション](/docs/ja/permission-modes#actions-no-mode-auto-approves)を事前承認しません。詳細は [`CanUseTool`](#canusetool) を参照してください |554| `canUseTool` | [`CanUseTool`](#canusetool) | `undefined` | カスタム権限関数。[権限フロー](/docs/ja/agent-sdk/permissions#how-permissions-are-evaluated)がプロンプトの表示に至った場合にのみ呼び出されます。`allowedTools`、許可ルール、または `permissionMode` によって自動承認された呼び出しに対しては呼び出されません。許可ルールは[どのモードでも自動承認されないアクション](/docs/ja/permission-modes#actions-no-mode-auto-approves)を事前承認しません。詳細は [`CanUseTool`](#canusetool) を参照してください |
550| `continue` | `boolean` | `false` | 最新の会話を続行します |555| `continue` | `boolean` | `false` | 最新の会話を続行します |
551| `cwd` | `string` | `process.cwd()` | 現在の作業ディレクトリ |556| `cwd` | `string` | `process.cwd()` | 現在の作業ディレクトリ |
552| `debug` | `boolean` | `false` | Claude Code プロセスのデバッグモードを有効にします |557| `debug` | `boolean` | `false` | Claude Code プロセスのデバッグモードを有効にします |
553| `debugFile` | `string` | `undefined` | デバッグログを特定のファイルパスに書き込みます。暗黙的にデバッグモードを有効にします |558| `debugFile` | `string` | `undefined` | デバッグログを特定のファイルパスに書き込みます。暗黙的にデバッグモードが有効になります |
554| `disallowedTools` | `string[]` | `[]` | 拒否するツール。`"Bash"` のような名前のみの指定は、ツールを Claude のコンテキストから削除します。`"Bash(rm *)"` のようなスコープ付きルールはツールを利用可能なままにし、`bypassPermissions` を含むすべての権限モードで、[記述されたとおりの](/docs/ja/permissions#bash-rule-limits)コマンドに一致する呼び出しを拒否します。[権限](/docs/ja/agent-sdk/permissions#allow-and-deny-rules)を参照してください |559| `disallowedTools` | `string[]` | `[]` | 拒否するツール。`"Bash"` のような単独の名前は、そのツールを Claude のコンテキストから削除します。`"Bash(rm *)"` のようなスコープ付きルールはツールを利用可能なままにし、`bypassPermissions` を含むすべての権限モードで、[記述どおりの](/docs/ja/permissions#bash-rule-limits)コマンドに一致する呼び出しを拒否します。[権限](/docs/ja/agent-sdk/permissions#allow-and-deny-rules)を参照してください |
555| `effort` | `'low' \| 'medium' \| 'high' \| 'xhigh' \| 'max'` | `undefined` | Claude が応答にどれだけの労力をかけるかを制御します。適応型思考と連携して思考の深さを導きます。[effort レベルを調整する](/docs/ja/model-config#adjust-effort-level)を参照してください |560| `effort` | `'low' \| 'medium' \| 'high' \| 'xhigh' \| 'max'` | `undefined` | Claude が応答にかける労力を制御します。adaptive thinking と連携して思考の深さを導きます。[effort レベルを調整する](/docs/ja/model-config#adjust-effort-level)を参照してください |
556| `enableFileCheckpointing` | `boolean` | `false` | 巻き戻しのためのファイル変更追跡を有効にします。[ファイルチェックポイント機能](/docs/ja/agent-sdk/file-checkpointing)を参照してください |561| `enableFileCheckpointing` | `boolean` | `false` | 巻き戻しのためのファイル変更追跡を有効にします。[ファイルのチェックポイント機能](/docs/ja/agent-sdk/file-checkpointing)を参照してください |
557| `env` | `Record<string, string \| undefined>` | `process.env` | 環境変数。設定すると、`process.env` とマージされるのではなくサブプロセスの環境を置き換えるため、`PATH` などの継承された変数を保持するには `{ ...process.env, YOUR_VAR: 'value' }` を渡してください。このパターンの例については[遅い API レスポンスや停止した API レスポンスに対処する](#handle-slow-or-stalled-api-responses)を、基盤となる CLI が読み取る変数については[環境変数](/docs/ja/env-vars)を参照してください。User-Agent ヘッダーでアプリを識別するには `CLAUDE_AGENT_SDK_CLIENT_APP` を設定します |562| `env` | `Record<string, string \| undefined>` | `process.env` | 環境変数。設定すると、`process.env` とマージされるのではなくサブプロセスの環境が置き換えられるため、`PATH` などの継承された変数を保持するには `{ ...process.env, YOUR_VAR: 'value' }` を渡してください。このパターンの例については[遅い、または停止した API レスポンスを処理する](#handle-slow-or-stalled-api-responses)を、基盤となる CLI が読み取る変数については[環境変数](/docs/ja/env-vars)を参照してください。User-Agent ヘッダーでアプリを識別するには `CLAUDE_AGENT_SDK_CLIENT_APP` を設定します |
558| `executable` | `'bun' \| 'deno' \| 'node'` | 自動検出 | 使用する JavaScript ランタイム |563| `executable` | `'bun' \| 'deno' \| 'node'` | 自動検出 | 使用する JavaScript ランタイム |
559| `executableArgs` | `string[]` | `[]` | 実行ファイルに渡す引数 |564| `executableArgs` | `string[]` | `[]` | 実行可能ファイルに渡す引数 |
560| `extraArgs` | `Record<string, string \| null>` | `{}` | 追加の引数 |565| `extraArgs` | `Record<string, string \| null>` | `{}` | 追加の引数 |
561| `fallbackModel` | `string` | `undefined` | プライマリモデルが失敗した場合に使用するモデル。カンマ区切りのリストを受け付けます。順序と上限については[フォールバックモデルチェーン](/docs/ja/model-config#fallback-model-chains)を参照してください。ガイダンスについては[モデルを選択する](/docs/ja/agent-sdk/configuration#choose-a-model)を参照してください |566| `fallbackModel` | `string` | `undefined` | プライマリモデルが失敗した場合に使用するモデル。カンマ区切りのリストを受け付けます。順序と上限については[フォールバックモデルチェーン](/docs/ja/model-config#fallback-model-chains)を参照してください。ガイダンスについては[モデルを選択する](/docs/ja/agent-sdk/configuration#choose-a-model)を参照してください |
562| `forkSession` | `boolean` | `false` | `resume` で再開する際に、元のセッションを続行するのではなく新しいセッション ID にフォークします |567| `forkSession` | `boolean` | `false` | `resume` で再開する際、元のセッションを続行する代わりに新しいセッション ID にフォークします |
563| `forwardSubagentText` | `boolean` | `false` | サブエージェントのテキストと思考ブロックを、`parent_tool_use_id` が設定されたアシスタントメッセージおよびユーザーメッセージとして転送し、コンシューマーがネストされたトランスクリプトをレンダリングできるようにします。このオプションがない場合、Claude Code はサブエージェントの `tool_use` ブロックと `tool_result` ブロックを出力しますが、テキストや思考は出力しません。Claude Code v2.1.219 以降では、すべてのネスト深度のサブエージェントからのメッセージが転送されます。v2.1.219 より前は、深度 1 のサブエージェントからのメッセージのみが表示されていました。フォークされたスキルが生成するサブエージェントのメッセージ、およびネストされたフォークされたスキルのメッセージには v2.1.275 以降が必要です |568| `forwardSubagentText` | `boolean` | `false` | サブエージェントのテキストブロックと思考ブロックを、`parent_tool_use_id` を設定した assistant メッセージおよび user メッセージとして転送し、利用側がネストされたトランスクリプトを表示できるようにします。このオプションがない場合、Claude Code はサブエージェントの `tool_use` ブロックと `tool_result` ブロックを出力しますが、テキストや思考は出力しません。Claude Code v2.1.219 以降では、すべてのネストの深さのサブエージェントからのメッセージが転送されます。v2.1.219 より前は、深さ 1 のサブエージェントからのメッセージのみが表示されていました。フォークされたスキルが起動するサブエージェントのメッセージ、およびネストされたフォークスキルのメッセージには v2.1.275 以降が必要です |
564| `hooks` | `Partial<Record<`[`HookEvent`](#hookevent)`, `[`HookCallbackMatcher`](#hookcallbackmatcher)`[]>>` | `{}` | イベントのフックコールバック |569| `hooks` | `Partial<Record<`[`HookEvent`](#hookevent)`, `[`HookCallbackMatcher`](#hookcallbackmatcher)`[]>>` | `{}` | イベントのフックコールバック |
565| `includeHookEvents` | `boolean` | `false` | フックのライフサイクルイベントを [`SDKHookStartedMessage`](#sdkhookstartedmessage)、[`SDKHookProgressMessage`](#sdkhookprogressmessage)、[`SDKHookResponseMessage`](#sdkhookresponsemessage) としてメッセージストリームに含めます。`SessionStart` フックと `Setup` フックのライフサイクルイベントは常に含まれるため、このオプションは不要です。`Notification`、`SessionEnd`、`PreCompact`、`PostCompact` など一部のフックイベントは、このオプションを指定しても `SDKHookStartedMessage` を生成しません。これらのイベントでも、1 秒以上実行されるコマンドフックが出力を生成している間は Claude Code は `SDKHookProgressMessage` を出力し、`SDKHookResponseMessage` は[バックグラウンドで実行される](/docs/ja/hooks#run-hooks-in-the-background)フックが終了した場合にのみ出力します |570| `includeHookEvents` | `boolean` | `false` | フックのライフサイクルイベントを [`SDKHookStartedMessage`](#sdkhookstartedmessage)、[`SDKHookProgressMessage`](#sdkhookprogressmessage)、[`SDKHookResponseMessage`](#sdkhookresponsemessage) としてメッセージストリームに含めます。`SessionStart` フックと `Setup` フックのライフサイクルイベントは常に含まれるため、このオプションは不要です。`Notification`、`SessionEnd`、`PreCompact`、`PostCompact` などの一部のフックイベントは、このオプションを指定しても `SDKHookStartedMessage` を生成しません。これらのイベントについても、Claude Code は 1 秒以上実行されるコマンドフックが出力を生成している間は `SDKHookProgressMessage` を出力し、[バックグラウンドで実行される](/docs/ja/hooks#run-hooks-in-the-background)フックが終了したときにのみ `SDKHookResponseMessage` を出力します |
566| `includePartialMessages` | `boolean` | `false` | 部分メッセージイベントを含めます |571| `includePartialMessages` | `boolean` | `false` | 部分メッセージイベントを含めます |
567| `loadTimeoutMs` | `number` | `60000` | *アルファ版。* 再開時のマテリアライズ中の各 `sessionStore.load()` および `sessionStore.listSubkeys()` 呼び出しのタイムアウト（ミリ秒）。アダプターがこの時間内に完了しない場合、クエリはハングせずに失敗します。`sessionStore` が設定されていない場合は無視されます |572| `loadTimeoutMs` | `number` | `60000` | *アルファ版。* 再開時の実体化処理における、各 `sessionStore.load()` および `sessionStore.listSubkeys()` 呼び出しのタイムアウト（ミリ秒）。アダプターがこの時間内に完了しない場合、クエリはハングせずに失敗します。`sessionStore` が設定されていない場合は無視されます |
568| `managedSettings` | `Settings` | `undefined` | ホストプロセスが生成されたセッションに提供するポリシー層の設定。管理者がデプロイした管理設定があるマシンでは、管理者の優先順位が最も高い管理ソースが `parentSettingsBehavior: 'merge'` を設定していない限り Claude Code はこれらを無視し、[`policyHelper`](/docs/ja/settings-reference#policyhelper) が管理設定を提供している間は決してマージしません。マージされた値は制限のみを許可するフィルターを通過します。フィルターが許可する内容と `allowManaged*Only` ロックについては[親設定を制限する](/docs/ja/claude-apps-gateway#restrict-parent-settings)で説明しています。[`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](/docs/ja/env-vars) を設定するホストでは、次の 3 つのキーが代わりにこのペイロードから直接読み取られます。Claude Code v2.1.222 以降ではその[モデル設定](/docs/ja/model-config#restrict-model-selection)、v2.1.246 以降ではどの管理ソースも設定していない場合の [`modelPricing`](/docs/ja/settings-reference#modelpricing)、v2.1.247 以降ではその `ENABLE_TOOL_SEARCH` env エントリです |573| `managedSettings` | `Settings` | `undefined` | ホストプロセスが起動したセッションに提供する、ポリシー階層の設定。管理者がデプロイした管理設定があるマシンでは、管理者の最も優先度の高い管理ソースが `parentSettingsBehavior: 'merge'` を設定していない限り Claude Code はこれらを無視し、[`policyHelper`](/docs/ja/settings-reference#policyhelper) が管理設定を提供している間は決してマージしません。マージされた値は、制限を強める方向のみを許可するフィルターを通過します。フィルターが受け入れる内容と `allowManaged*Only` ロックについては[親の設定を制限する](/docs/ja/claude-apps-gateway#restrict-parent-settings)で説明しています。[`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](/docs/ja/env-vars) を設定するホストでは、代わりに 3 つのキーがこのペイロードから直接読み取られます：Claude Code v2.1.222 以降ではその[モデル設定](/docs/ja/model-config#restrict-model-selection)、v2.1.246 以降ではどの管理ソースも設定していない場合の [`modelPricing`](/docs/ja/settings-reference#modelpricing)、v2.1.247 以降ではその `ENABLE_TOOL_SEARCH` env エントリです |
569| `maxBudgetUsd` | `number` | `undefined` | クライアント側のコスト見積もりがこの USD 値に達したらクエリを停止します。この呼び出し自体の支出のみがカウントされ、再開されたセッションから復元された合計はカウントされません。精度に関する注意点とリセット動作については[コストと使用量を追跡する](/docs/ja/agent-sdk/cost-tracking)を参照してください |574| `maxBudgetUsd` | `number` | `undefined` | クライアント側のコスト見積もりがこの USD 値に達したときにクエリを停止します。その呼び出し自体の支出のみをカウントし、再開されたセッションから復元された合計はカウントされません。精度に関する注意点とリセット時の動作については[コストと使用量を追跡する](/docs/ja/agent-sdk/cost-tracking)を参照してください |
570| `maxThinkingTokens` | `number` | `undefined` | *非推奨:* 代わりに `thinking` を使用してください。思考プロセスの最大トークン数 |575| `maxThinkingTokens` | `number` | `undefined` | *非推奨：* 代わりに `thinking` を使用してください。思考プロセスの最大トークン数 |
571| `maxTurns` | `number` | `undefined` | エージェントの最大ターン数（ツール使用の往復） |576| `maxTurns` | `number` | `undefined` | エージェントの最大ターン数（ツール使用の往復） |
572| `mcpServers` | `Record<string, [`McpServerConfig`](#mcpserverconfig)>` | `{}` | MCP サーバーの設定 |577| `mcpServers` | `Record<string, [`McpServerConfig`](#mcpserverconfig)>` | `{}` | MCP サーバーの設定 |
573| `model` | `string` | CLI のデフォルト | Claude のモデルエイリアスまたは完全なモデル名。[使用可能な値とプロバイダー固有の ID](/docs/ja/model-config#available-models) を参照してください |578| `model` | `string` | CLI のデフォルト | Claude のモデルエイリアスまたは完全なモデル名。[受け付けられる値とプロバイダー固有の ID](/docs/ja/model-config#available-models)を参照してください |
574| `onElicitation` | `(request: ElicitationRequest, options: { signal: AbortSignal }) => Promise<ElicitationResult>` | `undefined` | MCP elicitation リクエストを処理するためのコールバック。MCP サーバーがユーザー入力を要求し、どのフックも先に処理しない場合に呼び出されます。指定しない場合、処理されない elicitation リクエストは自動的に拒否されます |579| `onElicitation` | `(request: ElicitationRequest, options: { signal: AbortSignal }) => Promise<ElicitationResult>` | `undefined` | MCP elicitation リクエストを処理するためのコールバック。MCP サーバーがユーザー入力を要求し、どのフックも先にそれを処理しない場合に呼び出されます。指定しない場合、処理されない elicitation リクエストは自動的に拒否されます |
575| `outputFormat` | `{ type: 'json_schema', schema: JSONSchema }` | `undefined` | エージェントの結果の出力形式を定義します。詳細は[構造化出力](/docs/ja/agent-sdk/structured-outputs)を参照してください |580| `outputFormat` | `{ type: 'json_schema', schema: JSONSchema }` | `undefined` | エージェントの結果の出力形式を定義します。詳細は[構造化出力](/docs/ja/agent-sdk/structured-outputs)を参照してください |
576| `outputStyle` | `string` | `undefined` | `Options` のフィールドではありません。代わりに、インラインの [`settings`](/docs/ja/settings) オブジェクトまたは設定ファイルで `outputStyle` を設定してください。[出力スタイルを有効にする](/docs/ja/agent-sdk/modifying-system-prompts#activate-an-output-style)を参照してください |581| `outputStyle` | `string` | `undefined` | `Options` のフィールドではありません。代わりに、インラインの [`settings`](/docs/ja/settings) オブジェクトまたは設定ファイルで `outputStyle` を設定してください。[出力スタイルを有効にする](/docs/ja/agent-sdk/modifying-system-prompts#activate-an-output-style)を参照してください |
577| `pathToClaudeCodeExecutable` | `string` | バンドルされたネイティブバイナリから自動解決 | Claude Code 実行ファイルへのパス。インストール時にオプションの依存関係がスキップされた場合、またはプラットフォームがサポート対象に含まれていない場合にのみ必要です |582| `pathToClaudeCodeExecutable` | `string` | バンドルされたネイティブバイナリから自動解決 | Claude Code 実行可能ファイルへのパス。インストール時にオプションの依存関係がスキップされた場合、またはプラットフォームがサポート対象に含まれていない場合にのみ必要です |
578| `permissionMode` | [`PermissionMode`](#permissionmode) | `undefined` | セッションの権限モード。省略した場合、セッションは auto モードで開始される可能性があります。Claude Code が開始時の権限モードをどのように選択するかについては[権限モード](/docs/ja/agent-sdk/permissions#permission-modes)を参照してください |583| `permissionMode` | [`PermissionMode`](#permissionmode) | `undefined` | セッションの権限モード。省略すると、セッションは auto モードで開始される場合があります。Claude Code が開始時の権限モードを選択する方法については[権限モード](/docs/ja/agent-sdk/permissions#permission-modes)を参照してください |
579| `permissionPromptToolName` | `string` | `undefined` | 権限プロンプト用の MCP ツール名 |584| `permissionPromptToolName` | `string` | `undefined` | 権限プロンプト用の MCP ツール名 |
580| `permissionPrompts` | `'host' \| 'none'` | `'host'` | 権限プロンプトに誰が応答するかを指定します。`'host'` はプロンプトを [`canUseTool`](#canusetool) コールバックまたは `permissionPromptToolName` ツールにルーティングし、`'none'` は[プロンプトを表示するはずだった呼び出しを拒否します](/docs/ja/agent-sdk/permissions#how-permissions-are-evaluated)。Claude Code v2.1.259 以降が必要です |585| `permissionPrompts` | `'host' \| 'none'` | `'host'` | 権限プロンプトに誰が応答するかを指定します：`'host'` はプロンプトを [`canUseTool`](#canusetool) コールバックまたは `permissionPromptToolName` ツールにルーティングし、`'none'` は[プロンプトが表示されるはずだった呼び出しを拒否します](/docs/ja/agent-sdk/permissions#how-permissions-are-evaluated)。Claude Code v2.1.259 以降が必要です |
581| `persistSession` | `boolean` | `true` | `false` の場合、ディスクへのセッションの永続化を無効にします。セッションは後で再開できません |586| `persistSession` | `boolean` | `true` | `false` の場合、ディスクへのセッションの永続化を無効にします。セッションを後で再開することはできません |
582| `planModeInstructions` | `string` | `undefined` | plan モード用のカスタムワークフロー指示。`permissionMode` が `'plan'` の場合、この文字列がデフォルトの plan モードのワークフロー本文を置き換えます。CLI は引き続き、読み取り専用を強制するプリアンブルと ExitPlanMode プロトコルのフッターでこれをラップします |587| `planModeInstructions` | `string` | `undefined` | plan モード用のカスタムワークフロー指示。`permissionMode` が `'plan'` の場合、この文字列がデフォルトの plan モードのワークフロー本文を置き換えます。CLI は引き続き、読み取り専用を強制する前文と ExitPlanMode プロトコルのフッターでこれをラップします |
583| `plugins` | [`SdkPluginConfig`](#sdkpluginconfig)`[]` | `[]` | ローカルパスからカスタムプラグインを読み込みます。詳細は[プラグイン](/docs/ja/agent-sdk/plugins)を参照してください |588| `plugins` | [`SdkPluginConfig`](#sdkpluginconfig)`[]` | `[]` | ローカルパスからカスタムプラグインを読み込みます。詳細は[プラグイン](/docs/ja/agent-sdk/plugins)を参照してください |
584| `projectConfigRoot` | `string` | `undefined` | `cwd` がその worktree となっている信頼済みチェックアウトの絶対パス。Claude Code は、プロジェクト設定、`.mcp.json`、およびプロジェクトの `.claude/` のコマンド、エージェント、スキル、ワークフロー、ルーティン、出力スタイルを `cwd` ではなくこのディレクトリから読み取り、`CLAUDE_PROJECT_DIR` をこのディレクトリに設定します。フック、`apiKeyHelper` などのヘルパースクリプト、stdio MCP サーバーは、このディレクトリを作業ディレクトリとして起動します。`CLAUDE.md` ファイルと `.claude/rules/` は引き続き `cwd` から読み込まれます。Claude Code v2.1.275 以降が必要です |589| `projectConfigRoot` | `string` | `undefined` | `cwd` を worktree として持つ、信頼されたチェックアウトの絶対パス。Claude Code は、プロジェクト設定、`.mcp.json`、およびプロジェクトの `.claude/` にあるコマンド、エージェント、スキル、ワークフロー、ルーティン、出力スタイルを `cwd` ではなくこのディレクトリから読み取り、`CLAUDE_PROJECT_DIR` をこのディレクトリに設定します。フック、`apiKeyHelper` などのヘルパースクリプト、stdio MCP サーバーは、このディレクトリを作業ディレクトリとして起動します。`CLAUDE.md` ファイルと `.claude/rules/` は引き続き `cwd` から読み込まれます。Claude Code v2.1.275 以降が必要です |
585| `promptSuggestions` | `boolean` | `false` | プロンプト候補を有効にします。ターンの後、Claude Code は予測された次のユーザープロンプトを含む `prompt_suggestion` メッセージを出力します。アカウントが使用制限に近づいているか達している間など、一部のターンでは Claude Code は候補を生成しません。[Claude Code が候補をスキップする場合](/docs/ja/interactive-mode#when-claude-code-skips-suggestions)を参照してください |590| `promptSuggestions` | `boolean` | `false` | プロンプト候補を有効にします。ターンの後、Claude Code は予測される次のユーザープロンプトを含む `prompt_suggestion` メッセージを出力します。アカウントが使用制限に近づいている、または達している間など、一部のターンでは Claude Code は候補を生成しません。[Claude Code が候補をスキップする場合](/docs/ja/interactive-mode#when-claude-code-skips-suggestions)を参照してください |
586| `resume` | `string` | `undefined` | 再開するセッション ID |591| `resume` | `string` | `undefined` | 再開するセッション ID |
587| `resumeDropsTurn` | `string` | `undefined` | `resumeSessionAt` と併用します。切り詰めを伴う再開で破棄しようとするターンのプロンプト UUID です。破棄される範囲に、取り込まれたキュー内のメッセージやタスク通知など、そのターンに帰属しないものが含まれている場合、Claude Code は再開を拒否し、拒否メッセージで `--resume-drops-turn` フラグを示します。このペアを読み取るのは Agent SDK と print モードの再開のみです。Claude Code v2.1.223 以降が必要です |592| `resumeDropsTurn` | `string` | `undefined` | `resumeSessionAt` と併用します：切り詰めを伴う再開で破棄する予定のターンのプロンプト UUID。破棄される範囲に、取り込まれたキュー内のメッセージやタスク通知など、そのターンに帰属しないものが含まれている場合、Claude Code は再開を拒否し、拒否メッセージで `--resume-drops-turn` フラグを示します。この組み合わせを読み取るのは、Agent SDK と print モードでの再開のみです。Claude Code v2.1.223 以降が必要です |
588| `resumeSessionAt` | `string` | `undefined` | 特定のメッセージ UUID の時点でセッションを再開します |593| `resumeSessionAt` | `string` | `undefined` | 特定のメッセージ UUID の時点でセッションを再開します |
589| `sandbox` | [`SandboxSettings`](#sandboxsettings) | `undefined` | サンドボックスの動作をプログラムで設定します。詳細は[サンドボックス設定](#sandboxsettings)を参照してください |594| `sandbox` | [`SandboxSettings`](#sandboxsettings) | `undefined` | サンドボックスの動作をプログラムで設定します。詳細は[サンドボックス設定](#sandboxsettings)を参照してください |
590| `sessionId` | `string` | 自動生成 | 自動生成する代わりに、セッションに特定の UUID を使用します |595| `sessionId` | `string` | 自動生成 | 自動生成する代わりに、セッションに特定の UUID を使用します |
591| `sessionStore` | [`SessionStore`](/docs/ja/agent-sdk/session-storage#the-sessionstore-interface) | `undefined` | 別のホストが再開できるように、セッションのトランスクリプトを外部バックエンドにミラーリングします。[外部ストレージにセッションを永続化する](/docs/ja/agent-sdk/session-storage)を参照してください |596| `sessionStore` | [`SessionStore`](/docs/ja/agent-sdk/session-storage#the-sessionstore-interface) | `undefined` | 別のホストが再開できるように、セッションのトランスクリプトを外部バックエンドにミラーリングします。[外部ストレージにセッションを永続化する](/docs/ja/agent-sdk/session-storage)を参照してください |
592| `sessionStoreFlush` | `'batched' \| 'eager'` | `'batched'` | *アルファ版。* `sessionStore` のフラッシュモード。`sessionStore` が設定されていない場合は無視されます |597| `sessionStoreFlush` | `'batched' \| 'eager'` | `'batched'` | *アルファ版。* `sessionStore` のフラッシュモード。`sessionStore` が設定されていない場合は無視されます |
593| `settings` | `string \| Settings` | `undefined` | インラインの[設定](/docs/ja/settings)オブジェクト、設定ファイルのパス、またはインライン JSON 文字列。[優先順位](/docs/ja/settings#settings-precedence)におけるフラグ設定レイヤーに値を設定します。実行時に [`applyFlagSettings()`](#applyflagsettings) で変更できます |598| `settings` | `string \| Settings` | `undefined` | インラインの[設定](/docs/ja/settings)オブジェクト、設定ファイルのパス、またはインライン JSON 文字列。[優先順位](/docs/ja/settings#settings-precedence)におけるフラグ設定レイヤーに値を設定します。実行時には [`applyFlagSettings()`](#applyflagsettings) で変更できます |
594| `settingSources` | [`SettingSource`](#settingsource)`[]` | CLI のデフォルト（すべてのソース） | 読み込むファイルシステム設定を制御します。ユーザー、プロジェクト、ローカルの設定を無効にするには `[]` を渡します。[エンドポイント管理ポリシー](/docs/ja/managed-settings#delivery-mechanisms)はこの指定に関係なく読み込まれます。サーバー管理設定は、セッションが[対象となる設定](/docs/ja/server-managed-settings#platform-availability)で組織の認証情報を使って認証される場合に取得されます。[Claude Code の機能を使用する](/docs/ja/agent-sdk/claude-code-features#what-settingsources-does-not-control)を参照してください |599| `settingSources` | [`SettingSource`](#settingsource)`[]` | CLI のデフォルト（すべてのソース） | 読み込むファイルシステム設定を制御します。ユーザー、プロジェクト、ローカルの設定を無効にするには `[]` を渡します。[エンドポイント管理ポリシー](/docs/ja/managed-settings#delivery-mechanisms)はこの指定に関係なく読み込まれます。サーバー管理設定は、セッションが[対象となる構成](/docs/ja/server-managed-settings#platform-availability)で組織の認証情報を使用して認証した場合に取得されます。[Claude Code の機能を使用する](/docs/ja/agent-sdk/claude-code-features#what-settingsources-does-not-control)を参照してください |
595| `skills` | `string[] \| 'all'` | `undefined` | セッションで使用可能なスキル。検出されたすべてのスキルを有効にするには `'all'` を、またはスキル名のリストを渡します。正確な名前のみを渡してください。Agent SDK v0.3.221 以降では、SDK は Claude Code プロセスを開始する前に、不正な形式の名前とワイルドカード形式の名前をエラーで拒否します。設定すると、SDK は Skill ツールを自動的に `allowedTools` に追加します。`tools` も渡す場合は、そのリストに `'Skill'` を含めてください。[スキル](/docs/ja/agent-sdk/skills)を参照してください |600| `skills` | `string[] \| 'all'` | `undefined` | セッションで利用可能なスキル。検出されたすべてのスキルを有効にするには `'all'` を、または特定のスキル名のリストを渡します。正確な名前のみを渡してください。Agent SDK v0.3.221 以降では、SDK は Claude Code プロセスを開始する前に、不正な形式やワイルドカード形式の名前をエラーとして拒否します。設定すると、SDK は Skill ツールを `allowedTools` に自動的に追加します。`tools` も渡す場合は、そのリストに `'Skill'` を含めてください。[スキル](/docs/ja/agent-sdk/skills)を参照してください |
596| `spawnClaudeCodeProcess` | `(options: SpawnOptions) => SpawnedProcess` | `undefined` | Claude Code プロセスを生成するカスタム関数。VM、コンテナ、またはリモート環境で Claude Code を実行する場合に使用します |601| `spawnClaudeCodeProcess` | `(options: SpawnOptions) => SpawnedProcess` | `undefined` | Claude Code プロセスを起動するためのカスタム関数。VM、コンテナ、またはリモート環境で Claude Code を実行する場合に使用します |
597| `stderr` | `(data: string) => void` | `undefined` | stderr 出力のコールバック |602| `stderr` | `(data: string) => void` | `undefined` | stderr 出力用のコールバック |
598| `strictMcpConfig` | `boolean` | `false` | `mcpServers` で渡されたサーバーのみを使用し、プロジェクトの `.mcp.json`、ユーザー設定、プラグインが提供する MCP サーバー、[claude.ai コネクタ](/docs/ja/mcp#use-mcp-servers-from-claude-ai)を無視します |603| `strictMcpConfig` | `boolean` | `false` | `mcpServers` で渡されたサーバーのみを使用し、プロジェクトの `.mcp.json`、ユーザー設定、プラグインが提供する MCP サーバー、[claude.ai のコネクタ](/docs/ja/mcp#use-mcp-servers-from-claude-ai)を無視します |
599| `systemPrompt` | `string \| string[] \| { type: 'custom'; prompt: string \| string[]; snapshot?: boolean } \| { type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean; snapshot?: boolean }` | `undefined`（最小限のプロンプト） | システムプロンプトの設定。カスタムプロンプトには文字列を渡し、Claude Code のシステムプロンプトを使用するには `{ type: 'preset', preset: 'claude_code' }` を渡します。静的部分とリクエストごとの部分の間にエクスポートされた `SYSTEM_PROMPT_DYNAMIC_BOUNDARY` 定数を挟んだ文字列の配列を渡すと、[カスタムプロンプトの静的部分をキャッシュ](/docs/ja/agent-sdk/modifying-system-prompts#cache-the-static-part-of-a-custom-prompt)できます。プリセットオブジェクト形式を使用する場合は、`append` を追加すると追加の指示で拡張でき、`excludeDynamicSections: true` を設定するとセッションごとのコンテキストを最初のユーザーメッセージに移動して[マシン間でのプロンプトキャッシュの再利用を改善](/docs/ja/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines)できます。`snapshot: false` を設定すると、[セッションが最初のリクエストで記録したプロンプトを再利用する](/docs/ja/agent-sdk/modifying-system-prompts#change-the-prompt-of-an-existing-session)代わりに、リクエストごとにプロンプトを再構築します。カスタムプロンプトで `snapshot` を設定するには、`{ type: 'custom', prompt }` 形式を渡します。`{ type: 'custom' }` 形式と `snapshot` フィールドには TypeScript Agent SDK v0.3.257 以降が必要です |604| `systemPrompt` | `string \| string[] \| { type: 'custom'; prompt: string \| string[]; snapshot?: boolean } \| { type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean; snapshot?: boolean }` | `undefined`（最小限のプロンプト） | システムプロンプトの設定。カスタムプロンプトには文字列を渡し、Claude Code のシステムプロンプトを使用するには `{ type: 'preset', preset: 'claude_code' }` を渡します。静的な部分とリクエストごとの部分の間にエクスポートされた `SYSTEM_PROMPT_DYNAMIC_BOUNDARY` 定数を挟んだ文字列の配列を渡すと、[カスタムプロンプトの静的な部分をキャッシュ](/docs/ja/agent-sdk/modifying-system-prompts#cache-the-static-part-of-a-custom-prompt)できます。プリセットのオブジェクト形式を使用する場合は、`append` を追加して追加の指示で拡張でき、`excludeDynamicSections: true` を設定するとセッションごとのコンテキストが最初のユーザーメッセージに移動し、[マシン間でのプロンプトキャッシュの再利用が向上します](/docs/ja/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines)。`snapshot: false` を設定すると、[セッションが最初のリクエストで記録したプロンプトを再利用する](/docs/ja/agent-sdk/modifying-system-prompts#change-the-prompt-of-an-existing-session)代わりに、リクエストごとにプロンプトを再構築します。カスタムプロンプトで `snapshot` を設定するには、`{ type: 'custom', prompt }` 形式を渡します。`{ type: 'custom' }` 形式と `snapshot` フィールドには TypeScript Agent SDK v0.3.257 以降が必要です |
600| `taskBudget` | `{ total: number }` | `undefined` | *アルファ版。* トークン単位の API 側のタスク予算。設定すると、モデルに残りのトークン予算が伝えられ、モデルはツールの使用ペースを調整して上限に達する前に作業をまとめられるようになります |605| `taskBudget` | `{ total: number }` | `undefined` | *アルファ版。* API 側のタスク予算（トークン単位）。設定すると、モデルに残りのトークン予算が伝えられ、モデルはツールの使用ペースを調整し、上限に達する前に作業をまとめることができます |
601| `thinking` | [`ThinkingConfig`](#thinkingconfig) | サポートされているモデルでは `{ type: 'adaptive' }` | Claude の思考/推論の動作を制御します。オプションについては [`ThinkingConfig`](#thinkingconfig) を参照してください |606| `thinking` | [`ThinkingConfig`](#thinkingconfig) | サポートされているモデルでは `{ type: 'adaptive' }` | Claude の思考/推論の動作を制御します。オプションについては [`ThinkingConfig`](#thinkingconfig) を参照してください |
602| `title` | `string` | `undefined` | セッションの表示タイトル。`resume` または `continue` で再開する場合は、再開されたセッションに保存されているタイトルが優先されます。既存のセッションのタイトルを変更するには [`renameSession()`](#renamesession) を使用します |607| `title` | `string` | `undefined` | セッションの表示タイトル。`resume` または `continue` で再開する場合は、再開されたセッションに永続化されているタイトルが優先されます。既存のセッションのタイトルを変更するには [`renameSession()`](#renamesession) を使用してください |
603| `toolAliases` | `Record<string, string>` | `undefined` | 組み込みツール名を MCP ツール名にマッピングし、Claude が組み込みツールの代わりに MCP 実装を呼び出すようにします。例: `{ Bash: 'mcp__workspace__bash' }` |608| `toolAliases` | `Record<string, string>` | `undefined` | 組み込みツール名を MCP ツール名にマッピングし、Claude が組み込みツールの代わりに MCP の実装を呼び出すようにします。例：`{ Bash: 'mcp__workspace__bash' }` |
604| `toolConfig` | [`ToolConfig`](#toolconfig) | `undefined` | 組み込みツールの動作の設定。詳細は [`ToolConfig`](#toolconfig) を参照してください |609| `toolConfig` | [`ToolConfig`](#toolconfig) | `undefined` | 組み込みツールの動作に関する設定。詳細は [`ToolConfig`](#toolconfig) を参照してください |
605| `tools` | `string[] \| { type: 'preset'; preset: 'claude_code' }` | `undefined` | ツールの設定。ツール名の配列を渡すか、プリセットを使用して Claude Code のデフォルトツールを取得します |610| `tools` | `string[] \| { type: 'preset'; preset: 'claude_code' }` | `undefined` | ツールの設定。ツール名の配列を渡すか、プリセットを使用して Claude Code のデフォルトツールを取得します |
606| `verbatimPrompts` | `boolean` | `false` | すべてのプロンプトを記述されたとおりに配信します。SDK は各ユーザーメッセージを `client_composed: true` 付きで送信します。これらのメッセージで Claude Code がスキップする処理については [`client_composed`](#sdkusermessage) を参照してください。プロンプトテキストにエンドユーザーが入力していないコンテンツが含まれる場合にこのオプションを使用します。ターンごとに制御するには、このオプションをオフのままにして、代わりに個々のストリーミングされるメッセージで `client_composed` を設定します。TypeScript Agent SDK v0.3.280 以降と Claude Code v2.1.248 以降が必要です。これらの SDK バージョンにバンドルされている Claude Code のバージョンは Claude Code の要件を満たしています |611| `verbatimPrompts` | `boolean` | `false` | すべてのプロンプトを記述どおりに配信します。SDK は各ユーザーメッセージを `client_composed: true` 付きで送信します。これらのメッセージで Claude Code がスキップする処理については [`client_composed`](#sdkusermessage) を参照してください。プロンプトのテキストにエンドユーザーが入力していないコンテンツが含まれる場合にこのオプションを使用します。ターンごとに制御するには、このオプションをオフのままにし、代わりに個々のストリーミングメッセージで `client_composed` を設定します。TypeScript Agent SDK v0.3.280 以降と Claude Code v2.1.248 以降が必要です。これらの SDK バージョンにバンドルされている Claude Code のバージョンは、Claude Code の要件を満たしています |
607 612
608<h4 id="handle-slow-or-stalled-api-responses">613<h4 id="handle-slow-or-stalled-api-responses">
609 遅い API レスポンスや停止した API レスポンスに対処する614 遅い、または停止した API レスポンスを処理する
610</h4>615</h4>
611 616
612CLI サブプロセスは、API のタイムアウトと停止検出を制御するいくつかの環境変数を読み取ります。これらは `env` オプションを通じて渡します。617CLI サブプロセスは、API のタイムアウトと停止検出を制御するいくつかの環境変数を読み取ります。これらは `env` オプションを通じて渡します：
613 618
614```typescript theme={null}619```typescript theme={null}
615import { query } from "@anthropic-ai/claude-agent-sdk";620import { query } from "@anthropic-ai/claude-agent-sdk";
627});632});
628```633```
629 634
630* `API_TIMEOUT_MS`: Anthropic クライアントのリクエストごとのタイムアウト（ミリ秒）。デフォルトは `600000` です。メインループとすべてのサブエージェントに適用されます。635* `API_TIMEOUT_MS`：Anthropic クライアントのリクエストごとのタイムアウト（ミリ秒）。デフォルトは `600000` です。メインループとすべてのサブエージェントに適用されます。
631* `CLAUDE_CODE_MAX_RETRIES`: API の最大再試行回数。デフォルトは `10` で、上限は `15` です。各再試行にはそれぞれ `API_TIMEOUT_MS` の時間枠が与えられるため、最悪の場合の経過時間はおおよそ `API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1)` にバックオフを加えた値になります。より長い障害を待ち続ける必要がある無人実行では、[`CLAUDE_CODE_RETRY_WATCHDOG=1`](/docs/ja/errors#tune-retry-behavior) を設定してください。これにより一時的な容量エラーが無期限に再試行され、Claude Code v2.1.199 以降ではその他の一時的なエラーのデフォルトが `300` に引き上げられ、この変数の上限が撤廃されます。636* `CLAUDE_CODE_MAX_RETRIES`：API の最大再試行回数。デフォルトは `10` で、上限は `15` です。各再試行にはそれぞれ独自の `API_TIMEOUT_MS` の時間枠が与えられるため、最悪の場合の経過時間はおおよそ `API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1)` にバックオフを加えた値になります。より長い障害を待ち続ける必要がある無人実行では、[`CLAUDE_CODE_RETRY_WATCHDOG=1`](/docs/ja/errors#tune-retry-behavior) を設定してください。これにより一時的な容量エラーは無制限に再試行され、Claude Code v2.1.199 以降では、その他の一時的なエラーのデフォルトが `300` に引き上げられ、この変数の上限が撤廃されます。
632* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`: サブエージェントの停止ウォッチドッグ。ストリームウォッチドッグが有効な間、デフォルトは `CLAUDE_STREAM_IDLE_TIMEOUT_MS` に 5 分を加えた値で、その変数を引き上げない限り `600000` になります。ストリームウォッチドッグが無効の場合、デフォルトは `600000` です。v2.1.257 より前は、デフォルトは常に `600000` でした。637* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`：サブエージェントの停止ウォッチドッグ。ストリームウォッチドッグが有効な間、デフォルトは `CLAUDE_STREAM_IDLE_TIMEOUT_MS` に 5 分を加えた値で、その変数を引き上げない限り `600000` になります。ストリームウォッチドッグが無効な場合、デフォルトは `600000` です。v2.1.257 より前は、デフォルトは常に `600000` でした。
633 638
634 タイマーはストリームイベントのたびにリセットされます。停止が発生すると、Claude Code はサブエージェントを中止し、停止を親に報告します。バックグラウンドのサブエージェントの場合は、さらにタスクを失敗としてマークし、部分的な結果があれば添付します。639 タイマーはストリームイベントごとにリセットされます。停止した場合、Claude Code はサブエージェントを中止し、停止を親に報告します。バックグラウンドのサブエージェントの場合は、タスクを失敗としてマークし、部分的な結果があれば添付します。
635* `CLAUDE_ENABLE_STREAM_WATCHDOG` と `CLAUDE_STREAM_IDLE_TIMEOUT_MS`: ヘッダーは到着したもののレスポンスボディのストリーミングが停止した場合にリクエストを中止するストリームウォッチドッグ。ウォッチドッグはすべてのプロバイダーでデフォルトで有効です。無効にするには `CLAUDE_ENABLE_STREAM_WATCHDOG=0` を設定します。`CLAUDE_STREAM_IDLE_TIMEOUT_MS` のデフォルトは `300000` で、この値が最小値として適用されます。中止後に Claude Code がレスポンスの進行状況に応じて何を行うかについては、[自動再試行](/docs/ja/errors#automatic-retries)で説明しています。640* `CLAUDE_ENABLE_STREAM_WATCHDOG` と `CLAUDE_STREAM_IDLE_TIMEOUT_MS`：ヘッダーは到着したもののレスポンス本文のストリーミングが止まった場合にリクエストを中止するストリームウォッチドッグ。ウォッチドッグはすべてのプロバイダーでデフォルトで有効です。無効にするには `CLAUDE_ENABLE_STREAM_WATCHDOG=0` を設定します。`CLAUDE_STREAM_IDLE_TIMEOUT_MS` のデフォルトは `300000` で、この値が最小値として適用されます。中止後に Claude Code がレスポンスの進行状況に応じて何を行うかについては、[自動再試行](/docs/ja/errors#automatic-retries)で説明しています。
636 641
637 `ANTHROPIC_BASE_URL` の背後にあるゲートウェイがキープアライブ ping でレスポンスを開いたままにしている間、ウォッチドッグはそのレスポンスを待ち続けます。その間も `includePartialMessages` を設定しているホストは `ping` [ストリームイベント](#sdkpartialassistantmessage)を受信し続けるため、無通信を理由にセッションをタイムアウトさせるのではなく、これらのフレームを生存確認として扱ってください。v2.1.257 より前は、最後の実際のストリームイベントから 5 分後にフレームが停止していました。642 `ANTHROPIC_BASE_URL` の背後にあるゲートウェイがキープアライブの ping でレスポンスを開いたまま保持している間、ウォッチドッグがそのレスポンスを待ち続けるとき、`includePartialMessages` を設定しているホストは `ping` [ストリームイベント](#sdkpartialassistantmessage)を受信し続けます。そのため、無応答を理由にセッションをタイムアウトさせるのではなく、これらのフレームを生存確認として扱ってください。v2.1.257 より前は、最後の実際のストリームイベントから 5 分後にフレームが停止していました。
638 643
639<h3 id="query-object">644<h3 id="query-object">
640 `Query` オブジェクト645 `Query` オブジェクト
696 701
697| メソッド | 説明 |702| メソッド | 説明 |
698| :- | :- |703| :- | :- |
699| `interrupt()` | クエリを中断します。ストリーミング入力モードでのみ使用できます。CLI が [`SDKSystemMessage.capabilities`](#sdksystemmessage) で `interrupt_receipt_v1` ケイパビリティを通知している場合、中断が到着した時点で保留中だったメッセージを一覧にした [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse) で解決されます。v2.1.205 より前の CLI では `undefined` で解決されます |704| `interrupt()` | クエリを中断します。ストリーミング入力モードでのみ使用できます。CLI が [`SDKSystemMessage.capabilities`](#sdksystemmessage) で `interrupt_receipt_v1` ケイパビリティを通知している場合、中断が届いた時点で保留中だったメッセージを列挙した [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse) で解決されます。v2.1.205 より前の CLI では `undefined` で解決されます |
700| `rewindFiles(userMessageId, options?)` | 指定したユーザーメッセージ時点の状態にファイルを復元します。変更をプレビューするには `{ dryRun: true }` を渡します。`enableFileCheckpointing: true` が必要です。[ファイルチェックポイント機能](/docs/ja/agent-sdk/file-checkpointing)を参照してください |705| `rewindFiles(userMessageId, options?)` | 指定したユーザーメッセージの時点の状態にファイルを復元します。変更をプレビューするには `{ dryRun: true }` を渡します。`enableFileCheckpointing: true` が必要です。[ファイルのチェックポイント機能](/docs/ja/agent-sdk/file-checkpointing)を参照してください |
701| `setPermissionMode()` | 権限モードを変更します（ストリーミング入力モードでのみ使用可能） |706| `setPermissionMode()` | 権限モードを変更します（ストリーミング入力モードでのみ使用可能） |
702| `setModel()` | モデルを変更します（ストリーミング入力モードでのみ使用可能）。`undefined` または文字列 `"default"` を渡すと、[Claude Code のデフォルトモデル](/docs/ja/model-config)にリセットされます |707| `setModel()` | モデルを変更します（ストリーミング入力モードでのみ使用可能）。`undefined` または文字列 `"default"` を渡すと、[Claude Code のデフォルトモデル](/docs/ja/model-config)にリセットされます |
703| `setMaxThinkingTokens()` | *非推奨:* 代わりに `thinking` オプションを使用してください。最大思考トークン数を変更します。`null` を渡すと思考がセッションのデフォルトにリセットされます。セッション途中の上書きはクリアされ、思考が無効になっているセッションでは思考は無効のままです |708| `setMaxThinkingTokens()` | *非推奨：* 代わりに `thinking` オプションを使用してください。最大思考トークン数を変更します。`null` を渡すと、思考がセッションのデフォルトにリセットされます。セッション途中での上書きは解除され、思考が無効になっているセッションでは思考はオフのままです |
704| `applyFlagSettings(settings)` | 実行時にセッションのフラグ設定レイヤーに設定をマージします（ストリーミング入力モードでのみ使用可能）。[`applyFlagSettings()`](#applyflagsettings) を参照してください |709| `applyFlagSettings(settings)` | 実行時にセッションのフラグ設定レイヤーに設定をマージします（ストリーミング入力モードでのみ使用可能）。[`applyFlagSettings()`](#applyflagsettings) を参照してください |
705| `updateSettings(source, settings)` | 許可リストに含まれる 1 つのキーをプロジェクトのローカル設定ファイルまたはユーザー設定ファイルに書き込み、その値を以降のセッションにも保持します。[`updateSettings()`](#updatesettings) を参照してください。TypeScript SDK v0.3.257 以降が必要です（Claude Code v2.1.257 がバンドルされています） |710| `updateSettings(source, settings)` | 許可リストに含まれる 1 つのキーをプロジェクトのローカル設定ファイルまたはユーザー設定ファイルに書き込み、その値が以降のセッションにも保持されるようにします。[`updateSettings()`](#updatesettings) を参照してください。Claude Code v2.1.257 をバンドルした TypeScript SDK v0.3.257 以降が必要です |
706| `initializationResult()` | サポートされているコマンド、モデル、アカウント情報、出力スタイルの設定を含む完全な初期化結果を返します |711| `initializationResult()` | サポートされているコマンド、モデル、アカウント情報、出力スタイルの設定を含む、完全な初期化結果を返します |
707| `reinitialize()` | 実行中の CLI に `initialize` コントロールリクエストを再送信し、キャッシュされた初回接続時の結果ではなく新しい結果を返します。切断後にセッションに再接続する場合など、トランスポートの途絶後に使用すると、保留中の権限リクエストが再び `canUseTool` コールバックに届きます。レスポンスが失われたリクエストは再度ディスパッチされるため、コールバックはリクエスト ID ごとに冪等にしてください。Claude Code v2.1.195 以降が必要です |712| `reinitialize()` | 実行中の CLI に `initialize` コントロールリクエストを再送信し、キャッシュされた初回接続時の結果ではなく新しい結果を返します。切断後にセッションに再接続する場合など、トランスポートの途絶後に使用すると、保留中の権限リクエストが再び `canUseTool` コールバックに届くようになります。レスポンスが失われたリクエストは再度ディスパッチされるため、コールバックはリクエスト ID ごとに冪等にしてください。Claude Code v2.1.195 以降が必要です |
708| `supportedCommands()` | 使用可能なコマンドを返します。Agent SDK v0.3.216 以降、このリストにはセッション途中のコマンドの変更が反映されます。[`SDKCommandsChangedMessage`](#sdkcommandschangedmessage) を参照してください |713| `supportedCommands()` | 利用可能なコマンドを返します。Agent SDK v0.3.216 以降では、リストにセッション途中でのコマンドの変更が反映されます。[`SDKCommandsChangedMessage`](#sdkcommandschangedmessage) を参照してください |
709| `supportedModels()` | 表示情報付きで使用可能なモデルを返します |714| `supportedModels()` | 表示情報付きで利用可能なモデルを返します |
710| `supportedAgents()` | 使用可能なサブエージェントを [`AgentInfo`](#agentinfo)`[]` として返します |715| `supportedAgents()` | 利用可能なサブエージェントを [`AgentInfo`](#agentinfo)`[]` として返します |
711| `mcpServerStatus()` | 接続されている MCP サーバーのステータスを [`McpServerStatus`](#mcpserverstatus)`[]` として返します |716| `mcpServerStatus()` | 接続されている MCP サーバーのステータスを [`McpServerStatus`](#mcpserverstatus)`[]` として返します |
712| `getContextUsage(opts?)` | セッションのコンテキストウィンドウの使用量をカテゴリ、スキル、ツールごとに分類した [`SDKControlGetContextUsageResponse`](#sdkcontrolgetcontextusageresponse) を返します。デフォルトの `detail` では、インタラクティブセッションで `/context` が表示するものと同じデータで、メッセージストリームに現れないトークンカウント API リクエストを使って計算されます。[これらのリクエストの扱い](#sdkcontrolgetcontextusageresponse)を参照してください。[`detail` オプション](#sdkcontrolgetcontextusageresponse)には Agent SDK v0.3.257 以降が必要です |717| `getContextUsage(opts?)` | セッションのコンテキストウィンドウの使用量をカテゴリ、スキル、ツール別に分類した [`SDKControlGetContextUsageResponse`](#sdkcontrolgetcontextusageresponse) を返します。デフォルトの `detail` では、対話型セッションで `/context` が表示するのと同じデータであり、メッセージストリームに表示されないトークンカウント API リクエストを使用して計算されます。[これらのリクエストの扱い](#sdkcontrolgetcontextusageresponse)を参照してください。[`detail` オプション](#sdkcontrolgetcontextusageresponse)には Agent SDK v0.3.257 以降が必要です |
713| `readFile(path, options?)` | セッションのファイルシステムからファイルを読み取ります。Claude Code はパスを `cwd` に対して解決します。提供されるファイルについては [`readFile()` が読み取れるもの](#what-readfile-can-read)に記載しています。読み取り上限（デフォルト 1 MB、最大 10 MB）を変更するには `{ maxBytes }` を、画像などのバイナリファイルには `{ encoding: 'base64' }` を渡します。[`SDKControlReadFileResponse`](#sdkcontrolreadfileresponse) で解決されるか、権限の拒否、ファイルが存在しない場合、またはトランスポートエラーの場合は `null` で解決されます。TypeScript SDK v0.2.121 以降が必要です |718| `readFile(path, options?)` | セッションのファイルシステムからファイルを読み取ります。Claude Code はパスを `cwd` を基準に解決します。提供されるファイルについては [`readFile()` で読み取れるもの](#what-readfile-can-read)に記載しています。読み取り上限を変更するには `{ maxBytes }` を（デフォルトは 1 MB、最大 10 MB）、画像などのバイナリファイルには `{ encoding: 'base64' }` を渡します。[`SDKControlReadFileResponse`](#sdkcontrolreadfileresponse) で解決されるか、権限の拒否、ファイルの欠如、またはトランスポートエラーの場合は `null` で解決されます。TypeScript SDK v0.2.121 以降が必要です |
714| `reloadPlugins(options?)` | ディスクからプラグインを再読み込みし、セッション途中にインストールまたは編集したプラグインを実行中のセッションに反映させます。セッションのコマンド、サブエージェント、プラグイン、MCP サーバーのステータスを一覧にした [`SDKControlReloadPluginsResponse`](#sdkcontrolreloadpluginsresponse) で解決されます。Agent SDK v0.2.85 以降が必要です。[`holdOnCacheImpact` オプション](#sdkcontrolreloadpluginsresponse)には Agent SDK v0.3.268 以降が必要です |719| `reloadPlugins(options?)` | ディスクからプラグインを再読み込みし、セッション途中でインストールまたは編集したプラグインが実行中のセッションに反映されるようにします。セッションのコマンド、サブエージェント、プラグイン、MCP サーバーのステータスを列挙した [`SDKControlReloadPluginsResponse`](#sdkcontrolreloadpluginsresponse) で解決されます。Agent SDK v0.2.85 以降が必要です。[`holdOnCacheImpact` オプション](#sdkcontrolreloadpluginsresponse)には Agent SDK v0.3.268 以降が必要です |
715| `reloadSkills()` | ディスクからスキルを再読み込みし、セッション途中に追加または編集したスキルを実行中のセッションで使用できるようにします。再読み込み後に使用可能なスキルを一覧にした [`SDKControlReloadSkillsResponse`](#sdkcontrolreloadskillsresponse) で解決されます。Agent SDK v0.3.163 以降が必要です |720| `reloadSkills()` | ディスクからスキルを再読み込みし、セッション途中で追加または編集したスキルが実行中のセッションで利用できるようにします。再読み込み後に利用可能なスキルを列挙した [`SDKControlReloadSkillsResponse`](#sdkcontrolreloadskillsresponse) で解決されます。Agent SDK v0.3.163 以降が必要です |
716| `reloadOutputStyles()` | ディスクから[出力スタイル](/docs/ja/output-styles)を再読み込みし、セッション途中に追加または編集したスタイルファイルを実行中のセッションで使用できるようにします。再読み込み後に使用可能なスタイル名を一覧にした [`SDKControlReloadOutputStylesResponse`](#sdkcontrolreloadoutputstylesresponse) で解決されます。Agent SDK v0.3.261 以降が必要です |721| `reloadOutputStyles()` | ディスクから[出力スタイル](/docs/ja/output-styles)を再読み込みし、セッション途中で追加または編集したスタイルファイルが実行中のセッションで利用できるようにします。再読み込み後に利用可能なスタイル名を列挙した [`SDKControlReloadOutputStylesResponse`](#sdkcontrolreloadoutputstylesresponse) で解決されます。Agent SDK v0.3.261 以降が必要です |
717| `accountInfo()` | アカウント情報を返します |722| `accountInfo()` | アカウント情報を返します |
718| `reconnectMcpServer(serverName)` | 名前を指定して MCP サーバーに再接続します。その名前が `.mcp.json` や `~/.claude.json` などの設定ファイル内のエントリにも一致する場合、Claude Code は設定ファイルのエントリではなく、[`mcpServers`](#options) または `setMcpServers()` で設定したサーバーに再接続します。この解決順序には Claude Code v2.1.257 以降が必要です |723| `reconnectMcpServer(serverName)` | 名前を指定して MCP サーバーに再接続します。名前が `.mcp.json` や `~/.claude.json` などの設定ファイル内のエントリにも一致する場合、Claude Code は設定ファイルのエントリではなく、[`mcpServers`](#options) または `setMcpServers()` で設定したサーバーに再接続します。この解決順序には Claude Code v2.1.257 以降が必要です |
719| `toggleMcpServer(serverName, enabled)` | `reconnectMcpServer()` と同じ名前解決で、名前を指定して MCP サーバーを有効化または無効化します。サーバーを無効にすると、接続が切断され、そのツールが削除されます。サーバーの種類ごとに必要な Claude Code のバージョンについては [`toggleMcpServer()`](#togglemcpserver) を参照してください |724| `toggleMcpServer(serverName, enabled)` | `reconnectMcpServer()` と同じ名前解決で、名前を指定して MCP サーバーを有効または無効にします。サーバーを無効にすると、そのサーバーは切断され、そのツールは削除されます。サーバーの種類ごとに必要な Claude Code のバージョンについては [`toggleMcpServer()`](#togglemcpserver) を参照してください |
720| `setMcpServers(servers)` | このセッションの MCP サーバーのセットを動的に置き換えます。追加および削除されたサーバーとエラーを示す [`McpSetServersResult`](#mcpsetserversresult) で解決されます |725| `setMcpServers(servers)` | このメソッドが管理する MCP サーバー（このメソッドで追加したサーバーと[インプロセスの SDK サーバー](#createsdkmcpserver)）を置き換えます。追加および削除されたサーバーとエラーを示す [`McpSetServersResult`](#mcpsetserversresult) で解決されます。他のどのサーバーが接続されたままになるかはそのセクションで説明しています |
721| `readMcpResource(serverName, uri)` | *アルファ版。* アプリケーションがツールのウィジェットをレンダリングできるように、接続されている MCP サーバーから MCP Apps の `ui://` リソースを 1 つ読み取ります。[`SDKControlMcpReadResourceResponse`](#sdkcontrolmcpreadresourceresponse) で解決されます。TypeScript Agent SDK v0.3.280 以降が必要です |726| `readMcpResource(serverName, uri)` | *アルファ版。* 接続された MCP サーバーから MCP Apps の `ui://` リソースを 1 つ読み取り、アプリケーションがツールのウィジェットを表示できるようにします。[`SDKControlMcpReadResourceResponse`](#sdkcontrolmcpreadresourceresponse) で解決されます。TypeScript Agent SDK v0.3.280 以降が必要です |
722| `streamInput(stream)` | マルチターンの会話のために、入力メッセージをクエリにストリーミングします |727| `streamInput(stream)` | マルチターン会話のために、入力メッセージをクエリにストリーミングします |
723| `stopTask(taskId)` | 実行中のバックグラウンドタスクを ID で停止します |728| `stopTask(taskId)` | ID を指定して実行中のバックグラウンドタスクを停止します |
724| `close()` | クエリを閉じ、基盤となるプロセスを終了します。クエリを強制的に終了し、すべてのリソースをクリーンアップします |729| `close()` | クエリを閉じ、基盤となるプロセスを終了します。クエリを強制的に終了し、すべてのリソースをクリーンアップします |
725 730
726<h4 id="applyflagsettings">731<h4 id="applyflagsettings">
727 `applyFlagSettings()`732 `applyFlagSettings()`
728</h4>733</h4>
729 734
730クエリを再起動せずに、実行中のセッションの[設定](/docs/ja/settings)を変更します。エージェントが信頼できない入力を読み取った後に `permissions` を厳しくする場合など、専用のセッターがない設定項目をセッション途中で変更する必要があるときに使用します。`setModel()` と `setPermissionMode()` はそれぞれのキー専用のセッターです。`applyFlagSettings()` は設定キーの任意のサブセットを受け付ける汎用的な形式で、ここで `model` を渡すと `setModel()` と同じように動作します。735クエリを再起動せずに、実行中のセッションの[設定](/docs/ja/settings)を変更します。エージェントが信頼できない入力を読み取った後に `permissions` を厳しくする場合など、専用のセッターがない設定をセッション途中で変更する必要があるときに使用します。`setModel()` と `setPermissionMode()` はそれら 2 つのキー専用のセッターです。`applyFlagSettings()` は設定キーの任意のサブセットを受け付ける汎用形式であり、ここで `model` を渡すと `setModel()` と同じように動作します。
731 736
732セッション途中で有効になるのは一部のキーのみです。737セッション途中で有効になるのは一部のキーのみです：
733 738
734* **次のターンで適用**: `effortLevel`、`ultracode`、`permissions`、`hooks`、`skillOverrides`、`fastMode`、`agent`。`agent` を切り替えると、そのエージェントのモデルの上書きとフックも次のターンで適用されます。そのシステムプロンプトは次のターンで適用されますが、[記録されたシステムプロンプトを再利用する](/docs/ja/agent-sdk/modifying-system-prompts#change-the-prompt-of-an-existing-session)セッションでは、セッションが圧縮された時点で適用されます。739* **次のターンで適用されるもの**：`effortLevel`、`ultracode`、`permissions`、`hooks`、`skillOverrides`、`fastMode`、`agent`。`agent` を切り替えると、そのエージェントのモデルの上書きとフックも次のターンで適用されます。そのシステムプロンプトは次のターンで適用されるか、[記録されたシステムプロンプトを再利用する](/docs/ja/agent-sdk/modifying-system-prompts#change-the-prompt-of-an-existing-session)セッションではセッションが圧縮された時点で適用されます。
735* **現在のターン中に適用**: `model`。Claude がターンの作業中に `model` を切り替えると、Claude がすでに生成中の応答は古いモデルで完了し、Claude Code が次にモデルを呼び出すところから始まるターンの残りの部分では新しいモデルが使用されます。サブエージェントは独自のモデルを維持します。v2.1.212 より前は、ターン途中の切り替えは次のターンまで待機していました。740* **現在のターン中に適用されるもの**：`model`。Claude がターンの処理中に `model` を切り替えた場合、Claude がすでに生成中の応答は古いモデルで完了し、Claude Code がモデルに対して行う次の呼び出しから、ターンの残りの部分では新しいモデルが使用されます。サブエージェントは独自のモデルを保持します。v2.1.212 より前は、ターン途中の切り替えは次のターンまで待機していました。
736* **セッション途中では効果なし**: システムプロンプトのオプション。これらは起動時に 1 回だけ解決されるため、呼び出しが成功しても実行中のセッションは元の値を保持します。変更するには、新しいセッションを開始してください。741* **セッション途中では効果がないもの**：システムプロンプトのオプション。これらは起動時に一度だけ解決されるため、呼び出し自体は成功しても、実行中のセッションは元の値を保持します。変更するには、新しいセッションを開始してください。
737 742
738`effortLevel` は [effort レベル](/docs/ja/model-config#adjust-effort-level)の名前を受け付けます。また、[ultracode](/docs/ja/workflows#let-claude-decide-with-ultracode) をオンにした状態で `xhigh` の effort を要求する `"ultracode"` も受け付けます。`applyFlagSettings()` は `effortLevel` をこの値なしで宣言しているため、TypeScript で同じ結果を得るには `{ ultracode: true, effortLevel: "xhigh" }` を渡すか、セッションの現在の effort レベルのまま ultracode をオンにするには [`ultracode`](/docs/ja/settings-reference#ultracode) キーのみを渡します。`ultracode` 値には Claude Code v2.1.203 以降が必要で、`applyFlagSettings()` でのみ受け付けられ、設定ファイルの `effortLevel` キーでは受け付けられません。v2.1.284 より前は、`ultracode` キーのみを指定した場合もレベルが `xhigh` に設定されていました。743`effortLevel` は [effort レベル](/docs/ja/model-config#adjust-effort-level)の名前を受け付けます。また、[ultracode](/docs/ja/workflows#let-claude-decide-with-ultracode) をオンにした状態で `xhigh` の effort を要求する `"ultracode"` も受け付けます。`applyFlagSettings()` は `effortLevel` をこの値を含まない形で宣言しているため、TypeScript で同じ結果を得るには `{ ultracode: true, effortLevel: "xhigh" }` を渡すか、セッションの現在の effort レベルのまま ultracode をオンにするには [`ultracode`](/docs/ja/settings-reference#ultracode) キーのみを渡してください。`ultracode` という値には Claude Code v2.1.203 以降が必要であり、`applyFlagSettings()` でのみ受け付けられ、設定ファイルの `effortLevel` キーでは受け付けられません。v2.1.284 より前は、`ultracode` キーのみを渡した場合もレベルが `xhigh` に設定されていました。
739 744
740値はフラグ設定レイヤーに書き込まれ、起動時に `query()` のインライン `settings` オプションで設定された内容の上にマージされます。これは[このページの優先順位セクション](#settings-precedence)でプログラムによるオプションと呼んでいるのと同じ層です。745値はフラグ設定レイヤーに書き込まれ、`query()` のインライン `settings` オプションが起動時に設定した内容の上にマージされます。これは、[このページの優先順位のセクション](#settings-precedence)でプログラムによるオプションと呼んでいるのと同じ階層です。
741 746
742連続した呼び出しでは、トップレベルのキーが浅くマージされます。`{ permissions: {...} }` を指定した 2 回目の呼び出しは、前回の呼び出しの `permissions` オブジェクトに深くマージされるのではなく、オブジェクト全体を置き換えます。747連続した呼び出しでは、トップレベルのキーが浅くマージされます。`{ permissions: {...} }` を指定した 2 回目の呼び出しは、前回の呼び出しの `permissions` オブジェクトにディープマージするのではなく、オブジェクト全体を置き換えます。
743 748
744`applyFlagSettings()` で設定したキーをクリアするには、そのキーに `null` を渡します。ほとんどのキーはその後、まず起動時に `query()` の `settings` オプションで設定された値に、次に優先順位の低いソースにフォールバックします。クリアされた `model` は、設定ファイルで `model` が設定されている場合でも、[Claude Code のデフォルトモデル](/docs/ja/model-config)にリセットされます。`undefined` を渡しても、JSON シリアライズで削除されるため効果はありません。749`applyFlagSettings()` で設定したキーをクリアするには、そのキーに `null` を渡します。ほとんどのキーは、まず `query()` の `settings` オプションが起動時に設定した値にフォールバックし、次に優先順位の低いソースにフォールバックします。クリアされた `model` は、設定ファイルで `model` が設定されている場合でも、[Claude Code のデフォルトモデル](/docs/ja/model-config)にリセットされます。`undefined` を渡しても、JSON シリアライズで削除されるため効果はありません。
745 750
746`model` 以外に、フォールバックする代わりにセッションの状態をリセットするキーが 3 つあります。751`model` 以外に 3 つのキーは、フォールバックする代わりにセッションの状態をリセットします：
747 752
748* `effortLevel: null` は、`query()` の `effort` オプションや設定ファイルの `effortLevel` ではなく、セッションをモデルのデフォルトの effort レベルに戻します。753* `effortLevel: null` は、`query()` の `effort` オプションや設定ファイルの `effortLevel` ではなく、セッションをモデルのデフォルトの effort レベルに戻します。
749* `agent: null` は、`query()` の `agent` オプションや設定ファイルの `agent` を復元するのではなく、次のターンからエージェントなしでメインスレッドを実行します。クリアされたエージェントが独自のモデルを適用していた場合、セッションは起動時に解決されたモデルに戻ります。754* `agent: null` は、`query()` の `agent` オプションや設定ファイルの `agent` を復元するのではなく、次のターンからエージェントなしでメインスレッドを実行します。クリアされたエージェントが独自のモデルを適用していた場合、セッションは起動時に解決したモデルに戻ります。
750* `ultracode: null` は、設定ファイルの `ultracode` 値を復元するのではなく、`false` と同様に ultracode をオフにします。セッションは現在の effort レベルを維持するため、変更するには同じ呼び出しで `effortLevel` を渡してください。755* `ultracode: null` は、設定ファイルの `ultracode` の値を復元するのではなく、`false` と同様に ultracode をオフにします。セッションは現在の effort レベルを維持するため、変更するには同じ呼び出しで `effortLevel` を渡してください。
751 756
752`setModel()` や `setPermissionMode()` と同じ制約で、ストリーミング入力モードでのみ使用できます。757`setModel()` および `setPermissionMode()` と同じ制約で、ストリーミング入力モードでのみ使用できます。
753 758
754以下の例では、セッション途中でアクティブなモデルを切り替え、その後上書きをクリアしてモデルを [Claude Code のデフォルトモデル](/docs/ja/model-config)にリセットします。759以下の例では、セッション途中でアクティブなモデルを切り替え、その後上書きをクリアしてモデルを [Claude Code のデフォルトモデル](/docs/ja/model-config)にリセットします。
755 760
766```771```
767 772
768<Note>773<Note>
769 `applyFlagSettings()` は TypeScript のみで使用できます。Python SDK には同等のメソッドはありません。774 `applyFlagSettings()` は TypeScript 専用です。Python SDK には同等のメソッドはありません。
770</Note>775</Note>
771 776
772<h4 id="updatesettings">777<h4 id="updatesettings">
773 `updateSettings()`778 `updateSettings()`
774</h4>779</h4>
775 780
776許可リストに含まれる 1 つのキーをディスク上の設定ファイルに書き込み、そのソースを読み込む以降のセッションにも値を保持します。各ソースは文字列値を持つ 1 つのキーを受け付けます。781許可リストに含まれる 1 つのキーをディスク上の設定ファイルに書き込み、そのソースを読み込む以降のセッションでも値が保持されるようにします。各ソースは、文字列値を持つ 1 つのキーを受け付けます：
777 782
778* **`"localSettings"`**: `outputStyle` を受け付け、プロジェクトのローカル設定ファイル `.claude/settings.local.json` にマージします。新しいスタイルはセッションの次のリクエストから有効になります。783* **`"localSettings"`**：`outputStyle` を受け付け、プロジェクトのローカル設定ファイル `.claude/settings.local.json` にマージします。新しいスタイルはセッションの次のリクエストで有効になります。
779* **`"userSettings"`**: `effortLevel` を受け付け、セッションの現在のモデルのデフォルトの [effort レベル](/docs/ja/model-config#adjust-effort-level)として、ユーザー設定ファイルの [`modelSettings`](/docs/ja/settings-reference#modelsettings) の下に保存します。`max` はセッション限定であるため、`max` を渡しても何も書き込まれません。いずれの場合も実行中のセッションは現在の effort レベルを維持するため、それも変更したい場合は [`applyFlagSettings()`](#applyflagsettings) を呼び出してください。このソースには TypeScript SDK v0.3.277 以降が必要です（Claude Code v2.1.277 がバンドルされています）。784* **`"userSettings"`**：`effortLevel` を受け付け、ユーザー設定ファイルの [`modelSettings`](/docs/ja/settings-reference#modelsettings) の下に、セッションの現在のモデルのデフォルトの [effort レベル](/docs/ja/model-config#adjust-effort-level)として保存します。`max` はセッション限定のため、`max` を渡しても何も書き込まれません。いずれの場合も実行中のセッションは現在の effort レベルを維持するため、それも変更したい場合は [`applyFlagSettings()`](#applyflagsettings) を呼び出してください。このソースには、Claude Code v2.1.277 をバンドルした TypeScript SDK v0.3.277 以降が必要です。
780 785
781リクエストにその他のキーが含まれている場合、セッションがリモートトランスポート上で実行されている場合、およびセッションの [`settingSources`](#options) が指定したソースを除外している場合、呼び出しは拒否されます。キーの削除はサポートされていません。786リクエストにその他のキーが含まれている場合、セッションがリモートトランスポート上で実行されている場合、およびセッションの [`settingSources`](#options) が指定したソースを除外している場合、呼び出しは拒否されます。キーの削除はサポートされていません。
782 787
784 `toggleMcpServer()`789 `toggleMcpServer()`
785</h4>790</h4>
786 791
787サーバーを無効にすると、接続が切断され、そのツールがセッションから削除されます。セッション途中で追加したサーバーとインプロセスサーバーについては、Claude Code のバージョンによって次のように異なります。792サーバーを無効にすると、そのサーバーは切断され、そのツールはセッションから削除されます。セッション途中で追加したサーバーとインプロセスサーバーについては、これは Claude Code のバージョンに依存します：
788 793
789* `setMcpServers()` でセッション途中に追加した stdio、SSE、または HTTP サーバー: ツールの削除には Claude Code v2.1.285 以降が必要です。794* `setMcpServers()` でセッション途中に追加した stdio、SSE、または HTTP サーバー：そのツールを削除するには Claude Code v2.1.285 以降が必要です。
790* [`createSdkMcpServer()`](#createsdkmcpserver) で作成したインプロセスサーバー（`mcpServers` で渡したか `setMcpServers()` で渡したかを問わない）: 接続の切断とツールの削除には Claude Code v2.1.286 以降が必要です。また、無効にすると実行中のツール呼び出しも失敗するため、Claude はハンドラーが戻るのを待たずに、それぞれについてエラー結果を即座に受け取ります。795* [`createSdkMcpServer()`](#createsdkmcpserver) で作成したインプロセスサーバー（`mcpServers` で渡したか `setMcpServers()` で渡したかを問わない）：切断してそのツールを削除するには Claude Code v2.1.286 以降が必要です。無効にすると、まだ実行中のそのサーバーのツール呼び出しも失敗するため、Claude はハンドラーが戻るのを待たずに、それぞれについてエラー結果を直ちに受け取ります。
791 796
792<h3 id="warmquery">797<h3 id="warmquery">
793 `WarmQuery`798 `WarmQuery`
794</h3>799</h3>
795 800
796[`startup()`](#startup) が返すハンドルです。サブプロセスはすでに生成および初期化されているため、このハンドルで `query()` を呼び出すと、起動の遅延なしに準備済みのプロセスへプロンプトが直接書き込まれます。801[`startup()`](#startup) が返すハンドルです。サブプロセスはすでに起動および初期化されているため、このハンドルで `query()` を呼び出すと、起動の遅延なしに準備済みのプロセスへプロンプトが直接書き込まれます。
797 802
798```typescript theme={null}803```typescript theme={null}
799interface WarmQuery extends AsyncDisposable {804interface WarmQuery extends AsyncDisposable {
808 813
809| メソッド | 説明 |814| メソッド | 説明 |
810| :- | :- |815| :- | :- |
811| `query(prompt)` | 事前にウォームアップされたサブプロセスにプロンプトを送信し、[`Query`](#query-object) を返します。`WarmQuery` ごとに 1 回だけ呼び出せます |816| `query(prompt)` | 事前ウォームアップされたサブプロセスにプロンプトを送信し、[`Query`](#query-object) を返します。`WarmQuery` ごとに 1 回だけ呼び出せます |
812| `close()` | プロンプトを送信せずにサブプロセスを閉じます。不要になったウォームクエリを破棄する場合に使用します |817| `close()` | プロンプトを送信せずにサブプロセスを閉じます。不要になったウォームクエリを破棄する場合に使用します |
813 818
814`WarmQuery` は `AsyncDisposable` を実装しているため、`await using` と組み合わせて自動クリーンアップに使用できます。819`WarmQuery` は `AsyncDisposable` を実装しているため、`await using` と組み合わせて自動クリーンアップに使用できます。
817 `SpareProcess`822 `SpareProcess`
818</h3>823</h3>
819 824
820*アルファ版。* [`prewarm()`](#prewarm) が返すハンドルで、まだセッションにバインドされておらず、1 回だけ取得（claim）できる起動済みの Claude Code プロセスです。TypeScript Agent SDK v0.3.282 以降が必要です。825*アルファ版。* [`prewarm()`](#prewarm) が返すハンドルです。まだセッションにバインドされておらず、1 回だけ取得（claim）できる起動済みの Claude Code プロセスです。TypeScript Agent SDK v0.3.282 以降が必要です。
821 826
822```typescript theme={null}827```typescript theme={null}
823interface SpareProcess extends AsyncDisposable {828interface SpareProcess extends AsyncDisposable {
837 842
838| メンバー | 説明 |843| メンバー | 説明 |
839| :- | :- |844| :- | :- |
840| `claim({ prompt, options })` | スペアを `options.cwd` 内のセッションにバインドし、最初のメッセージを送信します。`query()` と同様に [`Query`](#query-object) を同期的に返します。1 回だけ呼び出せます |845| `claim({ prompt, options })` | スペアを `options.cwd` のセッションにバインドし、最初のメッセージを送信します。`query()` と同様に、[`Query`](#query-object) を同期的に返します。1 回だけ呼び出せます |
841| `claimed` | Claude Code が claim を受け入れると、セッションの作業ディレクトリと ID で解決されます。Claude Code が claim を拒否した場合、プロセスが先に終了したか閉じられた場合、およびセッションが要求した `model` または `maxThinkingTokens` なしで実行されている場合（`option_not_applied` で始まるメッセージ）に拒否されます |846| `claimed` | Claude Code が claim を受け入れると、セッションの作業ディレクトリと ID で解決されます。Claude Code が claim を拒否した場合、プロセスが先に終了したか閉じられた場合、および（`option_not_applied` で始まるメッセージとともに）要求した `model` または `maxThinkingTokens` なしでセッションが実行されている場合は拒否されます |
842| `exited` | claim されたかどうかにかかわらず、プロセスが終了すると確定します。claim する前に終了したスペアは置き換えてください |847| `exited` | claim されたかどうかにかかわらず、プロセスが終了したときに確定します。claim する前に終了したスペアは置き換えてください |
843| `close()` | プロセスを終了します。claim 前の場合はスペアを破棄し、`claimed` を拒否します |848| `close()` | プロセスを終了します。claim の前であれば、スペアを破棄して `claimed` を拒否します |
844 849
845`options.cwd` は必須です。claim では、`additionalDirectories`、`model`、`permissionMode`、`maxThinkingTokens`、`settings` でのフラグ設定オーバーレイ、`appendSystemPrompt`、`title`、`agents`、`env` でのセッションごとのトークンも設定できます。850`options.cwd` は必須です。claim では、`additionalDirectories`、`model`、`permissionMode`、`maxThinkingTokens`、`settings` でのフラグ設定のオーバーレイ、`appendSystemPrompt`、`title`、`agents`、および `env` でのセッションごとのトークンも設定できます。
846 851
847Claude Code は、存在しないフォルダーや、プロジェクト設定で `env`、`agent`、または `model` が設定されているフォルダーなどの場合に claim を拒否することがあります。`claimed` が `option_not_applied` で始まるメッセージで拒否された場合、セッションは要求した `model` または `maxThinkingTokens` なしで実行されています。その他の拒否の場合はプロンプトが実行されていないため、代わりに `query()` でセッションを開始してください。852Claude Code は、存在しないフォルダや、プロジェクト設定で `env`、`agent`、または `model` を設定しているフォルダなどに対して claim を拒否することがあります。拒否された後、`claim()` がすでに送信したプロンプトは `not_claimed` で始まるテキストのエラー結果を受け取り、返されたクエリはその後スローします。スローを越えて処理を続けるには、クエリのループを try ブロックで囲んでください。`claimed` が `option_not_applied` で始まるメッセージとともに拒否された場合、セッションは要求した `model` または `maxThinkingTokens` なしで実行されています。それ以外の拒否の後はプロンプトは実行されていないため、代わりに `query()` でセッションを開始してください。
848 853
849<h3 id="sdkcontrolinitializeresponse">854<h3 id="sdkcontrolinitializeresponse">
850 `SDKControlInitializeResponse`855 `SDKControlInitializeResponse`
874};879};
875```880```
876 881
877`hooks_applied` は、`initialize` リクエストに含まれていた `hooks` を Claude Code が登録したかどうかを示します。SDK はこのリクエストをセッション開始時に 1 回送信し、[`reinitialize()`](#query-object) を呼び出すたびに再度送信します。このフィールドには Agent SDK v0.3.238 以降が必要です。882`hooks_applied` は、`initialize` リクエストに含まれていた `hooks` を Claude Code が登録したかどうかを報告します。SDK はこのリクエストをセッション開始時に 1 回送信し、[`reinitialize()`](#query-object) を呼び出すたびに再度送信します。このフィールドには Agent SDK v0.3.238 以降が必要です。
878 883
879リクエストにフックが含まれていなかった場合、Claude Code はこのフィールドを省略します。リクエストにフックが含まれていた場合、値はそのリクエストがセッションの最初の initialize かどうか、また繰り返しの initialize の場合はどのようにセッションに到達したかによって決まります。884リクエストにフックが含まれていなかった場合、Claude Code はこのフィールドを省略します。リクエストにフックが含まれていた場合、値はそのリクエストがセッションの最初の initialize かどうか、また繰り返しの initialize の場合はそれがどのようにセッションに届いたかによって決まります：
880 885
881* `true`: Claude Code がフックを登録しました。セッションの最初の initialize はこの値を返します。CLI の stdin を介して送信された繰り返しの initialize も `true` を返します。その場合、新しいリクエストのフックが以前に登録されたフックを置き換えます。886* `true`：Claude Code がフックを登録しました。セッションの最初の initialize はこの値を返します。CLI の stdin を介して送信された繰り返しの initialize も `true` を返します。その場合、新しいリクエストのフックが以前に登録されたフックを置き換えます。
882* `false`: Claude Code はフックを無視しました。リモートセッションに送信された繰り返しの initialize はこの値を返すため、セッションに参加した 2 番目のクライアントは、最初のクライアントが登録したフックを置き換えることができません。887* `false`：Claude Code はフックを無視しました。リモートセッションに送信された繰り返しの initialize はこの値を返すため、セッションに参加した 2 番目のクライアントが最初のクライアントが登録したフックを置き換えることはできません。
883 888
884Agent SDK v0.3.238 より前は、レスポンスにこのフィールドは含まれず、Claude Code は繰り返しのすべての initialize で `hooks` を無視していました。889Agent SDK v0.3.238 より前は、レスポンスにこのフィールドが含まれることはなく、Claude Code は繰り返しの initialize のたびに `hooks` を無視していました。
885 890
886リクエストの `sdkMcpServerManifests` フィールドとレスポンスの `sdk_mcp_manifests_parked` フィールドは、[`createSdkMcpServer()`](#createsdkmcpserver) で作成したインプロセスの [SDK MCP サーバー](/docs/ja/agent-sdk/custom-tools)のためのものです。アプリケーションがどちらのフィールドを設定したり読み取ったりすることもありません。891リクエストの `sdkMcpServerManifests` フィールドとレスポンスの `sdk_mcp_manifests_parked` フィールドは、[`createSdkMcpServer()`](#createsdkmcpserver) で作成したインプロセスの [SDK MCP サーバー](/docs/ja/agent-sdk/custom-tools)用です。アプリケーションがこれらのフィールドを設定したり読み取ったりすることはありません。
887 892
888レスポンスは常に `fast_mode_state` を報告し、何かが [fast mode](/docs/ja/fast-mode) をブロックしている場合は `fast_mode_disabled_reason` がその理由コードを併せて伝えるため、可用性を再導出することなくブロックされた状態を説明できます。どちらの動作にも Claude Code v2.1.219 以降が必要です。v2.1.219 より前は、fast mode が利用できない場合にレスポンスは `fast_mode_state` を省略し、理由を含むことはありませんでした。理由コードとその意味については、結果メッセージの [`fast_mode_disabled_reason`](#sdkresultmessage) を参照してください。893レスポンスは常に `fast_mode_state` を報告し、何かが [fast mode](/docs/ja/fast-mode) をブロックしている場合は、`fast_mode_disabled_reason` がその理由コードを併せて伝えるため、利用可否を改めて導出しなくても、ブロックされた状態を説明できます。どちらの動作にも Claude Code v2.1.219 以降が必要です。v2.1.219 より前は、fast mode が利用できない場合にレスポンスは `fast_mode_state` を省略し、理由を含めることもありませんでした。理由コードとその意味については、結果メッセージの [`fast_mode_disabled_reason`](#sdkresultmessage) を参照してください。
889 894
890成功した `initialize` のコントロールレスポンスのラッパーには、`pending_permission_requests` 配列も含まれます。このフィールドはレスポンスラッパー自体にあり、上記の `SDKControlInitializeResponse` ペイロード内にはありません。各エントリは完全な `control_request` メッセージで、実行中にセッションが権限リクエストとしてストリーミングするのと同じ `{ type: "control_request", request_id, request }` の形をしています。895成功した `initialize` のコントロールレスポンスのラッパーには、`pending_permission_requests` 配列も含まれます。このフィールドはレスポンスラッパー自体にあり、上記の `SDKControlInitializeResponse` ペイロード内にはありません。各エントリは完全な `control_request` メッセージであり、セッションが実行中に権限リクエストとしてストリーミングするものと同じ `{ type: "control_request", request_id, request }` の形式を持ちます。
891 896
892この配列には、この Claude Code プロセスが発行してまだ解決されていない権限リクエストが一覧表示されます。SDK はこの配列を読み取り、各エントリを [`canUseTool`](#canusetool) コールバックにディスパッチします。これは、トランスポートの途絶後に [`reinitialize()`](#query-object) がトリガーするのと同じ再配信です。エントリは、接続が切断される前にコールバックがすでに受け取ったリクエストを繰り返す場合があるため、繰り返されるリクエスト ID は冪等に処理してください。897この配列には、この Claude Code プロセスが発行してまだ解決されていない権限リクエストが列挙されます。SDK がこの配列を読み取り、各エントリを [`canUseTool`](#canusetool) コールバックにディスパッチします。これは、トランスポートの途絶後に [`reinitialize()`](#query-object) がトリガーするのと同じ再配信です。エントリは接続が切れる前にコールバックがすでに受け取ったリクエストを繰り返す場合があるため、繰り返されるリクエスト ID は冪等に処理してください。
893 898
894この配列は成功した `initialize` レスポンスに常に存在し、このプロセスに未解決の権限リクエストがない場合は空になります。Claude Code v2.1.268 以降が必要です。以前のバージョンではこのフィールドが省略される場合があるため、ワイヤープロトコルを自分で解析する場合は、フィールドがないことを保留中のものがない証拠としてではなく、古い CLI であることの表れとして扱ってください。899この配列は成功した `initialize` レスポンスに常に存在し、このプロセスに未解決の権限リクエストがない場合は空です。Claude Code v2.1.268 以降が必要です。それより前のバージョンではこのフィールドが省略される場合があるため、ワイヤープロトコルを自分で解析する場合は、フィールドがないことを保留中のものがない証拠としてではなく、古い CLI であることの表れとして扱ってください。
895 900
896<h3 id="sdkcontrolinterruptresponse">901<h3 id="sdkcontrolinterruptresponse">
897 `SDKControlInterruptResponse`902 `SDKControlInterruptResponse`
898</h3>903</h3>
899 904
900中断の受領通知です。[`SDKSystemMessage.capabilities`](#sdksystemmessage) で `interrupt_receipt_v1` ケイパビリティを通知している CLI で、[`interrupt()`](#query-object) が解決される値です。Claude Code v2.1.205 以降が必要です。それ以前の CLI は空の成功ペイロードで中断に応答するため、`interrupt()` は `undefined` に解決されます。905中断の受領通知です。[`SDKSystemMessage.capabilities`](#sdksystemmessage) で `interrupt_receipt_v1` ケイパビリティを通知している CLI において、[`interrupt()`](#query-object) が解決される値です。Claude Code v2.1.205 以降が必要です。それより前の CLI は空の成功ペイロードで中断に応答するため、`interrupt()` は `undefined` に解決されます。
901 906
902```typescript theme={null}907```typescript theme={null}
903type SDKControlInterruptResponse = {908type SDKControlInterruptResponse = {
906};911};
907```912```
908 913
909`still_queued` は、中断が到着した時点で保留中だったユーザーメッセージの UUID を一覧表示します。これには、まだキューにあるメッセージと、Claude Code が次のターンのためにすでにキューから取り出していたメッセージが含まれます。セッションの最初のターンが開始された後は、先にキャンセルしない限り、Claude Code は一覧にあるメッセージを中断後に処理し、複数のメッセージを 1 つのターンにまとめることがあります。最初のターンが開始される前に中断した場合、Claude Code はそのターンが開始されるとすぐに中止し、そのターン内の一覧にあるメッセージには応答がありません。914`still_queued` には、中断が届いた時点で保留中だったユーザーメッセージの UUID が列挙されます。これには、まだキューにあるメッセージに加え、Claude Code が次のターンのためにすでにキューから取り出したメッセージも含まれます。セッションの最初のターンが開始された後であれば、Claude Code は先にキャンセルしない限り中断後に列挙されたメッセージを処理し、複数のメッセージを 1 つのターンにまとめることがあります。最初のターンが開始される前に中断した場合、Claude Code はそのターンを開始直後に中止し、そのターンに含まれる列挙されたメッセージは応答を受け取りません。
910 915
911受領通知を使用して、何かを再送信するかどうかを判断してください。キャンセルしなかった一覧のメッセージは、応答があるかどうかにかかわらず会話に入るため、再送信すると Claude に 2 回配信されることになります。916何かを再送信するかどうかの判断には、この受領通知を使用してください。キャンセルしなかった列挙されたメッセージは、応答を受け取るかどうかにかかわらず会話に入るため、再送信すると Claude に 2 回届くことになります。
912 917
913一覧を解釈する際は、次の注意点に留意してください。918リストは次の注意点を踏まえて解釈してください：
914 919
915* UUID 付きでキューに入れられたメッセージのみが表示されます。空の配列は、他に何も実行されないことを意味するわけではありません。920* UUID 付きでキューに入れられたメッセージのみが表示されます。空の配列は、他に何も実行されないことを意味するわけではありません。
916* メインスレッドのメッセージのみが一覧表示されます。サブエージェント宛てのメッセージは対象外です。921* メインスレッドのメッセージのみが列挙されます。サブエージェント宛てのメッセージは対象外です。
917* 一覧には、[スケジュールタスク](/docs/ja/scheduled-tasks)のトリガーなど、クライアントが送信していない UUID が含まれる場合があります。認識できない UUID はエラーとして扱わず、無視してください。922* リストには、[スケジュールタスク](/docs/ja/scheduled-tasks)のトリガーなど、クライアントが送信していない UUID が含まれる場合があります。認識できない UUID はエラーとして扱わず、無視してください。
918 923
919`interrupt()` を介さずに CLI のコントロールプロトコルを直接操作するクライアントは、`interrupt` コントロールリクエストに `cancel_queued: true` を設定できます。Claude Code v2.1.219 以降は、[`SDKSystemMessage.capabilities`](#sdksystemmessage) の `interrupt_cancel_queued_v1` ケイパビリティでサポートを通知します。古い CLI はこのフィールドを無視し、キュー内のメッセージは通常どおり実行されます。このような中断は、本来 `still_queued` に一覧表示されるはずのすべてのメッセージもキャンセルします。受領通知ではそれらが代わりに `cancelled` に一覧表示され、`still_queued` は空になり、いずれも実行されません。924`interrupt()` を介さずに CLI のコントロールプロトコルを直接操作するクライアントは、`interrupt` コントロールリクエストに `cancel_queued: true` を設定できます。Claude Code v2.1.219 以降は [`SDKSystemMessage.capabilities`](#sdksystemmessage) の `interrupt_cancel_queued_v1` ケイパビリティでサポートを通知します。それより古い CLI はこのフィールドを無視し、キュー内のメッセージを通常どおり実行させます。このような中断では、本来 `still_queued` に列挙されるはずのすべてのメッセージもキャンセルされます。受領通知ではそれらが代わりに `cancelled` に列挙され、`still_queued` は空になり、いずれも実行されません。
920 925
921`cancelled` の一覧にも `still_queued` と同じ注意点があります。`interrupt()` メソッドは `cancel_queued` を送信しないため、このメソッドが解決する受領通知には `cancelled` は含まれません。926`cancelled` リストには `still_queued` と同じ注意点が当てはまります。`interrupt()` メソッドは `cancel_queued` を送信しないため、このメソッドが解決する受領通知には `cancelled` は含まれません。
922 927
923受領通知は中断が処理された時点で取得されたスナップショットであり、正常な中断の場合は中断されたターンの [`SDKResultMessage`](#sdkresultmessage) より前に到着します。その結果の後にキューを調べるのではなく、受領通知を読み取ってください。ループは次のキュー内のターンをすぐに開始するため、結果の後に調べるキューはすでに変化しています。928受領通知は中断が処理された時点のスナップショットであり、正常な中断では、中断されたターンの [`SDKResultMessage`](#sdkresultmessage) より前に届きます。その結果の後にキューを調べるのではなく、受領通知を読み取ってください。ループは次のキュー内のターンを直ちに開始するため、結果の後に調べるキューはすでに変化しています。
924 929
925<h3 id="sdkcontrolgetcontextusageresponse">930<h3 id="sdkcontrolgetcontextusageresponse">
926 `SDKControlGetContextUsageResponse`931 `SDKControlGetContextUsageResponse`
927</h3>932</h3>
928 933
929[`getContextUsage()`](#query-object) の戻り値の型です。デフォルトの `detail` では、インタラクティブセッションで Claude Code が `/context` コマンドに対してレンダリングするものと同じペイロードであるため、トークン数に加えて、Claude Code が `/context` の使用量グリッドを描画するために使用する `color` や `gridRows` などの表示用フィールドも含まれます。934[`getContextUsage()`](#query-object) の戻り値の型です。デフォルトの `detail` では、これは対話型セッションで Claude Code が `/context` コマンドに対して表示するのと同じペイロードであり、トークン数に加えて、Claude Code が `/context` の使用量グリッドを描画するために使用する `color` や `gridRows` などの表示用フィールドも含まれます。
930 935
931メソッドのオプションの `detail` 引数で、Claude Code が各カテゴリをどのようにカウントするかを選択します。`detail` 引数には Agent SDK v0.3.257 以降が必要です。936メソッドのオプションの `detail` 引数は、Claude Code が各カテゴリをどのようにカウントするかを選択します。`detail` 引数には Agent SDK v0.3.257 以降が必要です。
932 937
933* **`'full'`**: デフォルトです。Claude Code は[トークンカウント](https://platform.claude.com/docs/en/build-with-claude/token-counting) API リクエストを使って各カテゴリをカウントします。これらのリクエストはメッセージストリームに現れないため、ストリームを読み取るコスト追跡では把握できません。Anthropic API では、トークンカウントは課金されません。938* **`'full'`**：デフォルトです。Claude Code は [トークンカウント](https://platform.claude.com/docs/en/build-with-claude/token-counting) API リクエストを使用して各カテゴリをカウントします。これらのリクエストはメッセージストリームに表示されないため、ストリームを読み取るコスト追跡ではこれらを把握できません。Anthropic API では、トークンカウントは課金されません。
934* **`'summary'`**: `{ detail: 'summary' }` を渡すと、代わりに最後のレスポンスの使用量とローカルの見積もりから回答を得られます。トークンカウントのリクエストは送信されず、カテゴリごとの数値は概算になります。939* **`'summary'`**：`{ detail: 'summary' }` を渡すと、代わりに最後のレスポンスの使用量とローカルの見積もりから回答を得られます。トークンカウントのリクエストは送信されず、カテゴリごとの数値は概算になります。
935 940
936メソッドを呼び出す代わりに `/context` をプロンプトとして送信すると、Claude Code は結果を伝えるアシスタントメッセージの `context_usage` フィールドに [`SDKContextUsage`](#sdkcontextusage) ペイロードを添付します。このフィールドには Agent SDK v0.3.232 以降が必要です。941メソッドを呼び出す代わりに `/context` をプロンプトとして送信した場合、Claude Code は結果を届ける assistant メッセージの `context_usage` フィールドに [`SDKContextUsage`](#sdkcontextusage) ペイロードを添付します。このフィールドには Agent SDK v0.3.232 以降が必要です。
937 942
938```typescript theme={null}943```typescript theme={null}
939type SDKControlGetContextUsageResponse = {944type SDKControlGetContextUsageResponse = {
1030};1035};
1031```1036```
1032 1037
1033トークンの内訳はコレクションフィールドから読み取ります。1038トークンの内訳はコレクションフィールドから読み取ります：
1034 1039
1035* `categories` はカテゴリごとの合計を保持します。各エントリの `kind` は、[`SDKContextUsageCategory`](#sdkcontextusagecategory) と同じ値で行を分類します。表示用の `name` ではなく、このフィールドに基づいて行を分類してください。このフィールドには Agent SDK v0.3.268 以降が必要です。1040* `categories` にはカテゴリごとの合計が格納されます。各エントリの `kind` は、[`SDKContextUsageCategory`](#sdkcontextusagecategory) と同じ値で行を分類します。行の分類には表示用の `name` ではなくこのフィールドを使用してください。このフィールドには Agent SDK v0.3.268 以降が必要です。
1036* `mcpTools` と `agents` は、トークンを個々の MCP ツールとサブエージェントに割り当てます。1041* `mcpTools` と `agents` は、トークンを個々の MCP ツールとサブエージェントに割り当てます。
1037* `memoryFiles` は、読み込まれた各メモリファイルとそのコストを一覧表示します。1042* `memoryFiles` には、読み込まれた各メモリファイルとそのコストが列挙されます。
1038* `skills.skillFrontmatter` は、スキル一覧のトークンを含まれている各スキルに割り当てます。スキルごとのカウントは、Claude Code が実際に送信する各スキルの一覧エントリを測定したもので、スキルの完全なフロントマターより短い場合があります。`skills.totalSkills` と `skills.includedSkills` を比較すると、検出されたすべてのスキルが一覧に含まれたかどうかを確認できます。1043* `skills.skillFrontmatter` は、スキル一覧のトークンを含まれている各スキルに割り当てます。スキルごとの数は、Claude Code が実際に送信する各スキルの一覧エントリを測定したものであり、スキルの完全なフロントマターより短い場合があります。検出されたすべてのスキルが一覧に含まれたかどうかを確認するには、`skills.totalSkills` と `skills.includedSkills` を比較してください。
1039 1044
1040`totalTokens` はセッションの現在のコンテキスト使用量で、`maxTokens` はその使用量を測定する基準となるウィンドウです。このウィンドウはモデルのコンテキストウィンドウ、または自動圧縮のウィンドウが適用される場合はそれより小さいそのウィンドウです。`rawMaxTokens` は `maxTokens` と同じ値を持ち、`percentage` はそのウィンドウに対する `totalTokens` の割合を丸めた値です。`apiUsage` は最新の API レスポンスの使用量を保持し、セッションの累計ではありません。1045`totalTokens` はセッションの現在のコンテキスト使用量であり、`maxTokens` はその使用量の測定基準となるウィンドウです。このウィンドウはモデルのコンテキストウィンドウ、または適用される場合はより小さい自動圧縮のウィンドウです。`rawMaxTokens` は `maxTokens` と同じ値を持ち、`percentage` はそのウィンドウに対する `totalTokens` の割合を四捨五入したものです。`apiUsage` には、セッションの累計ではなく、最新の API レスポンスの使用量が格納されます。
1041 1046
1042Claude Code はオプションの診断フィールドである `deferredBuiltinTools`、`systemTools`、`systemPromptSections` を設定しないため、型で宣言されていてもこれらは存在しないものと想定してください。1047Claude Code はオプションの診断情報である `deferredBuiltinTools`、`systemTools`、`systemPromptSections` を設定しないため、型で宣言されていてもこれらは存在しないものと考えてください。
1043 1048
1044<h3 id="sdkcontrolreadfileresponse">1049<h3 id="sdkcontrolreadfileresponse">
1045 `SDKControlReadFileResponse`1050 `SDKControlReadFileResponse`
1056};1061};
1057```1062```
1058 1063
1059`contents` はファイルのテキスト、または `encoding: 'base64'` を要求した場合は base64 データを保持します。その場合、レスポンスの `encoding` フィールドは `'base64'` に設定されます。`absPath` は解決された絶対パスです。`truncated` は、ファイルが `maxBytes` の上限より長く、内容がその上限で切り詰められた場合に設定されます。1064`contents` にはファイルのテキスト、または `encoding: 'base64'` を要求した場合は base64 データが格納されます。その場合、レスポンスの `encoding` フィールドは `'base64'` に設定されます。`absPath` は解決された絶対パスです。`truncated` は、ファイルが `maxBytes` の上限より長く、内容がその上限で切り詰められた場合に設定されます。
1060 1065
1061<h4 id="what-readfile-can-read">1066<h4 id="what-readfile-can-read">
1062 `readFile()` が読み取れるもの1067 `readFile()` で読み取れるもの
1063</h4>1068</h4>
1064 1069
1065`readFile()` が提供するファイルの範囲は Read ツールより狭くなっています。1070`readFile()` が提供するファイルは、Read ツールよりも限定されています：
1066 1071
1067* `cwd` や `additionalDirectories` など、セッションの作業ディレクトリのいずれかに含まれる通常のファイル1072* `cwd` や `additionalDirectories` など、セッションの作業ディレクトリのいずれかにある通常のファイル
1068* ツールの結果など、そのセッションに関する Claude Code 自身のファイルの一部1073* ツールの結果など、セッションに関する Claude Code 自身のいくつかのファイル
1069 1074
1070`Read` の拒否ルールと確認ルールは引き続き一致するパスをブロックし、広範な `Read` の許可ルールがあっても、ファイルシステムの残りの部分が `readFile()` に開放されることはありません。それ以外のものについては、呼び出しは `null` で解決されます。1075`Read` の拒否ルールと確認ルールは引き続き一致するパスをブロックし、広範な `Read` 許可ルールがあってもファイルシステムの残りの部分が `readFile()` に開放されることはありません。それ以外のものについては、呼び出しは `null` で解決されます。
1071 1076
1072<h3 id="sdkcontrolreloadpluginsresponse">1077<h3 id="sdkcontrolreloadpluginsresponse">
1073 `SDKControlReloadPluginsResponse`1078 `SDKControlReloadPluginsResponse`
1096};1101};
1097```1102```
1098 1103
1099コレクションフィールドは、呼び出し後のセッションを表します。1104コレクションフィールドは、呼び出し後のセッションを表します：
1100 1105
1101* `commands`、`agents`、`mcpServers`: セッションのコマンド、サブエージェント、MCP サーバーのステータスで、`supportedCommands()`、`supportedAgents()`、`mcpServerStatus()` が返すのと同じ形式です。`supportedAgents()` は初期化時に取得されたリストを返し続けるため、再読み込み後のセットについてはここの `agents` を読み取ってください1106* `commands`、`agents`、`mcpServers`：セッションのコマンド、サブエージェント、MCP サーバーのステータスで、`supportedCommands()`、`supportedAgents()`、`mcpServerStatus()` が返すのと同じ形式です。`supportedAgents()` は初期化時に取得したリストを返し続けるため、再読み込み後のセットを知るにはここで `agents` を読み取ってください
1102* `plugins`: 読み込まれた各プラグインとその `name` およびインストール先の `path`。`version` はプラグインのマニフェストが宣言している内容をそのまま示すもので、プラグインの作成者が制御するため、信頼する前に検証してください。マニフェストが何も宣言していない場合は省略されます1107* `plugins`：読み込まれた各プラグインとその `name` およびインストール先の `path`。`version` はプラグインのマニフェストが宣言している内容をそのまま示すものであり、プラグインの作成者が制御するため、信頼する前に検証してください。マニフェストで宣言されていない場合は省略されます
1103* `error_count`: プラグインの読み込みで発生したエラーの数1108* `error_count`：プラグインの読み込み時に発生したエラーの数
1104 1109
1105`reloadPlugins()` に `{ holdOnCacheImpact: true }` を渡すと、会話のプロンプトキャッシュを無効にするような再読み込みを適用せずに保留できます。Claude Code は、インタラクティブな `/reload-plugins` コマンドが[キャッシュのコストについて警告する](/docs/ja/prompt-caching#enabling-or-disabling-a-plugin)前に行うチェックを実行します。このオプションには Agent SDK v0.3.268 以降が必要です。`pathToClaudeCodeExecutable` で指定したものなど、v2.1.268 より古い Claude Code 実行ファイルはこのオプションを無視して再読み込みを適用します。1110`reloadPlugins()` に `{ holdOnCacheImpact: true }` を渡すと、会話のプロンプトキャッシュを無効にするような再読み込みを、適用する代わりに保留できます。Claude Code は、対話型の `/reload-plugins` コマンドが[キャッシュのコストについて警告する](/docs/ja/prompt-caching#enabling-or-disabling-a-plugin)前に行うのと同じチェックを実行します。このオプションには Agent SDK v0.3.268 以降が必要です。`pathToClaudeCodeExecutable` で指定したものなど、v2.1.268 より古い Claude Code 実行可能ファイルはこのオプションを無視し、再読み込みを適用します。
1106 1111
1107このオプションを渡した場合は、`held` を読み取って何が起きたかを確認します。1112このオプションを渡した場合は、`held` を読み取って何が起きたかを確認します：
1108 1113
1109* `true`: 再読み込みは適用されておらず、コレクションフィールドは現在のままのセッションを表します。`cache_impact` は、適用した場合に何が変わるかを示します。それでも適用するには、オプションなしで `reloadPlugins()` を再度呼び出します。1114* `true`：再読み込みは適用されておらず、コレクションフィールドは現在のままのセッションを表しています。`cache_impact` は、適用した場合に何が変わるかを示します。それでも適用するには、オプションなしで `reloadPlugins()` を再度呼び出してください。
1110* `false`: チェックでキャッシュへの影響が見つからず、再読み込みが適用されました。1115* `false`：チェックでキャッシュへの影響が見つからず、再読み込みが適用されました。
1111* 存在しない: オプションを渡さなかったか、Claude Code 実行ファイルが v2.1.268 より古く、再読み込みを適用しました。1116* 存在しない：オプションを渡していないか、Claude Code 実行可能ファイルが v2.1.268 より古く、再読み込みを適用しました。
1112 1117
1113`cache_impact` は `held: true` と併せてのみ存在します。`mcp_servers_added` と `mcp_servers_removed` は、再読み込みによって登録または削除されるプラグインの MCP サーバーを、スコープ付きの `plugin:<plugin>:<server>` 名で示します。これらの名前はプラグインの作成者が付けたものであるため、表示する前に検証してください。`lsp_tool_change` は、適用によって LSP ツールが追加されるか削除されるかを示し、どちらでもない場合は `null` です。`may-` 形式は、チェックで保留中のプラグインセットを完全には把握できなかったことを意味します。1118`cache_impact` は `held: true` と一緒の場合にのみ存在します。`mcp_servers_added` と `mcp_servers_removed` は、再読み込みによって登録または削除されるプラグインの MCP サーバーを、スコープ付きの `plugin:<plugin>:<server>` 形式の名前で示します。名前はプラグインの作成者によるものなので、表示する前に検証してください。`lsp_tool_change` は、適用によって LSP ツールが追加されるか削除されるかを示し、どちらでもない場合は `null` になります。`may-` 形式は、チェックが保留中のプラグインのセットを完全には把握できなかったことを意味します。
1114 1119
1115<h3 id="sdkcontrolreloadskillsresponse">1120<h3 id="sdkcontrolreloadskillsresponse">
1116 `SDKControlReloadSkillsResponse`1121 `SDKControlReloadSkillsResponse`
1124};1129};
1125```1130```
1126 1131
1127`skills` は、再読み込み後に使用可能なスキルを、`supportedCommands()` が返すのと同じ [`SlashCommand`](#slashcommand) の形式で一覧表示します。1132`skills` には、再読み込み後に利用可能なスキルが、`supportedCommands()` が返すのと同じ [`SlashCommand`](#slashcommand) の形式で列挙されます。
1128 1133
1129<h3 id="sdkcontrolreloadoutputstylesresponse">1134<h3 id="sdkcontrolreloadoutputstylesresponse">
1130 `SDKControlReloadOutputStylesResponse`1135 `SDKControlReloadOutputStylesResponse`
1138};1143};
1139```1144```
1140 1145
1141`available_output_styles` は、再読み込み後に使用可能な組み込みおよびカスタムの出力スタイルの名前を一覧表示します。1146`available_output_styles` には、再読み込み後に利用可能な組み込みおよびカスタムの出力スタイルの名前が列挙されます。
1142 1147
1143<h3 id="sdkcontrolmcpreadresourceresponse">1148<h3 id="sdkcontrolmcpreadresourceresponse">
1144 `SDKControlMcpReadResourceResponse`1149 `SDKControlMcpReadResourceResponse`
1158};1163};
1159```1164```
1160 1165
1161`readMcpResource()` には、`mcpServerStatus()` が報告するサーバー名と、ツールが [`_meta`](#mcpserverstatus) で宣言する `ui.resourceUri` などの `ui://` URI を渡します。その他の URI スキームの場合、アプリケーション自身がホストする [SDK MCP サーバー](#createsdkmcpserver)の場合、および接続されていないサーバーの場合、呼び出しは拒否されます。init メッセージの [`capabilities`](#sdksystemmessage) に `mcp_read_resource_v1` が含まれている場合に使用できます。1166`readMcpResource()` には、`mcpServerStatus()` が報告するサーバー名と、ツールが [`_meta`](#mcpserverstatus) で宣言する `ui.resourceUri` などの `ui://` URI を渡します。その他の URI スキーム、アプリケーション自身がホストする [SDK MCP サーバー](#createsdkmcpserver)、および接続されていないサーバーに対しては、呼び出しは拒否されます。init メッセージの [`capabilities`](#sdksystemmessage) に `mcp_read_resource_v1` が含まれている場合に利用できます。
1162 1167
1163各 `contents` エントリは、サーバーが送信したとおりの 1 つのコンテンツ項目ですが、Claude Code 用に予約されている `com.anthropic/` プレフィックス以下の `_meta` キーは除かれます。`blob` はバイナリ項目の base64 データを保持し、`_meta` はその項目自身の `_meta` で、MCP Apps サーバーはリソースの `ui.csp` と `ui.permissions` をここに配置します。1168各 `contents` エントリは、サーバーが送信したままの 1 つのコンテンツアイテムですが、Claude Code 用に予約されている `com.anthropic/` プレフィックス配下の `_meta` キーは除かれます。`blob` にはバイナリアイテムの base64 データが格納され、`_meta` はアイテム自身の `_meta` であり、MCP Apps サーバーはここにリソースの `ui.csp` と `ui.permissions` を配置します。
1164 1169
1165コンテンツは信頼できないサードパーティの HTML であるため、サンドボックス内でレンダリングしてください。1170内容は信頼できないサードパーティの HTML であるため、サンドボックス内で表示してください。
1166 1171
1167<h3 id="agentdefinition">1172<h3 id="agentdefinition">
1168 `AgentDefinition`1173 `AgentDefinition`
1192 1197
1193| フィールド | 必須 | 説明 |1198| フィールド | 必須 | 説明 |
1194| :- | :- | :- |1199| :- | :- | :- |
1195| `description` | はい | このエージェントをいつ使用するかを自然言語で説明したもの |1200| `description` | はい | このエージェントをいつ使用するかについての自然言語による説明 |
1196| `tools` | いいえ | 許可されるツール名の配列。省略した場合、[サブエージェントが使用できるツール](/docs/ja/sub-agents#available-tools)をすべて継承します。スキルをエージェントのコンテキストに事前読み込みするには、ここに `'Skill'` を列挙するのではなく `skills` フィールドを使用してください |1201| `tools` | いいえ | 許可されるツール名の配列。省略すると、[サブエージェントが利用できるすべてのツール](/docs/ja/sub-agents#available-tools)を継承します。スキルをエージェントのコンテキストに事前読み込みするには、ここに `'Skill'` を列挙するのではなく `skills` フィールドを使用してください |
1197| `disallowedTools` | いいえ | このエージェントで明示的に禁止するツール名の配列。MCP サーバーレベルのパターンも使用できます。`mcp__server` または `mcp__server__*` はそのサーバーのすべてのツールを削除し、`mcp__*` はすべてのサーバーのすべての MCP ツールを削除します |1202| `disallowedTools` | いいえ | このエージェントで明示的に禁止するツール名の配列。MCP サーバーレベルのパターンも受け付けます：`mcp__server` または `mcp__server__*` はそのサーバーのすべてのツールを削除し、`mcp__*` はすべてのサーバーのすべての MCP ツールを削除します |
1198| `prompt` | はい | エージェントのシステムプロンプト |1203| `prompt` | はい | エージェントのシステムプロンプト |
1199| `model` | いいえ | このエージェントのモデルの上書き。`'fable'`、`'opus'`、`'sonnet'`、`'haiku'`、`'inherit'` などのエイリアス、または完全なモデル ID を受け付けます。`'inherit'` はメインのモデルを使用します。省略した場合、Claude Code は[サブエージェントのモデルの順序](/docs/ja/sub-agents#choose-a-model)に従ってモデルを選択します |1204| `model` | いいえ | このエージェントのモデルの上書き。`'fable'`、`'opus'`、`'sonnet'`、`'haiku'`、`'inherit'` などのエイリアス、または完全なモデル ID を受け付けます。`'inherit'` はメインモデルを使用します。省略すると、Claude Code は[サブエージェントのモデルの順序](/docs/ja/sub-agents#choose-a-model)に従ってモデルを選択します |
1200| `mcpServers` | いいえ | このエージェントの MCP サーバーの指定 |1205| `mcpServers` | いいえ | このエージェントの MCP サーバーの指定 |
1201| `skills` | いいえ | エージェントのコンテキストに事前読み込みするスキル名の配列 |1206| `skills` | いいえ | エージェントのコンテキストに事前読み込みするスキル名の配列 |
1202| `initialPrompt` | いいえ | このエージェントがメインスレッドのエージェントとして実行されるときに、最初のユーザーターンとして自動送信されます |1207| `initialPrompt` | いいえ | このエージェントがメインスレッドのエージェントとして実行される場合に、最初のユーザーターンとして自動送信されます |
1203| `maxTurns` | いいえ | 停止するまでのエージェントの最大ターン数（API の往復） |1208| `maxTurns` | いいえ | 停止するまでのエージェントの最大ターン数（API の往復） |
1204| `background` | いいえ | 呼び出されたときに、このエージェントをノンブロッキングのバックグラウンドタスクとして実行します |1209| `background` | いいえ | 呼び出されたときに、このエージェントをノンブロッキングのバックグラウンドタスクとして実行します |
1205| `omitClaudeMd` | いいえ | サブエージェントとして実行されるときに、ユーザー、プロジェクト、ローカルの CLAUDE.md ファイルなしでこのエージェントを実行します。管理ポリシーファイルは引き続き読み込まれます。必要なものをすべて Agent ツールのプロンプトから受け取るエージェントに使用します。このエージェントがメインスレッドのエージェントとして実行される場合は無視されます。TypeScript Agent SDK v0.3.271 以降が必要です |1210| `omitClaudeMd` | いいえ | このエージェントがサブエージェントとして実行される場合に、ユーザー、プロジェクト、ローカルの CLAUDE.md ファイルなしで実行します。管理ポリシーのファイルは引き続き読み込まれます。必要なものをすべて Agent ツールのプロンプトから受け取るエージェントに使用してください。このエージェントがメインスレッドのエージェントとして実行される場合は無視されます。TypeScript Agent SDK v0.3.271 以降が必要です |
1206| `memory` | いいえ | このエージェントのメモリソース: `'user'`、`'project'`、または `'local'` |1211| `memory` | いいえ | このエージェントのメモリソース：`'user'`、`'project'`、または `'local'` |
1207| `effort` | いいえ | このエージェントの推論の effort レベル。名前付きのレベルまたは整数を受け付けます |1212| `effort` | いいえ | このエージェントの推論の effort レベル。名前付きのレベルまたは整数を受け付けます |
1208| `permissionMode` | いいえ | このエージェント内でのツール実行の権限モード。いつ適用されるかは[サブエージェントの継承ルール](/docs/ja/agent-sdk/permissions#available-modes)によって決まります。[`PermissionMode`](#permissionmode) を参照してください |1213| `permissionMode` | いいえ | このエージェント内でのツール実行の権限モード。いつ適用されるかは[サブエージェントの継承ルール](/docs/ja/agent-sdk/permissions#available-modes)によって決まります。[`PermissionMode`](#permissionmode) を参照してください |
1209| `criticalSystemReminder_EXPERIMENTAL` | いいえ | 実験的: システムプロンプトに追加される重要なリマインダー |1214| `criticalSystemReminder_EXPERIMENTAL` | いいえ | 実験的機能：システムプロンプトに追加される重要なリマインダー |
1210 1215
1211<h3 id="agentmcpserverspec">1216<h3 id="agentmcpserverspec">
1212 `AgentMcpServerSpec`1217 `AgentMcpServerSpec`
1213</h3>1218</h3>
1214 1219
1215サブエージェントが使用できる MCP サーバーを指定します。サーバー名（親の `mcpServers` 設定内のサーバーを参照する文字列）、またはサーバー名を設定にマッピングするインラインのサーバー設定レコードを指定できます。1220サブエージェントが利用できる MCP サーバーを指定します。サーバー名（親の `mcpServers` 設定内のサーバーを参照する文字列）、またはサーバー名を設定にマッピングするインラインのサーバー設定レコードのいずれかを指定できます。
1216 1221
1217```typescript theme={null}1222```typescript theme={null}
1218type AgentMcpServerSpec = string | Record<string, McpServerConfigForProcessTransport>;1223type AgentMcpServerSpec = string | Record<string, McpServerConfigForProcessTransport>;
1224 `SettingSource`1229 `SettingSource`
1225</h3>1230</h3>
1226 1231
1227SDK が設定を読み込むファイルシステムベースの設定ソースを制御します。1232SDK がどのファイルシステムベースの設定ソースから設定を読み込むかを制御します。
1228 1233
1229```typescript theme={null}1234```typescript theme={null}
1230type SettingSource = "user" | "project" | "local";1235type SettingSource = "user" | "project" | "local";
1234| :- | :- | :- |1239| :- | :- | :- |
1235| `'user'` | グローバルなユーザー設定 | `~/.claude/settings.json` |1240| `'user'` | グローバルなユーザー設定 | `~/.claude/settings.json` |
1236| `'project'` | 共有プロジェクト設定（バージョン管理対象） | `.claude/settings.json` |1241| `'project'` | 共有プロジェクト設定（バージョン管理対象） | `.claude/settings.json` |
1237| `'local'` | ローカルプロジェクト設定。Claude Code が設定を保存する際に gitignore に追加されます | `.claude/settings.local.json` |1242| `'local'` | ローカルプロジェクト設定。Claude Code がこのファイルに設定を保存する際に gitignore に追加されます | `.claude/settings.local.json` |
1238 1243
1239<h4 id="default-behavior">1244<h4 id="default-behavior">
1240 デフォルトの動作1245 デフォルトの動作
1241</h4>1246</h4>
1242 1247
1243`settingSources` が省略されているか `undefined` の場合、`query()` は Claude Code CLI と同じファイルシステム設定（user、project、local）を読み込みます。このオプションに関係なく読み込まれる入力とそれらを無効にする方法については、[settingSources が制御しないもの](/docs/ja/agent-sdk/claude-code-features#what-settingsources-does-not-control)を参照してください。1248`settingSources` が省略されているか `undefined` の場合、`query()` は Claude Code CLI と同じファイルシステム設定（user、project、local）を読み込みます。このオプションに関係なく読み込まれる入力とその無効化方法については、[settingSources で制御されないもの](/docs/ja/agent-sdk/claude-code-features#what-settingsources-does-not-control)を参照してください。
1244 1249
1245<h4 id="why-use-settingsources">1250<h4 id="why-use-settingsources">
1246 settingSources を使用する理由1251 settingSources を使用する理由
1272});1277});
1273```1278```
1274 1279
1275CLAUDE.md のプロジェクト指示を読み込むには、`settingSources` に `"project"` を含めてください。CLAUDE.md の読み込みとシステムプロンプトのオプションとの関係については、[システムプロンプトの変更](/docs/ja/agent-sdk/modifying-system-prompts#claude-md-files-for-project-level-instructions)を参照してください。1280CLAUDE.md のプロジェクト指示を読み込むには、`settingSources` に `"project"` を含めてください。CLAUDE.md の読み込みとシステムプロンプトオプションの相互作用については、[システムプロンプトの変更](/docs/ja/agent-sdk/modifying-system-prompts#claude-md-files-for-project-level-instructions)を参照してください。
1276 1281
1277<h4 id="settings-precedence">1282<h4 id="settings-precedence">
1278 設定の優先順位1283 設定の優先順位
12842. プロジェクト設定（`.claude/settings.json`）12892. プロジェクト設定（`.claude/settings.json`）
12853. ユーザー設定（`~/.claude/settings.json`）12903. ユーザー設定（`~/.claude/settings.json`）
1286 1291
1287`agents`、`allowedTools`、`settings` などのプログラムによるオプションは、ユーザー、プロジェクト、ローカルのファイルシステム設定を上書きします。管理ポリシー設定はプログラムによるオプションよりも優先されます。1292`agents`、`allowedTools`、`settings` などのプログラムによるオプションは、user、project、local のファイルシステム設定を上書きします。管理ポリシー設定は、プログラムによるオプションよりも優先されます。
1288 1293
1289<h3 id="permissionmode">1294<h3 id="permissionmode">
1290 `PermissionMode`1295 `PermissionMode`
1306 1311
1307ツールの使用を制御するためのカスタム権限関数の型です。1312ツールの使用を制御するためのカスタム権限関数の型です。
1308 1313
1309この関数は、対話型の権限プロンプトを SDK で置き換えるものです。[権限評価フロー](/docs/ja/agent-sdk/permissions#how-permissions-are-evaluated)の結果がプロンプトになった場合にのみ呼び出されます。`allowedTools` のエントリ、設定の許可ルール、または `acceptEdits` や `bypassPermissions` などの権限モードによってすでに承認されているツール呼び出しでは、この関数は呼び出されません。すべてのツール呼び出しを制御するには、代わりに [`PreToolUse` フック](/docs/ja/agent-sdk/hooks)を使用してください。1314この関数は、対話型の権限プロンプトを SDK で置き換えるものです。[権限の評価フロー](/docs/ja/agent-sdk/permissions#how-permissions-are-evaluated)がプロンプトに到達した場合にのみ呼び出されます。`allowedTools` のエントリ、設定の許可ルール、または `acceptEdits` や `bypassPermissions` などの権限モードによってすでに承認されているツール呼び出しでは、この関数は呼び出されません。すべてのツール呼び出しを制御するには、代わりに [`PreToolUse` フック](/docs/ja/agent-sdk/hooks)を使用してください。
1310 1315
1311許可ルールは、[どのモードでも自動承認されないアクション](/docs/ja/permission-modes#actions-no-mode-auto-approves)を事前承認しません。それらのうちどれがコールバックに到達するか、また `dontAsk` モードと `auto` モードで何が起こるかについては、[権限の評価方法](/docs/ja/agent-sdk/permissions#how-permissions-are-evaluated)を参照してください。1316許可ルールは、[どのモードでも自動承認されないアクション](/docs/ja/permission-modes#actions-no-mode-auto-approves)を事前承認しません。それらのうちどれがコールバックに到達するか、また `dontAsk` モードと `auto` モードでどうなるかについては、[権限の評価方法](/docs/ja/agent-sdk/permissions#how-permissions-are-evaluated)を参照してください。
1312 1317
1313```typescript theme={null}1318```typescript theme={null}
1314type CanUseTool = (1319type CanUseTool = (
1332| オプション | 型 | 説明 |1337| オプション | 型 | 説明 |
1333| :- | :- | :- |1338| :- | :- | :- |
1334| `signal` | `AbortSignal` | 操作を中止すべき場合にシグナルが送られます |1339| `signal` | `AbortSignal` | 操作を中止すべき場合にシグナルが送られます |
1335| `suggestions` | [`PermissionUpdate`](#permissionupdate)`[]` | このツールについてユーザーに再度プロンプトが表示されないようにするための、提案された権限の更新。Bash のプロンプトには `localSettings` [保存先](#permissionupdatedestination)を持つ提案が含まれるため、それを `updatedPermissions` で返すとルールが `.claude/settings.local.json` に書き込まれ、セッションをまたいで保持されます。 |1340| `suggestions` | [`PermissionUpdate`](#permissionupdate)`[]` | このツールについてユーザーに再度プロンプトを表示しないようにするための、推奨される権限の更新。Bash のプロンプトには `localSettings` [保存先](#permissionupdatedestination)を持つ提案が含まれるため、これを `updatedPermissions` で返すとルールが `.claude/settings.local.json` に書き込まれ、セッションをまたいで保持されます。 |
1336| `blockedPath` | `string` | 権限リクエストをトリガーしたファイルパス（該当する場合） |1341| `blockedPath` | `string` | 権限リクエストのきっかけとなったファイルパス（該当する場合） |
1337| `mcpServer` | `{ name: string; source: string }` | `mcp__*` ツールの場合、そのツールを提供する MCP サーバーと、そのサーバーの定義の取得元。フィールドは [`McpServerProvenance`](#mcpserverprovenance) と同じです。その他のツールでは存在しません。Agent SDK v0.3.274 以降が必要です |1342| `mcpServer` | `{ name: string; source: string }` | `mcp__*` ツールの場合、そのツールを提供する MCP サーバーと、そのサーバーの定義の出所。フィールドは [`McpServerProvenance`](#mcpserverprovenance) と同じです。その他のツールでは存在しません。Agent SDK v0.3.274 以降が必要です |
1338| `decisionReason` | `string` | この権限リクエストがトリガーされた理由の説明 |1343| `decisionReason` | `string` | この権限リクエストがトリガーされた理由の説明 |
1339| `defaultToNo` | `boolean` | `true` の場合、誤って押された 1 回のキー入力でこのリクエストが承認されてはなりません。プロンプトは拒否オプションを選択した状態で開き、承認を事前選択せず、1 キーで承認できるショートカットも提供しないでください。Agent SDK v0.3.268 以降が必要です |1344| `defaultToNo` | `boolean` | `true` の場合、誤った 1 回のキー入力でこのリクエストが承認されてはなりません。プロンプトは拒否の選択肢にフォーカスした状態で開き、承認を事前選択せず、1 キーで承認できるショートカットも提供しないでください。Agent SDK v0.3.268 以降が必要です |
1340| `suppressAlwaysAllowRule` | `boolean` | `true` の場合、このリクエストに対して永続的な「常に許可」の選択肢を提供しないでください。書き込まれるルールが、リクエスト自体のアクションよりも広い権限を付与してしまうためです。Agent SDK v0.3.268 以降が必要です |1345| `suppressAlwaysAllowRule` | `boolean` | `true` の場合、このリクエストに対して永続的な「常に許可」の選択肢を提示しないでください。Agent SDK v0.3.268 以降が必要です |
1341| `toolUseID` | `string` | アシスタントメッセージ内のこの特定のツール呼び出しの一意な識別子 |1346| `toolUseID` | `string` | アシスタントメッセージ内でのこの特定のツール呼び出しの一意な識別子 |
1342| `agentID` | `string` | サブエージェント内で実行されている場合、そのサブエージェントの ID |1347| `agentID` | `string` | サブエージェント内で実行されている場合、そのサブエージェントの ID |
1343| `requestId` | `string` | `control_request` エンベロープの `request_id`。アプリケーションが SDK の外部から送信する `control_response`（署名付き HTTP POST など）は、Claude Code プロセスが応答をリクエストと照合できるよう、この値をそのまま返す必要があります |1348| `requestId` | `string` | `control_request` エンベロープの `request_id`。アプリケーションが SDK の外部で送信する `control_response`（署名付き HTTP POST など）は、Claude Code プロセスが応答をリクエストと照合できるよう、この値をそのまま返す必要があります |
1344 1349
1345コールバックは通常、[`PermissionResult`](#permissionresult) を返すことでリクエストを解決し、SDK はそれを `control_response` としてトランスポート経由で書き戻します。`null` を返すのは、アプリケーションがすでに独自のチャネル経由で `requestId` を含めてこのリクエストの `control_response` を送信済みの場合に限ってください。その場合、SDK はトランスポートへのレスポンスの書き込みをスキップします。それ以外のケースで `null` を返すと、`control_response` が送信されず、権限プロンプトはタイムアウトしないため、ツール呼び出しが無期限にブロックされたままになります。1350コールバックは通常、[`PermissionResult`](#permissionresult) を返すことでリクエストを解決し、SDK はそれを `control_response` としてトランスポート経由で書き戻します。`null` を返すのは、アプリケーションが独自のチャンネル経由で `requestId` を含めてこのリクエストの `control_response` をすでに送信している場合のみにしてください。その場合、SDK はトランスポートへのレスポンスの書き込みをスキップします。それ以外の場合に `null` を返すと、`control_response` が一切送信されず、権限プロンプトはタイムアウトしないため、ツール呼び出しが無期限にブロックされたままになります。
1346 1351
1347`requestId` オプションと `null` の戻り値には、Claude Code v2.1.199 以降が必要です。1352`requestId` オプションと `null` の戻り値には Claude Code v2.1.199 以降が必要です。
1348 1353
1349<h3 id="permissionresult">1354<h3 id="permissionresult">
1350 `PermissionResult`1355 `PermissionResult`
1384 1389
1385| フィールド | 型 | 説明 |1390| フィールド | 型 | 説明 |
1386| :- | :- | :- |1391| :- | :- | :- |
1387| `askUserQuestion.previewFormat` | `'markdown' \| 'html'` | [`AskUserQuestion`](/docs/ja/agent-sdk/user-input#question-format) のオプションで `preview` フィールドを有効にし、そのコンテンツ形式を設定します。未設定の場合、Claude はプレビューを出力しません |1392| `askUserQuestion.previewFormat` | `'markdown' \| 'html'` | [`AskUserQuestion`](/docs/ja/agent-sdk/user-input#question-format) の選択肢で `preview` フィールドを有効にし、そのコンテンツ形式を設定します。未設定の場合、Claude はプレビューを出力しません |
1388 1393
1389<h3 id="mcpserverconfig">1394<h3 id="mcpserverconfig">
1390 `McpServerConfig`1395 `McpServerConfig`
1480| :- | :- | :- |1485| :- | :- | :- |
1481| `type` | `'local'` | `'local'` である必要があります（現在はローカルプラグインのみサポート） |1486| `type` | `'local'` | `'local'` である必要があります（現在はローカルプラグインのみサポート） |
1482| `path` | `string` | プラグインディレクトリへの絶対パスまたは相対パス |1487| `path` | `string` | プラグインディレクトリへの絶対パスまたは相対パス |
1483| `skipMcpDiscovery` | `boolean` | `true` の場合、SDK はこのプラグインからスキル、フック、エージェント、コマンドを読み込みますが、`.mcp.json` やマニフェストの `mcpServers` は読み込みません。アプリケーションがプラグインの MCP 接続を管理する場合に設定してください。 |1488| `skipMcpDiscovery` | `boolean` | `true` の場合、SDK はこのプラグインからスキル、フック、エージェント、コマンドを読み込みますが、その `.mcp.json` やマニフェストの `mcpServers` は読み込みません。アプリケーションがプラグインの MCP 接続を管理する場合に設定してください。 |
1484 1489
1485**例：**1490**例：**
1486 1491
3788};3793};
3789```3794```
3790 3795
3791コードレビューの検出結果を構造化リストとしてレポートするため、Claude Code はテキストとして出力する代わりにレンダリングできます。`level` はレビューが実行された努力レベルです。検出結果は最も重大度の高い順に並べられ、呼び出しごとに最大 32 個で、配列は何も生き残らなかった場合は空です。Claude Code v2.1.196 以降が必要です。3796コードレビューの検出結果を構造化リストとしてレポートするため、Claude Code はテキストとして出力する代わりにレンダリングできます。検出結果は最も重大度の高い順に並べられ、呼び出しごとに最大 32 個で、配列は何も生き残らなかった場合は空です。Claude Code v2.1.196 以降が必要です。
3797
3798`level` はオプションで、Claude がレビューについて報告する effort レベルを保持します。Claude Code はこれをレビューが実際に実行されたレベルと比較しないため、両者が異なる場合があります。
3792 3799
3793各検出結果には以下のフィールドが含まれます：3800各検出結果には以下のフィールドが含まれます：
3794 3801
4838};4845};
4839```4846```
4840 4847
4841報告された検出結果の数、レビューが実行された努力レベル、および結果本体のためにエコーバックされた検出結果を返します。Claude Code v2.1.196 以降が必要です。エコーバックされた `short_summary` フィールドは Claude Code v2.1.212 以降が必要です。4848報告された検出結果の数、Claude が渡した `level` 値、および結果本体のためにエコーバックされた検出結果を返します。Claude Code v2.1.196 以降が必要です。エコーバックされた `short_summary` フィールドは Claude Code v2.1.212 以降が必要です。
4842 4849
4843<h3 id="artifact-2">4850<h3 id="artifact-2">
4844 Artifact4851 Artifact
5459 | { type: "disabled" }; // No extended thinking5466 | { type: "disabled" }; // No extended thinking
5460```5467```
5461 5468
5462オプションの `display` フィールドは、思考テキストが `"summarized"` または `"omitted"` で返されるかどうかを制御します。Claude Opus 4.7 以降では、API デフォルトは `"omitted"` なため、思考コンテンツを `thinking` ブロックで受け取るには `"summarized"` を設定してください。Claude Code は Amazon Bedrock または Google Cloud の Agent Platform に `display` を送信しないため、これらのプロバイダーでは Opus 4.7 以降は `display` を `"summarized"` に設定した場合でも空の `thinking` ブロックを返します。5469オプションの `display` フィールドは、思考テキストが `"summarized"` または `"omitted"` で返されるかどうかを制御します。Claude Opus 4.7 以降では、API デフォルトは `"omitted"` なため、思考コンテンツを `thinking` ブロックで受け取るには `"summarized"` を設定してください。Claude Code は、Amazon Bedrock や Google Cloud の Agent Platform など一部のプロバイダーへのリクエストに `display` を含めません。これらのプロバイダーでは、`display` を `"summarized"` に設定した場合でも、Opus 4.7 以降は空の `thinking` ブロックを返します。
5463 5470
5464<h3 id="spawnedprocess">5471<h3 id="spawnedprocess">
5465 `SpawnedProcess`5472 `SpawnedProcess`
5530 5537
5531`setMcpServers()` を呼び出すと、Claude Code は以下のルールを適用します。5538`setMcpServers()` を呼び出すと、Claude Code は以下のルールを適用します。
5532 5539
5533* **呼び出しが名前を付けないサーバー**: Claude Code はプラグイン提供サーバーを実行し続けます。Agent SDK v0.3.210 以降が必要です。5540* **呼び出しが名前を付けないサーバー**: [クラウドセッション](/docs/ja/claude-code-on-the-web)以外では、Claude Code は以前の `setMcpServers()` 呼び出しが追加したサーバーとインプロセス SDK サーバーを切断し、それらを `removed` にリストします。その他のサーバーは実行を続け、`removed` にはリストされません。これには [`mcpServers`](#options) オプションからの stdio、HTTP、SSE サーバー、設定ファイルからのサーバー、プラグイン提供サーバーが含まれます。
5534* **呼び出しが名前を付けるサーバー**: CLI が起動時に開始した組み込みサーバーを除き、Claude Code は実行中のサーバーを、渡した設定と異なる場合にのみ置き換えます。5541* **呼び出しが名前を付けるサーバー**: Claude Code は、以前の `setMcpServers()` 呼び出しが追加した stdio、HTTP、または SSE サーバーを、その設定が渡したものと異なる場合にのみ置き換えます。その名前ですでに登録されているインプロセス SDK サーバーはそのまま残るため、入れ替えるには、ある呼び出しからそれを除外し、次の呼び出しで追加してください。
5535* **CLI が起動時に開始した組み込みサーバー**: 呼び出しが 1 つを名前付けする場合、Claude Code はそのエントリをドロップし、`errors` で報告します。5542* **CLI が起動時に開始した組み込みサーバー**: 呼び出しが 1 つを名前付けする場合、Claude Code はそのエントリをドロップし、`errors` で報告します。
5536 5543
5537新しく追加された stdio、HTTP、SSE サーバーが接続または失敗した後、プロミスが解決されるため、接続されたサーバーからのツールは次のターンで利用可能です。5544新しく追加された stdio、HTTP、SSE サーバーが接続または失敗した後、プロミスが解決されるため、接続されたサーバーからのツールは次のターンで利用可能です。
