ktg-plugin-marketplace/plugins/ultraplan-local/skills/cc-architect-catalog/background-agents-reference.md

name	description	layer	cc_feature	source	concept	last_verified	ngram_overlap_score	review_status
background-agents-reference	CC background agents — long-running subagents with run_in_background and Monitor for progress streaming.	reference	background-agents	https://docs.claude.com/en/docs/claude-code/background-agents	async-agents-and-monitoring	2026-04-19	null	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.