Documentation — Spybara

agent-sdk/agent-loop.md +395 −0 created

Details

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

5# エージェントループの仕組み

7> メッセージライフサイクル、ツール実行、コンテキストウィンドウ、および SDK エージェントを支えるアーキテクチャを理解します。

9Agent SDK を使用すると、Claude Code の自律型エージェントループを独自のアプリケーションに組み込むことができます。SDK はスタンドアロンパッケージで、ツール、権限、コスト制限、および出力をプログラムで制御できます。これを使用するために Claude Code CLI をインストールする必要はありません。

11エージェントを開始すると、SDK は Claude Code を支える[実行ループ](/ja/how-claude-code-works#the-agentic-loop)と同じものを実行します。Claude はプロンプトを評価し、ツールを呼び出してアクションを実行し、結果を受け取り、タスクが完了するまで繰り返します。このページでは、そのループ内で何が起こるかを説明し、エージェントを効果的に構築、デバッグ、最適化できるようにします。

13## ループの概要

15すべてのエージェントセッションは同じサイクルに従います。

17<img src="https://mintcdn.com/claude-code/gvy2DIUELtNA8qD3/images/agent-loop-diagram.svg?fit=max&auto=format&n=gvy2DIUELtNA8qD3&q=85&s=192e1bd6c8a2950a16e5ee0b94e27e26" alt="エージェントループ：プロンプトが入力され、Claude が評価し、ツール呼び出しまたは最終回答に分岐" width="680" height="150" data-path="images/agent-loop-diagram.svg" />

191. **プロンプトを受け取る。** Claude はプロンプト、システムプロンプト、ツール定義、および会話履歴とともにプロンプトを受け取ります。SDK はセッションメタデータを含むサブタイプ `"init"` の[`SystemMessage`](#message-types)を生成します。

202. **評価して応答する。** Claude は現在の状態を評価し、どのように進めるかを決定します。テキストで応答したり、1 つ以上のツール呼び出しをリクエストしたり、その両方を行ったりできます。SDK はテキストとツール呼び出しリクエストを含む[`AssistantMessage`](#message-types)を生成します。

213. **ツールを実行する。** SDK は要求された各ツールを実行し、結果を収集します。ツール結果の各セットは次の決定のために Claude にフィードバックされます。[hooks](/ja/agent-sdk/hooks)を使用して、ツール呼び出しを実行前に傍受、変更、またはブロックできます。

224. **繰り返す。** ステップ 2 と 3 がサイクルとして繰り返されます。各完全なサイクルは 1 ターンです。Claude はツール呼び出しと結果の処理を続け、ツール呼び出しのない応答を生成するまで続きます。

235. **結果を返す。** SDK は最終的な[`AssistantMessage`](#message-types)（テキスト応答、ツール呼び出しなし）を生成し、その後に最終テキスト、トークン使用量、コスト、およびセッション ID を含む[`ResultMessage`](#message-types)を生成します。

25簡単な質問（「ここにはどのようなファイルがありますか？」）は、`Glob` を呼び出して結果で応答する 1 ～ 2 ターンで済む場合があります。複雑なタスク（「認証モジュールをリファクタリングしてテストを更新する」）は、多くのターンにわたって数十のツール呼び出しをチェーンでき、ファイルを読み取り、コードを編集し、テストを実行し、Claude が各結果に基づいてアプローチを調整します。

27## ターンとメッセージ

29ターンはループ内の 1 往復です。Claude はツール呼び出しを含む出力を生成し、SDK はそれらのツールを実行し、結果は自動的に Claude にフィードバックされます。これはコードに制御を戻さずに発生します。Claude がツール呼び出しのない出力を生成するまでターンが続き、その時点でループが終了し、最終結果が配信されます。

31プロンプト「Fix the failing tests in auth.ts」の完全なセッションがどのようなものかを考えてみましょう。

33まず、SDK はプロンプトを Claude に送信し、セッションメタデータを含む[`SystemMessage`](#message-types)を生成します。その後、ループが開始されます。

351. **ターン 1：** Claude は `Bash` を呼び出して `npm test` を実行します。SDK は[`AssistantMessage`](#message-types)とツール呼び出しを生成し、コマンドを実行し、出力（3 つの失敗）を含む[`UserMessage`](#message-types)を生成します。

362. **ターン 2：** Claude は `Read` を呼び出して `auth.ts` と `auth.test.ts` を読み取ります。SDK はファイルの内容を返し、`AssistantMessage` を生成します。

373. **ターン 3：** Claude は `Edit` を呼び出して `auth.ts` を修正し、`Bash` を呼び出して `npm test` を再実行します。3 つのテストすべてが成功します。SDK は `AssistantMessage` を生成します。

384. **最終ターン：** Claude はツール呼び出しのないテキストのみの応答を生成します。「認証バグを修正し、3 つのテストすべてが成功しました。」SDK はこのテキストを含む最終 `AssistantMessage` を生成し、その後、同じテキストとコストおよび使用量を含む[`ResultMessage`](#message-types)を生成します。

40これは 4 ターンでした。3 つはツール呼び出し、1 つは最終テキストのみの応答です。

42`max_turns` / `maxTurns` でループをキャップできます。これはツール使用ターンのみをカウントします。たとえば、上記のループで `max_turns=2` は編集ステップの前に停止していたでしょう。`max_budget_usd` / `maxBudgetUsd` を使用して、支出しきい値に基づいてターンをキャップすることもできます。

44制限がない場合、ループは Claude が独自に終了するまで実行されます。これは適切にスコープされたタスクには問題ありませんが、オープンエンドのプロンプト（「このコードベースを改善する」）では長時間実行される可能性があります。予算を設定することは、本番エージェントの良いデフォルトです。以下の[ターンと予算](#turns-and-budget)でオプションリファレンスを参照してください。

46## メッセージタイプ

48ループが実行されると、SDK はメッセージのストリームを生成します。各メッセージは、ループのどのステージから来たかを示すタイプを持ちます。5 つのコアタイプは次のとおりです。

50* **`SystemMessage`：** セッションライフサイクルイベント。`subtype` フィールドはそれらを区別します。`"init"` は最初のメッセージ（セッションメタデータ）で、`"compact_boundary"` は[圧縮](#automatic-compaction)後に発火します。TypeScript では、圧縮境界は `SDKSystemMessage` のサブタイプではなく、独自の[`SDKCompactBoundaryMessage`](/ja/agent-sdk/typescript#sdkcompactboundarymessage)タイプです。

51* **`AssistantMessage`：** 最終テキストのみの応答を含む、各 Claude 応答の後に生成されます。そのターンからのテキストコンテンツブロックとツール呼び出しブロックを含みます。

52* **`UserMessage`：** 各ツール実行後、Claude に送り返されるツール結果コンテンツとともに生成されます。ループ中盤でストリーミングするユーザー入力に対しても生成されます。

53* **`StreamEvent`：** 部分メッセージが有効な場合のみ生成されます。生のAPI ストリーミングイベント（テキストデルタ、ツール入力チャンク）を含みます。[ストリーム応答](/ja/agent-sdk/streaming-output)を参照してください。

54* **`ResultMessage`：** エージェントループの終了をマークします。最終テキスト結果、トークン使用量、コスト、およびセッション ID を含みます。`subtype` フィールドをチェックして、タスクが成功したか制限に達したかを判断します。`prompt_suggestion` などの少数の末尾システムイベントはその後に到着する可能性があるため、結果で中断するのではなく、ストリームを完了まで反復処理します。[結果を処理する](#handle-the-result)を参照してください。

56これら 5 つのタイプは、両方の SDK でエージェントループライフサイクル全体をカバーしています。TypeScript SDK は、追加の観測可能性イベント（フックイベント、ツール進捗、レート制限、タスク通知）も生成し、追加の詳細を提供しますが、ループを駆動するために必須ではありません。完全なリストについては、[Python メッセージタイプリファレンス](/ja/agent-sdk/python#message-types)と[TypeScript メッセージタイプリファレンス](/ja/agent-sdk/typescript#message-types)を参照してください。

58### メッセージを処理する

60処理するメッセージは、構築しているものによって異なります。

62* **最終結果のみ：** `ResultMessage` を処理して、出力、コスト、およびタスクが成功したか制限に達したかを取得します。

63* **進捗更新：** `AssistantMessage` を処理して、Claude が各ターンで何をしているか、どのツールを呼び出したかを確認します。

64* **ライブストリーミング：** 部分メッセージを有効にする（Python では `include_partial_messages`、TypeScript では `includePartialMessages`）して、リアルタイムで `StreamEvent` メッセージを取得します。[リアルタイムでストリーム応答](/ja/agent-sdk/streaming-output)を参照してください。

66メッセージタイプをチェックする方法は SDK によって異なります。

68* **Python：** `claude_agent_sdk` からインポートされたクラスに対して `isinstance()` でメッセージタイプをチェックします（たとえば、`isinstance(message, ResultMessage)`）。

69* **TypeScript：** `type` 文字列フィールドをチェックします（たとえば、`message.type === "result"`）。`AssistantMessage` と `UserMessage` は生の API メッセージを `.message` フィールドでラップするため、コンテンツブロックは `message.content` ではなく `message.message.content` にあります。

71<Accordion title="例：メッセージタイプをチェックして結果を処理する">

72 <CodeGroup>

73 ```python Python theme={null}

74 from claude_agent_sdk import query, AssistantMessage, ResultMessage

76 async for message in query(prompt="Summarize this project"):

77 if isinstance(message, AssistantMessage):

78 print(f"Turn completed: {len(message.content)} content blocks")

79 if isinstance(message, ResultMessage):

80 if message.subtype == "success":

81 print(message.result)

82 else:

83 print(f"Stopped: {message.subtype}")

84 ```

86 ```typescript TypeScript theme={null}

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

89 for await (const message of query({ prompt: "Summarize this project" })) {

90 if (message.type === "assistant") {

91 console.log(`Turn completed: ${message.message.content.length} content blocks`);

92 }

93 if (message.type === "result") {

94 if (message.subtype === "success") {

95 console.log(message.result);

96 } else {

97 console.log(`Stopped: ${message.subtype}`);

98 }

99 }

100 }

101 ```

102 </CodeGroup>

103</Accordion>

104

105## ツール実行

106

107ツールはエージェントにアクションを実行する機能を提供します。ツールがなければ、Claude はテキストでのみ応答できます。ツールを使用すると、Claude はファイルを読み取り、コマンドを実行し、コードを検索し、外部サービスと相互作用できます。

108

109### 組み込みツール

110

111SDK には Claude Code を支えるのと同じツールが含まれています。

112

113| カテゴリ | ツール | 機能 |

114| :------------- | :-------------------------------------------- | :------------------------------------ |

115| **ファイル操作** | `Read`、`Edit`、`Write` | ファイルを読み取り、変更、作成 |

116| **検索** | `Glob`、`Grep` | パターンでファイルを検索、正規表現でコンテンツを検索 |

117| **実行** | `Bash` | シェルコマンド、スクリプト、git 操作を実行 |

118| **Web** | `WebSearch`、`WebFetch` | Web を検索、ページを取得して解析 |

119| **検出** | `ToolSearch` | すべてをプリロードする代わりに、オンデマンドでツールを動的に検索してロード |

120| **オーケストレーション** | `Agent`、`Skill`、`AskUserQuestion`、`TodoWrite` | サブエージェントを生成、スキルを呼び出し、ユーザーに質問、タスクを追跡 |

121

122組み込みツール以外に、以下を実行できます。

123

124* **外部サービスを接続する** [MCP サーバー](/ja/agent-sdk/mcp)（データベース、ブラウザ、API）

125* **カスタムツールを定義する** [カスタムツールハンドラー](/ja/agent-sdk/custom-tools)

126* **プロジェクトスキルをロードする** [設定ソース](/ja/agent-sdk/claude-code-features)経由で再利用可能なワークフロー

127

128### ツール権限

129

130Claude はタスクに基づいてどのツールを呼び出すかを決定しますが、それらの呼び出しの実行を許可するかどうかを制御します。特定のツールを自動承認したり、他のツールを完全にブロックしたり、すべてに対して承認を要求したりできます。3 つのオプションが連携して、何が実行されるかを決定します。

131

132* **`allowed_tools` / `allowedTools`** リストされたツールを自動承認します。許可されたツールリストに `["Read", "Glob", "Grep"]` がある読み取り専用エージェントは、プロンプトなしでそれらのツールを実行します。リストされていないツールは引き続き利用可能ですが、権限が必要です。

133* **`disallowed_tools` / `disallowedTools`** リストされたツールをブロックします。他の設定に関係なく。ツールが実行される前にルールがチェックされる順序については、[権限](/ja/agent-sdk/permissions)を参照してください。

134* **`permission_mode` / `permissionMode`** 許可または拒否ルールでカバーされていないツールに何が起こるかを制御します。利用可能なモードについては、[権限モード](#permission-mode)を参照してください。

135

136`"Bash(npm *)"` のようなルールで個別のツールをスコープすることもできます。これにより、特定のコマンドのみを許可できます。完全なルール構文については、[権限](/ja/agent-sdk/permissions)を参照してください。

137

138ツールが拒否されると、Claude はツール結果として拒否メッセージを受け取り、通常は別のアプローチを試みるか、進めなかったことを報告します。

139

140### 並列ツール実行

141

142Claude が単一のターンで複数のツール呼び出しをリクエストすると、両方の SDK はツールに応じて同時または順序に実行できます。読み取り専用ツール（`Read`、`Glob`、`Grep`、読み取り専用としてマークされた MCP ツール）は同時に実行できます。状態を変更するツール（`Edit`、`Write`、`Bash`）は競合を避けるために順序に実行されます。

143

144カスタムツールはデフォルトで順序実行されます。カスタムツールの並列実行を有効にするには、その注釈で `readOnlyHint` を設定します。[TypeScript](/ja/agent-sdk/typescript#tool)と[Python](/ja/agent-sdk/python#tool)SDK の両方は MCP SDK からこのフィールド名を使用します。

145

146## ループの実行方法を制御する

147

148ループが実行するターン数、コスト、Claude がどの程度推論するか、ツールが実行前に承認を必要とするかどうかを制限できます。これらはすべて[`ClaudeAgentOptions`](/ja/agent-sdk/python#claudeagentoptions)（Python）/ [`Options`](/ja/agent-sdk/typescript#options)（TypeScript）のフィールドです。

149

150### ターンと予算

151

152| オプション | 制御内容 | デフォルト |

153| :-------------------------------------- | :--------- | :---- |

154| 最大ターン（`max_turns` / `maxTurns`） | 最大ツール使用往復数 | 制限なし |

155| 最大予算（`max_budget_usd` / `maxBudgetUsd`） | 停止前の最大コスト | 制限なし |

156

157どちらかの制限に達すると、SDK は対応するエラーサブタイプ（`error_max_turns` または `error_max_budget_usd`）を含む `ResultMessage` を返します。これらのサブタイプをチェックする方法については[結果を処理する](#handle-the-result)を、構文については[`ClaudeAgentOptions`](/ja/agent-sdk/python#claudeagentoptions) / [`Options`](/ja/agent-sdk/typescript#options)を参照してください。

158

159### 努力レベル

160

161`effort` オプションは Claude が適用する推論の量を制御します。低い努力レベルはターンあたりのトークンが少なく、コストが削減されます。すべてのモデルが努力パラメータをサポートしているわけではありません。どのモデルがサポートしているかについては、[努力](https://platform.claude.com/docs/ja/build-with-claude/effort)を参照してください。

162

163| レベル | 動作 | 適している用途 |

164| :--------- | :---------- | :-------------------------------------- |

165| `"low"` | 最小限の推論、高速応答 | ファイル検索、ディレクトリのリスト |

166| `"medium"` | バランスの取れた推論 | ルーチン編集、標準タスク |

167| `"high"` | 徹底的な分析 | リファクタリング、デバッグ |

168| `"xhigh"` | 拡張推論深度 | コーディングと agentic coding タスク。Opus 4.7 で推奨 |

169| `"max"` | 最大推論深度 | 深い分析が必要な複数ステップの問題 |

170

171`effort` を設定しない場合、Python SDK はパラメータを設定したままにして、モデルのデフォルト動作に委譲します。TypeScript SDK はデフォルトで `"high"` です。

172

173<Note>

174 `effort` は各応答内の推論深度のレイテンシとトークンコストをトレードオフします。[拡張思考](https://platform.claude.com/docs/ja/build-with-claude/extended-thinking)は、出力に表示される思考の連鎖ブロックを生成する別の機能です。これらは独立しています。`effort: "low"` を拡張思考有効で設定することも、`effort: "max"` を有効にしないで設定することもできます。

175</Note>

176

177単純でスコープが明確なタスク（ファイルのリストや単一の grep の実行など）を実行するエージェントの場合は、低い努力を使用してコストとレイテンシを削減します。トップレベルの `query()` オプションでセッション全体に `effort` を設定するか、[`AgentDefinition`](/ja/agent-sdk/subagents#agentdefinition-configuration)の `effort` フィールドでサブエージェントごとにセッションレベルをオーバーライドします。

178

179### 権限モード

180

181権限モードオプション（Python では `permission_mode`、TypeScript では `permissionMode`）は、エージェントがツールを使用する前に承認を求めるかどうかを制御します。

182

183| モード | 動作 |

184| :---------------------- | :------------------------------------------------------------------------------------------------------------------- |

185| `"default"` | 許可ルールでカバーされていないツールは承認コールバックをトリガーします。コールバックがない場合は拒否 |

186| `"acceptEdits"` | ファイル編集と一般的なファイルシステムコマンド（`mkdir`、`touch`、`mv`、`cp` など）を自動承認します。他の Bash コマンドはデフォルトルールに従います |

187| `"plan"` | 読み取り専用ツールを実行します。Claude はソースファイルを編集せずに探索して計画を作成します |

188| `"dontAsk"` | プロンプトしません。[権限ルール](/ja/settings#permission-settings)によって事前承認されたツールが実行され、その他はすべて拒否されます |

189| `"auto"`（TypeScript のみ） | モデル分類器を使用して各ツール呼び出しを承認または拒否します。利用可能性と動作については、[自動モード](/ja/permission-modes#eliminate-prompts-with-auto-mode)を参照してください |

190| `"bypassPermissions"` | 尋ねずにすべての許可されたツールを実行します。Unix でルートとして実行する場合は使用できません。エージェントのアクションが気にするシステムに影響を与えられない隔離環境でのみ使用します |

191

192インタラクティブアプリケーションの場合は、ツール承認コールバックで `"default"` を使用して承認プロンプトを表示します。開発マシン上の自律型エージェントの場合は、`"acceptEdits"` を使用してファイル編集と一般的なファイルシステムコマンド（`mkdir`、`touch`、`mv`、`cp` など）を自動承認しながら、他の `Bash` コマンドを許可ルールの背後にゲートします。CI、コンテナ、またはその他の隔離環境に対して `"bypassPermissions"` を予約します。詳細については、[権限](/ja/agent-sdk/permissions)を参照してください。

193

194### モデル

195

196`model` を設定しない場合、SDK は Claude Code のデフォルトを使用します。これは認証方法とサブスクリプションによって異なります。特定のモデルをピン留めするか、より高速で安価なエージェント用に小さいモデルを使用するために明示的に設定します（たとえば、`model="claude-sonnet-4-6"`）。利用可能な ID については、[モデル](https://platform.claude.com/docs/ja/about-claude/models)を参照してください。

197

198## コンテキストウィンドウ

199

200コンテキストウィンドウは、セッション中に Claude が利用できる情報の総量です。セッション内のターン間でリセットされません。すべてが蓄積されます。システムプロンプト、ツール定義、会話履歴、ツール入力、およびツール出力。ターン間で同じままのコンテンツ（システムプロンプト、ツール定義、CLAUDE.md）は自動的に[プロンプトキャッシュ](https://platform.claude.com/docs/ja/build-with-claude/prompt-caching)され、繰り返されるプリフィックスのコストとレイテンシが削減されます。

201

202### コンテキストを消費するもの

203

204SDK でのコンテキストへの各コンポーネントの影響は次のとおりです。

205

206| ソース | ロード時期 | 影響 |

207| :----------------- | :---------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------- |

208| **システムプロンプト** | すべてのリクエスト | 小さい固定コスト、常に存在 |

209| **CLAUDE.md ファイル** | セッション開始時、[`settingSources`](/ja/agent-sdk/claude-code-features)経由 | すべてのリクエストで完全なコンテンツ（ただしプロンプトキャッシュされるため、最初のリクエストのみが完全なコストを支払う） |

210| **ツール定義** | すべてのリクエスト | 各ツールはそのスキーマを追加します。[MCP ツール検索](/ja/agent-sdk/mcp#mcp-tool-search)を使用して、すべてを一度にロードする代わりにオンデマンドでツールをロード |

211| **会話履歴** | ターン間で蓄積 | 各ターンで増加。プロンプト、応答、ツール入力、ツール出力 |

212| **スキル説明** | セッション開始時、設定ソース経由 | 短い要約。完全なコンテンツは呼び出し時のみロード |

213

214大きなツール出力は大量のコンテキストを消費します。大きなファイルを読み取るか、詳細な出力を含むコマンドを実行すると、単一のターンで数千のトークンを使用できます。コンテキストはターン間で蓄積されるため、多くのツール呼び出しを含む長いセッションは、短いセッションよりもはるかに多くのコンテキストを構築します。

215

216### 自動圧縮

217

218コンテキストウィンドウが制限に近づくと、SDK は会話を自動的に圧縮します。古い履歴を要約してスペースを解放し、最新の交換と重要な決定を保持します。SDK はこれが発生したときにストリームで `type: "system"` と `subtype: "compact_boundary"` を含むメッセージを生成します（Python では `SystemMessage`。TypeScript では別の `SDKCompactBoundaryMessage` タイプです）。

219

220圧縮は古いメッセージを要約に置き換えるため、会話の早い段階からの特定の指示は保持されない可能性があります。永続的なルールは初期プロンプトではなく CLAUDE.md に属します（[`settingSources`](/ja/agent-sdk/claude-code-features)経由でロード）。CLAUDE.md コンテンツはすべてのリクエストで再注入されるためです。

221

222圧縮動作をいくつかの方法でカスタマイズできます。

223

224* **CLAUDE.md の要約指示：** 圧縮機は他のコンテキストと同様に CLAUDE.md を読むため、要約時に保持する内容を指示するセクションを含めることができます。セクションヘッダーは自由形式です（マジック文字列ではありません）。圧縮機は意図に基づいて一致します。

225* **`PreCompact` フック：** 圧縮が発生する前にカスタムロジックを実行します。たとえば、完全なトランスクリプトをアーカイブします。フックは `trigger` フィールド（`manual` または `auto`）を受け取ります。[hooks](/ja/agent-sdk/hooks)を参照してください。

226* **手動圧縮：** `/compact` をプロンプト文字列として送信して、オンデマンドで圧縮をトリガーします。（この方法で送信されるスラッシュコマンドは CLI のみのショートカットではなく、SDK 入力です。[SDK のスラッシュコマンド](/ja/agent-sdk/slash-commands)を参照してください。）

227

228<Accordion title="例：CLAUDE.md の要約指示">

229 プロジェクトの CLAUDE.md にセクションを追加して、圧縮機に保持する内容を指示します。ヘッダー名は特別ではありません。明確なラベルを使用してください。

230

231 ```markdown CLAUDE.md theme={null}

232 # Summary instructions

233

234 When summarizing this conversation, always preserve:

235 - The current task objective and acceptance criteria

236 - File paths that have been read or modified

237 - Test results and error messages

238 - Decisions made and the reasoning behind them

239 ```

240</Accordion>

241

242### コンテキストを効率的に保つ

243

244長時間実行されるエージェントのいくつかの戦略。

245

246* **サブタスク用にサブエージェントを使用します。** 各サブエージェントは新しい会話で開始されます（以前のメッセージ履歴はありませんが、独自のシステムプロンプトとプロジェクトレベルのコンテキスト（CLAUDE.md など）をロードします）。親のターンは表示されず、最終応答のみが親にツール結果として返されます。メインエージェントのコンテキストは完全なサブタスクトランスクリプトではなく、その要約で増加します。詳細については、[サブエージェントが継承するもの](/ja/agent-sdk/subagents#what-subagents-inherit)を参照してください。

247* **ツールを選別します。** すべてのツール定義はコンテキストスペースを取ります。[`AgentDefinition`](/ja/agent-sdk/subagents#agentdefinition-configuration)の `tools` フィールドを使用してサブエージェントを必要な最小セットにスコープし、[MCP ツール検索](/ja/agent-sdk/mcp#mcp-tool-search)を使用してすべてをプリロードする代わりにオンデマンドでツールをロード。

248* **MCP サーバーコストを監視します。** 各 MCP サーバーはすべてのツールスキーマをすべてのリクエストに追加します。多くのツールを持つ少数のサーバーは、エージェントが何か作業を行う前に大量のコンテキストを消費できます。`ToolSearch` ツールはすべてをプリロードする代わりにオンデマンドでツールをロードすることで役立ちます。設定については、[MCP ツール検索](/ja/agent-sdk/mcp#mcp-tool-search)を参照してください。

249* **ルーチンタスクに低い努力を使用します。** ルーチンタスク用に[努力](#effort-level)を `"low"` に設定します。これはファイルを読み取るか、ディレクトリをリストするだけで済むエージェント用です。これはトークン使用量とコストを削減します。

250

251機能ごとのコンテキストコストの詳細な内訳については、[コンテキストコストを理解する](/ja/features-overview#understand-context-costs)を参照してください。

252

253## セッションと継続性

254

255SDK との各インタラクションはセッションを作成または継続します。`ResultMessage.session_id` からセッション ID をキャプチャして（両方の SDK で利用可能）、後で再開します。TypeScript SDK は init `SystemMessage` の直接フィールドとしても公開します。Python では、`SystemMessage.data` にネストされています。

256

257再開すると、以前のターンからの完全なコンテキストが復元されます。読み取られたファイル、実行された分析、および実行されたアクション。セッションをフォークして、元のセッションを変更せずに別のアプローチに分岐することもできます。

258

259セッション再開、継続、フォークパターンの完全なガイドについては、[セッション管理](/ja/agent-sdk/sessions)を参照してください。

260

261<Note>

262 Python では、`ClaudeSDKClient` は複数の呼び出し間でセッション ID を自動的に処理します。詳細については、[Python SDK リファレンス](/ja/agent-sdk/python#choosing-between-query-and-claudesdkclient)を参照してください。

263</Note>

264

265## 結果を処理する

266

267ループが終了すると、`ResultMessage` は何が起こったかを示し、出力を提供します。`subtype` フィールド（両方の SDK で利用可能）は、終了状態をチェックする主な方法です。

268

269| 結果サブタイプ | 何が起こったか | `result` フィールドは利用可能か？ |

270| :------------------------------------ | :------------------------------------------ | :-------------------: |

271| `success` | Claude は通常、タスクを完了しました | はい |

272| `error_max_turns` | 完了前に `maxTurns` 制限に達しました | いいえ |

273| `error_max_budget_usd` | 完了前に `maxBudgetUsd` 制限に達しました | いいえ |

274| `error_during_execution` | エラーがループを中断しました（たとえば、API 障害またはキャンセルされたリクエスト） | いいえ |

275| `error_max_structured_output_retries` | 構造化出力検証が設定された再試行制限後に失敗しました | いいえ |

276

277`result` フィールド（最終テキスト出力）は `success` バリアントにのみ存在するため、読み取る前に常にサブタイプをチェックしてください。すべての結果サブタイプは `total_cost_usd`、`usage`、`num_turns`、および `session_id` を持つため、コストを追跡し、エラー後でも再開できます。Python では、`total_cost_usd` と `usage` はオプションとして型付けされ、一部のエラーパスで `None` である可能性があるため、フォーマットする前にガードしてください。[コストと使用量の追跡](/ja/agent-sdk/cost-tracking)を参照して、`usage` フィールドの解釈の詳細を確認してください。

278

279結果には、モデルが最終ターンで生成を停止した理由を示す `stop_reason` フィールド（TypeScript では `string | null`、Python では `str | None`）も含まれます。一般的な値は `end_turn`（モデルが通常終了）、`max_tokens`（出力トークン制限に達した）、および `refusal`（モデルがリクエストを拒否）です。エラー結果サブタイプでは、`stop_reason` はループが終了する前の最後のアシスタント応答からの値を持ちます。拒否を検出するには、`stop_reason === "refusal"`（TypeScript）または `stop_reason == "refusal"`（Python）をチェックしてください。完全なタイプについては、[`SDKResultMessage`](/ja/agent-sdk/typescript#sdkresultmessage)（TypeScript）または[`ResultMessage`](/ja/agent-sdk/python#resultmessage)（Python）を参照してください。

280

281## Hooks

282

283[Hooks](/ja/agent-sdk/hooks)は、ループの特定のポイントで発火するコールバックです。ツールが実行される前、戻った後、エージェントが終了したときなど。一般的に使用されるフックは次のとおりです。

284

285| フック | 発火時期 | 一般的な用途 |

286| :------------------------------- | :------------- | :-------------------- |

287| `PreToolUse` | ツール実行前 | 入力を検証、危険なコマンドをブロック |

288| `PostToolUse` | ツール戻り後 | 出力を監査、副作用をトリガー |

289| `UserPromptSubmit` | プロンプト送信時 | プロンプトに追加コンテキストを注入 |

290| `Stop` | エージェント終了時 | 結果を検証、セッション状態を保存 |

291| `SubagentStart` / `SubagentStop` | サブエージェント生成/完了時 | 並列タスク結果を追跡して集約 |

292| `PreCompact` | コンテキスト圧縮前 | 要約前に完全なトランスクリプトをアーカイブ |

293

294フックはエージェントのコンテキストウィンドウ内ではなく、アプリケーションプロセスで実行されるため、コンテキストを消費しません。フックはループをショートサーキットすることもできます。ツール呼び出しを拒否する `PreToolUse` フックはそれが実行されるのを防ぎ、Claude は代わりに拒否メッセージを受け取ります。

295

296両方の SDK はすべての上記のイベントをサポートしています。TypeScript SDK には、Python がまだサポートしていない追加のイベントが含まれています。完全なイベントリスト、SDK ごとの利用可能性、および完全なコールバック API については、[フックで実行を制御する](/ja/agent-sdk/hooks)を参照してください。

297

298## すべてをまとめる

299

300この例は、このページの主要な概念を、失敗するテストを修正する単一のエージェントに組み合わせています。許可されたツール（自動承認されるため、エージェントが自律的に実行される）、プロジェクト設定、およびターンと推論努力の安全制限でエージェントを構成します。ループが実行されると、潜在的な再開のためにセッション ID をキャプチャし、最終結果を処理し、総コストを出力します。

301

302<CodeGroup>

303 ```python Python theme={null}

304 import asyncio

305 from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

306

307

308 async def run_agent():

309 session_id = None

310

311 async for message in query(

312 prompt="Find and fix the bug causing test failures in the auth module",

313 options=ClaudeAgentOptions(

314 allowed_tools=[

315 "Read",

316 "Edit",

317 "Bash",

318 "Glob",

319 "Grep",

320 ], # Listing tools here auto-approves them (no prompting)

321 setting_sources=[

322 "project"

323 ], # Load CLAUDE.md, skills, hooks from current directory

324 max_turns=30, # Prevent runaway sessions

325 effort="high", # Thorough reasoning for complex debugging

326 ),

327 ):

328 # Handle the final result

329 if isinstance(message, ResultMessage):

330 session_id = message.session_id # Save for potential resumption

331

332 if message.subtype == "success":

333 print(f"Done: {message.result}")

334 elif message.subtype == "error_max_turns":

335 # Agent ran out of turns. Resume with a higher limit.

336 print(f"Hit turn limit. Resume session {session_id} to continue.")

337 elif message.subtype == "error_max_budget_usd":

338 print("Hit budget limit.")

339 else:

340 print(f"Stopped: {message.subtype}")

341 if message.total_cost_usd is not None:

342 print(f"Cost: ${message.total_cost_usd:.4f}")

343

344

345 asyncio.run(run_agent())

346 ```

347

348 ```typescript TypeScript theme={null}

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

350

351 let sessionId: string | undefined;

352

353 for await (const message of query({

354 prompt: "Find and fix the bug causing test failures in the auth module",

355 options: {

356 allowedTools: ["Read", "Edit", "Bash", "Glob", "Grep"], // Listing tools here auto-approves them (no prompting)

357 settingSources: ["project"], // Load CLAUDE.md, skills, hooks from current directory

358 maxTurns: 30, // Prevent runaway sessions

359 effort: "high" // Thorough reasoning for complex debugging

360 }

361 })) {

362 // Save the session ID to resume later if needed

363 if (message.type === "system" && message.subtype === "init") {

364 sessionId = message.session_id;

365 }

366

367 // Handle the final result

368 if (message.type === "result") {

369 if (message.subtype === "success") {

370 console.log(`Done: ${message.result}`);

371 } else if (message.subtype === "error_max_turns") {

372 // Agent ran out of turns. Resume with a higher limit.

373 console.log(`Hit turn limit. Resume session ${sessionId} to continue.`);

374 } else if (message.subtype === "error_max_budget_usd") {

375 console.log("Hit budget limit.");

376 } else {

377 console.log(`Stopped: ${message.subtype}`);

378 }

379 console.log(`Cost: $${message.total_cost_usd.toFixed(4)}`);

380 }

381 }

382 ```

383</CodeGroup>

384

385## 次のステップ

386

387ループを理解したので、構築しているものに応じて、ここに行くべき場所があります。

388

389* **まだエージェントを実行していませんか？** [クイックスタート](/ja/agent-sdk/quickstart)から始めて、SDK をインストールし、完全な例をエンドツーエンドで実行してください。

390* **プロジェクトにフックする準備ができていますか？** [CLAUDE.md、スキル、ファイルシステムフックをロード](/ja/agent-sdk/claude-code-features)して、エージェントがプロジェクト規約に自動的に従うようにします。

391* **インタラクティブ UI を構築していますか？** [ストリーミング](/ja/agent-sdk/streaming-output)を有効にして、ループが実行されるときにライブテキストとツール呼び出しを表示します。

392* **エージェントが何をできるかについてより厳密な制御が必要ですか？** [権限](/ja/agent-sdk/permissions)でツールアクセスをロックダウンし、[フック](/ja/agent-sdk/hooks)を使用して、実行前にツール呼び出しを監査、ブロック、または変換します。

393* **長時間または高コストのタスクを実行していますか？** 隔離された作業を[サブエージェント](/ja/agent-sdk/subagents)にオフロードして、メインコンテキストをリーンに保ちます。

394

395agentic ループのより広い概念的な図（SDK 固有ではない）については、[Claude Code の仕組み](/ja/how-claude-code-works)を参照してください。

agent-sdk/hooks.md +11 −11

Details

236コールバックは 2 つのカテゴリのフィールドを持つオブジェクトを返します。236コールバックは 2 つのカテゴリのフィールドを持つオブジェクトを返します。

237 237

238* **トップレベルフィールド**は会話を制御します。`systemMessage` はモデルに表示される会話にメッセージを注入し、`continue`（Python では `continue_`）はこのフック後にエージェントが実行を続けるかどうかを決定します。238* **トップレベルフィールド**は会話を制御します。`systemMessage` はモデルに表示される会話にメッセージを注入し、`continue`（Python では `continue_`）はこのフック後にエージェントが実行を続けるかどうかを決定します。

239* **`hookSpecificOutput`** は現在の操作を制御します。内部のフィールドはフックイベントタイプに依存します。`PreToolUse` フックの場合、ここで `permissionDecision`（`"allow"`、`"deny"`、または `"ask"`）、`permissionDecisionReason`、および `updatedInput` を設定します。TypeScript SDK では、`permissionDecision` は `"defer"` も受け入れて、クエリを終了し[後で再開](/ja/hooks#defer-a-tool-call-for-later)します。この値は Python SDK では利用できません。`PostToolUse` フックの場合、`additionalContext` を設定してツール結果に情報を追加できます。239* **`hookSpecificOutput`** は現在の操作を制御します。内部のフィールドはフックイベントタイプに依存します。`PreToolUse` フックの場合、ここで `permissionDecision`（`"allow"`、`"deny"`、または `"ask"`）、`permissionDecisionReason`、および `updatedInput` を設定します。TypeScript SDK では、`permissionDecision` は `"defer"` も受け入れて、クエリを終了し[後で再開](/ja/hooks#defer-a-tool-call-for-later)します。この値は Python SDK では利用できません。`PostToolUse` フックの場合、`additionalContext` を設定してツール結果に情報を追加できます。または `updatedToolOutput` を設定して、Claude がそれを見る前にツールの出力全体を置き換えることができます。

240 240

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

242 242

417 ```417 ```

418</CodeGroup>418</CodeGroup>

419 419

420### 複数のフックをチェーンする420### 複数のフックを登録する

421 421

422フックは配列に表示される順序で実行されます。各フックを単一の責任に焦点を当てて、複雑なロジックのために複数のフックをチェーンします。422イベントが発火すると、すべてのマッチするフックが並列で実行されます。パーミッション決定の場合、最も制限的な結果が優先されます。単一の `deny` は、他のフックが何を返すかに関係なく、ツール呼び出しをブロックします。完了順序は非決定的であるため、別のフックが最初に実行されたことに依存するのではなく、各フックが独立して動作するように記述します。

423

424以下の例は、すべてのツール呼び出しに対して 3 つの独立したチェックを登録します。

423 425

424<CodeGroup>426<CodeGroup>

425 ```python Python theme={null}427 ```python Python theme={null}

426 options = ClaudeAgentOptions(428 options = ClaudeAgentOptions(

427 hooks={429 hooks={

428 "PreToolUse": [430 "PreToolUse": [

429 HookMatcher(hooks=[rate_limiter]), # 最初：レート制限をチェックする431 HookMatcher(hooks=[authorization_check]),

430 HookMatcher(hooks=[authorization_check]), # 次：パーミッションを確認する432 HookMatcher(hooks=[input_validator]),

431 HookMatcher(hooks=[input_sanitizer]), # 3 番目：入力をサニタイズする433 HookMatcher(hooks=[audit_logger]),

432 HookMatcher(hooks=[audit_logger]), # 最後：アクションをログする

433 ]434 ]

434 }435 }

435 )436 )

439 const options = {440 const options = {

440 hooks: {441 hooks: {

441 PreToolUse: [442 PreToolUse: [

442 { hooks: [rateLimiter] }, // 最初：レート制限をチェックする443 { hooks: [authorizationCheck] },

443 { hooks: [authorizationCheck] }, // 次：パーミッションを確認する444 { hooks: [inputValidator] },

444 { hooks: [inputSanitizer] }, // 3 番目：入力をサニタイズする445 { hooks: [auditLogger] }

445 { hooks: [auditLogger] } // 最後：アクションをログする

446 ]446 ]

447 }447 }

448 };448 };

agent-sdk/migration-guide.md +289 −0 created

Details

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

5# Claude Agent SDK への移行

7> Claude Code TypeScript および Python SDK を Claude Agent SDK に移行するためのガイド

9## 概要

11Claude Code SDK は **Claude Agent SDK** に名前が変更され、ドキュメントが再編成されました。この変更は、コーディングタスクだけでなく、AI エージェント構築のための SDK のより広い機能を反映しています。

13## 変更内容

15| 項目 | 旧版 | 新版 |

16| :---------------- | :-------------------------- | :------------------------------- |

17| **パッケージ名（TS/JS）** | `@anthropic-ai/claude-code` | `@anthropic-ai/claude-agent-sdk` |

18| **Python パッケージ** | `claude-code-sdk` | `claude-agent-sdk` |

19| **ドキュメント場所** | Claude Code ドキュメント | API ガイド → Agent SDK セクション |

21<Note>

22 **ドキュメント変更：** Agent SDK ドキュメントは Claude Code ドキュメントから API ガイドの専用 [Agent SDK](/ja/agent-sdk/overview) セクションに移動しました。Claude Code ドキュメントは現在、CLI ツールと自動化機能に焦点を当てています。

23</Note>

25## 移行手順

27### TypeScript/JavaScript プロジェクト向け

29**1. 古いパッケージをアンインストールします：**

31```bash theme={null}

32npm uninstall @anthropic-ai/claude-code

33```

35**2. 新しいパッケージをインストールします：**

37```bash theme={null}

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

39```

41**3. インポートを更新します：**

43`@anthropic-ai/claude-code` からのすべてのインポートを `@anthropic-ai/claude-agent-sdk` に変更します：

45```typescript theme={null}

46// 変更前

47import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-code";

49// 変更後

50import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";

51```

53**4. package.json の依存関係を更新します：**

55`package.json` にパッケージがリストされている場合は、更新します：

57変更前：

59```json theme={null}

60{

61 "dependencies": {

62 "@anthropic-ai/claude-code": "^0.0.42"

63 }

64}

65```

67変更後：

69```json theme={null}

70{

71 "dependencies": {

72 "@anthropic-ai/claude-agent-sdk": "^0.2.0"

73 }

74}

75```

77以上です。他のコード変更は必要ありません。

79### Python プロジェクト向け

81**1. 古いパッケージをアンインストールします：**

83```bash theme={null}

84pip uninstall claude-code-sdk

85```

87**2. 新しいパッケージをインストールします：**

89```bash theme={null}

90pip install claude-agent-sdk

91```

93**3. インポートを更新します：**

95`claude_code_sdk` からのすべてのインポートを `claude_agent_sdk` に変更します：

97```python theme={null}

98# 変更前

99from claude_code_sdk import query, ClaudeCodeOptions

100

101# 変更後

102from claude_agent_sdk import query, ClaudeAgentOptions

103```

104

105**4. 型名を更新します：**

106

107`ClaudeCodeOptions` を `ClaudeAgentOptions` に変更します：

108

109```python theme={null}

110# 変更前

111from claude_code_sdk import query, ClaudeCodeOptions

112

113options = ClaudeCodeOptions(model="claude-opus-4-7")

114

115# 変更後

116from claude_agent_sdk import query, ClaudeAgentOptions

117

118options = ClaudeAgentOptions(model="claude-opus-4-7")

119```

120

121**5. [破壊的変更](#breaking-changes) を確認します**

122

123移行を完了するために必要なコード変更を行います。

124

125## 破壊的変更

126

127<Warning>

128 分離と明示的な設定を改善するため、Claude Agent SDK v0.1.0 は Claude Code SDK から移行するユーザーに対して破壊的変更を導入しています。移行前にこのセクションを注意深く確認してください。

129</Warning>

130

131### Python：ClaudeCodeOptions が ClaudeAgentOptions に名前変更

132

133**変更内容：** Python SDK の型 `ClaudeCodeOptions` が `ClaudeAgentOptions` に名前変更されました。

134

135**移行：**

136

137```python theme={null}

138# 変更前（claude-code-sdk）

139from claude_code_sdk import query, ClaudeCodeOptions

140

141options = ClaudeCodeOptions(model="claude-opus-4-7", permission_mode="acceptEdits")

142

143# 変更後（claude-agent-sdk）

144from claude_agent_sdk import query, ClaudeAgentOptions

145

146options = ClaudeAgentOptions(model="claude-opus-4-7", permission_mode="acceptEdits")

147```

148

149**変更理由：** 型名は「Claude Agent SDK」ブランディングと一致し、SDK の命名規則全体で一貫性を提供します。

150

151### システムプロンプトがデフォルトではなくなりました

152

153**変更内容：** SDK はデフォルトで Claude Code のシステムプロンプトを使用しなくなりました。

154

155**移行：**

156

157<CodeGroup>

158 ```typescript TypeScript theme={null}

159 // 変更前（v0.0.x）- デフォルトで Claude Code のシステムプロンプトを使用

160 const result = query({ prompt: "Hello" });

161

162 // 変更後（v0.1.0）- デフォルトで最小限のシステムプロンプトを使用

163 // 古い動作を取得するには、Claude Code のプリセットを明示的にリクエストします：

164 const result = query({

165 prompt: "Hello",

166 options: {

167 systemPrompt: { type: "preset", preset: "claude_code" }

168 }

169 });

170

171 // またはカスタムシステムプロンプトを使用します：

172 const result = query({

173 prompt: "Hello",

174 options: {

175 systemPrompt: "You are a helpful coding assistant"

176 }

177 });

178 ```

179

180 ```python Python theme={null}

181 # 変更前（v0.0.x）- デフォルトで Claude Code のシステムプロンプトを使用

182 async for message in query(prompt="Hello"):

183 print(message)

184

185 # 変更後（v0.1.0）- デフォルトで最小限のシステムプロンプトを使用

186 # 古い動作を取得するには、Claude Code のプリセットを明示的にリクエストします：

187 from claude_agent_sdk import query, ClaudeAgentOptions

188

189 async for message in query(

190 prompt="Hello",

191 options=ClaudeAgentOptions(

192 system_prompt={"type": "preset", "preset": "claude_code"} # プリセットを使用

193 ),

194 ):

195 print(message)

196

197 # またはカスタムシステムプロンプトを使用します：

198 async for message in query(

199 prompt="Hello",

200 options=ClaudeAgentOptions(system_prompt="You are a helpful coding assistant"),

201 ):

202 print(message)

203 ```

204</CodeGroup>

205

206**変更理由：** SDK アプリケーションのより良い制御と分離を提供します。Claude Code の CLI 中心の指示を継承することなく、カスタム動作を持つエージェントを構築できるようになりました。

207

208### 設定ソースのデフォルト

209

210このデフォルトは v0.1.0 で一度変更されてから元に戻されたため、移行アクションは必要ありません。

211

212**現在の動作：** `query()` で `settingSources` を省略すると、ユーザー、プロジェクト、ローカルファイルシステムの設定が読み込まれ、CLI と一致します。これには `~/.claude/settings.json`、`.claude/settings.json`、`.claude/settings.local.json`、CLAUDE.md ファイル、およびカスタムコマンドが含まれます。

213

214ファイルシステム設定から分離して実行するには、空の配列を渡します：

215

216<CodeGroup>

217 ```typescript TypeScript theme={null}

218 const result = query({

219 prompt: "Hello",

220 options: {

221 settingSources: [] // ファイルシステム設定は読み込まれません

222 }

223 });

224

225 // または特定のソースのみを読み込みます：

226 const result = query({

227 prompt: "Hello",

228 options: {

229 settingSources: ["project"] // プロジェクト設定のみ

230 }

231 });

232 ```

233

234 ```python Python theme={null}

235 from claude_agent_sdk import query, ClaudeAgentOptions

236

237 async for message in query(

238 prompt="Hello",

239 options=ClaudeAgentOptions(setting_sources=[]), # ファイルシステム設定は読み込まれません

240 ):

241 print(message)

242

243 # または特定のソースのみを読み込みます：

244 async for message in query(

245 prompt="Hello",

246 options=ClaudeAgentOptions(

247 setting_sources=["project"] # プロジェクト設定のみ

248 ),

249 ):

250 print(message)

251 ```

252</CodeGroup>

253

254分離は、ローカルのカスタマイズがリークしてはいけない CI/CD パイプライン、デプロイされたアプリケーション、テスト環境、マルチテナントシステムで特に重要です。

255

256<Note>

257 SDK v0.1.0 は一度設定が読み込まれないようにデフォルト設定されましたが、その後のリリースで元に戻されました。Python SDK 0.1.59 以前は空のリストをオプションを省略するのと同じように扱ったため、`setting_sources=[]` に依存する前にアップグレードしてください。`settingSources` が `[]` の場合でも読み込まれる入力については、[What settingSources does not control](/ja/agent-sdk/claude-code-features#what-settingsources-does-not-control) を参照してください。

258</Note>

259

260## 名前変更の理由

261

262Claude Code SDK はもともとコーディングタスク用に設計されていましたが、あらゆるタイプの AI エージェント構築のための強力なフレームワークに進化しました。新しい名前「Claude Agent SDK」はその機能をより良く反映しています：

263

264* ビジネスエージェントの構築（法務アシスタント、ファイナンスアドバイザー、カスタマーサポート）

265* 特化したコーディングエージェントの作成（SRE ボット、セキュリティレビュアー、コードレビューエージェント）

266* ツール使用、MCP 統合など、あらゆるドメイン向けのカスタムエージェント開発

267

268## ヘルプを得る

269

270移行中に問題が発生した場合：

271

272**TypeScript/JavaScript の場合：**

273

2741. すべてのインポートが `@anthropic-ai/claude-agent-sdk` を使用するように更新されていることを確認します

2752. package.json に新しいパッケージ名があることを確認します

2763. `npm install` を実行して、依存関係が更新されていることを確認します

277

278**Python の場合：**

279

2801. すべてのインポートが `claude_agent_sdk` を使用するように更新されていることを確認します

2812. requirements.txt または pyproject.toml に新しいパッケージ名があることを確認します

2823. `pip install claude-agent-sdk` を実行して、パッケージがインストールされていることを確認します

283

284## 次のステップ

285

286* [Agent SDK Overview](/ja/agent-sdk/overview) を探索して、利用可能な機能について学びます

287* [TypeScript SDK Reference](/ja/agent-sdk/typescript) をチェックして、詳細な API ドキュメントを確認します

288* [Python SDK Reference](/ja/agent-sdk/python) を確認して、Python 固有のドキュメントを確認します

289* [Custom Tools](/ja/agent-sdk/custom-tools) と [MCP Integration](/ja/agent-sdk/mcp) について学びます

agent-sdk/permissions.md +242 −0 created

Details

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

5# パーミッションの設定

7> パーミッションモード、フック、宣言的な許可/拒否ルールを使用して、エージェントがツールをどのように使用するかを制御します。

9Claude Agent SDK は、Claude がツールをどのように使用するかを管理するためのパーミッション制御を提供します。パーミッションモードとルールを使用して、自動的に許可されるものを定義し、[`canUseTool` コールバック](/ja/agent-sdk/user-input)を使用して、実行時にそれ以外のすべてを処理します。

11<Note>

12 このページはパーミッションモードとルールについて説明しています。ユーザーが実行時にツールリクエストを承認または拒否する対話的な承認フローを構築するには、[承認とユーザー入力の処理](/ja/agent-sdk/user-input)を参照してください。

13</Note>

15## パーミッションの評価方法

17Claude がツールをリクエストすると、SDK は次の順序でパーミッションをチェックします。

19<Steps>

20 <Step title="フック">

21 最初に[フック](/ja/agent-sdk/hooks)を実行します。フックはコールを直接拒否するか、それを渡すことができます。`allow` を返すフックは、以下の拒否および質問ルールをスキップしません。これらはフックの結果に関係なく評価されます。

22 </Step>

24 <Step title="拒否ルール">

25 `deny` ルール（`disallowed_tools` および[settings.json](/ja/settings#permission-settings)から）をチェックします。拒否ルールが一致する場合、`bypassPermissions` モードでもツールはブロックされます。

26 </Step>

28 <Step title="パーミッションモード">

29 アクティブな[パーミッションモード](#permission-modes)を適用します。`bypassPermissions` はこのステップに到達したすべてを承認します。`acceptEdits` はファイル操作を承認します。その他のモードはフォールスルーします。

30 </Step>

32 <Step title="許可ルール">

33 `allow` ルール（`allowed_tools` および settings.json から）をチェックします。ルールが一致する場合、ツールは承認されます。

34 </Step>

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

37 上記のいずれでも解決されない場合、決定のために[`canUseTool` コールバック](/ja/agent-sdk/user-input)を呼び出します。`dontAsk` モードでは、このステップはスキップされ、ツールは拒否されます。

38 </Step>

39</Steps>

41<img src="https://mintcdn.com/claude-code/FEspvVUyRuaWjm0s/images/agent-sdk/permissions-flow.svg?fit=max&auto=format&n=FEspvVUyRuaWjm0s&q=85&s=a1759b0cf4541281a9fdd8f5348228e8" alt="パーミッション評価フロー図" width="920" height="260" data-path="images/agent-sdk/permissions-flow.svg" />

43このページは**許可および拒否ルール**と**パーミッションモード**に焦点を当てています。その他のステップについては、以下を参照してください。

45* **フック：** カスタムコードを実行して、ツールリクエストを許可、拒否、または変更します。[フックで実行を制御](/ja/agent-sdk/hooks)を参照してください。

46* **canUseTool コールバック：** 実行時にユーザーに承認を促します。[承認とユーザー入力の処理](/ja/agent-sdk/user-input)を参照してください。

48## 許可および拒否ルール

50`allowed_tools` および `disallowed_tools`（TypeScript：`allowedTools` / `disallowedTools`）は、上記の評価フロー内の許可および拒否ルールリストにエントリを追加します。これらは、ツール呼び出しが承認されるかどうかを制御し、ツールが Claude に利用可能かどうかではありません。

52| オプション | 効果 |

53| :------------------------------- | :------------------------------------------------------------------------------------------ |

54| `allowed_tools=["Read", "Grep"]` | `Read` および `Grep` は自動承認されます。ここにリストされていないツールは引き続き存在し、パーミッションモードおよび `canUseTool` にフォールスルーします。 |

55| `disallowed_tools=["Bash"]` | `Bash` は常に拒否されます。拒否ルールは最初にチェックされ、`bypassPermissions` を含むすべてのパーミッションモードで保持されます。 |

57ロックダウンされたエージェントの場合、`allowedTools` を `permissionMode: "dontAsk"` と組み合わせます。リストされたツールは承認されます。その他のものはプロンプトの代わりに直接拒否されます。

59```typescript theme={null}

60const options = {

61 allowedTools: ["Read", "Glob", "Grep"],

62 permissionMode: "dontAsk"

63};

64```

66<Warning>

67 **`allowed_tools` は `bypassPermissions` を制限しません。** `allowed_tools` はリストしたツールのみを事前承認します。リストされていないツールは許可ルールと一致せず、パーミッションモードにフォールスルーします。ここで `bypassPermissions` はそれらを承認します。`allowed_tools=["Read"]` を `permission_mode="bypassPermissions"` と一緒に設定すると、`Bash`、`Write`、`Edit` を含むすべてのツールが承認されます。`bypassPermissions` が必要だが特定のツールをブロックしたい場合は、`disallowed_tools` を使用してください。

68</Warning>

70`.claude/settings.json` で許可、拒否、および質問ルールを宣言的に設定することもできます。これらのルールは、`project` 設定ソースが有効な場合に読み込まれます。デフォルトの `query()` オプションではこれが有効です。`setting_sources`（TypeScript：`settingSources`）を明示的に設定する場合は、それらを適用するために `"project"` を含めてください。ルール構文については、[パーミッション設定](/ja/settings#permission-settings)を参照してください。

72## パーミッションモード

74パーミッションモードは、Claude がツールをどのように使用するかについてのグローバル制御を提供します。`query()` を呼び出すときにパーミッションモードを設定するか、ストリーミングセッション中に動的に変更できます。

76### 利用可能なモード

78SDK は以下のパーミッションモードをサポートしています。

80| モード | 説明 | ツール動作 |

81| :-------------------- | :------------------- | :----------------------------------------------------------------------------------------------------------- |

82| `default` | 標準パーミッション動作 | 自動承認なし。一致しないツールは `canUseTool` コールバックをトリガーします |

83| `dontAsk` | プロンプトの代わりに拒否 | `allowed_tools` またはルールで事前承認されていないものはすべて拒否されます。`canUseTool` は呼び出されません |

84| `acceptEdits` | ファイル編集を自動受け入れ | ファイル編集および[ファイルシステム操作](#accept-edits-mode-acceptedits)（`mkdir`、`rm`、`mv` など）は自動的に承認されます |

85| `bypassPermissions` | すべてのパーミッションチェックをバイパス | すべてのツールはパーミッションプロンプトなしで実行されます（注意して使用してください） |

86| `plan` | 計画モード | 読み取り専用ツールが実行されます。Claude はソースファイルを編集せずに分析および計画します |

87| `auto`（TypeScript のみ） | モデル分類承認 | モデル分類器が各ツール呼び出しを承認または拒否します。利用可能性については[自動モード](/ja/permission-modes#eliminate-prompts-with-auto-mode)を参照してください |

89<Warning>

90 **サブエージェント継承：** 親が `bypassPermissions`、`acceptEdits`、または `auto` を使用する場合、すべてのサブエージェントはそのモードを継承し、サブエージェントごとにオーバーライドすることはできません。サブエージェントはシステムプロンプトが異なり、メインエージェントよりも制約が少ない動作をする可能性があるため、`bypassPermissions` を継承すると、承認プロンプトなしで完全な自律的なシステムアクセスが付与されます。

91</Warning>

93### パーミッションモードの設定

95クエリを開始するときにパーミッションモードを一度設定するか、セッションがアクティブな間に動的に変更できます。

97<Tabs>

98 <Tab title="クエリ時">

99 クエリを作成するときに `permission_mode`（Python）または `permissionMode`（TypeScript）を渡します。このモードは、動的に変更されない限り、セッション全体に適用されます。

100

101 <CodeGroup>

102 ```python Python theme={null}

103 import asyncio

104 from claude_agent_sdk import query, ClaudeAgentOptions

105

106

107 async def main():

108 async for message in query(

109 prompt="Help me refactor this code",

110 options=ClaudeAgentOptions(

111 permission_mode="default", # ここでモードを設定

112 ),

113 ):

114 if hasattr(message, "result"):

115 print(message.result)

116

117

118 asyncio.run(main())

119 ```

120

121 ```typescript TypeScript theme={null}

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

123

124 async function main() {

125 for await (const message of query({

126 prompt: "Help me refactor this code",

127 options: {

128 permissionMode: "default" // ここでモードを設定

129 }

130 })) {

131 if ("result" in message) {

132 console.log(message.result);

133 }

134 }

135 }

136

137 main();

138 ```

139 </CodeGroup>

140 </Tab>

141

142 <Tab title="ストリーミング中">

143 `set_permission_mode()`（Python）または `setPermissionMode()`（TypeScript）を呼び出して、セッション中盤でモードを変更します。新しいモードは、その後のすべてのツールリクエストに対して直ちに有効になります。これにより、制限的に開始し、信頼が構築されるにつれてパーミッションを緩和できます。たとえば、Claude の初期アプローチをレビューした後に `acceptEdits` に切り替えます。

144

145 <CodeGroup>

146 ```python Python theme={null}

147 import asyncio

148 from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

149

150

151 async def main():

152 async with ClaudeSDKClient(

153 options=ClaudeAgentOptions(

154 permission_mode="default", # デフォルトモードで開始

155 )

156 ) as client:

157 await client.query("Help me refactor this code")

158

159 # セッション中盤でモードを動的に変更

160 await client.set_permission_mode("acceptEdits")

161

162 # 新しいパーミッションモードでメッセージを処理

163 async for message in client.receive_response():

164 if hasattr(message, "result"):

165 print(message.result)

166

167

168 asyncio.run(main())

169 ```

170

171 ```typescript TypeScript theme={null}

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

173

174 async function main() {

175 const q = query({

176 prompt: "Help me refactor this code",

177 options: {

178 permissionMode: "default" // デフォルトモードで開始

179 }

180 });

181

182 // セッション中盤でモードを動的に変更

183 await q.setPermissionMode("acceptEdits");

184

185 // 新しいパーミッションモードでメッセージを処理

186 for await (const message of q) {

187 if ("result" in message) {

188 console.log(message.result);

189 }

190 }

191 }

192

193 main();

194 ```

195 </CodeGroup>

196 </Tab>

197</Tabs>

198

199### モードの詳細

200

201#### ファイル編集モード（`acceptEdits`）

202

203ファイル操作を自動承認し、Claude がプロンプトなしでコードを編集できるようにします。その他のツール（ファイルシステム操作ではない Bash コマンドなど）は引き続き通常のパーミッションが必要です。

204

205**自動承認される操作：**

206

207* ファイル編集（Edit、Write ツール）

208* ファイルシステムコマンド：`mkdir`、`touch`、`rm`、`rmdir`、`mv`、`cp`、`sed`

209

210どちらも、作業ディレクトリまたは `additionalDirectories` 内のパスにのみ適用されます。そのスコープ外のパスおよび保護されたパスへの書き込みはプロンプトが表示されます。

211

212**使用時期：** Claude の編集を信頼し、プロトタイピング中など、より高速な反復を望む場合、または分離されたディレクトリで作業する場合。

213

214#### 質問しないモード（`dontAsk`）

215

216パーミッションプロンプトを拒否に変換します。`allowed_tools`、`settings.json` 許可ルール、またはフックで事前承認されたツールは通常どおり実行されます。その他のすべては `canUseTool` を呼び出さずに拒否されます。

217

218**使用時期：** ヘッドレスエージェント用に固定された明示的なツール表面が必要で、`canUseTool` が存在しないことへの暗黙的な依存よりもハード拒否を優先する場合。

219

220#### パーミッションバイパスモード（`bypassPermissions`）

221

222プロンプトなしですべてのツール使用を自動承認します。フックは引き続き実行され、必要に応じて操作をブロックできます。

223

224<Warning>

225 極度の注意を持って使用してください。Claude はこのモードでフルシステムアクセスを持ちます。すべての可能な操作を信頼できる制御された環境でのみ使用してください。

226

227 `allowed_tools` はこのモードを制限しません。リストしたツールだけでなく、すべてのツールが承認されます。拒否ルール（`disallowed_tools`）、明示的な `ask` ルール、およびフックはモードチェック前に評価され、ツールをブロックできます。

228</Warning>

229

230#### 計画モード（`plan`）

231

232Claude を読み取り専用ツールに制限します。Claude はファイルを読み取り、読み取り専用シェルコマンドを実行してコードベースを探索できますが、ソースファイルは編集しません。Claude は `AskUserQuestion` を使用して、計画を最終化する前に要件を明確にする場合があります。これらのプロンプトの処理については、[承認とユーザー入力の処理](/ja/agent-sdk/user-input#handle-clarifying-questions)を参照してください。

233

234**使用時期：** Claude に変更を提案させたいが実行させたくない場合、たとえばコードレビュー中または変更を実行する前に承認が必要な場合。

235

236## 関連リソース

237

238パーミッション評価フロー内の他のステップについては、以下を参照してください。

239

240* [承認とユーザー入力の処理](/ja/agent-sdk/user-input)：対話的な承認プロンプトと明確化の質問

241* [フックガイド](/ja/agent-sdk/hooks)：エージェントライフサイクルの主要なポイントでカスタムコードを実行

242* [パーミッションルール](/ja/settings#permission-settings)：`settings.json` の宣言的な許可/拒否ルール

agent-sdk/python.md +38 −36

Details

113#### パラメータ113#### パラメータ

114 114

115| パラメータ | 型 | 説明 |115| パラメータ | 型 | 説明 |

116| :------------- | :----------------------------------------------- | :------------------------------------- |116| :------------- | :---------------------------------------------- | :------------------------------------- |

117| `name` | `str` | ツールの一意の識別子 |117| `name` | `str` | ツールの一意の識別子 |

118| `description` | `str` | ツールが何をするかの人間が読める説明 |118| `description` | `str` | ツールが何をするかの人間が読める説明 |

121 121

122#### 入力スキーマオプション122#### 入力スキーマオプション

123 123

269| `cwd` | `str \| None` | セッションの作業ディレクトリ |269| `cwd` | `str \| None` | セッションの作業ディレクトリ |

270| `tag` | `str \| None` | ユーザーが設定したセッションタグ（[`tag_session()`](#tag-session) を参照） |270| `tag` | `str \| None` | ユーザーが設定したセッションタグ（[`tag_session()`](#tag_session) を参照） |

272 272

273#### 例273#### 例

301| `session_id` | `str` | 必須 | メッセージを取得するセッション ID |301| `session_id` | `str` | 必須 | メッセージを取得するセッション ID |

304| `offset` | `int` | `0` | 開始からスキップするメッセージ数 |304| `offset` | `int` | `0` | 開始からスキップするメッセージ数 |

305 305

306#### 戻り値の型：`SessionMessage`306#### 戻り値の型：`SessionMessage`

307 307

343| `session_id` | `str` | 必須 | 検索するセッションの UUID |343| `session_id` | `str` | 必須 | 検索するセッションの UUID |

345 345

346[`SDKSessionInfo`](#return-type-sdk-session-info) を返すか、セッションが見つからない場合は `None`。346[`SDKSessionInfo`](#return-type-sdksessioninfo) を返すか、セッションが見つからない場合は `None`。

347 347

348#### 例348#### 例

349 349

381 381

382#### 例382#### 例

383 383

384最新のセッションの名前を変更して、後で見つけやすくします。新しいタイトルは、その後の読み取りで [`SDKSessionInfo.custom_title`](#return-type-sdk-session-info) に表示されます。384最新のセッションの名前を変更して、後で見つけやすくします。新しいタイトルは、その後の読み取りで [`SDKSessionInfo.custom_title`](#return-type-sdksessioninfo) に表示されます。

385 385

386```python theme={null}386```python theme={null}

387from claude_agent_sdk import list_sessions, rename_session387from claude_agent_sdk import list_sessions, rename_session

478| `rewind_files(user_message_id)` | ファイルを指定されたユーザーメッセージの状態に復元します。`enable_file_checkpointing=True` が必要です。[ファイルチェックポイント](/ja/agent-sdk/file-checkpointing) を参照 |478| `rewind_files(user_message_id)` | ファイルを指定されたユーザーメッセージの状態に復元します。`enable_file_checkpointing=True` が必要です。[ファイルチェックポイント](/ja/agent-sdk/file-checkpointing) を参照 |

482| `stop_task(task_id)` | 実行中のバックグラウンドタスクを停止します。ステータス `"stopped"` の [`TaskNotificationMessage`](#task-notification-message) がメッセージストリームに続きます |482| `stop_task(task_id)` | 実行中のバックグラウンドタスクを停止します。ステータス `"stopped"` の [`TaskNotificationMessage`](#tasknotificationmessage) がメッセージストリームに続きます |

485 485

791 effort: Literal["low", "medium", "high", "max"] | None = None791 effort: Literal["low", "medium", "high", "max"] | None = None

792 enable_file_checkpointing: bool = False792 enable_file_checkpointing: bool = False

793 session_store: SessionStore | None = None793 session_store: SessionStore | None = None

794 session_store_flush: SessionStoreFlushMode = "batched"

794```795```

795 796

796| プロパティ | 型 | デフォルト | 説明 |797| プロパティ | 型 | デフォルト | 説明 |

797| :---------------------------- | :------------------------------------------------------------------------------------- | :------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |798| :---------------------------- | :------------------------------------------------------------------------------------ | :------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |

798| `tools` | `list[str] \| ToolsPreset \| None` | `None` | ツール設定。Claude Code のデフォルトツールには `{"type": "preset", "preset": "claude_code"}` を使用します |799| `tools` | `list[str] \| ToolsPreset \| None` | `None` | ツール設定。Claude Code のデフォルトツールには `{"type": "preset", "preset": "claude_code"}` を使用します |

799| `allowed_tools` | `list[str]` | `[]` | プロンプトなしで自動承認するツール。これは Claude をこれらのツールのみに制限しません。リストされていないツールは `permission_mode` と `can_use_tool` にフォールスルーします。`disallowed_tools` を使用してツールをブロックします。[パーミッション](/ja/agent-sdk/permissions#allow-and-deny-rules) を参照 |800| `allowed_tools` | `list[str]` | `[]` | プロンプトなしで自動承認するツール。これは Claude をこれらのツールのみに制限しません。リストされていないツールは `permission_mode` と `can_use_tool` にフォールスルーします。`disallowed_tools` を使用してツールをブロックします。[パーミッション](/ja/agent-sdk/permissions#allow-and-deny-rules) を参照 |

800| `system_prompt` | `str \| SystemPromptPreset \| None` | `None` | システムプロンプト設定。カスタムプロンプトの場合は文字列を渡すか、Claude Code のシステムプロンプトの場合は `{"type": "preset", "preset": "claude_code"}` を使用します。プリセットを拡張するには `"append"` を追加します |801| `system_prompt` | `str \| SystemPromptPreset \| None` | `None` | システムプロンプト設定。カスタムプロンプトの場合は文字列を渡すか、Claude Code のシステムプロンプトの場合は `{"type": "preset", "preset": "claude_code"}` を使用します。プリセットを拡張するには `"append"` を追加します |

812| `output_format` | `dict[str, Any] \| None` | `None` | 構造化応答の出力形式（例：`{"type": "json_schema", "schema": {...}}`）。詳細については [構造化出力](/ja/agent-sdk/structured-outputs) を参照 |813| `output_format` | `dict[str, Any] \| None` | `None` | 構造化応答の出力形式（例：`{"type": "json_schema", "schema": {...}}`）。詳細については [構造化出力](/ja/agent-sdk/structured-outputs) を参照 |

814| `cwd` | `str \| Path \| None` | `None` | 現在の作業ディレクトリ |815| `cwd` | `str \| Path \| None` | `None` | 現在の作業ディレクトリ |

831| `setting_sources` | `list[SettingSource] \| None` | `None`（CLI デフォルト：すべてのソース） | 読み込むファイルシステム設定を制御します。`[]` を渡してユーザー、プロジェクト、ローカル設定を無効にします。管理ポリシー設定は常に読み込まれます。[Claude Code 機能を使用](/ja/agent-sdk/claude-code-features#what-settingsources-does-not-control) を参照 |832| `setting_sources` | `list[SettingSource] \| None` | `None`（CLI デフォルト：すべてのソース） | 読み込むファイルシステム設定を制御します。`[]` を渡してユーザー、プロジェクト、ローカル設定を無効にします。管理ポリシー設定は常に読み込まれます。[Claude Code 機能を使用](/ja/agent-sdk/claude-code-features#what-settingsources-does-not-control) を参照 |

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

836 838

837### `OutputFormat`839### `OutputFormat`

838 840

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

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

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

1034| `permissionMode` | いいえ | このエージェント内のツール実行のパーミッションモード。[`PermissionMode`](#permission-mode) を参照 |1036| `permissionMode` | いいえ | このエージェント内のツール実行のパーミッションモード。[`PermissionMode`](#permissionmode) を参照 |

1035 1037

1036<Note>1038<Note>

1037 `AgentDefinition` フィールド名は `disallowedTools`、`permissionMode`、`maxTurns` などの camelCase を使用します。これらの名前は TypeScript SDK と共有される wire 形式に直接マップされます。これは `disallowed_tools` と `permission_mode` などの同等のトップレベルフィールドに Python snake\_case を使用する `ClaudeAgentOptions` とは異なります。`AgentDefinition` は dataclass であるため、snake\_case キーワードを渡すと構築時に `TypeError` が発生します。1039 `AgentDefinition` フィールド名は `disallowedTools`、`permissionMode`、`maxTurns` などの camelCase を使用します。これらの名前は TypeScript SDK と共有される wire 形式に直接マップされます。これは `disallowed_tools` と `permission_mode` などの同等のトップレベルフィールドに Python snake\_case を使用する `ClaudeAgentOptions` とは異なります。`AgentDefinition` は dataclass であるため、snake\_case キーワードを渡すと構築時に `TypeError` が発生します。

1045PermissionMode = Literal[1047PermissionMode = Literal[

1046 "default", # Standard permission behavior1048 "default", # Standard permission behavior

1047 "acceptEdits", # Auto-accept file edits1049 "acceptEdits", # Auto-accept file edits

1048 "plan", # Planning mode - no execution1050 "plan", # Planning mode - read-only tools only

1049 "dontAsk", # Deny anything not pre-approved instead of prompting1051 "dontAsk", # Deny anything not pre-approved instead of prompting

1050 "bypassPermissions", # Bypass all permission checks (use with caution)1052 "bypassPermissions", # Bypass all permission checks (use with caution)

1051]1053]

1081```1083```

1082 1084

1083| フィールド | 型 | 説明 |1085| フィールド | 型 | 説明 |

1084| :------------ | :----------------------- | :----------------- |1086| :------------ | :----------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------- |

1087 1089

1088### `PermissionResult`1090### `PermissionResult`

1089 1091

1289 1291

1290### `McpServerStatusConfig`1292### `McpServerStatusConfig`

1291 1293

1292[`get_mcp_status()`](#methods) によって報告される MCP サーバーの設定。これは、すべての [`McpServerConfig`](#mcp-server-config) トランスポートバリアント、および claude.ai を通じてプロキシされるサーバー用の出力のみの `claudeai-proxy` バリアントの Union です。1294[`get_mcp_status()`](#methods) によって報告される MCP サーバーの設定。これは、すべての [`McpServerConfig`](#mcpserverconfig) トランスポートバリアント、および claude.ai を通じてプロキシされるサーバー用の出力のみの `claudeai-proxy` バリアントの Union です。

1293 1295

1294```python theme={null}1296```python theme={null}

1295McpServerStatusConfig = (1297McpServerStatusConfig = (

1301)1303)

1302```1304```

1303 1305

1304`McpSdkServerConfigStatus` は [`McpSdkServerConfig`](#mcp-sdk-server-config) のシリアライズ可能な形式で、`type`（`"sdk"`）と `name`（`str`）フィールドのみです。インプロセス `instance` は省略されます。`McpClaudeAIProxyServerConfig` には `type`（`"claudeai-proxy"`）、`url`（`str`）、`id`（`str`）フィールドがあります。1306`McpSdkServerConfigStatus` は [`McpSdkServerConfig`](#mcpsdkserverconfig) のシリアライズ可能な形式で、`type`（`"sdk"`）と `name`（`str`）フィールドのみです。インプロセス `instance` は省略されます。`McpClaudeAIProxyServerConfig` には `type`（`"claudeai-proxy"`）、`url`（`str`）、`id`（`str`）フィールドがあります。

1305 1307

1306### `McpStatusResponse`1308### `McpStatusResponse`

1307 1309

1314 1316

1315### `McpServerStatus`1317### `McpServerStatus`

1316 1318

1317接続された MCP サーバーのステータス。[`McpStatusResponse`](#mcp-status-response) に含まれます。1319接続された MCP サーバーのステータス。[`McpStatusResponse`](#mcpstatusresponse) に含まれます。

1318 1320

1319```python theme={null}1321```python theme={null}

1320class McpServerStatus(TypedDict):1322class McpServerStatus(TypedDict):

1328```1330```

1329 1331

1330| フィールド | 型 | 説明 |1332| フィールド | 型 | 説明 |

1331| :----------- | :---------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------- |1333| :----------- | :------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------ |

1332| `name` | `str` | サーバー名 |1334| `name` | `str` | サーバー名 |

1333| `status` | `str` | `"connected"`、`"failed"`、`"needs-auth"`、`"pending"`、または `"disabled"` のいずれか |1335| `status` | `str` | `"connected"`、`"failed"`、`"needs-auth"`、`"pending"`、または `"disabled"` のいずれか |

1334| `serverInfo` | `dict`（オプション） | サーバー名とバージョン（`{"name": str, "version": str}`） |1336| `serverInfo` | `dict`（オプション） | サーバー名とバージョン（`{"name": str, "version": str}`） |

1336| `config` | [`McpServerStatusConfig`](#mcp-server-status-config)（オプション） | サーバー設定。[`McpServerConfig`](#mcp-server-config) と同じ形状（stdio、SSE、HTTP、または SDK）、および claude.ai を通じて接続されたサーバー用の `claudeai-proxy` バリアント |1338| `config` | [`McpServerStatusConfig`](#mcpserverstatusconfig)（オプション） | サーバー設定。[`McpServerConfig`](#mcpserverconfig) と同じ形状（stdio、SSE、HTTP、または SDK）、および claude.ai を通じて接続されたサーバー用の `claudeai-proxy` バリアント |

1339 1341

1416```1418```

1417 1419

1418| フィールド | 型 | 説明 |1420| フィールド | 型 | 説明 |

1419| :------------------- | :------------------------------------------------------------- | :--------------------------------------------------------------- |1421| :------------------- | :----------------------------------------------------------- | :-------------------------------------------------------------- |

1421| `model` | `str` | 応答を生成したモデル |1423| `model` | `str` | 応答を生成したモデル |

1426 1428

1427### `AssistantMessageError`1429### `AssistantMessageError`

1481| `cache_creation_input_tokens` | `int` | 新しいキャッシュエントリを作成するために使用されたトークン。 |1483| `cache_creation_input_tokens` | `int` | 新しいキャッシュエントリを作成するために使用されたトークン。 |

1482| `cache_read_input_tokens` | `int` | 既存のキャッシュエントリから読み取られたトークン。 |1484| `cache_read_input_tokens` | `int` | 既存のキャッシュエントリから読み取られたトークン。 |

1483 1485

1484`model_usage` dict はモデル名をモデルごとの使用状況にマップします。内部 dict キーは camelCase を使用します。これは、基になる CLI プロセスから変更されずに渡される値であり、TypeScript [`ModelUsage`](/ja/agent-sdk/typescript#model-usage) 型と一致するためです：1486`model_usage` dict はモデル名をモデルごとの使用状況にマップします。内部 dict キーは camelCase を使用します。これは、基になる CLI プロセスから変更されずに渡される値であり、TypeScript [`ModelUsage`](/ja/agent-sdk/typescript#modelusage) 型と一致するためです：

1485 1487

1486| キー | 型 | 説明 |1488| キー | 型 | 説明 |

1487| -------------------------- | ------- | --------------------------------------------------------------------------------------------- |1489| -------------------------- | ------- | --------------------------------------------------------------------------------------------- |

1527```1529```

1528 1530

1529| フィールド | 型 | 説明 |1531| フィールド | 型 | 説明 |

1530| :---------------- | :---------------------------------- | :--------- |1532| :---------------- | :-------------------------------- | :--------- |

1532| `uuid` | `str` | 一意のイベント識別子 |1534| `uuid` | `str` | 一意のイベント識別子 |

1533| `session_id` | `str` | セッション識別子 |1535| `session_id` | `str` | セッション識別子 |

1534 1536

1535### `RateLimitInfo`1537### `RateLimitInfo`

1536 1538

1537[`RateLimitEvent`](#rate-limit-event) によって運ばれるレート制限状態。1539[`RateLimitEvent`](#ratelimitevent) によって運ばれるレート制限状態。

1538 1540

1539```python theme={null}1541```python theme={null}

1540RateLimitStatus = Literal["allowed", "allowed_warning", "rejected"]1542RateLimitStatus = Literal["allowed", "allowed_warning", "rejected"]

1812 1814

1813パラメータ：1815パラメータ：

1814 1816

1815* `input`：`hook_event_name` に基づいた判別 Union を持つ強く型付けされた hook 入力（[`HookInput`](#hook-input) を参照）1817* `input`：`hook_event_name` に基づいた判別 Union を持つ強く型付けされた hook 入力（[`HookInput`](#hookinput) を参照）

1816* `tool_use_id`：オプションのツール使用識別子（ツール関連の hook 用）1818* `tool_use_id`：オプションのツール使用識別子（ツール関連の hook 用）

1817* `context`：追加情報を含む hook コンテキスト1819* `context`：追加情報を含む hook コンテキスト

1818 1820

1819以下を含む可能性のある [`HookJSONOutput`](#hook-json-output) を返します：1821以下を含む可能性のある [`HookJSONOutput`](#hookjsonoutput) を返します：

1820 1822

1821* `decision`：アクションをブロックするには `"block"`1823* `decision`：アクションをブロックするには `"block"`

1822* `systemMessage`：トランスクリプトに追加するシステムメッセージ1824* `systemMessage`：トランスクリプトに追加するシステムメッセージ

3110```3112```

3111 3113

3112| プロパティ | 型 | デフォルト | 説明 |3114| プロパティ | 型 | デフォルト | 説明 |

3113| :-------------------------- | :------------------------------------------------------ | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |3115| :-------------------------- | :---------------------------------------------------- | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

3117| `allowUnsandboxedCommands` | `bool` | `True` | モデルがサンドボックスの外でコマンドを実行するようにリクエストすることを許可します。`True` の場合、モデルはツール入力で `dangerouslyDisableSandbox` を設定でき、[パーミッションシステム](#permissions-fallback-for-unsandboxed-commands) にフォールバックします |3119| `allowUnsandboxedCommands` | `bool` | `True` | モデルがサンドボックスの外でコマンドを実行するようにリクエストすることを許可します。`True` の場合、モデルはツール入力で `dangerouslyDisableSandbox` を設定でき、[パーミッションシステム](#permissions-fallback-for-unsandboxed-commands) にフォールバックします |

3121 3123

3122#### 使用例3124#### 使用例

agent-sdk/streaming-output.md +396 −0 created

Details

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

5# リアルタイムでレスポンスをストリーミングする

7> テキストとツール呼び出しがストリーミングされるときに、Agent SDK からリアルタイムレスポンスを取得します

9デフォルトでは、Agent SDK は Claude がレスポンスの生成を完了した後に、完全な `AssistantMessage` オブジェクトを返します。テキストとツール呼び出しが生成されるときにインクリメンタルな更新を受け取るには、オプションで `include_partial_messages`（Python）または `includePartialMessages`（TypeScript）を `true` に設定して、部分的なメッセージストリーミングを有効にします。

11<Tip>

12 このページは出力ストリーミング（リアルタイムでトークンを受け取ること）について説明しています。入力モード（メッセージの送信方法）については、[エージェントにメッセージを送信する](/ja/agent-sdk/streaming-vs-single-mode)を参照してください。また、[CLI 経由で Agent SDK を使用してレスポンスをストリーミングする](/ja/headless)こともできます。

13</Tip>

15## ストリーミング出力を有効にする

17ストリーミングを有効にするには、オプションで `include_partial_messages`（Python）または `includePartialMessages`（TypeScript）を `true` に設定します。これにより、SDK は到着した生の API イベントを含む `StreamEvent` メッセージを返すようになり、通常の `AssistantMessage` と `ResultMessage` に加えて返されます。

19コードは以下の処理を実行する必要があります：

211. 各メッセージのタイプをチェックして、`StreamEvent` を他のメッセージタイプから区別する

222. `StreamEvent` の場合、`event` フィールドを抽出してそのタイプをチェックする

233. `delta.type` が `text_delta` である `content_block_delta` イベントを探す。これには実際のテキストチャンクが含まれます

25以下の例はストリーミングを有効にし、テキストチャンクが到着するときに出力します。ネストされたタイプチェックに注意してください：最初に `StreamEvent`、次に `content_block_delta`、その後 `text_delta` です：

27<CodeGroup>

28 ```python Python theme={null}

29 from claude_agent_sdk import query, ClaudeAgentOptions

30 from claude_agent_sdk.types import StreamEvent

31 import asyncio

34 async def stream_response():

35 options = ClaudeAgentOptions(

36 include_partial_messages=True,

37 allowed_tools=["Bash", "Read"],

38 )

40 async for message in query(prompt="List the files in my project", options=options):

41 if isinstance(message, StreamEvent):

42 event = message.event

43 if event.get("type") == "content_block_delta":

44 delta = event.get("delta", {})

45 if delta.get("type") == "text_delta":

46 print(delta.get("text", ""), end="", flush=True)

49 asyncio.run(stream_response())

50 ```

52 ```typescript TypeScript theme={null}

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

55 for await (const message of query({

56 prompt: "List the files in my project",

57 options: {

58 includePartialMessages: true,

59 allowedTools: ["Bash", "Read"]

60 }

61 })) {

62 if (message.type === "stream_event") {

63 const event = message.event;

64 if (event.type === "content_block_delta") {

65 if (event.delta.type === "text_delta") {

66 process.stdout.write(event.delta.text);

67 }

68 }

69 }

70 }

71 ```

72</CodeGroup>

74## StreamEvent リファレンス

76部分的なメッセージが有効な場合、生の Claude API ストリーミングイベントがオブジェクトでラップされて返されます。タイプは各 SDK で異なる名前を持ちます：

78* **Python**: `StreamEvent`（`claude_agent_sdk.types` からインポート）

79* **TypeScript**: `SDKPartialAssistantMessage` with `type: 'stream_event'`

81どちらも生の Claude API イベントを含み、蓄積されたテキストではありません。テキストデルタを自分で抽出して蓄積する必要があります。各タイプの構造は以下の通りです：

83<CodeGroup>

84 ```python Python theme={null}

85 @dataclass

86 class StreamEvent:

87 uuid: str # このイベントの一意の識別子

88 session_id: str # セッション識別子

89 event: dict[str, Any] # 生の Claude API ストリームイベント

90 parent_tool_use_id: str | None # サブエージェントからの場合は親ツール ID

91 ```

93 ```typescript TypeScript theme={null}

94 type SDKPartialAssistantMessage = {

95 type: "stream_event";

96 event: BetaRawMessageStreamEvent; // Anthropic SDK から

97 parent_tool_use_id: string | null;

98 uuid: UUID;

99 session_id: string;

100 };

101 ```

102</CodeGroup>

103

104`event` フィールドには、[Claude API](https://platform.claude.com/docs/en/build-with-claude/streaming#event-types) からの生のストリーミングイベントが含まれます。一般的なイベントタイプは以下の通りです：

105

106| イベントタイプ | 説明 |

107| :-------------------- | :---------------------------- |

108| `message_start` | 新しいメッセージの開始 |

109| `content_block_start` | 新しいコンテンツブロック（テキストまたはツール使用）の開始 |

110| `content_block_delta` | コンテンツへのインクリメンタルな更新 |

111| `content_block_stop` | コンテンツブロックの終了 |

112| `message_delta` | メッセージレベルの更新（停止理由、使用量） |

113| `message_stop` | メッセージの終了 |

114

115## メッセージフロー

116

117部分的なメッセージが有効な場合、メッセージは以下の順序で返されます：

118

119```text theme={null}

120StreamEvent (message_start)

121StreamEvent (content_block_start) - テキストブロック

122StreamEvent (content_block_delta) - テキストチャンク...

123StreamEvent (content_block_stop)

124StreamEvent (content_block_start) - tool_use ブロック

125StreamEvent (content_block_delta) - ツール入力チャンク...

126StreamEvent (content_block_stop)

127StreamEvent (message_delta)

128StreamEvent (message_stop)

129AssistantMessage - すべてのコンテンツを含む完全なメッセージ

130... ツール実行 ...

131... 次のターンのストリーミングイベント ...

132ResultMessage - 最終結果

133```

134

135部分的なメッセージが有効でない場合（Python では `include_partial_messages`、TypeScript では `includePartialMessages`）、`StreamEvent` を除くすべてのメッセージタイプを受け取ります。一般的なタイプには `SystemMessage`（セッション初期化）、`AssistantMessage`（完全なレスポンス）、`ResultMessage`（最終結果）、および会話履歴がコンパクト化されたときを示すコンパクト境界メッセージ（TypeScript では `SDKCompactBoundaryMessage`、Python では `SystemMessage` with subtype `"compact_boundary"`）が含まれます。

136

137## テキストレスポンスをストリーミングする

138

139生成されるときにテキストを表示するには、`delta.type` が `text_delta` である `content_block_delta` イベントを探します。これらには、インクリメンタルなテキストチャンクが含まれます。以下の例は、各チャンクが到着するときに出力します：

140

141<CodeGroup>

142 ```python Python theme={null}

143 from claude_agent_sdk import query, ClaudeAgentOptions

144 from claude_agent_sdk.types import StreamEvent

145 import asyncio

146

147

148 async def stream_text():

149 options = ClaudeAgentOptions(include_partial_messages=True)

150

151 async for message in query(prompt="Explain how databases work", options=options):

152 if isinstance(message, StreamEvent):

153 event = message.event

154 if event.get("type") == "content_block_delta":

155 delta = event.get("delta", {})

156 if delta.get("type") == "text_delta":

157 # 各テキストチャンクが到着するときに出力

158 print(delta.get("text", ""), end="", flush=True)

159

160 print() # 最後の改行

161

162

163 asyncio.run(stream_text())

164 ```

165

166 ```typescript TypeScript theme={null}

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

168

169 for await (const message of query({

170 prompt: "Explain how databases work",

171 options: { includePartialMessages: true }

172 })) {

173 if (message.type === "stream_event") {

174 const event = message.event;

175 if (event.type === "content_block_delta" && event.delta.type === "text_delta") {

176 process.stdout.write(event.delta.text);

177 }

178 }

179 }

180

181 console.log(); // 最後の改行

182 ```

183</CodeGroup>

184

185## ツール呼び出しをストリーミングする

186

187ツール呼び出しもインクリメンタルにストリーミングされます。ツールが開始されるときを追跡し、生成されるときに入力を受け取り、完了するときを確認できます。以下の例は、現在呼び出されているツールを追跡し、ストリーミングされるときに JSON 入力を蓄積します。3 つのイベントタイプを使用します：

188

189* `content_block_start`: ツール開始

190* `content_block_delta` with `input_json_delta`: 入力チャンク到着

191* `content_block_stop`: ツール呼び出し完了

192

193<CodeGroup>

194 ```python Python theme={null}

195 from claude_agent_sdk import query, ClaudeAgentOptions

196 from claude_agent_sdk.types import StreamEvent

197 import asyncio

198

199

200 async def stream_tool_calls():

201 options = ClaudeAgentOptions(

202 include_partial_messages=True,

203 allowed_tools=["Read", "Bash"],

204 )

205

206 # 現在のツールを追跡し、その入力 JSON を蓄積

207 current_tool = None

208 tool_input = ""

209

210 async for message in query(prompt="Read the README.md file", options=options):

211 if isinstance(message, StreamEvent):

212 event = message.event

213 event_type = event.get("type")

214

215 if event_type == "content_block_start":

216 # 新しいツール呼び出しが開始

217 content_block = event.get("content_block", {})

218 if content_block.get("type") == "tool_use":

219 current_tool = content_block.get("name")

220 tool_input = ""

221 print(f"Starting tool: {current_tool}")

222

223 elif event_type == "content_block_delta":

224 delta = event.get("delta", {})

225 if delta.get("type") == "input_json_delta":

226 # ストリーミングされるときに JSON 入力を蓄積

227 chunk = delta.get("partial_json", "")

228 tool_input += chunk

229 print(f" Input chunk: {chunk}")

230

231 elif event_type == "content_block_stop":

232 # ツール呼び出し完了 - 最終入力を表示

233 if current_tool:

234 print(f"Tool {current_tool} called with: {tool_input}")

235 current_tool = None

236

237

238 asyncio.run(stream_tool_calls())

239 ```

240

241 ```typescript TypeScript theme={null}

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

243

244 // 現在のツールを追跡し、その入力 JSON を蓄積

245 let currentTool: string | null = null;

246 let toolInput = "";

247

248 for await (const message of query({

249 prompt: "Read the README.md file",

250 options: {

251 includePartialMessages: true,

252 allowedTools: ["Read", "Bash"]

253 }

254 })) {

255 if (message.type === "stream_event") {

256 const event = message.event;

257

258 if (event.type === "content_block_start") {

259 // 新しいツール呼び出しが開始

260 if (event.content_block.type === "tool_use") {

261 currentTool = event.content_block.name;

262 toolInput = "";

263 console.log(`Starting tool: ${currentTool}`);

264 }

265 } else if (event.type === "content_block_delta") {

266 if (event.delta.type === "input_json_delta") {

267 // ストリーミングされるときに JSON 入力を蓄積

268 const chunk = event.delta.partial_json;

269 toolInput += chunk;

270 console.log(` Input chunk: ${chunk}`);

271 }

272 } else if (event.type === "content_block_stop") {

273 // ツール呼び出し完了 - 最終入力を表示

274 if (currentTool) {

275 console.log(`Tool ${currentTool} called with: ${toolInput}`);

276 currentTool = null;

277 }

278 }

279 }

280 }

281 ```

282</CodeGroup>

283

284## ストリーミング UI を構築する

285

286この例は、テキストとツールストリーミングを統合された UI に組み合わせます。エージェントが現在ツールを実行しているかどうかを追跡します（`in_tool` フラグを使用）。ツールの実行中に `[Using Read...]` のようなステータスインジケータを表示します。ツールが実行されていないときはテキストが通常にストリーミングされ、ツール完了は「完了」メッセージをトリガーします。このパターンは、マルチステップエージェントタスク中に進捗を表示する必要があるチャットインターフェースに役立ちます。

287

288<CodeGroup>

289 ```python Python theme={null}

290 from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

291 from claude_agent_sdk.types import StreamEvent

292 import asyncio

293 import sys

294

295

296 async def streaming_ui():

297 options = ClaudeAgentOptions(

298 include_partial_messages=True,

299 allowed_tools=["Read", "Bash", "Grep"],

300 )

301

302 # 現在ツール呼び出し中かどうかを追跡

303 in_tool = False

304

305 async for message in query(

306 prompt="Find all TODO comments in the codebase", options=options

307 ):

308 if isinstance(message, StreamEvent):

309 event = message.event

310 event_type = event.get("type")

311

312 if event_type == "content_block_start":

313 content_block = event.get("content_block", {})

314 if content_block.get("type") == "tool_use":

315 # ツール呼び出しが開始 - ステータスインジケータを表示

316 tool_name = content_block.get("name")

317 print(f"\n[Using {tool_name}...]", end="", flush=True)

318 in_tool = True

319

320 elif event_type == "content_block_delta":

321 delta = event.get("delta", {})

322 # ツール実行中でないときのみテキストをストリーミング

323 if delta.get("type") == "text_delta" and not in_tool:

324 sys.stdout.write(delta.get("text", ""))

325 sys.stdout.flush()

326

327 elif event_type == "content_block_stop":

328 if in_tool:

329 # ツール呼び出し完了

330 print(" done", flush=True)

331 in_tool = False

332

333 elif isinstance(message, ResultMessage):

334 # エージェントがすべての作業を完了

335 print(f"\n\n--- Complete ---")

336

337

338 asyncio.run(streaming_ui())

339 ```

340

341 ```typescript TypeScript theme={null}

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

343

344 // 現在ツール呼び出し中かどうかを追跡

345 let inTool = false;

346

347 for await (const message of query({

348 prompt: "Find all TODO comments in the codebase",

349 options: {

350 includePartialMessages: true,

351 allowedTools: ["Read", "Bash", "Grep"]

352 }

353 })) {

354 if (message.type === "stream_event") {

355 const event = message.event;

356

357 if (event.type === "content_block_start") {

358 if (event.content_block.type === "tool_use") {

359 // ツール呼び出しが開始 - ステータスインジケータを表示

360 process.stdout.write(`\n[Using ${event.content_block.name}...]`);

361 inTool = true;

362 }

363 } else if (event.type === "content_block_delta") {

364 // ツール実行中でないときのみテキストをストリーミング

365 if (event.delta.type === "text_delta" && !inTool) {

366 process.stdout.write(event.delta.text);

367 }

368 } else if (event.type === "content_block_stop") {

369 if (inTool) {

370 // ツール呼び出し完了

371 console.log(" done");

372 inTool = false;

373 }

374 }

375 } else if (message.type === "result") {

376 // エージェントがすべての作業を完了

377 console.log("\n\n--- Complete ---");

378 }

379 }

380 ```

381</CodeGroup>

382

383## 既知の制限事項

384

385一部の SDK 機能はストリーミングと互換性がありません：

386

387* **拡張思考**: `max_thinking_tokens`（Python）または `maxThinkingTokens`（TypeScript）を明示的に設定すると、`StreamEvent` メッセージは発行されません。各ターンの後に完全なメッセージのみを受け取ります。思考は SDK ではデフォルトで無効になっているため、有効にしない限りストリーミングは機能します。

388* **構造化出力**: JSON 結果は最終的な `ResultMessage.structured_output` にのみ表示され、ストリーミングデルタとしては表示されません。詳細は[構造化出力](/ja/agent-sdk/structured-outputs)を参照してください。

389

390## 次のステップ

391

392テキストとツール呼び出しをリアルタイムでストリーミングできるようになったので、これらの関連トピックを探索してください：

393

394* [インタラクティブ対ワンショットクエリ](/ja/agent-sdk/streaming-vs-single-mode): ユースケースに応じて入力モードを選択する

395* [構造化出力](/ja/agent-sdk/structured-outputs): エージェントから型付き JSON レスポンスを取得する

396* [権限](/ja/agent-sdk/permissions): エージェントが使用できるツールを制御する

agent-sdk/todo-tracking.md +189 −0 created

Details

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

5# Todo リスト

7> Claude Agent SDK を使用して todo を追跡・表示し、タスク管理を整理します

9Todo 追跡は、タスクを管理し、ユーザーに進捗を表示するための構造化された方法を提供します。Claude Agent SDK には、複雑なワークフローを整理し、ユーザーにタスク進捗を知らせるのに役立つ組み込み todo 機能が含まれています。

11### Todo ライフサイクル

13Todo は予測可能なライフサイクルに従います：

151. **作成** - タスクが識別されたときに `pending` として作成される

162. **アクティベート** - 作業が開始されたときに `in_progress` に変更される

173. **完了** - タスクが正常に完了したときに完了する

184. **削除** - グループ内のすべてのタスクが完了したときに削除される

20### Todo が使用される場合

22SDK は以下の場合に自動的に todo を作成します：

24* **複雑なマルチステップタスク** - 3 つ以上の異なるアクションが必要な場合

25* **ユーザー提供のタスクリスト** - 複数のアイテムが言及されている場合

26* **非自明な操作** - 進捗追跡の恩恵を受ける場合

27* **明示的なリクエスト** - ユーザーが todo 整理を要求した場合

29## 例

31### Todo 変更の監視

33<CodeGroup>

34 ```typescript TypeScript theme={null}

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

37 for await (const message of query({

38 prompt: "Optimize my React app performance and track progress with todos",

39 options: { maxTurns: 15 }

40 })) {

41 // Todo updates are reflected in the message stream

42 if (message.type === "assistant") {

43 for (const block of message.message.content) {

44 if (block.type === "tool_use" && block.name === "TodoWrite") {

45 const todos = block.input.todos;

47 console.log("Todo Status Update:");

48 todos.forEach((todo, index) => {

49 const status =

50 todo.status === "completed" ? "✅" : todo.status === "in_progress" ? "🔧" : "❌";

51 console.log(`${index + 1}. ${status} ${todo.content}`);

52 });

53 }

54 }

55 }

56 }

57 ```

59 ```python Python theme={null}

60 from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ToolUseBlock

62 async for message in query(

63 prompt="Optimize my React app performance and track progress with todos",

64 options=ClaudeAgentOptions(max_turns=15),

65 ):

66 # Todo updates are reflected in the message stream

67 if isinstance(message, AssistantMessage):

68 for block in message.content:

69 if isinstance(block, ToolUseBlock) and block.name == "TodoWrite":

70 todos = block.input["todos"]

72 print("Todo Status Update:")

73 for i, todo in enumerate(todos):

74 status = (

75 "✅"

76 if todo["status"] == "completed"

77 else "🔧"

78 if todo["status"] == "in_progress"

79 else "❌"

80 )

81 print(f"{i + 1}. {status} {todo['content']}")

82 ```

83</CodeGroup>

85### リアルタイム進捗表示

87<CodeGroup>

88 ```typescript TypeScript theme={null}

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

91 class TodoTracker {

92 private todos: any[] = [];

94 displayProgress() {

95 if (this.todos.length === 0) return;

97 const completed = this.todos.filter((t) => t.status === "completed").length;

98 const inProgress = this.todos.filter((t) => t.status === "in_progress").length;

99 const total = this.todos.length;

100

101 console.log(`\nProgress: ${completed}/${total} completed`);

102 console.log(`Currently working on: ${inProgress} task(s)\n`);

103

104 this.todos.forEach((todo, index) => {

105 const icon =

106 todo.status === "completed" ? "✅" : todo.status === "in_progress" ? "🔧" : "❌";

107 const text = todo.status === "in_progress" ? todo.activeForm : todo.content;

108 console.log(`${index + 1}. ${icon} ${text}`);

109 });

110 }

111

112 async trackQuery(prompt: string) {

113 for await (const message of query({

114 prompt,

115 options: { maxTurns: 20 }

116 })) {

117 if (message.type === "assistant") {

118 for (const block of message.message.content) {

119 if (block.type === "tool_use" && block.name === "TodoWrite") {

120 this.todos = block.input.todos;

121 this.displayProgress();

122 }

123 }

124 }

125 }

126 }

127 }

128

129 // Usage

130 const tracker = new TodoTracker();

131 await tracker.trackQuery("Build a complete authentication system with todos");

132 ```

133

134 ```python Python theme={null}

135 from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ToolUseBlock

136 from typing import List, Dict

137

138

139 class TodoTracker:

140 def __init__(self):

141 self.todos: List[Dict] = []

142

143 def display_progress(self):

144 if not self.todos:

145 return

146

147 completed = len([t for t in self.todos if t["status"] == "completed"])

148 in_progress = len([t for t in self.todos if t["status"] == "in_progress"])

149 total = len(self.todos)

150

151 print(f"\nProgress: {completed}/{total} completed")

152 print(f"Currently working on: {in_progress} task(s)\n")

153

154 for i, todo in enumerate(self.todos):

155 icon = (

156 "✅"

157 if todo["status"] == "completed"

158 else "🔧"

159 if todo["status"] == "in_progress"

160 else "❌"

161 )

162 text = (

163 todo["activeForm"]

164 if todo["status"] == "in_progress"

165 else todo["content"]

166 )

167 print(f"{i + 1}. {icon} {text}")

168

169 async def track_query(self, prompt: str):

170 async for message in query(prompt=prompt, options=ClaudeAgentOptions(max_turns=20)):

171 if isinstance(message, AssistantMessage):

172 for block in message.content:

173 if isinstance(block, ToolUseBlock) and block.name == "TodoWrite":

174 self.todos = block.input["todos"]

175 self.display_progress()

176

177

178 # Usage

179 tracker = TodoTracker()

180 await tracker.track_query("Build a complete authentication system with todos")

181 ```

182</CodeGroup>

183

184## 関連ドキュメント

185

186* [TypeScript SDK リファレンス](/ja/agent-sdk/typescript)

187* [Python SDK リファレンス](/ja/agent-sdk/python)

188* [ストリーミング vs シングルモード](/ja/agent-sdk/streaming-vs-single-mode)

189* [カスタムツール](/ja/agent-sdk/custom-tools)

agent-sdk/typescript.md +32 −32

Details

41#### パラメータ41#### パラメータ

42 42

43| パラメータ | 型 | 説明 |43| パラメータ | 型 | 説明 |

~~44| :-------- | :---------------------------------------------------------------- | :----------------------------------------- |~~44| :-------- | :--------------------------------------------------------------- | :----------------------------------------- |

47 47

48#### 戻り値48#### 戻り値

49 49

~~50[`Query`](#query-object) オブジェクトを返します。これは `AsyncGenerator<`[`SDKMessage`](#sdk-message)`, void>` を拡張し、追加のメソッドを持ちます。~~50[`Query`](#query-object) オブジェクトを返します。これは `AsyncGenerator<`[`SDKMessage`](#sdkmessage)`, void>` を拡張し、追加のメソッドを持ちます。

51 51

52### `startup()`52### `startup()`

53 53

54プロンプトが利用可能になる前に、CLI サブプロセスをスポーンして初期化ハンドシェイクを完了することで、プリウォーミングします。返された [`WarmQuery`](#warm-query) ハンドルは後でプロンプトを受け入れ、既に準備ができているプロセスに書き込むため、最初の `query()` 呼び出しはサブプロセスのスポーンと初期化コストをインラインで支払うことなく解決します。54プロンプトが利用可能になる前に、CLI サブプロセスをスポーンして初期化ハンドシェイクを完了することで、プリウォーミングします。返された [`WarmQuery`](#warmquery) ハンドルは後でプロンプトを受け入れ、既に準備ができているプロセスに書き込むため、最初の `query()` 呼び出しはサブプロセスのスポーンと初期化コストをインラインで支払うことなく解決します。

55 55

56```typescript theme={null}56```typescript theme={null}

57function startup(params?: {57function startup(params?: {

69 69

70#### 戻り値70#### 戻り値

71 71

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

73 73

74#### 例74#### 例

75 75

104#### パラメータ104#### パラメータ

105 105

106| パラメータ | 型 | 説明 |106| パラメータ | 型 | 説明 |

107| :------------ | :------------------------------------------------------------------ | :------------------------------------------------ |107| :------------ | :---------------------------------------------------------------- | :------------------------------------------------ |

112| `extras` | `{ annotations?: `[`ToolAnnotations`](#tool-annotations)` }` | クライアントに動作ヒントを提供するオプションの MCP ツール注釈 |112| `extras` | `{ annotations?: `[`ToolAnnotations`](#toolannotations)` }` | クライアントに動作ヒントを提供するオプションの MCP ツール注釈 |

113 113

114#### `ToolAnnotations`114#### `ToolAnnotations`

115 115

177#### 戻り値の型：`SDKSessionInfo`177#### 戻り値の型：`SDKSessionInfo`

178 178

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

180| :------------- | :-------------------- | :--------------------------------------------------- |180| :------------- | :-------------------- | :-------------------------------------------------- |

191 191

192#### 例192#### 例

272 272

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

274 274

275### `renameSession()`275### `renameSession()`

276 276

328| `allowedTools` | `string[]` | `[]` | プロンプトなしで自動承認するツール。これは Claude をこれらのツールのみに制限しません。リストされていないツールは `permissionMode` と `canUseTool` にフォールスルーします。ツールをブロックするには `disallowedTools` を使用します。[パーミッション](/ja/agent-sdk/permissions#allow-and-deny-rules) を参照してください |328| `allowedTools` | `string[]` | `[]` | プロンプトなしで自動承認するツール。これは Claude をこれらのツールのみに制限しません。リストされていないツールは `permissionMode` と `canUseTool` にフォールスルーします。ツールをブロックするには `disallowedTools` を使用します。[パーミッション](/ja/agent-sdk/permissions#allow-and-deny-rules) を参照してください |

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

344| `hooks` | `Partial<Record<`[`HookEvent`](#hook-event)`, `[`HookCallbackMatcher`](#hook-callback-matcher)`[]>>` | `{}` | イベントのフックコールバック |344| `hooks` | `Partial<Record<`[`HookEvent`](#hookevent)`, `[`HookCallbackMatcher`](#hookcallbackmatcher)`[]>>` | `{}` | イベントのフックコールバック |

349| `mcpServers` | `Record<string, [`McpServerConfig`](#mcp-server-config)>` | `{}` | MCP サーバー設定 |349| `mcpServers` | `Record<string, [`McpServerConfig`](#mcpserverconfig)>` | `{}` | MCP サーバー設定 |

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

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

363| `settingSources` | [`SettingSource`](#setting-source)`[]` | CLI デフォルト（すべてのソース） | ロードするファイルシステム設定を制御します。ユーザー、プロジェクト、ローカル設定を無効にするには `[]` を渡します。管理ポリシー設定は関係なくロードされます。[Claude Code 機能を使用](/ja/agent-sdk/claude-code-features#what-settingsources-does-not-control) を参照してください |363| `settingSources` | [`SettingSource`](#settingsource)`[]` | CLI デフォルト（すべてのソース） | ロードするファイルシステム設定を制御します。ユーザー、プロジェクト、ローカル設定を無効にするには `[]` を渡します。管理ポリシー設定は関係なくロードされます。[Claude Code 機能を使用](/ja/agent-sdk/claude-code-features#what-settingsources-does-not-control) を参照してください |

367| `systemPrompt` | `string \| { type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean }` | `undefined`（最小限のプロンプト） | システムプロンプト設定。カスタムプロンプト用の文字列を渡すか、Claude Code のシステムプロンプトを使用するには `{ type: 'preset', preset: 'claude_code' }` を渡します。プリセットオブジェクト形式を使用する場合、追加の指示で拡張するには `append` を追加し、[マシン全体でプロンプトキャッシュの再利用を改善](/ja/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) するためにセッションごとのコンテキストを最初のユーザーメッセージに移動するには `excludeDynamicSections: true` を設定します |367| `systemPrompt` | `string \| { type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean }` | `undefined`（最小限のプロンプト） | システムプロンプト設定。カスタムプロンプト用の文字列を渡すか、Claude Code のシステムプロンプトを使用するには `{ type: 'preset', preset: 'claude_code' }` を渡します。プリセットオブジェクト形式を使用する場合、追加の指示で拡張するには `append` を追加し、[マシン全体でプロンプトキャッシュの再利用を改善](/ja/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) するためにセッションごとのコンテキストを最初のユーザーメッセージに移動するには `excludeDynamicSections: true` を設定します |

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

370| `tools` | `string[] \| { type: 'preset'; preset: 'claude_code' }` | `undefined` | ツール設定。ツール名の配列を渡すか、Claude Code のデフォルトツールを取得するにはプリセットを使用します |370| `tools` | `string[] \| { type: 'preset'; preset: 'claude_code' }` | `undefined` | ツール設定。ツール名の配列を渡すか、Claude Code のデフォルトツールを取得するにはプリセットを使用します |

371 371

372### `Query` オブジェクト372### `Query` オブジェクト

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

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

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

496| `permissionMode` | いいえ | このエージェント内のツール実行のパーミッションモード。[`PermissionMode`](#permission-mode) を参照してください |496| `permissionMode` | いいえ | このエージェント内のツール実行のパーミッションモード。[`PermissionMode`](#permissionmode) を参照してください |

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

498 498

499### `AgentMcpServerSpec`499### `AgentMcpServerSpec`

626 | "default" // 標準的なパーミッション動作626 | "default" // 標準的なパーミッション動作

627 | "acceptEdits" // ファイル編集を自動承認627 | "acceptEdits" // ファイル編集を自動承認

628 | "bypassPermissions" // すべてのパーミッションチェックをバイパス628 | "bypassPermissions" // すべてのパーミッションチェックをバイパス

629 | "plan" // 計画モード - 実行なし629 | "plan" // 計画モード - 読み取り専用ツールのみ

630 | "dontAsk" // パーミッションをプロンプトしない、事前承認されていない場合は拒否630 | "dontAsk" // パーミッションをプロンプトしない、事前承認されていない場合は拒否

631 | "auto"; // モデル分類器を使用して各ツール呼び出しを承認または拒否631 | "auto"; // モデル分類器を使用して各ツール呼び出しを承認または拒否

632```632```

651```651```

652 652

653| オプション | 型 | 説明 |653| オプション | 型 | 説明 |

654| :--------------- | :------------------------------------------- | :--------------------------------------------- |654| :--------------- | :------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

656| `suggestions` | [`PermissionUpdate`](#permission-update)`[]` | 提案されたパーミッション更新。ユーザーがこのツールに対して再度プロンプトされないようにします |656| `suggestions` | [`PermissionUpdate`](#permissionupdate)`[]` | 提案されたパーミッション更新。ユーザーがこのツールに対して再度プロンプトされないようにします。Bash プロンプトには `localSettings` [宛先](#permissionupdatedestination) を含む提案が含まれているため、`updatedPermissions` で返すと、ルールを `.claude/settings.local.json` に書き込み、セッション全体で永続化します。 |

2379 | McpClaudeAIProxyServerConfig;2379 | McpClaudeAIProxyServerConfig;

2380```2380```

2381 2381

2382各トランスポートタイプの詳細については、[`McpServerConfig`](#mcp-server-config) を参照してください。2382各トランスポートタイプの詳細については、[`McpServerConfig`](#mcpserverconfig) を参照してください。

2383 2383

2384### `AccountInfo`2384### `AccountInfo`

2385 2385

2825```2825```

2826 2826

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

2828| :-------------------------- | :------------------------------------------------------ | :---------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |2828| :-------------------------- | :---------------------------------------------------- | :---------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

2832| `allowUnsandboxedCommands` | `boolean` | `true` | モデルがサンドボックス外でコマンドを実行するようにリクエストすることを許可します。`true` の場合、モデルはツール入力で `dangerouslyDisableSandbox` を設定でき、[パーミッションシステム](#permissions-fallback-for-unsandboxed-commands) にフォールバックします |2832| `allowUnsandboxedCommands` | `boolean` | `true` | モデルがサンドボックス外でコマンドを実行するようにリクエストすることを許可します。`true` の場合、モデルはツール入力で `dangerouslyDisableSandbox` を設定でき、[パーミッションシステム](#permissions-fallback-for-unsandboxed-commands) にフォールバックします |

2835| `ignoreViolations` | `Record<string, string[]>` | `undefined` | 違反カテゴリを無視するパターンのマップ（例：`{ file: ['/tmp/*'], network: ['localhost'] }`） |2835| `ignoreViolations` | `Record<string, string[]>` | `undefined` | 違反カテゴリを無視するパターンのマップ（例：`{ file: ['/tmp/*'], network: ['localhost'] }`） |

2837| `ripgrep` | `{ command: string; args?: string[] }` | `undefined` | サンドボックス環境のカスタム ripgrep バイナリ設定 |2837| `ripgrep` | `{ command: string; args?: string[] }` | `undefined` | サンドボックス環境のカスタム ripgrep バイナリ設定 |

data-usage.md +1 −1

Details

67 67

68以下の図は、インストール中および通常の操作中に Claude Code が外部サービスにどのように接続するかを示しています。実線は必須の接続を示し、破線はオプションまたはユーザーが開始したデータフローを表します。68以下の図は、インストール中および通常の操作中に Claude Code が外部サービスにどのように接続するかを示しています。実線は必須の接続を示し、破線はオプションまたはユーザーが開始したデータフローを表します。

69 69

70<img src="https://mintcdn.com/claude-code/YcBW2H7CArGcduPb/images/claude-code-data-flow.svg?fit=max&auto=format&n=YcBW2H7CArGcduPb&q=85&s=b600a89f84fc86f9ff7be00a466c0635" alt="Claude Code の外部接続を示す図：インストール/更新は配布サーバーに接続し、ユーザーリクエストは Console 認証、public-api、およびオプションで Statsig、Sentry、バグレポートを含む Anthropic サービスに接続します" width="720" height="520" data-path="images/claude-code-data-flow.svg" />70<img src="https://mintcdn.com/claude-code/RcOyXc06Ja8cuvMZ/images/claude-code-data-flow.svg?fit=max&auto=format&n=RcOyXc06Ja8cuvMZ&q=85&s=b5be40abf333defe984993af89546c19" alt="Claude Code の外部接続を示す図：インストール/更新は配布サーバーに接続し、ユーザーリクエストは Console 認証、public-api、およびオプションで Statsig、Sentry、バグレポートを含む Anthropic サービスに接続します" width="720" height="520" data-path="images/claude-code-data-flow.svg" />

71 71

72Claude Code はローカルで実行されます。LLM と対話するために、Claude Code はネットワーク経由でデータを送信します。このデータには、すべてのユーザープロンプトとモデル出力が含まれます。データは TLS 1.2 以上で転送中に暗号化されます。Claude Code はほとんどの一般的な VPN および LLM プロキシと互換性があります。72Claude Code はローカルで実行されます。LLM と対話するために、Claude Code はネットワーク経由でデータを送信します。このデータには、すべてのユーザープロンプトとモデル出力が含まれます。データは TLS 1.2 以上で転送中に暗号化されます。Claude Code はほとんどの一般的な VPN および LLM プロキシと互換性があります。

73 73

desktop.md +5 −3

Details

282 282

283### セッションで並列に作業する283### セッションで並列に作業する

284 284

285サイドバーの\*\*+ New session**をクリックするか、macOS で**Cmd+N**を、Windows で**Ctrl+N**を押して、複数のタスクを並列で作業します。**Ctrl+Tab**と**Ctrl+Shift+Tab\*\*を押してサイドバーのセッションをサイクルします。Git リポジトリの場合、各セッションは[Git worktrees](/ja/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees)を使用してプロジェクトの独立した分離コピーを取得するため、1 つのセッションの変更は、コミットするまで他のセッションに影響しません。285サイドバーの\*\*+ New session**をクリックするか、macOS で**Cmd+N**を、Windows で**Ctrl+N**を押して、複数のタスクを並列で作業します。**Ctrl+Tab**と**Ctrl+Shift+Tab\*\*を押してサイドバーのセッションをサイクルします。Git リポジトリの場合、各セッションは[Git worktrees](/ja/worktrees)を使用してプロジェクトの独立した分離コピーを取得するため、1 つのセッションの変更は、コミットするまで他のセッションに影響しません。

286

2872 つのセッションを同時に表示するには、macOS で**Cmd**を、Windows で**Ctrl**を押しながらサイドバーのセッションをクリックします。セッションは既に開いているセッションの横の 2 番目のペインで開きます。分割がアクティブな間、別のサイドバーセッションをクリックすると、フォーカスがあるペインが置き換わります。macOS で\*\*Cmd+\\**を、Windows で**Ctrl+\\\*\*を押して、フォーカスされたペインを閉じて、単一のセッションに戻ります。

286 288

287Worktrees はデフォルトで`<project-root>/.claude/worktrees/`に保存されます。Settings → Claude Code の「Worktree location」でカスタムディレクトリに変更できます。また、すべての worktree ブランチ名の前に付加されるブランチプレフィックスを設定することもできます。これは Claude が作成したブランチを整理するのに便利です。完了したら、サイドバーのセッションにマウスを合わせてアーカイブアイコンをクリックして worktree を削除します。PR がマージまたはクローズされた後にセッションを自動的にアーカイブするには、Settings → Claude Code で**Auto-archive after PR merge or close**をオンにします。Auto-archive はローカルセッションで実行が完了したものにのみ適用されます。289Worktrees はデフォルトで`<project-root>/.claude/worktrees/`に保存されます。Settings → Claude Code の「Worktree location」でカスタムディレクトリに変更できます。また、すべての worktree ブランチ名の前に付加されるブランチプレフィックスを設定することもできます。これは Claude が作成したブランチを整理するのに便利です。完了したら、サイドバーのセッションにマウスを合わせてアーカイブアイコンをクリックして worktree を削除します。PR がマージまたはクローズされた後にセッションを自動的にアーカイブするには、Settings → Claude Code で**Auto-archive after PR merge or close**をオンにします。Auto-archive はローカルセッションで実行が完了したものにのみ適用されます。

288 290

289gitignored ファイル（`.env`など）を新しい worktrees に含めるには、プロジェクトルートに[`.worktreeinclude`ファイル](/ja/common-workflows#copy-gitignored-files-to-worktrees)を作成します。291gitignored ファイル（`.env`など）を新しい worktrees に含めるには、プロジェクトルートに[`.worktreeinclude`ファイル](/ja/worktrees#copy-gitignored-files-into-worktrees)を作成します。

290 292

291<Note>293<Note>

292 セッション分離には[Git](https://git-scm.com/downloads)が必要です。ほとんどの Mac には Git がデフォルトで含まれています。Terminal で`git --version`を実行して確認してください。Windows では、Code タブが機能するために Git が必要です：[Git for Windows をダウンロード](https://git-scm.com/downloads/win)し、インストールしてアプリを再起動します。Git エラーが発生した場合は、[Cowork タブ](https://claude.com/product/cowork)で Claude に助けを求めてセットアップのトラブルシューティングを行ってください。294 セッション分離には[Git](https://git-scm.com/downloads)が必要です。ほとんどの Mac には Git がデフォルトで含まれています。Terminal で`git --version`を実行して確認してください。Windows では、Code タブが機能するために Git が必要です：[Git for Windows をダウンロード](https://git-scm.com/downloads/win)し、インストールしてアプリを再起動します。Git エラーが発生した場合は、[Cowork タブ](https://claude.com/product/cowork)で Claude に助けを求めてセットアップのトラブルシューティングを行ってください。

516 518

517ローカルセッションと dev サーバーの環境変数を設定するには、プロンプトボックスの環境ドロップダウンを開き、**Local** にマウスを合わせて、ギアアイコンをクリックしてローカル環境エディタを開きます。ここで保存する変数は、マシンに暗号化されて保存され、開始するすべてのローカルセッションとプレビューサーバーに適用されます。また、`~/.claude/settings.json` ファイルの `env` キーに変数を追加することもできます。ただし、これらは Claude セッションにのみ到達し、dev サーバーには到達しません。サポートされている変数の完全なリストについては、[環境変数](/ja/env-vars)を参照してください。519ローカルセッションと dev サーバーの環境変数を設定するには、プロンプトボックスの環境ドロップダウンを開き、**Local** にマウスを合わせて、ギアアイコンをクリックしてローカル環境エディタを開きます。ここで保存する変数は、マシンに暗号化されて保存され、開始するすべてのローカルセッションとプレビューサーバーに適用されます。また、`~/.claude/settings.json` ファイルの `env` キーに変数を追加することもできます。ただし、これらは Claude セッションにのみ到達し、dev サーバーには到達しません。サポートされている変数の完全なリストについては、[環境変数](/ja/env-vars)を参照してください。

518 520

519[拡張思考](/ja/common-workflows#use-extended-thinking-thinking-mode)はデフォルトで有効になっており、複雑な推論タスクのパフォーマンスを向上させますが、追加のトークンを使用します。思考を完全に無効にするには、ローカル環境エディタで `MAX_THINKING_TOKENS` を `0` に設定します。[適応的推論](/ja/model-config#adjust-effort-level)を持つモデルでは、適応的推論が思考の深さを制御するため、他の `MAX_THINKING_TOKENS` 値は無視されます。Opus 4.6 と Sonnet 4.6 では、固定思考予算を使用するために `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` を `1` に設定します。Opus 4.7 は常に適応的推論を使用し、固定予算モードはありません。521[拡張思考](/ja/model-config#extended-thinking)はデフォルトで有効になっており、複雑な推論タスクのパフォーマンスを向上させますが、追加のトークンを使用します。思考を完全に無効にするには、ローカル環境エディタで `MAX_THINKING_TOKENS` を `0` に設定します。[適応的推論](/ja/model-config#adjust-effort-level)を持つモデルでは、適応的推論が思考の深さを制御するため、他の `MAX_THINKING_TOKENS` 値は無視されます。Opus 4.6 と Sonnet 4.6 では、固定思考予算を使用するために `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` を `1` に設定します。Opus 4.7 は常に適応的推論を使用し、固定予算モードはありません。

520 522

521### リモートセッション523### リモートセッション

522 524

features-overview.md +53 −16

Details

12 コア agentic ループがどのように機能するかについては、[How Claude Code works](/ja/how-claude-code-works) を参照してください。12 コア agentic ループがどのように機能するかについては、[How Claude Code works](/ja/how-claude-code-works) を参照してください。

13</Note>13</Note>

14 14

~~15**Claude Code は初めてですか？** [CLAUDE.md](/ja/memory) でプロジェクト規約を開始します。必要に応じて他の拡張機能を追加してください。~~15**Claude Code は初めてですか？** [CLAUDE.md](/ja/memory) でプロジェクト規約を開始します。その後、[特定のトリガーが発生したときに](#build-your-setup-over-time)他の拡張機能を追加してください。

16 16

17## 概要17## 概要

18 18

23* **[MCP](/ja/mcp)** は Claude を外部サービスとツールに接続します23* **[MCP](/ja/mcp)** は Claude を外部サービスとツールに接続します

24* **[Subagents](/ja/sub-agents)** は独立したコンテキストで独自のループを実行し、サマリーを返します24* **[Subagents](/ja/sub-agents)** は独立したコンテキストで独自のループを実行し、サマリーを返します

25* **[Agent teams](/ja/agent-teams)** は、共有タスクとピアツーピアメッセージングを使用して複数の独立したセッションを調整します25* **[Agent teams](/ja/agent-teams)** は、共有タスクとピアツーピアメッセージングを使用して複数の独立したセッションを調整します

~~26* **[Hooks](/ja/hooks)** はループの外側で決定論的スクリプトとして実行されます~~26* **[Hooks](/ja/hooks-guide)** はライフサイクルイベントで発火し、スクリプト、HTTP リクエスト、プロンプト、または subagent を実行できます

27* **[Plugins](/ja/plugins)** と **[marketplaces](/ja/plugin-marketplaces)** はこれらの機能をパッケージ化して配布します27* **[Plugins](/ja/plugins)** と **[marketplaces](/ja/plugin-marketplaces)** はこれらの機能をパッケージ化して配布します

28 28

29[Skills](/ja/skills) は最も柔軟な拡張機能です。スキルは知識、ワークフロー、または指示を含むマークダウンファイルです。`/deploy` のようなコマンドでスキルを呼び出すことができます。または Claude は関連する場合に自動的にスキルをロードできます。スキルは現在の会話で実行することも、subagents を介して独立したコンテキストで実行することもできます。29[Skills](/ja/skills) は最も柔軟な拡張機能です。スキルは知識、ワークフロー、または指示を含むマークダウンファイルです。`/deploy` のようなコマンドでスキルを呼び出すことができます。または Claude は関連する場合に自動的にスキルをロードできます。スキルは現在の会話で実行することも、subagents を介して独立したコンテキストで実行することもできます。

33機能は、Claude がすべてのセッションで見る常時オンのコンテキストから、あなたまたは Claude が呼び出すことができるオンデマンド機能、特定のイベントで実行される背景自動化まで、さまざまです。以下の表は、利用可能な機能と各機能が適切な場合を示しています。33機能は、Claude がすべてのセッションで見る常時オンのコンテキストから、あなたまたは Claude が呼び出すことができるオンデマンド機能、特定のイベントで実行される背景自動化まで、さまざまです。以下の表は、利用可能な機能と各機能が適切な場合を示しています。

34 34

35| 機能 | 機能 | 使用する場合 | 例 |35| 機能 | 機能 | 使用する場合 | 例 |

~~36| ---------------------------------- | ---------------------------- | -------------------------------- | ------------------------------------------------------------ |~~36| ---------------------------------- | --------------------------------------------- | -------------------------------- | ------------------------------------------------------------ |

41| **MCP** | 外部サービスに接続 | 外部データまたはアクション | データベースをクエリ、Slack に投稿、ブラウザを制御 |41| **MCP** | 外部サービスに接続 | 外部データまたはアクション | データベースをクエリ、Slack に投稿、ブラウザを制御 |

43 43

44**[Plugins](/ja/plugins)** はパッケージングレイヤーです。プラグインはスキル、フック、subagents、MCP サーバーを単一のインストール可能なユニットにバンドルします。プラグインスキルは名前空間化されています（`/my-plugin:review` のように）ため、複数のプラグインが共存できます。同じセットアップを複数のリポジトリで再利用したい場合、または **[marketplace](/ja/plugin-marketplaces)** を通じて他のユーザーに配布したい場合はプラグインを使用します。44**[Plugins](/ja/plugins)** はパッケージングレイヤーです。プラグインはスキル、フック、subagents、MCP サーバーを単一のインストール可能なユニットにバンドルします。プラグインスキルは名前空間化されています（`/my-plugin:review` のように）ため、複数のプラグインが共存できます。同じセットアップを複数のリポジトリで再利用したい場合、または **[marketplace](/ja/plugin-marketplaces)** を通じて他のユーザーに配布したい場合はプラグインを使用します。

45 45

46### セットアップを時間をかけて構築する

48すべてを事前に設定する必要はありません。各機能には認識可能なトリガーがあり、ほとんどのチームはおおよそこの順序で追加します。

50| トリガー | 追加 |

51| :-------------------------------------- | :------------------------------------- |

52| Claude が規約またはコマンドを 2 回間違える | [CLAUDE.md](/ja/memory) に追加 |

53| 同じプロンプトをタスクを開始するために何度も入力している | ユーザーが呼び出し可能な [skill](/ja/skills) として保存 |

54| 同じプレイブックまたは複数ステップの手順をチャットに 3 回目に貼り付けている | [skill](/ja/skills) としてキャプチャ |

55| Claude が見ることができないブラウザタブからデータをコピーし続けている | そのシステムを [MCP server](/ja/mcp) として接続 |

56| サイドタスクが会話に再度参照しない出力で満杯になっている | [subagent](/ja/sub-agents) を通じてルーティング |

57| 何かが毎回聞かずに起こることを望んでいる | [hook](/ja/hooks-guide) を記述 |

58| 2 番目のリポジトリが同じセットアップを必要としている | [plugin](/ja/plugins) としてパッケージ化 |

60同じトリガーは、既に持っているものを更新する時期を示します。繰り返される間違いまたは繰り返されるレビューコメントは、チャットでの 1 回限りの修正ではなく、CLAUDE.md の編集です。手動で何度も調整するワークフローは、別の改訂が必要なスキルです。

46### 類似機能を比較する62### 類似機能を比較する

47 63

48一部の機能は似ているように見えることがあります。ここでは、それらを区別する方法を説明します。64一部の機能は似ているように見えることがあります。ここでは、それらを区別する方法を説明します。

55 * **Subagents** はメイン会話とは別に実行される独立したワーカーです71 * **Subagents** はメイン会話とは別に実行される独立したワーカーです

56 72

57 | 側面 | Skill | Subagent |73 | 側面 | Skill | Subagent |

~~58 | --------- | ------------------------- | ------------------------------ |~~74 | --------------------------------------------- | ------------------------- | ------------------------------ |

77 | **[Context window](/ja/context-window) への影響** | メインウィンドウに追加 | 独自の入力トークンと出力トークンを持つ別のウィンドウを使用 |

62 79

63 **スキルはリファレンスまたはアクションです。** リファレンススキルは Claude がセッション全体で使用する知識を提供します（API スタイルガイドなど）。アクションスキルは Claude に特定の操作を実行するよう指示します（デプロイメントワークフローを実行する `/deploy` など）。80 **スキルはリファレンスまたはアクションです。** リファレンススキルは Claude がセッション全体で使用する知識を提供します（API スタイルガイドなど）。アクションスキルは Claude に特定の操作を実行するよう指示します（デプロイメントワークフローを実行する `/deploy` など）。

142 159

143 例：MCP サーバーは Claude をデータベースに接続します。スキルは Claude にデータモデル、一般的なクエリパターン、さまざまなタスクに使用するテーブルを教えます。160 例：MCP サーバーは Claude をデータベースに接続します。スキルは Claude にデータモデル、一般的なクエリパターン、さまざまなタスクに使用するテーブルを教えます。

144 </Tab>161 </Tab>

162

163 <Tab title="Hook vs Skill">

164 フックはライフサイクルイベントで発火します。スキルはコンテキストにロードされて Claude が適用します。

165

166 | 側面 | Hook | Skill |

167 | ------------- | ------------------------------------------------------------------------------ | ----------------------------------- |

168 | **実行** | シェルコマンド、HTTP リクエスト、LLM プロンプト、または subagent | Claude が読み取って従う指示 |

169 | **トリガー** | [Lifecycle events](/ja/hooks#hook-events)（`PostToolUse` または `SessionStart` など） | `/<name>` を入力するか、Claude がタスクに説明を照合 |

170 | **決定論性** | イベントで常に発火。トリガーは保証される | Claude が指示を解釈。結果は異なる可能性 |

171 | **コンテキストコスト** | ゼロ（フックが出力を返さない限り） | 説明は毎セッションロード。使用時に完全なコンテンツをロード |

172 | **最適な用途** | リント後の編集、安全でないコマンドのブロック、ロギング、通知 | 推論が必要なワークフロー、リファレンスマテリアル、複数ステップのタスク |

173

174 **アクションが毎回同じ方法で実行される必要があり、Claude が考える必要がない場合は hook を使用します。** たとえば、保存時にフォーマット、`rm -rf /` を拒否、セッション終了時に Slack メッセージを投稿。

175

176 **Claude が手順をどのように適用するかを決定する必要がある場合、またはコンテンツが知識ではなくスクリプトの場合は skill を使用します。** たとえば、`/release` チェックリスト、API スタイルガイド、デバッグプレイブック。

177

178 **ガードレールをフックに入れます。** CLAUDE.md またはスキルの「`.env` を編集しない」のような指示はリクエストであり、保証ではありません。編集をブロックする `PreToolUse` フックは強制です。ルールが毎回保持される必要がある場合は、プロンプト指示ではなくフックにします。

179

180 **フック出力はコンテキストに着地します。** リンターを実行する `PostToolUse` フックは結果をテキストとして返し、Claude が読み取ります。`/fix-lint` スキルは Claude にそれらを解決する方法を指示します。

181 </Tab>

145</Tabs>182</Tabs>

146 183

147### 機能がどのようにレイヤーするかを理解する184### 機能がどのようにレイヤーするかを理解する

163| ---------------------- | ------------------------------------------------------------ | ---------------------------------------------------------------- |200| ---------------------- | ------------------------------------------------------------ | ---------------------------------------------------------------- |

168 205

169## コンテキストコストを理解する206## コンテキストコストを理解する

170 207

171追加する各機能は Claude のコンテキストの一部を消費します。多すぎるとコンテキストウィンドウがいっぱいになる可能性がありますが、Claude の効果を低下させるノイズを追加することもできます。スキルが正しくトリガーされない場合や、Claude が規約を失う場合があります。これらのトレードオフを理解することで、効果的なセットアップを構築するのに役立ちます。208追加する各機能は Claude のコンテキストの一部を消費します。多すぎるとコンテキストウィンドウがいっぱいになる可能性がありますが、Claude の効果を低下させるノイズを追加することもできます。スキルが正しくトリガーされない場合や、Claude が規約を失う場合があります。これらのトレードオフを理解することで、効果的なセットアップを構築するのに役立ちます。実行中のセッションでこれらの機能がどのように組み合わされるかのインタラクティブビューについては、[Explore the context window](/ja/context-window) を参照してください。

172 209

173### 機能別のコンテキストコスト210### 機能別のコンテキストコスト

174 211

175各機能には異なるロード戦略とコンテキストコストがあります。212各機能には異なるロード戦略とコンテキストコストがあります。

176 213

177| 機能 | ロード時期 | ロード内容 | コンテキストコスト |214| 機能 | ロード時期 | ロード内容 | コンテキストコスト |

178| ------------- | ------------- | -------------------- | ---------------------- |215| ------------- | ------------- | ------------------------- | ----------------------- |

184 221

185\*デフォルトでは、スキル説明はセッション開始時にロードされるため、Claude はそれらを使用する時期を決定できます。スキルの frontmatter で `disable-model-invocation: true` を設定して、手動で呼び出すまで Claude から完全に非表示にします。これにより、自分でのみトリガーするスキルのコンテキストコストをゼロに削減します。222\*デフォルトでは、スキル説明はセッション開始時にロードされるため、Claude はそれらを使用する時期を決定できます。スキルの frontmatter で `disable-model-invocation: true` を設定して、手動で呼び出すまで Claude から完全に非表示にします。これにより、自分でのみトリガーするスキルのコンテキストコストをゼロに削減します。

186 223

188 225

189各機能はセッション内の異なるポイントでロードされます。以下のタブは、各機能がいつロードされるか、およびコンテキストに何が入るかを説明しています。226各機能はセッション内の異なるポイントでロードされます。以下のタブは、各機能がいつロードされるか、およびコンテキストに何が入るかを説明しています。

190 227

191<img src="https://mintcdn.com/claude-code/6yTCYq1p37ZB8-CQ/images/context-loading.svg?fit=max&auto=format&n=6yTCYq1p37ZB8-CQ&q=85&s=5a58ce953a35a2412892015e2ad6cb67" alt="コンテキストロード：CLAUDE.md と MCP はセッション開始時にロードされ、すべてのリクエストに留まります。スキルは開始時に説明をロードし、呼び出し時に完全なコンテンツをロードします。Subagents は独立したコンテキストを取得します。Hooks は外部で実行されます。" width="720" height="410" data-path="images/context-loading.svg" />228<img src="https://mintcdn.com/claude-code/6yTCYq1p37ZB8-CQ/images/context-loading.svg?fit=max&auto=format&n=6yTCYq1p37ZB8-CQ&q=85&s=5a58ce953a35a2412892015e2ad6cb67" alt="コンテキストロード：CLAUDE.md はセッション開始時にロードされ、すべてのリクエストに留まります。MCP ツール名は開始時にロードされ、完全なスキーマは使用時に遅延されます。スキルは開始時に説明をロードし、呼び出し時に完全なコンテンツをロードします。Subagents は独立したコンテキストを取得します。Hooks は外部で実行されます。" width="720" height="410" data-path="images/context-loading.svg" />

192 229

193<Tabs>230<Tabs>

194 <Tab title="CLAUDE.md">231 <Tab title="CLAUDE.md">

202 </Tab>239 </Tab>

203 240

204 <Tab title="Skills">241 <Tab title="Skills">

205 スキルは Claude のツールキットの追加機能です。リファレンスマテリアル（API スタイルガイドなど）または `/<name>` でトリガーする呼び出し可能なワークフロー（`/deploy` など）です。Claude Code は `/simplify`、`/batch`、`/debug` などの[バンドルされたスキル](/ja/skills#bundled-skills)を備えており、すぐに機能します。独自のスキルを作成することもできます。Claude は適切な場合にスキルを使用するか、直接呼び出すことができます。242 スキルは Claude のツールキットの追加機能です。リファレンスマテリアル（API スタイルガイドなど）または `/<name>` でトリガーする呼び出し可能なワークフロー（`/deploy` など）です。Claude Code は `/simplify`、`/batch`、`/debug` などの[バンドルされたスキル](/ja/commands) を備えており、すぐに機能します。独自のスキルを作成することもできます。Claude は適切な場合にスキルを使用するか、直接呼び出すことができます。

206 243

207 **時期：** スキルの設定によって異なります。デフォルトでは、説明はセッション開始時にロードされ、完全なコンテンツは使用時にロードされます。ユーザーのみのスキル（`disable-model-invocation: true`）の場合、呼び出すまで何もロードされません。244 **時期：** スキルの設定によって異なります。デフォルトでは、説明はセッション開始時にロードされ、完全なコンテンツは使用時にロードされます。ユーザーのみのスキル（`disable-model-invocation: true`）の場合、呼び出すまで何もロードされません。

208 245

220 <Tab title="MCP servers">257 <Tab title="MCP servers">

221 **時期：** セッション開始。258 **時期：** セッション開始。

222 259

223 **ロード内容：** 接続されたサーバーからのすべてのツール定義と JSON スキーマ。260 **ロード内容：** 接続されたサーバーからのツール名。完全な JSON スキーマは Claude が特定のツールを必要とするまで遅延されます。

224 261

225 **コンテキストコスト：** [Tool search](/ja/mcp#scale-with-mcp-tool-search)（デフォルトで有効）は MCP ツールをコンテキストの最大 10% までロードし、残りは必要になるまで遅延します。262 **コンテキストコスト：** [Tool search](/ja/mcp#scale-with-mcp-tool-search) はデフォルトで有効になっているため、アイドル MCP ツールは最小限のコンテキストを消費します。

226 263

227 **信頼性に関する注記：** MCP 接続はセッション中に静かに失敗する可能性があります。サーバーが切断されると、そのツールは警告なく消えます。Claude は以前アクセスできたツールを使用しようとする可能性があります。Claude が以前アクセスできた MCP ツールを使用できなくなったことに気付いた場合は、`/mcp` で接続を確認してください。264 **信頼性に関する注記：** MCP 接続はセッション中に静かに失敗する可能性があります。サーバーが切断されると、そのツールは警告なく消えます。Claude は以前アクセスできたツールを使用しようとする可能性があります。Claude が以前アクセスできた MCP ツールを使用できなくなったことに気付いた場合は、`/mcp` で接続を確認してください。

228 265

247 <Tab title="Hooks">284 <Tab title="Hooks">

248 **時期：** トリガー時。フックはツール実行、セッション境界、プロンプト送信、権限リクエスト、コンパクションなどの特定のライフサイクルイベントで発火します。完全なリストは [Hooks](/ja/hooks) を参照してください。285 **時期：** トリガー時。フックはツール実行、セッション境界、プロンプト送信、権限リクエスト、コンパクションなどの特定のライフサイクルイベントで発火します。完全なリストは [Hooks](/ja/hooks) を参照してください。

249 286

250 **ロード内容：** デフォルトではなし。フックは外部スクリプトとして実行されます。287 **ロード内容：** デフォルトではなし。フックは外部で実行されます。

251 288

252 **コンテキストコスト：** ゼロ、フックが会話にメッセージとして追加されるコンテキストを返さない限り。289 **コンテキストコスト：** ゼロ（フックが会話にメッセージとして追加されるコンテキストを返さない限り）。

253 290

254 <Tip>フックは Claude のコンテキストに影響する必要がない副作用（リント、ロギング）に最適です。</Tip>291 <Tip>フックは Claude のコンテキストに影響する必要がない副作用（リント、ロギング）に最適です。</Tip>

255 </Tab>292 </Tab>

hooks.md +1 −1

Details

978 978

979```json theme={null}979```json theme={null}

980{980{

permissions.md +8 −8

Details

36| :------------------ | :------------------------------------------------------------------------------------------------------------ |36| :------------------ | :------------------------------------------------------------------------------------------------------------ |

37| `default` | 標準動作。各ツールの最初の使用時に権限を促します |37| `default` | 標準動作。各ツールの最初の使用時に権限を促します |

38| `acceptEdits` | ファイル編集と一般的なファイルシステムコマンド（`mkdir`、`touch`、`mv`、`cp` など）を、作業ディレクトリまたは `additionalDirectories` 内のパスに対して自動的に受け入れます |38| `acceptEdits` | ファイル編集と一般的なファイルシステムコマンド（`mkdir`、`touch`、`mv`、`cp` など）を、作業ディレクトリまたは `additionalDirectories` 内のパスに対して自動的に受け入れます |

43 43

44<Warning>44<Warning>

45 `bypassPermissions` モードはすべての権限プロンプトをスキップします。`.git`、`.claude`、`.vscode`、`.idea`、`.husky` への書き込みを含みます。ファイルシステムルートまたはホームディレクトリを対象とした削除（`rm -rf /` や `rm -rf ~` など）は、モデルエラーに対する回路遮断器として引き続きプロンプトを表示します。このモードは、Claude Code が損害を引き起こせないコンテナや VM などの隔離された環境でのみ使用してください。管理者は、[管理設定](#managed-settings)で `permissions.disableBypassPermissionsMode` を `"disable"` に設定することで、このモードを防止できます。45 `bypassPermissions` モードはすべての権限プロンプトをスキップします。`.git`、`.claude`、`.vscode`、`.idea`、`.husky` への書き込みを含みます。ファイルシステムルートまたはホームディレクトリを対象とした削除（`rm -rf /` や `rm -rf ~` など）は、モデルエラーに対する回路遮断器として引き続きプロンプトを表示します。このモードは、Claude Code が損害を引き起こせないコンテナや VM などの隔離された環境でのみ使用してください。管理者は、[管理設定](#managed-settings)で `permissions.disableBypassPermissionsMode` を `"disable"` に設定することで、このモードを防止できます。

296 296

297* 権限 deny ルールは、Claude が制限されたリソースへのアクセスを試みることさえ防止します297* 権限 deny ルールは、Claude が制限されたリソースへのアクセスを試みることさえ防止します

298* サンドボックス制限は、プロンプトインジェクションが Claude の意思決定をバイパスしても、Bash コマンドが定義された境界外のリソースに到達することを防止します298* サンドボックス制限は、プロンプトインジェクションが Claude の意思決定をバイパスしても、Bash コマンドが定義された境界外のリソースに到達することを防止します

299* サンドボックス内のファイルシステム制限は、Read と Edit deny ルールを使用し、別のサンドボックス設定は使用しません299* サンドボックス内のファイルシステム制限は、[`sandbox.filesystem`](/ja/sandboxing) 設定と Read および Edit deny ルールを組み合わせます。両方が最終的なサンドボックス境界にマージされます

300* ネットワーク制限は、WebFetch 権限ルールとサンドボックスの `allowedDomains` と `deniedDomains` リストを組み合わせます300* ネットワーク制限は、WebFetch 権限ルールとサンドボックスの `allowedDomains` および `deniedDomains` リストを組み合わせます

301 301

302サンドボックスが `autoAllowBashIfSandboxed: true` で有効になっている場合（デフォルト）、サンドボックス化された Bash コマンドは、権限に `ask: Bash(*)` が含まれている場合でもプロンプトなしで実行されます。サンドボックス境界はコマンドごとのプロンプトの代わりになります。[サンドボックスモード](/ja/sandboxing#sandbox-modes)を参照して、この動作を変更してください。302サンドボックスが `autoAllowBashIfSandboxed: true` で有効になっている場合（デフォルト）、サンドボックス化された Bash コマンドは、権限に `ask: Bash(*)` が含まれている場合でもプロンプトなしで実行されます。サンドボックス境界はコマンドごとのプロンプトの代わりになります。明示的な deny ルールは引き続き適用され、`/`、ホームディレクトリ、またはその他の重要なシステムパスをターゲットとする `rm` または `rmdir` コマンドは、引き続きプロンプトをトリガーします。[サンドボックスモード](/ja/sandboxing#sandbox-modes)を参照して、この動作を変更してください。

303 303

304## 管理設定304## 管理設定

305 305

316| `allowManagedMcpServersOnly` | `true` の場合、管理設定からの `allowedMcpServers` のみが尊重されます。`deniedMcpServers` はすべてのソースからマージされます。[管理 MCP 設定](/ja/mcp#managed-mcp-configuration)を参照してください |316| `allowManagedMcpServersOnly` | `true` の場合、管理設定からの `allowedMcpServers` のみが尊重されます。`deniedMcpServers` はすべてのソースからマージされます。[管理 MCP 設定](/ja/mcp#managed-mcp-configuration)を参照してください |

317| `allowManagedPermissionRulesOnly` | `true` の場合、ユーザーおよびプロジェクト設定が `allow`、`ask`、または `deny` 権限ルールを定義することを防止します。管理設定のルールのみが適用されます |317| `allowManagedPermissionRulesOnly` | `true` の場合、ユーザーおよびプロジェクト設定が `allow`、`ask`、または `deny` 権限ルールを定義することを防止します。管理設定のルールのみが適用されます |

318| `blockedMarketplaces` | マーケットプレイスソースのブロックリスト。ブロックされたソースはダウンロード前にチェックされるため、ファイルシステムに触れることはありません。[管理マーケットプレイス制限](/ja/plugin-marketplaces#managed-marketplace-restrictions)を参照してください |318| `blockedMarketplaces` | マーケットプレイスソースのブロックリスト。ブロックされたソースはダウンロード前にチェックされるため、ファイルシステムに触れることはありません。[管理マーケットプレイス制限](/ja/plugin-marketplaces#managed-marketplace-restrictions)を参照してください |

319| `channelsEnabled` | Team および Enterprise ユーザーの[チャネル](/ja/channels)を許可します。設定されていないか `false` の場合、ユーザーが `--channels` に渡すものに関係なく、チャネルメッセージ配信をブロックします |319| `channelsEnabled` | 組織の[チャネル](/ja/channels)を許可します。各プランのデフォルトについては、[エンタープライズコントロール](/ja/channels#enterprise-controls)を参照してください |

320| `forceRemoteSettingsRefresh` | `true` の場合、リモート管理設定が新しく取得されるまで CLI 起動をブロックし、取得に失敗した場合は終了します。[フェイルクローズ強制](/ja/server-managed-settings#enforce-fail-closed-startup)を参照してください |320| `forceRemoteSettingsRefresh` | `true` の場合、リモート管理設定が新しく取得されるまで CLI 起動をブロックし、取得に失敗した場合は終了します。[フェイルクローズ強制](/ja/server-managed-settings#enforce-fail-closed-startup)を参照してください |

322| `sandbox.filesystem.allowManagedReadPathsOnly` | `true` の場合、管理設定からの `filesystem.allowRead` パスのみが尊重されます。`denyRead` はすべてのソースからマージされます |322| `sandbox.filesystem.allowManagedReadPathsOnly` | `true` の場合、管理設定からの `filesystem.allowRead` パスのみが尊重されます。`denyRead` はすべてのソースからマージされます |

323| `sandbox.network.allowManagedDomainsOnly` | `true` の場合、管理設定からの `allowedDomains` と `WebFetch(domain:...)` allow ルールのみが尊重されます。許可されていないドメインはユーザーに促すことなく自動的にブロックされます。拒否されたドメインはすべてのソースからマージされます |323| `sandbox.network.allowManagedDomainsOnly` | `true` の場合、管理設定からの `allowedDomains` と `WebFetch(domain:...)` allow ルールのみが尊重されます。許可されていないドメインはユーザーに促すことなく自動的にブロックされます。拒否されたドメインはすべてのソースからマージされます |

324| `strictKnownMarketplaces` | ユーザーが追加できるプラグインマーケットプレイスを制御します。[管理マーケットプレイス制限](/ja/plugin-marketplaces#managed-marketplace-restrictions)を参照してください |324| `strictKnownMarketplaces` | ユーザーが追加およびインストールできるプラグインマーケットプレイスソースを制御します。[管理マーケットプレイス制限](/ja/plugin-marketplaces#managed-marketplace-restrictions)を参照してください |

325| `wslInheritsWindowsSettings` | Windows HKLM レジストリキーまたは `C:\Program Files\ClaudeCode\managed-settings.json` で `true` の場合、WSL は `/etc/claude-code` に加えて Windows ポリシーチェーンから管理設定を読み込みます。[設定ファイル](/ja/settings#settings-files)を参照してください |325| `wslInheritsWindowsSettings` | Windows HKLM レジストリキーまたは `C:\Program Files\ClaudeCode\managed-settings.json` で `true` の場合、WSL は `/etc/claude-code` に加えて Windows ポリシーチェーンから管理設定を読み込みます。[設定ファイル](/ja/settings#settings-files)を参照してください |

326 326

327`disableBypassPermissionsMode` は通常、組織ポリシーを強制するために管理設定に配置されますが、任意のスコープから機能します。ユーザーは独自の設定で設定して、自分自身をバイパスモードからロックアウトできます。327`disableBypassPermissionsMode` は通常、組織ポリシーを強制するために管理設定に配置されますが、任意のスコープから機能します。ユーザーは独自の設定で設定して、自分自身をバイパスモードからロックアウトできます。

328 328

329<Note>329<Note>

330 [リモートコントロール](/ja/remote-control)と[ウェブセッション](/ja/claude-code-on-the-web)へのアクセスは、管理設定キーで制御されません。Team および Enterprise プランでは、管理者が [Claude Code 管理設定](https://claude.ai/admin-settings/claude-code)でこれらの機能を有効または無効にします。330 Team および Enterprise プランでは、管理者が [Claude Code 管理設定](https://claude.ai/admin-settings/claude-code)で[リモートコントロール](/ja/remote-control)と[ウェブセッション](/ja/claude-code-on-the-web)を組織全体で有効または無効にします。リモートコントロールは、[`disableRemoteControl`](/ja/settings#available-settings)管理設定でデバイスごとに無効にすることもできます。ウェブセッションにはデバイスごとの管理設定キーはありません。

331</Note>331</Note>

332 332

333## 設定の優先順位333## 設定の優先順位

platforms.md +7 −4

Details

4 4

5# プラットフォームと統合5# プラットフォームと統合

6 6

7> Claude Code を実行する場所を選択し、何に接続するかを決定します。CLI、Desktop、VS Code、JetBrains、Web、および Chrome、Slack、CI/CD などの統合を比較します。7> Claude Code を実行する場所を選択し、何に接続するかを決定します。CLI、Desktop、VS Code、JetBrains、Web、モバイル、および Chrome、Slack、CI/CD などの統合を比較します。

8 8

9Claude Code は、どこでも同じ基盤となるエンジンを実行しますが、各サーフェスは異なる作業方法に合わせて調整されています。このページは、ワークフローに適したプラットフォームを選択し、既に使用しているツールを接続するのに役立ちます。9Claude Code は、どこでも同じ基盤となるエンジンを実行しますが、各サーフェスは異なる作業方法に合わせて調整されています。このページは、ワークフローに適したプラットフォームを選択し、既に使用しているツールを接続するのに役立ちます。

10 10

13プロジェクトがどこにあるか、どのように作業したいかに基づいてプラットフォームを選択します。13プロジェクトがどこにあるか、どのように作業したいかに基づいてプラットフォームを選択します。

14 14

16| :-------------------------------- | :--------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------- |16| :-------------------------------- | :--------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------- |

18| [Desktop](/ja/desktop) | ビジュアルレビュー、並列セッション、管理されたセットアップ | Diff ビューアー、アプリプレビュー、Pro および Max での[コンピューター使用](/ja/desktop#let-claude-use-your-computer)および[Dispatch](/ja/desktop#sessions-from-dispatch) |18| [Desktop](/ja/desktop) | ビジュアルレビュー、並列セッション、管理されたセットアップ | Diff ビューアー、アプリプレビュー、Pro および Max での[コンピューター使用](/ja/desktop#let-claude-use-your-computer)および[Dispatch](/ja/desktop#sessions-from-dispatch) |

22| モバイル | コンピューターから離れている間にタスクを開始および監視 | iOS および Android 用 Claude アプリからのクラウドセッション、ローカルセッション用の[Remote Control](/ja/remote-control)、Pro および Max での Desktop への[Dispatch](/ja/desktop#sessions-from-dispatch) |

22 23

23CLI はターミナルネイティブな作業に最も完全なサーフェスです。スクリプティング、サードパーティプロバイダー、Agent SDK は CLI のみです。Desktop と IDE 拡張機能は、CLI のみの機能の一部をビジュアルレビューとより緊密なエディター統合と引き換えにします。Web は Anthropic のクラウドで実行されるため、切断後もタスクが続行されます。24CLI はターミナルネイティブな作業に最も完全なサーフェスです。スクリプティングと Agent SDK は CLI のみです。サードパーティプロバイダーは[VS Code](/ja/vs-code#use-third-party-providers)でも機能します。Enterprise [Desktop](/ja/desktop) デプロイメントは Vertex AI およびゲートウェイプロバイダーをサポートしています。Bedrock または Foundry の場合は、Desktop の代わりに CLI または VS Code を使用してください。Desktop と IDE 拡張機能は、CLI のみの機能の一部をビジュアルレビューとより緊密なエディター統合と引き換えにします。Web は Anthropic のクラウドで実行されるため、切断後もタスクが続行されます。モバイルは、これらの同じクラウドセッションへのシンクライアント、または Remote Control 経由のローカルセッションへのシンクライアントであり、Dispatch で Desktop にタスクを送信できます。

24 25

25同じプロジェクトで複数のサーフェスを混在させることができます。設定、プロジェクトメモリ、MCP サーバーはローカルサーフェス全体で共有されます。26同じプロジェクトで複数のサーフェスを混在させることができます。設定、プロジェクトメモリ、MCP サーバーはローカルサーフェス全体で共有されます。

26 27

61* [VS Code](/ja/vs-code)：エディター内の Claude Code 拡張機能62* [VS Code](/ja/vs-code)：エディター内の Claude Code 拡張機能

62* [JetBrains](/ja/jetbrains)：IntelliJ、PyCharm、およびその他の JetBrains IDE の拡張機能63* [JetBrains](/ja/jetbrains)：IntelliJ、PyCharm、およびその他の JetBrains IDE の拡張機能

63* [Claude Code on the web](/ja/claude-code-on-the-web)：切断後も実行し続けるクラウドセッション64* [Claude Code on the web](/ja/claude-code-on-the-web)：切断後も実行し続けるクラウドセッション

65* モバイル：コンピューターから離れている間にタスクを開始および監視するための [iOS](https://apps.apple.com/us/app/claude-by-anthropic/id6473753684) および [Android](https://play.google.com/store/apps/details?id=com.anthropic.claude) 用 Claude アプリ

64 66

65### 統合67### 統合

66 68

67* [Chrome](/ja/chrome)：ログインしたセッションでブラウザタスクを自動化69* [Chrome](/ja/chrome)：ログインしたセッションでブラウザタスクを自動化

70* [Computer use](/ja/computer-use)：Claude が macOS でアプリを開いてスクリーンを制御できるようにする

68* [GitHub Actions](/ja/github-actions)：CI パイプラインで Claude を実行71* [GitHub Actions](/ja/github-actions)：CI パイプラインで Claude を実行

69* [GitLab CI/CD](/ja/gitlab-ci-cd)：GitLab の場合も同じ72* [GitLab CI/CD](/ja/gitlab-ci-cd)：GitLab の場合も同じ

70* [Code Review](/ja/code-review)：すべてのプルリクエストで自動レビュー73* [Code Review](/ja/code-review)：すべてのプルリクエストで自動レビュー

plugin-marketplaces.md +8 −6

Details

23 23

24## チュートリアル：ローカルマーケットプレイスの作成24## チュートリアル：ローカルマーケットプレイスの作成

25 25

26この例では、1 つのプラグイン（コードレビュー用の `/quality-review` skill）を含むマーケットプレイスを作成します。ディレクトリ構造を作成し、skill を追加し、プラグインマニフェストとマーケットプレイスカタログを作成してから、インストールしてテストします。26この例では、1 つのプラグイン（コードレビュー用の `quality-review` skill）を含むマーケットプレイスを作成します。ディレクトリ構造を作成し、skill を追加し、プラグインマニフェストとマーケットプレイスカタログを作成してから、インストールしてテストします。

27 27

28<Steps>28<Steps>

29 <Step title="ディレクトリ構造の作成">29 <Step title="ディレクトリ構造の作成">

35 </Step>35 </Step>

36 36

37 <Step title="skill の作成">37 <Step title="skill の作成">

~~38 `/quality-review` skill が何をするかを定義する `SKILL.md` ファイルを作成します。~~38 `quality-review` skill が何をするかを定義する `SKILL.md` ファイルを作成します。

39 39

40 ```markdown my-marketplace/plugins/quality-review-plugin/skills/quality-review/SKILL.md theme={null}40 ```markdown my-marketplace/plugins/quality-review-plugin/skills/quality-review/SKILL.md theme={null}

41 ---41 ---

59 ```json my-marketplace/plugins/quality-review-plugin/.claude-plugin/plugin.json theme={null}59 ```json my-marketplace/plugins/quality-review-plugin/.claude-plugin/plugin.json theme={null}

60 {60 {

61 "name": "quality-review-plugin",61 "name": "quality-review-plugin",

~~62 "description": "Adds a /quality-review skill for quick code reviews",~~62 "description": "Adds a quality-review skill for quick code reviews",

63 "version": "1.0.0"63 "version": "1.0.0"

64 }64 }

65 ```65 ```

82 {82 {

83 "name": "quality-review-plugin",83 "name": "quality-review-plugin",

84 "source": "./plugins/quality-review-plugin",84 "source": "./plugins/quality-review-plugin",

~~85 "description": "Adds a /quality-review skill for quick code reviews"~~85 "description": "Adds a quality-review skill for quick code reviews"

86 }86 }

87 ]87 ]

88 }88 }

99 </Step>99 </Step>

100 100

101 <Step title="試してみる">101 <Step title="試してみる">

102 エディタでコードを選択し、新しい skill を実行します。102 エディタでコードを選択し、新しい skill を実行します。プラグイン skill はプラグイン名でネームスペース化されます。

103 103

104 ```shell theme={null}104 ```shell theme={null}

105 /quality-review105 /quality-review-plugin:quality-review

106 ```106 ```

107 </Step>107 </Step>

108</Steps>108</Steps>

693* `hostPattern` ソースの場合：マーケットプレイスホストが正規表現パターンと照合されます693* `hostPattern` ソースの場合：マーケットプレイスホストが正規表現パターンと照合されます

694* `pathPattern` ソースの場合：マーケットプレイスのファイルシステムパスが正規表現パターンと照合されます694* `pathPattern` ソースの場合：マーケットプレイスのファイルシステムパスが正規表現パターンと照合されます

695 695

696正確なマッチングは URL を正規化しません。末尾のスラッシュ、`.git` サフィックス、または `ssh://` と `https://` の形式は異なる値として扱われます。組織のマーケットプレイスが複数の URL 形式でクローンできる場合、リテラル URL よりも `hostPattern` エントリを優先して、すべての形式が一致するようにします。

697

696`strictKnownMarketplaces` は[管理設定](/ja/settings#settings-files)で設定されるため、個別のユーザーとプロジェクト設定はこれらの制限をオーバーライドできません。698`strictKnownMarketplaces` は[管理設定](/ja/settings#settings-files)で設定されるため、個別のユーザーとプロジェクト設定はこれらの制限をオーバーライドできません。

697 699

698完全な設定詳細（サポートされているすべてのソースタイプと `extraKnownMarketplaces` との比較を含む）については、[strictKnownMarketplaces リファレンス](/ja/settings#strictknownmarketplaces)を参照してください。700完全な設定詳細（サポートされているすべてのソースタイプと `extraKnownMarketplaces` との比較を含む）については、[strictKnownMarketplaces リファレンス](/ja/settings#strictknownmarketplaces)を参照してください。

plugins-reference.md +7 −3

Details

262**利用可能な LSP プラグイン:**262**利用可能な LSP プラグイン:**

263 263

265| :--------------- | :------------------------- | :---------------------------------------------------------------------------------- |265| :------------------ | :------------------------- | :---------------------------------------------------------------------------------- |

269 269

270言語サーバーをまずインストールしてから、マーケットプレイスからプラグインをインストールしてください。270言語サーバーをまずインストールしてから、マーケットプレイスからプラグインをインストールしてください。

271 271

531 531

532Claude Code は、プラグインパスを参照するための 2 つの変数を提供します。どちらも skill コンテンツ、エージェントコンテンツ、hook コマンド、monitor コマンド、MCP または LSP サーバー設定に表示される場所にインラインで置換されます。どちらも hook プロセスおよび MCP または LSP サーバーサブプロセスに環境変数としてエクスポートされます。532Claude Code は、プラグインパスを参照するための 2 つの変数を提供します。どちらも skill コンテンツ、エージェントコンテンツ、hook コマンド、monitor コマンド、MCP または LSP サーバー設定に表示される場所にインラインで置換されます。どちらも hook プロセスおよび MCP または LSP サーバーサブプロセスに環境変数としてエクスポートされます。

533 533

534**`${CLAUDE_PLUGIN_ROOT}`**: プラグインのインストールディレクトリへの絶対パス。プラグインにバンドルされたスクリプト、バイナリ、設定ファイルを参照するために使用します。このパスはプラグインが更新されると変更されるため、ここに書き込むファイルは更新後に保持されません。534**`${CLAUDE_PLUGIN_ROOT}`**: プラグインのインストールディレクトリへの絶対パス。プラグインにバンドルされたスクリプト、バイナリ、設定ファイルを参照するために使用します。このパスはプラグインが更新されると変更されます。前のバージョンのディレクトリは更新後約 7 日間ディスク上に残りますが、これを一時的なものとして扱い、ここに状態を書き込まないでください。

535

536プラグインがセッション中に更新されると、hook コマンド、monitors、MCP サーバー、LSP サーバーは前のバージョンのパスを使用し続けます。`/reload-plugins` を実行して、hook、MCP サーバー、LSP サーバーを新しいパスに切り替えます。monitors はセッション再起動が必要です。

535 537

536**`${CLAUDE_PLUGIN_DATA}`**: 更新後も保持される永続ディレクトリ。`node_modules` または Python 仮想環境などのインストール済み依存関係、生成されたコード、キャッシュ、およびプラグインバージョン全体で保持する必要があるその他のファイルに使用します。このディレクトリは、この変数が最初に参照されるときに自動的に作成されます。538**`${CLAUDE_PLUGIN_DATA}`**: 更新後も保持される永続ディレクトリ。`node_modules` または Python 仮想環境などのインストール済み依存関係、生成されたコード、キャッシュ、およびプラグインバージョン全体で保持する必要があるその他のファイルに使用します。このディレクトリは、この変数が最初に参照されるときに自動的に作成されます。

537 539

677 `.claude-plugin/` ディレクトリは `plugin.json` ファイルを含みます。他のすべてのディレクトリ（commands/、agents/、skills/、output-styles/、themes/、monitors/、hooks/）は `.claude-plugin/` 内ではなく、プラグインルートにある必要があります。679 `.claude-plugin/` ディレクトリは `plugin.json` ファイルを含みます。他のすべてのディレクトリ（commands/、agents/、skills/、output-styles/、themes/、monitors/、hooks/）は `.claude-plugin/` 内ではなく、プラグインルートにある必要があります。

678</Warning>680</Warning>

679 681

682プラグインルートの `CLAUDE.md` ファイルはプロジェクトコンテキストとして読み込まれません。プラグインは CLAUDE.md ではなく、skills、agents、hooks を通じてコンテキストを提供します。Claude のコンテキストに読み込まれる命令を配布するには、[skill](#skills) に配置してください。

683

680### ファイル場所リファレンス684### ファイル場所リファレンス

681 685

682| コンポーネント | デフォルト場所 | 目的 |686| コンポーネント | デフォルト場所 | 目的 |

security.md +1 −1

Details

27* **サンドボックス化された bash ツール**: [Sandbox](/ja/sandboxing) bash コマンドをファイルシステムとネットワークの分離で実行し、パーミッションプロンプトを減らしながらセキュリティを維持します。`/sandbox` で有効にして、Claude Code が自律的に動作できる境界を定義します27* **サンドボックス化された bash ツール**: [Sandbox](/ja/sandboxing) bash コマンドをファイルシステムとネットワークの分離で実行し、パーミッションプロンプトを減らしながらセキュリティを維持します。`/sandbox` で有効にして、Claude Code が自律的に動作できる境界を定義します

28* **書き込みアクセス制限**: Claude Code は開始されたフォルダとそのサブフォルダにのみ書き込みでき、明示的なパーミッションなしに親ディレクトリのファイルを変更することはできません。Claude Code は作業ディレクトリ外のファイルを読み取ることができます（システムライブラリと依存関係へのアクセスに便利です）が、書き込み操作はプロジェクトスコープに厳密に限定され、明確なセキュリティ境界を作成します28* **書き込みアクセス制限**: Claude Code は開始されたフォルダとそのサブフォルダにのみ書き込みでき、明示的なパーミッションなしに親ディレクトリのファイルを変更することはできません。Claude Code は作業ディレクトリ外のファイルを読み取ることができます（システムライブラリと依存関係へのアクセスに便利です）が、書き込み操作はプロジェクトスコープに厳密に限定され、明確なセキュリティ境界を作成します

29* **プロンプト疲労の軽減**: ユーザーごと、コードベースごと、または組織ごとに頻繁に使用される安全なコマンドのホワイトリスト化をサポート29* **プロンプト疲労の軽減**: ユーザーごと、コードベースごと、または組織ごとに頻繁に使用される安全なコマンドのホワイトリスト化をサポート

~~30* **Accept Edits モード**: 複数の編集をバッチで受け入れながら、副作用のあるコマンドのパーミッションプロンプトを維持~~30* **Accept Edits モード**: ファイル編集と `mkdir`、`touch`、`rm`、`mv`、`cp`、`sed` などの固定セットのファイルシステム Bash コマンドを作業ディレクトリ内のパスに対して自動承認します。その他の Bash コマンドとスコープ外のパスはプロンプトが表示されます

31 31

32### ユーザーの責任32### ユーザーの責任

33 33

settings.md +26 −3

Details

73 73

74Windows では、`~/.claude` として表示されるパスは `%USERPROFILE%\.claude` に解決されます。

74***76***

75 77

76## 設定ファイル78## 設定ファイル

167| `attribution` | git コミットとプルリクエストの属性をカスタマイズします。[属性設定](#attribution-settings)を参照してください | `{"commit": "🤖 Generated with Claude Code", "pr": ""}` |169| `attribution` | git コミットとプルリクエストの属性をカスタマイズします。[属性設定](#attribution-settings)を参照してください | `{"commit": "🤖 Generated with Claude Code", "pr": ""}` |

168| `autoMemoryDirectory` | [自動メモリ](/ja/memory#storage-location)ストレージ用のカスタムディレクトリ。絶対パスまたは `~/` プレフィックス付きパスを受け入れます。ポリシーおよびユーザー設定から、および `--settings` フラグから受け入れられます。クローンされたリポジトリがメモリ書き込みを機密の場所にリダイレクトするのを防ぐため、プロジェクトまたはローカル設定からは受け入れられません | `"~/my-memory-dir"` |170| `autoMemoryDirectory` | [自動メモリ](/ja/memory#storage-location)ストレージ用のカスタムディレクトリ。絶対パスまたは `~/` プレフィックス付きパスを受け入れます。ポリシーおよびユーザー設定から、および `--settings` フラグから受け入れられます。クローンされたリポジトリがメモリ書き込みを機密の場所にリダイレクトするのを防ぐため、プロジェクトまたはローカル設定からは受け入れられません | `"~/my-memory-dir"` |

171| `autoMemoryEnabled` | [自動メモリ](/ja/memory#enable-or-disable-auto-memory)を有効にします。`false` の場合、Claude は自動メモリディレクトリから読み込んだり、書き込んだりしません。デフォルト：`true`。セッション中に `/memory` でこれを切り替えることもできます | `false` |

169| `autoMode` | [自動モード](/ja/permission-modes#eliminate-prompts-with-auto-mode)分類器がブロックおよび許可するものをカスタマイズします。`environment`、`allow`、および `soft_deny` 配列の散文ルールを含みます。リテラル文字列 `"$defaults"` を配列に含めて、その位置で組み込みルールを継承します。[自動モードを構成](/ja/auto-mode-config)を参照してください。共有プロジェクト設定から読み込まれません | `{"soft_deny": ["$defaults", "Never run terraform apply"]}` |172| `autoMode` | [自動モード](/ja/permission-modes#eliminate-prompts-with-auto-mode)分類器がブロックおよび許可するものをカスタマイズします。`environment`、`allow`、および `soft_deny` 配列の散文ルールを含みます。リテラル文字列 `"$defaults"` を配列に含めて、その位置で組み込みルールを継承します。[自動モードを構成](/ja/auto-mode-config)を参照してください。共有プロジェクト設定から読み込まれません | `{"soft_deny": ["$defaults", "Never run terraform apply"]}` |

176| `blockedMarketplaces` | （Managed 設定のみ）マーケットプレイスソースのブロックリスト。マーケットプレイス追加時およびプラグインのインストール、更新、リフレッシュ、自動更新時に適用されるため、ポリシーが設定される前に追加されたマーケットプレイスは使用できません。ブロックされたソースはダウンロード前にチェックされるため、ファイルシステムに触れることはありません。[Managed マーケットプレイス制限](/ja/plugin-marketplaces#managed-marketplace-restrictions)を参照してください | `[{ "source": "github", "repo": "untrusted/plugins" }]` |179| `blockedMarketplaces` | （Managed 設定のみ）マーケットプレイスソースのブロックリスト。マーケットプレイス追加時およびプラグインのインストール、更新、リフレッシュ、自動更新時に適用されるため、ポリシーが設定される前に追加されたマーケットプレイスは使用できません。ブロックされたソースはダウンロード前にチェックされるため、ファイルシステムに触れることはありません。[Managed マーケットプレイス制限](/ja/plugin-marketplaces#managed-marketplace-restrictions)を参照してください | `[{ "source": "github", "repo": "untrusted/plugins" }]` |

177| `channelsEnabled` | （Managed 設定のみ）Team および Enterprise ユーザーに対して[チャネル](/ja/channels)を許可します。未設定または `false` は、ユーザーが `--channels` に渡すものに関係なく、チャネルメッセージ配信をブロックします | `true` |180| `channelsEnabled` | （Managed 設定のみ）組織に対して[チャネル](/ja/channels)を許可します。Claude.ai Team および Enterprise プランでは、これが未設定または `false` の場合、チャネルはブロックされます。[Anthropic Console](/ja/authentication#claude-console-authentication)アカウントで API キー認証を使用している場合、チャネルはデフォルトで許可されます。ただし、組織が managed 設定をデプロイしている場合は、このキーを `true` に設定する必要があります | `true` |

178| `cleanupPeriodDays` | この期間より長く非アクティブなセッションは起動時に削除されます（デフォルト：30 日、最小 1）。`0` に設定するとバリデーションエラーで拒否されます。また、起動時に[孤立した subagent worktrees](/ja/worktrees#clean-up-worktrees)の自動削除の年齢カットオフも制御します。トランスクリプト書き込みを完全に無効にするには、[`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/ja/env-vars)環境変数を設定するか、非インタラクティブモード（`-p`）で `--no-session-persistence` フラグまたは `persistSession: false` SDK オプションを使用します。 | `20` |181| `cleanupPeriodDays` | この期間より長く非アクティブなセッションは起動時に削除されます（デフォルト：30 日、最小 1）。`0` に設定するとバリデーションエラーで拒否されます。また、起動時に[孤立した subagent worktrees](/ja/worktrees#clean-up-worktrees)の自動削除の年齢カットオフも制御します。トランスクリプト書き込みを完全に無効にするには、[`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/ja/env-vars)環境変数を設定するか、非インタラクティブモード（`-p`）で `--no-session-persistence` フラグまたは `persistSession: false` SDK オプションを使用します。 | `20` |

180| `defaultShell` | 入力ボックス `!` コマンドのデフォルトシェル。`"bash"`（デフォルト）または `"powershell"` を受け入れます。`"powershell"` を設定すると、インタラクティブ `!` コマンドが Windows 上の PowerShell を通じてルーティングされます。`CLAUDE_CODE_USE_POWERSHELL_TOOL=1` が必要です。[PowerShell ツール](/ja/tools-reference#powershell-tool)を参照してください | `"powershell"` |183| `defaultShell` | 入力ボックス `!` コマンドのデフォルトシェル。`"bash"`（デフォルト）または `"powershell"` を受け入れます。`"powershell"` を設定すると、インタラクティブ `!` コマンドが Windows 上の PowerShell を通じてルーティングされます。`CLAUDE_CODE_USE_POWERSHELL_TOOL=1` が必要です。[PowerShell ツール](/ja/tools-reference#powershell-tool)を参照してください | `"powershell"` |

183| `disableAutoMode` | [自動モード](/ja/permission-modes#eliminate-prompts-with-auto-mode)の有効化を防ぐために `"disable"` に設定します。`Shift+Tab` サイクルから `auto` を削除し、起動時に `--permission-mode auto` を拒否します。[managed 設定](/ja/permissions#managed-settings)で最も役立ちます。ユーザーはこれをオーバーライドできません | `"disable"` |186| `disableAutoMode` | [自動モード](/ja/permission-modes#eliminate-prompts-with-auto-mode)の有効化を防ぐために `"disable"` に設定します。`Shift+Tab` サイクルから `auto` を削除し、起動時に `--permission-mode auto` を拒否します。[managed 設定](/ja/permissions#managed-settings)で最も役立ちます。ユーザーはこれをオーバーライドできません | `"disable"` |

184| `disableDeepLinkRegistration` | Claude Code が起動時にオペレーティングシステムで `claude-cli://` プロトコルハンドラーを登録するのを防ぐために `"disable"` に設定します。[ディープリンク](/ja/deep-links)を使用すると、外部ツールは事前入力されたプロンプトで Claude Code セッションを開くことができます。プロトコルハンドラー登録が制限されているか、別途管理されている環境で役立ちます | `"disable"` |187| `disableDeepLinkRegistration` | Claude Code が起動時にオペレーティングシステムで `claude-cli://` プロトコルハンドラーを登録するのを防ぐために `"disable"` に設定します。[ディープリンク](/ja/deep-links)を使用すると、外部ツールは事前入力されたプロンプトで Claude Code セッションを開くことができます。プロトコルハンドラー登録が制限されているか、別途管理されている環境で役立ちます | `"disable"` |

189| `disableRemoteControl` | {/* min-version: 2.1.128 */}[リモートコントロール](/ja/remote-control)を無効にします：`claude remote-control`、`--remote-control` フラグ、自動開始、およびセッション内トグルをブロックします。通常は [managed 設定](/ja/permissions#managed-settings)に配置されます。デバイスごとの MDM 強制用ですが、任意のスコープから機能します。Claude Code v2.1.128 以降が必要です | `true` |

186| `disableSkillShellExecution` | [skills](/ja/skills) およびユーザー、プロジェクト、プラグイン、または追加ディレクトリソースからのカスタムコマンド内の `` !`...` `` および ` ```! ` ブロックのインラインシェル実行を無効にします。コマンドは実行される代わりに `[shell command execution disabled by policy]` に置き換えられます。バンドルされた skills および managed skills は影響を受けません。[managed 設定](/ja/permissions#managed-settings)で最も役立ちます。ユーザーはこれをオーバーライドできません | `true` |190| `disableSkillShellExecution` | [skills](/ja/skills) およびユーザー、プロジェクト、プラグイン、または追加ディレクトリソースからのカスタムコマンド内の `` !`...` `` および ` ```! ` ブロックのインラインシェル実行を無効にします。コマンドは実行される代わりに `[shell command execution disabled by policy]` に置き換えられます。バンドルされた skills および managed skills は影響を受けません。[managed 設定](/ja/permissions#managed-settings)で最も役立ちます。ユーザーはこれをオーバーライドできません | `true` |

187| `editorMode` | 入力プロンプトのキーバインディングモード：`"normal"` または `"vim"`。デフォルト：`"normal"`。`/config` に**エディターモード**として表示されます | `"vim"` |191| `editorMode` | 入力プロンプトのキーバインディングモード：`"normal"` または `"vim"`。デフォルト：`"normal"`。`/config` に**エディターモード**として表示されます | `"vim"` |

188| `effortLevel` | [努力レベル](/ja/model-config#adjust-effort-level)をセッション全体で永続化します。`"low"`、`"medium"`、`"high"`、または `"xhigh"` を受け入れます。これらの値のいずれかで `/effort` を実行すると自動的に書き込まれます。[努力レベルを調整](/ja/model-config#adjust-effort-level)でサポートされているモデルを参照してください | `"xhigh"` |192| `effortLevel` | [努力レベル](/ja/model-config#adjust-effort-level)をセッション全体で永続化します。`"low"`、`"medium"`、`"high"`、または `"xhigh"` を受け入れます。これらの値のいずれかで `/effort` を実行すると自動的に書き込まれます。[努力レベルを調整](/ja/model-config#adjust-effort-level)でサポートされているモデルを参照してください | `"xhigh"` |

550 },554 },

551 "extraKnownMarketplaces": {555 "extraKnownMarketplaces": {

552 "acme-tools": {556 "acme-tools": {

557 "source": {

553 "source": "github",558 "source": "github",

554 "repo": "acme-corp/claude-plugins"559 "repo": "acme-corp/claude-plugins"

555 }560 }

556 }561 }

562 }

557}563}

558```564```

559 565

568* **ローカル設定**（`.claude/settings.local.json`）：マシンごとのオーバーライド（コミットされない）574* **ローカル設定**（`.claude/settings.local.json`）：マシンごとのオーバーライド（コミットされない）

569* **Managed 設定**（`managed-settings.json`）：すべてのスコープでのインストールをブロックし、マーケットプレイスからプラグインを非表示にする組織全体のポリシーオーバーライド575* **Managed 設定**（`managed-settings.json`）：すべてのスコープでのインストールをブロックし、マーケットプレイスからプラグインを非表示にする組織全体のポリシーオーバーライド

570 576

577<Note>

578 プロジェクト設定はユーザー設定よりも優先されるため、`~/.claude/settings.json` でプラグインを `false` に設定しても、プロジェクトの `.claude/settings.json` が有効にするプラグインは無効になりません。プロジェクトで有効になっているプラグインをマシンでオプトアウトするには、代わりに `.claude/settings.local.json` で `false` に設定してください。

579

580 Managed 設定で強制的に有効にされたプラグインは、Managed 設定がローカル設定をオーバーライドするため、この方法では無効にできません。

581</Note>

582

571**例**：583**例**：

572 584

573```json theme={null}585```json theme={null}

659* managed 設定（`managed-settings.json`）でのみ利用可能671* managed 設定（`managed-settings.json`）でのみ利用可能

660* ユーザーまたはプロジェクト設定でオーバーライドできません（最高優先度）672* ユーザーまたはプロジェクト設定でオーバーライドできません（最高優先度）

661* ネットワーク/ファイルシステム操作の前に強制されます（ブロックされたソースは実行されません）673* ネットワーク/ファイルシステム操作の前に強制されます（ブロックされたソースは実行されません）

662* `hostPattern` を除き、ソース仕様に対して完全一致を使用します。`hostPattern` は正規表現マッチングを使用します674* `hostPattern` と `pathPattern` を除き、ソース仕様に対して完全一致を使用します。`hostPattern` と `pathPattern` は正規表現マッチングを使用します

663 675

664**ホワイトリスト動作**：676**ホワイトリスト動作**：

665 677

669 681

670**サポートされているすべてのソースタイプ**：682**サポートされているすべてのソースタイプ**：

671 683

672ホワイトリストは複数のマーケットプレイスソースタイプをサポートしています。ほとんどのソースは完全一致を使用しますが、`hostPattern` はマーケットプレイスホストに対して正規表現マッチングを使用します。684ホワイトリストは複数のマーケットプレイスソースタイプをサポートしています。ほとんどのソースは完全一致を使用しますが、`hostPattern` と `pathPattern` はそれぞれマーケットプレイスホストとファイルシステムパスに対して正規表現マッチングを使用します。

673 685

6741. **GitHub リポジトリ**：6861. **GitHub リポジトリ**：

675 687

749* `url`：URL からホスト名を抽出761* `url`：URL からホスト名を抽出

750* `npm`、`file`、`directory`：ホストパターンマッチングではサポートされていません762* `npm`、`file`、`directory`：ホストパターンマッチングではサポートされていません

751 763

7648. **パスパターンマッチング**：

765

766```json theme={null}

767{ "source": "pathPattern", "pathPattern": "^/opt/approved/" }

768{ "source": "pathPattern", "pathPattern": ".*" }

769```

770

771フィールド：`pathPattern`（必須：`file` および `directory` ソースの `path` フィールドに対してマッチする正規表現パターン）

772

773ネットワークソースの `hostPattern` 制限と並行して、ファイルシステムベースのマーケットプレイスを許可するには、パスパターンマッチングを使用します。すべてのローカルパスを許可するには `".*"` を設定するか、特定のディレクトリに制限するにはより狭いパターンを設定します。

774

752**構成例**：775**構成例**：

753 776

754例：特定のマーケットプレイスのみを許可：777例：特定のマーケットプレイスのみを許可：

sub-agents.md +37 −12

Details

51 </Tab>51 </Tab>

52 52

53 <Tab title="Plan">53 <Tab title="Plan">

54 [プランモード](/ja/common-workflows#use-plan-mode-for-safe-code-analysis)中にプランを提示する前にコンテキストを収集するために使用される研究エージェント。54 [プランモード](/ja/permission-modes#analyze-before-you-edit-with-plan-mode)中にプランを提示する前にコンテキストを収集するために使用される研究エージェント。

55 55

56 * **モデル**：メイン会話から継承56 * **モデル**：メイン会話から継承

57 * **ツール**：読み取り専用ツール（Write および Edit ツールへのアクセスは拒否）57 * **ツール**：読み取り専用ツール（Write および Edit ツールへのアクセスは拒否）

76 | エージェント | モデル | Claude が使用する場合 |76 | エージェント | モデル | Claude が使用する場合 |

77 | :---------------- | :----- | :--------------------------------- |77 | :---------------- | :----- | :--------------------------------- |

80 </Tab>80 </Tab>

81</Tabs>81</Tabs>

82 82

180 180

181**CLI で定義されたサブエージェント** は、Claude Code を起動するときに JSON として渡されます。これらはそのセッションのみに存在し、ディスクに保存されないため、クイックテストまたは自動化スクリプトに役立ちます。単一の `--agents` 呼び出しで複数のサブエージェントを定義できます：181**CLI で定義されたサブエージェント** は、Claude Code を起動するときに JSON として渡されます。これらはそのセッションのみに存在し、ディスクに保存されないため、クイックテストまたは自動化スクリプトに役立ちます。単一の `--agents` 呼び出しで複数のサブエージェントを定義できます：

182 182

183```bash theme={null}183<Tabs>

184claude --agents '{184 <Tab title="macOS, Linux, WSL">

185 ```bash theme={null}

186 claude --agents '{

185 "code-reviewer": {187 "code-reviewer": {

186 "description": "Expert code reviewer. Use proactively after code changes.",188 "description": "Expert code reviewer. Use proactively after code changes.",

187 "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",189 "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",

192 "description": "Debugging specialist for errors and test failures.",194 "description": "Debugging specialist for errors and test failures.",

193 "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."195 "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."

194 }196 }

195}'197 }'

196```198 ```

199 </Tab>

200

201 <Tab title="Windows PowerShell">

202 ```powershell theme={null}

203 claude --agents @'

204 {

205 "code-reviewer": {

206 "description": "Expert code reviewer. Use proactively after code changes.",

207 "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",

208 "tools": ["Read", "Grep", "Glob", "Bash"],

209 "model": "sonnet"

210 },

211 "debugger": {

212 "description": "Debugging specialist for errors and test failures.",

213 "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."

214 }

215 }

216 '@

217 ```

218 </Tab>

219</Tabs>

197 220

198`--agents` フラグは、ファイルベースのサブエージェントと同じ[フロントマター](#supported-frontmatter-fields)フィールドを持つ JSON を受け入れます：`description`、`prompt`、`tools`、`disallowedTools`、`model`、`permissionMode`、`mcpServers`、`hooks`、`maxTurns`、`skills`、`initialPrompt`、`memory`、`effort`、`background`、`isolation`、および `color`。システムプロンプトには `prompt` を使用します。これはファイルベースのサブエージェントの markdown 本体と同等です。221`--agents` フラグは、ファイルベースのサブエージェントと同じ[フロントマター](#supported-frontmatter-fields)フィールドを持つ JSON を受け入れます：`description`、`prompt`、`tools`、`disallowedTools`、`model`、`permissionMode`、`mcpServers`、`hooks`、`maxTurns`、`skills`、`initialPrompt`、`memory`、`effort`、`background`、`isolation`、および `color`。システムプロンプトには `prompt` を使用します。これはファイルベースのサブエージェントの markdown 本体と同等です。

199 222

212サブエージェントファイルは、YAML フロントマターを使用して設定を行い、その後に Markdown でシステムプロンプトを続けます：235サブエージェントファイルは、YAML フロントマターを使用して設定を行い、その後に Markdown でシステムプロンプトを続けます：

213 236

214<Note>237<Note>

215 サブエージェントはセッション開始時に読み込まれます。ファイルを手動で追加してサブエージェントを作成する場合は、セッションを再起動するか、`/agents` を使用してすぐに読み込みます。238 サブエージェントはセッション開始時に読み込まれます。ディスク上でサブエージェントファイルを直接追加または編集する場合は、セッションを再起動してそれを読み込みます。`/agents` インターフェースを通じて作成されたサブエージェントは、再起動なしで即座に有効になります。

216</Note>239</Note>

217 240

218```markdown theme={null}241```markdown theme={null}

250| `memory` | いいえ | [永続メモリスコープ](#enable-persistent-memory)：`user`、`project`、または `local`。クロスセッション学習を有効にします |273| `memory` | いいえ | [永続メモリスコープ](#enable-persistent-memory)：`user`、`project`、または `local`。クロスセッション学習を有効にします |

251| `background` | いいえ | `true` に設定して、このサブエージェントを常に[バックグラウンドタスク](#run-subagents-in-foreground-or-background)として実行します。デフォルト：`false` |274| `background` | いいえ | `true` に設定して、このサブエージェントを常に[バックグラウンドタスク](#run-subagents-in-foreground-or-background)として実行します。デフォルト：`false` |

252| `effort` | いいえ | このサブエージェントがアクティブな場合の努力レベル。セッション努力レベルをオーバーライドします。デフォルト：セッションから継承。オプション：`low`、`medium`、`high`、`xhigh`、`max`。利用可能なレベルはモデルに依存します |275| `effort` | いいえ | このサブエージェントがアクティブな場合の努力レベル。セッション努力レベルをオーバーライドします。デフォルト：セッションから継承。オプション：`low`、`medium`、`high`、`xhigh`、`max`。利用可能なレベルはモデルに依存します |

253| `isolation` | いいえ | `worktree` に設定して、サブエージェントを一時的な[git worktree](/ja/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees)で実行し、リポジトリの分離されたコピーを提供します。サブエージェントが変更を加えない場合、worktree は自動的にクリーンアップされます |276| `isolation` | いいえ | `worktree` に設定して、サブエージェントを一時的な[git worktree](/ja/worktrees)で実行し、リポジトリの分離されたコピーを提供します。サブエージェントが変更を加えない場合、worktree は自動的にクリーンアップされます |

254| `color` | いいえ | タスクリストとトランスクリプトでサブエージェントの表示色。`red`、`blue`、`green`、`yellow`、`purple`、`orange`、`pink`、または `cyan` を受け入れます |277| `color` | いいえ | タスクリストとトランスクリプトでサブエージェントの表示色。`red`、`blue`、`green`、`yellow`、`purple`、`orange`、`pink`、または `cyan` を受け入れます |

255| `initialPrompt` | いいえ | このエージェントがメインセッションエージェント（`--agent` または `agent` 設定を通じて）として実行される場合、最初のユーザーターンとして自動送信されます。[コマンド](/ja/commands)および[スキル](/ja/skills)が処理されます。ユーザーが提供するプロンプトの前に付加されます |278| `initialPrompt` | いいえ | このエージェントがメインセッションエージェント（`--agent` または `agent` 設定を通じて）として実行される場合、最初のユーザーターンとして自動送信されます。[コマンド](/ja/commands)および[スキル](/ja/skills)が処理されます。ユーザーが提供するプロンプトの前に付加されます |

256 279

375 398

376<Warning>399<Warning>

377 `bypassPermissions` は注意して使用してください。権限プロンプトをスキップし、サブエージェントが承認なしで操作を実行できるようにします。`.git`、`.claude`、`.vscode`、`.idea`、および `.husky` ディレクトリへの書き込みを含む、承認なしで操作を実行できるようにします。`/` や `/root` などのルートおよびホームディレクトリの削除は、サーキットブレーカーとしてプロンプトが表示されます。詳細については、[権限モード](/ja/permission-modes#skip-all-checks-with-bypasspermissions-mode)を参照してください。400 `bypassPermissions` は注意して使用してください。権限プロンプトをスキップし、サブエージェントが承認なしで操作を実行できるようにします。`.git`、`.claude`、`.vscode`、`.idea`、および `.husky` ディレクトリへの書き込みを含みます。`rm -rf /` などのルートおよびホームディレクトリの削除は、サーキットブレーカーとしてプロンプトが表示されます。詳細については、[権限モード](/ja/permission-modes#skip-all-checks-with-bypasspermissions-mode)を参照してください。

378</Warning>401</Warning>

379 402

380親が `bypassPermissions` または `acceptEdits` を使用する場合、これが優先され、オーバーライドできません。親が[自動モード](/ja/permission-modes#eliminate-prompts-with-auto-mode)を使用する場合、サブエージェントは自動モードを継承し、フロントマター内の `permissionMode` は無視されます：分類器は、親セッションと同じブロックおよび許可ルールを使用してサブエージェントのツール呼び出しを評価します。403親が `bypassPermissions` または `acceptEdits` を使用する場合、これが優先され、オーバーライドできません。親が[自動モード](/ja/permission-modes#eliminate-prompts-with-auto-mode)を使用する場合、サブエージェントは自動モードを継承し、フロントマター内の `permissionMode` は無視されます：分類器は、親セッションと同じブロックおよび許可ルールを使用してサブエージェントのツール呼び出しを評価します。

484exit 0507exit 0

485```508```

486 509

487完全な入力スキーマについては[Hook 入力](/ja/hooks#pretooluse-input)を参照し、終了コードが動作に与える影響については[終了コード](/ja/hooks#exit-code-output)を参照してください。510完全な入力スキーマについては[Hook 入力](/ja/hooks#pretooluse-input)を参照し、終了コードが動作に与える影響については[終了コード](/ja/hooks#exit-code-output)を参照してください。Windows では、PowerShell で hook スクリプトを記述し、[PowerShell で hooks を実行する](/ja/hooks#windows-powershell-tool)に示されているように hook エントリに `shell: powershell` を追加します。

488 511

489#### 特定のサブエージェントを無効にする512#### 特定のサブエージェントを無効にする

490 513

994exit 01017exit 0

995```1018```

996 1019

997スクリプトを実行可能にします：1020macOS と Linux では、スクリプトを実行可能にします：

998 1021

999```bash theme={null}1022```bash theme={null}

1000chmod +x ./scripts/validate-readonly-query.sh1023chmod +x ./scripts/validate-readonly-query.sh

1001```1024```

1002 1025

1003hook は stdin を通じて JSON を受け取り、Bash コマンドは `tool_input.command` にあります。終了コード 2 は操作をブロックし、エラーメッセージを Claude にフィードバックします。終了コードと[Hook 入力](/ja/hooks#pretooluse-input)の詳細については、[Hooks](/ja/hooks#exit-code-output)を参照してください。1026Windows では、検証スクリプトを PowerShell で記述し、hook エントリに `shell: powershell` を追加します。[PowerShell で hooks を実行する](/ja/hooks#windows-powershell-tool)を参照してください。

1027

1028hook は stdin を通じて JSON を受け取り、Bash コマンドは `tool_input.command` にあります。終了コード 2 は操作をブロックし、エラーメッセージを Claude にフィードバックします。終了コードと出力の詳細については[Hooks](/ja/hooks#exit-code-output)を参照し、完全な入力スキーマについては[Hook 入力](/ja/hooks#pretooluse-input)を参照してください。

1004 1029

1005## 次のステップ1030## 次のステップ

1006 1031

vs-code.md +23 −13

Details

95* **許可モード**：プロンプトボックスの下部のモード指示器をクリックしてモードを切り替えます。通常モードでは、Claude は各アクション前に許可を求めます。Plan モードでは、Claude は実行内容を説明し、変更を加える前に承認を待ちます。VS Code は自動的にプランをフルマークダウンドキュメントとして開き、Claude が開始する前にフィードバックを提供するためのインラインコメントを追加できます。自動受け入れモードでは、Claude は許可を求めずに編集を行います。VS Code 設定の `claudeCode.initialPermissionMode` でデフォルトを設定します。95* **許可モード**：プロンプトボックスの下部のモード指示器をクリックしてモードを切り替えます。通常モードでは、Claude は各アクション前に許可を求めます。Plan モードでは、Claude は実行内容を説明し、変更を加える前に承認を待ちます。VS Code は自動的にプランをフルマークダウンドキュメントとして開き、Claude が開始する前にフィードバックを提供するためのインラインコメントを追加できます。自動受け入れモードでは、Claude は許可を求めずに編集を行います。VS Code 設定の `claudeCode.initialPermissionMode` でデフォルトを設定します。

96* **コマンドメニュー**：`/` をクリックするか `/` と入力してコマンドメニューを開きます。オプションには、ファイルの添付、モデルの切り替え、拡張思考の切り替え、プラン使用状況の表示（`/usage`）、および [Remote Control](/ja/remote-control) セッションの開始（`/remote-control`）が含まれます。カスタマイズセクションは、MCP サーバー、hooks、メモリ、権限、プラグインへのアクセスを提供します。ターミナルアイコン付きのアイテムは統合ターミナルで開きます。96* **コマンドメニュー**：`/` をクリックするか `/` と入力してコマンドメニューを開きます。オプションには、ファイルの添付、モデルの切り替え、拡張思考の切り替え、プラン使用状況の表示（`/usage`）、および [Remote Control](/ja/remote-control) セッションの開始（`/remote-control`）が含まれます。カスタマイズセクションは、MCP サーバー、hooks、メモリ、権限、プラグインへのアクセスを提供します。ターミナルアイコン付きのアイテムは統合ターミナルで開きます。

97* **コンテキスト指示器**：プロンプトボックスは、Claude のコンテキストウィンドウをどの程度使用しているかを表示します。Claude は必要に応じて自動的にコンパクト化するか、`/compact` を手動で実行できます。97* **コンテキスト指示器**：プロンプトボックスは、Claude のコンテキストウィンドウをどの程度使用しているかを表示します。Claude は必要に応じて自動的にコンパクト化するか、`/compact` を手動で実行できます。

98* **拡張思考**：Claude が複雑な問題を推論するためにより多くの時間を費やすことができます。コマンドメニュー（`/`）を使用してオンに切り替えます。Claude の推論は会話に折りたたまれたブロックとして表示されます。ブロックをクリックして読むか、`Ctrl+O` を押してセッション内のすべての思考ブロックを展開または折りたたみます。詳細については、[拡張思考](/ja/common-workflows#use-extended-thinking-thinking-mode)を参照してください。98* **拡張思考**：Claude が複雑な問題を推論するためにより多くの時間を費やすことができます。コマンドメニュー（`/`）を使用してオンに切り替えます。Claude の推論は会話に折りたたまれたブロックとして表示されます。ブロックをクリックして読むか、`Ctrl+O` を押してセッション内のすべての思考ブロックを展開または折りたたみます。詳細については、[拡張思考](/ja/model-config#extended-thinking)を参照してください。

99* **複数行入力**：`Shift+Enter` を押して送信せずに新しい行を追加します。これは質問ダイアログの'その他'フリーテキスト入力でも機能します。99* **複数行入力**：`Shift+Enter` を押して送信せずに新しい行を追加します。これは質問ダイアログの'その他'フリーテキスト入力でも機能します。

100 100

101### ファイルとフォルダを参照する101### ファイルとフォルダを参照する

115 115

116### 過去の会話を再開する116### 過去の会話を再開する

117 117

118Claude Code パネルの上部の **Session history** ボタンをクリックして、会話履歴にアクセスします。キーワードで検索するか、時間（今日、昨日、過去 7 日間など）で参照できます。任意の会話をクリックして、完全なメッセージ履歴で再開します。新しいセッションは、最初のメッセージに基づいて AI が生成したタイトルを受け取ります。セッションの上にマウスを置くと、名前変更と削除アクションが表示されます。説明的なタイトルを付けるために名前を変更するか、リストから削除するために削除します。セッションの再開の詳細については、[一般的なワークフロー](/ja/common-workflows#resume-previous-conversations)を参照してください。118Claude Code パネルの上部の **Session history** ボタンをクリックして、会話履歴にアクセスします。キーワードで検索するか、時間（今日、昨日、過去 7 日間など）で参照できます。任意の会話をクリックして、完全なメッセージ履歴で再開します。新しいセッションは、最初のメッセージに基づいて AI が生成したタイトルを受け取ります。セッションの上にマウスを置くと、名前変更と削除アクションが表示されます。説明的なタイトルを付けるために名前を変更するか、リストから削除するために削除します。セッションの再開の詳細については、[セッションの管理](/ja/sessions)を参照してください。

119 119

120### Claude.ai からリモートセッションを再開する120### Claude.ai からリモートセッションを再開する

121 121

399claude --worktree feature-auth399claude --worktree feature-auth

400```400```

401 401

402各 worktree は git 履歴を共有しながら独立したファイル状態を保持します。これにより、異なるタスクで作業するときに Claude インスタンスが互いに干渉するのを防ぎます。詳細については、[Run parallel sessions with Git worktrees](/ja/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees) を参照してください。402各 worktree は git 履歴を共有しながら独立したファイル状態を保持します。これにより、異なるタスクで作業するときに Claude インスタンスが互いに干渉するのを防ぎます。詳細については、[Git worktrees で並列セッションを実行する](/ja/worktrees) を参照してください。

403 403

404## サードパーティプロバイダーを使用する404## サードパーティプロバイダーを使用する

405 405

460 460

461### 拡張機能がインストールされない461### 拡張機能がインストールされない

462 462

463* VS Code の互換バージョン（1.98.0 以上）があることを確認します。463* VS Code の互換バージョン（1.98.0 以上）があることを確認してください

464* VS Code に拡張機能をインストールする権限があることを確認します。464* VS Code に拡張機能をインストールする権限があることを確認してください

465* [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code) から直接インストールしてみてください。465* [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=anthropic.claude-code) から直接インストールしてみてください

466 466

467### Spark アイコンが表示されない467### Spark アイコンが表示されない

468 468

470 470

4711. **ファイルを開く**：アイコンはファイルを開く必要があります。フォルダを開いているだけでは不十分です。4711. **ファイルを開く**：アイコンはファイルを開く必要があります。フォルダを開いているだけでは不十分です。

4722. **VS Code バージョンを確認**：1.98.0 以上が必要です（Help → About）4722. **VS Code バージョンを確認**：1.98.0 以上が必要です（Help → About）

4733. **VS Code を再起動**：コマンドパレットから「Developer: Reload Window」を実行します。4733. **VS Code を再起動**：コマンドパレットから「Developer: Reload Window」を実行してください

4744. **競合する拡張機能を無効にする**：他の AI 拡張機能（Cline、Continue など）を一時的に無効にします。4744. **競合する拡張機能を無効にする**：他の AI 拡張機能（Cline、Continue など）を一時的に無効にしてください

4755. **ワークスペーストラストを確認**：拡張機能は制限モードでは機能しません。4755. **ワークスペーストラストを確認**：拡張機能は制限モードでは機能しません

476 476

477または、**ステータスバー**（右下隅）の「✱ Claude Code」をクリックします。これはファイルを開かなくても機能します。**コマンドパレット**（`Cmd+Shift+P` / `Ctrl+Shift+P`）を使用して「Claude Code」と入力することもできます。477または、**ステータスバー**（右下隅）の「✱ Claude Code」をクリックしてください。これはファイルを開かなくても機能します。**コマンドパレット**（`Cmd+Shift+P` / `Ctrl+Shift+P`）を使用して「Claude Code」と入力することもできます。

478

479### macOS で Cmd+Esc が機能しない

480

481macOS Tahoe 以降では、システムのゲームオーバーレイショートカットがデフォルトで `Cmd+Esc` にバインドされており、キープレスが VS Code に到達する前に傍受されます。ショートカットを解放するには：

482

4831. システム設定を開く

4842. キーボード、次にキーボードショートカット、次にゲームコントローラーに移動します

4853. ゲームオーバーレイチェックボックスをクリアします

486

487または、拡張機能を別のキーに再バインドしてください：VS Code の [キーボードショートカットエディタ](https://code.visualstudio.com/docs/configure/keybindings)（`Cmd+K Cmd+S`）を開き、`Claude Code: Focus input` を検索して、新しいバインディングを割り当ててください。

478 488

479### Claude Code が応答しない489### Claude Code が応答しない

480 490

481Claude Code がプロンプトに応答しない場合：491Claude Code がプロンプトに応答しない場合：

482 492

4831. **インターネット接続を確認**：安定したインターネット接続があることを確認します。4931. **インターネット接続を確認**：安定したインターネット接続があることを確認してください

4842. **新しい会話を開始**：新しい会話を開始して、問題が続くかどうかを確認します。4942. **新しい会話を開始**：新しい会話を開始して、問題が続くかどうかを確認してください

4853. **CLI を試す**：ターミナルから `claude` を実行して、より詳細なエラーメッセージが表示されるかどうかを確認します。4953. **CLI を試す**：ターミナルから `claude` を実行して、より詳細なエラーメッセージが表示されるかどうかを確認してください

486 496

487問題が続く場合は、エラーの詳細を含めて [GitHub で問題を報告](https://github.com/anthropics/claude-code/issues)してください。497問題が続く場合は、エラーの詳細を含めて [GitHub で問題を報告](https://github.com/anthropics/claude-code/issues)してください。

488 498

Documentation 2026-05-04 22:58 UTC to 2026-05-05 23:00 UTC