docs(voyage): correct now-false harness-constraint claims (W0/CC-01)

8 sites across 3 orchestrator agents + trekbrief/trekplan/trekresearch asserted 'the harness does not expose the Agent tool to sub-agents' as present fact -- the rationale for the v2.4.0 inline migration. CC 2.1.172 (verified) lets sub-agents spawn sub-agents up to 5 levels deep, so the claim is false. Replaced each with verified history (pre-2.1.172) + current fact + forward pointer to the decision matrix (W1/CC-26). Decision-neutral: states fact without pre-empting the orchestration redesign. CHANGELOG history left untouched. Tests 578/0/2; claude plugin validate passes.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LqBYc8Ltrk7LipyJmGxXiB

agents/planning-orchestrator.md

@@ -2,13 +2,15 @@
 name: planning-orchestrator
 description: |
   Inline reference (v2.4.0) — documents the planning workflow that
-  /trekplan executes in main context. This file is NOT spawned as a
-  sub-agent anymore. The Claude Code harness does not expose the Agent tool
-  to sub-agents, so an orchestrator launched with run_in_background: true
-  cannot spawn the exploration swarm (architecture-mapper, task-finder,
-  plan-critic, etc.) and would degrade to single-context reasoning. The
-  /trekplan command now orchestrates the phases below directly in the
-  main session.
+  /trekplan executes in main context. Historically not spawned as a
+  sub-agent: before Claude Code 2.1.172 the harness did not expose the
+  Agent tool to sub-agents, so a background orchestrator could not spawn
+  the exploration swarm (architecture-mapper, task-finder, plan-critic,
+  etc.). As of CC 2.1.172 sub-agents can spawn sub-agents (up to 5 levels
+  deep), so a delegated-orchestration redesign is under evaluation (see
+  docs/cc-upgrade-2.1.181-decision-matrix.md, W1/CC-26). Until then the
+  /trekplan command orchestrates the phases below directly in the main
+  session.
 model: opus
 color: cyan
 tools: ["Agent", "Read", "Glob", "Grep", "Write", "Edit", "Bash", "TaskCreate", "TaskUpdate"]
@@ -29,9 +31,14 @@ tools: ["Agent", "Read", "Glob", "Grep", "Write", "Edit", "Bash", "TaskCreate",
 
 This document is the canonical workflow description for the trekplan
 pipeline as of v2.4.0. The `/trekplan` command reads it as reference
-and executes the phases below **inline in the main command context**. It is
-no longer spawned as a background sub-agent — that mode silently lost the
-Agent tool and degraded the exploration swarm to single-context reasoning.
+and executes the phases below **inline in the main command context**. It was
+moved out of background sub-agent mode because, before Claude Code 2.1.172,
+that mode silently lost the Agent tool and degraded the exploration swarm to
+single-context reasoning. As of CC 2.1.172 sub-agents can spawn sub-agents
+(up to 5 levels deep), so this constraint no longer holds; a
+delegated-orchestration redesign is under evaluation (see
+`docs/cc-upgrade-2.1.181-decision-matrix.md`, W1/CC-26). Until then,
+orchestration stays inline.
 
 The role of the "orchestrator" now belongs to the command markdown itself:
 the main Opus session launches exploration and review agents via the Agent

agents/research-orchestrator.md

@@ -2,12 +2,14 @@
 name: research-orchestrator
 description: |
   Inline reference (v2.4.0) — documents the research workflow that
-  /trekresearch executes in main context. This file is NOT spawned as
-  a sub-agent anymore. The Claude Code harness does not expose the Agent tool
-  to sub-agents, so an orchestrator launched with run_in_background: true
-  cannot spawn the research swarm and would degrade to single-context
-  reasoning. The /trekresearch command now orchestrates the phases
-  below directly in the main session.
+  /trekresearch executes in main context. Historically not spawned as
+  a sub-agent: before Claude Code 2.1.172 the harness did not expose the
+  Agent tool to sub-agents, so a background orchestrator could not spawn
+  the research swarm. As of CC 2.1.172 sub-agents can spawn sub-agents
+  (up to 5 levels deep), so a delegated-orchestration redesign is under
+  evaluation (see docs/cc-upgrade-2.1.181-decision-matrix.md, W1/CC-26).
+  Until then the /trekresearch command orchestrates the phases below
+  directly in the main session.
 model: opus
 color: cyan
 tools: ["Agent", "Read", "Glob", "Grep", "Write", "Edit", "Bash"]

agents/review-orchestrator.md

@@ -2,14 +2,16 @@
 name: review-orchestrator
 description: |
   Inline reference (v3.2.0) — documents the review workflow that
-  /trekreview executes in main context. This file is NOT spawned
-  as a sub-agent. The Claude Code harness does not expose the Agent tool
-  to sub-agents, so a background orchestrator launched with
-  run_in_background: true cannot spawn the reviewer swarm
-  (brief-conformance-reviewer, code-correctness-reviewer, review-coordinator)
-  and would degrade silently to single-context reasoning. The
-  /trekreview command now orchestrates the phases below directly in
-  the main session.
+  /trekreview executes in main context. Historically not spawned
+  as a sub-agent: before Claude Code 2.1.172 the harness did not expose
+  the Agent tool to sub-agents, so a background orchestrator could not
+  spawn the reviewer swarm (brief-conformance-reviewer,
+  code-correctness-reviewer, review-coordinator). As of CC 2.1.172
+  sub-agents can spawn sub-agents (up to 5 levels deep), so a
+  delegated-orchestration redesign is under evaluation (see
+  docs/cc-upgrade-2.1.181-decision-matrix.md, W1/CC-26). Until then the
+  /trekreview command orchestrates the phases below directly in the main
+  session.
 model: opus
 color: red
 tools: ["Agent", "Read", "Glob", "Grep", "Write", "Edit", "Bash", "TaskCreate", "TaskUpdate"]
@@ -31,9 +33,13 @@ tools: ["Agent", "Read", "Glob", "Grep", "Write", "Edit", "Bash", "TaskCreate",
 This document is the canonical workflow description for the trekreview
 pipeline as of v3.2.0. The `/trekreview` command reads it as
 reference and executes the phases below **inline in the main command
-context**. It is not spawned as a background sub-agent — that mode would
-silently lose the Agent tool and degrade the reviewer swarm to
-single-context reasoning.
+context**. It was moved out of background sub-agent mode because, before
+Claude Code 2.1.172, that mode would silently lose the Agent tool and degrade
+the reviewer swarm to single-context reasoning. As of CC 2.1.172 sub-agents
+can spawn sub-agents (up to 5 levels deep), so this constraint no longer
+holds; a delegated-orchestration redesign is under evaluation (see
+`docs/cc-upgrade-2.1.181-decision-matrix.md`, W1/CC-26). Until then,
+orchestration stays inline.
 
 The role of the "orchestrator" now belongs to the command markdown itself:
 the main Opus session launches reviewer agents via the Agent tool, runs the
@@ -217,11 +223,14 @@ Append a stats line to `${CLAUDE_PLUGIN_DATA}/trekreview-stats.jsonl`:
 
 ## Hard rules
 
-- **Never spawn in background.** This orchestrator file is reference, not
-  a runnable sub-agent. Background mode silently degrades — the harness
-  does not expose the Agent tool to sub-agents, so the reviewer swarm
-  collapses to single-context reasoning. Always run review agents from
-  the main /trekreview command context.
+- **Currently runs inline, not in background.** This orchestrator file is
+  reference, not a runnable sub-agent. Original reason: before Claude Code
+  2.1.172, background mode silently lost the Agent tool and the reviewer
+  swarm collapsed to single-context reasoning. As of CC 2.1.172 sub-agents
+  can spawn sub-agents (up to 5 levels deep), so that hard block is gone — a
+  delegated redesign is under evaluation (see
+  `docs/cc-upgrade-2.1.181-decision-matrix.md`, W1/CC-26). Until it lands,
+  always run review agents from the main /trekreview command context.
 - **Reviewers run independently.** No cross-feeding of findings. The
   coordinator is the only place where reviewer outputs are combined.
 - **Coordinator scope is bounded.** Dedup, severity ranking, reasonableness

commands/trekbrief.md

@@ -736,14 +736,17 @@ invocation to finish writing the research brief at
 `{PROJECT_DIR}/research/{NN}-{topic-slug}.md` before moving to the next
 topic.
 
-> **Why sequential inline instead of parallel background?** Background
-> orchestrator-agents cannot spawn the research swarm — the Claude Code
-> harness does not expose the Agent tool to sub-agents, so a background
-> run silently degrades to single-context reasoning without WebSearch /
-> Tavily / WebFetch / Gemini (see v2.4.0 release notes). Running each
-> research pass inline in main context keeps the swarm intact. For true
-> parallel execution, use `claude -p` invocations in separate terminal
-> windows.
+> **Why sequential inline instead of parallel background?** Historically,
+> background orchestrator-agents could not spawn the research swarm —
+> before Claude Code 2.1.172 the harness did not expose the Agent tool to
+> sub-agents, so a background run silently degraded to single-context
+> reasoning without WebSearch / Tavily / WebFetch / Gemini (see v2.4.0
+> release notes). As of CC 2.1.172 sub-agents can spawn sub-agents (up to 5
+> levels deep), so a delegated redesign is under evaluation (see
+> `docs/cc-upgrade-2.1.181-decision-matrix.md`, W1/CC-26). Until then,
+> running each research pass inline in main context keeps the swarm intact.
+> For true parallel execution, use `claude -p` invocations in separate
+> terminal windows.
 
 ### Step 6c — Verify all briefs landed
 

commands/trekplan.md

@@ -396,14 +396,17 @@ Planning pipeline running in foreground.
 
 Then continue to the next phase inline.
 
-> **Why foreground?** As of v2.4.0 the planning-orchestrator is no longer
-> spawned as a background agent. The Claude Code harness does not expose the
-> Agent tool to sub-agents, so an orchestrator launched with
-> `run_in_background: true` cannot spawn the documented exploration swarm
-> (`architecture-mapper`, `task-finder`, `plan-critic`, etc.) and silently
-> degrades to single-context reasoning. Running the phases inline in main
-> context keeps the swarm intact. Use `claude -p` in a separate terminal
-> window for long-running headless work.
+> **Why foreground (for now)?** The planning-orchestrator was moved out of
+> background mode in v2.4.0 because, before Claude Code 2.1.172, the harness
+> did not expose the Agent tool to sub-agents, so an orchestrator launched
+> with `run_in_background: true` could not spawn the documented exploration
+> swarm (`architecture-mapper`, `task-finder`, `plan-critic`, etc.) and
+> silently degraded to single-context reasoning. As of CC 2.1.172 sub-agents
+> can spawn sub-agents (up to 5 levels deep), so that block no longer holds —
+> a delegated redesign is under evaluation (see
+> `docs/cc-upgrade-2.1.181-decision-matrix.md`, W1/CC-26). Until then, running
+> the phases inline in main context keeps the swarm intact. Use `claude -p`
+> in a separate terminal window for long-running headless work.
 
 ---
 

commands/trekresearch.md

@@ -206,14 +206,18 @@ Research pipeline running in foreground.
 
 Then continue to the next phase inline.
 
-> **Why foreground?** As of v2.4.0 the research-orchestrator is no longer
-> spawned as a background agent. The Claude Code harness does not expose the
-> Agent tool to sub-agents, so an orchestrator launched with
-> `run_in_background: true` cannot spawn the documented research swarm
-> (`docs-researcher`, `community-researcher`, etc.) and silently degrades to
-> single-context reasoning without WebSearch / Tavily / WebFetch / Gemini.
-> Running the phases inline in main context keeps the swarm intact. Use
-> `claude -p` in a separate terminal window for long-running headless work.
+> **Why foreground (for now)?** The research-orchestrator was moved out of
+> background mode in v2.4.0 because, before Claude Code 2.1.172, the harness
+> did not expose the Agent tool to sub-agents, so an orchestrator launched
+> with `run_in_background: true` could not spawn the documented research
+> swarm (`docs-researcher`, `community-researcher`, etc.) and silently
+> degraded to single-context reasoning without WebSearch / Tavily / WebFetch
+> / Gemini. As of CC 2.1.172 sub-agents can spawn sub-agents (up to 5 levels
+> deep), so that block no longer holds — a delegated redesign is under
+> evaluation (see `docs/cc-upgrade-2.1.181-decision-matrix.md`, W1/CC-26).
+> Until then, running the phases inline in main context keeps the swarm
+> intact. Use `claude -p` in a separate terminal window for long-running
+> headless work.
 
 ---