SubagentHandbackとは — auto modeでサブエージェントの最終報告を審査する仕組み
auto modeのときだけサブエージェントに付くSubagentHandbackツールの役割、付与される条件、toolsやdisallowedToolsで外せない理由、v2.1.271以降の要件を解説します。
SubagentHandbackは、サブエージェントの最終報告を、その結果を受け取る会話へ届けるための組み込みツールです。auto modeのときだけ、しかもAgentツールがローカルで動かすサブエージェント(フォークを除く)にだけ付きます。報告はこのツールを通るので、届く前に分類器が中身を審査できます。Claude Code v2.1.271以降が前提です。
SubagentHandbackとは何をするツールか
ツール一覧では、SubagentHandbackは「サブエージェントの最終報告を、そのサブエージェントの結果を受け取る会話に届ける」ツールと定義されています。権限確認の列は「No」で、呼び出しごとに承認を求められる種類のツールではありません。
従来のサブエージェントは、最後に返したメッセージがそのまま親の会話に渡っていました。auto modeでは、v2.1.271の変更でここが変わっています。サブエージェントは専用の受け渡し呼び出しで呼び出し元へ報告し、その呼び出しを安全性の分類器が審査します。以前は最後のメッセージを、渡ったあとで審査する形でした。
定義の文言は「受け取る会話」で、メイン会話と限定していません。ただし、サブエージェントがさらにサブエージェントを起動する構成で報告がどこへ届くかは、ツール表にもAgentツールの説明にも記述がありません。ここでは宛先を断定せず、定義上の文言だけを押さえておきます。
付与される条件
ツール表に書かれた条件は3つです。
| 条件 | 内容 |
|---|---|
| 権限モード | 内容auto modeであること |
| サブエージェントの種類 | 内容Agentツールがローカルで動かすもの。フォークは対象外 |
| バージョン | 内容Claude Code v2.1.271以降 |
使える面は、ターミナルのCLI、IDE拡張機能、クラウドセッション、Agent SDKの4つです。
フォークは会話全体を引き継ぎ、メイン会話とまったく同じツール一式を受け取ります。サブエージェント向けの絞り込みも通りません。バックグラウンドで動く点は通常のサブエージェントと同じですが、権限確認はターミナルに表示されます。
auto modeでない会話では、サブエージェントの報告は従来どおり最後のメッセージとして返ります。手動確認のモードやacceptEditsでは、このツールは付きません。
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に書いても付与されません。該当するのは、質問を投げるAskUserQuestion、メイン会話しか終えられないEndConversation、プランモードに入るEnterPlanMode、時刻指定で再開するScheduleWakeup、MCPサーバーの接続を待つWaitForMcpServers、Workflowです。ExitPlanModeはpermissionModeがplanのときだけ使え、Agentは入れ子の深さの上限に達したサブエージェントから外れます。
例外が置かれた理由は説明されていません。報告がこのツールを通ることで分類器の審査が成り立つため、定義側で外せない扱いなのだろうと推測できますが、確認できた事実ではありません。
通常のツールとSubagentHandbackで、絞り込みの効き方を並べると次のようになります。
| 絞り込み | 通常のツール | SubagentHandback |
|---|---|---|
toolsに書かない | 通常のツール付与されない | SubagentHandback条件が揃えば付く |
disallowedToolsに書く | 通常のツール外れる(両方に書けば外れる) | SubagentHandback外れずに付く |
| サブエージェントで使えないツールの除外 | 通常のツールtoolsに書いても付かない | SubagentHandback対象外(条件が揃えば付く) |
| バックグラウンド実行の絞り込み | 通常のツール一覧にないものは除去される | SubagentHandback報告に使うサブエージェントには残る |
disallowedToolsとtoolsの両方を書いた通常のツールは、disallowedToolsが優先されて外れます。SubagentHandbackだけが、この優先順位の外に置かれています。
バックグラウンド実行でも残る
サブエージェントは、既定ではバックグラウンドで動きます。バックグラウンドのサブエージェントは、組み込みツールが絞られます。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も残ります。「報告にこのツールを使うサブエージェント」に限って残る、という書き方です。つまり、バックグラウンドの絞り込みを通ったあとでも、auto modeなら報告の経路は維持されます。
フォアグラウンドとバックグラウンドで同じ定義が別のツールに解決される点は、以前から変わりません。確認間隔の設定などバックグラウンド固有の挙動はClaude Codeでサブエージェントの確認間隔を設定するにまとめています。
審査の結果、報告はどうなるか
auto modeのサブエージェントは、分類器が3か所で見ます。SubagentHandbackが関わるのは3つ目だけです。
| 審査の時点 | 対象 | 結果 |
|---|---|---|
| 起動前 | 対象親が渡す依頼文 | 結果危険に見える依頼は、起動の時点でブロックされる |
| 実行中 | 対象サブエージェントの各操作 | 結果親のセッションと同じ規則で判定される |
| 終了時 | 対象作業内容と最終報告 | 結果親が読む前に審査され、問題があっても報告は届く(警告付き) |
起動前の審査だけが、サブエージェントそのものを止めます。終了時の審査は止める仕組みではなく、親が報告を読む前に、警告か注意を先頭へ添える仕組みです。
終了時の審査の結果ごとの扱いは次のとおりです。
| 審査の状況 | 親に届く報告 |
|---|---|
| 問題なし | 親に届く報告そのまま届く |
| 分類器が作業または報告に問題を検出 | 親に届く報告届くが、先頭にセキュリティ警告が付く |
| 別のAPI安全チェックが審査を拒否 | 親に届く報告届くが、先頭にセキュリティ警告が付く |
| 分類器が審査に使えない | 親に届く報告届くが、「行動前にサブエージェントの作業を確認してください」という注意が付く |
報告が握りつぶされることはなく、届いたうえで警告か注意が付く設計です。
報告経路の変化(バージョン別)
サブエージェントの報告と権限確認の経路は、次の2つのバージョンで変わっています。
| バージョン | 変更内容 |
|---|---|
| v2.1.186 | 変更内容バックグラウンドのサブエージェントの権限確認が、メインセッションに表示されるようになった。以前は、確認が必要な呼び出しは自動で拒否され、そのツールなしで続行していた |
| v2.1.271 | 変更内容auto modeで、サブエージェントが専用の受け渡し呼び出しで報告し、それを分類器が審査する形になった。以前は、最後のメッセージを渡ったあとで審査していた |
v2.1.186は「実行中の操作」の扱い、v2.1.271は「終了時の報告」の扱いを変えた版です。auto modeでバックグラウンドのサブエージェントを回すなら、この2つが揃っているかで挙動が変わります。
実行中の操作は、親と同じ規則で判定されます。サブエージェント定義にpermissionModeを書いても、auto modeでは無視されます。サブエージェントの起動そのものは権限確認の対象になりません。確認の対象は、起動後のサブエージェント自身のツール呼び出しです。権限確認が出る場合、フォアグラウンドなら呼び出しの瞬間にメイン会話と同じ確認が出ます。バックグラウンドの確認は、v2.1.186以降メインセッションに表示され、Escを押すとそのツール呼び出しだけを拒否できます(サブエージェントは止まりません)。auto modeの規則を調整したい場合の手段はAuto modeルールを編集するで扱っています。
確認と切り分けの手順
自分の環境で条件が揃っているかは、バージョンと権限モードの2点で確かめられます。
claude --versionv2.1.271未満なら、そもそもこのツールがありません。バージョンが足りていても、権限モードがauto以外なら付与されません。auto modeが使えない環境では、セッションは手動確認のモードで始まります。既定でauto modeになる条件はv2.1.284のリリースノートにあります。
auto modeの安全確認をサーバーに投げない設定にしている場合は、審査の実行経路が変わります。設定の意味はCLAUDE_CODE_AUTO_MODE_SERVERを参照してください。
権限ルールでSubagentHandbackを扱えるか
ツール名は、権限ルールやフックのマッチャーに書く文字列として使えると、ツール一覧の冒頭で説明されています。ただしSubagentHandbackに対する許可・拒否ルールが効くかどうかは、確認できていません。toolsやdisallowedToolsで外せない例外がある以上、拒否ルールで止まるかどうかも同じく未確認です。
設計への影響
サブエージェントを多用する運用では、次の点が変わります。
- 報告は審査を通ってから届くので、報告に警告や注意が付く場面が生じる
- 読み取り専用に絞ったサブエージェントでも、報告用のツールだけは付く
- サブエージェントのモデルを固定する設定や配分設計(モデル配分設計)とは独立した仕組みで、審査はサブエージェントのモデルではなく分類器が行う
サブエージェントを並列で使う全体像はTaskツールで作る並列開発パターンが詳しく、SubagentHandbackはそのうちの「結果を返す段階」にだけ関わります。
まとめ
SubagentHandbackは、auto modeでサブエージェントの最終報告を安全に届けるための、定義側から外せないツールです。付与の条件はauto mode、ローカルで動く非フォークのサブエージェント、v2.1.271以降の3つ。審査の結果が悪くても報告は届き、警告か注意が付きます。自分で設定するものではないので、確認するのはバージョンと権限モードだけです。