Documentation 2026-10-06 23:59 UTC to 2026-10-07 21:59 UTC

46 設定がデバイスに到達する方法を決定する46 設定がデバイスに到達する方法を決定する

47</h2>47</h2>

48 48 

49マネージド設定は、組織ポリシーを定義します。Claude Code は以下の表に示す 4 つのソースを優先順位順にチェックします。[Claude Code がマネージドソースを組み合わせる方法](/docs/ja/managed-settings#precedence-within-the-managed-tier)は、どのソースが適用されるか、ポリシーヘルパーが何を変更するか、およびすべてのソースを構成する方法を説明しています。この表は決定マップです。49管理設定は、組織ポリシーを定義します。Claude Code は以下の表に示す 4 つのソースを優先順位順にチェックします。[Claude Code がマネージドソースを組み合わせる方法](/docs/ja/managed-settings#precedence-within-the-managed-tier)は、どのソースが適用されるか、ポリシーヘルパーが何を変更するか、およびすべてのソースを構成する方法を説明しています。この表は決定マップです。

50 50 

51| メカニズム | 配信 | 優先度 | プラットフォーム |51| メカニズム | 配信 | 優先度 | プラットフォーム |

52| :- | :- | :- | :- |52| :- | :- | :- | :- |

55| File-based managed | macOS: `/Library/Application Support/ClaudeCode/managed-settings.json`<br />Linux と WSL: `/etc/claude-code/managed-settings.json`<br />Windows: `C:\Program Files\ClaudeCode\managed-settings.json` | 中 | すべて |55| File-based managed | macOS: `/Library/Application Support/ClaudeCode/managed-settings.json`<br />Linux と WSL: `/etc/claude-code/managed-settings.json`<br />Windows: `C:\Program Files\ClaudeCode\managed-settings.json` | 中 | すべて |

56| Windows user registry | `HKCU\SOFTWARE\Policies\ClaudeCode` | 最低 | Windows のみ |56| Windows user registry | `HKCU\SOFTWARE\Policies\ClaudeCode` | 最低 | Windows のみ |

57 57 

58Claude Code はスタートアップ時に server-managed 設定をフェッチし、セッション中は 1 時間ごとに更新します。デプロイするエンドポイントインフラストラクチャはありません。claude.ai 管理コンソール経由の配信には Claude for Teams または Enterprise プランが必要です。Amazon Bedrock、Google Cloud の Agent Platform、または Microsoft Foundry でのデプロイメントは、[Claude apps gateway](/docs/ja/claude-apps-gateway) を実行することで同じリモート配信を取得できます。または、ファイルベースまたは OS レベルのメカニズムのいずれかを代わりに使用してください。58Claude Code はスタートアップ時に server-managed 設定をフェッチし、セッション中は 1 時間ごとに更新します。デプロイするエンドポイントインフラストラクチャはありません。claude.ai 管理コンソール経由の配信には Claude for Teams または Enterprise プランが必要です。Amazon Bedrock、Google Cloud の Agent Platform、または Microsoft Foundry でのデプロイは、[Claude apps gateway](/docs/ja/claude-apps-gateway) を実行することで同じリモート配信を取得できます。または、ファイルベースまたは OS レベルのメカニズムのいずれかを代わりに使用してください。

59 59 

60組織が複数のプロバイダーを混在させている場合、claude.ai ユーザー向けに [server-managed settings](/docs/ja/server-managed-settings) を設定し、他のユーザーがマネージドポリシーを受け取るように [ファイルベースまたは plist/registry フォールバック](/docs/ja/managed-settings#delivery-mechanisms)を設定してください。60組織が複数のプロバイダーを混在させている場合、claude.ai ユーザー向けに [server-managed settings](/docs/ja/server-managed-settings) を設定し、他のユーザーがマネージドポリシーを受け取るように [ファイルベースまたは plist/registry フォールバック](/docs/ja/managed-settings#delivery-mechanisms)を設定してください。

61 61 

69 Claude Code Desktop の WSL セッション69 Claude Code Desktop の WSL セッション

70</h3>70</h3>

71 71 

72Windows では、[Claude Code Desktop は WSL 2 ディストリビューション内で Code セッションを実行できます](/docs/ja/desktop-wsl)。セッションの Claude Code プロセスはディストリビューション内で実行されるため、上記の WSL 検出パスを通じてマネージド設定を解決します。`wslInheritsWindowsSettings: true` が展開されていない限り、Windows のみのソースはそれに到達しません。72Windows では、[Claude Code Desktop は WSL 2 ディストリビューション内で Code セッションを実行できます](/docs/ja/desktop-wsl)。セッションの Claude Code プロセスはディストリビューション内で実行されるため、上記の WSL 検出パスを通じて管理設定を解決します。`wslInheritsWindowsSettings: true` がデプロイされていない限り、Windows のみのソースはそれに到達しません。

73 73 

74Claude Desktop は、`C:\Program Files\ClaudeCode\managed-settings.json` が存在する場合など、組織がマネージドしているデバイスとして検出されるデバイスでは、デフォルトで WSL セッションをオフにします。それらをオンにするには、Windows レジストリポリシーをデプロイします。これには Claude Desktop v1.19367.0 以降が必要です。74Claude Desktop は、`C:\Program Files\ClaudeCode\managed-settings.json` が存在する場合など、組織が管理しているデバイスとして検出されるデバイスでは、デフォルトで WSL セッションをオフにします。それらをオンにするには、Windows レジストリポリシーをデプロイします。これには Claude Desktop v1.19367.0 以降が必要です。

75 75 

76* `HKLM\SOFTWARE\Policies\Claude` の下に `disableWslSessions` という名前の値を作成し、`REG_SZ` 文字列 `false` または `REG_DWORD` `0` に設定します。この値は Claude Desktop ポリシーキーの下にあり、マネージド設定を含む `ClaudeCode` キーとは別です。HKLM の下に値をデプロイします。これには管理者権限が必要です。HKCU の下の値は WSL セッションを有効にしません。76* `HKLM\SOFTWARE\Policies\Claude` の下に `disableWslSessions` という名前の値を作成し、`REG_SZ` 文字列 `false` または `REG_DWORD` `0` に設定します。この値は Claude Desktop ポリシーキーの下にあり、管理設定を含む `ClaudeCode` キーとは別です。HKLM の下に値をデプロイします。これには管理者権限が必要です。HKCU の下の値は WSL セッションを有効にしません。

77* `C:\Program Files\ClaudeCode\managed-settings.json` をデプロイする場合は、そのままにしておいてください。`disableWslSessions` が HKLM の下で `false` になると、そのファイルが存在していても Desktop は WSL セッションを許可します。77* `C:\Program Files\ClaudeCode\managed-settings.json` をデプロイする場合は、そのままにしておいてください。`disableWslSessions` が HKLM の下で `false` になると、そのファイルが存在していても Desktop は WSL セッションを許可します。

78 78 

79Desktop は WSL セッションが開始されるたびにポリシーを読み取るため、デプロイ後にアプリを再起動する必要はありません。79Desktop は WSL セッションが開始されるたびにポリシーを読み取るため、デプロイ後にアプリを再起動する必要はありません。

80 80 

81デバイスが依然として WSL セッションを拒否する場合は、そのデバイスの Claude Desktop で **Help > Troubleshooting > Show Logs in Explorer** を開きます。これにより、ログフォルダのコピーが Downloads に保存されます。そのコピーの `main.log` で `[wslPolicyGate] denying WSL session` を検索してください。拒否の理由は括弧内に続きます。例えば `(cli-file-present)` のようにです。Claude Desktop が `.exe` インストーラーでインストールされた場合、`%APPDATA%\Claude\logs\main.log` のライブファイルを読むこともできます。81デバイスが依然として WSL セッションを拒否する場合は、そのデバイスの Claude Desktop で **Help > Troubleshooting > Show Logs in File Explorer** を開きます。これにより、ログフォルダのコピーが Downloads に保存されます。そのコピーの `main.log` で `[wslPolicyGate] denying WSL session` を検索してください。拒否の理由は括弧内に続きます。例えば `(cli-file-present)` のようにです。

82 82 

83WSL セッションが有効になった後、マネージド設定をそれらに拡張します。83WSL セッションが有効になった後、管理設定をそれらに拡張します。

84 84 

85* HKLM レジストリまたは `C:\Program Files\ClaudeCode` ファイルを通じて `wslInheritsWindowsSettings: true` をデプロイして、WSL セッションがホストセッションと同じポリシーを継承するようにしてください。85* HKLM レジストリまたは `C:\Program Files\ClaudeCode` ファイルを通じて `wslInheritsWindowsSettings: true` をデプロイして、WSL セッションがホストセッションと同じポリシーを継承するようにしてください。

86* WSL セッション内で `/status` を実行して検証し、`Setting sources` 行を読んでください。それを解釈する方法については、[/status で出力を読む](/docs/ja/managed-settings#read-the-source-in-/status)を参照してください。86* WSL セッション内で `/status` を実行して検証し、`Setting sources` 行を読んでください。それを解釈する方法については、[/status で出力を読む](/docs/ja/managed-settings#read-the-source-in-/status)を参照してください。

87Claude Code はそのセッションの `advisorModel` 設定の代わりにフラグを使用します。`claude --help` に `--advisor` をリストしません。Claude Code は以下の場合、起動時にエラーで終了します。87Claude Code はそのセッションの `advisorModel` 設定の代わりにフラグを使用します。`claude --help` に `--advisor` をリストしません。Claude Code は以下の場合、起動時にエラーで終了します。

88 88 

89* セッションのメインモデルが advisor をサポートしていない89* セッションのメインモデルが advisor をサポートしていない

90* Haiku などのリクエストされたモデルが advisor として機能できない90* Haiku 4.5 などのリクエストされたモデルが advisor として機能できない

91* 組織の [`availableModels`](/docs/ja/model-config#restrict-model-selection) 許可リストがリクエストされたモデルを除外している91* 組織の [`availableModels`](/docs/ja/model-config#restrict-model-selection) 許可リストがリクエストされたモデルを除外している

92* Fable をリクエストし、アカウントがまだ[使用クレジット同意](#fable-advisor-and-usage-credits)を必要としている92* Fable をリクエストし、アカウントがまだ[使用クレジット同意](#fable-advisor-and-usage-credits)を必要としている

93 93 

103 103 

104| メインモデル | 受け入れられるアドバイザー |104| メインモデル | 受け入れられるアドバイザー |

105| - | - |105| - | - |

106| Haiku 4.5 | Fable、Opus、Sonnet |106| Haiku 4.5 | Fable、Opus、Sonnet、Haiku 5.5 |

107| Sonnet 4.6 | Fable、Opus、Sonnet |107| Sonnet 4.6 | Fable、Opus、Sonnet、Haiku 5.5 |

108| Opus 4.6 | Fable、Opus、Sonnet 5 以降 |108| Opus 4.6 | Fable、Opus、Sonnet 5 以降、Haiku 5.5 |

109| Sonnet 5 | Fable、Opus 4.7 以降、Sonnet 5 以降 |109| Sonnet 5 または Haiku 5.5 | Fable、Opus 4.7 以降、Sonnet 5 以降、Haiku 5.5 |

110| Opus 4.7 または Opus 4.8 | Fable、Opus 4.7 以降、Sonnet 5.5 |110| Opus 4.7 または Opus 4.8 | Fable、Opus 4.7 以降、Sonnet 5.5 |

111| Sonnet 5.5 | Fable、Opus 5 以降、Sonnet 5.5 |111| Sonnet 5.5 | Fable、Opus 5 以降、Sonnet 5.5 |

112| Opus 5 または Opus 5.5 | Fable、Opus 5 以降 |112| Opus 5 または Opus 5.5 | Fable、Opus 5 以降 |

113| Fable 5 | Fable 5.1 または Fable 5 |113| Fable 5 | Fable 5.1 または Fable 5 |

114| Fable 5.1 | Fable 5.1 |114| Fable 5.1 | Fable 5.1 |

115 115 

116Fable 5.1 には Claude Code v2.1.257 以降が必要です。Fable モデルには [Fable アクセス](/docs/ja/model-config#work-with-fable) が必要です。Opus 4.7 または Opus 4.8 のメインモデルに対して Sonnet 5.5 をアドバイザーとして使用するには、Claude Code v2.1.287 以降が必要です。116Fable 5.1 には Claude Code v2.1.257 以降が必要です。Fable モデルには [Fable アクセス](/docs/ja/model-config#work-with-fable) が必要です。Opus 4.7 または Opus 4.8 のメインモデルに対して Sonnet 5.5 をアドバイザーとして使用するには、Claude Code v2.1.287 以降が必要です。Haiku 5.5 をメインモデルまたはアドバイザーとして使用するには、Claude Code v2.1.293 以降が必要です。

117 117 

118アドバイザーを `fable`、`opus`、または `sonnet` として設定します。これらのエイリアスは Claude Code の各モデルファミリーの[組み込みデフォルトバージョン](/docs/ja/model-config#model-aliases)に解決され、新しい Claude Code リリースで進化します。`claude-opus-5-5` などの完全なモデル ID を渡すこともできます。Haiku はアドバイザーを呼び出すことはできますが、アドバイザーとして機能することはできません。118アドバイザーを `fable`、`opus`、または `sonnet` として設定します。これらのエイリアスは Claude Code の各モデルファミリーの[組み込みデフォルトバージョン](/docs/ja/model-config#model-aliases)に解決され、新しい Claude Code リリースで進化します。`claude-opus-5-5` や `claude-haiku-5-5` などの完全なモデル ID を渡すこともできます。Haiku 4.5 はアドバイザーを呼び出すことはできますが、アドバイザーとして機能することはできません。

119 119 

120サブエージェントは設定されたアドバイザーを継承し、独自のモデルに対して同じペアリングチェックを適用します。120サブエージェントは設定されたアドバイザーを継承し、独自のモデルに対して同じペアリングチェックを適用します。

121 121 

202advisor ツールには、以下のすべてが必要です。202advisor ツールには、以下のすべてが必要です。

203 203 

204* **Anthropic API のみ**：advisor はサーバー実行ツールです。Amazon Bedrock、Claude Platform on AWS、Google Cloud の Agent Platform、または Microsoft Foundry では利用できません。[LLM ゲートウェイ](/docs/ja/llm-gateway)を通じて `ANTHROPIC_BASE_URL` で構成されている場合、利用可能性はゲートウェイがリクエストを Anthropic API に完全に転送するかどうかに依存します。ゲートウェイまたはそのアップストリームが advisor ツールを認識しない場合は、[自動リトライとエラー転送](/docs/ja/llm-gateway-protocol#automatic-retry-and-error-forwarding)を参照して、Claude Code がどのように応答するかを確認してください。204* **Anthropic API のみ**：advisor はサーバー実行ツールです。Amazon Bedrock、Claude Platform on AWS、Google Cloud の Agent Platform、または Microsoft Foundry では利用できません。[LLM ゲートウェイ](/docs/ja/llm-gateway)を通じて `ANTHROPIC_BASE_URL` で構成されている場合、利用可能性はゲートウェイがリクエストを Anthropic API に完全に転送するかどうかに依存します。ゲートウェイまたはそのアップストリームが advisor ツールを認識しない場合は、[自動リトライとエラー転送](/docs/ja/llm-gateway-protocol#automatic-retry-and-error-forwarding)を参照して、Claude Code がどのように応答するかを確認してください。

205* **サポートされているメインモデル**：Fable、Opus 4.6 以降、Sonnet 4.6 以降、または Haiku 4.5。[advisor モデルを選択する](#choose-an-advisor-model)を参照して、各 advisor がどのモデルを受け入れるかを確認してください。205* **サポートされているメインモデル**：Fable、Opus 4.6 以降、Sonnet 4.6 以降、Haiku 4.5、または Haiku 5.5。各メインモデルがどの advisor を受け入れるかについては、[advisor モデルを選択する](#choose-an-advisor-model)を参照してください。

206* **フィーチャーフラグ取得**：Claude Code は Anthropic から取得するフィーチャーフラグを通じて advisor をオンにします。`DISABLE_TELEMETRY` など、フラグ取得をオフにする変数が設定されているセッションでは、advisor はオフのままです。[フィーチャーフラグ取得が必要な機能](/docs/ja/env-vars#features-that-need-feature-flag-fetching)を参照してください。206* **フィーチャーフラグ取得**：Claude Code は Anthropic から取得するフィーチャーフラグを通じて advisor をオンにします。`DISABLE_TELEMETRY` など、フラグ取得をオフにする変数が設定されているセッションでは、advisor はオフのままです。[フィーチャーフラグ取得が必要な機能](/docs/ja/env-vars#features-that-need-feature-flag-fetching)を参照してください。

207 207 

208<h2 id="turn-the-advisor-off">208<h2 id="turn-the-advisor-off">

27 SDK は、そのイベントタイプに登録されたフックをチェックします。これには、`options.hooks` に渡すコールバックフックと、対応する [`settingSources`](/docs/ja/agent-sdk/typescript#settingsource) または [`setting_sources`](/docs/ja/agent-sdk/python#settingsource) エントリが有効になっているときの設定ファイルからのシェルコマンドフックが含まれます。これはデフォルトの `query()` オプションで有効になっています。27 SDK は、そのイベントタイプに登録されたフックをチェックします。これには、`options.hooks` に渡すコールバックフックと、対応する [`settingSources`](/docs/ja/agent-sdk/typescript#settingsource) または [`setting_sources`](/docs/ja/agent-sdk/python#settingsource) エントリが有効になっているときの設定ファイルからのシェルコマンドフックが含まれます。これはデフォルトの `query()` オプションで有効になっています。

28 </Step>28 </Step>

29 29 

30 <Step title="マッチャーがどのフックを実行するかをフィルタリングする">30 <Step title="matcher がどのフックを実行するかをフィルタリングする">

31 フックに [`matcher`](#matchers) パターン（`"Write|Edit"` など）がある場合、SDK はそれをイベントのターゲット（たとえば、ツール名）に対してテストします。マッチャーのないフックは、そのタイプのすべてのイベントに対して実行されます。31 フックに [`matcher`](#matchers) パターン（`"Write|Edit"` など）がある場合、SDK はそれをイベントのターゲット（たとえば、ツール名）に対してテストします。matcher のないフックは、そのタイプのすべてのイベントに対して実行されます。

32 </Step>32 </Step>

33 33 

34 <Step title="コールバック関数が実行される">34 <Step title="コールバック関数が実行される">

40 </Step>40 </Step>

41</Steps>41</Steps>

42 42 

43次の例は、これらのステップをまとめたものです。`PreToolUse` フック（ステップ 1）を `"Write|Edit"` マッチャー（ステップ 3）で登録して、コールバックがファイル書き込みツールに対してのみ発火するようにします。トリガーされると、コールバックはツールの入力（ステップ 4）を受け取り、ファイルパスが `.env` ファイルをターゲットにしているかどうかをチェックし、`permissionDecision: "deny"` を返して操作をブロックします（ステップ 5）。43次の例は、これらのステップをまとめたものです。`PreToolUse` フック（ステップ 1）を `"Write|Edit"` matcher（ステップ 3）で登録して、コールバックがファイル書き込みツールに対してのみ発火するようにします。トリガーされると、コールバックはツールの入力（ステップ 4）を受け取り、ファイルパスが `.env` ファイルをターゲットにしているかどうかをチェックし、`permissionDecision: "deny"` を返して操作をブロックします（ステップ 5）。

44 44 

45<CodeGroup>45<CodeGroup>

46 ```python Python theme={null}46 ```python Python theme={null}

78 options = ClaudeAgentOptions(78 options = ClaudeAgentOptions(

79 hooks={79 hooks={

80 # PreToolUse イベントのフックを登録する80 # PreToolUse イベントのフックを登録する

81 # マッチャーは Write と Edit ツール呼び出しのみにフィルタリングする81 # matcher は Write と Edit ツール呼び出しのみにフィルタリングする

82 "PreToolUse": [HookMatcher(matcher="Write|Edit", hooks=[protect_env_files])]82 "PreToolUse": [HookMatcher(matcher="Write|Edit", hooks=[protect_env_files])]

83 }83 }

84 )84 )

127 options: {127 options: {

128 hooks: {128 hooks: {

129 // PreToolUse イベントのフックを登録する129 // PreToolUse イベントのフックを登録する

130 // マッチャーは Write と Edit ツール呼び出しのみにフィルタリングする130 // matcher は Write と Edit ツール呼び出しのみにフィルタリングする

131 PreToolUse: [{ matcher: "Write|Edit", hooks: [protectEnvFiles] }]131 PreToolUse: [{ matcher: "Write|Edit", hooks: [protectEnvFiles] }]

132 }132 }

133 }133 }

140 ```140 ```

141</CodeGroup>141</CodeGroup>

142 142 

143どちらのスクリプトを実行しても、Claude は `.env` ファイルを作成しようとし、フックはツール呼び出しを拒否し、Claude の最終的な応答は `.env` ファイルを作成できないことを説明します。143どちらのスクリプトを実行しても、Claude は `.env` ファイルを作成しようとし、フックはツール呼び出しを拒否します。

144 144 

145<h2 id="available-hooks">145<h2 id="available-hooks">

146 利用可能なフック146 利用可能なフック

179| `ConfigChange` | いいえ | はい | 設定ファイル変更 | 設定を動的に再ロードする |179| `ConfigChange` | いいえ | はい | 設定ファイル変更 | 設定を動的に再ロードする |

180| `InstructionsLoaded` | いいえ | はい | `CLAUDE.md` またはルールファイルがコンテキストにロードされる | どの命令ファイルがロードされるかを監査する |180| `InstructionsLoaded` | いいえ | はい | `CLAUDE.md` またはルールファイルがコンテキストにロードされる | どの命令ファイルがロードされるかを監査する |

181| `WorktreeCreate` | いいえ | はい | Git ワークツリー作成 | 分離されたワークスペースを追跡する |181| `WorktreeCreate` | いいえ | はい | Git ワークツリー作成 | 分離されたワークスペースを追跡する |

182| `WorktreeRemove` | いいえ | はい | Git ワークツリー削除 | ワークスペースリソースをクリーンアップする |182| `WorktreeRemove` | いいえ | はい | `WorktreeCreate` フックによって作成された worktree が削除されようとしている | ワークスペースリソースをクリーンアップする |

183| `CwdChanged` | いいえ | はい | セッション中に作業ディレクトリが変更される | ディレクトリごとに環境変数を再ロードする |183| `CwdChanged` | いいえ | はい | セッション中に作業ディレクトリが変更される | ディレクトリごとに環境変数を再ロードする |

184| `FileChanged` | いいえ | はい | 監視対象ファイルが変更、作成、または削除される | プロジェクトファイルが変更されたときに設定を再ロードする |184| `FileChanged` | いいえ | はい | 監視対象ファイルが変更、作成、または削除される | プロジェクトファイルが変更されたときに設定を再ロードする |

185| `DirectoryAdded` | いいえ | はい | セッション中に作業ディレクトリが追加される | セッション中に追加されたリポジトリの依存関係をインストールする |185| `DirectoryAdded` | いいえ | はい | セッション中に作業ディレクトリが追加される | セッション中に追加されたリポジトリの依存関係をインストールする |

262* **トップレベルフィールド**はすべてのイベントで受け入れられます。`systemMessage` はユーザーにメッセージを表示し、`continue`（Python では `continue_`）はこのフック後にエージェントが実行を続けるかどうかを決定します。一部のイベントはこれらを破棄するか、別の場所に配信します。各[イベントのセクション](/docs/ja/hooks#hook-events)はフックページでそれらがどこに着地するかを説明しています。262* **トップレベルフィールド**はすべてのイベントで受け入れられます。`systemMessage` はユーザーにメッセージを表示し、`continue`（Python では `continue_`）はこのフック後にエージェントが実行を続けるかどうかを決定します。一部のイベントはこれらを破棄するか、別の場所に配信します。各[イベントのセクション](/docs/ja/hooks#hook-events)はフックページでそれらがどこに着地するかを説明しています。

263* **`hookSpecificOutput`** は現在の操作を制御します。内部に設定するフィールドはフックイベントタイプに依存します。263* **`hookSpecificOutput`** は現在の操作を制御します。内部に設定するフィールドはフックイベントタイプに依存します。

264 * `PreToolUse` フックの場合、ここで `permissionDecision`（`"allow"`、`"deny"`、`"ask"`、または `"defer"`）、`permissionDecisionReason`、および `updatedInput` を設定します。`"defer"` を返すと、`stop_reason` が `"tool_deferred"` である結果メッセージでターンが終了するため、[後で呼び出しを再開](/docs/ja/hooks#defer-a-tool-call-for-later)できます。264 * `PreToolUse` フックの場合、ここで `permissionDecision`（`"allow"`、`"deny"`、`"ask"`、または `"defer"`）、`permissionDecisionReason`、および `updatedInput` を設定します。`"defer"` を返すと、`stop_reason` が `"tool_deferred"` である結果メッセージでターンが終了するため、[後で呼び出しを再開](/docs/ja/hooks#defer-a-tool-call-for-later)できます。

265 * `PostToolUse` フックの場合、`additionalContext` を設定してツール結果に情報を追加できます。Claude がそれを見る前にツールの出力を置き換えるには、`updatedToolOutput` を設定します。これは両方の SDK のすべてのツールで機能します。古い `updatedMCPToolOutput` フィールドは MCP ツール出力のみを置き換え、非推奨です。265 * `PostToolUse` フックの場合、`additionalContext` を設定してツール結果に情報を追加できます。Claude がそれを見る前にツールの出力を置き換えるには、`updatedToolOutput` を設定します。これは両方の SDK のすべてのツールで機能します。古い `updatedMCPToolOutput` フィールドは MCP ツール出力のみを置き換えます。

266 * TypeScript SDK では、`PostToolUse` コールバックは `classifierContext` を返すこともできます。これはツール呼び出しの結果に関する短いメモで、[auto モード](/docs/ja/permission-modes#eliminate-prompts-with-auto-mode)の権限分類器用です。コールバックはアプリケーション独自のプロセスで実行されるため、分類器はメモで中継するユーザーステートメントをユーザーの意図として重視する可能性があります。このフィールドは TypeScript Agent SDK v0.3.236 以降が必要です。[auto モード分類器の結果に注釈を付ける](/docs/ja/hooks#annotate-a-result-for-the-auto-mode-classifier)は長さの上限、同期のみのルール、およびメモに何を入れないかをカバーしています。266 * TypeScript SDK では、`PostToolUse` コールバックは `classifierContext` を返すこともできます。これはツール呼び出しの結果に関する短いメモで、[auto モード](/docs/ja/permission-modes#eliminate-prompts-with-auto-mode)の権限分類器用です。コールバックはアプリケーション独自のプロセスで実行されるため、分類器はメモで中継するユーザーステートメントをユーザーの意図として重視する可能性があります。このフィールドは TypeScript Agent SDK v0.3.236 以降が必要です。[auto モード分類器の結果に注釈を付ける](/docs/ja/hooks#annotate-a-result-for-the-auto-mode-classifier)は長さの上限、同期のみのルール、およびメモに何を入れないかをカバーしています。

267 267 

268変更なしで操作を許可するには `{}` を返します。SDK コールバックフックは、[Claude Code シェルコマンドフック](/docs/ja/hooks#json-output)と同じ JSON 出力形式を使用します。これはすべてのフィールドとイベント固有のオプションを文書化しています。SDK 型定義については、[TypeScript](/docs/ja/agent-sdk/typescript#synchookjsonoutput) および [Python](/docs/ja/agent-sdk/python#synchookjsonoutput) SDK リファレンスを参照してください。268変更なしで操作を許可するには `{}` を返します。SDK コールバックフックは、[Claude Code シェルコマンドフック](/docs/ja/hooks#json-output)と同じ JSON 出力形式を使用します。これはすべてのフィールドとイベント固有のオプションを文書化しています。SDK 型定義については、[TypeScript](/docs/ja/agent-sdk/typescript#synchookjsonoutput) および [Python](/docs/ja/agent-sdk/python#synchookjsonoutput) SDK リファレンスを参照してください。

269 269 

270<Note>270<Note>

271 複数のフックまたはパーミッションルールが適用される場合、`deny` は `defer` より優先され、`defer` は `ask` より優先され、`ask` は `allow` より優先されます。いずれかのフックが `deny` を返す場合、他のフックに関係なく操作はブロックされます。271 複数のフックまたは権限ルールが適用される場合、`deny` は `defer` より優先され、`defer` は `ask` より優先され、`ask` は `allow` より優先されます。いずれかのフックが `deny` を返す場合、他のフックに関係なく操作はブロックされます。

272</Note>272</Note>

273 273 

274<h4 id="asynchronous-output">274<h4 id="asynchronous-output">

802</h3>802</h3>

803 803 

804* フックイベント名が正しく、大文字と小文字が区別されていることを確認してください（`preToolUse` ではなく `PreToolUse`）804* フックイベント名が正しく、大文字と小文字が区別されていることを確認してください（`preToolUse` ではなく `PreToolUse`）

805* マッチャーパターンがツール名と正確に一致していることを確認してください805* matcher パターンがツール名と正確に一致していることを確認してください

806* フックが `options.hooks` の正しいイベントタイプの下にあることを確認してください806* フックが `options.hooks` の正しいイベントタイプの下にあることを確認してください

807* マッチャーをサポートする非ツールフック（`Notification` や `SubagentStop` など）の場合、マッチャーは異なるフィールドに対してマッチし、`Stop` はマッチャーを完全に無視します（[マッチャーパターン](/docs/ja/hooks#matcher-patterns)を参照）807* matcher をサポートする非ツールフック（`Notification` や `SubagentStop` など）の場合、matcher は異なるフィールドに対してマッチし、`Stop` は matcher を完全に無視します（[matcher パターン](/docs/ja/hooks#matcher-patterns)を参照）

808* エージェントが [`max_turns`](/docs/ja/agent-sdk/python#claudeagentoptions) 制限に達した場合、セッションが終了してからフックが実行される前にセッションが終了するため、フックが発火しない可能性があります808* エージェントが [`max_turns`](/docs/ja/agent-sdk/python#claudeagentoptions) 制限に達した場合、フックが実行される前にセッションが終了するため、フックが発火しない可能性があります

809 809 

810<h3 id="matcher-not-filtering-as-expected">810<h3 id="matcher-not-filtering-as-expected">

811 マッチャーが期待通りにフィルタリングしない811 matcher が期待通りにフィルタリングしない

812</h3>812</h3>

813 813 

814マッチャーはツール名のみをマッチし、ファイルパスや他の引数はマッチしません。ファイルパスでフィルタリングするには、フック内で `tool_input.file_path` を確認してください：814matcher はツール名のみをマッチし、ファイルパスや他の引数はマッチしません。ファイルパスでフィルタリングするには、フック内で `tool_input.file_path` を確認してください：

815 815 

816```typescript theme={null}816```typescript theme={null}

817const myHook: HookCallback = async (input, toolUseID, { signal }) => {817const myHook: HookCallback = async (input, toolUseID, { signal }) => {

852 852 

853* すべての `PreToolUse` フックで `permissionDecision: 'deny'` の戻り値を確認してください853* すべての `PreToolUse` フックで `permissionDecision: 'deny'` の戻り値を確認してください

854* フックにログを追加して、返している `permissionDecisionReason` を確認してください854* フックにログを追加して、返している `permissionDecisionReason` を確認してください

855* マッチャーパターンが広すぎないことを確認してください：空のマッチャーはすべてのツールにマッチします855* matcher パターンが広すぎないことを確認してください：空の matcher はすべてのツールにマッチします

856 856 

857<h3 id="modified-input-not-applied">857<h3 id="modified-input-not-applied">

858 変更された入力が適用されない858 変更された入力が適用されない

878 Python でセッションフックが利用できない878 Python でセッションフックが利用できない

879</h3>879</h3>

880 880 

881`SessionStart` と `SessionEnd` は TypeScript で SDK コールバックフックとして登録できますが、その `HookEvent` タイプがそれらを省略しているため、Python SDK では利用できません。Python では、`.claude/settings.json` などの設定ファイルで定義された [シェルコマンドフック](/docs/ja/hooks#hook-events)としてのみ利用できます。SDK アプリケーションからシェルコマンドフックをロードするには、[`setting_sources`](/docs/ja/agent-sdk/python#settingsource) または [`settingSources`](/docs/ja/agent-sdk/typescript#settingsource) で適切な設定ソースを含めてください：881`SessionStart` と `SessionEnd` は TypeScript で SDK コールバックフックとして登録できますが、その `HookEvent` タイプがそれらを省略しているため、Python SDK では利用できません。Python では、`.claude/settings.json` などの設定ファイルで定義された [シェルコマンドフック](/docs/ja/hooks#hook-events)としてのみ利用できます。SDK アプリケーションがどの設定ファイルをロードするかは、[`setting_sources`](/docs/ja/agent-sdk/python#settingsource) または [`settingSources`](/docs/ja/agent-sdk/typescript#settingsource) によって決まります。このオプションを設定する場合は、フックを含むソースを含めてください：

882 882 

883<CodeGroup>883<CodeGroup>

884 ```python Python theme={null}884 ```python Python theme={null}

900 サブエージェント権限プロンプトが増加する900 サブエージェント権限プロンプトが増加する

901</h3>901</h3>

902 902 

903複数のサブエージェントをスポーンする場合、各サブエージェントは独自のツール呼び出しに対して権限を個別にリクエストする可能性があります。繰り返されるプロンプトを避けるには、`PreToolUse` フックを使用して特定のツールを自動承認するか、権限ルールを設定してください。サブエージェントは [親会話から権限ルールを継承](/docs/ja/sub-agents#permission-modes)します。903複数のサブエージェントをスポーンする場合、各サブエージェントは独自のツール呼び出しに対して権限を個別に求める可能性があります。繰り返されるプロンプトを避けるには、`PreToolUse` フックを使用して特定のツールを自動承認するか、権限ルールを設定してください。サブエージェントは [親会話から権限ルールを継承](/docs/ja/sub-agents#permission-modes)します。

904 904 

905<h3 id="recursive-hook-loops-with-subagents">905<h3 id="recursive-hook-loops-with-subagents">

906 サブエージェントを使用した再帰的フックループ906 サブエージェントを使用した再帰的フックループ

194 `ToolAnnotations`194 `ToolAnnotations`

195</h4>195</h4>

196 196 

197ツールの動作ヒント。[`tool()`](#tool) の `annotations` 引数として渡されます。`ToolAnnotations` は MCP SDK の `mcp.types.ToolAnnotations` を `maxResultSizeChars` フィールドで拡張し、各ヒントを camelCase または snake\_case で記述できます：`ToolAnnotations(readOnlyHint=True)` と `ToolAnnotations(read_only_hint=True)` は同等です。SDK がアノテーションを受け入れる場所であればどこでも、プレーンな `mcp.types.ToolAnnotations` を渡すこともできます。197ツールの動作ヒント。[`tool()`](#tool) の `annotations` 引数として渡されます。`ToolAnnotations` は MCP SDK の `mcp.types.ToolAnnotations` を `maxResultSizeChars` フィールドで拡張し、各ヒントを camelCase または snake\_case で記述できます：`ToolAnnotations(readOnlyHint=True)` と `ToolAnnotations(read_only_hint=True)` は同等です。オブジェクトからヒントを読み取る際は、インストールされている `mcp` パッケージが宣言している表記を使用してください：`mcp` 1.x では `.readOnlyHint`、2.x では `.read_only_hint` を使用し、`.maxResultSizeChars` はどちらでも動作します。SDK がアノテーションを受け入れる場所であればどこでも、プレーンな `mcp.types.ToolAnnotations` を渡すこともできます。

198 198 

199snake\_case 名と型付き `maxResultSizeChars` フィールドには Python Agent SDK 0.2.140 以降が必要です。バージョン 0.1.31 から 0.2.139 は `mcp.types.ToolAnnotations` を変更なしで再エクスポートします。バージョン 0.1.55 から 0.2.139 では、`maxResultSizeChars` をキーワード引数として渡すことができます：MCP クラスは追加フィールドを受け入れ、SDK は値を Claude Code に転送します。199snake\_case 名と型付き `maxResultSizeChars` フィールドには Python Agent SDK 0.2.140 以降が必要です。バージョン 0.1.31 から 0.2.139 は `mcp.types.ToolAnnotations` を変更なしで再エクスポートします。バージョン 0.1.55 から 0.2.139 では、`maxResultSizeChars` をキーワード引数として渡すことができます：MCP クラスは追加フィールドを受け入れ、SDK は値を Claude Code に転送します。

200 200 

950| `user` | `str \| None` | `None` | POSIXプラットフォームでは、Claude Codeサブプロセスが実行されるOSユーザーアカウント。Claude Codeは親プロセスの環境（`HOME`を含む）を保持し、`cwd`で実行されます |950| `user` | `str \| None` | `None` | POSIXプラットフォームでは、Claude Codeサブプロセスが実行されるOSユーザーアカウント。Claude Codeは親プロセスの環境（`HOME`を含む）を保持し、`cwd`で実行されます |

951| `include_partial_messages` | `bool` | `False` | 部分的なメッセージストリーミングイベントを含めます。有効にすると、[`StreamEvent`](#streamevent)メッセージが生成されます |951| `include_partial_messages` | `bool` | `False` | 部分的なメッセージストリーミングイベントを含めます。有効にすると、[`StreamEvent`](#streamevent)メッセージが生成されます |

952| `include_hook_events` | `bool` | `False` | メッセージストリームに`HookEventMessage`オブジェクトとしてフックライフサイクルイベントを含めます |952| `include_hook_events` | `bool` | `False` | メッセージストリームに`HookEventMessage`オブジェクトとしてフックライフサイクルイベントを含めます |

953| `forward_subagent_text` | `bool` | `False` | メッセージストリームでサブエージェントのテキストと思考ブロックを転送します。このオプションがない場合、Claude Codeはサブエージェント`tool_use`と`tool_result`ブロックを出力しますが、テキストや思考は出力しません。Python Agent SDK 0.2.140以降が必要です |953| `forward_subagent_text` | `bool` | `False` | メッセージストリームでサブエージェントのテキストと思考ブロックを転送します。このオプションがない場合、Claude Codeは[フォアグラウンド](/docs/ja/sub-agents#run-subagents-in-foreground-or-background)で実行されるサブエージェントのテキストと思考ブロックを省略します。ネストされたサブエージェント、`context: fork`を持つスキル、およびそれぞれに必要なClaude Codeのバージョンについては、[サブエージェントのメッセージを追跡する](/docs/ja/headless#follow-subagent-messages)を参照してください。Python Agent SDK 0.2.140以降が必要です |

954| `verbatim_prompts` | `bool` | `False` | すべてのプロンプトを書かれたとおりに配信します。SDKは各ユーザーメッセージを`client_composed`を`True`に設定して送信します。Claude Codeがこれらのメッセージでスキップするものについては、[`client_composed`](/docs/ja/agent-sdk/typescript#sdkusermessage)を参照してください。プロンプトテキストにエンドユーザーが入力しなかったコンテンツが含まれている場合は、このオプションを使用します。ターンごとの制御については、これをオフのままにして、代わりにストリーミングされたメッセージで個別に`"client_composed": True`を設定します。オプションがオンの間、SDKは設定した`client_composed`値を上書きします。Python Agent SDK 0.2.158以降およびClaude Code v2.1.248以降が必要です。これらのSDKバージョンにバンドルされているCLIはClaude Code要件を満たします |954| `verbatim_prompts` | `bool` | `False` | すべてのプロンプトを書かれたとおりに配信します。SDKは各ユーザーメッセージを`client_composed`を`True`に設定して送信します。Claude Codeがこれらのメッセージでスキップするものについては、[`client_composed`](/docs/ja/agent-sdk/typescript#sdkusermessage)を参照してください。プロンプトテキストにエンドユーザーが入力しなかったコンテンツが含まれている場合は、このオプションを使用します。ターンごとの制御については、これをオフのままにして、代わりにストリーミングされたメッセージで個別に`"client_composed": True`を設定します。オプションがオンの間、SDKは設定した`client_composed`値を上書きします。Python Agent SDK 0.2.158以降およびClaude Code v2.1.248以降が必要です。これらのSDKバージョンにバンドルされているCLIはClaude Code要件を満たします |

955| `fork_session` | `bool` | `False` | `resume`で再開するときに、元のセッションを続行する代わりに新しいセッションIDにフォークします |955| `fork_session` | `bool` | `False` | `resume`で再開するときに、元のセッションを続行する代わりに新しいセッションIDにフォークします |

956| `resume_session_at` | `str \| None` | `None` | 再開するときに、このUUIDを持つメッセージまでを含めて会話を読み込みます。`resume`を使用し、通常は`fork_session`を使用して、以前のポイントから分岐します。Python Agent SDK 0.2.137以降が必要です |956| `resume_session_at` | `str \| None` | `None` | 再開するときに、このUUIDを持つメッセージまでを含めて会話を読み込みます。`resume`を使用し、通常は`fork_session`を使用して、以前のポイントから分岐します。Python Agent SDK 0.2.137以降が必要です |

962| `skills` | `list[str] \| Literal["all"] \| None` | `None` | セッションで利用可能なスキル。すべての発見されたスキルを有効にするには`"all"`を渡すか、スキル名のリストを渡します。正確な名前のみを渡します。SDKは形式が正しくないワイルドカード形式の名前を`ValueError`で拒否してからClaude Codeプロセスを開始します。このチェックにはPython Agent SDK 0.2.129以降が必要です。設定すると、SDKはSkillツールを`allowed_tools`に自動的に追加します。`tools`も渡す場合は、そのリストに`"Skill"`を含めます。[スキル](/docs/ja/agent-sdk/skills)を参照してください |962| `skills` | `list[str] \| Literal["all"] \| None` | `None` | セッションで利用可能なスキル。すべての発見されたスキルを有効にするには`"all"`を渡すか、スキル名のリストを渡します。正確な名前のみを渡します。SDKは形式が正しくないワイルドカード形式の名前を`ValueError`で拒否してからClaude Codeプロセスを開始します。このチェックにはPython Agent SDK 0.2.129以降が必要です。設定すると、SDKはSkillツールを`allowed_tools`に自動的に追加します。`tools`も渡す場合は、そのリストに`"Skill"`を含めます。[スキル](/docs/ja/agent-sdk/skills)を参照してください |

963| `max_thinking_tokens` | `int \| None` | `None` | *非推奨* - 思考ブロックの最大トークン数。代わりに`thinking`を使用してください |963| `max_thinking_tokens` | `int \| None` | `None` | *非推奨* - 思考ブロックの最大トークン数。代わりに`thinking`を使用してください |

964| `thinking` | [`ThinkingConfig`](#thinkingconfig) ` \| None` | `None` | 拡張思考動作を制御します。`max_thinking_tokens`より優先されます |964| `thinking` | [`ThinkingConfig`](#thinkingconfig) ` \| None` | `None` | 拡張思考動作を制御します。`max_thinking_tokens`より優先されます |

965| `effort` | [`EffortLevel`](#effortlevel) ` \| None` | `None` | 思考の深さの努力レベル。[努力レベルを調整](/docs/ja/model-config#adjust-effort-level)を参照してください |965| `effort` | [`EffortLevel`](#effortlevel) ` \| None` | `None` | 思考の深さのeffort レベル。[effort レベルを調整](/docs/ja/model-config#adjust-effort-level)を参照してください |

966| `session_store` | [`SessionStore`](/docs/ja/agent-sdk/session-storage#the-sessionstore-interface) ` \| None` | `None` | セッショントランスクリプトを外部バックエンドにミラーリングして、別のホストがそれらを再開できるようにします。[セッションを外部ストレージに永続化](/docs/ja/agent-sdk/session-storage)を参照してください |966| `session_store` | [`SessionStore`](/docs/ja/agent-sdk/session-storage#the-sessionstore-interface) ` \| None` | `None` | セッショントランスクリプトを外部バックエンドにミラーリングして、別のホストがそれらを再開できるようにします。[セッションを外部ストレージに永続化](/docs/ja/agent-sdk/session-storage)を参照してください |

967| `session_store_flush` | `Literal["batched", "eager"]` | `"batched"` | ミラーリングされたトランスクリプトエントリを`session_store`にフラッシュするタイミング。`"batched"`はターンごと、またはバッファが満杯になったときにフラッシュします。`"eager"`はすべてのフレームの後にバックグラウンドフラッシュをトリガーします。`session_store`が`None`の場合は無視されます |967| `session_store_flush` | `Literal["batched", "eager"]` | `"batched"` | ミラーリングされたトランスクリプトエントリを`session_store`にフラッシュするタイミング。`"batched"`はターンごと、またはバッファが満杯になったときにフラッシュします。`"eager"`はすべてのフレームの後にバックグラウンドフラッシュをトリガーします。`session_store`が`None`の場合は無視されます |

968| `load_timeout_ms` | `int` | `60000` | 再開の具体化中に`session_store.load()`と`list_subkeys()`のコール単位のタイムアウト（ミリ秒） |968| `load_timeout_ms` | `int` | `60000` | 再開の具体化中に`session_store.load()`と`list_subkeys()`のコール単位のタイムアウト（ミリ秒） |

993 タイマーは各ストリームイベントでリセットされます。停止時、Claude Codeはサブエージェントを中止し、停止を親に報告します。バックグラウンドサブエージェントの場合、タスクも失敗とマークし、部分的な結果を添付します。993 タイマーは各ストリームイベントでリセットされます。停止時、Claude Codeはサブエージェントを中止し、停止を親に報告します。バックグラウンドサブエージェントの場合、タスクも失敗とマークし、部分的な結果を添付します。

994* `CLAUDE_ENABLE_STREAM_WATCHDOG`と`CLAUDE_STREAM_IDLE_TIMEOUT_MS`：ヘッダーが到着したがレスポンスボディがストリーミングを停止したときにリクエストを中止するストリームウォッチドッグ。ウォッチドッグはすべてのプロバイダーでデフォルトでオンです。無効にするには`CLAUDE_ENABLE_STREAM_WATCHDOG=0`を設定します。`CLAUDE_STREAM_IDLE_TIMEOUT_MS`はデフォルト`300000`で、その最小値にクランプされます。中止後、[自動リトライ](/docs/ja/errors#automatic-retries)はレスポンスがどこまで進んだかに基づいて、Claude Codeが何をするかをカバーします。994* `CLAUDE_ENABLE_STREAM_WATCHDOG`と`CLAUDE_STREAM_IDLE_TIMEOUT_MS`：ヘッダーが到着したがレスポンスボディがストリーミングを停止したときにリクエストを中止するストリームウォッチドッグ。ウォッチドッグはすべてのプロバイダーでデフォルトでオンです。無効にするには`CLAUDE_ENABLE_STREAM_WATCHDOG=0`を設定します。`CLAUDE_STREAM_IDLE_TIMEOUT_MS`はデフォルト`300000`で、その最小値にクランプされます。中止後、[自動リトライ](/docs/ja/errors#automatic-retries)はレスポンスがどこまで進んだかに基づいて、Claude Codeが何をするかをカバーします。

995 995 

996 ウォッチドッグが`ANTHROPIC_BASE_URL`の背後にあるゲートウェイが保持するレスポンスをキープアライブピングで待機している間、`include_partial_messages`を設定するホストは`ping` [`StreamEvent`](#streamevent)メッセージを受け取り続けます。これらのフレームを最後の実際のストリームイベント後の5分ではなく、生存性として読み取ります。v2.1.257より前は、フレームは停止しました。996 `ANTHROPIC_BASE_URL`の背後にあるゲートウェイがキープアライブピングで開いたままにしているレスポンスをウォッチドッグが待機している間、`include_partial_messages`を設定するホストは`ping` [`StreamEvent`](#streamevent)メッセージを受け取り続けます。無応答を理由にセッションをタイムアウトさせるのではなく、これらのフレームを生存確認として扱ってください。v2.1.257より前は、最後の実際のストリームイベントから5分後にこれらのフレームが停止していました。

997 997 

998<h3 id="outputformat">998<h3 id="outputformat">

999 `OutputFormat`999 `OutputFormat`

1035| `preset` | はい | Claude Codeのシステムプロンプトを使用するには`"claude_code"`である必要があります |1035| `preset` | はい | Claude Codeのシステムプロンプトを使用するには`"claude_code"`である必要があります |

1036| `append` | いいえ | プリセットシステムプロンプトに追加する追加の指示 |1036| `append` | いいえ | プリセットシステムプロンプトに追加する追加の指示 |

1037| `exclude_dynamic_sections` | いいえ | ユーザーごとのコンテキスト（自動メモリロケーションなど）をシステムプロンプトから最初のユーザーメッセージに移動します。ユーザーとマシン間のプロンプトキャッシュの再利用を改善します。[システムプロンプトを変更](/docs/ja/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines)を参照してください |1037| `exclude_dynamic_sections` | いいえ | ユーザーごとのコンテキスト（自動メモリロケーションなど）をシステムプロンプトから最初のユーザーメッセージに移動します。ユーザーとマシン間のプロンプトキャッシュの再利用を改善します。[システムプロンプトを変更](/docs/ja/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines)を参照してください |

1038| `snapshot` | いいえ | `False`に設定して、[セッションが最初のリクエストで記録したプロンプトを再利用する](/docs/ja/agent-sdk/modifying-system-prompts#change-the-prompt-of-an-existing-session)代わりに、すべてのリクエストでシステムプロンプトを再構築します。Python Agent SDK 0.2.153以降が必要です |1038| `snapshot` | いいえ | `False`に設定して、[セッションが最初のリクエストで記録したプロンプトを再利用する](/docs/ja/agent-sdk/modifying-system-prompts#change-the-prompt-of-an-existing-session)代わりに、すべてのリクエストでシステムプロンプトを再構築します。`claude-agent-sdk` v0.2.153以降が必要です |

1039 1039 

1040<h3 id="systempromptcustom">1040<h3 id="systempromptcustom">

1041 `SystemPromptCustom`1041 `SystemPromptCustom`

1042</h3>1042</h3>

1043 1043 

1044文字列として`system_prompt`を渡すのと同等のオブジェクト形式のカスタムシステムプロンプト。`snapshot`も設定できます。Python Agent SDK 0.2.153以降が必要です。1044文字列として`system_prompt`を渡すのと同等のオブジェクト形式のカスタムシステムプロンプト。`snapshot`も設定できます。`claude-agent-sdk` v0.2.153以降が必要です。

1045 1045 

1046```python theme={null}1046```python theme={null}

1047class SystemPromptCustom(TypedDict):1047class SystemPromptCustom(TypedDict):

11862. プロジェクト設定（`.claude/settings.json`）11862. プロジェクト設定（`.claude/settings.json`）

11873. ユーザー設定（`~/.claude/settings.json`）11873. ユーザー設定（`~/.claude/settings.json`）

1188 1188 

1189`agents`、`allowed_tools`、`settings`などのプログラム的なオプションは、ユーザー、プロジェクト、ローカルのファイルシステム設定をオーバーライドします。管理ポリシー設定はプログラム的なオプションより優先されます。1189`agents`、`allowed_tools`、`settings`などのプログラム的なオプションは、ユーザー、プロジェクト、ローカルのファイルシステム設定を上書きします。管理ポリシー設定はプログラム的なオプションより優先されます。

1190 1190 

1191<h3 id="agentdefinition">1191<h3 id="agentdefinition">

1192 `AgentDefinition`1192 `AgentDefinition`

1218| `prompt` | はい | エージェントのシステムプロンプト |1218| `prompt` | はい | エージェントのシステムプロンプト |

1219| `tools` | いいえ | 許可されたツール名の配列。省略した場合、[サブエージェントで利用可能なすべてのツール](/docs/ja/sub-agents#available-tools)を継承します |1219| `tools` | いいえ | 許可されたツール名の配列。省略した場合、[サブエージェントで利用可能なすべてのツール](/docs/ja/sub-agents#available-tools)を継承します |

1220| `disallowedTools` | いいえ | エージェントのツールセットから削除するツール名の配列。MCPサーバーレベルのパターンも受け入れられます：`mcp__server`または`mcp__server__*`はそのサーバーからすべてのツールを削除し、`mcp__*`は任意のサーバーからすべてのMCPツールを削除します |1220| `disallowedTools` | いいえ | エージェントのツールセットから削除するツール名の配列。MCPサーバーレベルのパターンも受け入れられます：`mcp__server`または`mcp__server__*`はそのサーバーからすべてのツールを削除し、`mcp__*`は任意のサーバーからすべてのMCPツールを削除します |

1221| `model` | いいえ | このエージェントのモデルオーバーライド。`"sonnet"`、`"opus"`、`"haiku"`、`"inherit"`などのエイリアス、または完全なモデルIDを受け入れます。省略すると、Claude Codeは[サブエージェントモデル順序](/docs/ja/sub-agents#choose-a-model)でモデルを選択します |1221| `model` | いいえ | このエージェントのモデルの上書き。`"sonnet"`、`"opus"`、`"haiku"`、`"inherit"`などのエイリアス、または完全なモデルIDを受け入れます。省略すると、Claude Codeは[サブエージェントモデル順序](/docs/ja/sub-agents#choose-a-model)でモデルを選択します |

1222| `skills` | いいえ | 起動時にエージェントのコンテキストにプリロードするスキル名のリスト。リストされていないスキルはSkillツールを通じて呼び出し可能なままです |1222| `skills` | いいえ | 起動時にエージェントのコンテキストにプリロードするスキル名のリスト。リストされていないスキルはSkillツールを通じて呼び出し可能なままです |

1223| `memory` | いいえ | このエージェントのメモリソース：`"user"`、`"project"`、または`"local"` |1223| `memory` | いいえ | このエージェントのメモリソース：`"user"`、`"project"`、または`"local"` |

1224| `mcpServers` | いいえ | このエージェントで利用可能なMCPサーバー。各エントリはサーバー名またはインライン`{name: config}`辞書です |1224| `mcpServers` | いいえ | このエージェントで利用可能なMCPサーバー。各エントリはサーバー名またはインライン`{name: config}`辞書です |

1225| `initialPrompt` | いいえ | このエージェントがメインスレッドエージェントとして実行されるときに最初のユーザーターンとして自動送信されます |1225| `initialPrompt` | いいえ | このエージェントがメインスレッドエージェントとして実行されるときに最初のユーザーターンとして自動送信されます |

1226| `maxTurns` | いいえ | エージェントが停止する前のagentic ターンの最大数 |1226| `maxTurns` | いいえ | エージェントが停止する前のagentic ターンの最大数 |

1227| `background` | いいえ | 呼び出されたときにこのエージェントをブロッキングなしのバックグラウンドタスクとして実行します |1227| `background` | いいえ | 呼び出されたときにこのエージェントをブロッキングなしのバックグラウンドタスクとして実行します |

1228| `effort` | いいえ | このエージェントの推論努力レベル。名前付きレベルまたは整数を受け入れます。[`EffortLevel`](#effortlevel)を参照してください |1228| `effort` | いいえ | このエージェントの推論effort レベル。名前付きレベルまたは整数を受け入れます。[`EffortLevel`](#effortlevel)を参照してください |

1229| `permissionMode` | いいえ | このエージェント内のツール実行の権限モード。[サブエージェント継承ルール](/docs/ja/agent-sdk/permissions#available-modes)はいつそれが適用されるかを決定します。[`PermissionMode`](#permissionmode)を参照してください |1229| `permissionMode` | いいえ | このエージェント内のツール実行の権限モード。[サブエージェント継承ルール](/docs/ja/agent-sdk/permissions#available-modes)はいつそれが適用されるかを決定します。[`PermissionMode`](#permissionmode)を参照してください |

1230 1230 

1231<Note>1231<Note>

1243 "default", # 標準的な権限動作1243 "default", # 標準的な権限動作

1244 "acceptEdits", # ファイル編集を自動受け入れ1244 "acceptEdits", # ファイル編集を自動受け入れ

1245 "plan", # 計画モード - 編集なしで探索1245 "plan", # 計画モード - 編集なしで探索

1246 "dontAsk", # 事前承認されていないものを拒否する代わりにプロンプト1246 "dontAsk", # プロンプトを表示する代わりに、事前承認されていないものをすべて拒否

1247 "bypassPermissions", # 権限チェックをバイパス。明示的な質問ルールはまだプロンプト（注意して使用）1247 "bypassPermissions", # 権限チェックをバイパス。明示的な質問ルールはまだプロンプト（注意して使用）

1248 "auto", # モデル分類器が権限プロンプトを承認または拒否1248 "auto", # モデル分類器がシェルコマンドやネットワークリクエストなどのアクションをレビュー

1249]1249]

1250```1250```

1251 1251 

1253 `EffortLevel`1253 `EffortLevel`

1254</h3>1254</h3>

1255 1255 

1256思考の深さをガイドするための努力レベル。1256思考の深さをガイドするためのeffort レベル。

1257 1257 

1258```python theme={null}1258```python theme={null}

1259EffortLevel = Literal[1259EffortLevel = Literal[

1261 "medium", # 適度な思考1261 "medium", # 適度な思考

1262 "high", # 深い推論1262 "high", # 深い推論

1263 "xhigh", # 拡張推論。それをサポートしないモデルでは「高」にフォールバック1263 "xhigh", # 拡張推論。それをサポートしないモデルでは「高」にフォールバック

1264 "max", # 最大努力1264 "max", # 最大effort

1265]1265]

1266```1266```

1267 1267 

1316| `tool_use_id` | `str \| None` | このプロンプトが対象とする特定のツール呼び出しの識別子。`can_use_tool`に配信されるときは常に入力されます |1316| `tool_use_id` | `str \| None` | このプロンプトが対象とする特定のツール呼び出しの識別子。`can_use_tool`に配信されるときは常に入力されます |

1317| `agent_id` | `str \| None` | 呼び出しがサブエージェントから発生する場合のサブエージェントID。メインエージェントの場合は`None` |1317| `agent_id` | `str \| None` | 呼び出しがサブエージェントから発生する場合のサブエージェントID。メインエージェントの場合は`None` |

1318| `blocked_path` | `str \| None` | 権限リクエストをトリガーしたファイルパス（該当する場合）。例えば、Bashコマンドが許可されたディレクトリの外のパスにアクセスしようとする場合 |1318| `blocked_path` | `str \| None` | 権限リクエストをトリガーしたファイルパス（該当する場合）。例えば、Bashコマンドが許可されたディレクトリの外のパスにアクセスしようとする場合 |

1319| `decision_reason` | `str \| None` | この権限リクエストがトリガーされた理由。PreToolUseフックが`"ask"`を返したときにフックから転送されます |1319| `decision_reason` | `str \| None` | この権限リクエストがトリガーされた理由。PreToolUseフックが`"ask"`を返したときにフックの`permissionDecisionReason`から転送されます |

1320| `title` | `str \| None` | 完全な権限プロンプト文（例：`Claude wants to read foo.txt`）。存在する場合は、プライマリプロンプトテキストとして使用します |1320| `title` | `str \| None` | 完全な権限プロンプト文（例：`Claude wants to read foo.txt`）。存在する場合は、プライマリプロンプトテキストとして使用します |

1321| `display_name` | `str \| None` | ツールアクション用の短い名詞句（例：`Read file`）。ボタンラベルに適しています |1321| `display_name` | `str \| None` | ツールアクション用の短い名詞句（例：`Read file`）。ボタンラベルに適しています |

1322| `description` | `str \| None` | 権限UIの人間が読める字幕 |1322| `description` | `str \| None` | 権限UIの人間が読める字幕 |

1465| `enabled` | `type`、`budget_tokens`、`display` | 特定のトークン予算で思考を有効にします |1465| `enabled` | `type`、`budget_tokens`、`display` | 特定のトークン予算で思考を有効にします |

1466| `disabled` | `type` | 思考を無効にします |1466| `disabled` | `type` | 思考を無効にします |

1467 1467 

1468オプションの`display`フィールドは、思考テキストが`"summarized"`または`"omitted"`で返されるかどうかを制御します。Claude Opus 4.7以降では、APIデフォルトは`"omitted"`であるため、[`ThinkingBlock`](#thinkingblock)出力で思考コンテンツを受け取るには`"summarized"`を設定します。Claude Codeは`ANTHROPIC_BASE_URL`の背後にあるAmazon BedrockまたはGoogle Cloudのエージェントプラットフォームに`display`を送信しないため、これらのプロバイダーではOpus 4.7以降は`display`を`"summarized"`に設定した場合でも空の`ThinkingBlock`出力を返します。1468オプションの`display`フィールドは、思考テキストが`"summarized"`または`"omitted"`で返されるかどうかを制御します。Claude Opus 4.7以降では、APIデフォルトは`"omitted"`であるため、[`ThinkingBlock`](#thinkingblock)出力で思考コンテンツを受け取るには`"summarized"`を設定します。Claude Code は、Amazon Bedrock や Google Cloud の Agent Platform など、一部のプロバイダーには `display` の値を渡しません。これらのプロバイダーでは、`display` を `"summarized"` に設定した場合でも、Opus 4.7 以降は空の `ThinkingBlock` 出力を返します。

1469 1469 

1470これらは`TypedDict`クラスであるため、実行時にはプレーンな辞書です。辞書リテラルとして構築するか、クラスをコンストラクタのように呼び出します。どちらも`dict`を生成します。`config.budget_tokens`ではなく`config["budget_tokens"]`でフィールドにアクセスします：1470これらは`TypedDict`クラスであるため、実行時にはプレーンな辞書です。辞書リテラルとして構築するか、クラスをコンストラクタのように呼び出します。どちらも`dict`を生成します。`config.budget_tokens`ではなく`config["budget_tokens"]`でフィールドにアクセスします：

1471 1471 

1660 apiUsage: NotRequired[dict[str, Any] | None]1660 apiUsage: NotRequired[dict[str, Any] | None]

1661```1661```

1662 1662 

1663各`ContextUsageCategory`エントリは`name`、`tokens`、`color`、およびオプションの`isDeferred`フラグを含みます。`totalTokens`はセッションの現在のコンテキスト使用状況であり、`maxTokens`はその使用状況が測定されるウィンドウです。そのウィンドウはモデルのコンテキストウィンドウ、または自動コンパクション ウィンドウが適用される場合はより低いウィンドウであり、`rawMaxTokens`は`maxTokens`と同じ値を含みます。`apiUsage`はセッションの実行合計ではなく、最新のAPI応答からの使用状況を保持します。Claude Codeはオプションの`deferredBuiltinTools`、`systemTools`、`systemPromptSections`キーを設定しないため、型が宣言していても、それらが存在しないことを期待してください。1663各`ContextUsageCategory`エントリは`name`、`tokens`、`color`、およびオプションの`isDeferred`フラグを含みます。`totalTokens`はセッションの現在のコンテキスト使用状況であり、`maxTokens`はその使用状況が測定されるウィンドウです。そのウィンドウはモデルのコンテキストウィンドウ、または自動圧縮ウィンドウが適用される場合はそれより低いそのウィンドウであり、`rawMaxTokens`は`maxTokens`と同じ値を含みます。`apiUsage`はセッションの実行合計ではなく、最新のAPI応答からの使用状況を保持します。Claude Codeはオプションの`deferredBuiltinTools`、`systemTools`、`systemPromptSections`キーを設定しないため、型が宣言していても、それらが存在しないことを期待してください。

1664 1664 

1665<h3 id="sdkpluginconfig">1665<h3 id="sdkpluginconfig">

1666 `SdkPluginConfig`1666 `SdkPluginConfig`

1875| `maxOutputTokens` | `int` | このモデルの最大出力トークン制限。 |1875| `maxOutputTokens` | `int` | このモデルの最大出力トークン制限。 |

1876| `canonicalModel` | `str` | 価格ルックアップに使用される正規モデル ID。エントリがキーとなっている生のモデル文字列（プロバイダー固有の ID またはエイリアスなど）と異なる場合があります。常に存在するわけではありません。 |1876| `canonicalModel` | `str` | 価格ルックアップに使用される正規モデル ID。エントリがキーとなっている生のモデル文字列（プロバイダー固有の ID またはエイリアスなど）と異なる場合があります。常に存在するわけではありません。 |

1877| `provider` | `str` | このモデルを提供した API プロバイダー。例：`firstParty`、`bedrock`、`vertex`、`foundry`、`anthropicAws`、`mantle`、または `gateway`。常に存在するわけではありません。 |1877| `provider` | `str` | このモデルを提供した API プロバイダー。例：`firstParty`、`bedrock`、`vertex`、`foundry`、`anthropicAws`、`mantle`、または `gateway`。常に存在するわけではありません。 |

1878| `costBasis` | `str` | このモデルの最新リクエストの価格算出に使用された価格表。定価の場合は `list`、[`modelPricing`](/docs/ja/settings-reference#modelpricing) テーブルの場合は `managed`、どちらもモデル ID に一致しなかった場合は `unknown` です。常に存在するわけではなく、TypedDict で宣言されていないため、`.get()` で読み取ってください。Claude Code v2.1.246 以降が必要です。 |

1878 1879 

1879<h3 id="streamevent">1880<h3 id="streamevent">

1880 `StreamEvent`1881 `StreamEvent`

2166 """Base error for Claude SDK."""2167 """Base error for Claude SDK."""

2167```2168```

2168 2169 

2169単一ショットの `query()` がエラー結果で終了する場合（例えば、ターン制限エラー）、SDK は最終結果メッセージを生成した後に [`ResultError`](#resulterror) を発生させます。Python Agent SDK バージョン 0.2.140 より前は、`ClaudeSDKError` サブクラスではない通常の `Exception` を発生させていました。2170単一ショットの `query()` がエラー結果で終了した場合（例えば、ターン制限エラー）、SDK は [`ResultError`](#resulterror) を発生させます。

2170 2171 

2171<h3 id="clinotfounderror">2172<h3 id="clinotfounderror">

2172 `CLINotFoundError`2173 `CLINotFoundError`

2216 `ResultError`2217 `ResultError`

2217</h3>2218</h3>

2218 2219 

2219Claude Code プロセスが実行を終了し、ターン制限エラーや API エラーなどのエラー結果で実行が終了した場合、最終的な [`ResultMessage`](#resultmessage) の後に発生します。`ResultError` は `ProcessError` のサブクラスであるため、既存の `except ProcessError` ハンドラーもこれをキャッチします。その属性は結果メッセージのフィールドを保持しているため、メッセージテキストを解析することなく、実行が失敗した理由に基づいて分岐できます。Python Agent SDK 0.2.140 以降が必要です。2220ターン制限エラーや API エラーなど、実行がエラーの[結果メッセージ](#resultmessage)で終了したために Claude Code プロセスが終了した場合に発生します。`ResultError` は `ProcessError` のサブクラスであるため、既存の `except ProcessError` ハンドラーもこれをキャッチします。その属性はその結果メッセージのフィールドを保持しているため、メッセージテキストを解析することなく、実行が失敗した理由に基づいて分岐できます。Python Agent SDK 0.2.140 以降が必要です。

2220 2221 

2221```python theme={null}2222```python theme={null}

2222class ResultError(ProcessError):2223class ResultError(ProcessError):

2649 hookEventName: Literal["PostToolUse"]2650 hookEventName: Literal["PostToolUse"]

2650 additionalContext: NotRequired[str]2651 additionalContext: NotRequired[str]

2651 updatedToolOutput: NotRequired[Any]2652 updatedToolOutput: NotRequired[Any]

2652 updatedMCPToolOutput: NotRequired[Any] # Deprecated: use updatedToolOutput, which works for all tools2653 updatedMCPToolOutput: NotRequired[Any] # MCP tools only. Prefer updatedToolOutput, which works for all tools

2653 2654 

2654 2655 

2655class PostToolUseFailureHookSpecificOutput(TypedDict):2656class PostToolUseFailureHookSpecificOutput(TypedDict):

2767 ツール入出力型2768 ツール入出力型

2768</h2>2769</h2>

2769 2770 

2770すべての組み込み Claude Code ツールの入出力スキーマのドキュメント。Python SDK はこれらを型としてエクスポートしませんが、メッセージ内のツール入出力の構造を表します。2771組み込み Claude Code ツールの入出力スキーマのドキュメント。Python SDK はこれらを型としてエクスポートしませんが、メッセージ内のツール入出力の構造を表します。

2771 2772 

2772各出力は、そのツールの [`UserMessage.tool_use_result`](#usermessage) から読み込む値です。キー名は Claude Code が発行する通りに表示されます。「存在する場合」または「オプション」というコメント付きで `| None` と注釈が付けられたキーは、適用されない場合は省略されます。2773各出力は、そのツールの [`UserMessage.tool_use_result`](#usermessage) から読み込む値です。キー名は Claude Code が発行する通りに表示されます。「存在する場合」または「オプション」というコメント付きで `| None` と注釈が付けられたキーは、適用されない場合は省略されます。

2773 2774 

60 60 

61構造化された出力を使用するには、必要なデータの形状を説明する [JSON Schema](https://json-schema.org/understanding-json-schema/about) を定義し、`outputFormat` オプション（TypeScript）または `output_format` オプション（Python）を使用して `query()` に渡します。エージェントが完了すると、結果メッセージにはスキーマに一致する検証済みデータを含む `structured_output` フィールドが含まれます。61構造化された出力を使用するには、必要なデータの形状を説明する [JSON Schema](https://json-schema.org/understanding-json-schema/about) を定義し、`outputFormat` オプション（TypeScript）または `output_format` オプション（Python）を使用して `query()` に渡します。エージェントが完了すると、結果メッセージにはスキーマに一致する検証済みデータを含む `structured_output` フィールドが含まれます。

62 62 

63以下の例は、エージェントに Anthropic を調査し、会社名、設立年、本社を構造化された出力として返すよう求めています。63このページの例を実行する前に、[クイックスタート](/docs/ja/agent-sdk/quickstart#setup)に従って Claude Agent SDK をインストールしてください。以下の例は、エージェントに Anthropic を調査し、会社名、設立年、本社を構造化された出力として返すよう求めています。

64 64 

65<CodeGroup>65<CodeGroup>

66 ```typescript TypeScript theme={null}66 ```typescript TypeScript theme={null}

388 エラーハンドリング388 エラーハンドリング

389</h2>389</h2>

390 390 

391構造化された出力の生成は、エージェントがスキーマに一致する有効な JSON を生成できない場合に失敗する可能性があります。これは通常、スキーマがタスクに対して複雑すぎる場合、タスク自体が曖昧な場合、またはエージェントが検証エラーを修正しようとして再試行制限に達した場合に発生します。また、検証の失敗がなくても発生する可能性があります。[モデルフォールバック](/docs/ja/model-config#automatic-model-fallback)は既に完了した出力をストリーム中に取り消すことができ、再試行がそれを置き換えない場合、実行は同じエラーで終了します。デバッグの前に、結果メッセージの `errors` リストをチェックして、2 つの原因を区別してください。391構造化された出力の生成は、エージェントがスキーマに一致する有効な JSON を生成できない場合に失敗する可能性があります。これは通常、スキーマがタスクに対して複雑すぎる場合、タスク自体が曖昧な場合、またはエージェントが検証エラーを修正しようとして再試行制限に達した場合に発生します。また、検証の失敗がなくても発生する可能性があります。[モデルフォールバック](/docs/ja/model-config#automatic-model-fallback)は既に完了した出力をストリーム中に取り消すことができ、再試行がそれを置き換えない場合、実行は同じエラーで終了します。スキーマをデバッグする前に、エラー結果メッセージの `errors` リストを確認して、2 つの原因を区別してください。

392 392 

393エラーが発生すると、結果メッセージには何が問題かを示す `subtype` があります：393エラーが発生すると、結果メッセージには何が問題かを示す `subtype` があります：

394 394 

395| Subtype | 意味 |395| Subtype | 意味 |

396| - | - |396| - | - |

397| `success` | 出力が正常に生成および検証されました |397| `success` | 出力が正常に生成および検証されました |

398| `error_max_structured_output_retries` | 複数の試行後に有効な出力が生き残りませんでした（検証の失敗、またはモデルフォールバックの取り消しで再試行がない場合） |398| `error_max_structured_output_retries` | 複数の試行後に有効な出力が残りませんでした（検証の失敗、または成功した再試行のないモデルフォールバックによる取り消し） |

399 399 

400結果は `subtype` が `success` でも `structured_output` 値がない場合に終了することもあります。例えば、実行がエージェントによる構造化出力の生成なしに完了した場合です。その場合も失敗として扱ってください。トラブルシューティングエントリ [structured\_output is None but the result says success](/docs/ja/agent-sdk/troubleshooting#structured_output-is-none-but-the-result-says-success) がこのケースをカバーしています。以下の例は、`subtype` が `success` で `structured_output` が存在する場合にのみ結果を成功として扱い、他のすべての結果を失敗として処理します：400結果は `subtype` が `success` でも `structured_output` 値がない場合に終了することもあります。例えば、実行がエージェントによる構造化出力の生成なしに完了した場合です。その場合も失敗として扱ってください。トラブルシューティングエントリ [structured\_output is None but the result says success](/docs/ja/agent-sdk/troubleshooting#structured_output-is-none-but-the-result-says-success) がこのケースをカバーしています。以下の例は、`subtype` が `success` で `structured_output` が存在する場合にのみ結果を成功として扱い、他のすべての結果を失敗として処理します：

401 401 

6 6 

7> TypeScript Agent SDK の完全な API リファレンス。すべての関数、型、インターフェースを含みます。7> TypeScript Agent SDK の完全な API リファレンス。すべての関数、型、インターフェースを含みます。

8 8 

9<script src="/docs/components/typescript-sdk-type-links.js" defer />

10 

11<h2 id="installation">9<h2 id="installation">

12 インストール10 インストール

13</h2>11</h2>

186 console.error("Claim failed:", error.message);184 console.error("Claim failed:", error.message);

187});185});

188 186 

189for await (const message of claimedQuery) {187try {

188 for await (const message of claimedQuery) {

190 console.log(message);189 console.log(message);

190 }

191} catch (error) {

192 // クレームが拒否された場合、クレームされたクエリはエラー結果を生成した後にスローします

193 console.error(`Session ended with an error: ${error}`);

191}194}

192```195```

193 196 

539| プロパティ | 型 | デフォルト | 説明 |542| プロパティ | 型 | デフォルト | 説明 |

540| :- | :- | :- | :- |543| :- | :- | :- | :- |

541| `abortController` | `AbortController` | `new AbortController()` | 操作をキャンセルするためのコントローラー |544| `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) |545| `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` オプションまたは設定で定義されている必要があります |546| `agent` | `string` | `undefined` | メインスレッドのエージェント名。エージェントは `agents` オプションまたは設定で定義されている必要があります |

544| `agents` | `Record<string, [`AgentDefinition`](#agentdefinition)>` | `undefined` | サブエージェントをプログラムで定義します |547| `agents` | `Record<string, [`AgentDefinition`](#agentdefinition)>` | `undefined` | サブエージェントをプログラムで定義します |

545| `agentProgressSummaries` | `boolean` | `false` | `true` の場合、サブエージェントの 1 行の進捗サマリーを生成し、`summary` フィールドを介して [`task_progress`](#sdktaskprogressmessage) イベントで転送します。フォアグラウンドとバックグラウンドの両方のサブエージェントに適用されます |548| `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)を参照してください |549| `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)を参照してください |550| `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)`[]` | `[]` | ベータ機能を有効にします |551| `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) を参照してください |552| `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` | 最新の会話を続行します |553| `continue` | `boolean` | `false` | 最新の会話を続行します |

551| `cwd` | `string` | `process.cwd()` | 現在の作業ディレクトリ |554| `cwd` | `string` | `process.cwd()` | 現在の作業ディレクトリ |

552| `debug` | `boolean` | `false` | Claude Code プロセスのデバッグモードを有効にします |555| `debug` | `boolean` | `false` | Claude Code プロセスのデバッグモードを有効にします |

553| `debugFile` | `string` | `undefined` | デバッグログを特定のファイルパスに書き込みます。暗黙的にデバッグモードを有効にします |556| `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)を参照してください |557| `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)を参照してください |558| `effort` | `'low' \| 'medium' \| 'high' \| 'xhigh' \| 'max'` | `undefined` | Claude が応答にかける effort の量を制御します。adaptive thinking と連携して思考の深さを導きます。[effort レベルを調整する](/docs/ja/model-config#adjust-effort-level)を参照してください |

556| `enableFileCheckpointing` | `boolean` | `false` | 巻き戻しのためのファイル変更追跡を有効にします。[ファイルチェックポイント機能](/docs/ja/agent-sdk/file-checkpointing)を参照してください |559| `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` を設定します |560| `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 ランタイム |561| `executable` | `'bun' \| 'deno' \| 'node'` | 自動検出 | 使用する JavaScript ランタイム |

559| `executableArgs` | `string[]` | `[]` | 実行ファイルに渡す引数 |562| `executableArgs` | `string[]` | `[]` | 実行ファイルに渡す引数 |

560| `extraArgs` | `Record<string, string \| null>` | `{}` | 追加の引数 |563| `extraArgs` | `Record<string, string \| null>` | `{}` | 追加の引数 |

561| `fallbackModel` | `string` | `undefined` | プライマリモデルが失敗した場合に使用するモデル。カンマ区切りのリストを受け付けます。順序と上限については[フォールバックモデルチェーン](/docs/ja/model-config#fallback-model-chains)を参照してください。ガイダンスについては[モデルを選択する](/docs/ja/agent-sdk/configuration#choose-a-model)を参照してください |564| `fallbackModel` | `string` | `undefined` | プライマリモデルが失敗した場合に使用するモデル。カンマ区切りのリストを受け付けます。順序と上限については[フォールバックモデルチェーン](/docs/ja/model-config#fallback-model-chains)を、ガイダンスについては[モデルを選択する](/docs/ja/agent-sdk/configuration#choose-a-model)を参照してください |

562| `forkSession` | `boolean` | `false` | `resume` で再開する際に、元のセッションを続行するのではなく新しいセッション ID にフォークします |565| `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 以降が必要です |566| `forwardSubagentText` | `boolean` | `false` | `parent_tool_use_id` が設定されたアシスタントメッセージおよびユーザーメッセージとして、サブエージェントのテキストと思考ブロックを転送し、コンシューマーがネストされたトランスクリプトをレンダリングできるようにします。このオプションがない場合、Claude Code は[フォアグラウンド](/docs/ja/sub-agents#run-subagents-in-foreground-or-background)で実行されるサブエージェントのテキストと思考ブロックを省略します。ネストされたサブエージェント、`context: fork` を持つスキル、およびそれぞれに必要な Claude Code のバージョンについては、[サブエージェントのメッセージを追跡する](/docs/ja/headless#follow-subagent-messages)を参照してください |

564| `hooks` | `Partial<Record<`[`HookEvent`](#hookevent)`, `[`HookCallbackMatcher`](#hookcallbackmatcher)`[]>>` | `{}` | イベントのフックコールバック |567| `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)フックが終了した場合にのみ出力します |568| `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` | 部分メッセージイベントを含めます |569| `includePartialMessages` | `boolean` | `false` | 部分メッセージイベントを含めます |

567| `loadTimeoutMs` | `number` | `60000` | *アルファ版。* 再開時のマテリアライズ中の各 `sessionStore.load()` および `sessionStore.listSubkeys()` 呼び出しのタイムアウト（ミリ秒）。アダプターがこの時間内に完了しない場合、クエリはハングせずに失敗します。`sessionStore` が設定されていない場合は無視されます |570| `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 エントリです |571| `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)を参照してください |572| `maxBudgetUsd` | `number` | `undefined` | クライアント側のコスト見積もりがこの USD 値に達したときにクエリを停止します。この呼び出し自体の支出のみをカウントし、再開したセッションから復元された合計はカウントされません。精度に関する注意事項とリセット動作については、[コストと使用量を追跡する](/docs/ja/agent-sdk/cost-tracking)を参照してください |

570| `maxThinkingTokens` | `number` | `undefined` | *非推奨:* 代わりに `thinking` を使用してください。思考プロセスの最大トークン数 |573| `maxThinkingTokens` | `number` | `undefined` | *非推奨:* 代わりに `thinking` を使用してください。思考プロセスの最大トークン数 |

571| `maxTurns` | `number` | `undefined` | エージェントの最大ターン数（ツール使用の往復） |574| `maxTurns` | `number` | `undefined` | エージェントの最大ターン数（ツール使用のラウンドトリップ） |

572| `mcpServers` | `Record<string, [`McpServerConfig`](#mcpserverconfig)>` | `{}` | MCP サーバーの設定 |575| `mcpServers` | `Record<string, [`McpServerConfig`](#mcpserverconfig)>` | `{}` | MCP サーバーの設定 |

573| `model` | `string` | CLI のデフォルト | Claude のモデルエイリアスまたは完全なモデル名。[使用可能な値とプロバイダー固有の ID](/docs/ja/model-config#available-models) を参照してください |576| `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 リクエストは自動的に拒否されます |577| `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)を参照してください |578| `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)を参照してください |579| `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 実行ファイルへのパス。インストール時にオプションの依存関係がスキップされた場合、またはプラットフォームがサポート対象に含まれていない場合にのみ必要です |580| `pathToClaudeCodeExecutable` | `string` | バンドルされたネイティブバイナリから自動解決 | Claude Code 実行ファイルへのパス。インストール時にオプションの依存関係がスキップされた場合、またはプラットフォームがサポート対象に含まれていない場合にのみ必要です |

578| `permissionMode` | [`PermissionMode`](#permissionmode) | `undefined` | セッションの権限モード。省略した場合、セッションは auto モードで開始される可能性があります。Claude Code が開始時の権限モードをどのように選択するかについては[権限モード](/docs/ja/agent-sdk/permissions#permission-modes)を参照してください |581| `permissionMode` | [`PermissionMode`](#permissionmode) | `undefined` | セッションの権限モード。省略した場合、セッションは auto モードで開始される可能性があります。Claude Code が開始時の権限モードをどのように選択するかについては[権限モード](/docs/ja/agent-sdk/permissions#permission-modes)を参照してください |

579| `permissionPromptToolName` | `string` | `undefined` | 権限プロンプト用の MCP ツール名 |582| `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 以降が必要です |583| `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` の場合、ディスクへのセッションの永続化を無効にします。セッションは後で再開できません |584| `persistSession` | `boolean` | `true` | `false` の場合、ディスクへのセッションの永続化を無効にします。セッションを後で再開することはできません |

582| `planModeInstructions` | `string` | `undefined` | plan モード用のカスタムワークフロー指示。`permissionMode` が `'plan'` の場合、この文字列がデフォルトの plan モードのワークフロー本文を置き換えます。CLI は引き続き、読み取り専用を強制するプリアンブルと ExitPlanMode プロトコルのフッターでこれをラップします |585| `planModeInstructions` | `string` | `undefined` | plan モードのカスタムワークフロー指示。`permissionMode` が `'plan'` の場合、この文字列がデフォルトの plan モードのワークフロー本文を置き換えます。CLI は引き続き、読み取り専用を強制する前文と ExitPlanMode プロトコルのフッターでこれをラップします |

583| `plugins` | [`SdkPluginConfig`](#sdkpluginconfig)`[]` | `[]` | ローカルパスからカスタムプラグインを読み込みます。詳細は[プラグイン](/docs/ja/agent-sdk/plugins)を参照してください |586| `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 以降が必要です |587| `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)を参照してください |588| `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 |589| `resume` | `string` | `undefined` | 再開するセッション ID |

587| `resumeDropsTurn` | `string` | `undefined` | `resumeSessionAt` と併用します。切り詰めを伴う再開で破棄しようとするターンのプロンプト UUID です。破棄される範囲に、取り込まれたキュー内のメッセージやタスク通知など、そのターンに帰属しないものが含まれている場合、Claude Code は再開を拒否し、拒否メッセージで `--resume-drops-turn` フラグを示します。このペアを読み取るのは Agent SDK と print モードの再開のみです。Claude Code v2.1.223 以降が必要です |590| `resumeDropsTurn` | `string` | `undefined` | `resumeSessionAt` と併用します。切り詰めを伴う再開で破棄する予定のターンのプロンプト UUID です。破棄される範囲に、取り込まれたキュー内のメッセージやタスク通知など、そのターンに帰属しないものが含まれている場合、Claude Code は再開を拒否し、拒否メッセージで `--resume-drops-turn` フラグを示します。このペアを読み取るのは Agent SDK と print モードの再開のみです。Claude Code v2.1.223 以降が必要です |

588| `resumeSessionAt` | `string` | `undefined` | 特定のメッセージ UUID の時点でセッションを再開します |591| `resumeSessionAt` | `string` | `undefined` | 特定のメッセージ UUID の時点でセッションを再開します |

589| `sandbox` | [`SandboxSettings`](#sandboxsettings) | `undefined` | サンドボックスの動作をプログラムで設定します。詳細は[サンドボックス設定](#sandboxsettings)を参照してください |592| `sandbox` | [`SandboxSettings`](#sandboxsettings) | `undefined` | サンドボックスの動作をプログラムで設定します。詳細は[サンドボックス設定](#sandboxsettings)を参照してください |

590| `sessionId` | `string` | 自動生成 | 自動生成する代わりに、セッションに特定の UUID を使用します |593| `sessionId` | `string` | 自動生成 | 自動生成する代わりに、セッションに特定の UUID を使用します |

591| `sessionStore` | [`SessionStore`](/docs/ja/agent-sdk/session-storage#the-sessionstore-interface) | `undefined` | 別のホストが再開できるように、セッションのトランスクリプトを外部バックエンドにミラーリングします。[外部ストレージにセッションを永続化する](/docs/ja/agent-sdk/session-storage)を参照してください |594| `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` が設定されていない場合は無視されます |595| `sessionStoreFlush` | `'batched' \| 'eager'` | `'batched'` | *アルファ版。* `sessionStore` のフラッシュモード。`sessionStore` が設定されていない場合は無視されます |

593| `settings` | `string \| Settings` | `undefined` | インラインの[設定](/docs/ja/settings)オブジェクト、設定ファイルのパス、またはインライン JSON 文字列。[優先順位](/docs/ja/settings#settings-precedence)におけるフラグ設定レイヤーに値を設定します。実行時に [`applyFlagSettings()`](#applyflagsettings) で変更できます |596| `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)を参照してください |597| `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)を参照してください |598| `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 を実行する場合に使用します |599| `spawnClaudeCodeProcess` | `(options: SpawnOptions) => SpawnedProcess` | `undefined` | Claude Code プロセスを生成するカスタム関数。VM、コンテナ、リモート環境で Claude Code を実行する場合に使用します |

597| `stderr` | `(data: string) => void` | `undefined` | stderr 出力のコールバック |600| `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)を無視します |601| `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 以降が必要です |602| `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 側のタスク予算。設定すると、モデルに残りのトークン予算が伝えられ、モデルはツールの使用ペースを調整して上限に達する前に作業をまとめられるようになります |603| `taskBudget` | `{ total: number }` | `undefined` | *アルファ版。* API 側のタスク予算（トークン単位）。設定すると、モデルに残りのトークン予算が伝えられ、モデルはツールの使用ペースを調整して上限に達する前に作業をまとめられるようになります |

601| `thinking` | [`ThinkingConfig`](#thinkingconfig) | サポートされているモデルでは `{ type: 'adaptive' }` | Claude の思考/推論の動作を制御します。オプションについては [`ThinkingConfig`](#thinkingconfig) を参照してください |604| `thinking` | [`ThinkingConfig`](#thinkingconfig) | サポートされているモデルでは `{ type: 'adaptive' }` | Claude の思考/推論の動作を制御します。オプションについては [`ThinkingConfig`](#thinkingconfig) を参照してください |

602| `title` | `string` | `undefined` | セッションの表示タイトル。`resume` または `continue` で再開する場合は、再開されたセッションに保存されているタイトルが優先されます。既存のセッションのタイトルを変更するには [`renameSession()`](#renamesession) を使用します |605| `title` | `string` | `undefined` | セッションの表示タイトル。`resume` または `continue` で再開する場合は、再開されたセッションに永続化されたタイトルが優先されます。既存のセッションのタイトルを変更するには [`renameSession()`](#renamesession) を使用します |

603| `toolAliases` | `Record<string, string>` | `undefined` | 組み込みツール名を MCP ツール名にマッピングし、Claude が組み込みツールの代わりに MCP 実装を呼び出すようにします。例: `{ Bash: 'mcp__workspace__bash' }` |606| `toolAliases` | `Record<string, string>` | `undefined` | 組み込みツール名を MCP ツール名にマッピングし、Claude が組み込みツールの代わりに MCP 実装を呼び出すようにします。例: `{ Bash: 'mcp__workspace__bash' }` |

604| `toolConfig` | [`ToolConfig`](#toolconfig) | `undefined` | 組み込みツールの動作の設定。詳細は [`ToolConfig`](#toolconfig) を参照してください |607| `toolConfig` | [`ToolConfig`](#toolconfig) | `undefined` | 組み込みツールの動作の設定。詳細は [`ToolConfig`](#toolconfig) を参照してください |

605| `tools` | `string[] \| { type: 'preset'; preset: 'claude_code' }` | `undefined` | ツールの設定。ツール名の配列を渡すか、プリセットを使用して Claude Code のデフォルトツールを取得します |608| `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 の要件を満たしています |609| `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 610 

608<h4 id="handle-slow-or-stalled-api-responses">611<h4 id="handle-slow-or-stalled-api-responses">

609 遅い API レスポンスや停止した API レスポンスに対処する612 遅いまたは停止した API レスポンスを処理する

610</h4>613</h4>

611 614 

612CLI サブプロセスは、API のタイムアウトと停止検出を制御するいくつかの環境変数を読み取ります。これらは `env` オプションを通じて渡します。615CLI サブプロセスは、API のタイムアウトと停止検出を制御するいくつかの環境変数を読み取ります。これらは `env` オプションで渡します:

613 616 

614```typescript theme={null}617```typescript theme={null}

615import { query } from "@anthropic-ai/claude-agent-sdk";618import { query } from "@anthropic-ai/claude-agent-sdk";

628```631```

629 632 

630* `API_TIMEOUT_MS`: Anthropic クライアントのリクエストごとのタイムアウト（ミリ秒）。デフォルトは `600000` です。メインループとすべてのサブエージェントに適用されます。633* `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` に引き上げられ、この変数の上限が撤廃されます。634* `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` でした。635* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`: サブエージェントの停止ウォッチドッグ。ストリームウォッチドッグがオンの間、デフォルトは `CLAUDE_STREAM_IDLE_TIMEOUT_MS` に 5 分を加えた値で、その変数を引き上げない限り `600000` になります。ストリームウォッチドッグがオフの場合、デフォルトは `600000` です。v2.1.257 より前は、デフォルトは常に `600000` でした。

633 636 

634 タイマーはストリームイベントのたびにリセットされます。停止が発生すると、Claude Code はサブエージェントを中止し、停止を親に報告します。バックグラウンドのサブエージェントの場合は、さらにタスクを失敗としてマークし、部分的な結果があれば添付します。637 タイマーはストリームイベントごとにリセットされます。停止すると、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)で説明しています。638* `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 639 

637 `ANTHROPIC_BASE_URL` の背後にあるゲートウェイがキープアライブ ping でレスポンスを開いたままにしている間、ウォッチドッグはそのレスポンスを待ち続けます。その間も `includePartialMessages` を設定しているホストは `ping` [ストリームイベント](#sdkpartialassistantmessage)を受信し続けるため、無通信を理由にセッションをタイムアウトさせるのではなく、これらのフレームを生存確認として扱ってください。v2.1.257 より前は、最後の実際のストリームイベントから 5 分後にフレームが停止していました。640 `ANTHROPIC_BASE_URL` の背後にあるゲートウェイがキープアライブ ping で開いたままにしているレスポンスをウォッチドッグが待機している間、`includePartialMessages` を設定したホストは `ping` [ストリームイベント](#sdkpartialassistantmessage)を受信し続けます。そのため、無音を理由にセッションをタイムアウトさせるのではなく、これらのフレームを生存確認として扱ってください。v2.1.257 より前は、最後の実際のストリームイベントから 5 分後にフレームが停止していました。

638 641 

639<h3 id="query-object">642<h3 id="query-object">

640 `Query` オブジェクト643 `Query` オブジェクト

696 699 

697| メソッド | 説明 |700| メソッド | 説明 |

698| :- | :- |701| :- | :- |

699| `interrupt()` | クエリを中断します。ストリーミング入力モードでのみ使用できます。CLI が [`SDKSystemMessage.capabilities`](#sdksystemmessage) で `interrupt_receipt_v1` ケイパビリティを通知している場合、中断が到着した時点で保留中だったメッセージを一覧にした [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse) で解決されます。v2.1.205 より前の CLI では `undefined` で解決されます |702| `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)を参照してください |703| `rewindFiles(userMessageId, options?)` | ファイルを指定したユーザーメッセージの時点の状態に復元します。変更をプレビューするには `{ dryRun: true }` を渡します。`enableFileCheckpointing: true` が必要です。[ファイルのチェックポイント機能](/docs/ja/agent-sdk/file-checkpointing)を参照してください |

701| `setPermissionMode()` | 権限モードを変更します（ストリーミング入力モードでのみ使用可能） |704| `setPermissionMode()` | 権限モードを変更します（ストリーミング入力モードでのみ利用可能） |

702| `setModel()` | モデルを変更します（ストリーミング入力モードでのみ使用可能）。`undefined` または文字列 `"default"` を渡すと、[Claude Code のデフォルトモデル](/docs/ja/model-config)にリセットされます |705| `setModel()` | モデルを変更します（ストリーミング入力モードでのみ利用可能）。`undefined` または文字列 `"default"` を渡すと、[Claude Code のデフォルトモデル](/docs/ja/model-config)にリセットされます |

703| `setMaxThinkingTokens()` | *非推奨:* 代わりに `thinking` オプションを使用してください。最大思考トークン数を変更します。`null` を渡すと思考がセッションのデフォルトにリセットされます。セッション途中の上書きはクリアされ、思考が無効になっているセッションでは思考は無効のままです |706| `setMaxThinkingTokens()` | *非推奨:* 代わりに `thinking` オプションを使用してください。最大思考トークン数を変更します。`null` を渡すと思考がセッションのデフォルトにリセットされます。セッション中の上書きはクリアされ、思考が無効になっているセッションでは思考はオフのままになります |

704| `applyFlagSettings(settings)` | 実行時にセッションのフラグ設定レイヤーに設定をマージします（ストリーミング入力モードでのみ使用可能）。[`applyFlagSettings()`](#applyflagsettings) を参照してください |707| `applyFlagSettings(settings)` | 実行時にセッションのフラグ設定レイヤーに設定をマージします（ストリーミング入力モードでのみ利用可能）。[`applyFlagSettings()`](#applyflagsettings) を参照してください |

705| `updateSettings(source, settings)` | 許可リストに含まれる 1 つのキーをプロジェクトのローカル設定ファイルまたはユーザー設定ファイルに書き込み、その値を以降のセッションにも保持します。[`updateSettings()`](#updatesettings) を参照してください。TypeScript SDK v0.3.257 以降が必要です（Claude Code v2.1.257 がバンドルされています） |708| `updateSettings(source, settings)` | 許可リストに含まれる 1 つのキーをプロジェクトのローカル設定ファイルまたはユーザー設定ファイルに書き込み、その値が以降のセッションでも保持されるようにします。[`updateSettings()`](#updatesettings) を参照してください。TypeScript SDK v0.3.257 以降（Claude Code v2.1.257 をバンドル）が必要です |

706| `initializationResult()` | サポートされているコマンド、モデル、アカウント情報、出力スタイルの設定を含む完全な初期化結果を返します |709| `initializationResult()` | サポートされているコマンド、モデル、アカウント情報、出力スタイルの設定を含む完全な初期化結果を返します |

707| `reinitialize()` | 実行中の CLI に `initialize` コントロールリクエストを再送信し、キャッシュされた初回接続時の結果ではなく新しい結果を返します。切断後にセッションに再接続する場合など、トランスポートの途絶後に使用すると、保留中の権限リクエストが再び `canUseTool` コールバックに届きます。レスポンスが失われたリクエストは再度ディスパッチされるため、コールバックはリクエスト ID ごとに冪等にしてください。Claude Code v2.1.195 以降が必要です |710| `reinitialize()` | 実行中の CLI に `initialize` 制御リクエストを再送信し、キャッシュされた初回接続時の結果ではなく新しい結果を返します。切断後にセッションに再アタッチする場合など、トランスポートが途切れた後に使用すると、保留中の権限リクエストが再び `canUseTool` コールバックに届きます。レスポンスが失われたリクエストは再度ディスパッチされるため、コールバックはリクエスト ID ごとに冪等にしてください。Claude Code v2.1.195 以降が必要です |

708| `supportedCommands()` | 使用可能なコマンドを返します。Agent SDK v0.3.216 以降、このリストにはセッション途中のコマンドの変更が反映されます。[`SDKCommandsChangedMessage`](#sdkcommandschangedmessage) を参照してください |711| `supportedCommands()` | 利用可能なコマンドを返します。Agent SDK v0.3.216 以降では、リストにセッション中のコマンドの変更が反映されます。[`SDKCommandsChangedMessage`](#sdkcommandschangedmessage) を参照してください |

709| `supportedModels()` | 表示情報付きで使用可能なモデルを返します |712| `supportedModels()` | 利用可能なモデルを表示情報付きで返します |

710| `supportedAgents()` | 使用可能なサブエージェントを [`AgentInfo`](#agentinfo)`[]` として返します |713| `supportedAgents()` | 利用可能なサブエージェントを [`AgentInfo`](#agentinfo)`[]` として返します |

711| `mcpServerStatus()` | 接続されている MCP サーバーのステータスを [`McpServerStatus`](#mcpserverstatus)`[]` として返します |714| `mcpServerStatus()` | 接続されている MCP サーバーのステータスを [`McpServerStatus`](#mcpserverstatus)`[]` として返します |

712| `getContextUsage(opts?)` | セッションのコンテキストウィンドウの使用量をカテゴリ、スキル、ツールごとに分類した [`SDKControlGetContextUsageResponse`](#sdkcontrolgetcontextusageresponse) を返します。デフォルトの `detail` では、インタラクティブセッションで `/context` が表示するものと同じデータで、メッセージストリームに現れないトークンカウント API リクエストを使って計算されます。[これらのリクエストの扱い](#sdkcontrolgetcontextusageresponse)を参照してください。[`detail` オプション](#sdkcontrolgetcontextusageresponse)には Agent SDK v0.3.257 以降が必要です |715| `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 以降が必要です |716| `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 以降が必要です |

714| `reloadPlugins(options?)` | ディスクからプラグインを再読み込みし、セッション途中にインストールまたは編集したプラグインを実行中のセッションに反映させます。セッションのコマンド、サブエージェント、プラグイン、MCP サーバーのステータスを一覧にした [`SDKControlReloadPluginsResponse`](#sdkcontrolreloadpluginsresponse) で解決されます。Agent SDK v0.2.85 以降が必要です。[`holdOnCacheImpact` オプション](#sdkcontrolreloadpluginsresponse)には Agent SDK v0.3.268 以降が必要です |717| `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 以降が必要です |718| `reloadSkills()` | ディスクからスキルを再読み込みし、セッション中に追加または編集したスキルを実行中のセッションで利用できるようにします。再読み込み後に利用可能なスキルを列挙した [`SDKControlReloadSkillsResponse`](#sdkcontrolreloadskillsresponse) で解決されます。Agent SDK v0.3.163 以降が必要です |

716| `reloadOutputStyles()` | ディスクから[出力スタイル](/docs/ja/output-styles)を再読み込みし、セッション途中に追加または編集したスタイルファイルを実行中のセッションで使用できるようにします。再読み込み後に使用可能なスタイル名を一覧にした [`SDKControlReloadOutputStylesResponse`](#sdkcontrolreloadoutputstylesresponse) で解決されます。Agent SDK v0.3.261 以降が必要です |719| `reloadOutputStyles()` | ディスクから[出力スタイル](/docs/ja/output-styles)を再読み込みし、セッション中に追加または編集したスタイルファイルを実行中のセッションで利用できるようにします。再読み込み後に利用可能なスタイル名を列挙した [`SDKControlReloadOutputStylesResponse`](#sdkcontrolreloadoutputstylesresponse) で解決されます。Agent SDK v0.3.261 以降が必要です |

717| `accountInfo()` | アカウント情報を返します |720| `accountInfo()` | アカウント情報を返します |

718| `reconnectMcpServer(serverName)` | 名前を指定して MCP サーバーに再接続します。その名前が `.mcp.json` や `~/.claude.json` などの設定ファイル内のエントリにも一致する場合、Claude Code は設定ファイルのエントリではなく、[`mcpServers`](#options) または `setMcpServers()` で設定したサーバーに再接続します。この解決順序には Claude Code v2.1.257 以降が必要です |721| `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) を参照してください |722| `toggleMcpServer(serverName, enabled)` | `reconnectMcpServer()` と同じ名前解決で、名前を指定して MCP サーバーを有効または無効にします。サーバーを無効にすると切断され、そのツールが削除されます。サーバーの種類ごとに必要な Claude Code のバージョンについては [`toggleMcpServer()`](#togglemcpserver) を参照してください |

720| `setMcpServers(servers)` | このセッションの MCP サーバーのセットを動的に置き換えます。追加および削除されたサーバーとエラーを示す [`McpSetServersResult`](#mcpsetserversresult) で解決されます |723| `setMcpServers(servers)` | このメソッドが管理する MCP サーバー（このメソッドで追加したサーバーと[インプロセス SDK サーバー](#createsdkmcpserver)）を置き換えます。追加および削除されたサーバーとエラーを示す [`McpSetServersResult`](#mcpsetserversresult) で解決されます。他のどのサーバーが接続されたままになるかはそのセクションで説明しています |

721| `readMcpResource(serverName, uri)` | *アルファ版。* アプリケーションがツールのウィジェットをレンダリングできるように、接続されている MCP サーバーから MCP Apps の `ui://` リソースを 1 つ読み取ります。[`SDKControlMcpReadResourceResponse`](#sdkcontrolmcpreadresourceresponse) で解決されます。TypeScript Agent SDK v0.3.280 以降が必要です |724| `readMcpResource(serverName, uri)` | *アルファ版。* 接続された MCP サーバーから MCP Apps の `ui://` リソースを 1 つ読み取り、アプリケーションがツールのウィジェットをレンダリングできるようにします。[`SDKControlMcpReadResourceResponse`](#sdkcontrolmcpreadresourceresponse) で解決されます。TypeScript Agent SDK v0.3.280 以降が必要です |

722| `streamInput(stream)` | マルチターンの会話のために、入力メッセージをクエリにストリーミングします |725| `streamInput(stream)` | マルチターンの会話のために、入力メッセージをクエリにストリーミングします |

723| `stopTask(taskId)` | 実行中のバックグラウンドタスクを ID で停止します |726| `stopTask(taskId)` | 実行中のバックグラウンドタスクを ID で停止します |

724| `close()` | クエリを閉じ、基盤となるプロセスを終了します。クエリを強制的に終了し、すべてのリソースをクリーンアップします |727| `close()` | クエリを閉じて基盤となるプロセスを終了します。クエリを強制的に終了し、すべてのリソースをクリーンアップします |

725 728 

726<h4 id="applyflagsettings">729<h4 id="applyflagsettings">

727 `applyFlagSettings()`730 `applyFlagSettings()`

728</h4>731</h4>

729 732 

730クエリを再起動せずに、実行中のセッションの[設定](/docs/ja/settings)を変更します。エージェントが信頼できない入力を読み取った後に `permissions` を厳しくする場合など、専用のセッターがない設定項目をセッション途中で変更する必要があるときに使用します。`setModel()` と `setPermissionMode()` はそれぞれのキー専用のセッターです。`applyFlagSettings()` は設定キーの任意のサブセットを受け付ける汎用的な形式で、ここで `model` を渡すと `setModel()` と同じように動作します。733クエリを再起動せずに、実行中のセッションの[設定](/docs/ja/settings)を変更します。エージェントが信頼できない入力を読み取った後に `permissions` を厳しくする場合など、専用のセッターがない設定をセッション中に変更する必要があるときに使用します。`setModel()` と `setPermissionMode()` はこれら 2 つのキー専用のセッターです。`applyFlagSettings()` は設定キーの任意のサブセットを受け付ける汎用の形式であり、ここで `model` を渡すと `setModel()` と同じ動作になります。

731 734 

732セッション途中で有効になるのは一部のキーのみです。735セッション中に有効になるのは一部のキーのみです:

733 736 

734* **次のターンで適用**: `effortLevel`、`ultracode`、`permissions`、`hooks`、`skillOverrides`、`fastMode`、`agent`。`agent` を切り替えると、そのエージェントのモデルの上書きとフックも次のターンで適用されます。そのシステムプロンプトは次のターンで適用されますが、[記録されたシステムプロンプトを再利用する](/docs/ja/agent-sdk/modifying-system-prompts#change-the-prompt-of-an-existing-session)セッションでは、セッションが圧縮された時点で適用されます。737* **次のターンで適用**: `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 より前は、ターン途中の切り替えは次のターンまで待機していました。738* **現在のターン中に適用**: `model`。Claude がターンの処理中に `model` を切り替えた場合、Claude がすでに生成中の応答は古いモデルで完了し、Claude Code が次にモデルを呼び出す時点からのターンの残りでは新しいモデルが使用されます。サブエージェントは独自のモデルを維持します。v2.1.212 より前は、ターン中の切り替えは次のターンまで待機していました。

736* **セッション途中では効果なし**: システムプロンプトのオプション。これらは起動時に 1 回だけ解決されるため、呼び出しが成功しても実行中のセッションは元の値を保持します。変更するには、新しいセッションを開始してください。739* **セッション中は効果なし**: システムプロンプトのオプション。これらは起動時に一度だけ解決されるため、呼び出しが成功しても、実行中のセッションは元の値を保持します。変更するには、新しいセッションを開始してください。

737 740 

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` に設定されていました。741`effortLevel` は [effort レベル](/docs/ja/model-config#adjust-effort-level)の名前を受け付けます。また `"ultracode"` も受け付け、これは [ultracode](/docs/ja/workflows#let-claude-decide-with-ultracode) をオンにした状態で `xhigh` effort を要求します。`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 742 

740値はフラグ設定レイヤーに書き込まれ、起動時に `query()` のインライン `settings` オプションで設定された内容の上にマージされます。これは[このページの優先順位セクション](#settings-precedence)でプログラムによるオプションと呼んでいるのと同じ層です。743値はフラグ設定レイヤーに書き込まれ、`query()` のインライン `settings` オプションが起動時に設定した内容の上にマージされます。これは、[このページの優先順位セクション](#settings-precedence)でプログラムによるオプションと呼ばれている階層と同じです。

741 744 

742連続した呼び出しでは、トップレベルのキーが浅くマージされます。`{ permissions: {...} }` を指定した 2 回目の呼び出しは、前回の呼び出しの `permissions` オブジェクトに深くマージされるのではなく、オブジェクト全体を置き換えます。745連続した呼び出しでは、トップレベルのキーがシャローマージされます。`{ permissions: {...} }` を指定した 2 回目の呼び出しは、前の呼び出しの `permissions` オブジェクトにディープマージするのではなく、オブジェクト全体を置き換えます。

743 746 

744`applyFlagSettings()` で設定したキーをクリアするには、そのキーに `null` を渡します。ほとんどのキーはその後、まず起動時に `query()` の `settings` オプションで設定された値に、次に優先順位の低いソースにフォールバックします。クリアされた `model` は、設定ファイルで `model` が設定されている場合でも、[Claude Code のデフォルトモデル](/docs/ja/model-config)にリセットされます。`undefined` を渡しても、JSON シリアライズで削除されるため効果はありません。747`applyFlagSettings()` で設定したキーをクリアするには、そのキーに `null` を渡します。ほとんどのキーはその後、まず `query()` の `settings` オプションが起動時に設定した値にフォールバックし、次に優先順位の低いソースにフォールバックします。クリアされた `model` は、設定ファイルで `model` が設定されていても、[Claude Code のデフォルトモデル](/docs/ja/model-config)にリセットされます。`undefined` を渡しても、JSON シリアライズで削除されるため効果はありません。

745 748 

746`model` 以外に、フォールバックする代わりにセッションの状態をリセットするキーが 3 つあります。749`model` 以外に、フォールバックせずにセッションの状態をリセットするキーが 3 つあります:

747 750 

748* `effortLevel: null` は、`query()` の `effort` オプションや設定ファイルの `effortLevel` ではなく、セッションをモデルのデフォルトの effort レベルに戻します。751* `effortLevel: null` は、`query()` の `effort` オプションや設定ファイルの `effortLevel` ではなく、モデルのデフォルトの effort レベルにセッションを戻します。

749* `agent: null` は、`query()` の `agent` オプションや設定ファイルの `agent` を復元するのではなく、次のターンからエージェントなしでメインスレッドを実行します。クリアされたエージェントが独自のモデルを適用していた場合、セッションは起動時に解決されたモデルに戻ります。752* `agent: null` は、`query()` の `agent` オプションや設定ファイルの `agent` を復元するのではなく、次のターンからエージェントなしでメインスレッドを実行します。クリアされたエージェントが独自のモデルを適用していた場合、セッションは起動時に解決したモデルに戻ります。

750* `ultracode: null` は、設定ファイルの `ultracode` 値を復元するのではなく、`false` と同様に ultracode をオフにします。セッションは現在の effort レベルを維持するため、変更するには同じ呼び出しで `effortLevel` を渡してください。753* `ultracode: null` は、設定ファイルの `ultracode` 値を復元するのではなく、`false` と同様に ultracode をオフにします。セッションは現在の effort レベルを維持するため、変更するには同じ呼び出しで `effortLevel` を渡してください。

751 754 

752`setModel()` や `setPermissionMode()` と同じ制約で、ストリーミング入力モードでのみ使用できます。755`setModel()` や `setPermissionMode()` と同じ制約で、ストリーミング入力モードでのみ利用可能です。

753 756 

754以下の例では、セッション途中でアクティブなモデルを切り替え、その後上書きをクリアしてモデルを [Claude Code のデフォルトモデル](/docs/ja/model-config)にリセットします。757以下の例では、セッション中にアクティブなモデルを切り替え、その後上書きをクリアしてモデルを [Claude Code のデフォルトモデル](/docs/ja/model-config)にリセットします。

755 758 

756```typescript theme={null}759```typescript theme={null}

757import { query } from "@anthropic-ai/claude-agent-sdk";760import { query } from "@anthropic-ai/claude-agent-sdk";

766```769```

767 770 

768<Note>771<Note>

769 `applyFlagSettings()` は TypeScript のみで使用できます。Python SDK には同等のメソッドはありません。772 `applyFlagSettings()` は TypeScript 専用です。Python SDK には同等のメソッドはありません。

770</Note>773</Note>

771 774 

772<h4 id="updatesettings">775<h4 id="updatesettings">

773 `updateSettings()`776 `updateSettings()`

774</h4>777</h4>

775 778 

776許可リストに含まれる 1 つのキーをディスク上の設定ファイルに書き込み、そのソースを読み込む以降のセッションにも値を保持します。各ソースは文字列値を持つ 1 つのキーを受け付けます。779許可リストに含まれる 1 つのキーをディスク上の設定ファイルに書き込み、そのソースを読み込む以降のセッションでも値が保持されるようにします。各ソースは、文字列値を持つ 1 つのキーを受け付けます:

777 780 

778* **`"localSettings"`**: `outputStyle` を受け付け、プロジェクトのローカル設定ファイル `.claude/settings.local.json` にマージします。新しいスタイルはセッションの次のリクエストから有効になります。781* **`"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 がバンドルされています）。782* **`"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 をバンドル）が必要です。

780 783 

781リクエストにその他のキーが含まれている場合、セッションがリモートトランスポート上で実行されている場合、およびセッションの [`settingSources`](#options) が指定したソースを除外している場合、呼び出しは拒否されます。キーの削除はサポートされていません。784リクエストに他のキーが含まれている場合、セッションがリモートトランスポート上で実行されている場合、およびセッションの [`settingSources`](#options) が指定したソースを除外している場合、呼び出しは拒否されます。キーの削除はサポートされていません。

782 785 

783<h4 id="togglemcpserver">786<h4 id="togglemcpserver">

784 `toggleMcpServer()`787 `toggleMcpServer()`

785</h4>788</h4>

786 789 

787サーバーを無効にすると、接続が切断され、そのツールがセッションから削除されます。セッション途中で追加したサーバーとインプロセスサーバーについては、Claude Code のバージョンによって次のように異なります。790サーバーを無効にすると、そのサーバーは切断され、ツールがセッションから削除されます。セッション中に追加したサーバーとインプロセスサーバーについては、この動作は Claude Code のバージョンによって異なります:

788 791 

789* `setMcpServers()` でセッション途中に追加した stdio、SSE、または HTTP サーバー: ツールの削除には Claude Code v2.1.285 以降が必要です。792* セッション中に `setMcpServers()` で追加した stdio、SSE、HTTP サーバー: ツールの削除には Claude Code v2.1.285 以降が必要です。

790* [`createSdkMcpServer()`](#createsdkmcpserver) で作成したインプロセスサーバー（`mcpServers` で渡したか `setMcpServers()` で渡したかを問わない）: 接続の切断とツールの削除には Claude Code v2.1.286 以降が必要です。また、無効にすると実行中のツール呼び出しも失敗するため、Claude はハンドラーが戻るのを待たずに、それぞれについてエラー結果を即座に受け取ります。793* [`createSdkMcpServer()`](#createsdkmcpserver) で作成したインプロセスサーバー（`mcpServers` で渡したか `setMcpServers()` で渡したかを問いません）: 切断とツールの削除には Claude Code v2.1.286 以降が必要です。無効にすると、まだ実行中のツール呼び出しも失敗するため、Claude はハンドラーが戻るのを待たずに、それぞれについて即座にエラー結果を受け取ります。

791 794 

792<h3 id="warmquery">795<h3 id="warmquery">

793 `WarmQuery`796 `WarmQuery`

794</h3>797</h3>

795 798 

796[`startup()`](#startup) が返すハンドルです。サブプロセスはすでに生成および初期化されているため、このハンドルで `query()` を呼び出すと、起動の遅延なしに準備済みのプロセスへプロンプトが直接書き込まれます。799[`startup()`](#startup) が返すハンドルです。サブプロセスはすでに生成・初期化されているため、このハンドルで `query()` を呼び出すと、起動の遅延なしに準備済みのプロセスへプロンプトが直接書き込まれます。

797 800 

798```typescript theme={null}801```typescript theme={null}

799interface WarmQuery extends AsyncDisposable {802interface WarmQuery extends AsyncDisposable {

808 811 

809| メソッド | 説明 |812| メソッド | 説明 |

810| :- | :- |813| :- | :- |

811| `query(prompt)` | 事前にウォームアップされたサブプロセスにプロンプトを送信し、[`Query`](#query-object) を返します。`WarmQuery` ごとに 1 回だけ呼び出せます |814| `query(prompt)` | 事前にウォームアップされたサブプロセスにプロンプトを送信し、[`Query`](#query-object) を返します。`WarmQuery` ごとに 1 回のみ呼び出せます |

812| `close()` | プロンプトを送信せずにサブプロセスを閉じます。不要になったウォームクエリを破棄する場合に使用します |815| `close()` | プロンプトを送信せずにサブプロセスを閉じます。不要になったウォームクエリを破棄するために使用します |

813 816 

814`WarmQuery` は `AsyncDisposable` を実装しているため、`await using` と組み合わせて自動クリーンアップに使用できます。817`WarmQuery` は `AsyncDisposable` を実装しているため、自動クリーンアップのために `await using` と一緒に使用できます。

815 818 

816<h3 id="spareprocess">819<h3 id="spareprocess">

817 `SpareProcess`820 `SpareProcess`

818</h3>821</h3>

819 822 

820*アルファ版。* [`prewarm()`](#prewarm) が返すハンドルで、まだセッションにバインドされておらず、1 回だけ取得（claim）できる起動済みの Claude Code プロセスです。TypeScript Agent SDK v0.3.282 以降が必要です。823*アルファ版。* [`prewarm()`](#prewarm) が返すハンドルです。まだセッションにバインドされておらず、1 回だけ claim できる起動済みの Claude Code プロセスを表します。TypeScript Agent SDK v0.3.282 以降が必要です。

821 824 

822```typescript theme={null}825```typescript theme={null}

823interface SpareProcess extends AsyncDisposable {826interface SpareProcess extends AsyncDisposable {

837 840 

838| メンバー | 説明 |841| メンバー | 説明 |

839| :- | :- |842| :- | :- |

840| `claim({ prompt, options })` | スペアを `options.cwd` 内のセッションにバインドし、最初のメッセージを送信します。`query()` と同様に [`Query`](#query-object) を同期的に返します。1 回だけ呼び出せます |843| `claim({ prompt, options })` | スペアを `options.cwd` のセッションにバインドし、最初のメッセージを送信します。`query()` と同様に、[`Query`](#query-object) を同期的に返します。1 回のみ呼び出せます |

841| `claimed` | Claude Code が claim を受け入れると、セッションの作業ディレクトリと ID で解決されます。Claude Code が claim を拒否した場合、プロセスが先に終了したか閉じられた場合、およびセッションが要求した `model` または `maxThinkingTokens` なしで実行されている場合（`option_not_applied` で始まるメッセージ）に拒否されます |844| `claimed` | Claude Code が claim を受け入れると、セッションの作業ディレクトリと ID で解決されます。Claude Code が claim を拒否した場合、プロセスが先に終了またはクローズされた場合、および（`option_not_applied` で始まるメッセージとともに）要求した `model` または `maxThinkingTokens` なしでセッションが実行されている場合は拒否されます |

842| `exited` | claim されたかどうかにかかわらず、プロセスが終了すると確定します。claim する前に終了したスペアは置き換えてください |845| `exited` | claim されたかどうかにかかわらず、プロセスが終了したときに確定します。claim する前に終了したスペアは置き換えてください |

843| `close()` | プロセスを終了します。claim 前の場合はスペアを破棄し、`claimed` を拒否します |846| `close()` | プロセスを終了します。claim の前であれば、スペアを破棄して `claimed` を拒否します |

844 847 

845`options.cwd` は必須です。claim では、`additionalDirectories`、`model`、`permissionMode`、`maxThinkingTokens`、`settings` でのフラグ設定オーバーレイ、`appendSystemPrompt`、`title`、`agents`、`env` でのセッションごとのトークンも設定できます。848`options.cwd` は必須です。claim では、`additionalDirectories`、`model`、`permissionMode`、`maxThinkingTokens`、`settings` 内のフラグ設定オーバーレイ、`appendSystemPrompt`、`title`、`agents`、および `env` 内のセッションごとのトークンも設定できます。

846 849 

847Claude Code は、存在しないフォルダーや、プロジェクト設定で `env`、`agent`、または `model` が設定されているフォルダーなどの場合に claim を拒否することがあります。`claimed` が `option_not_applied` で始まるメッセージで拒否された場合、セッションは要求した `model` または `maxThinkingTokens` なしで実行されています。その他の拒否の場合はプロンプトが実行されていないため、代わりに `query()` でセッションを開始してください。850Claude Code は、存在しないフォルダーや、プロジェクト設定で `env`、`agent`、`model` を設定しているフォルダーなどに対して claim を拒否することがあります。拒否された後、`claim()` がすでに送信したプロンプトは `not_claimed` で始まるテキストのエラー結果を受け取り、返されたクエリはその後例外をスローします。スローされた後も処理を続けるには、クエリのループを try ブロックで囲んでください。`claimed` が `option_not_applied` で始まるメッセージで拒否された場合、セッションは要求した `model` または `maxThinkingTokens` なしで実行されています。それ以外の拒否の後はプロンプトは実行されていないため、代わりに `query()` でセッションを開始してください。

848 851 

849<h3 id="sdkcontrolinitializeresponse">852<h3 id="sdkcontrolinitializeresponse">

850 `SDKControlInitializeResponse`853 `SDKControlInitializeResponse`

874};877};

875```878```

876 879 

877`hooks_applied` は、`initialize` リクエストに含まれていた `hooks` を Claude Code が登録したかどうかを示します。SDK はこのリクエストをセッション開始時に 1 回送信し、[`reinitialize()`](#query-object) を呼び出すたびに再度送信します。このフィールドには Agent SDK v0.3.238 以降が必要です。880`hooks_applied` は、`initialize` リクエストに含まれていた `hooks` を Claude Code が登録したかどうかを報告します。SDK はこのリクエストをセッション開始時に 1 回送信し、[`reinitialize()`](#query-object) を呼び出すたびに再度送信します。このフィールドには Agent SDK v0.3.238 以降が必要です。

878 881 

879リクエストにフックが含まれていなかった場合、Claude Code はこのフィールドを省略します。リクエストにフックが含まれていた場合、値はそのリクエストがセッションの最初の initialize かどうか、また繰り返しの initialize の場合はどのようにセッションに到達したかによって決まります。882リクエストにフックが含まれていない場合、Claude Code はこのフィールドを省略します。リクエストにフックが含まれていた場合、値はそのリクエストがセッションの最初の initialize かどうか、また繰り返しの initialize の場合はセッションへの到達経路によって異なります:

880 883 

881* `true`: Claude Code がフックを登録しました。セッションの最初の initialize はこの値を返します。CLI の stdin を介して送信された繰り返しの initialize も `true` を返します。その場合、新しいリクエストのフックが以前に登録されたフックを置き換えます。884* `true`: Claude Code がフックを登録しました。セッションの最初の initialize はこの値を返します。CLI の stdin 経由で送信された繰り返しの initialize も `true` を返します。その場合、新しいリクエストのフックが以前に登録されたフックを置き換えます。

882* `false`: Claude Code はフックを無視しました。リモートセッションに送信された繰り返しの initialize はこの値を返すため、セッションに参加した 2 番目のクライアントは、最初のクライアントが登録したフックを置き換えることができません。885* `false`: Claude Code はフックを無視しました。リモートセッションに送信された繰り返しの initialize はこの値を返します。そのため、セッションに参加した 2 番目のクライアントが、最初のクライアントが登録したフックを置き換えることはできません。

883 886 

884Agent SDK v0.3.238 より前は、レスポンスにこのフィールドは含まれず、Claude Code は繰り返しのすべての initialize で `hooks` を無視していました。887Agent SDK v0.3.238 より前は、レスポンスにこのフィールドが含まれることはなく、Claude Code は繰り返しの initialize ではすべて `hooks` を無視していました。

885 888 

886リクエストの `sdkMcpServerManifests` フィールドとレスポンスの `sdk_mcp_manifests_parked` フィールドは、[`createSdkMcpServer()`](#createsdkmcpserver) で作成したインプロセスの [SDK MCP サーバー](/docs/ja/agent-sdk/custom-tools)のためのものです。アプリケーションがどちらのフィールドを設定したり読み取ったりすることもありません。889リクエストの `sdkMcpServerManifests` フィールドとレスポンスの `sdk_mcp_manifests_parked` フィールドは、[`createSdkMcpServer()`](#createsdkmcpserver) で作成したインプロセスの [SDK MCP サーバー](/docs/ja/agent-sdk/custom-tools)用です。アプリケーションがどちらのフィールドを設定したり読み取ったりすることはありません。

887 890 

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) を参照してください。891レスポンスは常に `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 892 

890成功した `initialize` のコントロールレスポンスのラッパーには、`pending_permission_requests` 配列も含まれます。このフィールドはレスポンスラッパー自体にあり、上記の `SDKControlInitializeResponse` ペイロード内にはありません。各エントリは完全な `control_request` メッセージで、実行中にセッションが権限リクエストとしてストリーミングするのと同じ `{ type: "control_request", request_id, request }` の形をしています。893成功した `initialize` の制御レスポンスのラッパーには、`pending_permission_requests` 配列も含まれます。このフィールドはレスポンスのラッパー自体にあり、上記の `SDKControlInitializeResponse` ペイロード内にはありません。各エントリは完全な `control_request` メッセージで、実行中にセッションが権限リクエストのためにストリーミングするのと同じ `{ type: "control_request", request_id, request }` の形状をしています。

891 894 

892この配列には、この Claude Code プロセスが発行してまだ解決されていない権限リクエストが一覧表示されます。SDK はこの配列を読み取り、各エントリを [`canUseTool`](#canusetool) コールバックにディスパッチします。これは、トランスポートの途絶後に [`reinitialize()`](#query-object) がトリガーするのと同じ再配信です。エントリは、接続が切断される前にコールバックがすでに受け取ったリクエストを繰り返す場合があるため、繰り返されるリクエスト ID は冪等に処理してください。895この配列には、この Claude Code プロセスが発行してまだ解決されていない権限リクエストが列挙されます。SDK はこの配列を自動的に読み取り、各エントリを [`canUseTool`](#canusetool) コールバックにディスパッチします。これは、トランスポートが途切れた後に [`reinitialize()`](#query-object) がトリガーするのと同じ再配信です。エントリは接続が切れる前にコールバックがすでに受け取ったリクエストを繰り返す可能性があるため、繰り返されるリクエスト ID は冪等に処理してください。

893 896 

894この配列は成功した `initialize` レスポンスに常に存在し、このプロセスに未解決の権限リクエストがない場合は空になります。Claude Code v2.1.268 以降が必要です。以前のバージョンではこのフィールドが省略される場合があるため、ワイヤープロトコルを自分で解析する場合は、フィールドがないことを保留中のものがない証拠としてではなく、古い CLI であることの表れとして扱ってください。897この配列は成功した `initialize` レスポンスに常に存在し、このプロセスに未解決の権限リクエストがない場合は空になります。Claude Code v2.1.268 以降が必要です。それより前のバージョンではこのフィールドが省略される可能性があるため、ワイヤプロトコルを自分で解析する場合は、フィールドがないことを保留中のものがない証拠としてではなく、古い CLI であることを示すものとして扱ってください。

895 898 

896<h3 id="sdkcontrolinterruptresponse">899<h3 id="sdkcontrolinterruptresponse">

897 `SDKControlInterruptResponse`900 `SDKControlInterruptResponse`

898</h3>901</h3>

899 902 

900中断の受領通知です。[`SDKSystemMessage.capabilities`](#sdksystemmessage) で `interrupt_receipt_v1` ケイパビリティを通知している CLI で、[`interrupt()`](#query-object) が解決される値です。Claude Code v2.1.205 以降が必要です。それ以前の CLI は空の成功ペイロードで中断に応答するため、`interrupt()` は `undefined` に解決されます。903割り込みの受領確認です。[`SDKSystemMessage.capabilities`](#sdksystemmessage) で `interrupt_receipt_v1` 機能をアドバタイズしている CLI で、[`interrupt()`](#query-object) が解決する値です。Claude Code v2.1.205 以降が必要です。それより前の CLI は空の成功ペイロードで割り込みに応答するため、`interrupt()` は `undefined` に解決されます。

901 904 

902```typescript theme={null}905```typescript theme={null}

903type SDKControlInterruptResponse = {906type SDKControlInterruptResponse = {

906};909};

907```910```

908 911 

909`still_queued` は、中断が到着した時点で保留中だったユーザーメッセージの UUID を一覧表示します。これには、まだキューにあるメッセージと、Claude Code が次のターンのためにすでにキューから取り出していたメッセージが含まれます。セッションの最初のターンが開始された後は、先にキャンセルしない限り、Claude Code は一覧にあるメッセージを中断後に処理し、複数のメッセージを 1 つのターンにまとめることがあります。最初のターンが開始される前に中断した場合、Claude Code はそのターンが開始されるとすぐに中止し、そのターン内の一覧にあるメッセージには応答がありません。912`still_queued` には、割り込みが到着した時点で保留中だったユーザーメッセージの UUID が列挙されます。これには、まだキューにあるメッセージと、Claude Code が次のターンのためにすでにキューから取り出したメッセージが含まれます。セッションの最初のターンが開始された後は、先にキャンセルしない限り、Claude Code は割り込みの後に列挙されたメッセージを処理し、複数のメッセージを 1 つのターンにまとめることがあります。最初のターンの開始前に割り込んだ場合、Claude Code はそのターンが開始されるとすぐに中止し、そのターンに含まれる列挙されたメッセージには応答がありません。

910 913 

911受領通知を使用して、何かを再送信するかどうかを判断してください。キャンセルしなかった一覧のメッセージは、応答があるかどうかにかかわらず会話に入るため、再送信すると Claude に 2 回配信されることになります。914受領確認を使用して、何かを再送信するかどうかを判断してください。キャンセルしなかった列挙メッセージは、応答の有無にかかわらず会話に入るため、再送信すると Claude に 2 回配信されます。

912 915 

913一覧を解釈する際は、次の注意点に留意してください。916リストは以下の注意点を踏まえて解釈してください:

914 917 

915* UUID 付きでキューに入れられたメッセージのみが表示されます。空の配列は、他に何も実行されないことを意味するわけではありません。918* UUID 付きでキューに追加されたメッセージのみが表示されます。空の配列は、他に何も実行されないことを意味するわけではありません。

916* メインスレッドのメッセージのみが一覧表示されます。サブエージェント宛てのメッセージは対象外です。919* メインスレッドのメッセージのみが列挙されます。サブエージェント宛てのメッセージは対象外です。

917* 一覧には、[スケジュールタスク](/docs/ja/scheduled-tasks)のトリガーなど、クライアントが送信していない UUID が含まれる場合があります。認識できない UUID はエラーとして扱わず、無視してください。920* リストには、[スケジュールタスク](/docs/ja/scheduled-tasks)のトリガーなど、クライアントが送信していない UUID が含まれることがあります。認識できない UUID はエラーとして扱わずに無視してください。

918 921 

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` は空になり、いずれも実行されません。922`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 923 

921`cancelled` の一覧にも `still_queued` と同じ注意点があります。`interrupt()` メソッドは `cancel_queued` を送信しないため、このメソッドが解決する受領通知には `cancelled` は含まれません。924`cancelled` リストには `still_queued` と同じ注意点があります。`interrupt()` メソッドは `cancel_queued` を送信しないため、このメソッドが解決する受領確認には `cancelled` が含まれません。

922 925 

923受領通知は中断が処理された時点で取得されたスナップショットであり、正常な中断の場合は中断されたターンの [`SDKResultMessage`](#sdkresultmessage) より前に到着します。その結果の後にキューを調べるのではなく、受領通知を読み取ってください。ループは次のキュー内のターンをすぐに開始するため、結果の後に調べるキューはすでに変化しています。926受領確認は割り込みが処理された時点のスナップショットであり、正常な割り込みでは、割り込まれたターンの [`SDKResultMessage`](#sdkresultmessage) より前に到着します。その結果の後にキューを調べるのではなく、受領確認を読み取ってください。ループは次のキュー内のターンをすぐに開始するため、結果の後に調べるキューはすでに変化しています。

924 927 

925<h3 id="sdkcontrolgetcontextusageresponse">928<h3 id="sdkcontrolgetcontextusageresponse">

926 `SDKControlGetContextUsageResponse`929 `SDKControlGetContextUsageResponse`

927</h3>930</h3>

928 931 

929[`getContextUsage()`](#query-object) の戻り値の型です。デフォルトの `detail` では、インタラクティブセッションで Claude Code が `/context` コマンドに対してレンダリングするものと同じペイロードであるため、トークン数に加えて、Claude Code が `/context` の使用量グリッドを描画するために使用する `color` や `gridRows` などの表示用フィールドも含まれます。932[`getContextUsage()`](#query-object) の戻り値の型です。デフォルトの `detail` では、インタラクティブセッションで Claude Code が `/context` コマンドに対してレンダリングするのと同じペイロードであり、トークン数とともに、Claude Code が `/context` の使用量グリッドを描画するために使用する `color` や `gridRows` などの表示用フィールドも含まれます。

930 933 

931メソッドのオプションの `detail` 引数で、Claude Code が各カテゴリをどのようにカウントするかを選択します。`detail` 引数には Agent SDK v0.3.257 以降が必要です。934メソッドのオプションの `detail` 引数で、Claude Code が各カテゴリをどのようにカウントするかを選択します。`detail` 引数には Agent SDK v0.3.257 以降が必要です。

932 935 

933* **`'full'`**: デフォルトです。Claude Code は[トークンカウント](https://platform.claude.com/docs/en/build-with-claude/token-counting) API リクエストを使って各カテゴリをカウントします。これらのリクエストはメッセージストリームに現れないため、ストリームを読み取るコスト追跡では把握できません。Anthropic API では、トークンカウントは課金されません。936* **`'full'`**: デフォルトです。Claude Code は[トークンカウント](https://platform.claude.com/docs/en/build-with-claude/token-counting) API リクエストで各カテゴリをカウントします。これらのリクエストはメッセージストリームに表示されないため、ストリームを読み取るコスト追跡では検出されません。Anthropic API では、トークンカウントは課金されません。

934* **`'summary'`**: `{ detail: 'summary' }` を渡すと、代わりに最後のレスポンスの使用量とローカルの見積もりから回答を得られます。トークンカウントのリクエストは送信されず、カテゴリごとの数値は概算になります。937* **`'summary'`**: `{ detail: 'summary' }` を渡すと、代わりに最後のレスポンスの使用量とローカルの見積もりから結果を得られます。トークンカウントリクエストは送信されず、カテゴリごとの数値は概算になります。

935 938 

936メソッドを呼び出す代わりに `/context` をプロンプトとして送信すると、Claude Code は結果を伝えるアシスタントメッセージの `context_usage` フィールドに [`SDKContextUsage`](#sdkcontextusage) ペイロードを添付します。このフィールドには Agent SDK v0.3.232 以降が必要です。939メソッドを呼び出す代わりに `/context` をプロンプトとして送信すると、Claude Code は結果を配信するアシスタントメッセージの `context_usage` フィールドに [`SDKContextUsage`](#sdkcontextusage) ペイロードを添付します。このフィールドには Agent SDK v0.3.232 以降が必要です。

937 940 

938```typescript theme={null}941```typescript theme={null}

939type SDKControlGetContextUsageResponse = {942type SDKControlGetContextUsageResponse = {

1030};1033};

1031```1034```

1032 1035 

1033トークンの内訳はコレクションフィールドから読み取ります。1036トークンの内訳はコレクションフィールドから読み取ります:

1034 1037 

1035* `categories` はカテゴリごとの合計を保持します。各エントリの `kind` は、[`SDKContextUsageCategory`](#sdkcontextusagecategory) と同じ値で行を分類します。表示用の `name` ではなく、このフィールドに基づいて行を分類してください。このフィールドには Agent SDK v0.3.268 以降が必要です。1038* `categories` にはカテゴリごとの合計が格納されます。各エントリの `kind` は、[`SDKContextUsageCategory`](#sdkcontextusagecategory) と同じ値で行を分類します。表示用の `name` ではなく、このフィールドで行を分類してください。このフィールドには Agent SDK v0.3.268 以降が必要です。

1036* `mcpTools` と `agents` は、トークンを個々の MCP ツールとサブエージェントに割り当てます。1039* `mcpTools` と `agents` は、トークンを個々の MCP ツールとサブエージェントに割り当てます。

1037* `memoryFiles` は、読み込まれた各メモリファイルとそのコストを一覧表示します。1040* `memoryFiles` は、読み込まれた各メモリファイルとそのコストを列挙します。

1038* `skills.skillFrontmatter` は、スキル一覧のトークンを含まれている各スキルに割り当てます。スキルごとのカウントは、Claude Code が実際に送信する各スキルの一覧エントリを測定したもので、スキルの完全なフロントマターより短い場合があります。`skills.totalSkills` と `skills.includedSkills` を比較すると、検出されたすべてのスキルが一覧に含まれたかどうかを確認できます。1041* `skills.skillFrontmatter` は、スキル一覧のトークンを、含まれている各スキルに割り当てます。スキルごとの数は、Claude Code が実際に送信する各スキルの一覧エントリを測定したもので、スキルの完全なフロントマターより短い場合があります。検出されたすべてのスキルが一覧に含まれたかどうかを確認するには、`skills.totalSkills` と `skills.includedSkills` を比較してください。

1039 1042 

1040`totalTokens` はセッションの現在のコンテキスト使用量で、`maxTokens` はその使用量を測定する基準となるウィンドウです。このウィンドウはモデルのコンテキストウィンドウ、または自動圧縮のウィンドウが適用される場合はそれより小さいそのウィンドウです。`rawMaxTokens` は `maxTokens` と同じ値を持ち、`percentage` はそのウィンドウに対する `totalTokens` の割合を丸めた値です。`apiUsage` は最新の API レスポンスの使用量を保持し、セッションの累計ではありません。1043`totalTokens` はセッションの現在のコンテキスト使用量で、`maxTokens` はその使用量の測定基準となるウィンドウです。このウィンドウは、モデルのコンテキストウィンドウ、または適用される場合はそれより小さい自動圧縮ウィンドウです。`rawMaxTokens` は `maxTokens` と同じ値を持ち、`percentage` はそのウィンドウに対する `totalTokens` の割合を四捨五入したパーセンテージです。`apiUsage` には、セッションの累計ではなく、最新の API レスポンスの使用量が格納されます。

1041 1044 

1042Claude Code はオプションの診断フィールドである `deferredBuiltinTools`、`systemTools`、`systemPromptSections` を設定しないため、型で宣言されていてもこれらは存在しないものと想定してください。1045Claude Code はオプションの `deferredBuiltinTools`、`systemTools`、`systemPromptSections` の診断情報を設定しないため、型で宣言されていても存在しないものと想定してください。

1043 1046 

1044<h3 id="sdkcontrolreadfileresponse">1047<h3 id="sdkcontrolreadfileresponse">

1045 `SDKControlReadFileResponse`1048 `SDKControlReadFileResponse`

1056};1059};

1057```1060```

1058 1061 

1059`contents` はファイルのテキスト、または `encoding: 'base64'` を要求した場合は base64 データを保持します。その場合、レスポンスの `encoding` フィールドは `'base64'` に設定されます。`absPath` は解決された絶対パスです。`truncated` は、ファイルが `maxBytes` の上限より長く、内容がその上限で切り詰められた場合に設定されます。1062`contents` にはファイルのテキスト、または `encoding: 'base64'` を要求した場合は base64 データが格納されます。その場合、レスポンスの `encoding` フィールドは `'base64'` に設定されます。`absPath` は解決された絶対パスです。`truncated` は、ファイルが `maxBytes` の上限より長く、内容がその上限で切り詰められた場合に設定されます。

1060 1063 

1061<h4 id="what-readfile-can-read">1064<h4 id="what-readfile-can-read">

1062 `readFile()` が読み取れるもの1065 `readFile()` で読み取れるもの

1063</h4>1066</h4>

1064 1067 

1065`readFile()` が提供するファイルの範囲は Read ツールより狭くなっています。1068`readFile()` が提供するファイルの範囲は、Read ツールより狭くなっています:

1066 1069 

1067* `cwd` や `additionalDirectories` など、セッションの作業ディレクトリのいずれかに含まれる通常のファイル1070* `cwd` や `additionalDirectories` など、セッションの作業ディレクトリのいずれかにある通常のファイル

1068* ツールの結果など、そのセッションに関する Claude Code 自身のファイルの一部1071* ツールの結果など、セッション用の Claude Code 自身のファイルの一部

1069 1072 

1070`Read` の拒否ルールと確認ルールは引き続き一致するパスをブロックし、広範な `Read` の許可ルールがあっても、ファイルシステムの残りの部分が `readFile()` に開放されることはありません。それ以外のものについては、呼び出しは `null` で解決されます。1073`Read` の拒否ルールと確認ルールは引き続き一致するパスをブロックし、広範な `Read` 許可ルールを設定しても、ファイルシステムの残りの部分が `readFile()` に開放されることはありません。それ以外のものについては、呼び出しは `null` で解決されます。

1071 1074 

1072<h3 id="sdkcontrolreloadpluginsresponse">1075<h3 id="sdkcontrolreloadpluginsresponse">

1073 `SDKControlReloadPluginsResponse`1076 `SDKControlReloadPluginsResponse`

1096};1099};

1097```1100```

1098 1101 

1099コレクションフィールドは、呼び出し後のセッションを表します。1102コレクションフィールドは、呼び出し後のセッションを表します:

1100 1103 

1101* `commands`、`agents`、`mcpServers`: セッションのコマンド、サブエージェント、MCP サーバーのステータスで、`supportedCommands()`、`supportedAgents()`、`mcpServerStatus()` が返すのと同じ形式です。`supportedAgents()` は初期化時に取得されたリストを返し続けるため、再読み込み後のセットについてはここの `agents` を読み取ってください1104* `commands`、`agents`、`mcpServers`: セッションのコマンド、サブエージェント、MCP サーバーのステータスで、`supportedCommands()`、`supportedAgents()`、`mcpServerStatus()` が返すのと同じ形状です。`supportedAgents()` は初期化時に取得したリストを返し続けるため、再読み込み後のセットについてはここの `agents` を読み取ってください

1102* `plugins`: 読み込まれた各プラグインとその `name` およびインストール先の `path`。`version` はプラグインのマニフェストが宣言している内容をそのまま示すもので、プラグインの作成者が制御するため、信頼する前に検証してください。マニフェストが何も宣言していない場合は省略されます1105* `plugins`: 読み込まれた各プラグインと、その `name` およびインストール先の `path`。`version` はプラグインのマニフェストが宣言する内容をそのまま示すもので、プラグインの作成者が制御するため、信頼する前に検証してください。マニフェストが何も宣言していない場合は省略されます

1103* `error_count`: プラグインの読み込みで発生したエラーの数1106* `error_count`: プラグインの読み込み時に発生したエラーの数

1104 1107 

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 実行ファイルはこのオプションを無視して再読み込みを適用します。1108会話のプロンプトキャッシュを無効化する再読み込みを、適用せずに保留するには、`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 1109 

1107このオプションを渡した場合は、`held` を読み取って何が起きたかを確認します。1110このオプションを渡した場合は、`held` を読み取って何が起きたかを確認します:

1108 1111 

1109* `true`: 再読み込みは適用されておらず、コレクションフィールドは現在のままのセッションを表します。`cache_impact` は、適用した場合に何が変わるかを示します。それでも適用するには、オプションなしで `reloadPlugins()` を再度呼び出します。1112* `true`: 再読み込みは適用されず、コレクションフィールドは現在のままのセッションを表します。`cache_impact` は、適用した場合に何が変わるかを示します。それでも適用するには、オプションなしで `reloadPlugins()` を再度呼び出します。

1110* `false`: チェックでキャッシュへの影響が見つからず、再読み込みが適用されました。1113* `false`: チェックでキャッシュへの影響が見つからず、再読み込みが適用されました。

1111* 存在しない: オプションを渡さなかったか、Claude Code 実行ファイルが v2.1.268 より古く、再読み込みを適用しました。1114* 存在しない: オプションを渡していないか、Claude Code 実行ファイルが v2.1.268 より古く、再読み込みを適用しました。

1112 1115 

1113`cache_impact` は `held: true` と併せてのみ存在します。`mcp_servers_added` と `mcp_servers_removed` は、再読み込みによって登録または削除されるプラグインの MCP サーバーを、スコープ付きの `plugin:<plugin>:<server>` 名で示します。これらの名前はプラグインの作成者が付けたものであるため、表示する前に検証してください。`lsp_tool_change` は、適用によって LSP ツールが追加されるか削除されるかを示し、どちらでもない場合は `null` です。`may-` 形式は、チェックで保留中のプラグインセットを完全には把握できなかったことを意味します。1116`cache_impact` は `held: true` と一緒の場合にのみ存在します。`mcp_servers_added` と `mcp_servers_removed` は、再読み込みによって登録または削除されるプラグイン MCP サーバーを、スコープ付きの `plugin:<plugin>:<server>` 名で示します。名前はプラグインの作成者が付けたものなので、表示する前に検証してください。`lsp_tool_change` は、適用によって LSP ツールが追加されるか削除されるかを示し、どちらも行わない場合は `null` になります。`may-` の形式は、チェックが保留中のプラグインセットを完全には把握できなかったことを意味します。

1114 1117 

1115<h3 id="sdkcontrolreloadskillsresponse">1118<h3 id="sdkcontrolreloadskillsresponse">

1116 `SDKControlReloadSkillsResponse`1119 `SDKControlReloadSkillsResponse`

1124};1127};

1125```1128```

1126 1129 

1127`skills` は、再読み込み後に使用可能なスキルを、`supportedCommands()` が返すのと同じ [`SlashCommand`](#slashcommand) の形式で一覧表示します。1130`skills` は、再読み込み後に利用可能なスキルを、`supportedCommands()` が返すのと同じ [`SlashCommand`](#slashcommand) の形状で列挙します。

1128 1131 

1129<h3 id="sdkcontrolreloadoutputstylesresponse">1132<h3 id="sdkcontrolreloadoutputstylesresponse">

1130 `SDKControlReloadOutputStylesResponse`1133 `SDKControlReloadOutputStylesResponse`

1138};1141};

1139```1142```

1140 1143 

1141`available_output_styles` は、再読み込み後に使用可能な組み込みおよびカスタムの出力スタイルの名前を一覧表示します。1144`available_output_styles` は、再読み込み後に利用可能な組み込みおよびカスタムの出力スタイルの名前を列挙します。

1142 1145 

1143<h3 id="sdkcontrolmcpreadresourceresponse">1146<h3 id="sdkcontrolmcpreadresourceresponse">

1144 `SDKControlMcpReadResourceResponse`1147 `SDKControlMcpReadResourceResponse`

1158};1161};

1159```1162```

1160 1163 

1161`readMcpResource()` には、`mcpServerStatus()` が報告するサーバー名と、ツールが [`_meta`](#mcpserverstatus) で宣言する `ui.resourceUri` などの `ui://` URI を渡します。その他の URI スキームの場合、アプリケーション自身がホストする [SDK MCP サーバー](#createsdkmcpserver)の場合、および接続されていないサーバーの場合、呼び出しは拒否されます。init メッセージの [`capabilities`](#sdksystemmessage) に `mcp_read_resource_v1` が含まれている場合に使用できます。1164`readMcpResource()` には、`mcpServerStatus()` が報告するサーバー名と、ツールが [`_meta`](#mcpserverstatus) で宣言する `ui.resourceUri` などの `ui://` URI を渡します。その他の URI スキーム、アプリケーション自身がホストする [SDK MCP サーバー](#createsdkmcpserver)、および接続されていないサーバーに対しては、呼び出しは拒否されます。init メッセージの [`capabilities`](#sdksystemmessage) に `mcp_read_resource_v1` が含まれている場合に利用できます。

1162 1165 

1163各 `contents` エントリは、サーバーが送信したとおりの 1 つのコンテンツ項目ですが、Claude Code 用に予約されている `com.anthropic/` プレフィックス以下の `_meta` キーは除かれます。`blob` はバイナリ項目の base64 データを保持し、`_meta` はその項目自身の `_meta` で、MCP Apps サーバーはリソースの `ui.csp` と `ui.permissions` をここに配置します。1166各 `contents` エントリは、サーバーが送信したとおりのコンテンツ項目 1 つであり、Claude Code 用に予約されている `com.anthropic/` プレフィックス配下の `_meta` キーは除かれます。`blob` にはバイナリ項目の base64 データが格納され、`_meta` は項目自身の `_meta` で、MCP Apps サーバーはここにリソースの `ui.csp` と `ui.permissions` を配置します。

1164 1167 

1165コンテンツは信頼できないサードパーティの HTML であるため、サンドボックス内でレンダリングしてください。1168内容は信頼できないサードパーティの HTML であるため、サンドボックス内でレンダリングしてください。

1166 1169 

1167<h3 id="agentdefinition">1170<h3 id="agentdefinition">

1168 `AgentDefinition`1171 `AgentDefinition`

1192 1195 

1193| フィールド | 必須 | 説明 |1196| フィールド | 必須 | 説明 |

1194| :- | :- | :- |1197| :- | :- | :- |

1195| `description` | はい | このエージェントをいつ使用するかを自然言語で説明したもの |1198| `description` | はい | このエージェントをいつ使用するかを説明する自然言語の記述 |

1196| `tools` | いいえ | 許可されるツール名の配列。省略した場合、[サブエージェントが使用できるツール](/docs/ja/sub-agents#available-tools)をすべて継承します。スキルをエージェントのコンテキストに事前読み込みするには、ここに `'Skill'` を列挙するのではなく `skills` フィールドを使用してください |1199| `tools` | いいえ | 許可するツール名の配列。省略した場合、[サブエージェントで利用可能なツール](/docs/ja/sub-agents#available-tools)をすべて継承します。スキルをエージェントのコンテキストにプリロードするには、ここに `'Skill'` を列挙するのではなく `skills` フィールドを使用してください |

1197| `disallowedTools` | いいえ | このエージェントで明示的に禁止するツール名の配列。MCP サーバーレベルのパターンも使用できます。`mcp__server` または `mcp__server__*` はそのサーバーのすべてのツールを削除し、`mcp__*` はすべてのサーバーのすべての MCP ツールを削除します |1200| `disallowedTools` | いいえ | このエージェントで明示的に禁止するツール名の配列。MCP サーバーレベルのパターンも受け付けます。`mcp__server` または `mcp__server__*` はそのサーバーのすべてのツールを削除し、`mcp__*` は任意のサーバーのすべての MCP ツールを削除します |

1198| `prompt` | はい | エージェントのシステムプロンプト |1201| `prompt` | はい | エージェントのシステムプロンプト |

1199| `model` | いいえ | このエージェントのモデルの上書き。`'fable'`、`'opus'`、`'sonnet'`、`'haiku'`、`'inherit'` などのエイリアス、または完全なモデル ID を受け付けます。`'inherit'` はメインのモデルを使用します。省略した場合、Claude Code は[サブエージェントのモデルの順序](/docs/ja/sub-agents#choose-a-model)に従ってモデルを選択します |1202| `model` | いいえ | このエージェントのモデルの上書き。`'fable'`、`'opus'`、`'sonnet'`、`'haiku'`、`'inherit'` などのエイリアス、または完全なモデル ID を受け付けます。`'inherit'` はメインモデルを使用します。省略した場合、Claude Code は[サブエージェントのモデルの順序](/docs/ja/sub-agents#choose-a-model)に従ってモデルを選択します |

1200| `mcpServers` | いいえ | このエージェントの MCP サーバーの指定 |1203| `mcpServers` | いいえ | このエージェントの MCP サーバーの指定 |

1201| `skills` | いいえ | エージェントのコンテキストに事前読み込みするスキル名の配列 |1204| `skills` | いいえ | エージェントのコンテキストにプリロードするスキル名の配列 |

1202| `initialPrompt` | いいえ | このエージェントがメインスレッドのエージェントとして実行されるときに、最初のユーザーターンとして自動送信されます |1205| `initialPrompt` | いいえ | このエージェントがメインスレッドのエージェントとして実行される場合に、最初のユーザーターンとして自動送信されます |

1203| `maxTurns` | いいえ | 停止するまでのエージェントの最大ターン数（API の往復） |1206| `maxTurns` | いいえ | 停止するまでのエージェントの最大ターン数（API ラウンドトリップ） |

1204| `background` | いいえ | 呼び出されたときに、このエージェントをノンブロッキングのバックグラウンドタスクとして実行します |1207| `background` | いいえ | 呼び出されたときに、このエージェントをノンブロッキングのバックグラウンドタスクとして実行します |

1205| `omitClaudeMd` | いいえ | サブエージェントとして実行されるときに、ユーザー、プロジェクト、ローカルの CLAUDE.md ファイルなしでこのエージェントを実行します。管理ポリシーファイルは引き続き読み込まれます。必要なものをすべて Agent ツールのプロンプトから受け取るエージェントに使用します。このエージェントがメインスレッドのエージェントとして実行される場合は無視されます。TypeScript Agent SDK v0.3.271 以降が必要です |1208| `omitClaudeMd` | いいえ | このエージェントがサブエージェントとして実行される場合に、ユーザー、プロジェクト、ローカルの CLAUDE.md ファイルなしで実行します。管理ポリシーファイルは引き続き読み込まれます。必要なものをすべて Agent ツールのプロンプトから受け取るエージェントに使用します。このエージェントがメインスレッドのエージェントとして実行される場合は無視されます。TypeScript Agent SDK v0.3.271 以降が必要です |

1206| `memory` | いいえ | このエージェントのメモリソース: `'user'`、`'project'`、または `'local'` |1209| `memory` | いいえ | このエージェントのメモリソース: `'user'`、`'project'`、または `'local'` |

1207| `effort` | いいえ | このエージェントの推論の effort レベル。名前付きのレベルまたは整数を受け付けます |1210| `effort` | いいえ | このエージェントの推論の effort レベル。名前付きのレベルまたは整数を受け付けます |

1208| `permissionMode` | いいえ | このエージェント内でのツール実行の権限モード。いつ適用されるかは[サブエージェントの継承ルール](/docs/ja/agent-sdk/permissions#available-modes)によって決まります。[`PermissionMode`](#permissionmode) を参照してください |1211| `permissionMode` | いいえ | このエージェント内でのツール実行の権限モード。適用されるタイミングは[サブエージェントの継承ルール](/docs/ja/agent-sdk/permissions#available-modes)によって決まります。[`PermissionMode`](#permissionmode) を参照してください |

1209| `criticalSystemReminder_EXPERIMENTAL` | いいえ | 実験的: システムプロンプトに追加される重要なリマインダー |1212| `criticalSystemReminder_EXPERIMENTAL` | いいえ | 実験的: システムプロンプトに追加される重要なリマインダー |

1210 1213 

1211<h3 id="agentmcpserverspec">1214<h3 id="agentmcpserverspec">

1212 `AgentMcpServerSpec`1215 `AgentMcpServerSpec`

1213</h3>1216</h3>

1214 1217 

1215サブエージェントが使用できる MCP サーバーを指定します。サーバー名（親の `mcpServers` 設定内のサーバーを参照する文字列）、またはサーバー名を設定にマッピングするインラインのサーバー設定レコードを指定できます。1218サブエージェントで利用可能な MCP サーバーを指定します。サーバー名（親の `mcpServers` 設定内のサーバーを参照する文字列）、またはサーバー名を設定にマッピングするインラインのサーバー設定レコードを指定できます。

1216 1219 

1217```typescript theme={null}1220```typescript theme={null}

1218type AgentMcpServerSpec = string | Record<string, McpServerConfigForProcessTransport>;1221type AgentMcpServerSpec = string | Record<string, McpServerConfigForProcessTransport>;

1219```1222```

1220 1223 

1221ここで `McpServerConfigForProcessTransport` は `McpStdioServerConfig | McpSSEServerConfig | McpHttpServerConfig | McpSdkServerConfig` です。1224ここで、`McpServerConfigForProcessTransport` は `McpStdioServerConfig | McpSSEServerConfig | McpHttpServerConfig | McpSdkServerConfig` です。

1222 1225 

1223<h3 id="settingsource">1226<h3 id="settingsource">

1224 `SettingSource`1227 `SettingSource`

1225</h3>1228</h3>

1226 1229 

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

1228 1231 

1229```typescript theme={null}1232```typescript theme={null}

1230type SettingSource = "user" | "project" | "local";1233type SettingSource = "user" | "project" | "local";

1234| :- | :- | :- |1237| :- | :- | :- |

1235| `'user'` | グローバルなユーザー設定 | `~/.claude/settings.json` |1238| `'user'` | グローバルなユーザー設定 | `~/.claude/settings.json` |

1236| `'project'` | 共有プロジェクト設定（バージョン管理対象） | `.claude/settings.json` |1239| `'project'` | 共有プロジェクト設定（バージョン管理対象） | `.claude/settings.json` |

1237| `'local'` | ローカルプロジェクト設定。Claude Code が設定を保存する際に gitignore に追加されます | `.claude/settings.local.json` |1240| `'local'` | ローカルプロジェクト設定。Claude Code が設定を保存する際に gitignore されます | `.claude/settings.local.json` |

1238 1241 

1239<h4 id="default-behavior">1242<h4 id="default-behavior">

1240 デフォルトの動作1243 デフォルトの動作

1241</h4>1244</h4>

1242 1245 

1243`settingSources` が省略されているか `undefined` の場合、`query()` は Claude Code CLI と同じファイルシステム設定（user、project、local）を読み込みます。このオプションに関係なく読み込まれる入力とそれらを無効にする方法については、[settingSources が制御しないもの](/docs/ja/agent-sdk/claude-code-features#what-settingsources-does-not-control)を参照してください。1246`settingSources` が省略されているか `undefined` の場合、`query()` は Claude Code CLI と同じファイルシステム設定（user、project、local）を読み込みます。このオプションに関係なく読み込まれる入力とその無効化方法については、[settingSources で制御されないもの](/docs/ja/agent-sdk/claude-code-features#what-settingsources-does-not-control)を参照してください。

1244 1247 

1245<h4 id="why-use-settingsources">1248<h4 id="why-use-settingsources">

1246 settingSources を使用する理由1249 settingSources を使用する理由

1278 設定の優先順位1281 設定の優先順位

1279</h4>1282</h4>

1280 1283 

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

1282 1285 

12831. ローカル設定（`.claude/settings.local.json`）12861. ローカル設定（`.claude/settings.local.json`）

12842. プロジェクト設定（`.claude/settings.json`）12872. プロジェクト設定（`.claude/settings.json`）

12853. ユーザー設定（`~/.claude/settings.json`）12883. ユーザー設定（`~/.claude/settings.json`）

1286 1289 

1287`agents`、`allowedTools`、`settings` などのプログラムによるオプションは、ユーザー、プロジェクト、ローカルのファイルシステム設定を上書きします。管理ポリシー設定はプログラムによるオプションよりも優先されます。1290`agents`、`allowedTools`、`settings` などのプログラムによるオプションは、user、project、local のファイルシステム設定を上書きします。管理ポリシー設定は、プログラムによるオプションよりも優先されます。

1288 1291 

1289<h3 id="permissionmode">1292<h3 id="permissionmode">

1290 `PermissionMode`1293 `PermissionMode`

1306 1309 

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

1308 1311 

1309この関数は、対話型の権限プロンプトを SDK で置き換えるものです。[権限評価フロー](/docs/ja/agent-sdk/permissions#how-permissions-are-evaluated)の結果がプロンプトになった場合にのみ呼び出されます。`allowedTools` のエントリ、設定の許可ルール、または `acceptEdits` や `bypassPermissions` などの権限モードによってすでに承認されているツール呼び出しでは、この関数は呼び出されません。すべてのツール呼び出しを制御するには、代わりに [`PreToolUse` フック](/docs/ja/agent-sdk/hooks)を使用してください。1312この関数は、対話型の権限プロンプトに代わる SDK の仕組みです。[権限評価フロー](/docs/ja/agent-sdk/permissions#how-permissions-are-evaluated)がプロンプトの表示に至った場合にのみ呼び出されます。`allowedTools` のエントリ、設定の許可ルール、または `acceptEdits` や `bypassPermissions` などの権限モードによってすでに承認されているツール呼び出しでは、この関数は呼び出されません。すべてのツール呼び出しを制御するには、代わりに [`PreToolUse` フック](/docs/ja/agent-sdk/hooks)を使用してください。

1310 1313 

1311許可ルールは、[どのモードでも自動承認されないアクション](/docs/ja/permission-modes#actions-no-mode-auto-approves)を事前承認しません。それらのうちどれがコールバックに到達するか、また `dontAsk` モードと `auto` モードで何が起こるかについては、[権限の評価方法](/docs/ja/agent-sdk/permissions#how-permissions-are-evaluated)を参照してください。1314許可ルールは、[どのモードでも自動承認されないアクション](/docs/ja/permission-modes#actions-no-mode-auto-approves)を事前承認しません。それらのうちどれがコールバックに到達するか、また `dontAsk` モードと `auto` モードで何が起こるかについては、[権限の評価方法](/docs/ja/agent-sdk/permissions#how-permissions-are-evaluated)を参照してください。

1312 1315 

1332| オプション | 型 | 説明 |1335| オプション | 型 | 説明 |

1333| :- | :- | :- |1336| :- | :- | :- |

1334| `signal` | `AbortSignal` | 操作を中止すべき場合にシグナルが送られます |1337| `signal` | `AbortSignal` | 操作を中止すべき場合にシグナルが送られます |

1335| `suggestions` | [`PermissionUpdate`](#permissionupdate)`[]` | このツールについてユーザーに再度プロンプトが表示されないようにするための、提案された権限の更新。Bash のプロンプトには `localSettings` [保存先](#permissionupdatedestination)を持つ提案が含まれるため、それを `updatedPermissions` で返すとルールが `.claude/settings.local.json` に書き込まれ、セッションをまたいで保持されます。 |1338| `suggestions` | [`PermissionUpdate`](#permissionupdate)`[]` | このツールについてユーザーに再度プロンプトが表示されないようにするための、推奨される権限の更新。Bash のプロンプトには `localSettings` の[保存先](#permissionupdatedestination)を持つ推奨が含まれるため、それを `updatedPermissions` で返すとルールが `.claude/settings.local.json` に書き込まれ、セッションをまたいで保持されます。 |

1336| `blockedPath` | `string` | 権限リクエストをトリガーしたファイルパス（該当する場合） |1339| `blockedPath` | `string` | 権限リクエストのきっかけとなったファイルパス（該当する場合） |

1337| `mcpServer` | `{ name: string; source: string }` | `mcp__*` ツールの場合、そのツールを提供する MCP サーバーと、そのサーバーの定義の取得元。フィールドは [`McpServerProvenance`](#mcpserverprovenance) と同じです。その他のツールでは存在しません。Agent SDK v0.3.274 以降が必要です |1340| `mcpServer` | `{ name: string; source: string }` | `mcp__*` ツールの場合、そのツールを提供する MCP サーバーと、そのサーバーの定義の取得元。フィールドは [`McpServerProvenance`](#mcpserverprovenance) と同じです。その他のツールでは存在しません。Agent SDK v0.3.274 以降が必要です |

1338| `decisionReason` | `string` | この権限リクエストがトリガーされた理由の説明 |1341| `decisionReason` | `string` | この権限リクエストがトリガーされた理由の説明 |

1339| `defaultToNo` | `boolean` | `true` の場合、誤って押された 1 回のキー入力でこのリクエストが承認されてはなりません。プロンプトは拒否オプションを選択した状態で開き、承認を事前選択せず、1 キーで承認できるショートカットも提供しないでください。Agent SDK v0.3.268 以降が必要です |1342| `defaultToNo` | `boolean` | `true` の場合、誤った 1 回のキー入力でこのリクエストが承認されてはなりません。プロンプトは拒否の選択肢を選択した状態で開き、承認を事前選択せず、1 キーで承認できるショートカットも提供しないでください。Agent SDK v0.3.268 以降が必要です |

1340| `suppressAlwaysAllowRule` | `boolean` | `true` の場合、このリクエストに対して永続的な「常に許可」の選択肢を提供しないでください。書き込まれるルールが、リクエスト自体のアクションよりも広い権限を付与してしまうためです。Agent SDK v0.3.268 以降が必要です |1343| `suppressAlwaysAllowRule` | `boolean` | `true` の場合、このリクエストに対して永続的な「常に許可」の選択肢を提供しないでください。Agent SDK v0.3.268 以降が必要です |

1341| `toolUseID` | `string` | アシスタントメッセージ内のこの特定のツール呼び出しの一意な識別子 |1344| `toolUseID` | `string` | アシスタントメッセージ内のこの特定のツール呼び出しの一意の識別子 |

1342| `agentID` | `string` | サブエージェント内で実行されている場合、そのサブエージェントの ID |1345| `agentID` | `string` | サブエージェント内で実行されている場合、そのサブエージェントの ID |

1343| `requestId` | `string` | `control_request` エンベロープの `request_id`。アプリケーションが SDK の外部から送信する `control_response`（署名付き HTTP POST など）は、Claude Code プロセスが応答をリクエストと照合できるよう、この値をそのまま返す必要があります |1346| `requestId` | `string` | `control_request` エンベロープの `request_id`。アプリケーションが SDK の外部で送信する `control_response`（署名付き HTTP POST など）は、Claude Code プロセスが応答をリクエストと照合できるように、この値をそのまま返す必要があります |

1344 1347 

1345コールバックは通常、[`PermissionResult`](#permissionresult) を返すことでリクエストを解決し、SDK はそれを `control_response` としてトランスポート経由で書き戻します。`null` を返すのは、アプリケーションがすでに独自のチャネル経由で `requestId` を含めてこのリクエストの `control_response` を送信済みの場合に限ってください。その場合、SDK はトランスポートへのレスポンスの書き込みをスキップします。それ以外のケースで `null` を返すと、`control_response` が送信されず、権限プロンプトはタイムアウトしないため、ツール呼び出しが無期限にブロックされたままになります。1348コールバックは通常、[`PermissionResult`](#permissionresult) を返すことでリクエストを解決し、SDK はそれを `control_response` としてトランスポート経由で書き戻します。`null` を返すのは、アプリケーションが `requestId` を含めて、このリクエストに対する `control_response` を独自のチャネルですでに送信している場合に限ってください。その場合、SDK はトランスポートへのレスポンスの書き込みをスキップします。それ以外の場合に `null` を返すと、`control_response` が一切送信されず、権限プロンプトはタイムアウトしないため、ツール呼び出しが無期限にブロックされたままになります。

1346 1349 

1347`requestId` オプションと `null` の戻り値には、Claude Code v2.1.199 以降が必要です。1350`requestId` オプションと `null` の戻り値には、Claude Code v2.1.199 以降が必要です。

1348 1351 

1384 1387 

1385| フィールド | 型 | 説明 |1388| フィールド | 型 | 説明 |

1386| :- | :- | :- |1389| :- | :- | :- |

1387| `askUserQuestion.previewFormat` | `'markdown' \| 'html'` | [`AskUserQuestion`](/docs/ja/agent-sdk/user-input#question-format) のオプションで `preview` フィールドを有効にし、そのコンテンツ形式を設定します。未設定の場合、Claude はプレビューを出力しません |1390| `askUserQuestion.previewFormat` | `'markdown' \| 'html'` | [`AskUserQuestion`](/docs/ja/agent-sdk/user-input#question-format) の選択肢で `preview` フィールドを有効にし、そのコンテンツ形式を設定します。未設定の場合、Claude はプレビューを出力しません |

1388 1391 

1389<h3 id="mcpserverconfig">1392<h3 id="mcpserverconfig">

1390 `McpServerConfig`1393 `McpServerConfig`

1478 1481 

1479| フィールド | 型 | 説明 |1482| フィールド | 型 | 説明 |

1480| :- | :- | :- |1483| :- | :- | :- |

1481| `type` | `'local'` | `'local'` である必要があります（現在はローカルプラグインのみサポート） |1484| `type` | `'local'` | `'local'` である必要があります（現在サポートされているのはローカルプラグインのみです） |

1482| `path` | `string` | プラグインディレクトリへの絶対パスまたは相対パス |1485| `path` | `string` | プラグインディレクトリへの絶対パスまたは相対パス |

1483| `skipMcpDiscovery` | `boolean` | `true` の場合、SDK はこのプラグインからスキル、フック、エージェント、コマンドを読み込みますが、`.mcp.json` やマニフェストの `mcpServers` は読み込みません。アプリケーションがプラグインの MCP 接続を管理する場合に設定してください。 |1486| `skipMcpDiscovery` | `boolean` | `true` の場合、SDK はこのプラグインからスキル、フック、エージェント、コマンドを読み込みますが、その `.mcp.json` やマニフェストの `mcpServers` は読み込みません。アプリケーションがプラグインの MCP 接続を管理する場合に設定します。 |

1484 1487 

1485**例：**1488**例：**

1486 1489 

3788};3791};

3789```3792```

3790 3793 

3791コードレビューの検出結果を構造化リストとしてレポートするため、Claude Code はテキストとして出力する代わりにレンダリングできます。`level` はレビューが実行された努力レベルです。検出結果は最も重大度の高い順に並べられ、呼び出しごとに最大 32 個で、配列は何も生き残らなかった場合は空です。Claude Code v2.1.196 以降が必要です。3794コードレビューの検出結果を構造化リストとしてレポートするため、Claude Code はテキストとして出力する代わりにレンダリングできます。検出結果は最も重大度の高い順に並べられ、呼び出しごとに最大 32 個で、配列は何も生き残らなかった場合は空です。Claude Code v2.1.196 以降が必要です。

3795 

3796`level` はオプションで、Claude がレビューについて報告する effort レベルを保持します。Claude Code はこれをレビューが実際に実行されたレベルと比較しないため、両者が異なる場合があります。

3792 3797 

3793各検出結果には以下のフィールドが含まれます：3798各検出結果には以下のフィールドが含まれます：

3794 3799 

4838};4843};

4839```4844```

4840 4845 

4841報告された検出結果の数、レビューが実行された努力レベル、および結果本体のためにエコーバックされた検出結果を返します。Claude Code v2.1.196 以降が必要です。エコーバックされた `short_summary` フィールドは Claude Code v2.1.212 以降が必要です。4846報告された検出結果の数、Claude が渡した `level` 値、および結果本体のためにエコーバックされた検出結果を返します。Claude Code v2.1.196 以降が必要です。エコーバックされた `short_summary` フィールドは Claude Code v2.1.212 以降が必要です。

4842 4847 

4843<h3 id="artifact-2">4848<h3 id="artifact-2">

4844 Artifact4849 Artifact

5459 | { type: "disabled" }; // No extended thinking5464 | { type: "disabled" }; // No extended thinking

5460```5465```

5461 5466 

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` ブロックを返します。5467オプションの `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 5468 

5464<h3 id="spawnedprocess">5469<h3 id="spawnedprocess">

5465 `SpawnedProcess`5470 `SpawnedProcess`

5530 5535 

5531`setMcpServers()` を呼び出すと、Claude Code は以下のルールを適用します。5536`setMcpServers()` を呼び出すと、Claude Code は以下のルールを適用します。

5532 5537 

5533* **呼び出しが名前を付けないサーバー**: Claude Code はプラグイン提供サーバーを実行し続けます。Agent SDK v0.3.210 以降が必要です。5538* **呼び出しが名前を付けないサーバー**: [クラウドセッション](/docs/ja/claude-code-on-the-web)以外では、Claude Code は以前の `setMcpServers()` 呼び出しが追加したサーバーとインプロセス SDK サーバーを切断し、それらを `removed` にリストします。その他のサーバーは実行を続け、`removed` にはリストされません。これには [`mcpServers`](#options) オプションからの stdio、HTTP、SSE サーバー、設定ファイルからのサーバー、プラグイン提供サーバーが含まれます。

5534* **呼び出しが名前を付けるサーバー**: CLI が起動時に開始した組み込みサーバーを除き、Claude Code は実行中のサーバーを、渡した設定と異なる場合にのみ置き換えます。5539* **呼び出しが名前を付けるサーバー**: Claude Code は、以前の `setMcpServers()` 呼び出しが追加した stdio、HTTP、または SSE サーバーを、その設定が渡したものと異なる場合にのみ置き換えます。その名前ですでに登録されているインプロセス SDK サーバーはそのまま残るため、入れ替えるには、ある呼び出しからそれを除外し、次の呼び出しで追加してください。

5535* **CLI が起動時に開始した組み込みサーバー**: 呼び出しが 1 つを名前付けする場合、Claude Code はそのエントリをドロップし、`errors` で報告します。5540* **CLI が起動時に開始した組み込みサーバー**: 呼び出しが 1 つを名前付けする場合、Claude Code はそのエントリをドロップし、`errors` で報告します。

5536 5541 

5537新しく追加された stdio、HTTP、SSE サーバーが接続または失敗した後、プロミスが解決されるため、接続されたサーバーからのツールは次のターンで利用可能です。5542新しく追加された stdio、HTTP、SSE サーバーが接続または失敗した後、プロミスが解決されるため、接続されたサーバーからのツールは次のターンで利用可能です。

5851 tasks: {5856 tasks: {

5852 task_id: string;5857 task_id: string;

5853 task_type: string;5858 task_type: string;

5859 subagent_type?: string;

5854 description: string;5860 description: string;

5855 ambient?: boolean;5861 ambient?: boolean;

5856 }[];5862 }[];

5859};5865};

5860```5866```

5861 5867 

5868`subagent_type` は、[`task_type`](#sdktaskstartedmessage) が `"local_agent"` のエントリで、サブエージェントタイプ（`general-purpose` やカスタムサブエージェントの名前など）に名前を付けます。フィールドには Agent SDK v0.3.293 以降が必要です。

5869 

5862<h3 id="sdkthinkingtokensmessage">5870<h3 id="sdkthinkingtokensmessage">

5863 `SDKThinkingTokensMessage`5871 `SDKThinkingTokensMessage`

5864</h3>5872</h3>

819| `claude rm <id> --discard-unpushed <commit>@<worktree-id>` | プッシュされていないコミットで削除が拒否されたセッションを削除し、worktree をそのブランチとコミットとともに破棄します。拒否が出力した正確な値を渡します。[セッションの削除で何が削除されるか](#what-deleting-a-session-removes)を参照してください。v2.1.260 以降が必要です |819| `claude rm <id> --discard-unpushed <commit>@<worktree-id>` | プッシュされていないコミットで削除が拒否されたセッションを削除し、worktree をそのブランチとコミットとともに破棄します。拒否が出力した正確な値を渡します。[セッションの削除で何が削除されるか](#what-deleting-a-session-removes)を参照してください。v2.1.260 以降が必要です |

820| `claude rm <id> --force-remove-worktree <worktree-id>` | git または `WorktreeRemove` フックが worktree を削除できなかったために削除が拒否されたセッションを削除し、worktree ディレクトリを削除してそのブランチをリポジトリに残します。拒否が出力した正確な値を渡します。[セッションの削除で何が削除されるか](#what-deleting-a-session-removes)を参照してください。v2.1.268 以降が必要です |820| `claude rm <id> --force-remove-worktree <worktree-id>` | git または `WorktreeRemove` フックが worktree を削除できなかったために削除が拒否されたセッションを削除し、worktree ディレクトリを削除してそのブランチをリポジトリに残します。拒否が出力した正確な値を渡します。[セッションの削除で何が削除されるか](#what-deleting-a-session-removes)を参照してください。v2.1.268 以降が必要です |

821| `claude daemon status` | [supervisor](#the-supervisor-process) の状態、バージョン、ソケットディレクトリ、およびワーカー数を出力する |821| `claude daemon status` | [supervisor](#the-supervisor-process) の状態、バージョン、ソケットディレクトリ、およびワーカー数を出力する |

822| `claude daemon logs` | supervisor のログファイル [`~/.claude/daemon.log`](#where-state-is-stored) を追跡し、`Ctrl+C` を押すまで新しい行を到着次第出力する |

822| `claude daemon stop --any` | supervisor プロセスとそれがホストするバックグラウンドセッションを停止します。`--keep-workers` を渡して、バックグラウンドセッションを実行したままにして、次の supervisor が再接続できるようにします。次の `claude agents` または `claude --bg` は新しい supervisor を開始します |823| `claude daemon stop --any` | supervisor プロセスとそれがホストするバックグラウンドセッションを停止します。`--keep-workers` を渡して、バックグラウンドセッションを実行したままにして、次の supervisor が再接続できるようにします。次の `claude agents` または `claude --bg` は新しい supervisor を開始します |

823 824 

824`claude attach` と `claude logs` は、`claude logs "auth refactor"` のように、ID の代わりに実行中のセッション名の一部を受け取ることができます。名前を渡すには Claude Code v2.1.290 以降が必要です。825`claude attach` と `claude logs` は、`claude logs "auth refactor"` のように、ID の代わりに実行中のセッション名の一部を受け取ることができます。名前を渡すには Claude Code v2.1.290 以降が必要です。

20 20 

21この作業をサポートする 3 つの追加ツールがありますが、エージェント自体を実行する方法ではありません。21この作業をサポートする 3 つの追加ツールがありますが、エージェント自体を実行する方法ではありません。

22 22 

23* [ワークツリー](/docs/ja/worktrees) は各セッションに個別の git チェックアウトを提供するため、並列セッションが同じファイルを編集することはありません。自分で実行するセッションに使用します。エージェントビューからディスパッチされたセッションは、[ファイルを編集する前に独自のワークツリーに移動](/docs/ja/agent-view#how-file-edits-are-isolated) し、スポーンするサブエージェントも各々独自のワークツリーを取得できます。23* [Worktree](/docs/ja/worktrees) は各セッションに個別の git チェックアウトを提供するため、並列セッションはそれぞれ自分のファイルのコピーを編集します。自分で実行するセッションに使用します。エージェントビューからディスパッチしたセッションは、[ファイルを編集する前に専用の worktree に移動](/docs/ja/agent-view#how-file-edits-are-isolated) し、スポーンするサブエージェントもそれぞれ worktree を取得できます。

24* [クロスセッションメッセージング](/docs/ja/cross-session-messaging) により、Claude はこのマシン上、別のマシン上、または [クラウド](/docs/ja/claude-code-on-the-web) 上の他の Claude Code セッションをリストして、メッセージを送信できます。自分で実行するセッションは、検出結果とステータスを相互に渡すことができます。24* [クロスセッションメッセージング](/docs/ja/cross-session-messaging) により、Claude はこのマシン上、別のマシン上、または [クラウド](/docs/ja/claude-code-on-the-web) 上の他の Claude Code セッションをリストして、メッセージを送信できます。自分で実行するセッションは、検出結果とステータスを相互に渡すことができます。

25* [`/batch`](/docs/ja/commands) は、1 つの大きな変更を 5 ～ 30 個のワークツリー分離サブエージェントに分割する [skill](/docs/ja/skills) です。これはサブエージェントとワークツリーのパッケージ化された使用法であり、別の調整スタイルではありません。25* [`/batch`](/docs/ja/commands) は、1 つの大きな変更を 5 ～ 30 個のワークツリー分離サブエージェントに分割する [skill](/docs/ja/skills) です。これはサブエージェントとワークツリーのパッケージ化された使用法であり、別の調整スタイルではありません。

26 26 

188 188 

189キャッシュは上記のすべての認証情報オプションをカバーしていますが、Amazon Bedrock API キーはプロバイダーチェーンを使用しないため除外されます。代わりにすべてのリクエストでチェーンを解決するには、[`CLAUDE_CODE_SKIP_AWS_CRED_CACHE=1`](/docs/ja/env-vars) を設定してください。189キャッシュは上記のすべての認証情報オプションをカバーしていますが、Amazon Bedrock API キーはプロバイダーチェーンを使用しないため除外されます。代わりにすべてのリクエストでチェーンを解決するには、[`CLAUDE_CODE_SKIP_AWS_CRED_CACHE=1`](/docs/ja/env-vars) を設定してください。

190 190 

191チェーンの各解決は 60 秒後にタイムアウトします。チェーン内のステップが停止した場合（例えば、受け取ることができない入力を待つ `credential_process` ヘルパー）、リクエストは [`AWS default-chain credential resolve timed out`](/docs/ja/errors#aws-default-chain-credential-resolve-timed-out) で失敗します。チェーンが正当に長い時間が必要なインタラクティブサインイン（`aws-vault` のようなラッパーを使用した MFA 付きブラウザベースの SSO など）を実行する場合、[`CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS`](/docs/ja/env-vars) でミリ秒単位で制限を引き上げてください。v2.1.207 より前では、停止した認証情報解決はリクエストを無期限に待機させていました。191キャッシュを埋める解決は 60 秒後にタイムアウトします。チェーン内のステップが停止した場合（例えば、受け取ることができない入力を待つ `credential_process` ヘルパー）、リクエストは [`AWS default-chain credential resolve timed out`](/docs/ja/errors#aws-default-chain-credential-resolve-timed-out) で失敗します。チェーンが正当に長い時間を必要とするインタラクティブサインイン（`aws-vault` のようなラッパーを使用した MFA 付きブラウザベースの SSO など）を実行する場合、[`CLAUDE_CODE_AWS_CHAIN_RESOLVE_TIMEOUT_MS`](/docs/ja/env-vars) でミリ秒単位で制限を引き上げてください。`CLAUDE_CODE_SKIP_AWS_CRED_CACHE=1` を設定している場合、各 API リクエストはこの制限なしでチェーンを解決します。

192 192 

193Amazon Bedrock API キーで認証する場合を除き、[セットアップウィザード](#sign-in-with-bedrock)は認証情報を検証する際に行う各 AWS 呼び出しに同じ制限を適用し、各モデルチェック前の認証情報ルックアップにも適用します。認証情報検証中に、制限を超えるチェックは [`Timed out after 60s waiting for AWS`](/docs/ja/errors#bedrock-setup-verification-timed-out-waiting-for-aws) で失敗します。193Amazon Bedrock API キーで認証する場合を除き、[セットアップウィザード](#sign-in-with-bedrock)は認証情報を検証する際に行う各 AWS 呼び出しに同じ制限を適用し、各モデルチェック前の認証情報ルックアップにも適用します。認証情報検証中に、制限を超えるチェックは [`Timed out after 60s waiting for AWS`](/docs/ja/errors#bedrock-setup-verification-timed-out-waiting-for-aws) で失敗します。

194 194 

682 682 

683Amazon Bedrock は `InvokeModelWithResponseStream` レスポンスをバイナリイベントストリーム形式でストリーミングし、ヘッダー `Content-Type: application/vnd.amazon.eventstream` を含みます。Claude Code と Amazon Bedrock の間のゲートウェイまたはプロキシは、Amazon Bedrock が送信したレスポンスボディとそのヘッダー（`Content-Type` を含む）を変更されずに転送する必要があります。683Amazon Bedrock は `InvokeModelWithResponseStream` レスポンスをバイナリイベントストリーム形式でストリーミングし、ヘッダー `Content-Type: application/vnd.amazon.eventstream` を含みます。Claude Code と Amazon Bedrock の間のゲートウェイまたはプロキシは、Amazon Bedrock が送信したレスポンスボディとそのヘッダー（`Content-Type` を含む）を変更されずに転送する必要があります。

684 684 

685ゲートウェイが `Content-Type` を別の値に書き換える場合、Claude Code は `Bedrock streaming response has content-type` で始まるエラーでレスポンスを拒否し、受け取った値を名前付けます。一般的な書き換えは `text/event-stream` で、ストリームをサーバー送信イベントとして再発行する統合からのものです。685ゲートウェイが `Content-Type` を別の値に書き換える場合、Claude Code は `Bedrock streaming response has content-type` で始まるエラーでレスポンスを拒否し、受け取った値を名前付けます。一般的な書き換えは `text/event-stream` で、ストリームをサーバー送信イベントとして再発行する統合からのものです。エラーメッセージに示される `CLAUDE_CODE_DISABLE_BEDROCK_CONTENT_TYPE_GUARD` 変数については、[Bedrock streaming response has an unexpected content-type](/docs/ja/errors#bedrock-streaming-response-has-an-unexpected-content-type) を参照してください。

686 686 

687ゲートウェイがヘッダーをドロップまたは空白にする代わりに、Claude Code は本体が Amazon Bedrock のイベントストリームであると仮定してデコードするため、ゲートウェイが変更されずに通した本体はストリーミングを続けます。687ゲートウェイがヘッダーをドロップまたは空白にする代わりに、Claude Code は本体が Amazon Bedrock のイベントストリームであると仮定してデコードするため、ゲートウェイが変更されずに通した本体はストリーミングを続けます。

688 688 

12 Claude Code にログインする12 Claude Code にログインする

13</h2>13</h2>

14 14 

15[Claude Code をインストール](/docs/ja/setup#install-claude-code)した後、ターミナルで `claude` を実行します。初回起動時に、Claude Code はログインするためのブラウザウィンドウを開きます。`ANTHROPIC_API_KEY` 環境変数を設定している場合、Claude Code はログインプロンプトをスキップし、代わりにキーを承認するよう求めます。15[Claude Code をインストール](/docs/ja/setup#install-claude-code)した後、ターミナルで `claude` を実行します。初回起動時に、Claude Code はログインするためのブラウザウィンドウを開きます。`ANTHROPIC_API_KEY` 環境変数を設定していて、そのキーを使用するかどうかを Claude Code に尋ねられたときにキーを承認した場合、Claude Code はログインプロンプトをスキップします。

16 16 

17ブラウザが自動的に開かない場合は、`c` を押してログイン URL をクリップボードにコピーし、ブラウザに貼り付けます。17ブラウザが自動的に開かない場合は、`c` を押してログイン URL をクリップボードにコピーし、ブラウザに貼り付けます。

18 18 

351}351}

352```352```

353 353 

354カスタム `allow`、`soft_deny`、`hard_deny` ルールについて AI からのフィードバックを取得します：354カスタムの `allow`、`soft_deny`、`hard_deny`、`environment` エントリについて AI からのフィードバックを取得します：

355 355 

356```bash theme={null}356```bash theme={null}

357claude auto-mode critique357claude auto-mode critique

343 343 

344| エラー | 原因 | 修正 |344| エラー | 原因 | 修正 |

345| - | - | - |345| - | - | - |

346| "Browser extension is not connected" | ネイティブメッセージングホストが拡張機能に到達できない、または組織の IP 許可リストが `bridge.claudeusercontent.com` への接続を拒否している | Chrome と Claude Code を再起動してから、`/chrome` を実行して再接続します。組織が IP 許可リストを使用しており、エラーが解決しない場合は、[組織の IP 許可リストとプロキシのエグレス](/docs/ja/network-config#organization-ip-allowlists-and-proxy-egress)を参照してください |346| "Browser extension is not connected" | ネイティブメッセージングホストが拡張機能に到達できない、または組織の IP 許可リストが `bridge.claudeusercontent.com` への接続を拒否している | 拡張機能が Claude Code と同じ claude.ai アカウントにサインインしていることを確認し、Chrome と Claude Code を再起動してから、`/chrome` を実行して再接続します。組織が IP 許可リストを使用しており、エラーが解決しない場合は、[組織の IP 許可リストとプロキシのエグレス](/docs/ja/network-config#organization-ip-allowlists-and-proxy-egress)を参照してください |

347| `/chrome` で拡張機能に「Not detected」と表示される | Chrome 拡張機能がインストールされていないか、無効になっている | `chrome://extensions` で拡張機能をインストールまたは有効にします |347| `/chrome` で拡張機能に「Not detected」と表示される | Chrome 拡張機能がインストールされていないか、無効になっている | `chrome://extensions` で拡張機能をインストールまたは有効にします |

348| "No tab available" | Claude がタブの準備ができる前に動作しようとした | Claude に新しいタブを作成して再度試すよう依頼します |348| "No tab available" | Claude がタブの準備ができる前に動作しようとした | Claude に新しいタブを作成して再度試すよう依頼します |

349| "Receiving end does not exist" | 拡張機能サービスワーカーがアイドル状態になった | `/chrome` を実行して「Reconnect extension」を選択します |349| "Receiving end does not exist" | 拡張機能サービスワーカーがアイドル状態になった | `/chrome` を実行して「Reconnect extension」を選択します |

75| - | - |75| - | - |

76| Claude Code v2.1.195 以降 | `claude gateway` サブコマンドとゲートウェイサインインフローは v2.1.195 で提供されます。以前のパブリックビルドには含まれていません。ゲートウェイサーバーを実行するマシンと各開発者のマシンの両方が v2.1.195 以降である必要があります。`claude update` を実行して最新リリースを取得します。[Claude Platform on AWS アップストリーム](/docs/ja/claude-apps-gateway-config#claude-platform-on-aws)はゲートウェイサーバーで Claude Code v2.1.198 以降が必要です。 |76| Claude Code v2.1.195 以降 | `claude gateway` サブコマンドとゲートウェイサインインフローは v2.1.195 で提供されます。以前のパブリックビルドには含まれていません。ゲートウェイサーバーを実行するマシンと各開発者のマシンの両方が v2.1.195 以降である必要があります。`claude update` を実行して最新リリースを取得します。[Claude Platform on AWS アップストリーム](/docs/ja/claude-apps-gateway-config#claude-platform-on-aws)はゲートウェイサーバーで Claude Code v2.1.198 以降が必要です。 |

77| OpenID Connect（OIDC）ID プロバイダー | Okta、Microsoft Entra ID、Google Workspace、Keycloak、Dex、または PingFederate などの OIDC 準拠の IdP。ゲートウェイは標準 OIDC ディスカバリーと認可コードフローを実行します。SAML と LDAP はサポートされていません。 |77| OpenID Connect（OIDC）ID プロバイダー | Okta、Microsoft Entra ID、Google Workspace、Keycloak、Dex、または PingFederate などの OIDC 準拠の IdP。ゲートウェイは標準 OIDC ディスカバリーと認可コードフローを実行します。SAML と LDAP はサポートされていません。 |

78| PostgreSQL 14 以降 | デバイスサインインフロー（ブラウザコールバックが書き込み、ポーリング CLI が読み取る）とレート制限カウンターをサポートします。最小層を含む任意の管理 Postgres が機能します。支出制限が設定されていない場合、ゲートウェイは数 KB の短期間有効な認証状態を保存します。[支出制限](/docs/ja/claude-apps-gateway-spend-limits)を使用すると、バックアップする必要がある耐久的な支出、監査、およびアイデンティティテーブルも保持します。`?sslmode=require` 経由の TLS が推奨されます。 |78| PostgreSQL 11 以降 | デバイスサインインフローとレート制限カウンターをサポートします。最小層を含むマネージド PostgreSQL サービスが利用できます。[サポートされているデータベース](/docs/ja/claude-apps-gateway-deploy#postgres)を参照してください。[支出制限](/docs/ja/claude-apps-gateway-spend-limits)を使用すると、バックアップする必要がある耐久的な支出、監査、およびアイデンティティテーブルも保持します。`?sslmode=require` 経由の TLS が推奨されます。PostgreSQL 11、12、13 には、ゲートウェイサーバーで Claude Code v2.1.290 以降が必要です。PostgreSQL プロジェクトはこれらのバージョンの保守を終了しているため、可能な場合は新しいバージョンを使用してください。 |

79| モデルアップストリーム | Amazon Bedrock 認証情報、Claude Platform on AWS 認証情報、Google Cloud 認証情報、Microsoft Foundry リソース、または Anthropic API キー。複数のアップストリームがサポートされ、フェイルオーバーがあります。 |79| モデルアップストリーム | Amazon Bedrock 認証情報、Claude Platform on AWS 認証情報、Google Cloud 認証情報、Microsoft Foundry リソース、または Anthropic API キー。複数のアップストリームがサポートされ、フェイルオーバーがあります。 |

80| HTTPS | ゲートウェイは開発者ラップトップとサインインに使用されるブラウザから `https://` 経由で到達可能である必要があります。ゲートウェイは同じリスナーでデバイス検証ページを提供します。`listen.tls` 経由で TLS 証明書を提供するか、TLS 終了イングレスの背後で実行し、`listen.public_url` を外部オリジンに設定します。プレーン `http://` オリジンはゲートウェイホストがループバック（`localhost`、`127.0.0.1`、または `::1`）の場合にのみ受け入れられます。 |80| HTTPS | ゲートウェイは開発者ラップトップとサインインに使用されるブラウザから `https://` 経由で到達可能である必要があります。ゲートウェイは同じリスナーでデバイス検証ページを提供します。`listen.tls` 経由で TLS 証明書を提供するか、TLS 終了イングレスの背後で実行し、いずれの場合も `listen.public_url` を外部オリジンに設定します。`/login` では、Claude Code はゲートウェイホストがループバック（`localhost`、`127.0.0.1`、または `::1`）の場合にのみプレーン `http://` オリジンを受け入れます。 |

81| プライベートネットワークアドレス | `/login` では、Claude Code はゲートウェイのホスト名または IP アドレスがプライベートアドレスのみに解決されることを要求します。RFC 1918、リンクローカル、CGNAT `100.64.0.0/10`、IPv6 ULA `fc00::/7`、またはループバック。ホストするゲートウェイの場合、宣言するブロック外のパブリックアドレスは拒否されます。デプロイメントガイドの[脅威モデル](/docs/ja/claude-apps-gateway-deploy#threat-model-summary)を参照してください。開発者マシンが HTTPS を企業プロキシ経由でルーティングする場合、サインインはプロキシホストもプライベートアドレスに解決されることを要求します。そうでない場合は、ゲートウェイホストを `NO_PROXY` に追加して、CLI が直接接続するようにします。内部ネットワークが組織が所有するパブリック IPv4 スペースから番号付けされている場合は、[これらのブロックを宣言](#allow-a-gateway-on-public-address-space-you-own)して、`/login` がそこでゲートウェイを受け入れるようにします。 |81| プライベートネットワークアドレス | `/login` では、Claude Code はゲートウェイのホスト名または IP アドレスがプライベートアドレスのみに解決されることを要求します。RFC 1918、リンクローカル、CGNAT `100.64.0.0/10`、IPv6 ULA `fc00::/7`、またはループバック。ホストするゲートウェイの場合、宣言するブロック外のパブリックアドレスは拒否されます。デプロイガイドの[脅威モデル](/docs/ja/claude-apps-gateway-deploy#threat-model-summary)を参照してください。開発者マシンが HTTPS を企業プロキシ経由でルーティングする場合、サインインはプロキシホストもプライベートアドレスに解決されることを要求します。そうでない場合は、ゲートウェイホストを `NO_PROXY` に追加して、CLI が直接接続するようにします。内部ネットワークが組織が所有するパブリック IPv4 スペースから番号付けされている場合は、[これらのブロックを宣言](#allow-a-gateway-on-public-address-space-you-own)して、`/login` がそこでゲートウェイを受け入れるようにします。 |

82| Linux ランタイム | ゲートウェイサーバーはネイティブ Linux バイナリでのみ実行されます。macOS はローカル開発用に機能します。Windows はサーバープラットフォームとしてサポートされていません。 |82| Linux ランタイム | ゲートウェイサーバーはネイティブ Linux バイナリでのみ実行されます。macOS はローカル開発用に機能します。Windows はサーバープラットフォームとしてサポートされていません。 |

83 83 

84<h3 id="steps">84<h3 id="steps">

91 </Step>91 </Step>

92 92 

93 <Step title="PostgreSQL データベースをプロビジョニングする">93 <Step title="PostgreSQL データベースをプロビジョニングする">

94 最小管理層を含む任意の Postgres 14 以降が機能します。ゲートウェイは起動時に独自のスキーママイグレーションを実行するため、データベースロールはテーブルを作成および変更する権限が必要です。[`store`](/docs/ja/claude-apps-gateway-config#store)を参照してください。94 PostgreSQL 11 以降を使用します。最小のマネージド層で十分です。ゲートウェイは起動時に独自のスキーママイグレーションを実行するため、データベースロールはテーブルを作成および変更する権限が必要です。[`store`](/docs/ja/claude-apps-gateway-config#store)を参照してください。

95 </Step>95 </Step>

96 96 

97 <Step title="gateway.yaml を書く">97 <Step title="gateway.yaml を書く">

142 </Step>142 </Step>

143 143 

144 <Step title="実行する">144 <Step title="実行する">

145 [イメージ要件](/docs/ja/claude-apps-gateway-deploy#container-image)を満たす `claude` バイナリの周りにコンテナイメージを構築し、Postgres と一緒に実行します。Compose ファイルはイメージを `registry.example.com/claude-gateway:2.1.198` として参照します。独自のレジストリとイメージタグに置き換えます。145 [イメージ要件](/docs/ja/claude-apps-gateway-deploy#container-image)を満たす `claude` バイナリの周りにコンテナイメージをビルドし、Postgres と一緒に実行します。Compose ファイルはイメージを `registry.example.com/claude-gateway:2.1.198` として参照します。独自のレジストリとイメージタグに置き換えます。

146 146 

147 ```yaml docker-compose.yaml theme={null}147 ```yaml docker-compose.yaml theme={null}

148 services:148 services:

172 volumes: { pgdata: }172 volumes: { pgdata: }

173 ```173 ```

174 174 

175 ゲートウェイは、設定を読み取り、Postgres に接続してスキーママイグレーションを適用し、IdP に対して OIDC ディスカバリーを実行し、アップストリームクライアントを構築し、リッスンを開始する単一の Linux バイナリです。起動は設定、Postgres 接続、OIDC ディスカバリー、およびアップストリームクライアント構築に対して失敗時に閉じられます。これらのいずれかが到達不可能または設定が誤っている場合、ゲートウェイは低下した状態でトラフィックを提供するのではなく、エラーで終了します。175 ゲートウェイは、設定を読み取り、Postgres に接続してスキーママイグレーションを適用し、IdP に対して OIDC ディスカバリーを実行し、アップストリームクライアントを構築し、リッスンを開始する単一の Linux バイナリです。

176 

177 起動は設定、Postgres 接続、OIDC ディスカバリー、およびアップストリームクライアント構築に対して失敗時に閉じられます。これらのいずれかが到達不可能または設定が誤っている場合、ゲートウェイは低下した状態でトラフィックを提供するのではなく、エラーで終了します。

176 178 

177 成功した起動は推論パスを検証しません。Amazon Bedrock と Google Cloud の Agent Platform インスタンス認証情報は起動時ではなく最初のリクエストで解決されるためです。179 成功した起動は推論パスを検証しません。Amazon Bedrock と Google Cloud の Agent Platform インスタンス認証情報は起動時ではなく最初のリクエストで解決されるためです。

178 180 

187 [gateway] 2026-06-10T17:03:21.512Z info claude gateway listening on http://0.0.0.0:8080189 [gateway] 2026-06-10T17:03:21.512Z info claude gateway listening on http://0.0.0.0:8080

188 ```190 ```

189 191 

190 ゲートウェイは、`access_control.allow_cidrs` が空であることを示す警告もログに記録します。これはここで予想されています。ゲートウェイがサーブするクライアントアドレスを制限するものがないためです。許可リストを設定するまで。[`access_control` リファレンス](/docs/ja/claude-apps-gateway-config#http-tuning)には推奨範囲があります。192 ゲートウェイは、`access_control.allow_cidrs` が空であることを示す警告もログに記録します。これはここでは想定どおりです。許可リストを設定するまで、ゲートウェイがサーブするクライアントアドレスを制限するものがないためです。[`access_control` リファレンス](/docs/ja/claude-apps-gateway-config#http-tuning)には推奨範囲があります。

191 193 

192 起動が `claude gateway listening on` 行の前に終了する場合、stderr の最後の行は問題を名前付けます。194 起動が `claude gateway listening on` 行の前に終了する場合、stderr の最後の行は問題を名前付けます。

193 195 

223 }225 }

224 ```226 ```

225 227 

226 応答には `response_types_supported` や `scopes_supported` などの追加フィールドが含まれます。228 レスポンスには `response_types_supported` や `scopes_supported` などの追加フィールドが含まれます。

227 229 

228 次に、デバイス認可をリクエストします。これはデバイスサインインフローが機能し、Postgres が到達可能で書き込み可能であることを確認します。230 次に、デバイス認可をリクエストします。これはデバイスサインインフローが機能し、Postgres が到達可能で書き込み可能であることを確認します。

229 231 

253 </Step>255 </Step>

254 256 

255 <Step title="開発者をログインさせる">257 <Step title="開発者をログインさせる">

256 この最後のステップはサーバーではなく開発者マシンで発生します。そのマシンの[管理設定ファイル](/docs/ja/managed-settings#delivery-mechanisms)で `forceLoginMethod` を `"gateway"` に、`forceLoginGatewayUrl` をゲートウェイの `public_url` に設定し、`/login` を実行し、**Cloud gateway** 画面で Enter キーを押し、ブラウザサインインを完了します。以下の[ゲートウェイ URL を設定](#set-the-gateway-url)は、スケール時に両方のキーを配布することをカバーしています。258 この最後のステップはサーバーではなく開発者マシンで発生します。そのマシンの[管理設定ファイル](/docs/ja/managed-settings#delivery-mechanisms)で `forceLoginMethod` を `"gateway"` に、`forceLoginGatewayUrl` をゲートウェイの `public_url` に設定し、`/login` を実行し、**Cloud gateway** 画面で Enter キーを押し、ブラウザサインインを完了します。以下の[ゲートウェイ URL を設定](#set-the-gateway-url)では、両方のキーをすべての開発者マシンに配布する方法を説明しています。

257 </Step>259 </Step>

258</Steps>260</Steps>

259 261 

156ゲートウェイは鍵と証明書をブート時に一度だけ読み込むため、ファイルの変更は再起動後にのみ反映されます。IdP が持っていない証明書をトークンリクエストが提示することがないよう、次の順序でローテーションします：156ゲートウェイは鍵と証明書をブート時に一度だけ読み込むため、ファイルの変更は再起動後にのみ反映されます。IdP が持っていない証明書をトークンリクエストが提示することがないよう、次の順序でローテーションします：

157 157 

1581. 新しい証明書を、古い証明書と並べて IdP にアップロードします。1581. 新しい証明書を、古い証明書と並べて IdP にアップロードします。

1592. `gateway.yaml` が読み込む鍵と証明書のファイルを置き換えてから、ゲートウェイを再起動します。1592. `gateway.yaml` が読み込む鍵と証明書のファイルを置き換えてから、ゲートウェイを再起動します。複数のレプリカを実行している場合は、[ローリング再起動](/docs/ja/claude-apps-gateway-deploy#upgrades)で問題ありません。古い証明書を削除するまで、IdP は両方の証明書を保持しているためです。

1603. 古い証明書を IdP から削除します。1603. すべてのレプリカが再起動した後、古い証明書を IdP から削除します。

161 161 

162<h4 id="idp-requests-through-a-forward-proxy">162<h4 id="idp-requests-through-a-forward-proxy">

163 フォワードプロキシを通じた IdP リクエスト163 フォワードプロキシを通じた IdP リクエスト