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

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

Parent interviews user, writes a spec, launches a background orchestrator with the spec path. Parent exits its turn; orchestrator takes over for the heavy phases.

Used by: ultraplan-local, ultraresearch-local.

Shape B: Parallel waves

Parent decomposes work into N independent sessions, launches them all in parallel with run_in_background: true, then synthesizes returns as they arrive.

Used by: ultraplan-local --decompose execution.

Shape C: Watcher

A background agent polls a process (build, test, deploy) and reports status changes. Uses Monitor for streaming.

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.
• Background + subagents: an orchestrator IS a subagent; it in turn can launch its own subagents (foreground inside the orchestrator's context, or further background).
• Background + hooks: hooks fire inside the background agent's tool calls, same as foreground.