🤖

Claude Code サブエージェントの歩き方 — Explore が read-only な理由と切替の仕組み

に公開
AI
Claude
Claude Code
subagent
tech

本記事の位置づけ：【必読】Claude マルチエージェントの初期設定はAgent Teams（複数の Claude Code インスタンスをチームとして動かす機能）を扱う マルチエージェント編 でした。本記事はその姉妹記事として、Agent Teams より一段下のレイヤーである サブエージェント（メインエージェントが委任する単一の作業者）にフォーカスします。

なぜ「Explore は read-only でした。general-purpose に切り替えて再起動します」と出るのか？

ある日サブエージェントを使った作業中、メインエージェントから次のメッセージが返ってきました。

Explore は read-only でした。general-purpose に切り替えて再起動します。

「再起動」と聞くとエラーや障害を連想しますが、これはサブエージェントの権限差による正常な軌道修正です。本記事では、

  • Claude Code のサブエージェントにはどんなタイプがあるのか
  • それぞれの ツール権限の違い
  • なぜ「最初から general-purpose にしないのか」
  • 切替が起きないようにする呼び出し方

を実例ベースで整理します。

サブエージェントとは？

メインのClaude Codeエージェントが、特定のタスクを別インスタンスに委任して実行させる仕組みです。Agent ツール（旧称 Task）から呼び出されます。

  • 目的: 調査・並列処理・長い検索結果の隔離など、メインのコンテキストを汚さずに処理を進めたい場面で使う
  • 特徴: 委任されたサブエージェントは独立した文脈で動き、最終結果だけをメインに返す
  • Agent Teams との違い: Agent Teams は複数の Claude Code インスタンスが互いに通信する協調モデル。サブエージェントはメインに結果だけ返すシンプルな委任モデル。詳細は マルチエージェント編 の比較表を参照。

【2026-06追記】サブエージェントが自身のサブエージェントを生成可能に（v2.1.172・最大5階層）

2026年6月10日（PT）/ 11日（JST）の Claude Code v2.1.172 で、サブエージェントの仕組みに大きな拡張が入りました。

Sub-agents can now spawn their own sub-agents (up to 5 levels deep)（公式 changelog）

これまでサブエージェントは「メインが委任した単一の作業者」で、自分の下にさらにサブエージェントを持つことはできませんでした。v2.1.172 以降は、サブエージェント自身が Agent ツールでさらに下位のサブエージェントを呼び出せるようになり、委任の階層を 最大5階層まで深くできます。

v2.1.172 より前 v2.1.172 以降
委任の深さ メイン → サブ（1段のみ） メイン → サブ → サブ…（最大5階層）
向く使い方 単発の調査・処理 大きなタスクを「親サブが小タスクに再分割し、各子サブへ」と階層的に展開

Dynamic Workflows との関係（横の並列 × 縦の階層）

混同しやすいのが、Dynamic Workflows の「最大1,000サブエージェントを並列ファンアウト」という数字との関係です。両者は別の軸を指しています。

  • Dynamic Workflows の最大1,000: 1回のワークフローで横方向に同時起動できる総数の上限（広く・浅く）
  • v2.1.172 の最大5階層: 縦方向の入れ子（再帰委任）の深さの上限（深く）

つまり「横（並列数）× 縦（階層の深さ）」の2軸で捉えると整理できます。深い階層で再帰的にタスクを分割しつつ、各段で並列に広げる、という構成が可能になりました。

ただし注意も増えます。メインを Fable 5 にしたら子サブエージェントが全部 Fable 5 で立ち上がった事例のように、階層が深く・並列が広いほど、トークンとレート上限の消費は急増します。各サブエージェントのモデルを明示指定して一段下げる（機械的な大量処理は Sonnet など）といったコスト設計が、これまで以上に重要になります。

【2026-07追記】v2.1.218 → v2.1.219: ネスト生成のデフォルトが「無効」→「深度3まで許可」に

v2.1.172 で「サブエージェントが自身のサブエージェントを生成できる（最大5階層）」機能が入りましたが、その後2バージョンでデフォルトの挙動が2段階で調整されています。

バージョン 変更内容
v2.1.172 サブエージェントのネスト生成が可能に（最大5階層まで）
v2.1.218（2026-07-22 PT） デフォルトでネスト生成を無効化（暴走防止）。深いネストを使うには CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH で明示的に許可する必要があった
v2.1.219（2026-07-24 PT） デフォルトを「深度3まで許可」に緩和（旧: 実質1）。CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1 を設定するとネスト生成を無効化できる

公式changelogの原文は以下の通りです。

v2.1.218: Changed subagents to no longer spawn nested subagents by default; set CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH to allow deeper nesting

v2.1.219: Subagents can now spawn nested subagents up to depth 3 by default (was 1); set CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1 to disable nesting

つまり「最大5階層まで生成できる」という上限そのものは v2.1.172 から変わっていませんが、何も設定しない場合にどこまで自動でネストするかというデフォルト値が、v2.1.218 でいったん絞られ、v2.1.219 で「3階層までは自動OK」に戻された、という経緯です。5階層フルに使いたい場合は、引き続き CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH で明示的に上限を引き上げる必要があります。

なお v2.1.219 では、これとは別に stream-json 出力でのネストサブエージェントのフォワーディング（--forward-subagent-text 指定時に depth-2 以降のサブエージェントのテキスト/thinkingも出力に含まれる）も追加されています。こちらは「生成できる深さ」ではなく「出力に何が見えるか」の話で、混同しないよう注意してください。

【2026-06追記】v2.1.178: auto モードがサブエージェントの起動を「起動前」に評価

2026年6月15日（PT）の Claude Code v2.1.178 で、本記事のテーマ（サブエージェントの権限・安全）に直結する重要な変更が入りました。

Improved auto mode: subagent spawns are now evaluated by the classifier before launch（公式 changelog）

auto モードにおいて、サブエージェントの起動が「起動前」に分類器（classifier）で評価されるようになりました。これにより、サブエージェントがレビューを経ずにブロック対象のアクションを要求できてしまう抜け穴が解消されました。

それまで（auto モード）は、メインの判断を十分経ずに起動したサブエージェントが、結果的に許可されていないツール/アクションを要求できる余地がありました。v2.1.178 以降は起動前に評価が挟まるため、「読み取り専用に絞ったつもりのサブエージェントが、いつの間にか書き込み系を実行する」といった事故を、起動段階で防ぎやすくなります。本記事で扱う「サブエージェントを read-only に切り替える」運用とも相性がよく、auto モードでの安全性が一段強化された形です。

あわせて v2.1.178 では、権限ルールに Agent(model:opus) のようなツールパラメータマッチング構文も追加され、サブエージェントのモデル指定単位でのブロック（例: Opus サブエージェントの起動を禁止）が可能になりました（→ Claude Code バージョン履歴まとめ 参照）。

サブエージェントのタイプと権限差

サブエージェントは複数のタイプを持ち、タイプごとに使えるツールが定義されています。Claude Code 標準で用意されている主要タイプは以下です。

タイプ 主な用途 利用可能ツール 書き込み系 (Edit / Write / NotebookEdit)
Explore 高速な読み取り専用検索（ファイル探索・grep・WebFetch） Glob, Grep, Read, WebFetch, WebSearch ほか ❌
general-purpose 汎用、多段階タスク全般 ほぼ全ツール（書き込み系を含む） ✅
Plan 実装プランの作成・アーキテクチャ検討 読み取り系＋分析、書き込み系は除外 ❌
claude（無名デフォルト） 何でも 全ツール ✅
statusline-setup ステータスライン設定の編集 Read, Edit のみ ✅（限定的）

ポイントは、Explore と Plan は意図的に read-only として設計されていることです。Edit / Write / NotebookEdit といったファイル書き込み系ツールがそもそも使えないようになっています。

エピソード：実際に切替が起きた瞬間の解読

冒頭のメッセージをもう一度見てみます。

Explore は read-only でした。general-purpose に切り替えて再起動します。

このメッセージは、メインエージェントの内部で起きた次の流れを言語化したものです。

1. メインが「これは調査タスク」と判断
   ↓
2. Agent ツールで Explore に委任
   ↓
3. Explore が処理を進めるうち、ファイル編集が必要だと判明
   ↓
4. Explore は Edit / Write を持っていない → 詰む
   ↓
5. Explore を終了し、同じタスクを general-purpose に委任し直す
   ↓
6. general-purpose は書き込み系を持っているので、続行できる

つまり、メインの委任先の選定がやや読み違えだったため、軌道修正をしているのです。エラーや障害ではありません。

なぜ「最初から general-purpose」にしないのか？

「面倒なので全部 general-purpose でいい」と思いたくなりますが、Explore が独立して存在するのには理由があります。

  1. コンテキスト保護: Explore は「結果の抜粋だけを返す」設計のため、検索ヒット行を大量にメインへ持ち帰らない。文脈を節約できる。
  2. 誤った変更の防止: 調査タスクのつもりが、勝手にファイルを書き換えてしまうと困る。read-only にすることで事故を物理的に防ぐ。
  3. 判断の高速化: Explore は読み取り専用に特化しているため、思考分岐が少なく短い時間で結果が返る。

トレードオフは明白で、「書き込みが本当に必要なのに Explore に投げてしまった」ケースで切替コストが発生します。

切替が起きるとどれだけ無駄になる？

主な無駄は以下の2点です。

種類 内容
トークン消費 Explore に渡したシステムプロンプト＋途中まで進めた調査結果が、丸ごと無駄になる
時間 別エージェントとして再起動するため、起動オーバーヘッドが追加でかかる

切替によってExplore で得た知見はそのまま引き継がれない点に注意してください。general-purpose は最初からやり直します。

頻発するなら: 同じパターンで切替が何度も起きるなら、メインエージェントが委任時の判断を学ぶよりも、ユーザーが明示的に指示する方が確実です（後述）。

切替を防ぐ：最初から正しいタイプを指名する

メインエージェントの委任先選定は、タスクの記述から推測されます。曖昧な指示はExplore に振られやすいため、書き込みが発生し得るタスクではタイプを明示するのが有効です。

NG例（Exploreに振られやすい）

「コードベースから ◯◯ の箇所を探して直して」

「探して」で Explore 寄りに判断されるリスクがあります。

OK例（general-purpose を明示）

「コードベースから ◯◯ の箇所を探して直して。書き込みが必要なので general-purpose で進めて」

明示することで、メインは最初から general-purpose に委任します。

純粋な調査だけのときは Explore を明示

逆に、本当に読み取りしかしないことを保証したいタスクでは Explore を明示すると、誤って書き換えられる事故を防げます。

「設定ファイル群を read-only で全部探索して、設定キーの一覧を返して。Explore で」

サブエージェント vs Agent Teams：どっちを使うべき？

姉妹記事の マルチエージェント編 で扱う Agent Teams と、本記事のサブエージェントは異なる場面で使い分けます。

観点 サブエージェント Agent Teams
通信モデル メインに結果を返すだけ メンバー同士で双方向
起動コスト 低い（軽量） 高い（独立インスタンス）
最適な用途 集中型の単発タスク（調査・特定処理） 議論・協働が必要な複雑タスク
主な切替パターン Explore ↔ general-purpose リーダー ↔ チームメイト
設定の必要性 不要（標準機能） CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 で有効化

経験則として、「メインがコンテキストを汚さずに調査・処理を済ませたい」だけならサブエージェントで十分です。複数視点での議論・並列協調が要るときに Agent Teamsへ進む、という順序がおすすめです。

まとめ

  • 「Explore は read-only でした。general-purpose に切り替えて再起動します」はエラーではなく軌道修正
  • サブエージェントには read-only 系（Explore / Plan） と 書き込み可（general-purpose / claude） がある
  • 権限分離はコンテキスト保護と事故防止のための意図的な設計
  • 切替を防ぐには書き込みが要るときは general-purpose を明示、純粋な調査では Explore を明示
  • 複数エージェントが協調する場面が必要になったら マルチエージェント編 の Agent Teams へステップアップ

関連記事

GitHubで編集を提案

Discussion