Claude Code サブエージェント: 何を節約し、何にコストがかかるか

サブエージェントは、Claude Code がセッション内で起動する別個の Claude ワーカーです。独自のコンテキストウィンドウ、システムプロンプト、ツールを持ち、そのウィンドウ内でツール呼び出しを行い、読み取り・検索・コマンド実行を行った後、最終的な回答だけを返します。Claude は必要に応じて、例えばコード検索が必要なときに組み込みの Explore サブエージェントへ委任することもあります。

つまりサブエージェントはコンテキストを節約しますが、必ずしもトークンを節約するわけではありません。読み取りがメイン会話に入らないため、会話は小さく保たれます。ただし、すべてのエージェントで処理されるトークン総量は増える可能性があります。各サブエージェントはそれぞれセットアップと探索にコストがかかり、同時に複数起動するとそのコストが掛け算になります。

サブエージェントが支払うもの

サブエージェントは、会話履歴や既に呼び出されたスキル、Claude が既に読んだファイルを持たず、Claude がタスクを引き継ぐために書くメッセージから開始します。各リクエストには以下が含まれます:

• →セッションより短い独自のシステムプロンプトと、使用可能なツール（MCP ツールを含む）
• →あなたの CLAUDE.md ファイルと git status のスナップショット。組み込みの Explore と Plan サブエージェントはこれらを省略してコストを抑えます。
• →タスクメッセージと、定義で事前ロードされるスキルの全文

その後、独自のエージェントループを実行します。各ツール呼び出しの結果、読み取ったファイル、コマンド出力はすべてコンテキストに追加され、次のステップでは増大したコンテキストが再送されます。検索が長くなるほど、このループのコストはセットアップコストを上回ります。

キャッシュはメインスレッドほど効果的ではありません。サブエージェントのプレフィックスは会話と異なるため、最初のリクエストはプロンプトキャッシュを利用できず、セットアップは毎回新たに処理されます。構築されたキャッシュはデフォルトで5分間保持され、サブスクリプションでメイン会話が1時間保持される場合でも同様です。subagentPromptCacheTtl 設定でキャッシュ有効期間を1時間に延長できますが、キャッシュ書き込みコストが上がります。

最終的に結果が返ります: サブエージェントの最終メッセージと、トークン数と所要時間を示す短いサマリが付随します。これが会話に組み込まれ、以降の各ターンで再送されるため、2行の判定だけを求めたサブエージェントは、フルレポートを求めたものよりメインスレッドのコストが低くなります。

節約できるもの

節約できるのは、サブエージェントが読み取り・実行したが会話に届かなかったすべての情報です。たとえば、ある関数を探すために開いた数十ファイルや、3つの失敗に伴う数千行のテスト出力などです。メインスレッドで実行した場合、これらはすべてコンテキストに残り、クリアまたは圧縮するまで各ターンで再送されます。プロンプトキャッシュは再読込みを割引料金で請求しますが、依然として上限にカウントされ、モデルが推論するウィンドウを圧迫します。

Claude Code のドキュメントでは、リサーチサブエージェントが約6,100トークン分のファイルを読み取り、メイン会話が受け取る結果は420トークンです。コンテキストは結果分だけ増加しました。読み取りはサブエージェントのウィンドウ内で支払われています。

したがって、サブエージェントが除外する情報が大きく、セッションに残りターンが多い場合に効果的で、タスクが小さいか、会話がすでに保持している情報を再読する必要がある場合は不利になります。

サブエージェントが効果的なケース

• →まだ知らないコードを探索する場合、読んだほとんどが無関係になることが多い。
• →詳細な操作のうち判定だけが必要な場合: 失敗部分だけに絞ったテスト実行、エラーだけのログ、ドキュメント1ページからの1つの回答。
• →長時間タスク。メインセッションの残りターンが多いほど、除外したトークンの価値が高まります。
• →並行する独立調査。全体の合計時間ではなく最も遅いものの時間で完了するため、時間は節約できますがトークンは節約できません。各エージェントはそれぞれセットアップコストを支払います。
• →検索、要約、チェック実行など、小型モデルが得意とする作業。

トークンを無駄にするケース

• →小規模で特定の変更。ファイルが既に分かっている場合、セットアップコストが置き換える探索コストを上回り、新しいサブエージェントはコンテキストを集める時間が必要です。
• →会話がすでに知っている情報に依存する作業。新しいサブエージェントは Claude が既に読んだファイルを再読します。頻繁なやり取りや、計画・実装・テストなどコンテキストを共有するフェーズはメイン会話に含めるべきです。
• →重複する並列エージェント。同じコアモジュールを必要とする3つのサブエージェントがそれぞれ読み取り、結果がすべて会話に入ります。
• →サブスクリプションで多数のエージェントを同時に使用する場合。各サブエージェントはメイン会話と同じプラン上限を使用し、Claude Code のドキュメントは同時実行がトークン使用量を掛け算にすることを明言しています。

委任は入れ子にすることも可能です。2026年9月時点で、サブエージェントは自分自身のサブエージェントを起動でき、デフォルトで会話から最大3層下まで、同時に最大20個まで実行できます。CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH を 1 に設定すると入れ子が無効になり、CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS で上限を変更できます。

同様の目的を持つツールが2つあります。/btw は会話に既にある情報から副質問に答え、ツールを使用せず、回答を履歴に残しません。/subtask はフォークを開始し、会話を継承しキャッシュを読み込むサブエージェントを作ります。ドキュメントでは、同じコンテキストが必要なタスクでは新規サブエージェントよりも安価とされていますが、フォークは会話と同等のサイズで開始します。

サブエージェントを安価なモデルで実行する

カスタムサブエージェントは、プロジェクトごとに .claude/agents/、すべてのプロジェクトに対しては ~/.claude/agents/ に配置する Markdown ファイルで、システムプロンプトの上に YAML フロントマターがあります。model フィールドには haiku、sonnet、opus、fable、claude-opus-5-5 のような完全なモデル ID、または inherit を指定できます。検索、要約、チェック実行を行うサブエージェントには model: haiku を追加してください。

Claude Code はサブエージェントのモデルを以下の順序で決定します: その呼び出しで Claude が指定したモデル、定義の model フィールド、CLAUDE_CODE_SUBAGENT_MODEL 環境変数、最後にメイン会話のモデル。この最後のステップにはコストが伴い、/model で Opus に切り替えると、モデルを継承しているすべてのサブエージェントも同様に切り替わります。

組み込みの Explore サブエージェントはもはや Haiku がデフォルトではありません。Claude Code v2.1.198 以降、セッションのモデルを継承し、Claude API では Opus に上限がかかります。探索コストを抑えるには、model: haiku を設定した Explore という名前のサブエージェントを作成してください。これにより組み込みのものを上書きできます。組み込みと異なり、omitClaudeMd: true を付けない限り CLAUDE.md ファイルを読み込みます。CLAUDE_CODE_SUBAGENT_MODEL だけでは Explore や Plan は変更されず、CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1（v2.1.257 以降）を追加するとそれらにも適用されます。

2026年9月時点で、Anthropic の API 料金表では Claude Haiku 4.5 が入力トークン 100 万件あたり $1、出力トークン 100 万件あたり $5 です。対して Sonnet 5 はそれぞれ $2 と $10、Opus 5.5 は $4 と $20 です。サブスクライバー向けのヘルプセンターでは、Opus は Sonnet の数倍、Sonnet は Haiku よりも高いコストになると記載されています。

1つの制限があります: サブエージェントのコンテキストウィンドウは使用モデルに依存し、Haiku 4.5 は 20 万トークン、Sonnet 5 と Opus 5.5 は 100 万トークンです。支出を制御するフィールドとして、maxTurns はサブエージェントが取れるエージェントターン数を上限し、Sonnet または Opus では effort: low が推論の努力度を下げますが、メインセッションには影響しません。

$/tasks

サブエージェントの消費量を確認する

合計を取得するには、すべてを合算するツールを使用してください:

• →/usage（Pro、Max、Team、Enterprise プラン）では、過去24時間または7日間の最近の使用量に占めるサブエージェントの割合を示します。d と w で過去24時間と7日間を切り替えます。ローカルセッション履歴を読み込むため、他のマシンや claude.ai は含まれず、Prompt cache (main) 行はメイン会話のみを対象とします。
• →スクリプトでは、usage ではなく total_cost_usd やモデル別内訳を参照してください。Agent SDK のドキュメントでは、usage はサブエージェントのリクエストを除外し、total_cost_usd と modelUsage がサブエージェントのリクエストも含むことが明示されています。
• →チーム向けには、OpenTelemetry のトークンとコストカウンタが各リクエストに query_source（サブエージェントリクエストの場合は subagent）と agent.name をタグ付けします。
• →各サブエージェントのトランスクリプト（読み取り・実行内容）は、デフォルトで ~/.claude/projects/{project}/{sessionId}/subagents/ に30日間保存されます。

$/usage

委任する前に

最も安価な探索は、実行しないことです。ファイルが分かっている場合は名前を指定し、広範な質問ではなく狭い質問をしてください。カスタムサブエージェントの description は短く保ちましょう。説明はメイン会話のコンテキストを消費しますが、サブエージェントのシステムプロンプトは実行時にのみロードされます。

探索部分に上限を設けたい場合、capsul は既にサインインしている Claude Code を操作し、リポジトリ全体ではなくタスクが要求するものだけを送信し、設定した予算で停止し、除外された内容を報告します。

$capsul ask 'why does the session expire early' --budget 3000