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

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.

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

@@ -5,7 +5,7 @@ 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-18
+last_verified: 2026-04-19
 ngram_overlap_score: null
 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
 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
 
 ```
@@ -63,26 +73,35 @@ Two complementary tools work with background agents:
 
 ## Common shapes
 
-### Shape A: Orchestrator handoff
+### Shape A: Orchestrator handoff (AVOID — see warning above)
 
-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.
+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.
 
-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
-in parallel with `run_in_background: true`, then synthesizes returns
-as they arrive.
+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.
 
-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
 
 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
 
@@ -98,9 +117,11 @@ status changes. Uses Monitor for streaming.
 
 - 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).
+  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.