---
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.