open/ktg-plugin-marketplace
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity Actions

feat(ultraplan-local)!: v2.4.0 — correct background-agents catalog skill

Browse source 
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.
This commit is contained in:
Kjell Tore Guttormsen 2026-04-19 21:25:30 +02:00
commit b5f6a528fd
1 changed files with 37 additions and 16 deletions
Download patch file Download diff file Expand all files Collapse all files

53
plugins/ultraplan-local/skills/cc-architect-catalog/background-agents-reference.md
View file

@ -5,7 +5,7 @@ layer: reference
cc_feature: background-agents cc_feature: background-agents
source: https://docs.claude.com/en/docs/claude-code/background-agents source: https://docs.claude.com/en/docs/claude-code/background-agents
concept: async-agents-and-monitoring concept: async-agents-and-monitoring
last_verified: 2026-04-18 last_verified: 2026-04-19
ngram_overlap_score: null ngram_overlap_score: null
review_status: approved review_status: approved
--- ---
@ -17,6 +17,16 @@ true`. The parent does not block on its return; instead, the harness
notifies the parent when the agent completes. Useful for long-running notifies the parent when the agent completes. Useful for long-running
exploration, orchestration, and work that overlaps with user activity. 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 ## Launching
``` ```
@ -63,26 +73,35 @@ Two complementary tools work with background agents:
## Common shapes ## Common shapes
### Shape A: Orchestrator handoff ### Shape A: Orchestrator handoff (AVOID — see warning above)
Parent interviews user, writes a spec, launches a background Pattern: parent interviews user, writes a spec, launches a background
orchestrator with the spec path. Parent exits its turn; orchestrator orchestrator that re-spawns a swarm of workers. **This does not work
takes over for the heavy phases. as documented.** The background orchestrator never gets the Agent
tool, so the swarm never materializes and the inner orchestrator
degrades to single-context reasoning.
Used by: `ultraplan-local`, `ultraresearch-local`. 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 ### Shape B: Parallel waves (single-file execution only)
Parent decomposes work into N independent sessions, launches them all Parent decomposes work into N independent sessions, launches them
in parallel with `run_in_background: true`, then synthesizes returns all in parallel with `run_in_background: true`, then synthesizes
as they arrive. 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.
Used by: `ultraplan-local --decompose` execution. Valid use: `ultraplan-local --decompose` execution where each session
implements concrete code changes without further orchestration.
### Shape C: Watcher ### Shape C: Watcher
A background agent polls a process (build, test, deploy) and reports A background agent polls a process (build, test, deploy) and reports
status changes. Uses Monitor for streaming. status changes. Uses Monitor for streaming. Watchers need Bash/Read
only — no Agent tool needed, so the harness limitation does not
apply.
## Pitfalls ## Pitfalls
@ -98,9 +117,11 @@ status changes. Uses Monitor for streaming.
- Background + worktrees: the canonical pattern for parallel - Background + worktrees: the canonical pattern for parallel
implementation — each background agent in its own worktree, no implementation — each background agent in its own worktree, no
clashes. clashes. Each session performs concrete file changes, not nested
- Background + subagents: an orchestrator IS a subagent; it in turn orchestration.
can launch its own subagents (foreground inside the orchestrator's - Background + subagents: **NOT SUPPORTED.** A sub-agent, whether
context, or further background). 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 - Background + hooks: hooks fire inside the background agent's tool
calls, same as foreground. calls, same as foreground.