Documentation 2026-09-28 22:59 UTC to 2026-09-29 19:01 UTC

111 メニューとプロンプトに答える111 メニューとプロンプトに答える

112</h2>112</h2>

113 113 

114スクリーンリーダーモードでは、通常は矢印キーで操作するメニュー（権限プロンプトを含む）が番号付きリストになります。Claude Code は各オプションを番号付き行として発表し、その後に有効な範囲を示す `Enter selection` プロンプトを発表します。希望するオプションの番号を入力して Enter キーを押します。114スクリーンリーダーモードでは、通常は矢印キーで操作するメニュー（権限プロンプトを含む）が番号付きリストになります。Claude Code は各オプションを番号付き行として発表し、その後に有効な範囲を示す `Select with numbers` プロンプトを発表します。希望するオプションの番号を入力して Enter キーを押します。

115 115 

116* `or Escape to cancel` で終わるプロンプトのメニューをキャンセルするには Escape キーを押します。116* `or Escape to cancel` で終わるプロンプトのメニューをキャンセルするには Escape キーを押します。

117* リストにない番号を入力した場合、Claude Code は有効な範囲を発表し、もう一度試すことができます。117* リストにない番号を入力した場合、Claude Code は有効な範囲を発表し、もう一度試すことができます。

97| :- | :- | :- |97| :- | :- | :- |

98| [権限ルール](/docs/ja/permissions) | 特定のツールとコマンドを許可、確認、または拒否する | `permissions.allow`、`permissions.deny` |98| [権限ルール](/docs/ja/permissions) | 特定のツールとコマンドを許可、確認、または拒否する | `permissions.allow`、`permissions.deny` |

99| [権限ロックダウン](/docs/ja/permissions#managed-only-settings) | マネージド設定を[権限ルールの唯一の設定ソース](/docs/ja/settings-reference#allowmanagedpermissionrulesonly)にします。`--dangerously-skip-permissions` を無効にする | `allowManagedPermissionRulesOnly`、`permissions.disableBypassPermissionsMode` |99| [権限ロックダウン](/docs/ja/permissions#managed-only-settings) | マネージド設定を[権限ルールの唯一の設定ソース](/docs/ja/settings-reference#allowmanagedpermissionrulesonly)にします。`--dangerously-skip-permissions` を無効にする | `allowManagedPermissionRulesOnly`、`permissions.disableBypassPermissionsMode` |

100| [開始権限モード](/docs/ja/permission-modes#which-mode-a-session-starts-in) | 組み込みの開始権限モードの代わりに、開発者のターミナルセッションが開始する権限モードを選択するか、自動モードを削除します。VS Code 拡張機能は、Pro、Max、Team プランでのみ設定した `defaultMode` を読み取ります。[権限モードの切り替え](/docs/ja/permission-modes#switch-permission-modes)は、拡張機能が読み取る内容を一覧表示します | `permissions.defaultMode`、`permissions.disableAutoMode` |100| [開始権限モード](/docs/ja/permission-modes#which-mode-a-session-starts-in) | 組み込みの開始権限モードの代わりに、開発者のターミナルセッションが開始する権限モードを選択するか、自動モードを削除します。[権限モードの切り替え](/docs/ja/permission-modes#switch-permission-modes)は、VS Code 拡張機能が `defaultMode` を読み取る時期を一覧表示します | `permissions.defaultMode`、`permissions.disableAutoMode` |

101| [サンドボックス](/docs/ja/sandboxing) | ドメイン許可リスト付きの OS レベルのファイルシステムとネットワーク分離 | `sandbox.enabled`、`sandbox.network.allowedDomains` |101| [サンドボックス](/docs/ja/sandboxing) | ドメイン許可リスト付きの OS レベルのファイルシステムとネットワーク分離 | `sandbox.enabled`、`sandbox.network.allowedDomains` |

102| [マネージドポリシー CLAUDE.md](/docs/ja/memory#deploy-organization-wide-claude-md) | すべてのセッションで読み込まれる組織全体の指示。除外できません | マネージドポリシーパスのファイル |102| [マネージドポリシー CLAUDE.md](/docs/ja/memory#deploy-organization-wide-claude-md) | すべてのセッションで読み込まれる組織全体の指示。除外できません | マネージドポリシーパスのファイル |

103| [MCP サーバー制御](/docs/ja/managed-mcp) | ユーザーが追加または接続できる MCP サーバーを制限し、固定セットをデプロイするか、リモートサーバーをすべてのユーザーに提供します | `allowedMcpServers`、`deniedMcpServers`、`allowManagedMcpServersOnly`、`managedMcpServers`、またはデプロイされた `managed-mcp.json` ファイル |103| [MCP サーバー制御](/docs/ja/managed-mcp) | ユーザーが追加または接続できる MCP サーバーを制限し、固定セットをデプロイするか、リモートサーバーをすべてのユーザーに提供します | `allowedMcpServers`、`deniedMcpServers`、`allowManagedMcpServersOnly`、`managedMcpServers`、またはデプロイされた `managed-mcp.json` ファイル |

95 アドバイザーモデルを選択する95 アドバイザーモデルを選択する

96</h2>96</h2>

97 97 

98アドバイザーはメインモデル以上の能力を持つ必要があります。各メインモデルで受け入れられるアドバイザーは以下の通りです。98アドバイザーは、メインモデル以上の能力を持つ必要があります。各メインモデルで受け入れられるアドバイザーは以下の通りです。

99 99 

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

101| - | - | - |101| - | - | - |

102| Haiku 4.5 | Fable、Opus、Sonnet | Haiku はアドバイザーを呼び出すことはできますが、アドバイザーとして機能することはできません |102| Haiku 4.5 | Fable、Opus、Sonnet | Haiku はアドバイザーを呼び出すことはできますが、アドバイザーとして機能することはできません |

103| Sonnet 4.6 | Fable、Opus、Sonnet | |103| Sonnet 4.6 | Fable、Opus、Sonnet | |

104| Sonnet 5 | Fable、Opus 4.7 以降、Sonnet 5 | Sonnet 4.6 アドバイザーは拒否され、Opus 4.6 アドバイザーを使用したリクエストは API エラーで失敗します |104| Sonnet 5.5 または Sonnet 5 | Fable、Opus 4.7 以降、Sonnet 5 以降 | Sonnet 4.6 アドバイザーは拒否され、API は Opus 4.6 アドバイザーを拒否します |

105| Opus 4.6 | Fable、Opus、Sonnet 5 | Sonnet 4.6 アドバイザーは拒否されます |105| Opus 4.6 | Fable、Opus、Sonnet 5 以降 | Sonnet 4.6 アドバイザーは拒否されます |

106| Opus 4.7 または Opus 4.8 | Fable、および Opus 4.7 以降 | Opus 4.6 または Sonnet アドバイザーは拒否されます |106| Opus 4.7 または Opus 4.8 | Fable、および Opus 4.7 以降 | Opus 4.6 または Sonnet アドバイザーは拒否されます |

107| Opus 5.5 または Opus 5 | Fable、および Opus 5 以降 | Opus 4.6 または Sonnet アドバイザーは拒否され、API は Opus 4.7 または Opus 4.8 アドバイザーを拒否します |107| Opus 5.5 または Opus 5 | Fable、および Opus 5 以降 | Opus 4.6 または Sonnet アドバイザーは拒否され、API は Opus 4.7 または Opus 4.8 アドバイザーを拒否します |

108| Fable 5 | Fable 5.1 または Fable 5 | Opus または Sonnet アドバイザーは拒否されます |108| Fable 5 | Fable 5.1 または Fable 5 | Opus または Sonnet アドバイザーは拒否されます |

109| Fable 5.1 | Fable 5.1 | Opus または Sonnet アドバイザーは拒否され、Fable 5 アドバイザーを使用したリクエストは API エラーで失敗します |109| Fable 5.1 | Fable 5.1 | Opus または Sonnet アドバイザーは拒否され、API は Fable 5 アドバイザーを拒否します |

110 110 

111Fable 5.1 には Claude Code v2.1.257 以降が必要です。両方の Fable モデルには [Fable アクセス](/docs/ja/model-config#work-with-fable) が必要です。111Fable 5.1 には Claude Code v2.1.257 以降が必要です。両方の Fable モデルには [Fable アクセス](/docs/ja/model-config#work-with-fable) が必要です。

112 112 

114 114 

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

116 116 

117Claude Code はリクエストを送信する前にペアリングを検証し、API が再度検証します。117Claude Code はリクエストを送信する前にペアリングを検証し、API も再度検証します。

118 118 

119* テーブルで拒否されたアドバイザーの場合、Claude Code はそれをメインモデルのリクエストに添付しません。`/advisor` コマンド出力と通知がこれを表示します。独自のモデルがペアリングを満たすサブエージェントは、引き続きアドバイザーを使用できます。119* テーブルで拒否されたアドバイザーの場合、Claude Code はそれをメインモデルのリクエストに添付しません。`/advisor` コマンド出力と通知がこれを表示します。独自のモデルがペアリングを満たすサブエージェントは、引き続きアドバイザーを使用できます。

120* テーブルで API エラーで失敗するとリストされているアドバイザーの場合、Claude Code はそれを添付し、API がそれを拒否します。Claude Code はその後、アドバイザーなしでそのリクエストを再送信し、残りの会話はアドバイザーなしで実行されるため、エラーが表示されず、アドバイザー呼び出しが行われません。`/advisor` で受け入れられたアドバイザーを選択してください。変更は `/clear` または `/compact` の後と新しいセッションで有効になります。120* テーブルで API によって拒否されたアドバイザーの場合、Claude Code はそれを添付し、API がそれを拒否します。Claude Code はその後、アドバイザーなしでそのリクエストを再送信し、会話の残りはアドバイザーなしで実行されるため、エラーが表示されず、アドバイザー呼び出しが行われません。`/advisor` で受け入れられたアドバイザーを選択してください。変更は `/clear` または `/compact` の後と新しいセッションで有効になります。

121* メインモデルまたはアドバイザーが Claude Code が認識しないモデルの場合、アドバイザーは添付されません。121* メインモデルまたはアドバイザーが Claude Code が認識しないモデルの場合、アドバイザーは添付されません。

122 122 

123<h3 id="fable-advisor-and-usage-credits">123<h3 id="fable-advisor-and-usage-credits">

124 Fable アドバイザーと使用クレジット124 Fable アドバイザーと使用クレジット

125</h3>125</h3>

126 126 

127一部のプランでは、Fable の使用は使用クレジットに請求され、アドバイザーとしての Fable も同じ方法で請求されます。アカウントが [Fable の使用を使用クレジットに請求するための一度限りの同意](/docs/ja/model-config#fable-and-usage-credits) を必要とする場合、Claude Code は `/model` で Fable モデルを選択するときにそれを要求し、その同意を受け入れるまで Fable をアドバイザーとして適用しません。127一部のプランでは、Fable の使用は使用クレジットに請求され、アドバイザーとしての Fable も同じ方法で請求されます。アカウントが [Fable の使用を使用クレジットに請求するための 1 回限りの同意](/docs/ja/model-config#fable-and-usage-credits) を必要とする場合、Claude Code は `/model` で Fable モデルを選択するときにそれを要求し、その同意を受け入れるまで Fable をアドバイザーとして適用しません。

128 128 

129それを受け入れる前に、Claude Code は `/advisor fable` を入力するか `/advisor` ピッカーで Fable を選択するときに Fable をアドバイザーとして保存しません。代わりに `/model fable` を指すようにします。`claude --advisor fable` を使用すると、Claude Code は `/model fable` を指すメッセージで起動時に終了します。[バックグラウンドセッション](#use-the-advisor-flag) では、終了する代わりにアドバイザーなしでセッションを開始します。Fable が既に `advisorModel` として保存されている場合、Claude Code はアドバイザーなしでリクエストを送信します。アドバイザーをサポートするインタラクティブセッションでは、`/model fable` を指す通知も表示されます。129それを受け入れる前に、Claude Code は `/advisor fable` を入力するか `/advisor` ピッカーで Fable を選択するときに Fable をアドバイザーとして保存しません。代わりに `/model fable` を指します。`claude --advisor fable` を使用すると、Claude Code は起動時に `/model fable` を指すメッセージで終了します。[バックグラウンドセッション](#use-the-advisor-flag) では、終了する代わりにアドバイザーなしでセッションを開始します。Fable が既に `advisorModel` として保存されている場合、Claude Code はアドバイザーなしでリクエストを送信します。メインモデルがアドバイザーをサポートする対話型セッションでは、`/model fable` を指す通知も表示されます。

130 130 

131同意を受け入れるには、`/model fable` を実行し、Fable で続行することを選択します。Claude Code は同意を記録し、[Fable を選択したモデルとして保存](/docs/ja/model-config#default-model-setting) します。次に、Fable をアドバイザーとして選択します。131同意を受け入れるには、`/model fable` を実行し、Fable で続行することを選択します。Claude Code は同意を記録し、[Fable を選択したモデルとして保存します](/docs/ja/model-config#default-model-setting)。その後、Fable をアドバイザーとして選択します。

132 132 

133<h3 id="common-model-pairings">133<h3 id="common-model-pairings">

134 一般的なモデルペアリング134 一般的なモデルペアリング

139| ペアリング | 使用する場合 |139| ペアリング | 使用する場合 |

140| - | - |140| - | - |

141| Sonnet メイン + Opus アドバイザー | Sonnet は日常的な作業を処理し、計画、曖昧な失敗、完了チェックを Opus にエスカレートします |141| Sonnet メイン + Opus アドバイザー | Sonnet は日常的な作業を処理し、計画、曖昧な失敗、完了チェックを Opus にエスカレートします |

142| Sonnet メイン + Fable アドバイザー | 決定ポイントで Fable ガイダンスを取得し、プロセス全体で Fable を実行しません。Fable アクセスが必要です |142| Sonnet メイン + Fable アドバイザー | 全体を通じて Fable を実行することなく、決定ポイントで Fable のガイダンスを取得します。Fable アクセスが必要です |

143| Haiku メイン + Opus アドバイザー | 強力な計画を備えた最も低コストのメインモデル。Haiku 単独よりも高いコストが予想されますが、メインモデルを Sonnet または Opus に切り替えるよりは低くなります |143| Haiku メイン + Opus アドバイザー | 最も低コストのメインモデルと強力な計画。Haiku のみより高いコストが予想されますが、メインモデルを Sonnet または Opus に切り替えるより低くなります |

144| Opus メイン + Opus アドバイザー | 2 番目の Opus が最初の Opus をレビューします。コストよりも独立したチェックが重要な高リスクタスクに役立ちます |144| Opus メイン + Opus アドバイザー | 2 番目の Opus が最初の Opus をレビューします。コストより独立したチェックが重要な高リスクタスクに役立ちます |

145| Fable メイン + Fable アドバイザー | Fable が利用可能な場合の最高能力ペアリング。Claude Code は Fable メインモデルに Opus または Sonnet アドバイザーを適用しません |145| Fable メイン + Fable アドバイザー | Fable が利用可能な場合の最高能力ペアリング。Claude Code は Opus または Sonnet アドバイザーを Fable メインモデルに適用しません |

146| Sonnet メイン + Sonnet アドバイザー | 日常的な見落としをキャッチするための低コストの 2 番目の意見 |146| Sonnet メイン + Sonnet アドバイザー | 日常的な見落としをキャッチするための低コストの 2 番目の意見 |

147 147 

148<h2 id="when-claude-consults-the-advisor">148<h2 id="when-claude-consults-the-advisor">

161 161 

162* **Reviewed**: この行は advisor が会話をレビューしたことを確認します。advisor が読み取り可能なガイダンスを返した場合、`Ctrl+O` を押して読むことができます。162* **Reviewed**: この行は advisor が会話をレビューしたことを確認します。advisor が読み取り可能なガイダンスを返した場合、`Ctrl+O` を押して読むことができます。

163* **Declined**: この行は `Advisor declined to advise on this request` と表示されます。advisor が理由を提供した場合、`Ctrl+O` を押して読むことができます。163* **Declined**: この行は `Advisor declined to advise on this request` と表示されます。advisor が理由を提供した場合、`Ctrl+O` を押して読むことができます。

164* **Unavailable**: advisor の呼び出しが失敗し、この行は `Advisor unavailable (<error_code>)` と表示されます。ここで `<error_code>` は呼び出しが返したコードです。

164 165 

165Claude は一般的に advisor のガイダンスに従いますが、独自の証拠が特定の主張と矛盾する場合は適応します。推奨されたステップが試行時に失敗した場合、またはファイルの内容がアドバイスと矛盾する場合、Claude はガイダンスに無条件に従うのではなく、矛盾を表示します。166Claude は一般的に advisor のガイダンスに従いますが、独自の証拠が特定の主張と矛盾する場合は適応します。推奨されたステップが試行時に失敗した場合、またはファイルの内容がアドバイスと矛盾する場合、Claude はガイダンスに無条件に従うのではなく、矛盾を表示します。

166 167 

129完全なパラメーター詳細（JSON Schema 入力形式と戻り値の構造を含む）については、[`tool()`](/docs/ja/agent-sdk/typescript#tool) TypeScript リファレンスまたは [`@tool`](/docs/ja/agent-sdk/python#tool) Python リファレンスを参照してください。129完全なパラメーター詳細（JSON Schema 入力形式と戻り値の構造を含む）については、[`tool()`](/docs/ja/agent-sdk/typescript#tool) TypeScript リファレンスまたは [`@tool`](/docs/ja/agent-sdk/python#tool) Python リファレンスを参照してください。

130 130 

131<Tip>131<Tip>

132 パラメーターをオプションにするには：TypeScript では、Zod フィールドに `.default()` を追加します。Python では、dict スキーマはすべてのキーを必須として扱うため、パラメーターをスキーマから除外し、説明文字列で言及し、ハンドラーで `args.get()` で読み取ります。以下の [`get_precipitation_chance` ツール](#add-more-tools)は両方のパターンを示しています。132 パラメーターをオプションにするには：TypeScript では、Zod フィールドに `.optional()` を追加し、ハンドラーでデフォルトを適用します。Python では、dict スキーマはすべてのキーを必須として扱うため、パラメーターをスキーマから除外し、説明文字列で言及し、ハンドラーで `args.get()` で読み取ります。以下の [`get_precipitation_chance` ツール](#add-more-tools)は両方のパターンを示しています。

133</Tip>133</Tip>

134 134 

135<h3 id="call-a-custom-tool">135<h3 id="call-a-custom-tool">

248 .int()248 .int()

249 .min(1)249 .min(1)

250 .max(24)250 .max(24)

251 .default(12) // .default() makes the parameter optional251 .optional() // .optional() lets Claude omit the parameter

252 .describe("How many hours of forecast to return")252 .describe("How many hours of forecast to return")

253 },253 },

254 async (args) => {254 async (args) => {

255 const hours = args.hours ?? 12; // Apply the default in the handler

255 const response = await fetch(256 const response = await fetch(

256 `https://api.open-meteo.com/v1/forecast?latitude=${args.latitude}&longitude=${args.longitude}&hourly=precipitation_probability&forecast_days=1`257 `https://api.open-meteo.com/v1/forecast?latitude=${args.latitude}&longitude=${args.longitude}&hourly=precipitation_probability&forecast_days=1`

257 );258 );

258 const data: any = await response.json();259 const data: any = await response.json();

259 const chances = data.hourly.precipitation_probability.slice(0, args.hours);260 const chances = data.hourly.precipitation_probability.slice(0, hours);

260 261 

261 return {262 return {

262 content: [{ type: "text", text: `Next ${args.hours} hours: ${chances.join("%, ")}%` }]263 content: [{ type: "text", text: `Next ${hours} hours: ${chances.join("%, ")}%` }]

263 };264 };

264 }265 }

265 );266 );

469 画像470 画像

470</h3>471</h3>

471 472 

472画像ブロックは、画像バイトをインラインで、base64 としてエンコードされた形式で保持します。URL フィールドはありません。URL に存在する画像を返すには、ハンドラー内でそれをフェッチし、レスポンスバイトを読み取り、返す前に base64 エンコードしてください。結果は視覚入力として処理されます。473画像ブロックは、画像バイトをインラインで、base64 としてエンコードされた形式で保持します。URL フィールドはありません。URL に存在する画像を返すには、ハンドラー内でそれをフェッチし、レスポンスバイトを読み取り、返す前に base64 エンコードしてください。PNG、JPEG、GIF、または WebP 画像は視覚入力として Claude に到達します。他の種類の画像はディスクに保存され、Claude はそのファイルパスをテキストとして受け取ります。

473 474 

474| フィールド | 型 | 注記 |475| フィールド | 型 | 注記 |

475| :- | :- | :- |476| :- | :- | :- |

538 リソース539 リソース

539</h3>540</h3>

540 541 

541リソースブロックは、URI で識別されるコンテンツを埋め込みます。URI はコンテンツの参照用ラベルです。実際のコンテンツはブロックの `text` または `blob` フィールドに含まれます。これは、ツールが後で名前で参照することが理にかなったもの（生成されたファイルや外部システムのレコードなど）を生成する場合に使用します。542リソースブロックは、URI で識別されるコンテンツを埋め込みます。実際のコンテンツはブロックの `text` または `blob` フィールドに含まれます。ツールが生成されたファイルや外部システムのレコードなど、後で名前で参照することが理にかなったものを生成する場合に使用します。

542 543 

543| フィールド | 型 | 注記 |544| フィールド | 型 | 注記 |

544| :- | :- | :- |545| :- | :- | :- |

548| `resource.blob` | `string` | バイナリの場合、base64 エンコードされたコンテンツ。TypeScript のみ：Python SDK はバイナリリソースをツール結果から削除し、警告をログに記録します |549| `resource.blob` | `string` | バイナリの場合、base64 エンコードされたコンテンツ。TypeScript のみ：Python SDK はバイナリリソースをツール結果から削除し、警告をログに記録します |

549| `resource.mimeType` | `string` | オプション |550| `resource.mimeType` | `string` | オプション |

550 551 

551この例は、ツールハンドラー内から返されるリソースブロックを示しています。URI `file:///tmp/report.md` は Claude が後で参照できるラベルです。SDK はそのパスから読み取りません。552この例は、ツールハンドラー内から返されるリソースブロックを示しています。SDK は例の URI `file:///tmp/report.md` から読み取りません。

552 553 

553<CodeGroup>554<CodeGroup>

554 ```typescript TypeScript theme={null}555 ```typescript TypeScript theme={null}

572 {573 {

573 "type": "resource",574 "type": "resource",

574 "resource": {575 "resource": {

575 "uri": "file:///tmp/report.md", # Label for Claude to reference, not a path the SDK reads576 "uri": "file:///tmp/report.md", # Not a path the SDK reads

576 "mimeType": "text/markdown",577 "mimeType": "text/markdown",

577 "text": "# Report\n...", # The actual content, inline578 "text": "# Report\n...", # The actual content, inline

578 },579 },

6 6 

7> 構築したいものに合致する完全で実行可能な Agent SDK プロジェクト、または Claude Cookbook のガイド付きレシピを見つけてください。7> 構築したいものに合致する完全で実行可能な Agent SDK プロジェクト、または Claude Cookbook のガイド付きレシピを見つけてください。

8 8 

9このページは、完全で実行可能な Agent SDK プロジェクトとガイド付き Claude Cookbook レシピへのルートを提供します。TypeScript アプリケーションは [`claude-agent-sdk-demos`](https://github.com/anthropics/claude-agent-sdk-demos) リポジトリに、Python レシピは [Claude Cookbook](https://platform.claude.com/cookbook) に存在します。9このページは、完全で実行可能な Agent SDK プロジェクトとガイド付き Claude Cookbook レシピへのルートを提供します。アプリケーションは [`claude-agent-sdk-demos`](https://github.com/anthropics/claude-agent-sdk-demos) リポジトリに、Python レシピは [Claude Cookbook](https://platform.claude.com/cookbook) に存在します。

10 10 

11<h2 id="run-a-minimal-agent-first">11<h2 id="run-a-minimal-agent-first">

12 まず最小限のエージェントを実行する12 まず最小限のエージェントを実行する

18 18 

19* [Hello World](https://github.com/anthropics/claude-agent-sdk-demos/tree/main/hello-world)：リポジトリコードから開始したい場合にクローンする最小限の TypeScript プロジェクト19* [Hello World](https://github.com/anthropics/claude-agent-sdk-demos/tree/main/hello-world)：リポジトリコードから開始したい場合にクローンする最小限の TypeScript プロジェクト

20 20 

21<h2 id="explore-a-typescript-application">21<h2 id="explore-a-demo-application">

22 TypeScript アプリケーションを探索する22 デモアプリケーションを探索する

23</h2>23</h2>

24 24 

25[`claude-agent-sdk-demos`](https://github.com/anthropics/claude-agent-sdk-demos) の TypeScript アプリケーションは、メールクライアントからマルチエージェント研究システムまで、ローカル開発用のデモです。構築しているものの形状に合致するデモをクローンしてください。25[`claude-agent-sdk-demos`](https://github.com/anthropics/claude-agent-sdk-demos) のアプリケーションは、メールクライアントからマルチエージェント研究システムまで、ローカル開発用のデモです。構築しているものの形状に合致するデモをクローンしてください。

26 26 

27<h2 id="work-through-a-python-recipe">27<h2 id="work-through-a-python-recipe">

28 Python レシピを実行する28 Python レシピを実行する

247 ```247 ```

248 </CodeGroup>248 </CodeGroup>

249 249 

250 セッション ID と checkpoint ID をキャプチャした場合、CLI からも巻き戻すことができます。このコマンドには、[Claude Code をインストール](/docs/ja/setup)することで取得できる `claude` 実行ファイルが必要です。これは SDK パッケージではインストールされません。SDK は checkpointing を有効にしますが、`claude -p` を直接実行する場合は、`CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING` 環境変数を設定する必要があります：250 セッション ID と checkpoint ID をキャプチャした場合、CLI からも巻き戻すことができます。このコマンドには、[Claude Code をインストール](/docs/ja/setup)することで取得できる `claude` 実行ファイルが必要です。SDK は checkpointing を有効にしますが、`claude -p` を直接実行する場合は、`CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING` 環境変数を設定する必要があります：

251 251 

252 ```bash theme={null}252 ```bash theme={null}

253 CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING=true claude -p --resume <session-id> --rewind-files <checkpoint-uuid>253 CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING=true claude -p --resume <session-id> --rewind-files <checkpoint-uuid>

127 127 

128例のワークロードには、受信メールをトリアージして応答するメールエージェント、コンテナポートを通じてユーザーが編集可能なサイトをホストするサイトビルダー、Slack などのプラットフォームからの継続的なトラフィックを処理するチャットボットが含まれます。128例のワークロードには、受信メールをトリアージして応答するメールエージェント、コンテナポートを通じてユーザーが編集可能なサイトをホストするサイトビルダー、Slack などのプラットフォームからの継続的なトラフィックを処理するチャットボットが含まれます。

129 129 

130コンテナは HTTP または WebSocket エンドポイントを公開し、各アクティブセッションを長時間実行されるクエリとその背後にあるサブプロセスにマップします。TypeScript では、[`streamInput()`](/docs/ja/agent-sdk/typescript#query-object)を使用してアクティブセッションにターンを追加し、[`startup()`](/docs/ja/agent-sdk/typescript#startup)を使用して受信トラフィック前にサブプロセスをプリウォームします。Python では、[`ClaudeSDKClient`](/docs/ja/agent-sdk/python#claudesdkclient)を使用してセッションをターン全体で開いたままにします。コンテナのサイズを、メモリに保持できる最大数の同時セッションに対応できるようにしてください。130コンテナは HTTP または WebSocket エンドポイントを公開し、各アクティブセッションを長時間実行されるクエリとその背後にあるサブプロセスにマップします。セッションを開いたままにして温かく保つ呼び出しは SDK 間で異なります。

131 

132* **TypeScript**：[`streamInput()`](/docs/ja/agent-sdk/typescript#query-object)を使用してアクティブセッションにターンを追加します。受信トラフィック前にサブプロセスをプリウォームするには[`startup()`](/docs/ja/agent-sdk/typescript#startup)を呼び出します。セッションの作業ディレクトリが最初のリクエストが到着するまで不明な場合は、代わりに[`prewarm()`](/docs/ja/agent-sdk/typescript#prewarm)でプリウォームしてください。

133* **Python**：[`ClaudeSDKClient`](/docs/ja/agent-sdk/python#claudesdkclient)を使用してセッションをターン全体で開いたままにします。

134 

135コンテナのサイズを、メモリに保持できる最大数の同時セッションに対応できるようにしてください。

131 136 

132<h3 id="hybrid-sessions">137<h3 id="hybrid-sessions">

133 ハイブリッドセッション138 ハイブリッドセッション

162| :- | :- | :- |162| :- | :- | :- |

163| stdio サーバー、またはキャッシュされたツールリストのない HTTP/SSE サーバー | はい、接続されるまで | [`MCP_TIMEOUT`](/docs/ja/env-vars)、デフォルトは 30 秒。接続はその期限で失敗します |163| stdio サーバー、またはキャッシュされたツールリストのない HTTP/SSE サーバー | はい、接続されるまで | [`MCP_TIMEOUT`](/docs/ja/env-vars)、デフォルトは 30 秒。接続はその期限で失敗します |

164| キャッシュされたツールリストを持つリモートサーバー（Claude Code が以前の接続から保存） | いいえ。キャッシュされたツールは最初のターンから利用可能 | なし。最初のツール呼び出しで接続し、その遅延接続には独自のタイムアウトがあります |164| キャッシュされたツールリストを持つリモートサーバー（Claude Code が以前の接続から保存） | いいえ。キャッシュされたツールは最初のターンから利用可能 | なし。最初のツール呼び出しで接続し、その遅延接続には独自のタイムアウトがあります |

165| インプロセス [SDK サーバー](#sdk-mcp-servers) | はい、接続してツールをリストするまで | なし。接続とツールリスティングリクエストはそれぞれ独自のタイムアウトを持ちます |165| インプロセス [SDK サーバー](#sdk-mcp-servers) | はい、接続してツールをリストするまで | [`MCP_TIMEOUT`](/docs/ja/env-vars)、デフォルトは 30 秒。接続試行ごと。接続はその期限で失敗します |

166 166 

167[設定ファイル](#from-a-config-file)（`.mcp.json` など）またはプラグインから読み込まれたサーバーは、通常、init メッセージで `pending` と表示されます。`options.mcpServers` が stdio、HTTP、または SSE サーバーを保持している場合、最初のターンはこれらの保留中のサーバーも待機し、`MCP_TIMEOUT` までです。`options.mcpServers` が空であるか、SDK サーバーのみを保持している場合、最初のターンは代わりに最大 2 秒間待機します。167[設定ファイル](#from-a-config-file)（`.mcp.json` など）またはプラグインから読み込まれたサーバーは、通常、init メッセージで `pending` と表示されます。`options.mcpServers` が stdio、HTTP、または SSE サーバーを保持している場合、最初のターンはこれらの保留中のサーバーも待機し、`MCP_TIMEOUT` までです。`options.mcpServers` が空であるか、SDK サーバーのみを保持している場合、最初のターンは代わりに最大 2 秒間待機します。

168 168 

14 14 

15システムプロンプトは、会話全体を通じて Claude の動作方法を形作る初期命令セットです。Agent SDK には、これに対する 3 つの開始点があります：15システムプロンプトは、会話全体を通じて Claude の動作方法を形作る初期命令セットです。Agent SDK には、これに対する 3 つの開始点があります：

16 16 

17* **最小限のデフォルト**：TypeScript で `systemPrompt` を設定しない、または Python で `system_prompt` を設定しない場合、SDK はツール呼び出しをカバーする最小限のプロンプトを使用しますが、`claude_code` プリセットの残りのコンテンツ（セキュリティと安全性の命令、および作業ディレクトリと環境に関するコンテキストを含む）は省略されています。これは、デフォルトで Claude Code システムプロンプトを使用する `claude -p` とは異なります。CLI から移行していて、一致する動作を望む場合は、`claude_code` プリセットを設定してください。17* **最小限のデフォルト**：TypeScript で `systemPrompt` を設定しない、または Python で `system_prompt` を設定しない場合、SDK はツール呼び出しをカバーする最小限のプロンプトを使用しますが、`claude_code` プリセットの残りのコンテンツ（セキュリティと安全性の命令を含む）は省略されています。これは、デフォルトで Claude Code システムプロンプトを使用する `claude -p` とは異なります。CLI から移行していて、一致する動作を望む場合は、`claude_code` プリセットを設定してください。

18* **`claude_code` プリセット**：Claude Code CLI が使用するシステムプロンプト。ツール使用命令、セキュリティと安全性の命令、および作業ディレクトリと環境に関するコンテキストが含まれています。TypeScript で `systemPrompt: { type: "preset", preset: "claude_code" }` を設定するか、Python で `system_prompt={"type": "preset", "preset": "claude_code"}` を設定してください。オプションで `append` を使用して、最後に独自の命令を追加できます。18* **`claude_code` プリセット**：Claude Code CLI が使用するシステムプロンプト。ツール使用命令、セキュリティと安全性の命令が含まれています。TypeScript で `systemPrompt: { type: "preset", preset: "claude_code" }` を設定するか、Python で `system_prompt={"type": "preset", "preset": "claude_code"}` を設定してください。オプションで `append` を使用して、最後に独自の命令を追加できます。

19* **カスタム文字列**：自分で作成したプロンプト。SDK は提供したものだけを送信します。19* **カスタム文字列**：自分で作成したプロンプト。SDK は提供したものだけを送信します。

20 20 

21<h3 id="decide-on-a-starting-point">21<h3 id="decide-on-a-starting-point">

26 26 

27| 構築しているもの | 使用するもの | 得られるもの |27| 構築しているもの | 使用するもの | 得られるもの |

28| :- | :- | :- |28| :- | :- | :- |

29| 人間が監視して指導する CLI または IDE のようなコーディングツール。Claude Code のデフォルトが必要なもの | `claude_code` プリセット | Claude Code プロンプト（ツールガイダンス、安全ルール、環境コンテキストを含む） |29| 人間が監視して指導する CLI または IDE のようなコーディングツール。Claude Code のデフォルトが必要なもの | `claude_code` プリセット | Claude Code プロンプト（ツールガイダンスと安全ルールを含む） |

30| 同じ種類のツール、プラス、コーディング標準、出力形式、またはドメインコンテキストなどの製品固有のルール | `claude_code` プリセット（`append` 付き） | 上記のすべて。プリセットの後に命令が追加されます。何も削除されないため、これは最もリスクが低いカスタマイズです |30| 同じ種類のツール、プラス、コーディング標準、出力形式、またはドメインコンテキストなどの製品固有のルール | `claude_code` プリセット（`append` 付き） | 上記のすべて。プリセットの後に命令が追加されます。何も削除されないため、これは最もリスクが低いカスタマイズです |

31| 異なるサーフェス、アイデンティティ、または権限モデルを持つエージェント、またはコーディング以外のエージェント | カスタムプロンプト文字列 | 作成したもののみ。エージェントが必要とするツールガイダンスと安全命令を置き換える責任があります |31| 異なるサーフェス、アイデンティティ、または権限モデルを持つエージェント、またはコーディング以外のエージェント | カスタムプロンプト文字列 | 作成したもののみ。エージェントが必要とするツールガイダンスと安全命令を置き換える責任があります |

32| ツール呼び出しループが薄く、エージェントペルソナがなく、ユーザープロンプトですべての動作を提供する | `systemPrompt` オプションなし | 最小限のデフォルト：ツール呼び出しサポートのみ |32| ツール呼び出しループが薄く、エージェントペルソナがなく、ユーザープロンプトですべての動作を提供する | `systemPrompt` オプションなし | 最小限のデフォルト：ツール呼び出しサポートのみ |

225 ユーザーとマシン全体でプロンプトキャッシングを改善する225 ユーザーとマシン全体でプロンプトキャッシングを改善する

226</h4>226</h4>

227 227 

228デフォルトでは、同じ `claude_code` プリセットと `append` テキストを使用する 2 つのセッションは、異なるワーキングディレクトリから実行される場合でも、プロンプトキャッシュエントリを共有できません。これは、プリセットが `append` テキストの前にシステムプロンプトにセッションごとのコンテキストを埋め込むためです。ワーキングディレクトリ、git リポジトリであるかどうか、プラットフォーム、アクティブなシェル、OS バージョン、および自動メモリパスです。そのコンテキストの違いはシステムプロンプトの違いを生じ、キャッシュミスになります。CLAUDE.md コンテンツはシステムプロンプトに影響を与えません。SDK がそれをシステムプロンプトではなく会話に注入するためです。228デフォルトでは、同じ `claude_code` プリセットと `append` テキストを使用する 2 つのセッションは、自動メモリの場所が異なる場合、プロンプトキャッシュエントリを共有できません。プリセットは `append` テキストの前にシステムプロンプトにその場所を埋め込みます。場所はデフォルトで `~/.claude/projects/` の下の絶対パスであり、ディスク上のリポジトリのパスに基づいて名前が付けられるため、ユーザー、マシン、チェックアウト全体で異なります。

229 229 

230セッション全体でシステムプロンプトを同一にするには、TypeScript で `excludeDynamicSections: true` を設定するか、Python で `"exclude_dynamic_sections": True` を設定します。セッションごとのコンテキストは最初のユーザーメッセージに移動し、静的プリセットと `append` テキストのみがシステムプロンプトに残るため、同一の設定はユーザーとマシン全体でキャッシュエントリを共有できます。230CLAUDE.md コンテンツおよびワーキングディレクトリ、プラットフォーム、シェル、OS バージョンなどの環境詳細は、Claude Code がそれらをシステムプロンプトではなく会話で配信するため、システムプロンプトキャッシュに影響を与えません。

231 

232セッション全体でシステムプロンプトを同一にするには、TypeScript で `excludeDynamicSections: true` を設定するか、Python で `"exclude_dynamic_sections": True` を設定します。ユーザーごとのコンテキストは最初のユーザーメッセージに移動し、静的プリセットと `append` テキストのみがシステムプロンプトに残るため、同一の設定はユーザーとマシン全体でキャッシュエントリを共有できます。

231 233 

232<Note>234<Note>

233 `excludeDynamicSections` には `@anthropic-ai/claude-agent-sdk` v0.2.98 以降、または Python の場合は `claude-agent-sdk` v0.1.58 以降が必要です。プリセットオブジェクト形式でのみ設定します。SDK はカスタムプロンプトの代わりにプリセットを渡す場合、それを無視します。カスタムプロンプトの指示を TypeScript SDK でキャッシュに保つには、[Cache the static part of a custom prompt](#cache-the-static-part-of-a-custom-prompt) を参照してください。235 `excludeDynamicSections` には `@anthropic-ai/claude-agent-sdk` v0.2.98 以降、または Python の場合は `claude-agent-sdk` v0.1.58 以降が必要です。プリセットオブジェクト形式でのみ設定します。SDK はカスタムプロンプトの代わりにプリセットを渡す場合、それを無視します。カスタムプロンプトの指示を TypeScript SDK でキャッシュに保つには、[Cache the static part of a custom prompt](#cache-the-static-part-of-a-custom-prompt) を参照してください。

234</Note>236</Note>

235 237 

236次の例は、共有 `append` ブロックを `excludeDynamicSections` と組み合わせるため、異なるディレクトリから実行されるエージェントのフリートが同じキャッシュされたシステムプロンプトを再利用できます。238次の例は、共有 `append` ブロックを `excludeDynamicSections` と組み合わせるため、エージェントのフリートが同じキャッシュされたシステムプロンプトを再利用できます。

237 239 

238<CodeGroup>240<CodeGroup>

239 ```typescript TypeScript theme={null}241 ```typescript TypeScript theme={null}

279 ```281 ```

280</CodeGroup>282</CodeGroup>

281 283 

282**トレードオフ:** ワーキングディレクトリ、git リポジトリフラグ、プラットフォーム、アクティブなシェル、OS バージョン、および自動メモリパスは引き続き Claude に到達しますが、システムプロンプトではなく最初のユーザーメッセージの一部として到達します。ユーザーメッセージの指示はシステムプロンプトの同じテキストよりもわずかに低い重みを持つため、Claude は現在のディレクトリまたは自動メモリパスについて推論する際にそれらに依存する可能性が低くなります。セッション間のキャッシュ再利用が最大限に権威あるコンテキストよりも重要な場合、このオプションを有効にします。284**トレードオフ:** システムプロンプトから移動したテキストは引き続き Claude に到達しますが、ユーザーメッセージとしてです。そのテキストは少なくとも自動メモリディレクトリの場所であり、多くの場合は自動メモリセクション全体です。ユーザーメッセージの指示はシステムプロンプトの同じテキストよりもわずかに低い重みを持つため、Claude はその自動メモリガイダンスに従う可能性が低くなります。セッション間のキャッシュ再利用がより権威あるコンテキストよりも重要な場合、このオプションを有効にします。

283 285 

284非対話型 CLI モードの同等のフラグについては、[`--exclude-dynamic-system-prompt-sections`](/docs/ja/cli-reference) を参照してください。286非対話型 CLI モードの同等のフラグについては、[`--exclude-dynamic-system-prompt-sections`](/docs/ja/cli-reference) を参照してください。

285 287 

418 420 

419`append` またはカスタムプロンプトを記録するには、デフォルトで Claude Code v2.1.265 以降が必要です。TypeScript Agent SDK は v0.3.265 から、Python Agent SDK は v0.2.153 からバンドルされています。Claude Code v2.1.268 より前では、[feature flags](/docs/ja/env-vars#features-that-need-feature-flag-fetching) をフェッチしないセッション（Amazon Bedrock、Google Cloud の Agent Platform、Microsoft Foundry のセッションを含む）はすべてのリクエストでプロンプトを再構築し、`snapshot` は効果がありませんでした。421`append` またはカスタムプロンプトを記録するには、デフォルトで Claude Code v2.1.265 以降が必要です。TypeScript Agent SDK は v0.3.265 から、Python Agent SDK は v0.2.153 からバンドルされています。Claude Code v2.1.268 より前では、[feature flags](/docs/ja/env-vars#features-that-need-feature-flag-fetching) をフェッチしないセッション（Amazon Bedrock、Google Cloud の Agent Platform、Microsoft Foundry のセッションを含む）はすべてのリクエストでプロンプトを再構築し、`snapshot` は効果がありませんでした。

420 422 

423<h2 id="context-claude-code-adds-outside-the-system-prompt">

424 Claude Code がシステムプロンプト外に追加するコンテキスト

425</h2>

426 

427システムリマインダーは、Claude Code がセッション中に会話に追加するメッセージで、CLAUDE.md ファイルの内容やファイルがディスク上で変更されたというメモなど、Claude にコンテキストを提供します。Claude Code はシステムプロンプトではなく会話内でそれらを送信するため、`claude_code` プリセットを使用するか、`systemPrompt` として独自の文字列を渡すかに関わらず、Claude に到達します。

428 

429このセクションでは、[エージェントの動作を変更する可能性が最も高いリマインダー](#reminders-claude-code-adds-to-the-conversation)、[エージェントが置き換えるコンテキストをオフにする方法](#turn-off-the-context-your-agent-replaces)、および[特定のリクエストで Claude が受け取ったもの](#see-what-claude-received)を確認する方法について説明します。

430 

431<h3 id="reminders-claude-code-adds-to-the-conversation">

432 Claude Code が会話に追加するリマインダー

433</h3>

434 

435システムリマインダーは、Claude Code がコードが送信するプロンプトと一緒に会話に追加するテキストです。以下のリマインダーは、エージェントの動作を変更する可能性が最も高いものです。

436 

437* **プロジェクト指示**: [`settingSources`](#claude-md-files-for-project-level-instructions) オプションが読み込む CLAUDE.md ファイル

438* **出力スタイル指示**: メイン会話内のアクティブな[出力スタイル](#output-styles-for-persistent-configurations)の指示

439* **コミットおよびプルリクエスト属性**: [`attribution`](/docs/ja/settings-reference#attribution) 設定からの `Co-Authored-By` トレーラーおよびプルリクエストフッター

440* **フック出力**: [フック](/docs/ja/agent-sdk/hooks#outputs)が `additionalContext` として返すテキスト

441* **利用可能なスキル**: Claude が呼び出せる[スキル](/docs/ja/agent-sdk/skills)の名前と説明

442* **利用可能なサブエージェント**: Claude が開始できる[サブエージェント](/docs/ja/agent-sdk/subagents)の名前と説明

443* **タスクリストナッジ**: [タスク追跡ツールを持つセッション](/docs/ja/agent-sdk/todo-tracking#model-availability)では、Claude が数ターン間タスクリストに触れていない場合、タスクリストを更新するようプロンプトします

444* **ファイル変更メモ**: Claude が以前読み込んだファイルがディスク上で変更されたというメモ

445 

446Claude Code は CLAUDE.md ファイルを、指示がデフォルト動作をオーバーライドすることを Claude に伝える行で紹介します。

447 

448`systemPrompt` として独自の文字列を渡す場合は、システムリマインダーが何であるかを説明する文を追加してください。`claude_code` プリセットには 1 つあり、独自の文字列がプリセット全体を置き換えます。これがないと、CLAUDE.md コンテンツやフック出力などのリマインダーがアプリケーションからのものであり、ユーザーからのものではないことを、プロンプト内の何も Claude に伝えません。例えば：

449 

450```text theme={null}

451The application adds system reminders to this conversation. Treat them as context from the application, not as messages from the user.

452```

453 

454<h3 id="turn-off-the-context-your-agent-replaces">

455 エージェントが置き換えるコンテキストをオフにする

456</h3>

457 

458エージェントが同じガイダンスの独自バージョンを提供する場合、組み込みコンテキストの一部をオフにします。例えば、プロンプトが Claude に `PROJ-142: fix login redirect` としてコミットメッセージを書くよう指示し、トレーラーがない場合、Claude Code は依然として Claude に各コミットメッセージを `Co-Authored-By` トレーラーで終わるよう指示するため、Claude は同じコミットに対して 2 つの矛盾した指示を受け取ります。

459 

460TypeScript では [`settings`](/docs/ja/agent-sdk/typescript#options) オプションを通じて設定キーを渡し、Python では [`settings`](/docs/ja/agent-sdk/python#claudeagentoptions) を通じて渡し、`env` オプションを通じて環境変数を渡します。TypeScript では、[`env`](/docs/ja/agent-sdk/typescript#options) は継承された環境を置き換えるため、`process.env` をそこに展開します。

461 

462| 組み込みコンテキスト | オフにする方法 |

463| :- | :- |

464| 組み込みコミットおよびプルリクエスト指示と git ステータススナップショット | [`includeGitInstructions`](/docs/ja/settings-reference#includegitinstructions) を `false` に設定するか、`CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS=1` |

465| `Co-Authored-By` トレーラーおよびプルリクエストフッター | [`attribution.commit`](/docs/ja/settings-reference#attribution-commit) と [`attribution.pr`](/docs/ja/settings-reference#attribution-pr) を独自のテキストに設定するか、削除するために空の文字列に設定します |

466| ユーザーまたはプロジェクト設定ソース（その CLAUDE.md を含む） | [`settingSources`](/docs/ja/agent-sdk/claude-code-features#control-filesystem-settings-with-settingsources) から `'user'` または `'project'` を除外します |

467| すべての CLAUDE.md ファイル | `CLAUDE_CODE_DISABLE_CLAUDE_MDS=1` を設定します |

468| タスクリストナッジ、ファイル変更メモ、およびスキルリスト | `CLAUDE_CODE_DISABLE_ATTACHMENTS=1` を設定します |

469 

470Claude Code の組み込みコミットおよびプルリクエスト指示はリマインダーではありません。これらは Bash ツールの説明の一部であるため、カスタム `systemPrompt` を渡す場合にも Claude に到達します。

471 

472`CLAUDE_CODE_DISABLE_ATTACHMENTS` を設定する場合、Claude Code は `@` ファイルメンションをプレーンテキストとして送信し、ファイルコンテンツに展開しません。利用可能なサブエージェントのリストとバックグラウンドタスク通知は依然として到達します。

473 

474以下の例は、`append` に独自のコミットルールを持つエージェント用です。トレーラーとフッターを削除するために両方の `attribution` キーを空の文字列に設定し、`includeGitInstructions` をオフにして、Claude Code 独自のコミットワークフロー指示があなたのものと競合しないようにします。

475 

476<CodeGroup>

477 ```typescript TypeScript theme={null}

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

479 

480 for await (const message of query({

481 prompt: "Commit the staged changes for ticket PROJ-142",

482 options: {

483 systemPrompt: {

484 type: "preset",

485 preset: "claude_code",

486 append: "Write commit messages as: <ticket id>: <summary>. Add no trailers."

487 },

488 settings: {

489 includeGitInstructions: false,

490 attribution: { commit: "", pr: "" }

491 },

492 allowedTools: ["Bash(git *)"]

493 }

494 })) {

495 if (message.type === "result") console.log(message.subtype);

496 }

497 ```

498 

499 ```python Python theme={null}

500 import asyncio

501 from claude_agent_sdk import query, ClaudeAgentOptions

502 

503 

504 async def main():

505 async for message in query(

506 prompt="Commit the staged changes for ticket PROJ-142",

507 options=ClaudeAgentOptions(

508 system_prompt={

509 "type": "preset",

510 "preset": "claude_code",

511 "append": "Write commit messages as: <ticket id>: <summary>. Add no trailers.",

512 },

513 settings='{"includeGitInstructions": false, "attribution": {"commit": "", "pr": ""}}',

514 allowed_tools=["Bash(git *)"],

515 ),

516 ):

517 print(message)

518 

519 

520 asyncio.run(main())

521 ```

522</CodeGroup>

523 

524変更を確認するには、ステージされた変更を持つリポジトリで例を実行し、`git log -1` で新しいコミットを確認します。メッセージは `Co-Authored-By` トレーラーなしで終わります。

525 

526<h3 id="see-what-claude-received">

527 Claude が受け取ったものを確認する

528</h3>

529 

530SDK メッセージストリームはシステムリマインダーを含まないため、コードが受け取るメッセージを読むことで、Claude が何を見たかは表示されません。それらを確認するには、Claude Code が送信するリクエストをログに記録します。

531 

532* **生のリクエストログ**: [`OTEL_LOG_RAW_API_BODIES`](/docs/ja/monitoring-usage#api-request-body-event) を `file:<dir>` に設定します。Claude Code は各リクエストボディをそのディレクトリに書き込みます。

533* **制御するゲートウェイ**: [`ANTHROPIC_BASE_URL`](/docs/ja/llm-gateway) をリクエストボディをログに記録するプロキシに指定します。

534 

535ログされたリクエストでは、`messages` 配列を確認します。リマインダーは `<system-reminder>` タグでラップされたユーザーメッセージ内に表示されるか、一部のモデルでは `system` ロールを持つ別のメッセージとして表示されます。

536 

421<h2 id="compare-the-four-approaches">537<h2 id="compare-the-four-approaches">

422 4 つのアプローチすべての比較538 4 つのアプローチすべての比較

423</h2>539</h2>

431| **管理** | ファイルシステム上 | CLI + ファイル | コード内 | コード内 |547| **管理** | ファイルシステム上 | CLI + ファイル | コード内 | コード内 |

432| **デフォルトツール** | 保持 | 保持 | 保持 | 失われる（含まれない限り） |548| **デフォルトツール** | 保持 | 保持 | 保持 | 失われる（含まれない限り） |

433| **組み込みセキュリティ** | 維持 | 維持 | 維持 | 追加する必要がある |549| **組み込みセキュリティ** | 維持 | 維持 | 維持 | 追加する必要がある |

434| **環境コンテキスト** | 自動 | 自動 | 自動 | 提供する必要がある |

435| **カスタマイズレベル** | 追加のみ | デフォルトを置き換え | 追加のみ | 完全な制御 |550| **カスタマイズレベル** | 追加のみ | デフォルトを置き換え | 追加のみ | 完全な制御 |

436| **バージョン管理** | プロジェクトと共に | はい | コードと共に | コードと共に |551| **バージョン管理** | プロジェクトと共に | はい | コードと共に | コードと共に |

437| **スコープ** | プロジェクト固有 | ユーザーまたはプロジェクト | コードセッション | コードセッション |552| **スコープ** | プロジェクト固有 | ユーザーまたはプロジェクト | コードセッション | コードセッション |

246| 変数 | 追加内容 |246| 変数 | 追加内容 |

247| - | - |247| - | - |

248| `OTEL_LOG_USER_PROMPTS=1` | `claude_code.user_prompt` イベントと `claude_code.interaction` スパンのプロンプトテキスト |248| `OTEL_LOG_USER_PROMPTS=1` | `claude_code.user_prompt` イベントと `claude_code.interaction` スパンのプロンプトテキスト |

249| `OTEL_LOG_TOOL_DETAILS=1` | `claude_code.tool_result` イベントのツール入力引数（ファイルパス、シェルコマンド、検索パターン） |249| `OTEL_LOG_TOOL_DETAILS=1` | `claude_code.tool_result` イベントのツール入力引数（ファイルパス、シェルコマンド、検索パターン）、および [コストとトークンメトリクス](/docs/ja/monitoring-usage#cost-counter)の実エージェント、スキル、プラグイン、MCP サーバー名 |

250| `OTEL_LOG_TOOL_CONTENT=1` | `claude_code.tool` の [`tool.output` スパンイベント](/docs/ja/monitoring-usage#tool-output-span-event)とファイルコンテンツと Bash 出力を含み、デフォルトで 60 KB で切り詰められ、`CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` で設定可能です。Claude Code v2.1.214 以降が必要です。[トレース](#read-agent-traces)が有効になっている必要があります。スパン属性は [独自のゲート](/docs/ja/monitoring-usage#new-context-gates)の下でツールコンテンツを保持します |250| `OTEL_LOG_TOOL_CONTENT=1` | `claude_code.tool` の [`tool.output` スパンイベント](/docs/ja/monitoring-usage#tool-output-span-event)とファイルコンテンツ、Bash 出力、MCP ツール、WebFetch、WebSearch が返すもの（デフォルトで 60 KB で切り詰められ、`CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` で設定可能）を含みます。Claude Code v2.1.214 以降が必要です。MCP ツール、WebFetch、WebSearch からの結果には Claude Code v2.1.283 以降が必要です。[トレース](#read-agent-traces)が有効になっている必要があります。スパン属性は [独自のゲート](/docs/ja/monitoring-usage#new-context-gates)の下でツールコンテンツを保持します |

251| `OTEL_LOG_RAW_API_BODIES` | Anthropic Messages API リクエストおよびレスポンス JSON 全体を `claude_code.api_request_body` および `claude_code.api_response_body` ログイベントとして。`1` に設定してデフォルトで 60 KB で切り詰められたインラインボディを取得するか、`file:<dir>` に設定してディスク上の切り詰められていないボディをイベント内の `body_ref` パスで取得します。`CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` はインライン切り詰め制限を設定し、Claude Code v2.1.214 以降が必要です。ボディには会話履歴全体が含まれ、拡張思考コンテンツが編集されます。これを有効にすると、上記の 3 つの変数が明かすすべてのコンテンツへの同意が暗示されます |251| `OTEL_LOG_RAW_API_BODIES` | Anthropic Messages API リクエストおよびレスポンス JSON 全体を `claude_code.api_request_body` および `claude_code.api_response_body` ログイベントとして。`1` に設定してデフォルトで 60 KB で切り詰められたインラインボディを取得するか、`file:<dir>` に設定してディスク上の切り詰められていないボディをイベント内の `body_ref` パスで取得します。`CLAUDE_CODE_OTEL_CONTENT_MAX_LENGTH` はインライン切り詰め制限を設定し、Claude Code v2.1.214 以降が必要です。ボディには会話履歴全体が含まれ、拡張思考コンテンツが編集されます。これを有効にすると、上記の 3 つの変数が明かすすべてのコンテンツへの同意が暗示されます |

252 252 

253エージェントが処理するデータを保存することが可観測性パイプラインで承認されていない限り、これらを設定しないままにしてください。Monitoring リファレンスの [セキュリティとプライバシー](/docs/ja/monitoring-usage#security-and-privacy)を参照して、すべての属性と編集動作の完全なリストを確認してください。253エージェントが処理するデータを保存することが可観測性パイプラインで承認されていない限り、これらを設定しないままにしてください。Monitoring リファレンスの [セキュリティとプライバシー](/docs/ja/monitoring-usage#security-and-privacy)を参照して、すべての属性と編集動作の完全なリストを確認してください。

41 </Step>41 </Step>

42 42 

43 <Step title="Allow ルール">43 <Step title="Allow ルール">

44 `allow` ルール（`allowed_tools` および settings.json から）をチェックします。ルールがマッチした場合、ツールは承認されます。ツール自体が承認する呼び出しもこのステップで解決されます。ルールは不要です。例えば、作業ディレクトリ内のファイル読み取りまたは [読み取り専用 Bash コマンド](/docs/ja/permissions#read-only-commands)。`rm` および `rmdir` の削除で [重要なパス](/docs/ja/permission-modes#critical-paths) をターゲットとするものは、allow ルールによって決して承認されません。プロンプトを表示するモードではコールバックに到達し、Claude Code v2.1.218 以降の `auto` モードでは [分類器](/docs/ja/permission-modes#eliminate-prompts-with-auto-mode) に移動し、`dontAsk` モードでは拒否されます。44 `allow` ルール（`allowed_tools` および settings.json から）をチェックします。ルールがマッチした場合、ツールは承認されます。ツール自体が承認する呼び出しもこのステップで解決されます。ルールは不要です。例えば、作業ディレクトリ内のファイル読み取りまたは [読み取り専用 Bash コマンド](/docs/ja/permissions#read-only-commands)。

45 

46 `rm` および `rmdir` の削除で [重要なパス](/docs/ja/permission-modes#critical-paths) をターゲットとするものは、allow ルールによって決して承認されません。その後、コールバックに到達するかどうかは permission モードに依存します。例えば、`auto` モードの Agent SDK セッションでは、Claude Code はデフォルトでそれを呼び出さずに拒否します。[重要なパス](/docs/ja/permission-modes#critical-paths) モード表は、各モードがそれらで何をするかをリストしています。

45 </Step>47 </Step>

46 48 

47 <Step title="canUseTool コールバック">49 <Step title="canUseTool コールバック">

89絶対ファイルシステムパスには `//path` を使用します：`Edit(//secrets/**)` の拒否ルールは、ディスク上の `/secrets` の下のどこでも書き込みをブロックします。単一の先頭スラッシュの場合、`Edit(/secrets/**)` はルールのソースでアンカーします。`allowed_tools` または `disallowed_tools` を通じて渡されるルールの場合、それはセッションの作業ディレクトリを意味するため、ルールはディスク上の `/secrets` をブロックしません。[Read と Edit ルール](/docs/ja/permissions#read-and-edit)で 4 つのアンカー形式と、設定ファイルからのルール解決方法を参照してください。91絶対ファイルシステムパスには `//path` を使用します：`Edit(//secrets/**)` の拒否ルールは、ディスク上の `/secrets` の下のどこでも書き込みをブロックします。単一の先頭スラッシュの場合、`Edit(/secrets/**)` はルールのソースでアンカーします。`allowed_tools` または `disallowed_tools` を通じて渡されるルールの場合、それはセッションの作業ディレクトリを意味するため、ルールはディスク上の `/secrets` をブロックしません。[Read と Edit ルール](/docs/ja/permissions#read-and-edit)で 4 つのアンカー形式と、設定ファイルからのルール解決方法を参照してください。

90 92 

91<Warning>93<Warning>

92 **自動承認ツールは `canUseTool` に到達しません。** `acceptEdits` または `bypassPermissions` によって、または許可ルールによって、任意の前のステップで承認されたツール呼び出しは、その `canUseTool` コールバックをスキップするため、そこに配置した権限チェックはそのツールに対して静かにバイパスされます。`AskUserQuestion`、MCP ツール（[`_meta["anthropic/requiresUserInteraction"]`](/docs/ja/mcp#require-approval-for-a-specific-tool)でマークされている）、コネクタツール（[組織が `ask` に設定](/docs/ja/mcp#organization-controls-on-connector-tools)）、および[重要なパス](/docs/ja/permission-modes#critical-paths)をターゲットとする `rm` と `rmdir` 削除は、許可ルールがマッチする場合でも、コールバックに到達します。`auto` モードでは、重要なパス削除は[分類器](/docs/ja/permission-modes#eliminate-prompts-with-auto-mode)に移動し、コールバックには移動しません。一方、ここにリストされている他の呼び出しはそれでも到達します。分類器ルーティングには Claude Code v2.1.218 以降が必要です。`dontAsk` モードでは、これらの呼び出しは代わりに拒否され、コールバックを呼び出しません。94 **自動承認ツールは `canUseTool` に到達しません。** `acceptEdits` または `bypassPermissions` によって、または許可ルールによって、任意の前のステップで承認されたツール呼び出しは、その `canUseTool` コールバックをスキップするため、そこに配置した権限チェックはそのツールに対して静かにバイパスされます。

95 

96 許可ルールは、`AskUserQuestion`、MCP ツール（[`_meta["anthropic/requiresUserInteraction"]`](/docs/ja/mcp#require-approval-for-a-specific-tool)でマークされている）、コネクタツール（[組織が `ask` に設定](/docs/ja/mcp#organization-controls-on-connector-tools)）、および[重要なパス](/docs/ja/permission-modes#critical-paths)をターゲットとする `rm` と `rmdir` 削除を自動承認することはありません。`dontAsk` モードでは、Claude Code はこれらの呼び出しをコールバックを呼び出さずに拒否します。他のモードでは、最初の 3 つはコールバックに到達します。[権限モード](/docs/ja/permission-modes#critical-paths)に応じて、重要なパス削除はコールバックに到達するか、Claude Code はそれを呼び出さずに拒否します。デフォルトでは Agent SDK セッションの `auto` モードでそうするように、です。

93 97 

94 カバレッジはエントリの形式に依存します：`Read` や `mcp__github__get_issue` のような裸の名前は、上記の例外を除いて、そのツールへのすべての呼び出しを自動承認しますが、`Bash(npm test *)` のようなスコープ付きルールはマッチする呼び出しのみを自動承認し、承認が必要な他の `Bash` 呼び出しはコールバックにフォールスルーします。すべてのツール呼び出しで実行する必要があるチェックの場合は、[`PreToolUse` フック](/docs/ja/agent-sdk/hooks)を使用します：フックはすべての他のステップの前に実行され、フック拒否は `bypassPermissions` モードでも適用されます。98 カバレッジはエントリの形式に依存します：`Read` や `mcp__github__get_issue` のような裸の名前は、上記の例外を除いて、そのツールへのすべての呼び出しを自動承認しますが、`Bash(npm test *)` のようなスコープ付きルールはマッチする呼び出しのみを自動承認し、承認が必要な他の `Bash` 呼び出しはコールバックにフォールスルーします。すべてのツール呼び出しで実行する必要があるチェックの場合は、[`PreToolUse` フック](/docs/ja/agent-sdk/hooks)を使用します：フックはすべての他のステップの前に実行され、フック拒否は `bypassPermissions` モードでも適用されます。

95</Warning>99</Warning>

301 305 

302ファイル編集は計画モードで自動承認されません。許可ルールが一致する場合でも、代わりに `canUseTool` コールバックを通じてプロンプトが表示されます。Claude Code v2.1.212 以降では、`touch` や `rm` などのファイルを変更するシェルコマンドは同じ方法で `canUseTool` コールバックに到達します。306ファイル編集は計画モードで自動承認されません。許可ルールが一致する場合でも、代わりに `canUseTool` コールバックを通じてプロンプトが表示されます。Claude Code v2.1.212 以降では、`touch` や `rm` などのファイルを変更するシェルコマンドは同じ方法で `canUseTool` コールバックに到達します。

303 307 

304`allowDangerouslySkipPermissions: true` を `permissionMode: 'plan'` と一緒に設定した場合、ファイル編集とファイルを変更するシェルコマンドは引き続き `canUseTool` コールバックに到達します。このオプションにより、後で `setPermissionMode()` で `bypassPermissions` に切り替えることができます。308TypeScript SDK で `allowDangerouslySkipPermissions: true` を `permissionMode: 'plan'` と一緒に設定した場合、ファイル編集とファイルを変更するシェルコマンドは引き続き `canUseTool` コールバックに到達します。このオプションにより、後で `setPermissionMode()` で `bypassPermissions` に切り替えることができます。

305 309 

306Claude は計画を最終化する前に、`AskUserQuestion` を使用して要件を明確にする場合があります。これらのプロンプトの処理については、[承認とユーザー入力の処理](/docs/ja/agent-sdk/user-input#handle-clarifying-questions) を参照してください。310Claude は計画を最終化する前に、`AskUserQuestion` を使用して要件を明確にする場合があります。これらのプロンプトの処理については、[承認とユーザー入力の処理](/docs/ja/agent-sdk/user-input#handle-clarifying-questions) を参照してください。

307 311 

331 プラグインが読み込まれない331 プラグインが読み込まれない

332</h3>332</h3>

333 333 

334プラグインが初期化メッセージに表示されない場合：334プラグインが初期化メッセージの `plugins` リストに表示されない場合は、その [`plugin_errors`](/docs/ja/agent-sdk/typescript#sdksystemmessage) フィールドで理由を確認してから、以下のチェックを実行してください。

335 335 

3361. **パスを確認する**: パスがプラグインルートディレクトリ（`skills/`、`agents/`、`hooks/`、`commands/`、または `.claude-plugin/` の親）を指していることを確認してください3361. **パスを確認する**: パスがプラグインルートディレクトリ（`skills/`、`agents/`、`hooks/`、`commands/`、または `.claude-plugin/` の親）を指していることを確認してください

3372. **plugin.json を検証する**: プラグインにマニフェストが含まれている場合、有効な JSON 構文を持っていることを確認してください3372. **plugin.json を検証する**: プラグインにマニフェストが含まれている場合、有効な JSON 構文を持っていることを確認してください

295| プロパティ | 型 | 説明 |295| プロパティ | 型 | 説明 |

296| :- | :- | :- |296| :- | :- | :- |

297| `session_id` | `str` | 一意のセッション識別子 |297| `session_id` | `str` | 一意のセッション識別子 |

298| `summary` | `str` | 表示タイトル：カスタムタイトル、自動生成されたサマリー、または最初のプロンプト |298| `summary` | `str` | 表示タイトル：カスタムタイトル、最新のプロンプト、自動生成されたサマリー、または最初のプロンプト |

299| `last_modified` | `int` | エポック以降のミリ秒単位での最後の変更時刻 |299| `last_modified` | `int` | エポック以降のミリ秒単位での最後の変更時刻 |

300| `file_size` | `int \| None` | セッションファイルサイズ（バイト）（リモートストレージバックエンドの場合は `None`） |300| `file_size` | `int \| None` | セッションファイルサイズ（バイト）（リモートストレージバックエンドの場合は `None`） |

301| `custom_title` | `str \| None` | ユーザーが設定したセッションタイトル |301| `custom_title` | `str \| None` | ユーザーが設定したセッションタイトル |

875 include_partial_messages: bool = False875 include_partial_messages: bool = False

876 include_hook_events: bool = False876 include_hook_events: bool = False

877 forward_subagent_text: bool = False877 forward_subagent_text: bool = False

878 verbatim_prompts: bool = False

878 fork_session: bool = False879 fork_session: bool = False

879 resume_session_at: str | None = None880 resume_session_at: str | None = None

880 resume_drops_turn: str | None = None881 resume_drops_turn: str | None = None

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

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

930| `forward_subagent_text` | `bool` | `False` | メッセージストリームでサブエージェントのテキストと思考ブロックを転送します。このオプションがない場合、Claude Codeはサブエージェント`tool_use`と`tool_result`ブロックを出力しますが、テキストや思考は出力しません。Python Agent SDK 0.2.140以降が必要です |931| `forward_subagent_text` | `bool` | `False` | メッセージストリームでサブエージェントのテキストと思考ブロックを転送します。このオプションがない場合、Claude Codeはサブエージェント`tool_use`と`tool_result`ブロックを出力しますが、テキストや思考は出力しません。Python Agent SDK 0.2.140以降が必要です |

932| `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要件を満たします |

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

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

933| `resume_drops_turn` | `str \| None` | `None` | ユーザープロンプトのUUID。`resume_session_at`切り詰めが破棄するターン。設定すると、CLIは破棄された範囲がそのターンに帰属しないエントリを保持する場合、再開を拒否します。Python Agent SDK 0.2.137以降およびClaude Code v2.1.223以降が必要です。これらのSDKバージョンにバンドルされているCLIはClaude Code要件を満たします |935| `resume_drops_turn` | `str \| None` | `None` | ユーザープロンプトのUUID。`resume_session_at`切り詰めが破棄するターン。設定すると、CLIは破棄された範囲がそのターンに帰属しないエントリを保持する場合、再開を拒否します。Python Agent SDK 0.2.137以降およびClaude Code v2.1.223以降が必要です。これらのSDKバージョンにバンドルされているCLIはClaude Code要件を満たします |

1010| `type` | はい | プリセットシステムプロンプトを使用するには`"preset"`である必要があります |1012| `type` | はい | プリセットシステムプロンプトを使用するには`"preset"`である必要があります |

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

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

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

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

1015 1017 

1016<h3 id="systempromptcustom">1018<h3 id="systempromptcustom">

3790<Warning>3792<Warning>

3791 `dangerouslyDisableSandbox: True` で実行されるコマンドはシステムへの完全なアクセスを持ちます。`can_use_tool` ハンドラーがこれらのリクエストを慎重に検証することを確認してください。3793 `dangerouslyDisableSandbox: True` で実行されるコマンドはシステムへの完全なアクセスを持ちます。`can_use_tool` ハンドラーがこれらのリクエストを慎重に検証することを確認してください。

3792 3794 

3793 `permission_mode` が `bypassPermissions` に設定され、`allow_unsandboxed_commands` が有効な場合、モデルは [アクションなしモードが自動承認しないアクション](/docs/ja/permission-modes#actions-no-mode-auto-approves) を除き、承認プロンプトなしにサンドボックスの外でコマンドを自律的に実行できます。この組み合わせは、モデルがサンドボックス分離をサイレントに逃れることを効果的に許可します。3795 `permission_mode` が `bypassPermissions` に設定され、`allowUnsandboxedCommands` が有効な場合、モデルは [アクションなしモードが自動承認しないアクション](/docs/ja/permission-modes#actions-no-mode-auto-approves) を除き、承認プロンプトなしにサンドボックスの外でコマンドを自律的に実行できます。この組み合わせは、モデルがサンドボックス分離をサイレントに逃れることを効果的に許可します。

3794</Warning>3796</Warning>

3795 3797 

3796<h2 id="see-also">3798<h2 id="see-also">

330 既知の制限事項330 既知の制限事項

331</h2>331</h2>

332 332 

333* **構造化出力**: JSON 結果は最終的な `ResultMessage.structured_output` にのみ表示され、ストリーミングデルタとしては表示されません。詳細は[構造化出力](/docs/ja/agent-sdk/structured-outputs)を参照してください。333* **構造化出力**: 部分メッセージが有効な場合、JSON はツール呼び出しの未検証の `input_json_delta` チャンクとしてストリーミングされ、検証済みの結果のみが最終的な `ResultMessage.structured_output` に到達します。詳細は[構造化出力](/docs/ja/agent-sdk/structured-outputs)を参照してください。

334 334 

335<h2 id="next-steps">335<h2 id="next-steps">

336 次のステップ336 次のステップ

162 structured\_output は None ですが、結果は成功と言っています162 structured\_output は None ですが、結果は成功と言っています

163</h3>163</h3>

164 164 

165結果メッセージは `subtype: "success"` で終わることができますが、Python では `structured_output` は `None` であり、TypeScript では `undefined` です。実行は完了しますが、検証された出力は存在しません。これに到達する 1 つの方法は、出力が満たすことができないスキーマです。たとえば、矛盾する長さの制約があります。実行は検証エラーなしで終了し、唯一の信号は欠落している `structured_output` です。165結果メッセージは `subtype: "success"` で終わることができますが、Python では `structured_output` は `None` であり、TypeScript では `undefined` です。実行は完了しますが、検証された出力は存在しません。これに到達する 1 つの方法は、出力が満たすことができないスキーマです。たとえば、矛盾する長さの制約があります。

166 166 

167アプリケーションコードでこの結果を失敗として扱ってください。`structured_output` を使用する前に、`subtype` が `success` であり、`structured_output` が存在することの両方を確認してください。[エラーハンドリング](/docs/ja/agent-sdk/structured-outputs#error-handling)セクションは両方の SDK のこのパターンを示しています。167アプリケーションコードでこの結果を失敗として扱ってください。`structured_output` を使用する前に、`subtype` が `success` であり、`structured_output` が存在することの両方を確認してください。[エラーハンドリング](/docs/ja/agent-sdk/structured-outputs#error-handling)セクションは両方の SDK のこのパターンを示しています。

168 168 

54* クロスコンパイルするには、一致しないプラットフォームパッケージをインストールします。例えば `npm install @anthropic-ai/claude-agent-sdk-linux-x64 --force`。54* クロスコンパイルするには、一致しないプラットフォームパッケージをインストールします。例えば `npm install @anthropic-ai/claude-agent-sdk-linux-x64 --force`。

55* Windows では、バイナリサブパスは `claude.exe` です。例えば `@anthropic-ai/claude-agent-sdk-win32-x64/claude.exe`。55* Windows では、バイナリサブパスは `claude.exe` です。例えば `@anthropic-ai/claude-agent-sdk-win32-x64/claude.exe`。

56 56 

57<h3 id="import-the-/core-entry-when-you-bundle-the-agent-sdk">

58 Agent SDK をバンドルする場合は `/core` エントリをインポートする

59</h3>

60 

61アプリケーションが Agent SDK を独自の依存関係と一緒にバンドルする場合、パッケージルートではなく `@anthropic-ai/claude-agent-sdk/core` からインポートしてください。`/core` エントリには TypeScript Agent SDK v0.3.282 以降が必要であり、そのタイプには TypeScript 5.0 以降が必要です。

62 

63`/core` エントリは、ルートエントリと同じ `query()`、`startup()`、`tool()`、`createSdkMcpServer()`、`resolveSettings()` をエクスポートします。セッションの名前変更、タグ付け、削除を行う関数、`AbortError`、ランタイム定数、およびすべてのタイプも含まれます。独自の名前は追加されません。アプリケーションが読み込むコードを小さく保つために、`/core` はいくつかのルートエクスポートを除外しています。これには `prewarm()`、`InMemorySessionStore` クラス、およびセッションをリスト、読み取り、フォーク、インポート、要約するヘルパーが含まれます。これらのいずれかが必要な場合は、代わりにルートエントリを使用してください。

64 

65ルートエントリは `zod` と `@modelcontextprotocol/sdk` の独自のコピーをインライン化します。`/core` エントリは、Agent SDK の `peerDependencies` が宣言する範囲で、`node_modules` からそれらをインポートします。そのため、既にそれらを含むバンドルは 2 番目のコピーを持ちません。特定のプロセスでルートまたは `/core` のいずれかからインポートしてください。両方からインポートしないでください。これらは別のバンドルであり、両方を読み込むと Agent SDK のクラスと状態の 2 つのコピーが得られます。

66 

57<h2 id="functions">67<h2 id="functions">

58 関数68 関数

59</h2>69</h2>

87 戻り値97 戻り値

88</h4>98</h4>

89 99 

90[`Query`](#query-object) オブジェクトを返します。このオブジェクトは `AsyncGenerator<`[`SDKMessage`](#sdkmessage)`, void>` を拡張し、追加のメソッドを備えています。100[`Query`](#query-object) オブジェクトを返します。これは `AsyncGenerator<`[`SDKMessage`](#sdkmessage)`, void>` を拡張し、追加のメソッドを備えています。

91 101 

92<h3 id="startup">102<h3 id="startup">

93 `startup()`103 `startup()`

94</h3>104</h3>

95 105 

96CLI サブプロセスをプリウォームします。プロセスをスポーンし、プロンプトが利用可能になる前に初期化ハンドシェイクを完了します。返された [`WarmQuery`](#warmquery) ハンドルは後でプロンプトを受け入れ、既に準備ができているプロセスに書き込むため、最初の `query()` 呼び出しはサブプロセスのスポーンと初期化のコストを支払わずに解決します。106プロンプトが利用可能になる前に CLI サブプロセスをプリウォーミングします。これはサブプロセスを生成し、初期化ハンドシェイクを完了します。返された [`WarmQuery`](#warmquery) ハンドルは後でプロンプトを受け入れ、既に準備ができているプロセスに書き込むため、最初の `query()` 呼び出しはサブプロセスの生成と初期化コストをインラインで支払うことなく解決します。セッションの作業ディレクトリがまだわからない場合は、代わりに [`prewarm()`](#prewarm) を使用してください。

97 107 

98```typescript theme={null}108```typescript theme={null}

99function startup(params?: {109function startup(params?: {

109| パラメータ | 型 | 説明 |119| パラメータ | 型 | 説明 |

110| :- | :- | :- |120| :- | :- | :- |

111| `options` | [`Options`](#options) | オプションの設定オブジェクト。`query()` の `options` パラメータと同じです |121| `options` | [`Options`](#options) | オプションの設定オブジェクト。`query()` の `options` パラメータと同じです |

112| `initializeTimeoutMs` | `number` | サブプロセス初期化の待機時間の最大値（ミリ秒）。デフォルトは `60000` です。初期化が時間内に完了しない場合、プロミスはタイムアウトエラーで拒否されます |122| `initializeTimeoutMs` | `number` | サブプロセス初期化の完了を待つ最大時間（ミリ秒）。デフォルトは `60000` です。初期化が時間内に完了しない場合、プロミスはタイムアウトエラーで拒否されます |

113 123 

114<h4 id="returns-2">124<h4 id="returns-2">

115 戻り値125 戻り値

116</h4>126</h4>

117 127 

118サブプロセスがスポーンされ、初期化ハンドシェイクを完了したら解決する `Promise<`[`WarmQuery`](#warmquery)`>` を返します。128サブプロセスが生成され、初期化ハンドシェイクを完了したら解決する `Promise<`[`WarmQuery`](#warmquery)`>` を返します。

119 129 

120<h4 id="example">130<h4 id="example">

121 例131 例

122</h4>132</h4>

123 133 

124`startup()` を早期に呼び出します。例えば、アプリケーション起動時に呼び出し、プロンプトが準備できたら返されたハンドルで `.query()` を呼び出します。これにより、サブプロセスのスポーンと初期化をクリティカルパスから外します。134`startup()` を早期に呼び出します。たとえば、アプリケーション起動時に呼び出してから、プロンプトが準備できたら返されたハンドルで `.query()` を呼び出します。これにより、サブプロセスの生成と初期化をクリティカルパスから外します。

125 135 

126```typescript theme={null}136```typescript theme={null}

127import { startup } from "@anthropic-ai/claude-agent-sdk";137import { startup } from "@anthropic-ai/claude-agent-sdk";

135}145}

136```146```

137 147 

148<h3 id="prewarm">

149 `prewarm()`

150</h3>

151 

152*アルファ版。* どのセッションに対応するかわかる前に Claude Code プロセスをスペアとして開始します。後で [`claim()`](#spareprocess) を使用してセッションにバインドできます。ユーザーがフォルダを選択する前に起動するアプリケーションで使用します。TypeScript Agent SDK v0.3.282 以降が必要です。

153 

154`prewarm()` は [`startup()`](#startup) と同じ初期化ハンドシェイクを完了します。`options.cwd` を設定した場合はそのディレクトリで、それ以外の場合は Claude Code 設定ディレクトリの下のプライベート一時ディレクトリでプロセスが待機します。セッションの作業ディレクトリ、その `SessionStart` フック、その stdio MCP サーバー、その CLAUDE.md と git コンテキストはクレームを待ちます。スペアは待機中に約 230 ～ 260 MB のメモリを保持します。[`spawnClaudeCodeProcess`](#options) が別のマシンまたはコンテナで Claude Code を実行する場合は、`options.cwd` をそこに存在するディレクトリに設定して、スペアが待機するようにします。

155 

156```typescript theme={null}

157function prewarm(params?: {

158 options?: Options;

159 initializeTimeoutMs?: number;

160}): Promise<SpareProcess>;

161```

162 

163`options` と `initializeTimeoutMs` は `startup()` と同じ意味ですが、`options.cwd` はスペアが待機するディレクトリのみを設定します。プロミスはプロセスが初期化ハンドシェイクを完了したら [`SpareProcess`](#spareprocess) で解決します。`prewarm()` は `options` が `resume`、`continue`、または `forkSession` を設定する場合にスローします。スペアはまだセッションを持たないためです。クレームが設定できないすべてのもの（`mcpServers`、`hooks`、`canUseTool`、`settingSources`、`systemPrompt`、`plugins` など）はスペアの生涯にわたって固定されるため、これらのオプションの異なるセットごとに 1 つのスペアを保持し、それらが変更されたら再度プリウォームします。

164 

165<h4 id="example-2">

166 例

167</h4>

168 

169アプリケーション起動時にプリウォームしてから、ユーザーがセッションを開始したときにスペアをクレームします。

170 

171```typescript theme={null}

172import { prewarm } from "@anthropic-ai/claude-agent-sdk";

173 

174// アプリケーション起動時、セッションのフォルダがわかる前

175const spare = await prewarm({ options: { maxTurns: 3 } });

176 

177// 後で、ユーザーがフォルダでセッションを開始したら

178const claimedQuery = spare.claim({

179 prompt: "What files are here?",

180 options: { cwd: "/path/to/project" },

181});

182 

183spare.claimed.catch((error: Error) => {

184 // メッセージが「option_not_applied」で始まらない限り、プロンプトは実行されませんでした。

185 // 代わりにこのセッションを query() で開始してください

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

187});

188 

189for await (const message of claimedQuery) {

190 console.log(message);

191}

192```

193 

138<h3 id="tool">194<h3 id="tool">

139 `tool()`195 `tool()`

140</h3>196</h3>

161| `description` | `string` | ツールが何をするかの説明 |217| `description` | `string` | ツールが何をするかの説明 |

162| `inputSchema` | `Schema extends AnyZodRawShape` | ツールの入力パラメータを定義する Zod スキーマ（Zod 3 と Zod 4 の両方をサポート） |218| `inputSchema` | `Schema extends AnyZodRawShape` | ツールの入力パラメータを定義する Zod スキーマ（Zod 3 と Zod 4 の両方をサポート） |

163| `handler` | `(args, extra) => Promise<`[`CallToolResult`](#calltoolresult)`>` | ツールロジックを実行する非同期関数 |219| `handler` | `(args, extra) => Promise<`[`CallToolResult`](#calltoolresult)`>` | ツールロジックを実行する非同期関数 |

164| `extras` | `{ annotations?: `[`ToolAnnotations`](#toolannotations)`; searchHint?: string; alwaysLoad?: boolean }` | オプションの追加情報。`annotations` は MCP の動作ヒントをクライアントに提供します。`searchHint` は [ツール検索](/docs/ja/agent-sdk/tool-search) がアクティブな場合に遅延ツールリストに表示される 1 行の機能フレーズです。`alwaysLoad: true` はこのツールの完全なスキーマを初期プロンプトに保持し、遅延させません |220| `extras` | `{ annotations?: `[`ToolAnnotations`](#toolannotations)`; searchHint?: string; alwaysLoad?: boolean }` | オプションのエクストラ。`annotations` はクライアントに MCP 動作ヒントを提供します。`searchHint` は [ツール検索](/docs/ja/agent-sdk/tool-search) がアクティブな場合に遅延ツールリストに表示される 1 行の機能フレーズです。`alwaysLoad: true` はこのツールの完全なスキーマを初期プロンプトに保持し、遅延させません |

165 221 

166<h4 id="toolannotations">222<h4 id="toolannotations">

167 `ToolAnnotations`223 `ToolAnnotations`

168</h4>224</h4>

169 225 

170`@modelcontextprotocol/sdk/types.js` から再エクスポートされます。すべてのフィールドはオプションのヒントです。クライアントはセキュリティの決定にこれらに依存すべきではありません。226`@modelcontextprotocol/sdk/types.js` から再エクスポートされます。すべてのフィールドはオプションのヒントです。クライアントはセキュリティ決定のためにそれらに依存すべきではありません。

171 227 

172| フィールド | 型 | デフォルト | 説明 |228| フィールド | 型 | デフォルト | 説明 |

173| :- | :- | :- | :- |229| :- | :- | :- | :- |

175| `readOnlyHint` | `boolean` | `false` | `true` の場合、ツールはその環境を変更しません |231| `readOnlyHint` | `boolean` | `false` | `true` の場合、ツールはその環境を変更しません |

176| `destructiveHint` | `boolean` | `true` | `true` の場合、ツールは破壊的な更新を実行する可能性があります（`readOnlyHint` が `false` の場合のみ意味があります） |232| `destructiveHint` | `boolean` | `true` | `true` の場合、ツールは破壊的な更新を実行する可能性があります（`readOnlyHint` が `false` の場合のみ意味があります） |

177| `idempotentHint` | `boolean` | `false` | `true` の場合、同じ引数での繰り返し呼び出しは追加の効果がありません（`readOnlyHint` が `false` の場合のみ意味があります） |233| `idempotentHint` | `boolean` | `false` | `true` の場合、同じ引数での繰り返し呼び出しは追加の効果がありません（`readOnlyHint` が `false` の場合のみ意味があります） |

178| `openWorldHint` | `boolean` | `true` | `true` の場合、ツールは外部エンティティと相互作用します（例えば、Web 検索）。`false` の場合、ツールのドメインは閉じられています（例えば、メモリツール） |234| `openWorldHint` | `boolean` | `true` | `true` の場合、ツールは外部エンティティと相互作用します（たとえば、Web 検索）。`false` の場合、ツールのドメインは閉じられています（たとえば、メモリツール） |

179 235 

180```typescript theme={null}236```typescript theme={null}

181import { tool } from "@anthropic-ai/claude-agent-sdk";237import { tool } from "@anthropic-ai/claude-agent-sdk";

220| `options.instructions` | `string` | オプションのサーバー指示。`initialize` から返され、MCP 指示ブロックとしてモデルに表示されます |276| `options.instructions` | `string` | オプションのサーバー指示。`initialize` から返され、MCP 指示ブロックとしてモデルに表示されます |

221| `options.tools` | `Array<SdkMcpToolDefinition>` | [`tool()`](#tool) で作成されたツール定義の配列 |277| `options.tools` | `Array<SdkMcpToolDefinition>` | [`tool()`](#tool) で作成されたツール定義の配列 |

222| `options.alwaysLoad` | `boolean` | `true` の場合、このサーバーのすべてのツールは初期プロンプトに留まり、[ツール検索](/docs/ja/agent-sdk/tool-search) の背後で遅延されることはありません。[`tool()`](#tool) のツール単位の `alwaysLoad` と組み合わせます |278| `options.alwaysLoad` | `boolean` | `true` の場合、このサーバーのすべてのツールは初期プロンプトに留まり、[ツール検索](/docs/ja/agent-sdk/tool-search) の背後で遅延されることはありません。[`tool()`](#tool) のツール単位の `alwaysLoad` と組み合わせます |

223| `options.timeout` | `number` | このサーバーのツール呼び出しのタイムアウト（ミリ秒）。Claude Code はこれを [`MCP_TOOL_TIMEOUT`](/docs/ja/env-vars) の代わりにこのサーバーに適用します。1000 以上の整数を渡してください。Claude Code は他の値を無視します。TypeScript Agent SDK v0.3.248 以降が必要です |279| `options.timeout` | `number` | このサーバーのツール呼び出しのタイムアウト（ミリ秒）。Claude Code はこれを [`MCP_TOOL_TIMEOUT`](/docs/ja/env-vars) の代わりにこのサーバーに適用します。1000 以上の整数を渡します。Claude Code は他の値を無視します。TypeScript Agent SDK v0.3.248 以降が必要です |

224 280 

225<h3 id="listsessions">281<h3 id="listsessions">

226 `listSessions()`282 `listSessions()`

249| プロパティ | 型 | 説明 |305| プロパティ | 型 | 説明 |

250| :- | :- | :- |306| :- | :- | :- |

251| `sessionId` | `string` | 一意のセッション識別子（UUID） |307| `sessionId` | `string` | 一意のセッション識別子（UUID） |

252| `summary` | `string` | 表示タイトル：カスタムタイトル、自動生成されたサマリー、または最初のプロンプト |308| `summary` | `string` | 表示タイトル：カスタムタイトル、最新のプロンプト、自動生成されたサマリー、または最初のプロンプト |

253| `lastModified` | `number` | 最後に変更された時刻（エポック以降のミリ秒） |309| `lastModified` | `number` | エポック以降のミリ秒単位での最後の変更時刻 |

254| `fileSize` | `number \| undefined` | セッションファイルサイズ（バイト）。ローカル JSONL ストレージの場合のみ入力されます |310| `fileSize` | `number \| undefined` | セッションファイルサイズ（バイト）。ローカル JSONL ストレージの場合のみ入力されます |

255| `customTitle` | `string \| undefined` | ユーザーが設定したセッションタイトル（`/rename` 経由） |311| `customTitle` | `string \| undefined` | ユーザーが設定したセッションタイトル（`/rename` 経由） |

256| `firstPrompt` | `string \| undefined` | セッション内の最初の意味のあるユーザープロンプト |312| `firstPrompt` | `string \| undefined` | セッション内の最初の意味のあるユーザープロンプト |

257| `gitBranch` | `string \| undefined` | セッション終了時の git ブランチ |313| `gitBranch` | `string \| undefined` | セッション終了時の git ブランチ |

258| `cwd` | `string \| undefined` | セッションの作業ディレクトリ |314| `cwd` | `string \| undefined` | セッションの作業ディレクトリ |

259| `tag` | `string \| undefined` | ユーザーが設定したセッションタグ（[`tagSession()`](#tagsession) を参照） |315| `tag` | `string \| undefined` | ユーザーが設定したセッションタグ（[`tagSession()`](#tagsession) を参照） |

260| `createdAt` | `number \| undefined` | 作成時刻（エポック以降のミリ秒）。最初のエントリのタイムスタンプから |316| `createdAt` | `number \| undefined` | エポック以降のミリ秒単位での作成時刻。最初のエントリのタイムスタンプから |

261 317 

262<h4 id="example-2">318<h4 id="example-3">

263 例319 例

264</h4>320</h4>

265 321 

266プロジェクトの 10 個の最新セッションを出力します。結果は `lastModified` で降順にソートされるため、最初の項目が最新です。`dir` を省略すると、すべてのプロジェクト全体を検索します。322プロジェクトの 10 個の最新セッションを出力します。結果は `lastModified` の降順でソートされるため、最初のアイテムが最新です。`dir` を省略してすべてのプロジェクト全体を検索します。

267 323 

268```typescript theme={null}324```typescript theme={null}

269import { listSessions } from "@anthropic-ai/claude-agent-sdk";325import { listSessions } from "@anthropic-ai/claude-agent-sdk";

310| `session_id` | `string` | このメッセージが属するセッション |366| `session_id` | `string` | このメッセージが属するセッション |

311| `message` | `unknown` | トランスクリプトからの生のメッセージペイロード |367| `message` | `unknown` | トランスクリプトからの生のメッセージペイロード |

312| `parent_tool_use_id` | `string \| null` | サブエージェントメッセージの場合、サブエージェントを開始した `Agent` または `Skill` ツール呼び出しの `tool_use_id`。メインセッションメッセージと古いセッションの場合は `null` |368| `parent_tool_use_id` | `string \| null` | サブエージェントメッセージの場合、サブエージェントを開始した `Agent` または `Skill` ツール呼び出しの `tool_use_id`。メインセッションメッセージと古いセッションの場合は `null` |

313| `parent_agent_id` | `string \| null` | [ネストされたサブエージェント](/docs/ja/sub-agents#let-subagents-spawn-their-own-subagents) からのメッセージの場合、それをスポーンしたサブエージェントの `agentId`。メインセッションメッセージ、トップレベルサブエージェントからのメッセージ、および古いセッションの場合は `null`。Claude Code v2.1.202 以降が必要です |369| `parent_agent_id` | `string \| null` | [ネストされたサブエージェント](/docs/ja/sub-agents#let-subagents-spawn-their-own-subagents) からのメッセージの場合、それを生成したサブエージェントの `agentId`。メインセッションメッセージ、トップレベルサブエージェントからのメッセージ、および古いセッションの場合は `null`。Claude Code v2.1.202 以降が必要です |

314 370 

315<h4 id="example-3">371<h4 id="example-4">

316 例372 例

317</h4>373</h4>

318 374 

337 `getSessionInfo()`393 `getSessionInfo()`

338</h3>394</h3>

339 395 

340フルプロジェクトディレクトリスキャンなしで ID でシングルセッションのメタデータを読み取ります。396プロジェクトディレクトリ全体をスキャンせずに ID でシングルセッションのメタデータを読み取ります。

341 397 

342```typescript theme={null}398```typescript theme={null}

343function getSessionInfo(399function getSessionInfo(

352 408 

353| パラメータ | 型 | デフォルト | 説明 |409| パラメータ | 型 | デフォルト | 説明 |

354| :- | :- | :- | :- |410| :- | :- | :- | :- |

355| `sessionId` | `string` | 必須 | ルックアップするセッションの UUID |411| `sessionId` | `string` | 必須 | 検索するセッションの UUID |

356| `options.dir` | `string` | `undefined` | プロジェクトディレクトリパス。省略した場合、すべてのプロジェクトディレクトリを検索します |412| `options.dir` | `string` | `undefined` | プロジェクトディレクトリパス。省略した場合、すべてのプロジェクトディレクトリを検索します |

357 413 

358[`SDKSessionInfo`](#return-type-sdksessioninfo) を返すか、セッションが見つからない場合は `undefined` を返します。414[`SDKSessionInfo`](#return-type-sdksessioninfo) を返すか、セッションが見つからない場合は `undefined` を返します。

409 `resolveSettings()`465 `resolveSettings()`

410</h3>466</h3>

411 467 

412CLI をスポーンせずに、CLI と同じマージエンジンを使用して、指定されたディレクトリの有効な Claude Code 設定を解決します。`query()` 呼び出しを呼び出す前に、その呼び出しが何を見るかを検査するために使用します。468CLI と同じマージエンジンを使用して、Claude Code プロセスを生成せずに、指定されたディレクトリの有効な Claude Code 設定を解決します。`query()` 呼び出しを呼び出す前に、設定がどのような設定を見るかを検査するために使用します。

413 469 

414<Note>470<Note>

415 この関数はアルファ版であり、安定化前に API が変更される可能性があります。471 この関数はアルファ版であり、安定化前に API が変更される可能性があります。

416</Note>472</Note>

417 473 

418スナップショットはライブ `query()` セッションが適用するものと異なります：474スナップショットはライブ `query()` セッションが適用するものと異なります。

419 475 

420* **`policyHelper`**：`resolveSettings()` は macOS plist と Windows HKLM/HKCU を含む MDM ソースを読み取りますが、管理者が設定した `policyHelper` サブプロセスを実行しません。476* **`policyHelper`**：`resolveSettings()` は MDM ソース（macOS plist と Windows HKLM/HKCU を含む）を読み取りますが、管理者が設定した `policyHelper` サブプロセスを実行しません。

421* **サーバー管理設定**：`resolveSettings()` は [サーバー管理設定](/docs/ja/server-managed-settings#fetch-and-caching-behavior) をフェッチしません。それらを含めるには `options.serverManagedSettings` に渡してください。477* **サーバー管理設定**：`resolveSettings()` は [サーバー管理設定](/docs/ja/server-managed-settings#fetch-and-caching-behavior) をフェッチしません。それらを含めるには `options.serverManagedSettings` として渡します。

422* **`defaultMode`**：スナップショットは `permissions.defaultMode` をすべてのティアから現状のまま返すため、プロジェクトおよびローカル設定からの `'auto'` および `'bypassPermissions'` 値を含めることができます。これは [ライブセッションが無視する](/docs/ja/permission-modes#which-mode-a-session-starts-in) ものです。478* **`defaultMode`**：スナップショットは `permissions.defaultMode` をすべてのティアから現状のまま返すため、プロジェクトおよびローカル設定からの `'auto'` および `'bypassPermissions'` 値を含めることができます。これは [ライブセッションが無視する](/docs/ja/permission-modes#which-mode-a-session-starts-in) ものです。

423 479 

424```typescript theme={null}480```typescript theme={null}

436| パラメータ | 型 | デフォルト | 説明 |492| パラメータ | 型 | デフォルト | 説明 |

437| :- | :- | :- | :- |493| :- | :- | :- | :- |

438| `options.cwd` | `string` | `process.cwd()` | プロジェクトおよびローカル設定を相対的に解決するディレクトリ |494| `options.cwd` | `string` | `process.cwd()` | プロジェクトおよびローカル設定を相対的に解決するディレクトリ |

439| `options.settingSources` | [`SettingSource`](#settingsource)`[]` | すべてのソース | どのファイルシステムソースをロードするか。`[]` を渡してユーザー、プロジェクト、およびローカル設定をスキップします。[エンドポイント管理ポリシー](/docs/ja/managed-settings#delivery-mechanisms) はすべての場合にロードされます。`resolveSettings()` は `options.serverManagedSettings` を渡す場合のみサーバー管理設定を含めます |495| `options.settingSources` | [`SettingSource`](#settingsource)`[]` | すべてのソース | どのファイルシステムソースをロードするか。ユーザー、プロジェクト、およびローカル設定をスキップするには `[]` を渡します。[エンドポイント管理ポリシー](/docs/ja/managed-settings#delivery-mechanisms) はすべての場合にロードされます。`resolveSettings()` は `options.serverManagedSettings` を渡す場合のみサーバー管理設定を含めます |

440| `options.managedSettings` | `Settings` | `undefined` | 埋め込みホストによって提供されるポリシーティア設定。[`Options`](#options) の [`managedSettings`](/docs/ja/settings-reference) と同じルールに従います。ただし、`resolveSettings()` は設定された [`policyHelper`](/docs/ja/settings-reference) を実行しないため、スナップショットはライブセッションが削除する設定を含めることができます |496| `options.managedSettings` | `Settings` | `undefined` | 埋め込みホストによって提供されるポリシーティア設定。[`Options`](#options) の [`managedSettings`](#options) と同じルールに従います。ただし、`resolveSettings()` は設定された [`policyHelper`](/docs/ja/settings-reference#policyhelper) を実行しないため、スナップショットはライブセッションがドロップする設定を含めることができます |

441| `options.serverManagedSettings` | `Settings` | `undefined` | `/api/claude_code/settings` からのサーバー管理設定ペイロード。制限のないキーはフィルタリングなしで通過します |497| `options.serverManagedSettings` | `Settings` | `undefined` | `/api/claude_code/settings` からのサーバー管理設定ペイロード。制限のないキーはフィルタリングなしで通過します |

442 498 

443<h4 id="return-type-resolvedsettings">499<h4 id="return-type-resolvedsettings">

444 戻り値の型：`ResolvedSettings`500 戻り値の型：`ResolvedSettings`

445</h4>501</h4>

446 502 

447`resolveSettings()` はマージされた設定と各キーに貢献したソースを説明するオブジェクトを返します。503`resolveSettings()` はマージされた設定と各キーに寄与したソースを説明するオブジェクトを返します。

448 504 

449| プロパティ | 型 | 説明 |505| プロパティ | 型 | 説明 |

450| :- | :- | :- |506| :- | :- | :- |

451| `effective` | `Settings` | すべての有効なソースを優先順位順に適用した後のマージされた設定 |507| `effective` | `Settings` | すべての有効なソースを優先順位順に適用した後のマージされた設定 |

452| `provenance` | `Partial<Record<keyof Settings, ProvenanceEntry>>` | `effective` の各トップレベルキーについて、値を提供したソース |508| `provenance` | `Partial<Record<keyof Settings, ProvenanceEntry>>` | `effective` の各トップレベルキーについて、値を提供したソース |

453| `sources` | `Array<{ source, settings, path?, policyOrigin? }>` | ソースごとの生の設定。最も低い優先順位から最も高い優先順位の順に並べられています |509| `sources` | `Array<{ source, settings, path?, policyOrigin? }>` | ソースごとの生の設定。最も低い優先度から最も高い優先度の順に並べられています |

454 510 

455<h4 id="example-4">511<h4 id="example-5">

456 例512 例

457</h4>513</h4>

458 514 

459以下の例は、プロジェクトディレクトリの設定を解決し、クリーンアップ期間を制御するソースを出力します。設定ファイルが `cleanupPeriodDays` を設定していないマシンでは、両方の出力行は値に対して `undefined` を表示します。これはエラーではなく、予想される出力です。515以下の例はプロジェクトディレクトリの設定を解決し、クリーンアップ期間を制御するソースを出力します。設定ファイルが `cleanupPeriodDays` を設定しないマシンでは、両方の出力行は値に対して `undefined` を表示します。これはエラーではなく、予想される出力です。

460 516 

461```typescript theme={null}517```typescript theme={null}

462import { resolveSettings } from "@anthropic-ai/claude-agent-sdk";518import { resolveSettings } from "@anthropic-ai/claude-agent-sdk";

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

484| :- | :- | :- | :- |540| :- | :- | :- | :- |

485| `abortController` | `AbortController` | `new AbortController()` | 操作をキャンセルするためのコントローラー |541| `abortController` | `AbortController` | `new AbortController()` | 操作をキャンセルするためのコントローラー |

486| `additionalDirectories` | `string[]` | `[]` | Claude がアクセスできる追加ディレクトリ。SDK は各エントリを Claude Code に `--add-dir` として渡すため、`project` 設定ソースを使用すると Claude Code は[ディレクトリのスキル、コマンド、サブエージェントも読み込みます](/docs/ja/permissions#additional-directories-grant-file-access-not-configuration) |542| `additionalDirectories` | `string[]` | `[]` | Claude Code がアクセスできる追加ディレクトリ。SDK は各エントリを Claude Code に `--add-dir` として渡すため、`project` 設定ソースを使用すると Claude Code は [ディレクトリのスキル、コマンド、サブエージェントも読み込みます](/docs/ja/permissions#additional-directories-grant-file-access-not-configuration) |

487| `agent` | `string` | `undefined` | メインスレッドのエージェント名。エージェントは `agents` オプションまたは設定で定義する必要があります |543| `agent` | `string` | `undefined` | メインスレッドのエージェント名。エージェントは `agents` オプションまたは設定で定義されている必要があります |

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

489| `agentProgressSummaries` | `boolean` | `false` | `true` の場合、サブエージェントの 1 行の進捗サマリーを生成し、`summary` フィールド経由で [`task_progress`](#sdktaskprogressmessage) イベントで転送します。フォアグラウンドおよびバックグラウンドサブエージェントに適用されます |545| `agentProgressSummaries` | `boolean` | `false` | `true` の場合、サブエージェントの 1 行の進捗サマリーを生成し、`summary` フィールド経由で [`task_progress`](#sdktaskprogressmessage) イベントで転送します。フォアグラウンドおよびバックグラウンドサブエージェントに適用されます |

490| `allowDangerouslySkipPermissions` | `boolean` | `false` | 権限をバイパスできるようにします。`permissionMode: 'bypassPermissions'` を使用する場合に必須です。スタートアップ時または後で `setPermissionMode()` を通じて設定できます。[プランモード](/docs/ja/agent-sdk/permissions#plan-mode-plan)を参照して、`permissionMode: 'plan'` との相互作用を確認してください |546| `allowDangerouslySkipPermissions` | `boolean` | `false` | 権限をバイパスすることを有効にします。`permissionMode: 'bypassPermissions'` を使用する場合に必須です。スタートアップ時またはその後 `setPermissionMode()` を通じて設定できます。[plan mode](/docs/ja/agent-sdk/permissions#plan-mode-plan) で `permissionMode: 'plan'` との相互作用を確認してください |

491| `allowedTools` | `string[]` | `[]` | プロンプトなしで自動承認するツール。これは Claude をこれらのツールのみに制限しません。[タスク追跡ツール](/docs/ja/agent-sdk/todo-tracking#model-availability)の 1 つをここで指定すると、Claude Code もセッションをオプトインします。リストされていない他のツールは `permissionMode` と `canUseTool` にフォールスルーします。`disallowedTools` を使用してツールをブロックします。[権限](/docs/ja/agent-sdk/permissions#allow-and-deny-rules)を参照してください |547| `allowedTools` | `string[]` | `[]` | プロンプトなしで自動承認するツール。これは Claude をこれらのツールのみに制限しません。[タスク追跡ツール](/docs/ja/agent-sdk/todo-tracking#model-availability) の 1 つをここで指定すると、Claude Code もセッションをオプトインします。リストされていない他のツールは `permissionMode` と `canUseTool` にフォールスルーします。ツールをブロックするには `disallowedTools` を使用してください。[権限](/docs/ja/agent-sdk/permissions#allow-and-deny-rules) を参照してください |

492| `betas` | [`SdkBeta`](#sdkbeta)`[]` | `[]` | ベータ機能を有効にします |548| `betas` | [`SdkBeta`](#sdkbeta)`[]` | `[]` | ベータ機能を有効にします |

493| `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) を参照してください |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) を参照してください |

494| `continue` | `boolean` | `false` | 最新の会話を続行します |550| `continue` | `boolean` | `false` | 最新の会話を続行します |

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

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

497| `debugFile` | `string` | `undefined` | デバッグログを特定のファイルパスに書き込みます。暗黙的にデバッグモードを有効にします |553| `debugFile` | `string` | `undefined` | デバッグログを特定のファイルパスに書き込みます。暗黙的にデバッグモードを有効にします |

498| `disallowedTools` | `string[]` | `[]` | 拒否するツール。`"Bash"` のような単純な名前はツールを Claude のコンテキストから削除します。`"Bash(rm *)"` のようなスコープ付きルールはツールを利用可能なままにし、すべての権限モード（`bypassPermissions` を含む）で[書かれたとおりの](/docs/ja/permissions#bash-rule-limits)コマンドの一致する呼び出しを拒否します。[権限](/docs/ja/agent-sdk/permissions#allow-and-deny-rules)を参照してください |554| `disallowedTools` | `string[]` | `[]` | 拒否するツール。`"Bash"` のような単純な名前はツールを Claude のコンテキストから削除します。`"Bash(rm *)"` のようなスコープ付きルールはツールを利用可能なままにし、`bypassPermissions` を含むすべての権限モードで一致する呼び出しを拒否します。[書かれたとおりの](/docs/ja/permissions#bash-rule-limits) コマンドの場合です。[権限](/docs/ja/agent-sdk/permissions#allow-and-deny-rules) を参照してください |

499| `effort` | `'low' \| 'medium' \| 'high' \| 'xhigh' \| 'max'` | `undefined` | Claude がレスポンスに費やす努力の量を制御します。適応的思考と連携して思考の深さをガイドします。[努力レベルを調整](/docs/ja/model-config#adjust-effort-level)を参照してください |555| `effort` | `'low' \| 'medium' \| 'high' \| 'xhigh' \| 'max'` | `undefined` | Claude が応答に費やす努力の量を制御します。適応的思考と連携して思考の深さをガイドします。[努力レベルを調整](/docs/ja/model-config#adjust-effort-level) を参照してください |

500| `enableFileCheckpointing` | `boolean` | `false` | ファイル変更追跡を有効にして巻き戻しを可能にします。[ファイルチェックポイント](/docs/ja/agent-sdk/file-checkpointing)を参照してください |556| `enableFileCheckpointing` | `boolean` | `false` | ファイル変更追跡を有効にして巻き戻しを可能にします。[ファイルチェックポイント](/docs/ja/agent-sdk/file-checkpointing) を参照してください |

501| `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)を参照してください。`CLAUDE_AGENT_SDK_CLIENT_APP` を設定して User-Agent ヘッダーでアプリを識別します |557| `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` を設定してください |

502| `executable` | `'bun' \| 'deno' \| 'node'` | 自動検出 | 使用する JavaScript ランタイム |558| `executable` | `'bun' \| 'deno' \| 'node'` | 自動検出 | 使用する JavaScript ランタイム |

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

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

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

506| `forkSession` | `boolean` | `false` | `resume` で再開する場合、元のセッション ID を続行する代わりに新しいセッション ID にフォークします |562| `forkSession` | `boolean` | `false` | `resume` で再開する場合、元のセッション ID を続行するのではなく新しいセッション ID にフォークします |

507| `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 以降が必要です |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 以降が必要です |

508| `hooks` | `Partial<Record<`[`HookEvent`](#hookevent)`, `[`HookCallbackMatcher`](#hookcallbackmatcher)`[]>>` | `{}` | イベントのフックコールバック |564| `hooks` | `Partial<Record<`[`HookEvent`](#hookevent)`, `[`HookCallbackMatcher`](#hookcallbackmatcher)`[]>>` | `{}` | イベントのフックコールバック |

509| `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` を出力します |565| `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` を出力します |

510| `includePartialMessages` | `boolean` | `false` | 部分メッセージイベントを含めます |566| `includePartialMessages` | `boolean` | `false` | 部分メッセージイベントを含めます |

511| `loadTimeoutMs` | `number` | `60000` | *アルファ版。* 再開の具体化中に各 `sessionStore.load()` および `sessionStore.listSubkeys()` 呼び出しのタイムアウト（ミリ秒）。アダプターがこのウィンドウ内で解決しない場合、クエリはハングする代わりに失敗します。`sessionStore` が設定されていない場合は無視されます |567| `loadTimeoutMs` | `number` | `60000` | *アルファ。* 再開の具体化中に各 `sessionStore.load()` および `sessionStore.listSubkeys()` 呼び出しのタイムアウト（ミリ秒）。アダプターがこのウィンドウ内で解決しない場合、クエリはハングするのではなく失敗します。`sessionStore` が設定されていない場合は無視されます |

512| `managedSettings` | `Settings` | `undefined` | ホストプロセスがスポーンされたセッションに提供するポリシー層設定。管理者がデプロイした管理設定を持つマシンでは、管理者の最優先管理ソースが `parentSettingsBehavior: 'merge'` を設定しない限り、Claude Code はこれらを無視し、[`policyHelper`](/docs/ja/settings-reference#policyhelper) が管理設定を提供している間はマージしません。マージされた値は制限のみのフィルターを通過します。[親設定を制限](/docs/ja/claude-apps-gateway#restrict-parent-settings)はフィルターが許可するもの、および `allowManaged*Only` ロックをカバーします。[`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 エントリ |568| `managedSettings` | `Settings` | `undefined` | ホストプロセスがスポーンされたセッションに提供するポリシー層設定。管理者がデプロイした管理設定を持つマシンでは、管理者の最優先管理ソースが `parentSettingsBehavior: 'merge'` を設定しない限り、Claude Code はこれらを無視し、[`policyHelper`](/docs/ja/settings-reference#policyhelper) が管理設定を提供している間はマージしません。マージされた値は制限のみのフィルターを通過します。[親設定を制限](/docs/ja/claude-apps-gateway#restrict-parent-settings) はフィルターが許可するもの、および `allowManaged*Only` ロックをカバーします。[`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 エントリ |

513| `maxBudgetUsd` | `number` | `undefined` | クライアント側のコスト推定がこの USD 値に達したときにクエリを停止します。呼び出し自体の支出のみをカウントします。再開されたセッションから復元された合計はカウントされません。精度の注意事項とリセット動作については、[コストと使用状況を追跡](/docs/ja/agent-sdk/cost-tracking)を参照してください |569| `maxBudgetUsd` | `number` | `undefined` | クライアント側のコスト推定がこの USD 値に達したときにクエリを停止します。呼び出し自体の支出のみをカウントします。再開されたセッションから復元された合計はカウントされません。精度の注意事項とリセット動作については、[コストと使用状況を追跡](/docs/ja/agent-sdk/cost-tracking) を参照してください |

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

515| `maxTurns` | `number` | `undefined` | 最大エージェンティックターン数（ツール使用ラウンドトリップ） |571| `maxTurns` | `number` | `undefined` | 最大エージェンティックターン数（ツール使用ラウンドトリップ） |

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

517| `model` | `string` | CLI からのデフォルト | Claude モデルエイリアスまたは完全なモデル名。[受け入れられた値とプロバイダー固有の ID](/docs/ja/model-config#available-models) を参照してください |573| `model` | `string` | CLI のデフォルト | Claude モデルエイリアスまたは完全なモデル名。[受け入れられた値とプロバイダー固有の ID](/docs/ja/model-config#available-models) を参照してください |

518| `onElicitation` | `(request: ElicitationRequest, options: { signal: AbortSignal }) => Promise<ElicitationResult>` | `undefined` | MCP エリシテーションリクエストを処理するためのコールバック。MCP サーバーがユーザー入力をリクエストし、フックが最初に処理しない場合に呼び出されます。提供されない場合、未処理のエリシテーションリクエストは自動的に拒否されます |574| `onElicitation` | `(request: ElicitationRequest, options: { signal: AbortSignal }) => Promise<ElicitationResult>` | `undefined` | MCP 誘導リクエストを処理するためのコールバック。MCP サーバーがユーザー入力をリクエストし、フックが最初に処理しない場合に呼び出されます。提供されない場合、未処理の誘導リクエストは自動的に拒否されます |

519| `outputFormat` | `{ type: 'json_schema', schema: JSONSchema }` | `undefined` | エージェント結果の出力形式を定義します。詳細は[構造化出力](/docs/ja/agent-sdk/structured-outputs)を参照してください |575| `outputFormat` | `{ type: 'json_schema', schema: JSONSchema }` | `undefined` | エージェント結果の出力形式を定義します。詳細は [構造化出力](/docs/ja/agent-sdk/structured-outputs) を参照してください |

520| `outputStyle` | `string` | `undefined` | `Options` フィールドではありません。インライン [`settings`](/docs/ja/settings) オブジェクトまたは設定ファイルで `outputStyle` を設定してください。[出力スタイルを有効化](/docs/ja/agent-sdk/modifying-system-prompts#activate-an-output-style)を参照してください |576| `outputStyle` | `string` | `undefined` | `Options` フィールドではありません。インライン [`settings`](/docs/ja/settings) オブジェクトまたは設定ファイルで `outputStyle` を設定してください。[出力スタイルを有効化](/docs/ja/agent-sdk/modifying-system-prompts#activate-an-output-style) を参照してください |

521| `pathToClaudeCodeExecutable` | `string` | バンドルされたネイティブバイナリから自動解決 | Claude Code 実行可能ファイルへのパス。インストール中にオプション依存関係がスキップされた場合、またはプラットフォームがサポートセットにない場合にのみ必要です |577| `pathToClaudeCodeExecutable` | `string` | バンドルされたネイティブバイナリから自動解決 | Claude Code 実行可能ファイルへのパス。オプション依存関係がインストール中にスキップされた場合、またはプラットフォームがサポートされているセットにない場合にのみ必要です |

522| `permissionMode` | [`PermissionMode`](#permissionmode) | `'default'` | セッションの権限モード |578| `permissionMode` | [`PermissionMode`](#permissionmode) | `'default'` | セッションの権限モード |

523| `permissionPromptToolName` | `string` | `undefined` | 権限プロンプト用の MCP ツール名 |579| `permissionPromptToolName` | `string` | `undefined` | 権限プロンプト用の MCP ツール名 |

524| `permissionPrompts` | `'host' \| 'none'` | `'host'` | 権限プロンプトに応答するのは誰か: `'host'` はそれらを [`canUseTool`](#canusetool) コールバックまたは `permissionPromptToolName` ツールにルーティングし、`'none'` は[プロンプトが表示されるはずだった呼び出しを拒否](/docs/ja/agent-sdk/permissions#how-permissions-are-evaluated)します。Claude Code v2.1.259 以降が必要です |580| `permissionPrompts` | `'host' \| 'none'` | `'host'` | 権限プロンプトに応答するのは誰か: `'host'` はそれらを [`canUseTool`](#canusetool) コールバックまたは `permissionPromptToolName` ツールにルーティングし、`'none'` は [プロンプトが表示されるはずだった呼び出しを拒否](/docs/ja/agent-sdk/permissions#how-permissions-are-evaluated) します。Claude Code v2.1.259 以降が必要です |

525| `persistSession` | `boolean` | `true` | `false` の場合、ディスクへのセッション永続化を無効にします。セッションは後で再開できません |581| `persistSession` | `boolean` | `true` | `false` の場合、セッションのディスクへの永続化を無効にします。セッションは後で再開できません |

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

527| `plugins` | [`SdkPluginConfig`](#sdkpluginconfig)`[]` | `[]` | ローカルパスからカスタムプラグインを読み込みます。詳細は[プラグイン](/docs/ja/agent-sdk/plugins)を参照してください |583| `plugins` | [`SdkPluginConfig`](#sdkpluginconfig)`[]` | `[]` | ローカルパスからカスタムプラグインを読み込みます。詳細は [プラグイン](/docs/ja/agent-sdk/plugins) を参照してください |

528| `projectConfigRoot` | `string` | `undefined` | `cwd` がワークツリーである信頼できるチェックアウトの絶対パス。Claude Code はプロジェクト設定、`.mcp.json`、およびプロジェクトの `.claude/` コマンド、エージェント、スキル、ワークフロー、ルーチン、出力スタイルを `cwd` ではなくこのディレクトリから読み込み、`CLAUDE_PROJECT_DIR` をそれに設定します。フック、`apiKeyHelper` などのヘルパースクリプト、および stdio MCP サーバーはこのディレクトリを作業ディレクトリとして開始します。`CLAUDE.md` ファイルと `.claude/rules/` は引き続き `cwd` から読み込まれます。Claude Code v2.1.275 以降が必要です |584| `projectConfigRoot` | `string` | `undefined` | `cwd` がワークツリーである信頼できるチェックアウトの絶対パス。Claude Code はプロジェクト設定、`.mcp.json`、およびプロジェクトの `.claude/` コマンド、エージェント、スキル、ワークフロー、ルーチン、および出力スタイルを `cwd` ではなくこのディレクトリから読み込み、`CLAUDE_PROJECT_DIR` をそれに設定します。フック、`apiKeyHelper` などのヘルパースクリプト、および stdio MCP サーバーはこのディレクトリをワーキングディレクトリとして開始します。`CLAUDE.md` ファイルと `.claude/rules/` は引き続き `cwd` から読み込まれます。Claude Code v2.1.275 以降が必要です |

529| `promptSuggestions` | `boolean` | `false` | プロンプト提案を有効にします。ターン後、Claude Code は予測される次のユーザープロンプトを含む `prompt_suggestion` メッセージを出力します。アカウントが使用制限に近い、または達している場合など、一部のターンでは Claude Code は提案を生成しません。[Claude Code が提案をスキップする場合](/docs/ja/interactive-mode#when-claude-code-skips-suggestions)を参照してください |585| `promptSuggestions` | `boolean` | `false` | プロンプト提案を有効にします。ターン後、Claude Code は予測される次のユーザープロンプトを含む `prompt_suggestion` メッセージを出力します。アカウントが使用制限に近い、または達している場合など、一部のターンでは Claude Code は提案を生成しません。[Claude Code が提案をスキップする場合](/docs/ja/interactive-mode#when-claude-code-skips-suggestions) を参照してください |

530| `resume` | `string` | `undefined` | 再開するセッション ID |586| `resume` | `string` | `undefined` | 再開するセッション ID |

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

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

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

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

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

536| `sessionStoreFlush` | `'batched' \| 'eager'` | `'batched'` | *アルファ版。* `sessionStore` のフラッシュモード。`sessionStore` が設定されていない場合は無視されます |592| `sessionStoreFlush` | `'batched' \| 'eager'` | `'batched'` | *アルファ。* `sessionStore` のフラッシュモード。`sessionStore` が設定されていない場合は無視されます |

537| `settings` | `string \| Settings` | `undefined` | インライン [settings](/docs/ja/settings) オブジェクト、設定ファイルパス、またはインライン JSON 文字列。[優先順位](/docs/ja/settings#settings-precedence)のフラグ設定層を入力します。[`applyFlagSettings()`](#applyflagsettings) で実行時に変更します |593| `settings` | `string \| Settings` | `undefined` | インライン [settings](/docs/ja/settings) オブジェクト、設定ファイルパス、またはインライン JSON 文字列。[優先順位](/docs/ja/settings#settings-precedence) でフラグ設定層を入力します。[`applyFlagSettings()`](#applyflagsettings) で実行時に変更します |

538| `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)を参照してください |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) を参照してください |

539| `skills` | `string[] \| 'all'` | `undefined` | セッションで利用可能なスキル。すべての検出されたスキルを有効にするには `'all'` を渡すか、スキル名のリストを渡します。正確な名前のみを渡してください。Agent SDK v0.3.221 以降では、SDK は形式が正しくないワイルドカード形式の名前を Claude Code プロセスを開始する前にエラーで拒否します。設定すると、SDK は Skill ツールを `allowedTools` に自動的に追加します。`tools` も渡す場合は、そのリストに `'Skill'` を含めてください。[スキル](/docs/ja/agent-sdk/skills)を参照してください |595| `skills` | `string[] \| 'all'` | `undefined` | セッションで利用可能なスキル。すべての検出されたスキルを有効にするには `'all'` を渡すか、スキル名のリストを渡します。正確な名前のみを渡してください。Agent SDK v0.3.221 以降では、SDK は Claude Code プロセスを開始する前に、形式が正しくないワイルドカードフォーム名をエラーで拒否します。設定すると、SDK は Skill ツールを `allowedTools` に自動的に追加します。`tools` も渡す場合は、そのリストに `'Skill'` を含めてください。[スキル](/docs/ja/agent-sdk/skills) を参照してください |

540| `spawnClaudeCodeProcess` | `(options: SpawnOptions) => SpawnedProcess` | `undefined` | Claude Code プロセスをスポーンするカスタム関数。VM、コンテナ、またはリモート環境で Claude Code を実行するために使用します |596| `spawnClaudeCodeProcess` | `(options: SpawnOptions) => SpawnedProcess` | `undefined` | Claude Code プロセスをスポーンするカスタム関数。VM、コンテナ、またはリモート環境で Claude Code を実行するために使用します |

541| `stderr` | `(data: string) => void` | `undefined` | stderr 出力のコールバック |597| `stderr` | `(data: string) => void` | `undefined` | stderr 出力のコールバック |

542| `strictMcpConfig` | `boolean` | `false` | `mcpServers` で渡されたサーバーのみを使用し、プロジェクト `.mcp.json`、ユーザー設定、プラグイン提供の MCP サーバー、および [claude.ai コネクタ](/docs/ja/mcp#use-mcp-servers-from-claude-ai)を無視します |598| `strictMcpConfig` | `boolean` | `false` | `mcpServers` で渡されたサーバーのみを使用し、プロジェクト `.mcp.json`、ユーザー設定、プラグイン提供の MCP サーバー、および [claude.ai コネクタ](/docs/ja/mcp#use-mcp-servers-from-claude-ai) を無視します |

543| `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 以降が必要です |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` を設定します。カスタムプロンプトで `snapshot` を設定するには、`{ type: 'custom', prompt }` 形式を渡します。`{ type: 'custom' }` 形式と `snapshot` フィールドには TypeScript Agent SDK v0.3.257 以降が必要です |

544| `taskBudget` | `{ total: number }` | `undefined` | *アルファ版。* API 側のタスク予算（トークン）。設定すると、モデルに残りのトークン予算が通知されるため、ツール使用のペースを調整し、制限前にラップアップできます |600| `taskBudget` | `{ total: number }` | `undefined` | *アルファ。* API 側のタスク予算（トークン）。設定すると、モデルは残りのトークン予算を通知され、ツール使用のペースを調整し、制限前にラップアップできます |

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

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

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

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

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

550 607 

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

552 遅いまたは停止した API レスポンスを処理609 遅いまたは停止した API レスポンスを処理

553</h4>610</h4>

554 611 

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

556 613 

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

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

571```628```

572 629 

573* `API_TIMEOUT_MS`: Anthropic クライアントのリクエストごとのタイムアウト（ミリ秒）。デフォルト `600000`。メインループとすべてのサブエージェントに適用されます。630* `API_TIMEOUT_MS`: Anthropic クライアントのリクエストごとのタイムアウト（ミリ秒）。デフォルト `600000`。メインループとすべてのサブエージェントに適用されます。

574* `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` に引き上げ、この変数の上限を削除します。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` に引き上げ、この変数のキャップを削除します。

575* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`: サブエージェント用のスタールウォッチドッグ。ストリームウォッチドッグがオンの場合、デフォルトは `CLAUDE_STREAM_IDLE_TIMEOUT_MS` プラス 5 分で、その変数を引き上げない限り `600000` になります。ストリームウォッチドッグがオフの場合、デフォルトは `600000` です。v2.1.257 より前では、デフォルトは常に `600000` でした。632* `CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS`: サブエージェント用のスタール監視犬。ストリーム監視犬がオンの場合、デフォルトは `CLAUDE_STREAM_IDLE_TIMEOUT_MS` プラス 5 分で、その変数を引き上げない限り `600000` になります。ストリーム監視犬がオフの場合、デフォルトは `600000` です。v2.1.257 より前では、デフォルトは常に `600000` でした。

576 633 

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

578* `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 が何をするかをカバーします。635* `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 が何をするかをカバーします。

579 636 

580 `ANTHROPIC_BASE_URL` の背後にあるゲートウェイがキープアライブピングで開いたままにしているレスポンスをウォッチドッグが待機している間、`includePartialMessages` を設定するホストは `ping` [ストリームイベント](#sdkpartialassistantmessage)を受け取り続けるため、これらのフレームを沈黙でセッションをタイムアウトするのではなく活性度として読み込んでください。v2.1.257 より前では、フレームは最後の実際のストリームイベントから 5 分後に停止しました。637 監視犬が `ANTHROPIC_BASE_URL` の背後にあるゲートウェイが保持するレスポンスをキープアライブピングで待機している間、`includePartialMessages` を設定するホストは `ping` [ストリームイベント](#sdkpartialassistantmessage) を受け取り続けるため、これらのフレームを実時間として読み取り、最後の実ストリームイベントから 5 分後のサイレンスでセッションをタイムアウトしないでください。v2.1.257 より前では、フレームは停止しました。

581 638 

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

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

617 path: string,674 path: string,

618 options?: { maxBytes?: number; encoding?: 'utf-8' | 'base64' }675 options?: { maxBytes?: number; encoding?: 'utf-8' | 'base64' }

619 ): Promise<SDKControlReadFileResponse | null>;676 ): Promise<SDKControlReadFileResponse | null>;

677 reloadPlugins(options?: {

678 holdOnCacheImpact?: boolean;

679 }): Promise<SDKControlReloadPluginsResponse>;

620 reloadSkills(): Promise<SDKControlReloadSkillsResponse>;680 reloadSkills(): Promise<SDKControlReloadSkillsResponse>;

681 reloadOutputStyles(): Promise<SDKControlReloadOutputStylesResponse>;

621 accountInfo(): Promise<AccountInfo>;682 accountInfo(): Promise<AccountInfo>;

622 reconnectMcpServer(serverName: string): Promise<void>;683 reconnectMcpServer(serverName: string): Promise<void>;

623 toggleMcpServer(serverName: string, enabled: boolean): Promise<void>;684 toggleMcpServer(serverName: string, enabled: boolean): Promise<void>;

635 696 

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

637| :- | :- |698| :- | :- |

638| `interrupt()` | クエリを中断します。ストリーミング入力モードでのみ利用可能です。CLI が [`SDKSystemMessage.capabilities`](#sdksystemmessage) で `interrupt_receipt_v1` 機能をアドバタイズする場合、中断が到着したときに保留中だったメッセージをリストする [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse) で解決します。v2.1.205 より前の CLI では `undefined` で解決します |699| `interrupt()` | クエリを中断します。ストリーミング入力モードでのみ利用可能です。CLI が [`SDKSystemMessage.capabilities`](#sdksystemmessage) で `interrupt_receipt_v1` 機能をアドバタイズする場合、中断が到着したときに保留中だった [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse) メッセージをリストして解決します。v2.1.205 より前の CLI では `undefined` に解決します |

639| `rewindFiles(userMessageId, options?)` | ファイルを指定されたユーザーメッセージの状態に復元します。変更をプレビューするには `{ dryRun: true }` を渡します。`enableFileCheckpointing: true` が必要です。[ファイルチェックポイント](/docs/ja/agent-sdk/file-checkpointing)を参照してください |700| `rewindFiles(userMessageId, options?)` | ファイルを指定されたユーザーメッセージの状態に復元します。変更をプレビューするには `{ dryRun: true }` を渡します。`enableFileCheckpointing: true` が必要です。[ファイルチェックポイント](/docs/ja/agent-sdk/file-checkpointing) を参照してください |

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

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

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

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

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

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

646| `reinitialize()` | 実行中の CLI に `initialize` 制御リクエストを再送信し、キャッシュされた最初の接続結果の代わりに新しい結果を返します。トランスポートギャップ後（切断後のセッションへの再接続など）に使用して、保留中の権限リクエストが `canUseTool` コールバックに再度到達するようにします。コールバックをリクエスト ID ごとにべき等にしてください。応答が失われたリクエストは再度ディスパッチされるためです。Claude Code v2.1.195 以降が必要です |707| `reinitialize()` | 実行中の CLI に `initialize` 制御リクエストを再送信し、キャッシュされた最初の接続結果の代わりに新しい結果を返します。トランスポートギャップ後（セッションへの再接続後など）に使用して、保留中の権限リクエストが `canUseTool` コールバックに再度到達するようにします。リクエスト ID ごとにコールバックをべき等にしてください。応答が失敗したリクエストは再度ディスパッチされるためです。Claude Code v2.1.195 以降が必要です |

647| `supportedCommands()` | 利用可能なコマンドを返します。Agent SDK v0.3.216 からリストは中セッションコマンド変更を反映します。[`SDKCommandsChangedMessage`](#sdkcommandschangedmessage) を参照してください |708| `supportedCommands()` | 利用可能なコマンドを返します。Agent SDK v0.3.216 からリストはミッドセッションコマンド変更を反映します。[`SDKCommandsChangedMessage`](#sdkcommandschangedmessage) を参照してください |

648| `supportedModels()` | 表示情報を含む利用可能なモデルを返します |709| `supportedModels()` | 表示情報を含む利用可能なモデルを返します |

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

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

651| `getContextUsage(opts?)` | セッションのコンテキストウィンドウ使用状況をカテゴリ、スキル、ツール別に分類する [`SDKControlGetContextUsageResponse`](#sdkcontrolgetcontextusageresponse) を返します。デフォルト `detail` では、インタラクティブセッションで `/context` が表示するのと同じデータです。[`detail` オプション](#sdkcontrolgetcontextusageresponse)には Agent SDK v0.3.257 以降が必要です |712| `getContextUsage(opts?)` | セッションのコンテキストウィンドウ使用状況をカテゴリ、スキル、ツール別に分類した [`SDKControlGetContextUsageResponse`](#sdkcontrolgetcontextusageresponse) を返します。デフォルト `detail` では、対話型セッションで `/context` が表示するのと同じデータです。[`detail` オプション](#sdkcontrolgetcontextusageresponse) には Agent SDK v0.3.257 以降が必要です |

652| `readFile(path, options?)` | セッションのファイルシステムからファイルを読み込みます。Claude Code は `cwd` に対してパスを解決します。[`readFile()` が読み込める内容](#what-readfile-can-read)は提供するファイルをリストします。読み込みキャップを変更するには `{ maxBytes }` を渡します（デフォルト 1 MB、上限 10 MB）。画像などのバイナリファイルの場合は `{ encoding: 'base64' }` を渡します。[`SDKControlReadFileResponse`](#sdkcontrolreadfileresponse) で解決するか、権限拒否、ファイル欠落、またはトランスポートエラーで `null` で解決します。TypeScript SDK v0.2.121 以降が必要です |713| `readFile(path, options?)` | セッションのファイルシステムからファイルを読み取ります。Claude Code は `cwd` に対してパスを解決します。[`readFile()` が読み取れるもの](#what-readfile-can-read) は提供するファイルをリストします。読み取りキャップを変更するには `{ maxBytes }` を渡します（デフォルト 1 MB、上限 10 MB）。画像などのバイナリファイルの場合は `{ encoding: 'base64' }` を渡します。[`SDKControlReadFileResponse`](#sdkcontrolreadfileresponse) で解決するか、権限拒否、ファイルの欠落、またはトランスポートエラーの場合は `null` で解決します。TypeScript SDK v0.2.121 以降が必要です |

653| `reloadSkills()` | ディスクからスキルを再読み込みして、中セッションで追加または編集したスキルが実行中のセッションで利用可能になるようにします。再読み込み後に利用可能なスキルをリストする [`SDKControlReloadSkillsResponse`](#sdkcontrolreloadskillsresponse) で解決します。Agent SDK v0.3.163 以降が必要です |714| `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 以降が必要です |

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

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

655| `reconnectMcpServer(serverName)` | MCP サーバーを名前で再接続します。名前が `.mcp.json` または `~/.claude.json` などの設定ファイルのエントリとも一致する場合、Claude Code は設定ファイルエントリではなく、[`mcpServers`](#options) または `setMcpServers()` を通じて設定したサーバーを再接続します。その解決順序には Claude Code v2.1.257 以降が必要です |718| `reconnectMcpServer(serverName)` | MCP サーバーを名前で再接続します。名前が `.mcp.json` または `~/.claude.json` などの設定ファイルのエントリとも一致する場合、Claude Code は [`mcpServers`](#options) または `setMcpServers()` を通じて設定したサーバーを再接続し、設定ファイルエントリではありません。その解決順序には Claude Code v2.1.257 以降が必要です |

656| `toggleMcpServer(serverName, enabled)` | `reconnectMcpServer()` と同じ名前解決で、MCP サーバーを名前で有効または無効にします。無効にするとサーバーが切断されます |719| `toggleMcpServer(serverName, enabled)` | `reconnectMcpServer()` と同じ名前解決で MCP サーバーを名前で有効または無効にします。無効にするとサーバーが切断されます |

657| `setMcpServers(servers)` | このセッションの MCP サーバーセットを動的に置き換えます。追加および削除されたサーバーと任意のエラーを指定する [`McpSetServersResult`](#mcpsetserversresult) で解決します |720| `setMcpServers(servers)` | このセッションの MCP サーバーセットを動的に置き換えます。追加および削除されたサーバーと任意のエラーを指定する [`McpSetServersResult`](#mcpsetserversresult) で解決します |

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

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

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

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

662 725 

664 `applyFlagSettings()`727 `applyFlagSettings()`

665</h4>728</h4>

666 729 

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

731 

732一部のキーのみがミッドセッション中に有効になります:

668 733 

669一部のキーのみが中セッションで有効になります:734* **次のターンで適用**: `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 より前では、ミッドターンスイッチは次のターンを待機していました。

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

670 737 

671* **次のターンで適用**: `effortLevel`、`ultracode`、`permissions`、`hooks`、`skillOverrides`、`fastMode`、`agent`。`agent` を切り替えると、そのエージェントのモデル上書きとフックも次のターンで適用されます。そのシステムプロンプトは次のターンで、または[記録されたシステムプロンプトを再利用](/docs/ja/agent-sdk/modifying-system-prompts#change-the-prompt-of-an-existing-session)するセッションではセッションがコンパクト化されると適用されます。738`effortLevel` は [努力レベル](/docs/ja/model-config#adjust-effort-level) 名を受け入れます。また、`"ultracode"` も受け入れます。これは [ultracode](/docs/ja/workflows#let-claude-decide-with-ultracode) を使用した `xhigh` 努力をリクエストします。`applyFlagSettings()` は `effortLevel` をその値なしで宣言するため、TypeScript で同等の `{ ultracode: true, effortLevel: "xhigh" }` を渡すか、[`ultracode`](/docs/ja/settings-reference#ultracode) キーのみを渡して、セッションの現在の努力レベルで ultracode をオンにしてください。`ultracode` 値には Claude Code v2.1.203 以降が必要で、設定ファイルの `effortLevel` キーではなく `applyFlagSettings()` によってのみ受け入れられます。v2.1.284 より前では、`ultracode` キーのみもレベルを `xhigh` に設定していました。

672* **現在のターン中に適用**: `model`。Claude がターンで作業している間に `model` を切り替える場合、Claude が既に生成しているレスポンスは古いモデルで完了し、ターンの残り（Claude Code がモデルに対して行う次の呼び出しから始まる）は新しいモデルを使用します。サブエージェントは独自のモデルを保持します。v2.1.212 より前では、中ターン切り替えは次のターンを待機していました。

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

674 739 

675`effortLevel` は[努力レベル](/docs/ja/model-config#adjust-effort-level)名を受け入れます。また、`"ultracode"` も受け入れます。これは [ultracode](/docs/ja/workflows#let-claude-decide-with-ultracode) を使用した `xhigh` 努力をリクエストします。`applyFlagSettings()` は `effortLevel` をその値なしで宣言するため、TypeScript で同等の `{ ultracode: true }` を渡してください。`ultracode` 値には Claude Code v2.1.203 以降が必要で、`applyFlagSettings()` でのみ受け入れられ、設定ファイルの `effortLevel` キーでは受け入れられません。740値はフラグ設定層に書き込まれ、`query()` の `settings` オプションがスタートアップで設定したものにマージされます。これは [ページ上の優先順位セクション](#settings-precedence) がプログラムオプションと呼ぶのと同じ層です。

676 741 

677値はフラグ設定層に書き込まれます。これは `query()` のインライン `settings` オプションがスタートアップで入力するのと同じ層です。これは[オンページ優先順位セクション](#settings-precedence)がプログラムオプションと呼ぶのと同じ層です。742連続した呼び出しは最上位キーを浅くマージします。`{ permissions: {...} }` を含む 2 番目の呼び出しは、前の呼び出しから `permissions` オブジェクト全体を置き換え、深くマージするのではなく置き換えます。

678 743 

679連続した呼び出しは最上位レベルキーをシャローマージします。`{ permissions: {...} }` を含む 2 番目の呼び出しは、前の呼び出しからの `permissions` オブジェクト全体を深くマージするのではなく置き換えます。フラグ層からキーをクリアするには、そのキーに `null` を渡します。ほとんどのキーはその後、低優先度ソースにフォールバックします。クリアされた `model` は、設定ファイルが `model` を設定している場合でも、[Claude Code のデフォルトモデル](/docs/ja/model-config)にリセットされます。`undefined` を渡すと JSON シリアル化がそれをドロップするため効果がありません。744`applyFlagSettings()` で設定したキーをクリアするには、そのキーに `null` を渡します。ほとんどのキーは、最初に `query()` の `settings` オプションで設定された値にフォールバックし、次に低優先度ソースにフォールバックします。クリアされた `model` は、設定ファイルが `model` を設定している場合でも、[Claude Code のデフォルトモデル](/docs/ja/model-config) にリセットされます。`undefined` を渡すと JSON シリアル化がそれをドロップするため効果がありません。

680 745 

681`model` 以外の 3 つのキーはセッション状態をリセットする代わりにフォールバックします:746`model` 以外の 3 つのキーはフォールバックする代わりにセッション状態をリセットします:

682 747 

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

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

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

686 751 

687ストリーミング入力モードでのみ利用可能です。これは `setModel()` と `setPermissionMode()` と同じ制約です。752ストリーミング入力モードでのみ利用可能で、`setModel()` と `setPermissionMode()` と同じ制約があります。

688 753 

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

690 755 

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

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

693 758 

694const q = query({ prompt: messageStream });759const q = query({ prompt: messageStream });

695 760 

696// Override the model for the rest of the session761// セッションの残りの部分のモデルをオーバーライドします

697await q.applyFlagSettings({ model: "claude-opus-4-6" });762await q.applyFlagSettings({ model: "claude-opus-4-6" });

698 763 

699// Later: clear the override; the model resets to Claude Code's default764// 後で: オーバーライドをクリアします。モデルは Claude Code のデフォルトにリセットされます

700await q.applyFlagSettings({ model: null });765await q.applyFlagSettings({ model: null });

701```766```

702 767 

708 `updateSettings()`773 `updateSettings()`

709</h4>774</h4>

710 775 

711設定ファイルにホワイトリストキーを書き込み、値が後のセッションで永続化されるようにします。各ソースは 1 つのキーを受け入れます。文字列値を持ちます:776設定ファイルをディスクに 1 つのホワイトリスト登録キーを書き込み、値が後のセッションで永続化されるようにします。各ソースは 1 つのキーを受け入れ、文字列値を持ちます:

712 777 

713* **`"localSettings"`**: `outputStyle` を受け入れ、プロジェクトのローカル設定ファイル `.claude/settings.local.json` にマージします。新しいスタイルはセッションの次のリクエストで有効になります。778* **`"localSettings"`**: `outputStyle` を受け入れ、プロジェクトのローカル設定ファイル `.claude/settings.local.json` にマージします。新しいスタイルはセッションの次のリクエストで有効になります。

714* **`"userSettings"`**: `effortLevel` を受け入れ、セッションの現在のモデルのデフォルト[努力レベル](/docs/ja/model-config#adjust-effort-level)としてユーザー設定ファイルの [`modelSettings`](/docs/ja/settings-reference#modelsettings) の下に保存します。`max` を渡すと、`max` はセッションのみであるため何も書き込みません。実行中のセッションは現在の努力レベルをどちらにしても保持するため、変更したい場合は [`applyFlagSettings()`](#applyflagsettings) を呼び出します。このソースには TypeScript SDK v0.3.277 以降が必要で、Claude Code v2.1.277 をバンドルしています。779* **`"userSettings"`**: `effortLevel` を受け入れ、セッションの現在のモデルのデフォルト [努力レベル](/docs/ja/model-config#adjust-effort-level) としてユーザー設定ファイルの [`modelSettings`](/docs/ja/settings-reference#modelsettings) に保存します。`max` を渡すと、`max` はセッションのみであるため何も書き込みません。実行中のセッションはいずれにせよ現在の努力レベルを保持するため、それも変更したい場合は [`applyFlagSettings()`](#applyflagsettings) を呼び出してください。このソースには TypeScript SDK v0.3.277 以降が必要で、Claude Code v2.1.277 をバンドルしています。

715 780 

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

717 782 

718<h3 id="warmquery">783<h3 id="warmquery">

719 `WarmQuery`784 `WarmQuery`

720</h3>785</h3>

721 786 

722[`startup()`](#startup) によって返されるハンドル。サブプロセスは既にスポーンおよび初期化されているため、このハンドルで `query()` を呼び出すと、スタートアップレイテンシーなしで準備完了プロセスにプロンプトを直接書き込みます。787[`startup()`](#startup) によって返されるハンドル。サブプロセスは既にスポーンされ初期化されているため、このハンドルで `query()` を呼び出すと、スタートアップレイテンシーなしで準備完了プロセスにプロンプトを直接書き込みます。

723 788 

724```typescript theme={null}789```typescript theme={null}

725interface WarmQuery extends AsyncDisposable {790interface WarmQuery extends AsyncDisposable {

735| メソッド | 説明 |800| メソッド | 説明 |

736| :- | :- |801| :- | :- |

737| `query(prompt)` | 事前ウォーミングされたサブプロセスにプロンプトを送信し、[`Query`](#query-object) を返します。`WarmQuery` ごとに 1 回のみ呼び出すことができます |802| `query(prompt)` | 事前ウォーミングされたサブプロセスにプロンプトを送信し、[`Query`](#query-object) を返します。`WarmQuery` ごとに 1 回のみ呼び出すことができます |

738| `close()` | プロンプトを送信せずにサブプロセスを閉じます。不要になった暖かいクエリを破棄するために使用します |803| `close()` | プロンプトを送信せずにサブプロセスを閉じます。不要になった warm query を破棄するために使用します |

739 804 

740`WarmQuery` は `AsyncDisposable` を実装するため、自動クリーンアップのために `await using` で使用できます。805`WarmQuery` は `AsyncDisposable` を実装するため、自動クリーンアップのために `await using` で使用できます。

741 806 

807<h3 id="spareprocess">

808 `SpareProcess`

809</h3>

810 

811*アルファ。* [`prewarm()`](#prewarm) によって返されるハンドル: セッションにまだバインドされていない開始された Claude Code プロセスで、1 回クレームできます。TypeScript Agent SDK v0.3.282 以降が必要です。

812 

813```typescript theme={null}

814interface SpareProcess extends AsyncDisposable {

815 claim(params: {

816 prompt: string | AsyncIterable<SDKUserMessage>;

817 options: ClaimOptions;

818 }): Query;

819 readonly claimed: Promise<{ cwd: string; sessionId: string; parkedMs?: number; sdkMcpSettled: boolean }>;

820 readonly exited: Promise<void>;

821 close(): void;

822}

823```

824 

825<h4 id="members">

826 メンバー

827</h4>

828 

829| メンバー | 説明 |

830| :- | :- |

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

832| `claimed` | Claude Code がクレームを受け入れると、セッションのワーキングディレクトリと ID で解決します。Claude Code がクレームを拒否する場合、プロセスが終了またはクローズされた場合、および `option_not_applied` で始まるメッセージを含む場合に拒否します。セッションは要求した `model` または `maxThinkingTokens` なしで実行されています |

833| `exited` | プロセスが終了すると、クレームされたかどうかに関わらず解決します。クレーム前に終了するスペアを置き換えます |

834| `close()` | プロセスを終了します。クレーム前にこれはスペアを破棄し、`claimed` を拒否します |

835 

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

837 

838Claude Code はクレームを拒否できます。例えば、存在しないフォルダまたはプロジェクト設定が `env`、`agent`、または `model` を設定するフォルダの場合です。`claimed` が `option_not_applied` で始まるメッセージで拒否する場合、セッションは要求した `model` または `maxThinkingTokens` なしで実行されています。他の拒否の場合、プロンプトは実行されていないため、代わりに `query()` でセッションを開始してください。

839 

742<h3 id="sdkcontrolinitializeresponse">840<h3 id="sdkcontrolinitializeresponse">

743 `SDKControlInitializeResponse`841 `SDKControlInitializeResponse`

744</h3>842</h3>

759};857};

760```858```

761 859 

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

763 861 

764Claude Code はリクエストがフックを運ばなかった場合、フィールドを省略します。リクエストがフックを運んだ場合、値はリクエストがセッションの最初の初期化かどうか、および繰り返されたものの場合、セッションに到達した方法に依存します:862Claude Code はリクエストがフックを含まない場合、フィールドを省略します。リクエストがフックを含む場合、値はリクエストがセッションの最初の初期化であるかどうか、および繰り返されるものの場合、それがセッションに到達した方法に依存します:

765 863 

766* `true`: Claude Code はフックを登録しました。セッションの最初の初期化はこの値を返します。CLI の stdin を通じて送信された繰り返し初期化も `true` を返します。その場合、新しいリクエストのフックは以前に登録されたフックを置き換えます。864* `true`: Claude Code はフックを登録しました。セッションの最初の初期化はこの値を返します。CLI の stdin を通じて送信された繰り返し初期化も `true` を返します。その場合、新しいリクエストのフックは以前に登録されたフックを置き換えます。

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

768 866 

769Agent SDK v0.3.238 より前では、レスポンスはフィールドを運ばず、Claude Code はすべての繰り返し初期化で `hooks` を無視していました。867Agent SDK v0.3.238 より前では、レスポンスはフィールドを含まず、Claude Code はすべての繰り返し初期化で `hooks` を無視していました。

770 868 

771レスポンスは常に `fast_mode_state` を報告し、何かが[高速モード](/docs/ja/fast-mode)をブロックする場合、`fast_mode_disabled_reason` はブロックされた状態を説明できるように理由コードを運びます。両方の動作には Claude Code v2.1.219 以降が必要です。v2.1.219 より前では、高速モードが利用可能でない場合、レスポンスは `fast_mode_state` を省略し、理由を運びませんでした。理由コードとその意味については、結果メッセージの [`fast_mode_disabled_reason`](#sdkresultmessage) を参照してください。869レスポンスは常に `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) を参照してください。

772 870 

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

774 872 

775配列は、この Claude Code プロセスが発行し、まだ解決していない権限リクエストをリストします。SDK はあなたのために配列を読み込み、各エントリを [`canUseTool`](#canusetool) コールバック（接続が切断される前にコールバックが既に受け取ったリクエストの再配信と同じ）にディスパッチします。繰り返されたリクエスト ID をべき等に処理してください。エントリはコールバックが既に受け取ったリクエストを繰り返すことができるためです。873配列は、この Claude Code プロセスが発行し、まだ解決していない権限リクエストをリストします。SDK はあなたのために配列を読み取り、各エントリを [`canUseTool`](#canusetool) コールバックにディスパッチします。これは、トランスポートギャップ後に [`reinitialize()`](#query-object) がトリガーするのと同じ再配信です。繰り返されたリクエスト ID をべき等に処理してください。エントリは、接続が切断される前にコールバックが既に受け取ったリクエストを繰り返すことができるためです。

776 874 

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

778 876 

779<h3 id="sdkcontrolinterruptresponse">877<h3 id="sdkcontrolinterruptresponse">

780 `SDKControlInterruptResponse`878 `SDKControlInterruptResponse`

781</h3>879</h3>

782 880 

783割り込み受信: [`interrupt()`](#query-object) が [`SDKSystemMessage.capabilities`](#sdksystemmessage) で `interrupt_receipt_v1` 機能をアドバタイズする CLI で解決する値。Claude Code v2.1.205 以降が必要です。以前の CLI は割り込みに空の成功ペイロードで応答するため、`interrupt()` は `undefined` で解決します。881割り込み受信: [`interrupt()`](#query-object) が [`SDKSystemMessage.capabilities`](#sdksystemmessage) で `interrupt_receipt_v1` 機能をアドバタイズする CLI で解決する値。Claude Code v2.1.205 以降が必要です。以前の CLI は空の成功ペイロードで割り込みに応答するため、`interrupt()` は `undefined` に解決します。

784 882 

785```typescript theme={null}883```typescript theme={null}

786type SDKControlInterruptResponse = {884type SDKControlInterruptResponse = {

789};887};

790```888```

791 889 

792`still_queued` は割り込みが到着したときに保留中だったユーザーメッセージの UUID をリストします。キューに入ったままのメッセージ、および Claude Code が既にキューから次のターンのために取り出したメッセージです。セッションの最初のターンが開始した後、Claude Code は最初に割り込みをキャンセルしない限り、リストされたメッセージを処理します。複数を 1 つのターンにマージできます。最初のターンが開始する前に割り込みする場合、Claude Code はそのターンが開始するとすぐに中止し、そのターンのリストされたメッセージはレスポンスを取得しません。890`still_queued` は割り込みが到着したときに保留中だったユーザーメッセージの UUID をリストします: キューに残っているメッセージ、および Claude Code が既に次のターンのキューから取り出したメッセージ。セッションの最初のターンが開始されると、Claude Code は割り込みがない限り、リストされたメッセージを処理します。最初のターンが開始される前に割り込みを行う場合、Claude Code はそのターンが開始されるとすぐに中止し、そのターンのリストされたメッセージはレスポンスを取得しません。

793 891 

794リストを使用して、何を再送信するかを決定します。リストされたメッセージを再送信しない場合、レスポンスを取得するかどうかに関わらず、会話に入り、Claude に 2 回配信されます。892受信を使用して、何かを再送信するかどうかを決定します。リストされたメッセージをキャンセルしない場合、レスポンスを取得するかどうかに関わらず会話に入るため、再送信するとそれを Claude に 2 回配信します。

795 893 

796これらの注意事項でリストを解釈します:894これらの注意事項でリストを解釈します:

797 895 

798* UUID でエンキューされたメッセージのみが表示されます。空の配列は他に何も実行されないことを意味しません。896* UUID でエンキューされたメッセージのみが表示されます。空の配列は他に何も実行されないことを意味しません。

799* メインスレッドメッセージのみがリストされます。サブエージェントにアドレス指定されたメッセージはスコープ外です。897* メインスレッドメッセージのみがリストされます。サブエージェントに宛てられたメッセージはスコープ外です。

800* リストには、クライアントが送信しなかった UUID（[スケジュール済みタスク](/docs/ja/scheduled-tasks)トリガーなど）を含めることができます。エラーとして扱う代わりに、認識しない UUID を無視してください。898* リストには、[スケジュール済みタスク](/docs/ja/scheduled-tasks) トリガーなど、クライアントが送信しなかった UUID を含めることができます。エラーとして扱うのではなく、認識しない UUID を無視してください。

801 899 

802CLI の制御プロトコルを `interrupt()` を通じてではなく直接駆動するクライアントは、`interrupt` 制御リクエストで `cancel_queued: true` を設定できます。Claude Code v2.1.219 以降は [`SDKSystemMessage.capabilities`](#sdksystemmessage) で `interrupt_cancel_queued_v1` 機能でサポートをアドバタイズします。古い CLI はフィールドを無視し、キューに入ったメッセージを通常どおり実行させます。そのような割り込みは、`still_queued` の下にリストされるはずのすべてのメッセージもキャンセルします。それらは代わりに `cancelled` の下にリストされ、`still_queued` は空で、それらのどれも実行されません。900制御プロトコルを `interrupt()` ではなく直接駆動するクライアントは、`interrupt` 制御リクエストで `cancel_queued: true` を設定できます。Claude Code v2.1.219 以降は [`SDKSystemMessage.capabilities`](#sdksystemmessage) で `interrupt_cancel_queued_v1` 機能でサポートをアドバタイズします。古い CLI はフィールドを無視し、キューに入ったメッセージを通常どおり実行したままにします。そのような割り込みは、`still_queued` の下にリストされるすべてのメッセージをキャンセルします: 代わりに `cancelled` の下にリストされ、`still_queued` は空で、それらのどれも実行されません。

803 901 

804`cancelled` リストは `still_queued` と同じ注意事項を運びます。`interrupt()` メソッドは `cancel_queued` を送信しないため、それが解決するレシートは `cancelled` を運びません。902`cancelled` リストは `still_queued` と同じ注意事項を含みます。`interrupt()` メソッドは `cancel_queued` を送信しないため、それが解決する受信は `cancelled` を含みません。

805 903 

806レシートは割り込みが処理される瞬間に撮られたスナップショットで、クリーン割り込みでは中断されたターンの [`SDKResultMessage`](#sdkresultmessage) の前に到着します。そのレシートの後のキューを検査する代わりにレシートを読み込んでください。ループは次のキューに入ったターンをすぐに開始するため、結果の後に検査するキューは既に変更されています。904受信は割り込みが処理される瞬間のスナップショットで、クリーン割り込みで中断されたターンの [`SDKResultMessage`](#sdkresultmessage) の前に到着します。その結果の後のキューを検査するのではなく、受信を読み取ってください: ループは次のキューに入ったターンをすぐに開始するため、結果の後に検査するキューは既に変更されています。

807 905 

808<h3 id="sdkcontrolgetcontextusageresponse">906<h3 id="sdkcontrolgetcontextusageresponse">

809 `SDKControlGetContextUsageResponse`907 `SDKControlGetContextUsageResponse`

810</h3>908</h3>

811 909 

812[`getContextUsage()`](#query-object) の戻り値の型。デフォルト `detail` では、これはインタラクティブセッションで `/context` コマンドが Claude Code がレンダリングするのと同じペイロードで、トークンカウントと共に `color` や `gridRows` などの表示フィールドを運びます。これは Claude Code が `/context` 使用グリッドを描画するために使用します。910[`getContextUsage()`](#query-object) の戻り値の型。デフォルト `detail` では、これは対話型セッションで `/context` コマンドが Claude Code がレンダリングするのと同じペイロードで、トークンカウントと共に `/context` 使用グリッドを描画するために Claude Code が使用する `color` および `gridRows` などの表示フィールドを含みます。

813 911 

814メソッドのオプション `detail` 引数は Claude Code が各カテゴリをカウントする方法を選択します。デフォルト `'full'` では、Claude Code はトークンカウント API リクエストで各カテゴリをカウントします。`{ detail: 'summary' }` を渡して、最後のレスポンスの使用状況とローカル推定から答えを取得します。トークンカウントリクエストは出ていかず、カテゴリごとの数値は概算です。`detail` 引数には Agent SDK v0.3.257 以降が必要です。912メソッドのオプション `detail` 引数は、Claude Code が各カテゴリをカウントする方法を選択します。デフォルト `'full'` では、Claude Code はトークンカウント API リクエストで各カテゴリをカウントします。最後のレスポンスの使用状況とローカル推定から答えを取得するには `{ detail: 'summary' }` を渡します。トークンカウントリクエストは送信されず、カテゴリごとの数値は概算です。`detail` 引数には Agent SDK v0.3.257 以降が必要です。

815 913 

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

817 915 

818```typescript theme={null}916```typescript theme={null}

819type SDKControlGetContextUsageResponse = {917type SDKControlGetContextUsageResponse = {

822 tokens: number;920 tokens: number;

823 color: string;921 color: string;

824 isDeferred?: boolean;922 isDeferred?: boolean;

923 kind: "used" | "free" | "buffer" | "deferred";

825 }[];924 }[];

826 totalTokens: number;925 totalTokens: number;

827 maxTokens: number;926 maxTokens: number;

909};1008};

910```1009```

911 1010 

912コレクションフィールドからトークン帰属を読み込みます:1011トークン帰属をコレクションフィールドから読み取ります:

913 1012 

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

915* `mcpTools` と `agents` はトークンを個別の MCP ツールとサブエージェントに帰属させます。1014* `mcpTools` と `agents` はトークンを個別の MCP ツールとサブエージェントに帰属させます。

916* `memoryFiles` は各読み込まれたメモリファイルをそのコストと共にリストします。1015* `memoryFiles` は各読み込まれたメモリファイルとそのコストをリストします。

917* `skills.skillFrontmatter` はスキルリストのトークンを含まれた各スキルに帰属させます。スキルごとのカウントは各スキルのリストエントリを Claude Code が実際に送信するときに測定し、スキルの完全なフロントマターより短くなる可能性があります。`skills.totalSkills` を `skills.includedSkills` と比較して、すべての検出されたスキルがリストに含まれたかどうかを確認します。1016* `skills.skillFrontmatter` は、含まれる各スキルにスキルリストのトークンを帰属させます。スキルごとの数値は、Claude Code が実際に送信するスキルリストエントリを測定します。これはスキルの完全なフロントマターより短くなる可能性があります。`skills.totalSkills` を `skills.includedSkills` と比較して、検出されたすべてのスキルがリストに含まれているかどうかを確認します。

918 1017 

919`totalTokens` はセッションの現在のコンテキスト使用状況で、`maxTokens` はその使用状況が測定されるウィンドウです。そのウィンドウはモデルのコンテキストウィンドウ、または 1 つが適用される場合は低い自動コンパクション ウィンドウです。`rawMaxTokens` は `maxTokens` と同じ値を運び、`percentage` はそのウィンドウの丸められたパーセンテージとしての `totalTokens` です。1018`totalTokens` はセッションの現在のコンテキスト使用状況で、`maxTokens` はその使用状況が測定されるウィンドウです。そのウィンドウはモデルのコンテキストウィンドウ、または 1 つが適用される場合は低い自動コンパクション ウィンドウです。`rawMaxTokens` は `maxTokens` と同じ値を含み、`percentage` は `totalTokens` をそのウィンドウのパーセンテージとして丸めたものです。

920 1019 

921Claude Code はオプション `deferredBuiltinTools`、`systemTools`、`systemPromptSections` 診断を設定しないため、フィールドが存在しない場合でも期待してください。1020Claude Code は、オプション `deferredBuiltinTools`、`systemTools`、および `systemPromptSections` 診断を設定しないままにするため、型が宣言していても存在しないことを期待してください。

922 1021 

923<h3 id="sdkcontrolreadfileresponse">1022<h3 id="sdkcontrolreadfileresponse">

924 `SDKControlReadFileResponse`1023 `SDKControlReadFileResponse`

935};1034};

936```1035```

937 1036 

938`contents` はファイルテキストを保持するか、`encoding: 'base64'` をリクエストした場合は base64 データを保持します。レスポンスの `encoding` フィールドはその場合 `'base64'` に設定されます。`absPath` は解決された絶対パスです。`truncated` はファイルが `maxBytes` キャップより長く、コンテンツがその制限で切り詰められた場合に設定されます。1037`contents` はファイルテキストを保持するか、`encoding: 'base64'` をリクエストした場合は base64 データを保持します。レスポンスの `encoding` フィールドはその場合 `'base64'` に設定されます。`absPath` は解決された絶対パスです。`truncated` は、ファイルが `maxBytes` キャップより長く、コンテンツがその制限で切り詰められた場合に設定されます。

939 1038 

940<h4 id="what-readfile-can-read">1039<h4 id="what-readfile-can-read">

941 `readFile()` が読み込める内容1040 `readFile()` が読み取れるもの

942</h4>1041</h4>

943 1042 

944`readFile()` は Read ツールより狭いファイルセットを提供します:1043`readFile()` は Read ツールより狭いファイルセットを提供します:

945 1044 

946* `cwd` や `additionalDirectories` などのセッションの作業ディレクトリの 1 つ内の通常ファイル1045* `cwd` および `additionalDirectories` などのセッションのワーキングディレクトリの 1 つ内の通常ファイル

947* セッションのツール結果などの Claude Code 独自のいくつかのファイル1046* セッションのツール結果などの Claude Code 独自のファイルのいくつか

948 1047 

949Read 拒否および質問ルールは引き続き一致するパスをブロックし、広い Read 許可ルールは `readFile()` にファイルシステムの残りを開きません。他のすべてについて、呼び出しは `null` で解決します。1048Read 拒否および質問ルールは引き続き一致するパスをブロックし、広い Read 許可ルールは `readFile()` にファイルシステムの残りを開きません。他のすべてについて、呼び出しは `null` で解決します。

950 1049 

1050<h3 id="sdkcontrolreloadpluginsresponse">

1051 `SDKControlReloadPluginsResponse`

1052</h3>

1053 

1054[`reloadPlugins()`](#query-object) の戻り値の型。

1055 

1056```typescript theme={null}

1057type SDKControlReloadPluginsResponse = {

1058 commands: SlashCommand[];

1059 agents: AgentInfo[];

1060 plugins: {

1061 name: string;

1062 path: string;

1063 source?: string;

1064 version?: string;

1065 }[];

1066 mcpServers: McpServerStatus[];

1067 error_count: number;

1068 held?: boolean;

1069 cache_impact?: {

1070 mcp_servers_added: string[];

1071 mcp_servers_removed: string[];

1072 lsp_tool_change: ("adds" | "may-add" | "removes" | "may-remove") | null;

1073 };

1074};

1075```

1076 

1077コレクションフィールドは呼び出し後のセッションを説明します:

1078 

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

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

1081* `error_count`: プラグイン読み込みからのエラー数

1082 

1083会話のプロンプトキャッシュを無効にするリロードを保持するには、`{ holdOnCacheImpact: true }` を `reloadPlugins()` に渡します。Claude Code は対話型 `/reload-plugins` コマンドが [キャッシュコストについて警告](/docs/ja/prompt-caching#enabling-or-disabling-a-plugin) する前に行うチェックを実行します。オプションには Agent SDK v0.3.268 以降が必要です。v2.1.268 より古い Claude Code 実行可能ファイル（`pathToClaudeCodeExecutable` で指定したものなど）はオプションを無視し、リロードを適用します。

1084 

1085オプションを渡すと、`held` を読み取って何が起こったかを確認します:

1086 

1087* `true`: リロードは適用されず、コレクションフィールドはセッションをそのまま説明します。`cache_impact` は適用が何を変更するかを示します。とにかく適用するには、オプションなしで `reloadPlugins()` を再度呼び出してください。

1088* `false`: チェックはキャッシュ影響を見つけず、リロードが適用されました。

1089* 存在しない: オプションを渡さなかったか、Claude Code 実行可能ファイルが v2.1.268 より古く、リロードを適用しました。

1090 

1091`cache_impact` は `held: true` と共にのみ存在します。`mcp_servers_added` と `mcp_servers_removed` はリロードが登録または削除するプラグイン MCP サーバーを、スコープ付き `plugin:<plugin>:<server>` 名として指定します。名前はプラグイン作成者が作成するため、表示する前に検証してください。`lsp_tool_change` は適用が LSP ツールを追加または削除するかどうかを示し、どちらもしない場合は `null` です。`may-` 形式は、チェックが保留中のプラグインセットを完全に見ることができなかったことを意味します。

1092 

951<h3 id="sdkcontrolreloadskillsresponse">1093<h3 id="sdkcontrolreloadskillsresponse">

952 `SDKControlReloadSkillsResponse`1094 `SDKControlReloadSkillsResponse`

953</h3>1095</h3>

962 1104 

963`skills` は再読み込み後に利用可能なスキルをリストします。`supportedCommands()` が返すのと同じ [`SlashCommand`](#slashcommand) 形状です。1105`skills` は再読み込み後に利用可能なスキルをリストします。`supportedCommands()` が返すのと同じ [`SlashCommand`](#slashcommand) 形状です。

964 1106 

1107<h3 id="sdkcontrolreloadoutputstylesresponse">

1108 `SDKControlReloadOutputStylesResponse`

1109</h3>

1110 

1111[`reloadOutputStyles()`](#query-object) の戻り値の型。

1112 

1113```typescript theme={null}

1114type SDKControlReloadOutputStylesResponse = {

1115 available_output_styles: string[];

1116};

1117```

1118 

1119`available_output_styles` は再読み込み後に利用可能な組み込みおよびカスタム出力スタイルの名前をリストします。

1120 

965<h3 id="sdkcontrolmcpreadresourceresponse">1121<h3 id="sdkcontrolmcpreadresourceresponse">

966 `SDKControlMcpReadResourceResponse`1122 `SDKControlMcpReadResourceResponse`

967</h3>1123</h3>

968 1124 

969[`readMcpResource()`](#query-object) の戻り値の型。MCP サーバーの `resources/read` 結果を運びます。TypeScript Agent SDK v0.3.280 以降が必要です。1125[`readMcpResource()`](#query-object) の戻り値の型。MCP サーバーの `resources/read` 結果を含みます。TypeScript Agent SDK v0.3.280 以降が必要です。

970 1126 

971```typescript theme={null}1127```typescript theme={null}

972type SDKControlMcpReadResourceResponse = {1128type SDKControlMcpReadResourceResponse = {

980};1136};

981```1137```

982 1138 

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

984 1140 

985各 `contents` エントリは、サーバーが送信した 1 つのコンテンツアイテムです。`blob` はバイナリアイテムの base64 データを保持し、`_meta` はアイテム自体の `_meta` で、MCP Apps サーバーはリソースの `ui.csp` と `ui.permissions` を配置します。コンテンツは信頼できない第三者の HTML であるため、サンドボックスでレンダリングしてください。1141各 `contents` エントリは、サーバーが送信した 1 つのコンテンツアイテムで、`com.anthropic/` プレフィックスの下の `_meta` キーを除きます。これは Claude Code 用に予約されています。`blob` はバイナリアイテムの base64 データを保持し、`_meta` はアイテム独自の `_meta` で、MCP Apps サーバーはリソースの `ui.csp` および `ui.permissions` を配置します。

1142 

1143コンテンツは信頼できない第三者の HTML であるため、サンドボックスでレンダリングしてください。

986 1144 

987<h3 id="agentdefinition">1145<h3 id="agentdefinition">

988 `AgentDefinition`1146 `AgentDefinition`

1013| フィールド | 必須 | 説明 |1171| フィールド | 必須 | 説明 |

1014| :- | :- | :- |1172| :- | :- | :- |

1015| `description` | はい | このエージェントを使用する場合の自然言語説明 |1173| `description` | はい | このエージェントを使用する場合の自然言語説明 |

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

1017| `disallowedTools` | いいえ | このエージェントで明示的に許可しないツール名の配列。MCP サーバーレベルのパターンも受け入れられます: `mcp__server` または `mcp__server__*` はそのサーバーからすべてのツールを削除し、`mcp__*` はすべての MCP ツールを任意のサーバーから削除します |1175| `disallowedTools` | いいえ | このエージェントで明示的に許可しないツール名の配列。MCP サーバーレベルのパターンも受け入れられます: `mcp__server` または `mcp__server__*` はそのサーバーからすべてのツールを削除し、`mcp__*` はすべての MCP ツールをすべてのサーバーから削除します |

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

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

1020| `mcpServers` | いいえ | このエージェント用の MCP サーバー仕様 |1178| `mcpServers` | いいえ | このエージェント用の MCP サーバー仕様 |

1021| `skills` | いいえ | エージェントコンテキストにプリロードするスキル名の配列 |1179| `skills` | いいえ | エージェントコンテキストにプリロードするスキル名の配列 |

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

1023| `maxTurns` | いいえ | 停止する前のエージェンティックターン数（API ラウンドトリップ）の最大数 |1181| `maxTurns` | いいえ | 停止する前のエージェンティックターン数（API ラウンドトリップ）の最大数 |

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

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

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

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

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

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

1030 1188 

1031<h3 id="agentmcpserverspec">1189<h3 id="agentmcpserverspec">

1054| :- | :- | :- |1212| :- | :- | :- |

1055| `'user'` | グローバルユーザー設定 | `~/.claude/settings.json` |1213| `'user'` | グローバルユーザー設定 | `~/.claude/settings.json` |

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

1057| `'local'` | ローカルプロジェクト設定、Claude Code が設定をそれに保存するときに gitignored | `.claude/settings.local.json` |1215| `'local'` | ローカルプロジェクト設定、Claude Code が設定を保存するときに gitignored | `.claude/settings.local.json` |

1058 1216 

1059<h4 id="default-behavior">1217<h4 id="default-behavior">

1060 デフォルト動作1218 デフォルト動作

1061</h4>1219</h4>

1062 1220 

1063`settingSources` が省略されるか `undefined` の場合、`query()` は Claude Code CLI と同じファイルシステム設定を読み込みます。ユーザー、プロジェクト、ローカル。[settingSources が制御しないもの](/docs/ja/agent-sdk/claude-code-features#what-settingsources-does-not-control)を参照して、それらを読み込む入力と、それらを無効にする方法を確認してください。1221`settingSources` が省略されるか `undefined` の場合、`query()` は Claude Code CLI と同じファイルシステム設定を読み込みます: ユーザー、プロジェクト、ローカル。[Claude Code 機能を使用](/docs/ja/agent-sdk/claude-code-features#what-settingsources-does-not-control) を参照して、入力を無効にする方法を確認してください。

1064 1222 

1065<h4 id="why-use-settingsources">1223<h4 id="why-use-settingsources">

1066 settingSources を使用する理由1224 settingSources を使用する理由

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

1072import { query } from "@anthropic-ai/claude-agent-sdk";1230import { query } from "@anthropic-ai/claude-agent-sdk";

1073 1231 

1074// Do not load user, project, or local settings from disk1232// ディスクからユーザー、プロジェクト、ローカル設定を読み込まないでください

1075const result = query({1233const result = query({

1076 prompt: "Analyze this code",1234 prompt: "Analyze this code",

1077 options: { settingSources: [] }1235 options: { settingSources: [] }

1083```typescript theme={null}1241```typescript theme={null}

1084import { query } from "@anthropic-ai/claude-agent-sdk";1242import { query } from "@anthropic-ai/claude-agent-sdk";

1085 1243 

1086// Load only project settings, ignore user and local1244// プロジェクト設定のみを読み込み、ユーザーとローカルを無視します

1087const result = query({1245const result = query({

1088 prompt: "Run CI checks",1246 prompt: "Run CI checks",

1089 options: {1247 options: {

1090 settingSources: ["project"] // Only .claude/settings.json1248 settingSources: ["project"] // .claude/settings.json のみ

1091 }1249 }

1092});1250});

1093```1251```

1094 1252 

1095CLAUDE.md プロジェクト指示を読み込むには、`settingSources` に `"project"` を含めます。CLAUDE.md 読み込みがシステムプロンプトオプションとどのように相互作用するかについては、[システムプロンプトを変更](/docs/ja/agent-sdk/modifying-system-prompts#claude-md-files-for-project-level-instructions)を参照してください。1253CLAUDE.md プロジェクト指示を読み込むには、`settingSources` に `"project"` を含めてください。CLAUDE.md 読み込みがシステムプロンプトオプションとどのように相互作用するかについては、[システムプロンプトを変更](/docs/ja/agent-sdk/modifying-system-prompts#claude-md-files-for-project-level-instructions) を参照してください。

1096 1254 

1097<h4 id="settings-precedence">1255<h4 id="settings-precedence">

1098 設定優先順位1256 設定優先順位

1112 1270 

1113```typescript theme={null}1271```typescript theme={null}

1114type PermissionMode =1272type PermissionMode =

1115 | "default" // Standard permission behavior1273 | "default" // 標準権限動作