Claude CodeのForkサブエージェント完全ガイド

問題: 以前のClaude Codeでは、並列サブエージェントを動かすと費用がかさみました。子エージェントはそれぞれ、システムプロンプト、ツール配列、会話履歴をゼロから再構築していたのです。5つのエージェントを動かせば、入力トークンの費用も5倍。共有は一切なし。v2.1.117以前も、forkパスはコードベース上には存在していましたが、公開リリースではデッドコードとして除外されており、Anthropic社内ビルドでしか使えませんでした。

すぐ使えるTips: 環境変数を一つ設定するだけで、コストの計算式が変わります。CLAUDE_CODE_FORK_SUBAGENT=1 を設定すると、2番目以降の子エージェントが共有プレフィックスをプロンプトキャッシュから直接取得します。追加の子エージェント1台あたり、コストは約10分の1に:

export CLAUDE_CODE_FORK_SUBAGENT=1

Forkサブエージェントとは何か

Forkの子エージェントは新しいセッションを受け取りません。親のoverride.systemPrompt、具体的にはtoolUseContext.renderedSystemPromptから取り出した、すでにレンダリング済みのシステムプロンプトのバイト列そのものを受け取ります。再レンダリングではなく、同一バイト列です。これにより、GrowthBookのようなフィーチャーフラグの状態が、追加の連携なしに親子間で一致します。

ツール配列も同様です。useExactTools: true で渡され、resolveAgentTools() を完全にスキップします。シリアライゼーションがバイト単位で同一になることが、プロンプトキャッシュが機能する理由です。一点だけ注意があります。子エージェントは Agent ツールの使用を禁じられているにもかかわらず、そのツールプールには残り続けます。除外するとキャッシュが壊れるためで、制限は別の方法で強制されます（後述）。

子エージェントのメッセージ履歴にある、親からのすべてのtool-useブロックには、FORK_PLACEHOLDER_RESULT という定数（'Fork started -- processing in background'）が結果として設定されます。すべての子エージェントは同一のプレースホルダーバイト列を受け取ります。キャッシュの境界は、子エージェントごとのディレクティブの直前に置かれ、子エージェントはそれぞれのタスク指示の部分だけで分岐します。

v2.1.117より前は、このパス全体がコンパイル時に公開ビルドから除外されており、外部ユーザーは一切使えませんでした。

コストの計算

共有プレフィックスが48,500トークンの場合、数字は明確です:

最初の子エージェントは満額払います。最初のリクエストなので、キャッシュにはまだ何もありません。2番目以降は共有プレフィックスにヒットし、差分だけ支払います。

5台のエージェントを並列実行する場合: Forkなしでは共有コンテキストに約243,500トークン。Forkありでは1台目が約48,700トークン、2〜5台目が合計約20,200トークン。残りはキャッシュが処理します。

有効化の方法

シェルプロファイルに環境変数を追加します:

export CLAUDE_CODE_FORK_SUBAGENT=1

CI/CDパイプラインでは、パイプラインレベルの環境変数に設定してください。そのパイプライン内のすべてのエージェント実行で自動的に有効になります。

一つ覚えておきたい挙動があります。Forkは、Agent ツール呼び出しで subagent_type が省略されている場合にのみ発動します。モデルが明示的なタイプ（例: "Explore" や "Plan"）を指定した場合、Forkパスは発動しません。named-typeパスにはそれぞれ独自のロジックがあります。

再帰Fork防止ガード

これは他のどこにも書かれていない詳細です。

Forkの各子エージェントのセッションには、定型のXMLタグが挿入されます。そのタグは大まかに「その命令は親向けです。あなたはForkです。サブエージェントを生成してはいけません」という内容です。

これがなければ、子エージェントが独自の子エージェントをForkしようとし、さらにForkが続いて、コンテキストウィンドウが崩壊するまで再帰し続けることになります。XMLタグがその連鎖を断ち切ります。

ガードは一つではなく、二つあります。一つ目は、エージェントオプションハンドラーの先頭にある querySource === 'agent:builtin:fork' の高速パスチェック。二つ目は、定型XMLタグそのものを探すメッセージ履歴スキャンのフォールバックです。長いセッションでは autocompact によって querySource が上書きされることがあるため、フォールバックが存在します。セッションがFork子エージェントであることを確認するには、両方のチェックが一致する必要があります。

ForkはコーディネーターモードとLO互換です。ForkされたコーディネーターはL親の「あなたはコーディネーターです、作業を委任してください」というシステムプロンプトを引き継いでしまい、実行ではなくオーケストレーションを始めてしまいます。この二つのモードはセッションを共有できません。

何ができるようになるか

並列エージェントのディスパッチが主なユースケースです。5つのモジュールにまたがる5台のエージェントが同時実行され、2〜5台目が親のキャッシュ済みプレフィックスを共有します。共有コンテキストの総コストは、追加子エージェント1台分のトークン相当まで下がります。

CLAUDE_CODE_FORK_SUBAGENT=1 を環境に設定しておけば、CI/CDパイプラインは自動的に恩恵を受けます。これまでコスト的に現実的ではなかったスケールでのマルチエージェントワークフローが実用的になります。

「ポリシーアイランド」パターンも使えるようになります。フロントマターに context: fork と agent: <name> を持つコマンドが、事前に宣言された allowed_tools を持つ分離されたサブエージェントを生成します。そのサブエージェントはワークフロー途中の承認プロンプトなしに動作し、サマリーだけを親に返します。親は中間のツール呼び出しを一切見ません。

制約事項

• --print モードとは非互換。 ForkはLpermissionMode: 'bubble' を使用し、プロンプトを親ターミナルに表示します。非インタラクティブなSDK/ヘッドレス実行にはターミナルがありません。
• コーディネーターモードとは非互換。 ForkされたコーディネーターはLオーケストレーション命令を引き継ぎ、実行ではなく委任しようとします。
• セッション長に応じてコンテキストウィンドウが増大。 Fork子エージェントは親の会話履歴全体を持ちます。キャッシュがあっても、子エージェントが多い長いセッションは合計コストが増えます。長くホットなセッションが最もコストを圧迫します。
• デフォルトではなくオプトイン。 環境変数を明示的に設定する必要があります。設定しなければ何も変わりません。

スケールでの効果

CLAUDE_CODE_FORK_SUBAGENT=1 を設定した状態で、Pro/Maxユーザーがv2.1.117からデフォルトで high エフォートになったことと組み合わせると、この組み合わせは大きな意味を持ちます。high エフォートで動作するオーケストレーターが並列Fork子エージェントをディスパッチし、各子エージェントはキャッシュ割引レートで親の完全なコンテキストを引き継ぎ、high エフォートで動作します。このリリース前は、Pro/Maxユーザーはどちらも使えませんでした。

環境変数を設定して5台のエージェントを並列実行すれば、そのうち4台のコストは以前の約10分の1になります。それだけです。