Claude Code subtaskコマンドでサブタスクを親セッションに戻す
/subtaskは会話を引き継いだままバックグラウンドで動き、結果だけを親セッションに戻します。/fork・/branchとの使い分けを表と実例で見分けます。
Claude Code subtaskコマンドは何をするコマンドか
/subtaskは、今の会話をそのまま引き継いだフォークサブエージェントをバックグラウンドで起動するコマンドです。渡したタスクをそのサブエージェントが処理している間、自分は元の会話で作業を続けられます。サブエージェントが完了すると、その結果は1件のメッセージとして親の会話に戻ってきます。
/subtask パーサー変更に対応する単体テストを書いて通常のサブエージェントは真っ白なコンテキストから始まり、渡されたプロンプトだけを頼りに動きます。/subtaskが起動するフォークは違います。ここまでの会話履歴、システムプロンプト、使えるツール、モデルまで、親の会話と同じ状態を引き継いで始まります。背景を説明し直す手間がかからないのが、通常のサブエージェントとの一番の違いです。
たとえば長時間のデバッグセッションで、原因の絞り込みまで会話が進んだところで/subtaskにテスト追加を任せると、フォークは「なぜこの実装になったか」という経緯を最初から持っています。要約を書いて渡す手間も、要約から抜け落ちた前提を後から補う手戻りも減ります。
結果だけ欲しい作業を任せたいとき
任せどころの目安は、途中の試行錯誤が親の会話に残らなくてよい副次的な作業です。公式の説明では、フォーク自身のツール呼び出しは親の会話に入らず、最終結果だけが戻ります。そのぶん親のコンテキストウィンドウを汚しません。
向いているのは次のような場面です。
- 実装を進めながら、並行してテストの下書きだけ別に書かせたい
- 大量のログやファイルを読み込む調査を、親の会話を膨らませずに済ませたい
- 同じ出発点から複数の方針を並行して試したい
反対に、途中経過を自分で見ながら舵を取りたい作業には向きません。その場合は自分が分岐先へ移る/branchのほうが合っています。軽い質問であれば、ツールを使わず履歴を見るだけで答えて履歴にも残さない/btwコマンドという選択肢もあります。
実行から結果が戻るまでの流れ
/subtaskの一連の流れ
- 1
タスクを付けて実行する
/subtaskの後ろにタスクを書いて実行します。名前は渡したタスクの冒頭の言葉から自動で付きます。 - 2
プロンプト下のパネルに行が出る
フォークは入力欄の下のパネルに専用の行として表示され、バックグラウンドで動き続けます。自分は親の会話で別の作業を続けられます。
- 3
必要なら途中で覗く・止める
行を選んでトランスクリプトを開けば追加の指示を送れます。止めたいときは
xです。 - 4
完了すると結果が親に届く
結果は1件のメッセージとして親の会話に届きます。追加の操作は要りません。
パネルのキー操作
| キー | できること |
|---|---|
↑ / ↓ | できることパネル内の行を移動する |
Enter | できること選択中のフォークのトランスクリプトを開き、フォローアップを送る |
x | できること実行中のフォークを停止する。終了済みなら行を消す |
Esc | できることフォーカスをプロンプト入力に戻す |
xには例外があります。メインセッションの行にいるときと、Enterでトランスクリプトを開いているフォークの行にいるときは、xが停止ではなくプロンプトへの文字入力になります。
フォークのトランスクリプトを開いている間、フォローアップのメッセージやスキルはそのフォークへ届きます。組み込みコマンドは親の会話に対して実行されます。/compact・/clear・/rewindは実行前に確認が入り、/modelと/fastはこの画面からは実行できません。
フォークが正常に完了すると行は自動で消えます。失敗した場合や自分で止めた場合は30秒ほど行が残り、結果を見落としにくくなっています。v2.1.232より前は、成功したフォークの行も30秒残っていました。
フォークが今やっている作業を待たずに自分のメッセージを読ませたいときは、Ctrl+EnterかCtrl+X Ctrl+Sで送ります。フォークが待っているシェルコマンドやサブエージェントがバックグラウンドに回せるものなら、そこへ移って動き続けます。この送り方はv2.1.286以降で使えます。
/fork・/branch・/subtaskの使い分け
3つとも「今の会話をもとに何かを分岐させる」点は共通ですが、分岐した側と自分自身の関係が違います。
分岐したあと、自分はどこにいるか
/subtask
分岐した側はフォークサブエージェントです。自分は元の会話に残り、完了すると結果が1件のメッセージで届きます。副次的な1タスクを任せて、結果だけ欲しいときの選択肢です。
/fork
会話をコピーした別のバックグラウンドセッションができ、自分は元のセッションに残ります。コピー側の作業が元の会話に入ることはありません。別の作業を並行して走らせ続けたいときに向きます。
/branch
分岐した会話に自分が切り替わり、元の会話は保存されて/resumeで戻れます。元の状態を残したまま自分で別方向を試したいときに向きます。
/fork側の使い方はClaude Code forkコマンドの記事にまとめています。
/subtaskという名前になったのはClaude Code v2.1.212からです。v2.1.161〜v2.1.211では、今の/subtaskにあたる挙動が/forkという名前でした。v2.1.212で会話をバックグラウンドセッションへ複製する新しい/forkが加わり、旧来の挙動が/subtaskへ分かれています。詳しい経緯はClaude Code v2.1.212のリリースノートで扱っています。
agent viewをオフにしている環境では/subtask自体が使えず、/forkが旧来のフォークサブエージェント挙動を保ったまま動きます。オフにする方法は、disableAgentView設定をtrueにするか、CLAUDE_CODE_DISABLE_AGENT_VIEW環境変数を設定することです。管理者がmanaged settingsで強制している場合もあります。
手元の環境で確認できること
v2.1.286のclaude --helpでは、バックグラウンドセッション関連のコマンドとして次の行が確認できます。/subtaskの裏で動くのはセッション内のサブエージェントなので、これらとは別の仕組みです。
claude --help agents [options] Manage background agents
attach <id> Open a background session in this terminal.
logs <id> Print a background session's recent terminal output
stop|kill <id> Stop a background session.
rm <id> Delete a background session, and its worktree when that is safe.これらは/forkで作った独立セッションやclaude --bgで起動したセッションを操作するコマンドです。claude agents --jsonならアクティブなセッションをJSONで出せます。/subtaskのフォークは、親セッションの入力欄の下のパネルで見ます(上の出力は表示用に抜粋・整形しています)。
/subtask自体は対話セッションの中でしか打てないため、実行出力はここに載せていません。確認できたのは、コマンドの有無とセッション操作系のヘルプまでです。
fork modeと/subtaskは別の設定
Claudeが自分の判断でAgentツール経由のforkサブエージェント型を要求できるかどうかは、「fork mode」という別の設定で決まります。対話セッションではv2.1.232以降で既定オンです。それより前のバージョンではCLAUDE_CODE_FORK_SUBAGENTを1にしてオンにします。非対話モード(-p)やAgent SDKでは既定オフで、同じ環境変数を1にすればオンにできます。0にすればどのセッションでも一律オフです。
/subtaskはこの設定とは独立に動き、fork modeがオフの環境でも自分で打てばフォークを起動できます。fork modeが制御するのは「Claudeが自律的にforkを選ぶかどうか」で、ユーザーが明示する/subtaskの可否とは別の話です。「fork modeをオフにしたのに/subtaskが動く」のは矛盾ではありません。
fork modeをオンのまま、Claudeがフォークを選ぶことだけを止めたいときは、Agent(fork)の拒否ルールでfork型を指定して止められます。なお、fork modeがオンの間は、Claudeが起動するサブエージェントがフォークも通常のものもバックグラウンドで動き、Agentツールのrun_in_backgroundパラメータも外されます。
通常のサブエージェントと何が違うか
フォークは、起動した瞬間の親の状態をそのまま持って始まります。公式の比較表を並べると、違いは次のとおりです。
| 観点 | フォーク | 通常のサブエージェント |
|---|---|---|
| コンテキスト | フォーク会話履歴の全体 | 通常のサブエージェント渡したプロンプトだけの新しい状態 |
| システムプロンプトとツール | フォーク親と同じ | 通常のサブエージェント定義ファイルの内容(バックグラウンド実行では絞られる) |
| モデル | フォーク親と同じ | 通常のサブエージェント定義のmodelフィールド |
| 権限プロンプト | フォークターミナルに出る | 通常のサブエージェントバックグラウンド実行時はメインセッションに出る |
| プロンプトキャッシュ | フォーク親と共有 | 通常のサブエージェント別のキャッシュ |
フォークのシステムプロンプトとツール定義は親と同一なので、最初のリクエストが親のプロンプトキャッシュを再利用できます。同じ文脈が要るタスクなら、新しいサブエージェントを起こすより安く済みます。
表にはない違いが、出力スタイルです。サブエージェントは自前のシステムプロンプトで動くため、通常はoutput styleの影響を受けません。例外がフォークで、こちらは親の出力スタイルがそのまま効きます。これは公式のサブエージェントの起動時の説明に書かれた点です。
ClaudeがAgentツール経由でフォークを起動するとき、isolation: "worktree"を渡すと、編集は自分のチェックアウトとは別のgit worktreeに書き込まれます。Worktree実践ガイドの分離と同じ考え方です。指定がなければ、フォークは自分のチェックアウトを直接編集する前提で考えるのが安全です。
同時実行数と入れ子の上限
サブエージェントの同時実行には上限があります。既定では20個が動いている状態でAgentツールから新しく起動するとConcurrent subagent limit reachedで失敗し、Claudeには再試行しないよう伝えられます。上限はCLAUDE_CODE_MAX_CONCURRENT_SUBAGENTSで変えられ、v2.1.217以降の機能です。/subtaskで起動したフォークはこの上限にブロックされませんが、動いている間は枠を1つ使います。上限には例外が2つあります。ultracodeが有効なセッションでは、上限は適用されません。終了済みサブエージェントの再開も上限を確認せず枠を使うため、実行数が上限を超えることがあります。複数のサブエージェントを組み合わせる設計はClaude Codeオーケストレーター設計で扱っています。
入れ子には別の上限があります。サブエージェントは既定で、メイン会話の下に最大3層まで自分のサブエージェントを起動できます。上限に達した層では、フォーク以外のサブエージェントからAgentツールが外されます。フォークだけは継承したツール一覧にAgentが残りますが、呼ぶとエラーが返るだけです。そもそもフォークは、さらにフォークを起動できません。フォークの中で委譲を重ねる設計は成立しない、と覚えておくと構成を考えやすくなります。深さはCLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTHで変えられます。サブエージェント設計全体はSub-agents完全ガイドにあります。
権限プロンプトと許可の範囲
公式のサブエージェントの説明では、バックグラウンドのサブエージェントが許可の要るツール呼び出しに当たると、そのプロンプトはメインセッションに出て、尋ねているサブエージェントの名前が示されます。承認すれば処理が続き、Escならそのツール呼び出し1回だけを拒否できます。サブエージェントは止まりません。
注意したいのは許可の範囲です。同じ説明に、セッション中ずっと有効にするような単発を超える回答を選んだ場合、その回答はメイン会話を含むセッション全体に適用されるとあります。フォークに一度だけ強い権限を与えたつもりが、親の権限まで緩めてしまう可能性があります。
v2.1.285以降、フォークは親セッションの権限モードのまま動きます。プランモードやdontAskも引き継がれ、フォークからプランモードを抜けることはできません。
フォークの権限プロンプトについては、公式の比較表の記載が「プロンプトはターミナルに出る」となっています。上の説明はバックグラウンドのサブエージェント全般についての記述で、/subtaskのフォークにそのまま当てはまると明記した箇所は見つけられませんでした。任せる作業に必要な権限の強さを事前に見積もり、プロンプトが出たときの選択肢を読んでから答えるのが安全です。
まとめ
フォークは親の権限モードを引き継ぎ、セッション全体に及ぶ許可の回答は親にも効きます。任せる前に、そのタスクが単発の許可で済むかを見ておくと、親の権限を広げずに済みます。