この記事は何
最近、Claude Codeのサブエージェント（Agent ツール）が、デフォルトでバックグラウンド実行されるようになりました。
バックグラウンド実行は、時間のかかる調査を裏で走らせつつ他の作業を進められるなど、便利な場面もあります。一方で、claude -p を使った自動化のように「メインの処理が終わったらセッションごと終了する」ケースでは、サブエージェントの処理が途中のままセッションが終わってしまう、という困った問題が起きます。
この記事では、サブエージェントをバックグラウンドではなくフォアグラウンドで実行させ、確実に完了を待つようにする方法を紹介します。
Claude CodeのサブエージェントやSkillsの挙動は、アップデートによって変わることがあります。この記事は執筆時点（2026年7月）の挙動をもとにしています。
サブエージェントがバックグラウンドで実行されるとは
Claude Codeでは、Agent ツールを使ってサブエージェントを起動できます。このサブエージェントが、いつからかデフォルトでバックグラウンド実行されるようになりました。
バックグラウンドで実行されると、サブエージェントは裏側で動き続け、メインのClaudeはその完了を待たずに一旦処理を止める（Stopする）ことがあります。対話的に使っている分には、あとから完了通知を受け取れるので、大きな問題にはなりません。
問題になるのは claude -p のようなヘッドレス実行のときです。
claude -p "..." は、プロンプトを一度だけ実行して結果を出力し、メインの処理が止まったらそのままプロセスを終了します。ここでサブエージェントがバックグラウンドで走っていると、メインのClaudeが先にStopした時点でセッションごと終了してしまい、サブエージェントの処理が未完のまま失われてしまいます。本来やりたかった処理が最後まで実行されない、というわけです。
さらに、Skillsに context: fork を指定した場合も、デフォルトでバックグラウンド実行されるようになっています。context: fork はコンテキストを分けてSkillを実行するための設定ですが、これがバックグラウンド実行と組み合わさると、「コンテキストは分けたいけれど、処理は前のステップの結果を待ってから次に進めたい」という段階的なワークフローでうまく噛み合いません。前の処理を待たずに制御が戻ってきてしまうためです。
サブエージェントをフォアグラウンド実行に変える方法
対処法は、サブエージェントの種類によって2つあります。
カスタムサブエージェントの場合
自分で定義したカスタムサブエージェントであれば、話は簡単です。定義ファイルのfrontmatterに background: false を追加するだけで済みます。
---
name: general-purpose-assistant
description: ...
model: sonnet
effort: medium
background: false
---
（サブエージェントへの指示）
これで、このサブエージェントはデフォルトでフォアグラウンド実行されるようになり、メインのClaudeが完了を待ってから次に進むようになります。
Skillsの場合
Skillの場合は、サブエージェントのようにfrontmatterで挙動を切り替える設定がありません。そこで、プロンプト（SKILL.md）の中で「サブエージェントやサブスキル、bashをバックグラウンドで実行せず、必ずフォアグラウンドで実行して完了を待つこと」を明示的に指示します。
僕が公開している claude-task-worker というプラグインでは、実際にこの方法でフォアグラウンド実行を担保しています。
例えば、GitHub Issueの内容を実行する exec-issue スキルでは、以下のように「実行モードの制約」というセクションを設けています。
## 実行モードの制約: サブエージェント・サブスキル・Bashをバックグラウンド実行しないこと
本スキルは `claude-task-worker` の `cc-exec-issue` ラベルをトリガーに自動起動される想定で、ワーカーはスキルプロセスの同期完了を根拠に `cc-in-progress` の除去や `cc-pr-created` 付与といったラベル遷移を進める。そのため、**本スキル内部で呼び出す `Agent` / `Skill` / `Bash` を絶対にバックグラウンド実行しないこと**：
- **`Agent` ツールは既定が `run_in_background: true`（バックグラウンド）**。そのため呼び出しごとに **必ず `run_in_background: false` を明示指定** し、フォアグラウンドで同期的に結果を受け取ってから次の処理に進む。指定を省略した場合はバックグラウンドで走り、本スキルが未完のまま終了する
- `Skill` ツール呼び出しにも `run_in_background: true` を指定しない（既定は同期）。同期完了を待ってから次へ進む
- `Bash` ツールにも `run_in_background: true` を指定しない。既定の同期実行で結果を受け取ってから次の処理に進む
- 同一メッセージ内で複数の `Agent` / `Skill` を並列に投げるのは「並列実行」であって「バックグラウンド実行」ではないため許容される。ただし **`Agent` は個別に `run_in_background: false` を指定** し、その場で同期的に完了を待つ
- シェルコマンド末尾に `&` を付けたり、`nohup` / `disown` / `setsid` などでプロセスをデタッチしたりしない
- `ScheduleWakeup` などで処理を後回しにしない
**理由**: バックグラウンド化すると処理完了前に本スキルが終了し、ワーカーが「正常完了」と誤認してラベル遷移や後続ワーカー起動に進むため、実装未完のままワーカーが二重起動したり、テスト・PR作成未完のまま `cc-pr-created` が付与されたりして、Issue/PRの状態が壊れる。`Agent` ツールの既定が background であることを見落として `run_in_background` を省略すると、この事故が確実に起きる。
ここでのポイントは、次の2つです。
-
Agentツールは既定がバックグラウンドなので、呼び出しごとにrun_in_background: falseを明示する -
&やnohupなどでプロセスをデタッチしたり、処理を後回しにしたりしない
また、context: fork で起動される read-github-issue スキルでも、同じように制約を書いています。
## 実行モードの制約
本スキルは `context: fork` のサブエージェントとして起動されるが、**内部で呼び出す Bash・Skill・Agent も絶対にバックグラウンド実行しないこと**。
- Bash に `run_in_background: true` を指定しない。既定の同期実行（フォアグラウンド）でstdoutを受け取ってから次の処理に進む
- コマンド末尾に `&` を付けない。`nohup` / `disown` / `setsid` 等でのデタッチも禁止
- **`Agent` ツールは既定が `run_in_background: true`（バックグラウンド）**。呼び出しごとに **必ず `run_in_background: false` を明示指定** し、フォアグラウンドで同期的に結果を受け取ってから次の処理に進む。指定を省略した場合はバックグラウンドで走り、本スキルが未完のまま終了する。手順2で並列起動する `Explore` サブエージェントも、同一メッセージ内で並列に投げるだけであり「バックグラウンド」ではない（各 `Agent` 呼び出しは `run_in_background: false` で個別発火する）
- `Skill` にも `run_in_background: true` を渡さない（既定は同期）
- ScheduleWakeup 等で処理を後回しにしない。呼び出し元は本スキルの返却値を同期的に受け取る前提で待機している
**理由**: 本スキルは「Issueを分解した構造化サマリ」を同期返却する契約であり、バックグラウンド化するとサマリ生成前に制御が戻り、後続のタスク実行が空振りするため。
このスキルは「Issueを分解した構造化サマリを同期的に返す」ことが役割です。もしバックグラウンド化してしまうと、サマリができあがる前に制御が呼び出し元へ戻ってしまい、後続のタスク実行が空振りしてしまいます。
ここまで見てきたように、Skillsの場合は次の2点をプロンプトに書いておくのがコツです。
-
Agentツールは既定がバックグラウンドなので、呼び出しごとにrun_in_background: falseを明示する -
BashやSkillにもrun_in_background: trueを渡さず、&などでデタッチもしない
最後に
今回は、Claude Codeのサブエージェントをバックグラウンドではなくフォアグラウンドで実行させる方法を紹介しました。改めて整理すると、以下のようになります。
- カスタムサブエージェントは、定義のfrontmatterに
background: falseを付ける - Skillsは、SKILL.mdの中でサブエージェント・サブスキル・bashをフォアグラウンドで実行して完了を待つよう明示する
デフォルトのバックグラウンド実行は便利な一方で、claude -p を使った自動化パイプラインやCIのように「メインの処理が止まったらセッションごと終了する」環境では、サブエージェントの処理が未完のまま失われる原因になります。自動化フローの中で「なぜかサブエージェントの処理が途中で終わってしまう」という現象に遭遇したら、まずはバックグラウンド実行を疑ってみてください。今回紹介した方法で、確実に完了を待たせられるはずです。
最後までお読みいただきありがとうございました。