c504982916
Add prominent warning block that the Agent tool is not exposed to sub-agents (foreground or background). Rewrite Shape A (orchestrator handoff) from "valid pattern" to "confirmed anti-pattern, removed in v2.4.0". Correct Composition section: background + subagents is NOT supported — nested spawn from a sub-agent silently fails. Source: github.com/anthropics/claude-code/issues/19077 Confirmed empirically 2026-04-19. BREAKING CHANGE: Catalog consumers that cited Shape A should migrate to orchestrating from the main command context instead.
127 lines
4.9 KiB
Markdown
127 lines
4.9 KiB
Markdown
---
|
||
name: background-agents-reference
|
||
description: CC background agents — long-running subagents with run_in_background and Monitor for progress streaming.
|
||
layer: reference
|
||
cc_feature: background-agents
|
||
source: https://docs.claude.com/en/docs/claude-code/background-agents
|
||
concept: async-agents-and-monitoring
|
||
last_verified: 2026-04-19
|
||
ngram_overlap_score: null
|
||
review_status: approved
|
||
---
|
||
|
||
# Background Agents — Reference
|
||
|
||
A background agent is a subagent launched with `run_in_background:
|
||
true`. The parent does not block on its return; instead, the harness
|
||
notifies the parent when the agent completes. Useful for long-running
|
||
exploration, orchestration, and work that overlaps with user activity.
|
||
|
||
> **Hard constraint (verified 2026-04-19):** The Claude Code harness does
|
||
> NOT expose the `Agent` tool to sub-agents — foreground OR background.
|
||
> A sub-agent cannot spawn further sub-agents. "Nested orchestration"
|
||
> patterns silently degrade: the inner orchestrator loses its planned
|
||
> swarm and falls back to single-context reasoning. Source:
|
||
> github.com/anthropics/claude-code/issues/19077. Only the main session
|
||
> can spawn agents. Plan shapes that require a swarm below a background
|
||
> agent do not work — keep the orchestration in the main command context
|
||
> instead. See Pitfalls and Composition below.
|
||
|
||
## Launching
|
||
|
||
```
|
||
Agent({
|
||
description: "...",
|
||
subagent_type: "...",
|
||
prompt: "...",
|
||
run_in_background: true
|
||
})
|
||
```
|
||
|
||
The Agent tool returns a handle (agent ID / name). The parent
|
||
continues its turn; no wait.
|
||
|
||
## Monitoring
|
||
|
||
Two complementary tools work with background agents:
|
||
|
||
- **Monitor** — streams updates from a named background process. Each
|
||
event line arrives as a notification. Used for long-running Bash
|
||
processes (and, in newer builds, some agent streaming paths).
|
||
- **Completion notifications** — the harness posts a message to the
|
||
parent when the background agent finishes. The parent sees it as a
|
||
system-reminder / notification on its next turn.
|
||
|
||
## When background is worth it
|
||
|
||
- **Overlapping work** — orchestrator runs 30+ minutes of research
|
||
while the user continues coding. Without background, the user is
|
||
blocked the whole time.
|
||
- **Parallel waves** — wave N of sessions running concurrently; the
|
||
parent collects results as they arrive.
|
||
- **Long-running processes** — an agent waiting on a build, test run,
|
||
or deployment.
|
||
|
||
## When background hurts
|
||
|
||
- **Short tasks** — agent returns in 10 seconds; making it async adds
|
||
overhead for no gain.
|
||
- **Tight coupling** — if the parent needs the result before doing
|
||
anything else, background is just foreground with extra steps.
|
||
- **Unbounded token spend** — a background agent with no budget
|
||
signaling can run until it hits limits. Cap explicitly.
|
||
|
||
## Common shapes
|
||
|
||
### Shape A: Orchestrator handoff (AVOID — see warning above)
|
||
|
||
Pattern: parent interviews user, writes a spec, launches a background
|
||
orchestrator that re-spawns a swarm of workers. **This does not work
|
||
as documented.** The background orchestrator never gets the Agent
|
||
tool, so the swarm never materializes and the inner orchestrator
|
||
degrades to single-context reasoning.
|
||
|
||
Anti-pattern confirmed in ultraplan-local v1.0–v2.3.2. Removed in
|
||
v2.4.0 — the command markdown itself is now the orchestrator in main
|
||
context.
|
||
|
||
### Shape B: Parallel waves (single-file execution only)
|
||
|
||
Parent decomposes work into N independent sessions, launches them
|
||
all in parallel with `run_in_background: true`, then synthesizes
|
||
returns as they arrive. **Each session must be self-contained and
|
||
avoid spawning further agents** — they can use Bash, Read, Grep,
|
||
Edit, Write, but not Agent.
|
||
|
||
Valid use: `ultraplan-local --decompose` execution where each session
|
||
implements concrete code changes without further orchestration.
|
||
|
||
### Shape C: Watcher
|
||
|
||
A background agent polls a process (build, test, deploy) and reports
|
||
status changes. Uses Monitor for streaming. Watchers need Bash/Read
|
||
only — no Agent tool needed, so the harness limitation does not
|
||
apply.
|
||
|
||
## Pitfalls
|
||
|
||
- **Lost context** — if the parent conversation ends before the
|
||
background agent completes, the result may be orphaned. Persist to
|
||
disk, not memory.
|
||
- **Notification fatigue** — too many background agents = too many
|
||
reminders interrupting the parent's flow.
|
||
- **Debugging** — background agents run out of the user's view; their
|
||
failures can be silent. Log to files, not just return messages.
|
||
|
||
## Composition
|
||
|
||
- Background + worktrees: the canonical pattern for parallel
|
||
implementation — each background agent in its own worktree, no
|
||
clashes. Each session performs concrete file changes, not nested
|
||
orchestration.
|
||
- Background + subagents: **NOT SUPPORTED.** A sub-agent, whether
|
||
foreground or background, does not have the Agent tool. Only the
|
||
main session can spawn agents. See the warning at the top of this
|
||
file.
|
||
- Background + hooks: hooks fire inside the background agent's tool
|
||
calls, same as foreground.
|