サブエージェントの仕組み
フォアグラウンド
セッション内でインライン実行されます。親エージェントは一時停止し、サブエージェントの完了を待ってから処理を続けます。ツール呼び出しが発生した場合は、その都度承認または拒否できます。
バックグラウンド
親エージェントが作業を続ける間、並行して実行されます。サブエージェントが完了すると、親エージェントに自動的に通知されます。承認されていないツールは自動的に拒否されます。
サブエージェントの生の出力は直接表示されません。サブエージェントが完了すると、親エージェントが結果を読み取り、重要な検出結果とアクションを要約して知らせます。
サブエージェントのコスト
プロンプトベースのプランでは、各サブエージェントでもユーザーメッセージと同様に追加のクレジットが消費されます。消費されるクレジット数はサブエージェントが利用するモデルによって異なるため、複数のサブエージェントを生成するタスク (またはそれらをnestするタスク) では、より多くのクレジットが消費されます。
サブエージェントはどのモデルを使いますか?
デフォルトのサブエージェントモデル は固定のモデル名ではありません。生成時にルーター経由で解決され、管理者が上書きすることもできます (以下を参照) 。既定の Subagent router 設定では、SWE-1.6 に解決されます (プランのティアに応じて、高速または低速な SWE-1.6 バリアントが使われます) 。
CLI では現在、実行中のサブエージェントがどのモデルを使っているかはサブエージェントパネルに表示されません。
モデルの選択に影響する要素
run_subagent ツールが受け取るのはモデルではなく プロファイル です。使える手段は 2 つあります。
- 自然言語で プロファイル を指定する。 explore サブエージェントを依頼すると (「explore サブエージェントで auth の仕組みを調査して」など) 、処理は低コストなデフォルトのサブエージェントモデルで実行されます。コード変更を依頼すると
subagent_generalが使われ、選択したモデルで実行されます。 - カスタムサブエージェント の プロファイル でモデルを固定する。 定義ファイルの
model:は、書き込み可能なサブエージェントを親とは異なるモデルで実行する唯一の方法です。サブエージェント内で実行される スキル でも、フロントマター にmodel:を設定して プロファイル のモデルを上書きできます。
Enterprise Controls
subagent_explore と、model: を固定していないカスタムサブエージェントに使用されるモデルを制御します。subagent_general は常に親エージェントのモデルに従うため、変更されません。

サブエージェントの有効化と無効化
subagents_enabled を false に設定すると、run_subagent ツールと read_subagent ツールが削除され、エージェントがすべての作業を自身で行うようになります。
組織ポリシーが優先されます。管理者が デフォルトのサブエージェントモデル を None に設定している場合、この設定の内容にかかわらず、サブエージェントは無効のままです。
サブエージェントプロファイル
エージェントは、タスクに応じて適切なプロファイルを自動的に選択します。explore サブエージェントは調査や理解に最適で、general サブエージェントは変更を加えられます。各プロファイルがどのようにモデルを選択するかについては、サブエージェントはどのモデルを利用しますか? を参照してください。2 つのプロファイルは同じモデルで実行されるわけではありません。
ツールの権限
- フォアグラウンドのサブエージェント はメインのエージェントと同様に動作し、通常どおりツール呼び出しを承認または拒否するよう求められます。プロンプトにはアクションをリクエストしたサブエージェントの名前が表示されるため、誰が要求しているかを確認できます。
- バックグラウンドのサブエージェント は、現在のセッション中にすでに付与したツールの権限を引き継ぎます。事前に承認されていないツールは自動的に拒否されます。バックグラウンドのサブエージェントが新しい権限の承認を求めることはできません。
サブエージェントの監視
サブエージェントのインジケーター
サブエージェントパネル
フォアグラウンド / バックグラウンドの切り替え
- フォアグラウンドのサブエージェントをバックグラウンドに切り替える: フォアグラウンドのサブエージェントの実行中に Ctrl+B を押します。サブエージェントはバックグラウンドで処理を続け、親エージェントが再開します。
- バックグラウンドのサブエージェントをフォアグラウンドに切り替える: サブエージェントパネルを開き、実行中のバックグラウンド サブエージェントで f を押します。サブエージェントの出力がインラインで表示されます。
サブエージェントをバックグラウンドに移した時点で、親エージェントのツール呼び出しはすでに完了しているため、親エージェントは独立して処理を続行します。サブエージェントの結果は親エージェントの現在のパイプラインには反映されませんが、完了すると通知されます。
ターンを中断する
サブエージェントのキャンセル
- サブエージェントパネルから: パネルを開き、実行中のサブエージェントで x を押します。
- フォアグラウンドのサブエージェント: 現在実行中のフォアグラウンドのサブエージェントをキャンセルするには、Ctrl+C または Esc を押します。
サブエージェントの再開
- バックグラウンドで実行していたサブエージェントが、必要なツールの利用を拒否されたために失敗した場合 — フォアグラウンドで再開して、必要な権限を付与できます。
- サブエージェントは完了したものの、その結果に基づいて追加のフォローアップ作業を行わせたい場合。
- サブエージェントが途中でキャンセルされてしまい、続きを実行させたい場合。
ネストの深さ
run_subagent と read_subagent) は無効になっています。
ただし、カスタム サブエージェントプロファイルでは、フロントマターで max-nesting フィールドを設定することで、ネストした起動を有効にできます。この値はデフォルトの最大深度を上書きし、ツリーがその上限内に収まっている限り、サブエージェントが子サブエージェントを起動できるようにします。
たとえば、max-nesting: 3 を設定すると、次のチェーンが可能です。
カスタムサブエージェント
subagent_exploreおよびsubagent_generalプロファイルに加えて、独自のカスタムサブエージェントプロファイルを定義できます。カスタムサブエージェントを使用すると、それぞれに固有のシステムプロンプト、ツールの制限、モデルのオーバーライドを持つ、ワークフロー内の特定のタスク向けに最適化された専用ワーカーを作成できます。これは、 (高価になる可能性がある) プライマリモデルでは実行されない書き込み可能なサブエージェントを使う方法でもあります。model:と必要なツールを指定してください。
カスタムサブエージェントの作成
agents/ 配下の Markdown ファイルとして、次のいずれかのレイアウトで定義します。
- フラットファイル —
agents/<name>.md(Claude Code、Cursor、その他のツールで使われているのと同じ規則です) 。ファイル名 (.mdを除く) がプロファイルの識別子になります。 - ディレクトリ —
agents/<name>/AGENT.md。ディレクトリ名がプロファイルの識別子になります。ファイル名にはAGENTS.md、agent.md、agents.mdも使用できます (複数存在する場合の優先順位は、AGENT.md、AGENTS.md、agent.md、agents.mdの順です) 。
name: を指定すると、パスに由来する識別子よりそちらが優先されます。
- プロジェクト固有
- グローバル
定義ファイルの形式
フロントマター のフィールド
カスタムサブエージェント の利用方法
subagent_explore, subagent_general) と競合するカスタム サブエージェントプロファイルは、警告が表示されたうえでスキップされます。
他のツールからのインポート
Claude Code のエージェントファイルでは、フロントマター に
allowed-tools ではなく tools を使用します。どちらの形式も自動的にサポートされます。
