SubagentHandbackとは — auto modeでサブエージェントの最終報告を審査する仕組み

SubagentHandbackは、サブエージェントの最終報告を、その結果を受け取る会話へ届けるための組み込みツールです。auto modeのときだけ、しかもAgentツールがローカルで動かすサブエージェント(フォークを除く)にだけ付きます。報告はこのツールを通るので、届く前に分類器が中身を審査できます。Claude Code v2.1.271以降が前提です。

SubagentHandbackとは何をするツールか

ツール一覧では、SubagentHandbackは「サブエージェントの最終報告を、そのサブエージェントの結果を受け取る会話に届ける」ツールと定義されています。権限確認の列は「No」で、呼び出しごとに承認を求められる種類のツールではありません。

ツール表の定義文は「受け取る会話」とだけ書かれ、入れ子での届き先はSubagentHandbackの項に書かれていません。サブエージェントがさらにサブエージェントを起動する構成で使うなら、実際の届き方を試してから前提に組み込む選択肢があります。

付与される条件

ツール表に書かれた条件は3つです。

使える面は、ターミナルのCLI、IDE拡張機能、クラウドセッション、Agent SDKの4つです。

フォークは会話全体を引き継ぎ、メイン会話とまったく同じツール一式を受け取ります。サブエージェント向けの絞り込みも通りません。バックグラウンドで動く点は通常のサブエージェントと同じですが、権限確認はターミナルに表示されます。v2.1.285以降、フォークはプランモードやdontAskモードも含め、親の権限モードのまま動きます。

auto modeでない会話では、サブエージェントの報告は従来どおり最後のメッセージとして返ります。v2.1.289のclaude --helpには、--permission-modeの選択肢が6つ出ます。acceptEdits、auto、bypassPermissions、manual、dontAsk、planです。このうちSubagentHandbackが付くのはautoだけです。

toolsやdisallowedToolsでは外せない

SubagentHandbackには、サブエージェント定義の側から外せないという癖があります。Agentツールの仕様では、条件が揃ったとき、Claude Codeはtoolsに書き忘れていても、disallowedToolsに書いていても、このツールをサブエージェントに付けます。

読み取り専用の調査役を定義した例です。

---
name: code-scout
description: コードを読んで構造を報告する調査役
tools: Read, Grep, Glob
disallowedTools: SubagentHandback
---
リポジトリを読み、見つけた構造を簡潔に報告してください。

toolsを3つに絞り、disallowedToolsでも名指ししています。それでもauto modeで、ローカルで動く非フォークのサブエージェントとして起動されれば、SubagentHandbackは付きます。ほかのツールはdisallowedToolsが優先されるので、この扱いは例外です。

一方で、サブエージェント向けに使えるツールの範囲という上限は守られます。サブエージェントで使えないツールは、toolsに書いても付与されません。該当するのは次の6つです。

• AskUserQuestion:質問を投げる
• EndConversation:メイン会話しか終えられない
• EnterPlanMode:プランモードに入る
• ScheduleWakeup:時刻を指定して再開する
• WaitForMcpServers:MCPサーバーの接続を待つ
• Workflow

ExitPlanModeはpermissionModeがplanのときだけ使え、Agentは入れ子の深さの上限に達したサブエージェントから外れます。

報告がこのツールを通ることで分類器の審査が成り立つので、定義側から外せない扱いになっていると考えられます。

バックグラウンド実行でも残る

サブエージェントは、既定ではバックグラウンドで動きます。バックグラウンドのサブエージェントは、組み込みツールが絞られます。MCPツールはすべて残り、組み込みツールで残るのは次のものだけです。

• ファイル操作系:Read、Grep、Glob、LSP、Edit、Write、NotebookEdit
• 実行系:Bash、PowerShell、Monitor、TaskStop
• Web系:WebFetch、WebSearch
• そのほか:TodoWrite、Skill、ToolSearch、EnterWorktree、ExitWorktree、SendMessage、Artifact

一覧にない組み込みツールは、継承した分もtoolsに書いた分も、バックグラウンドでは取り除かれます。同じ定義がフォアグラウンドとバックグラウンドで別のツールに解決されるのはこのためです。toolsの全項目がどれにも合わないと、エラーになってサブエージェントが起動しないこともあります。

この一覧に加えて、SubagentHandbackも残ります。「報告にこのツールを使うサブエージェント」に限って残る、という書き方です。

確認間隔の設定などバックグラウンド固有の挙動はClaude Codeでサブエージェントの確認間隔を設定するにまとめています。

審査の結果、報告はどうなるか

auto modeのサブエージェントは、分類器が3か所で見ます。SubagentHandbackが関わるのは3つ目だけです。

分類器とは別に、返ってきた報告そのものを走査して先頭に注記を付ける仕組みもあります。こちらはサブエージェント出力スキャンで扱っています。

審査の実行経路は、環境変数CLAUDE_CODE_AUTO_MODE_SERVERを0にするとサーバーでなくClaude Code自身の分類器リクエストに変わります。設定の意味はCLAUDE_CODE_AUTO_MODE_SERVERを参照してください。

報告経路の変化(バージョン別)

サブエージェントの報告と権限確認の経路は、次の3つのバージョンで変わっています。

auto modeでバックグラウンドのサブエージェントを回すなら、この3つが揃っているかで挙動が変わります。

サブエージェントの起動そのものは、権限確認の対象になりません。確認の対象は、起動後のサブエージェント自身のツール呼び出しです。フォアグラウンドなら、呼び出しの瞬間にメイン会話と同じ確認が出ます。auto modeの規則を調整したい場合の手段はAuto modeルールを編集するで扱っています。

SubagentHandbackが付かないときの切り分け

報告に警告が一度も付かない、あるいは定義どおりの絞り込みが効いていないように見えるときは、次の順にたどると原因を絞れます。

バージョンは次のコマンドで確かめられます。

claude --version

v2.1.289では、出力は2.1.289 (Claude Code)の1行です。

既定でauto modeになる条件はv2.1.284のリリースノートにあります。v2.1.283以降は、対話型のターミナルとVS Codeのセッションで、auto modeが組み込みの開始モードです。それより前のバージョンでは、Pro、Max、Teamプランだけがそうでした。

付与を止めたいときの手段

ツール名は、権限ルールやフックのマッチャー、サブエージェントのツール一覧に書く文字列として使えます。ただしtoolsとdisallowedToolsは、このツールには効きません。付与は権限モードで決まるので、止める手段は、その会話をauto mode以外で動かすことです。

終了時の審査はauto modeの仕組みなので、auto以外のモードでは報告に警告や注意も付きません。

設計への影響

サブエージェントを多用する運用では、次の点が変わります。

• 報告は審査を通ってから届くので、報告に警告や注意が付く場面が生じる
• 読み取り専用に絞ったサブエージェントでも、報告用のツールだけは付く
• サブエージェントのモデルを固定する設定や配分設計(モデル配分設計)とは独立した仕組みで、審査はサブエージェントのモデルではなく分類器が行う

サブエージェントを並列で使う全体像はTaskツールで作る並列開発パターンが詳しく、SubagentHandbackはそのうちの「結果を返す段階」にだけ関わります。

まとめ

権限を絞った読み取り専用のサブエージェントでも、auto modeなら報告は審査を通ります。サブエージェントの結果を受けて次の操作へ進む自動化では、先頭に警告や注意が付いた報告が返る場合を、分岐として想定しておく選択肢があります。