From 3f77b68727abac58475aefaff2dab1ed96f68dec Mon Sep 17 00:00:00 2001 From: Kjell Tore Guttormsen Date: Thu, 18 Jun 2026 11:43:17 +0200 Subject: [PATCH] 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) Claude-Session: https://claude.ai/code/session_01LqBYc8Ltrk7LipyJmGxXiB --- agents/planning-orchestrator.md | 27 ++++++++++++++-------- agents/research-orchestrator.md | 14 ++++++----- agents/review-orchestrator.md | 41 ++++++++++++++++++++------------- commands/trekbrief.md | 19 ++++++++------- commands/trekplan.md | 19 ++++++++------- commands/trekresearch.md | 20 +++++++++------- 6 files changed, 84 insertions(+), 56 deletions(-) diff --git a/agents/planning-orchestrator.md b/agents/planning-orchestrator.md index 50afa89..4332aa4 100644 --- a/agents/planning-orchestrator.md +++ b/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 diff --git a/agents/research-orchestrator.md b/agents/research-orchestrator.md index 98cd230..4ab1d4f 100644 --- a/agents/research-orchestrator.md +++ b/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"] diff --git a/agents/review-orchestrator.md b/agents/review-orchestrator.md index 2186e33..fe16f58 100644 --- a/agents/review-orchestrator.md +++ b/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 diff --git a/commands/trekbrief.md b/commands/trekbrief.md index edafd94..7abeb6a 100644 --- a/commands/trekbrief.md +++ b/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 diff --git a/commands/trekplan.md b/commands/trekplan.md index b7e30ce..225b989 100644 --- a/commands/trekplan.md +++ b/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. --- diff --git a/commands/trekresearch.md b/commands/trekresearch.md index f5a7169..6e3897f 100644 --- a/commands/trekresearch.md +++ b/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. ---