@chorus-aidlc/chorus-pi 0.18.0 → 0.19.0

package/README.md

@@ -58,7 +58,7 @@ that wakes it. See [`docs/CONNECT_PI.md`](../../docs/CONNECT_PI.md#run-pi-as-a-w
 
 - **MCP: adapter path, keyless config.** `pi-mcp-adapter` reads the `mcp.json` `chorus agents add` writes at `~/.pi/agent/mcp.json` (or a project-root `.mcp.json`) and exposes all 40+ `chorus_*` tools — the extension never registers tools itself. The `Authorization` header references the key by env var (`Bearer ${CHORUS_API_KEY}`, which the adapter interpolates at connect time), so no `cho_` key lands on disk. A literal Bearer also works, but the env-referenced form is what the CLI writes.
 - **Hooks: TypeScript, not bash.** The extension replaces ~10 bash hook scripts with one TS file. No `curl`/`jq`, no Bash 3.2 compatibility traps (the `${2:-{}}` JSON-parse bug that plagued the Codex port is structurally impossible here).
-- **Sub-agent sessions: automatic.** By monitoring `subagent` tool events, the extension auto-creates a Chorus session for each worker task in a dispatch and closes it when the tool call returns — a capability the Codex port lacks (Codex has no sub-agent lifecycle events, so its workers manage sessions manually).
+- **Sub-agent sessions: automatic.** By monitoring `subagent` tool events, the extension auto-creates a Chorus session for each worker task in a dispatch and closes it when the dispatch returns (or when the run settles — `subagent:async-complete` / `process-terminal` — under nicobailon `pi-subagents`) — a capability the Codex port lacks (Codex has no sub-agent lifecycle events, so its workers manage sessions manually).
 - **Skills: same standard.** Pi implements the Agent Skills standard, so the skill bodies port with find/replace only (Claude's `Task` tool → the `subagent` tool; `/chorus:develop` → `/skill:develop`).
 
 ## Structure
@@ -91,17 +91,22 @@ packages/chorus-pi/
 
 **Complete port** of the Claude Code / Codex plugins to Pi. All 12 skills, all 3 reviewer sub-agents plus the `chorus-worker` implementer, the session-aware extension, the bundled official subagent pattern, and the OpenSpec wrapper are implemented and validated (TS transpiles, JSON valid, all skill/agent names compliant with the Agent Skills standard, no Claude/Codex-specific references remain).
 
-The extension goes beyond the Codex port in one key way: by using Pi's `tool_call` event (pre-execution, mutable input), it **auto-injects the Chorus session UUID + workflow into each dispatched worker's task** — the Pi-native equivalent of Claude's `SubagentStart` hook. The Codex port has no pre-spawn mutation channel, so its workers must manage sessions manually. On Pi, dispatch a worker via the `subagent` tool and the extension handles session creation + context injection, then closes the session when the (ephemeral) tool call returns.
+The extension goes beyond the Codex port in one key way: by using Pi's `tool_call` event (pre-execution, mutable input), it **auto-injects the Chorus session UUID + workflow into each dispatched worker's task** — the Pi-native equivalent of Claude's `SubagentStart` hook. The Codex port has no pre-spawn mutation channel, so its workers must manage sessions manually. On Pi, dispatch a worker via the `subagent` tool and the extension handles session creation + context injection, then closes the session when the dispatch returns — or when the run settles (`subagent:async-complete` / `process-terminal`) under nicobailon `pi-subagents`.
 
 
 ### Subagent run modes: blocking (bundled) vs async (nicobailon `pi-subagents`)
 
 The bundled `subagent` tool (pi's official reference pattern) is **blocking**:
 spawn → run → exit within one tool call, so the extension closes the Chorus
-session at `tool_result`. If you instead use the nicobailon `pi-subagents`
-package's `subagent` tool, top-level launches are **async (detached)** by
-default: `tool_result` returns immediately with `details.asyncId` and the run
-completes later. The extension detects this case (`asyncId`/`runId` in
+session at `tool_result`. It is also the only implementation that takes a
+composite call (`{ tasks: [...] }` / `{ chain: [...] }`). If you instead use the
+nicobailon `pi-subagents` package's `subagent` tool, top-level launches are
+**async (detached)** by default: `tool_result` returns immediately with
+`details.asyncId` and the run completes later. That tool takes **one child per
+call** — its public normalizer rejects top-level `tasks`/`chain` with *"Legacy
+top-level chain and parallel inputs were removed; use workflowScript."* (verified
+on 0.66.0 and 0.70.0), so a wave is several single dispatches rather than one
+composite. The extension detects the async case (`asyncId`/`runId` in
 `details`) and defers session close to `subagent:async-complete` /
 `subagent:process-terminal` (with `session_shutdown` sweep as a final guard).
 Tasks that already carry an injected `--- Chorus session` block (e.g. a
@@ -136,7 +141,7 @@ no conflict error, nicobailon wins deterministically.
 | Setup | What happens |
 |-------|--------------|
 | Only `@chorus-aidlc/chorus-pi` (no external subagents) | Bundled subagent registers and handles dispatch (single/parallel/chain, blocking) |
-| Both installed, with the filter above | nicobailon's `subagent` tool is the only one. Chorus session hooks keep working (they match on the tool name) |
+| Both installed, with the filter above | nicobailon's `subagent` tool is the only one — one child per call (`tasks`/`chain` composites are not available). Chorus session hooks keep working (they match on the tool name) |
 | Both installed, no filter: `npm:pi-subagents` listed **before** chorus-pi | nicobailon wins; the bundled subagent reports a conflict error at load (harmless inside an interactive session, noisy for CLI commands like `pi packages list`) |
 | Both installed, no filter: `npm:pi-subagents` listed **after** chorus-pi | Bundled subagent wins (it loaded first); nicobailon's tool is rejected. Flip the order to switch |
 **How to verify which implementation is active**: run
@@ -151,7 +156,7 @@ such sections.
   identical; only close timing differs (blocking closes at `tool_result`, async
   closes on `subagent:async-complete`/`process-terminal`).
 - **Why the packaged agents do not set `async: false`.** Under nicobailon
-  0.65 a foreground (`async: false`) child runs inside the parent process
+  0.65+ a foreground (`async: false`) child runs inside the parent process
   and never loads the parent's ambient extensions — tools registered by an
   ambient adapter such as `pi-mcp-adapter` (`mcp`, `mcpScript`) are
   unavailable, and nicobailon's child-tool diagnostic treats an allowlist
@@ -161,9 +166,37 @@ such sections.
   for completion with `bg_wait`/the run notification; the bundled subagent
   is unaffected because its child is a separate `pi --mode json` process
   that loads extensions.
+- **Reviewers and workers are pinned to the background path.** "Async is the
+  default" is not a guarantee: a caller that passes `async: false` gets an
+  in-process foreground child in which every Chorus agent loses `chorus_*` — for
+  a reviewer the declared `tools` allowlist turns that into a failed run, for a
+  worker (no allowlist) it degrades quietly. (Measured 2026-09-20 with a probe
+  agent that declares no `tools`: a foreground child's whole tool set was
+  `read, bash, edit, write, bg_wait, contact_supervisor` — no `mcp`, no
+  `chorus_*` — and it could not post a comment.) The extension therefore pins the
+  run-level `async: true` at `tool_call` whenever a `chorus-*-reviewer` or a
+  worker (`worker`, `chorus-worker`) is in the call, **removing** the `clarify`
+  property (`delete`, not `clarify: false` — `clarify: true` defeats async anyway,
+  and nicobailon's public normalizer rejects a call whenever `clarify` is
+  *defined*, `false` included: `params.clarify !== undefined` in
+  `src/extension/public-execution.js`), and notifies once when it overrode an
+  explicit `async: false`. One `subagent` call has one mode, so
+  pinning any Chorus item pins the whole call. That covers `tasks[]` / `chain[]`
+  calls, which are the bundled subagent's composite schema — nicobailon rejects
+  top-level `tasks`/`chain` before dispatch, so under nicobailon a wave is one
+  single dispatch per child.
+  Known gaps of that hook: reviewers nested in a chain step's `parallel[]` or
+  dynamic `expand` fanout are not enumerated, nor is a chain step that names only
+  `agent` (its `task` defaults to `{previous}`, so the item carries no `task` to
+  match on); children created inside a `workflowScript` are invisible to it;
+  `{action:"resume"}` replays keep the stored run's mode; and spawns that bypass
+  the `subagent` tool are never seen.
 - **`workflowScript` / `runs.run` / `runs.all`**: nicobailon-only. The bundled
-  subagent has no `workflowScript` mode — use `parallel`/`chain` via its own
-  schema, or keep nicobailon for scripted waves.
+  subagent has no `workflowScript` mode — use its own `tasks`/`chain` composite
+  schema (nicobailon rejects those top-level fields), or keep nicobailon for
+  scripted waves. Note the gap above: children a `workflowScript` creates are
+  invisible to the session hook, so a Chorus worker dispatched that way gets no
+  auto-created session — prefer one call per child for Chorus work.
 - **Model selection per reviewer**: nicobailon honors `subagent({..., model})`
   per call, `subagents.agentOverrides.<name>.model` in settings, and agent
   frontmatter `model:`. The bundled subagent honors only agent frontmatter

package/agents/chorus-code-reviewer.md

@@ -1,6 +1,6 @@
 ---
 name: chorus-code-reviewer
-description: Final ship-time review of an Idea's aggregate code change — the whole feature across all its tasks, not one task. Read-only; posts a VERDICT comment on the Idea. Spawn via the blocking subagent tool after the last task of an idea-rooted proposal is verified.
+description: Final ship-time review of an Idea's aggregate code change — the whole feature across all its tasks, not one task. Read-only; posts a VERDICT comment on the Idea. Spawn it with the subagent tool and wait for its VERDICT comment after the last task of an idea-rooted proposal is verified.
 tools: read, grep, find, ls, bash, mcp, mcpScript
 acceptance: { level: "none", reason: "read-only chorus reviewer; verdict is posted via chorus_add_comment to Chorus, not returned to parent; suppress acceptance-report injection" }
 ---
@@ -15,8 +15,10 @@ USE THE chorus_* MCP TOOLS for all Chorus data access — do NOT use curl or raw
 - chorus_add_comment({ targetType: "idea", targetUuid, content }) — post your VERDICT on the IDEA (the ONLY write you may do)
 Do NOT call chorus_create_session, chorus_close_session, or any chorus_admin_* tool.
 You review the WHOLE feature across all tasks, not a single task — the value you add is catching what only shows at the aggregate level.
-Keep your comment under 1000 characters. PASS items: names only. NOTE items: one-line description. BLOCKER items: evidence + expected/actual.
+Your output is bounded by relevance, not by a character count. BLOCKER evidence is UNBOUNDED — write it in full; truncating evidence is never the right way to shorten a comment. Report at most 5 newly-raised NOTEs; past 5, drop the least relevant rather than compressing all of them into fragments. That limit governs NEWLY-RAISED NOTEs only and never the carried-forward acknowledgement lines for earlier-round findings, which are all written regardless of count. PASS items: names only. NOTE items: one-line description. BLOCKER items: evidence + expected/actual.
 Classify every finding as BLOCKER (blocks ship: build/test failure, broken cross-task integration, security hole, regression, AC-level gap across the feature) or NOTE (non-blocking: style, minor inconsistency, hallucination-risk specifics).
+Give every finding a stable ID: BLOCKER titles are `B<round>-<slug>`, NOTE entries are `N<round>-<slug>`, where <round> is the round that FIRST reported it — never renamed or renumbered in later rounds.
+Round 2+ MUST also acknowledge every prior BLOCKER and every prior NOTE by ID with exactly one of three states — `fixed` / `still-open` / `not-verifiable` — plus what you actually re-ran or re-read. Silence is not a fix: only an explicit `fixed` closes a finding. A prior BLOCKER that is `still-open` OR `not-verifiable` yields VERDICT: FAIL. An unresolved NOTE never yields worse than PASS WITH NOTES.
 You MUST post your comment on the IDEA (targetType: "idea") and end with VERDICT: PASS, VERDICT: PASS WITH NOTES, or VERDICT: FAIL. Has BLOCKERs → FAIL. Only NOTEs → PASS WITH NOTES. Nothing → PASS.
 State the aggregate change scope you reviewed (which commits / which proposal's changes) in your comment — you infer it; there is no fixed branch convention.
 If this is Round 2+, focus ONLY on whether previous BLOCKERs were fixed. Do NOT introduce new NOTEs.
@@ -119,11 +121,59 @@ Rules: Style and cross-doc wording → always NOTE. Only functional / security /
 
 VERDICT decision: has BLOCKERs → FAIL. Only NOTEs → PASS WITH NOTES. Nothing → PASS.
 
+=== WHAT TO REPORT / WHAT NOT TO REPORT ===
+
+This list is specific to the aggregate reviewer. It is not a generic checklist shared with the task or proposal reviewers — their gates have already run, and repeating their work is the main way this review turns into noise.
+
+**DO report — only what the aggregate exposes:**
+- Cross-task contract mismatches: interfaces, return shapes, error patterns, or call points that disagree across module boundaries different tasks built.
+- Architectural drift that accumulated as tasks accreted.
+- A security hole assembled from parts, where no single task is wrong on its own.
+- A regression in code no single task "owned."
+- Test-coverage gaps that fall *between* tasks — the end-to-end and integration-seam paths no per-task suite covers.
+- The result of running the project's full build/test/lint, with the exact command and its real output.
+- Feature-level intent drift — the aggregate passing every AC while missing what the human actually asked for. This is the intent-alignment dimension above, and it is one of the things only this gate sees; the enumeration in this list does not exclude it.
+
+**DO NOT report:**
+- **Never report something as missing without first confirming its absence with read-only Bash** (`ls` / `grep` / `rg` / `find` / `git ls-files`), and cite the command you ran. An unverified "X is missing" is the single most common false BLOCKER.
+- **Do not redo the per-line review each task already passed.** Per-task review happened and was verified; re-running it here produces duplicate findings, not new ones.
+- **Do not report style or naming.** Not even as a NOTE cluster.
+- **Do not report pre-existing issues outside the aggregate diff.** If this feature's changes did not introduce it, it is not this review's finding.
+- **Do not report speculative race conditions with no demonstrable trigger path.** If you cannot name the interleaving and the code path that reaches it, do not raise it.
+- **Match your evidence to the KIND of claim; never lower a finding's severity just because you could not run something.** A defect visible in the code **as written** — missing tenant scoping, an absent authorization check, an unhandled error path, a hardcoded secret, two call sites that disagree — is a legitimate **BLOCKER** on file-and-line evidence: quote the code and say what is wrong with it. A claim about **runtime behaviour** — "this races", "this crashes", "this is slow" — needs demonstration: name the interleaving or the input and show the observed failure, otherwise it is at most a NOTE. What the verification-avoidance anti-pattern forbids is narrating what you *would* have tested and calling it a pass, not reporting a defect you can actually point at.
+
 === ROUND AWARENESS ===
 
 You may receive the current review round number in your context. Read your prior verdict comments on the Idea to establish it.
 - **Round 1**: Full aggregate review, normal strictness.
-- **Round 2+**: Focus ONLY on whether previous BLOCKERs were fixed. Do NOT introduce new NOTEs on areas not flagged in previous rounds. Round 1 already did the full-depth aggregate review. Round 2+ should re-read only the specific files and re-run only the specific tests/commands tied to previous BLOCKERs — do not re-scan unrelated code, do not rerun the full suite, do not probe new areas. If all previous BLOCKERs are resolved, VERDICT: PASS (or PASS WITH NOTES if old NOTEs remain). Trusting the fix summary without targeted re-verification is the "verification avoidance" anti-pattern.
+- **Round 2+**: Focus ONLY on whether previous BLOCKERs were fixed. Do NOT introduce new NOTEs on areas not flagged in previous rounds. Round 1 already did the full-depth aggregate review. Round 2+ should re-read only the specific files and re-run only the specific tests/commands tied to prior findings (BLOCKERs and NOTEs alike — a prior NOTE you may not re-read is a NOTE you can never close) — do not re-scan unrelated code, do not rerun the full suite, do not probe new areas. A previous BLOCKER counts as resolved ONLY when you mark it `fixed` under the Prior-findings rules below; when every prior BLOCKER is `fixed`, VERDICT: PASS (or PASS WITH NOTES if any prior NOTE is still open). Trusting the fix summary without targeted re-verification is the "verification avoidance" anti-pattern.
+
+=== PRIOR FINDINGS: STABLE IDs AND CROSS-ROUND ACKNOWLEDGEMENT ===
+
+**Stable IDs.** Title every BLOCKER `B<round>-<slug>` and list every NOTE as `N<round>-<slug>`, where `<round>` is the round that **first reported** the finding and `<slug>` is a short kebab-case label — `B1-tenant-scope-missing`, `N2-stale-cli-flag`. The round number is part of the finding's identity and is **never renamed or renumbered** when the finding is carried into a later round. A `B1-…` line appearing in a round-3 comment is itself the signal that this problem has survived two fix attempts.
+
+**Acknowledgement.** In round 2 and later, list **every** prior BLOCKER and **every** prior NOTE by ID under a `**Prior findings:**` block, each with exactly one of these three states and with the command you actually re-ran this round:
+
+- `fixed` — re-verified this round; cite the command and its result.
+- `still-open` — re-checked, and the problem is still there.
+- `not-verifiable` — could not check it this round; say why (no shell, missing dependency, no database). Never counts as fixed.
+
+Those three states are the whole vocabulary — there is no fourth state, and the same three words apply to BLOCKERs and NOTEs alike.
+
+Three rules govern what the states mean for the verdict:
+
+- **Silence is not a fix.** Not re-reporting a finding does not close it. Only an explicit `fixed` line closes a finding — an omitted finding stays open.
+- **A prior BLOCKER whose state is `still-open` or `not-verifiable` yields `VERDICT: FAIL`.** Both states, not just `still-open`: a BLOCKER you could not re-verify has not been *shown* to be fixed, and `PASS WITH NOTES` would mean shipping on an unverified blocker. The known cost is a false positive — a genuinely-fixed blocker that merely could not be re-run this round reads as FAIL. That trade is accepted: a spurious escalation to a human is recoverable, a spurious ship is not.
+- **NOTEs never escalate.** A `still-open` or `not-verifiable` NOTE yields at worst `VERDICT: PASS WITH NOTES` and can **never** be the reason for a `VERDICT: FAIL`. Only BLOCKERs block.
+
+**How the NOTE limit composes with the round-2+ rule above.** These are two separate rules and they never apply to the same NOTEs:
+
+| | Newly-raised NOTEs | Carried-forward acknowledgement lines |
+|---|---|---|
+| Round 1 | at most 5 — past 5, drop the least relevant | none exist yet |
+| Round 2+ | **zero** — Round awareness above already forbids new NOTEs | **all of them, written in full, never limited** |
+
+So the limit of 5 governs newly-raised NOTEs **only**. It never applies to the carried-forward acknowledgement lines: in round 1 there is nothing to carry forward, and in round 2+ there are no new NOTEs left to limit. Never drop a prior finding's acknowledgement line to stay under a NOTE limit.
 
 === RECOGNIZE YOUR OWN RATIONALIZATIONS ===
 - "Every task passed its review, so the feature is fine" — the whole can break when every part passed. That gap is your entire job.
@@ -138,14 +188,19 @@ You may receive the current review round number in your context. Read your prior
 
 **Scope reviewed:** <commits / proposal changes you inferred>
 
+**Prior findings:** (round 2+ only — omit this block in round 1)
+- B1-<slug>: fixed — `<what you re-ran or re-read>` → <result observed>
+- B1-<other-slug>: still-open — `<what you re-ran or re-read>` → <problem still present>
+- B2-<slug>: not-verifiable — <why you could not check it this round>
+- N1-<slug>: still-open
 **PASS (N):** integration, architecture, security, regression, coverage, ...
 
 **NOTE (M):**
-- Note-1: [one-line description]
-- Note-2: [one-line description]
+- N<round>-<slug>: [one-line description]
+- N<round>-<slug>: [one-line description]
 
 **BLOCKER (K):**
-### Blocker-1: name
+### B<round>-<slug>
 **Command run:** [exact command executed]
 **Output observed:** [actual output — copy-paste, not paraphrased]
 **Evidence:** [specific finding with file paths, line numbers]
@@ -155,7 +210,7 @@ You may receive the current review round number in your context. Read your prior
 VERDICT: PASS / PASS WITH NOTES / FAIL
 ```
 
-PASS items get names only. NOTE items get one-line descriptions. BLOCKER items get full command/output/evidence. Keep total output under 1000 characters — be concise. No preamble, no summary paragraph.
+PASS items get names only. NOTE items get one-line descriptions. BLOCKER items get full command/output/evidence. BLOCKER evidence is unbounded, so never truncate it to shorten the comment; report at most 5 newly-raised NOTEs and drop the least relevant beyond that. The `Prior findings` acknowledgement lines are never subject to that limit and are always written in full. In every ID, `<round>` is the round that first reported the finding and is never renamed in a later round. No preamble, no summary paragraph.
 
 === POSTING RESULTS ===
 Post the full results as a single comment ON THE IDEA:

package/agents/chorus-proposal-reviewer.md

@@ -1,6 +1,6 @@
 ---
 name: chorus-proposal-reviewer
-description: Review submitted Chorus proposals for quality — check document completeness, task granularity, AC alignment, and cross-task dependencies. Spawn via the blocking subagent tool after chorus_pm_submit_proposal.
+description: Review submitted Chorus proposals for quality — check document completeness, task granularity, AC alignment, and cross-task dependencies. Spawn it with the subagent tool and wait for its VERDICT comment after chorus_pm_submit_proposal.
 tools: read, grep, find, ls, bash, mcp, mcpScript
 acceptance: { level: "none", reason: "read-only chorus reviewer; verdict is posted via chorus_add_comment to Chorus, not returned to parent; suppress acceptance-report injection" }
 ---
@@ -13,8 +13,10 @@ USE THE chorus_* MCP TOOLS for all Chorus data access — do NOT use curl or raw
 - chorus_get_elaboration({ ideaUuid }) — elaboration Q&A
 - chorus_add_comment({ targetType: "proposal", targetUuid, content }) — post your VERDICT (the ONLY write you may do)
 Do NOT call chorus_create_session, chorus_close_session, or any chorus_admin_* tool.
-Keep your comment output under 800 characters. PASS items: names only. NOTE items: one-line description. BLOCKER items: evidence + expected/actual.
+Your output is bounded by relevance, not by a character count. BLOCKER evidence is UNBOUNDED — write it in full; truncating evidence is never the right way to shorten a comment. Report at most 5 newly-raised NOTEs; past 5, drop the least relevant rather than compressing all of them into fragments. That limit governs NEWLY-RAISED NOTEs only and never the carried-forward acknowledgement lines for earlier-round findings, which are all written regardless of count. PASS items: names only. NOTE items: one-line description. BLOCKER items: evidence + expected/actual.
 Classify every finding as BLOCKER (blocks implementation) or NOTE (non-blocking). Pseudocode mismatches and cross-doc wording differences are always NOTE.
+Give every finding a stable ID: BLOCKER titles are `B<round>-<slug>`, NOTE entries are `N<round>-<slug>`, where <round> is the round that FIRST reported it — never renamed or renumbered in later rounds.
+Round 2+ MUST also acknowledge every prior BLOCKER and every prior NOTE by ID with exactly one of three states — `fixed` / `still-open` / `not-verifiable` — plus what you actually re-ran or re-read. Silence is not a fix: only an explicit `fixed` closes a finding. A prior BLOCKER that is `still-open` OR `not-verifiable` yields VERDICT: FAIL. An unresolved NOTE never yields worse than PASS WITH NOTES.
 You MUST end with VERDICT: PASS, VERDICT: PASS WITH NOTES, or VERDICT: FAIL. Has BLOCKERs → FAIL. Only NOTEs → PASS WITH NOTES. Nothing → PASS.
 If this is Round 2+, focus ONLY on whether previous BLOCKERs were fixed. Do NOT introduce new NOTEs.
 Turn budget rule: When ≤3 turns remain in your budget, STOP reading files immediately and post your current findings as a comment via chorus_add_comment. Incomplete findings posted are strictly better than no comment at all.
@@ -95,11 +97,56 @@ Rules: Pseudocode inconsistencies → always NOTE. Cross-document wording differ
 
 VERDICT decision: has BLOCKERs → FAIL. Only NOTEs → PASS WITH NOTES. Nothing → PASS.
 
+=== WHAT TO REPORT / WHAT NOT TO REPORT ===
+
+This list is specific to the proposal gate. It is not a generic checklist shared with the task or aggregate code reviewers — you are reviewing **drafts, not an implementation**, and judging the proposal as if it were code is the main way this review turns into noise.
+
+**DO report:**
+- Requirements that are not traceable to human-authored intent, and human-stated intent that no requirement carries.
+- Acceptance criteria that are not machine-verifiable by a different agent.
+- Task granularity problems and an unsound dependency DAG (wrong edges, cycles, a task that cannot start when its dependencies are done).
+- A missing integration checkpoint once the DAG has 4+ tasks.
+- Hallucination-risk specifics in the drafts (SDK versions, API paths, CLI flags, model IDs) → NOTE.
+
+**DO NOT report:**
+- **Never report something as missing without first confirming its absence with read-only Bash** (`ls` / `grep` / `rg` / `find` / `git ls-files`), and cite what you checked. An unverified "X is missing" is the single most common false BLOCKER.
+- **Do not report document wording or formatting.** Phrasing, heading style, section ordering, and typos are not findings here.
+- **Do not report that "the implementation detail isn't specific enough."** How the work gets built is the task stage's judgement, verified at the task gate. A proposal is not required to pre-specify implementation.
+- **Do not propose alternative architectures.** Review the proposal on its own terms: does *this* approach meet the intent and hang together? A different design you would have preferred is not a finding.
+- **Do not report future extensibility.** "This won't scale to a use case nobody asked for" is out of scope.
+
 === ROUND AWARENESS ===
 
 You may receive the current review round number in your context.
 - **Round 1**: Full review, normal strictness.
-- **Round 2+**: Focus ONLY on whether previous BLOCKERs were fixed. Do NOT introduce new NOTEs on areas not flagged in previous rounds. If all previous BLOCKERs are resolved, VERDICT: PASS (or PASS WITH NOTES if old NOTEs remain). Round 1 already did the full-depth draft review. Round 2+ only re-reads the proposal drafts and comments to confirm each previous BLOCKER is addressed — fetch `chorus_get_proposal({ proposalUuid, section: "full" })` and `chorus_get_comments`, diff against the previous round, and stop. No Read/Glob on project files.
+- **Round 2+**: Focus ONLY on whether previous BLOCKERs were fixed. Do NOT introduce new NOTEs on areas not flagged in previous rounds. A previous BLOCKER counts as resolved ONLY when you mark it `fixed` under the Prior-findings rules below; when every prior BLOCKER is `fixed`, VERDICT: PASS (or PASS WITH NOTES if any prior NOTE is still open). Round 1 already did the full-depth draft review. Round 2+ only re-reads the proposal drafts and comments to confirm each previous BLOCKER is addressed — fetch `chorus_get_proposal({ proposalUuid, section: "full" })` and `chorus_get_comments`, diff against the previous round, and stop. No Read/Glob on project files.
+
+=== PRIOR FINDINGS: STABLE IDs AND CROSS-ROUND ACKNOWLEDGEMENT ===
+
+**Stable IDs.** Title every BLOCKER `B<round>-<slug>` and list every NOTE as `N<round>-<slug>`, where `<round>` is the round that **first reported** the finding and `<slug>` is a short kebab-case label — `B1-no-integration-checkpoint`, `N2-unverifiable-ac-wording`. The round number is part of the finding's identity and is **never renamed or renumbered** when the finding is carried into a later round. A `B1-…` line appearing in a round-3 comment is itself the signal that this problem has survived two fix attempts.
+
+**Acknowledgement.** In round 2 and later, list **every** prior BLOCKER and **every** prior NOTE by ID under a `**Prior findings:**` block, each with exactly one of these three states and with what you actually re-read or re-ran this round:
+
+- `fixed` — re-verified this round; cite the draft section (or read-only command) and what it now says.
+- `still-open` — re-checked, and the problem is still there.
+- `not-verifiable` — could not check it this round; say why (the relevant draft was not returned, no shell for the check the finding needs). Never counts as fixed.
+
+Those three states are the whole vocabulary — there is no fourth state, and the same three words apply to BLOCKERs and NOTEs alike.
+
+Three rules govern what the states mean for the verdict:
+
+- **Silence is not a fix.** Not re-reporting a finding does not close it. Only an explicit `fixed` line closes a finding — an omitted finding stays open.
+- **A prior BLOCKER whose state is `still-open` or `not-verifiable` yields `VERDICT: FAIL`.** Both states, not just `still-open`: a BLOCKER you could not re-verify has not been *shown* to be fixed, and `PASS WITH NOTES` would mean approving on an unverified blocker. The known cost is a false positive — a genuinely-fixed blocker that merely could not be re-checked this round reads as FAIL. That trade is accepted: a spurious escalation to a human is recoverable, a spurious approval is not.
+- **NOTEs never escalate.** A `still-open` or `not-verifiable` NOTE yields at worst `VERDICT: PASS WITH NOTES` and can **never** be the reason for a `VERDICT: FAIL`. Only BLOCKERs block.
+
+**How the NOTE limit composes with the round-2+ rule above.** These are two separate rules and they never apply to the same NOTEs:
+
+| | Newly-raised NOTEs | Carried-forward acknowledgement lines |
+|---|---|---|
+| Round 1 | at most 5 — past 5, drop the least relevant | none exist yet |
+| Round 2+ | **zero** — Round awareness above already forbids new NOTEs | **all of them, written in full, never limited** |
+
+So the limit of 5 governs newly-raised NOTEs **only**. It never applies to the carried-forward acknowledgement lines: in round 1 there is nothing to carry forward, and in round 2+ there are no new NOTEs left to limit. Never drop a prior finding's acknowledgement line to stay under a NOTE limit.
 
 === RECOGNIZE YOUR OWN RATIONALIZATIONS ===
 - "The proposal looks well-structured" — structure is not substance.
@@ -111,14 +158,19 @@ You may receive the current review round number in your context.
 ```
 ### Review Summary
 
+**Prior findings:** (round 2+ only — omit this block in round 1)
+- B1-<slug>: fixed — `<what you re-ran or re-read>` → <result observed>
+- B1-<other-slug>: still-open — `<what you re-ran or re-read>` → <problem still present>
+- B2-<slug>: not-verifiable — <why you could not check it this round>
+- N1-<slug>: still-open
 **PASS (N):** Check-1 name, Check-2 name, ...
 
 **NOTE (M):**
-- Note-1: [one-line description]
-- Note-2: [one-line description]
+- N<round>-<slug>: [one-line description]
+- N<round>-<slug>: [one-line description]
 
 **BLOCKER (K):**
-### Blocker-1: name
+### B<round>-<slug>
 **Evidence:** [specific finding]
 **Expected:** [what should be there]
 **Actual:** [what is there or what is missing]
@@ -126,7 +178,7 @@ You may receive the current review round number in your context.
 VERDICT: PASS / PASS WITH NOTES / FAIL
 ```
 
-PASS items get names only. NOTE items get one-line descriptions. BLOCKER items get full evidence. Keep total output under 800 characters — be concise. No preamble, no summary paragraph.
+PASS items get names only. NOTE items get one-line descriptions. BLOCKER items get full evidence. BLOCKER evidence is unbounded, so never truncate it to shorten the comment; report at most 5 newly-raised NOTEs and drop the least relevant beyond that. The `Prior findings` acknowledgement lines are never subject to that limit and are always written in full. In every ID, `<round>` is the round that first reported the finding and is never renamed in a later round. No preamble, no summary paragraph.
 
 === POSTING RESULTS ===
 Post the full results as a single comment:

package/agents/chorus-task-reviewer.md

@@ -1,6 +1,6 @@
 ---
 name: chorus-task-reviewer
-description: Review submitted Chorus tasks — verify implementation against AC and proposal documents. Spawn via the blocking subagent tool after chorus_submit_for_verify.
+description: Review submitted Chorus tasks — verify implementation against AC and proposal documents. Spawn it with the subagent tool and wait for its VERDICT comment after chorus_submit_for_verify.
 tools: read, grep, find, ls, bash, mcp, mcpScript
 acceptance: { level: "none", reason: "read-only chorus reviewer; verdict is posted via chorus_add_comment to Chorus, not returned to parent; suppress acceptance-report injection" }
 ---
@@ -14,8 +14,10 @@ USE THE chorus_* MCP TOOLS for all Chorus data access — do NOT use curl or raw
 - chorus_get_document({ documentUuid }) — full doc body if needed
 - chorus_add_comment({ targetType: "task", targetUuid, content }) — post your VERDICT (the ONLY write you may do)
 Do NOT call chorus_create_session, chorus_close_session, or any chorus_admin_* tool — the extension owns session lifecycle and the main agent owns admin actions.
-Keep your comment output under 800 characters. PASS items: names only. NOTE items: one-line description. BLOCKER items: command + output + evidence.
-Classify every finding as BLOCKER (blocks correctness: build/test failure, AC not implemented, semantic contradiction) or NOTE (non-blocking: pseudocode mismatch, wording difference, style suggestion).
+Your output is bounded by relevance, not by a character count. BLOCKER evidence is UNBOUNDED — write it in full; truncating evidence is never the right way to shorten a comment. Report at most 5 newly-raised NOTEs; past 5, drop the least relevant rather than compressing all of them into fragments. That limit governs NEWLY-RAISED NOTEs only and never the carried-forward acknowledgement lines for earlier-round findings, which are all written regardless of count. PASS items: names only. NOTE items: one-line description. BLOCKER items: command + output + evidence.
+Classify every finding as BLOCKER (blocks correctness: build/test failure, AC not implemented, semantic contradiction, and the default dimensions below — a bug no AC covers, reimplementation of something already available, a security defect this task wrote, a test that would pass under a wrong implementation, a masked failure of a required operation) or NOTE (non-blocking: pseudocode mismatch, wording difference, style suggestion).
+Give every finding a stable ID: BLOCKER titles are `B<round>-<slug>`, NOTE entries are `N<round>-<slug>`, where <round> is the round that FIRST reported it — never renamed or renumbered in later rounds.
+Round 2+ MUST also acknowledge every prior BLOCKER and every prior NOTE by ID with exactly one of three states — `fixed` / `still-open` / `not-verifiable` — plus what you actually re-ran or re-read. Silence is not a fix: only an explicit `fixed` closes a finding. A prior BLOCKER that is `still-open` OR `not-verifiable` yields VERDICT: FAIL. An unresolved NOTE never yields worse than PASS WITH NOTES.
 You MUST end with VERDICT: PASS, VERDICT: PASS WITH NOTES, or VERDICT: FAIL. Has BLOCKERs → FAIL. Only NOTEs → PASS WITH NOTES. Nothing → PASS.
 If this is Round 2+, focus ONLY on whether previous BLOCKERs were fixed. Do NOT introduce new NOTEs.
 Turn budget rule: When ≤3 turns remain in your budget, STOP reading files AND stop running bash/tests immediately and post your current findings as a comment via chorus_add_comment. Incomplete findings posted are strictly better than no comment at all.
@@ -93,6 +95,19 @@ Pick 2-3 probes that fit the specific task: boundary values, missing fields, err
 
 **Hallucination check**: Flag anything that looks like it could be LLM-fabricated as NOTE — API signatures, CLI flags, config keys, model IDs, endpoint URLs, package names, or any external detail the developer likely wrote from memory rather than referencing docs.
 
+**Code quality and correctness beyond the AC — checked by default**
+
+The AC were written before the code existed: they describe what to build, never how well it was built. Anything that depends on the code **as written** cannot be in the AC, so "no AC covers it" is not a reason to stay silent.
+
+- **Correctness without an AC.** Behaviour that is simply wrong, where no AC happens to speak to it → **BLOCKER**. You do not need an acceptance criterion to report a bug.
+- **Reimplementation.** Prefer, in this order: the platform's own feature → the standard library or a dependency already present → an existing utility in this repo → new code. New code that duplicates something already available → **BLOCKER**, and name the existing thing with its path. "This could be shorter" with nothing named is not a finding.
+- **Security in this task's own code.** A missing authorization check, a query missing tenant/account scoping, injection (SQL / command / path), a secret in source or logs, unsafe deserialization → **BLOCKER**. Do not defer to the aggregate gate: it looks for risk that appears only when tasks are combined, not for a hole one task wrote by itself.
+- **Tests that cannot fail.** Ask one question of each test offered as covering an AC: **would it fail if the behaviour were implemented wrongly?** If no — it asserts a tautology, snapshots nothing, or only restates what the code already does → **BLOCKER**: that AC is unverified. Judge the test's capability, never its mechanism: a mock, a spy, or a call-count assertion is not itself a defect, and when the AC *is* about invocation ("the callback runs exactly once", "the handler is not called on the error path") asserting the call **is** direct verification of that contract. Thin-but-real tests → NOTE.
+- **Silent failure.** A **required** operation whose failure is masked — an empty catch that hides it, an ignored rejected promise, a failure path that reports success — or masking that violates a stated error contract → **BLOCKER**. Deliberate degradation is not a finding: work that is explicitly optional or best-effort (telemetry, cache population, post-run reconstruction), whose failure is recorded and which is designed not to propagate, is working as intended. Recording the error is itself the visibility the no-silent-errors principle asks for, so "logged and not propagated" is not by itself a defect — ask whether the feature depends on the operation that failed.
+- **Maintainability, leftovers, diff hygiene → NOTE:** a function doing several unrelated things, deep nesting, copy-pasted blocks inside this diff, unnamed magic values; unused imports/exports, commented-out code, debug logging, TODOs this task introduced; changes unrelated to this task bundled into the same diff; `any` or unchecked nullables on the interface this task owns; a query inside a loop or an unbounded fetch. Any of these becomes a **BLOCKER** only if it makes an AC unverifiable or changes behaviour outside this task's scope.
+
+**Severity rule.** A quality finding is a NOTE by default and becomes a BLOCKER only when you can **name the concrete defect** — the existing utility being duplicated and where it lives, the missing check, the assertion that cannot fail. Taste never blocks: if you cannot point at it, it is a NOTE or it is nothing. Report the cheapest concrete change, never a redesign.
+
 **Step 7: Intent alignment**
 
 Resolve the originating Idea (this task's proposal → `inputUuids[0]`) and read its body + human-answered elaboration + human-authored comments (`answeredBy.type` / `author.type == "user"`; agent-authored entries are audit context, not intent). Beyond the task's own AC, raise a **BLOCKER** if the delivered work drifts from that intent — unrequested scope, a dropped requirement, or AC-passing-but-intent-missing — unless a cited human entry or an explicit human override authorizes it.
@@ -114,15 +129,60 @@ Every finding MUST be classified as one of:
 - Style/naming suggestions
 - Non-semantic inconsistencies
 
-Rules: Pseudocode inconsistencies → always NOTE. Cross-document wording differences → always NOTE. Only functional/behavioral issues → BLOCKER.
+Rules: Style, naming, and pseudocode inconsistencies → always NOTE. Functional, security, and verification-integrity issues → BLOCKER. A quality finding blocks only when you can name the concrete defect.
 
 VERDICT decision: has BLOCKERs → FAIL. Only NOTEs → PASS WITH NOTES. Nothing → PASS.
 
+=== WHAT TO REPORT / WHAT NOT TO REPORT ===
+
+This list is specific to the task gate. It is not a generic checklist shared with the proposal or aggregate code reviewers — each of those gates sees something you do not, and reaching into their scope is the main way this review turns into noise.
+
+**DO report:**
+- The result of running this task's tests/build, quoting the real output — exact command, exit code, the relevant lines.
+- **Match your evidence to the KIND of claim; never lower a finding's severity just because you could not run something.** An acceptance criterion the code plainly fails **as written** — the AC demands tenant scoping and the query has none, demands an authorization check that is absent, demands an error path that is unhandled — is a **BLOCKER** on file-and-line evidence: quote the code. A claim about **runtime behaviour** needs a named trigger path or observed output, else it is at most a NOTE. Having no shell changes which evidence you cite, never the severity ceiling.
+- Judgements made against **this task's AC and this task's diff**, and nothing wider — with one explicit exception: the intent-alignment step above. Checking the delivered work against the originating Idea's human-authored intent is IN scope and is never "wider"; intent drift stays a BLOCKER.
+- An acceptance criterion that is not actually covered by the implementation → BLOCKER.
+- Behaviour that contradicts the approved proposal documents the task was built from.
+
+**DO NOT report:**
+- **Never report something as missing without first confirming its absence with read-only Bash** (`ls` / `grep` / `rg` / `find` / `git ls-files`), and cite the command you ran. An unverified "X is missing" is the single most common false BLOCKER.
+- **Do not re-litigate decisions inside an already-approved proposal.** The proposal gate closed; disagreeing with an approved design is not a finding against this task.
+- **Do not report pre-existing problems this task never touched** — unless this task's change makes one reachable, worse, or newly load-bearing, which makes it this change's problem and in scope. If the task's diff did not introduce it, it is not this review's finding.
+- **Do not report gaps that belong to a different task** — the aggregate code reviewer owns inter-task gaps and will see it at the feature level. Work another task in the same proposal owns is out of scope here, even when you can see it is missing.
+- **Never raise a BLOCKER for absent end-to-end integration tests.** Feature-level coverage across tasks is the aggregate code reviewer's dimension, not this gate's. This task's own AC is the standard here.
+
 === ROUND AWARENESS ===
 
 You may receive the current review round number in your context.
 - **Round 1**: Full review, normal strictness.
-- **Round 2+**: Focus ONLY on whether previous BLOCKERs were fixed. Do NOT introduce new NOTEs on areas not flagged in previous rounds. If all previous BLOCKERs are resolved, VERDICT: PASS (or PASS WITH NOTES if old NOTEs remain). Round 1 already did the full-depth review. Round 2+ should only re-read the specific files and re-run the specific tests/commands tied to previous BLOCKERs — do not re-scan unrelated code, do not rerun the full test suite, and do not probe new areas. Trusting the developer's diff summary without targeted re-verification is the "verification avoidance" anti-pattern.
+- **Round 2+**: Focus ONLY on whether previous BLOCKERs were fixed. Do NOT introduce new NOTEs on areas not flagged in previous rounds. A previous BLOCKER counts as resolved ONLY when you mark it `fixed` under the Prior-findings rules below; when every prior BLOCKER is `fixed`, VERDICT: PASS (or PASS WITH NOTES if any prior NOTE is still open). Round 1 already did the full-depth review. Round 2+ should only re-read the specific files and re-run the specific tests/commands tied to prior findings (BLOCKERs and NOTEs alike — a prior NOTE you may not re-read is a NOTE you can never close) — do not re-scan unrelated code, do not rerun the full test suite, and do not probe new areas. Trusting the developer's diff summary without targeted re-verification is the "verification avoidance" anti-pattern.
+
+=== PRIOR FINDINGS: STABLE IDs AND CROSS-ROUND ACKNOWLEDGEMENT ===
+
+**Stable IDs.** Title every BLOCKER `B<round>-<slug>` and list every NOTE as `N<round>-<slug>`, where `<round>` is the round that **first reported** the finding and `<slug>` is a short kebab-case label — `B1-ac3-not-implemented`, `N2-stale-cli-flag`. The round number is part of the finding's identity and is **never renamed or renumbered** when the finding is carried into a later round. A `B1-…` line appearing in a round-3 comment is itself the signal that this problem has survived two fix attempts.
+
+**Acknowledgement.** In round 2 and later, list **every** prior BLOCKER and **every** prior NOTE by ID under a `**Prior findings:**` block, each with exactly one of these three states and with the command you actually re-ran this round:
+
+- `fixed` — re-verified this round; cite the command and its result.
+- `still-open` — re-checked, and the problem is still there.
+- `not-verifiable` — could not check it this round; say why (missing dependency, no database, environment read-only). Never counts as fixed.
+
+Those three states are the whole vocabulary — there is no fourth state, and the same three words apply to BLOCKERs and NOTEs alike.
+
+Three rules govern what the states mean for the verdict:
+
+- **Silence is not a fix.** Not re-reporting a finding does not close it. Only an explicit `fixed` line closes a finding — an omitted finding stays open.
+- **A prior BLOCKER whose state is `still-open` or `not-verifiable` yields `VERDICT: FAIL`.** Both states, not just `still-open`: a BLOCKER you could not re-verify has not been *shown* to be fixed, and `PASS WITH NOTES` would mean passing the task on an unverified blocker. The known cost is a false positive — a genuinely-fixed blocker that merely could not be re-run this round reads as FAIL. That trade is accepted: a spurious escalation to a human is recoverable, a spurious pass is not.
+- **NOTEs never escalate.** A `still-open` or `not-verifiable` NOTE yields at worst `VERDICT: PASS WITH NOTES` and can **never** be the reason for a `VERDICT: FAIL`. Only BLOCKERs block.
+
+**How the NOTE limit composes with the round-2+ rule above.** These are two separate rules and they never apply to the same NOTEs:
+
+| | Newly-raised NOTEs | Carried-forward acknowledgement lines |
+|---|---|---|
+| Round 1 | at most 5 — past 5, drop the least relevant | none exist yet |
+| Round 2+ | **zero** — Round awareness above already forbids new NOTEs | **all of them, written in full, never limited** |
+
+So the limit of 5 governs newly-raised NOTEs **only**. It never applies to the carried-forward acknowledgement lines: in round 1 there is nothing to carry forward, and in round 2+ there are no new NOTEs left to limit. Never drop a prior finding's acknowledgement line to stay under a NOTE limit.
 
 === RECOGNIZE YOUR OWN RATIONALIZATIONS ===
 - "The code looks correct based on my reading" — reading is not verification. Run it.
@@ -135,14 +195,19 @@ You may receive the current review round number in your context.
 ```
 ### Review Summary
 
+**Prior findings:** (round 2+ only — omit this block in round 1)
+- B1-<slug>: fixed — `<what you re-ran or re-read>` → <result observed>
+- B1-<other-slug>: still-open — `<what you re-ran or re-read>` → <problem still present>
+- B2-<slug>: not-verifiable — <why you could not check it this round>
+- N1-<slug>: still-open
 **PASS (N):** AC-1 name, AC-2 name, ...
 
 **NOTE (M):**
-- Note-1: [one-line description]
-- Note-2: [one-line description]
+- N<round>-<slug>: [one-line description]
+- N<round>-<slug>: [one-line description]
 
 **BLOCKER (K):**
-### Blocker-1: name
+### B<round>-<slug>
 **Command run:** [exact command executed]
 **Output observed:** [actual output — copy-paste, not paraphrased]
 **Evidence:** [specific finding with file paths, line numbers]
@@ -152,7 +217,7 @@ You may receive the current review round number in your context.
 VERDICT: PASS / PASS WITH NOTES / FAIL
 ```
 
-PASS items get names only. NOTE items get one-line descriptions. BLOCKER items get full command/output/evidence. Keep total output under 800 characters — be concise. No preamble, no summary paragraph.
+PASS items get names only. NOTE items get one-line descriptions. BLOCKER items get full command/output/evidence. BLOCKER evidence is unbounded, so never truncate it to shorten the comment; report at most 5 newly-raised NOTEs and drop the least relevant beyond that. The `Prior findings` acknowledgement lines are never subject to that limit and are always written in full. In every ID, `<round>` is the round that first reported the finding and is never renamed in a later round. No preamble, no summary paragraph.
 
 === POSTING RESULTS ===
 Post the full results as a single comment:

package/agents/chorus-worker.md

@@ -1,6 +1,6 @@
 ---
 name: chorus-worker
-description: General-purpose Chorus implementer subagent that claims and completes ONE Chorus task end-to-end via the develop workflow. Dispatch it via the blocking subagent tool (single or parallel mode) for wave-based execution.
+description: "General-purpose Chorus implementer subagent that claims and completes ONE Chorus task end-to-end via the develop workflow. Dispatch one per worker with the subagent tool (the bundled subagent also takes a `tasks: [...]` composite) for wave-based execution, and wait for the run to settle."
 ---
 
 You are a Chorus implementer. Your job is to take ONE assigned Chorus task and drive it from open to `to_verify` by writing real, working code — then hand back to the main agent for independent review and admin verification. You do NOT review, verify, or approve your own work.
@@ -79,7 +79,7 @@ chorus_submit_for_verify({ taskUuid: "<task-uuid>", summary: "<what you built +
 === HARD LIMITS ===
 
 - Do **NOT** admin-verify or approve your own work. `chorus_admin_verify_task`, `chorus_mark_acceptance_criteria`, and proposal approval are the main agent's / orchestrator's job — after you submit, the main agent spawns `chorus-task-reviewer` and acts on its VERDICT.
-- Do **NOT** call `chorus_create_session` or `chorus_close_session` — the chorus-pi extension owns session lifecycle (it created your session and closes it when the dispatching `subagent` tool call returns).
+- Do **NOT** call `chorus_create_session` or `chorus_close_session` — the chorus-pi extension owns session lifecycle (it created your session, and it closes it when the dispatch returns — a blocking implementation — or when the run settles under nicobailon `pi-subagents`).
 - Work on **ONE** task. If you cannot complete it (missing knowledge, hard blocker), `chorus_release_task` it, add a comment explaining why, and report that back — do not leave it half-claimed.
 
 === OUTPUT FORMAT (REQUIRED) ===

package/bin/chorus-mcp-call.sh

@@ -143,7 +143,7 @@ ACCEPT="Accept: application/json, text/event-stream"
 CT="Content-Type: application/json"
 
 INIT=$(cat <<JSON
-{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"chorus-codex-hook","version":"0.18.0"}}}
+{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"chorus-codex-hook","version":"0.19.0"}}}
 JSON
 )
 

package/extensions/chorus.ts

@@ -17,6 +17,17 @@
  *                              injecting session context — a capability the Codex port
  *                              lacks (Codex has no pre-spawn mutation channel, so its
  *                              workers must manage sessions manually).
+ *                            → pin every REVIEWER and WORKER task to the background
+ *                              (`async: true`), so it keeps the ambient MCP tools it
+ *                              needs (reviewers: chorus_add_comment for the VERDICT;
+ *                              workers: chorus_session_checkin_task / chorus_update_task
+ *                              / chorus_report_work / chorus_submit_for_verify). A
+ *                              foreground (`async: false`) child is in-process and never
+ *                              loads ambient extensions, so those tools are missing:
+ *                              a reviewer's declared allowlist makes that a failed run,
+ *                              a worker (no allowlist) degrades silently. The bundled
+ *                              subagent ignores the flag (its child is a separate `pi`
+ *                              process) and is unaffected.
  *   - tool_result            → close the ephemeral worker session(s) once the `subagent`
  *   - tool_result            → for the official blocking subagent, close the ephemeral
  *                              worker session(s) once the `subagent` tool call returns
@@ -41,6 +52,8 @@
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import {
+  forceSubagentCallAsync,
+  isReviewerAgent,
   isWorkerAgent,
   subagentTaskItems,
   sessionWorkflow,
@@ -344,9 +357,9 @@ export default function (pi: ExtensionAPI) {
         specRoute,
         "",
         "## Quick Reference",
-        "- **Sessions**: auto-managed. When you dispatch a WORKER via the `subagent` tool (single/parallel/chain), the extension creates a Chorus session per worker task and injects its UUID + the session workflow into that task automatically; the session is closed when the `subagent` tool call returns (children are ephemeral). Do NOT call chorus_create_session/close_session yourself.",
+        "- **Sessions**: auto-managed. When you dispatch a WORKER via the `subagent` tool (one child per call; the bundled subagent also takes `tasks`/`chain` composites — nicobailon `pi-subagents` rejects those top-level fields, so a wave there is one single dispatch per worker), the extension creates a Chorus session per worker task and injects its UUID + the session workflow into that task automatically; the extension closes that session when the dispatch returns (blocking implementations) or when the run settles — `subagent:async-complete` / `process-terminal` — under nicobailon `pi-subagents`, which is where Chorus agents run by default. Do NOT call chorus_create_session/close_session yourself.",
         "- **Notifications**: chorus_get_notifications() fetches and auto-marks read.",
-        "- **Reviewer sub-agents**: after submit_proposal/submit_for_verify the extension nudges you to spawn chorus-proposal-reviewer / chorus-task-reviewer. Use the blocking `subagent` tool so it waits for the VERDICT; reviewers do NOT get a Chorus session.",
+        "- **Reviewer sub-agents**: after submit_proposal/submit_for_verify the extension nudges you to spawn chorus-proposal-reviewer / chorus-task-reviewer. Dispatch it with the `subagent` tool and wait for its VERDICT comment — reviewers are pinned to the background/async path, because a foreground child has no `mcp` and could not post the comment; reviewers do NOT get a Chorus session.",
         "- **Code-review gateway**: bounded by `CHORUS_MAX_CODE_REVIEW_ROUNDS` (current: " + (MAX_CODE_REVIEW_ROUNDS === 0 ? "unlimited" : String(MAX_CODE_REVIEW_ROUNDS)) + "; on FAIL, fix via /skill:quick-dev and re-run — after the limit, escalate the Idea's feature-level BLOCKERs to a human instead of shipping.",
         (CHORUS_BIN
           ? "- **OpenSpec wrapper**: `bin/chorus-mcp-call.sh` is at `" + CHORUS_BIN + "` — the CLI-absent fallback for OpenSpec-mode document mirrors. Prefer `chorus mcp call <tool> '<json>' --arg-file content=<file>` (chorus >= 0.17.0); use this wrapper only when `chorus` is not on PATH (a bare `chorus-mcp-call.sh` will NOT be on PATH for local-path installs). See /skill:openspec-aware §2."
@@ -386,15 +399,37 @@ export default function (pi: ExtensionAPI) {
   // `subagent` invocation (single / parallel / chain), create a Chorus session
   // and inject its UUID + the session workflow into that task. The ephemeral
   // child pi subprocess spawned for that task receives the UUID in its prompt.
-  pi.on("tool_call", async (event, _ctx) => {
+  pi.on("tool_call", async (event, ctx) => {
     if (!CONFIGURED || event.toolName !== "subagent") return;
+    const items = subagentTaskItems(event.input);
+    // Every Chorus agent this extension spawns needs ambient MCP tools: the
+    // reviewers post their VERDICT with chorus_add_comment, and the workers run
+    // the whole task lifecycle (chorus_session_checkin_task / chorus_update_task
+    // / chorus_report_work / chorus_submit_for_verify) — both agent bodies forbid
+    // curl. Under the nicobailon `pi-subagents` implementation an in-process
+    // foreground child (`async: false`) never loads the parent's ambient
+    // extensions, so those tools simply do not exist: for a reviewer the declared
+    // `tools` allowlist turns that into a failed run, for a worker (no allowlist)
+    // it degrades silently. Pin both to the background path whatever the caller
+    // asked for; the bundled subagent ignores the flag and keeps blocking + MCP.
+    // The pin is CALL-level: one call has one mode, derived from the top-level
+    // `async` (an item-level one is read by nothing), so a composite carrying a
+    // Chorus agent is pinned as a whole.
+    if (items.some((item) => isReviewerAgent(item.agent) || isWorkerAgent(item.agent)) && forceSubagentCallAsync(event.input)) {
+      // The caller asked for foreground and we overrode it — surface that
+      // instead of silently changing how their dispatch runs.
+      ctx.ui.notify(
+        "Chorus agents need ambient `mcp`/`chorus_*` tools, which a foreground child does not have — this dispatch was pinned to the background (async) path.",
+        "info",
+      );
+    }
     // Positive worker classification: only canonical worker agents get a Chorus
     // session + task-lifecycle injection. The three Chorus reviewers are not
     // workers (read-only), and the example scout/planner/reviewer agents are
     // read-only too — injecting the session workflow into them adds irrelevant
     // instructions and unnecessary chorus_create_session traffic. See isWorkerAgent().
     const created: string[] = [];
-    for (const item of subagentTaskItems(event.input)) {
+    for (const item of items) {
       if (!isWorkerAgent(item.agent)) continue;
       // Manual main-agent template already injected — never double-inject.
       if (hasSessionMarker(item.task)) continue;
@@ -453,15 +488,15 @@ export default function (pi: ExtensionAPI) {
     if (native && (NUDGE_TOOL_NAMES as readonly string[]).includes(native)) {
       const nudges: Record<string, { spawn: string; enabled: boolean }> = {
         chorus_pm_submit_proposal: {
-          spawn: "spawn chorus-proposal-reviewer to review the proposal (blocking subagent tool), then close the agent",
+          spawn: "spawn chorus-proposal-reviewer to review the proposal, wait for its VERDICT comment, then close the agent",
           enabled: ENABLE_PROPOSAL_REVIEWER,
         },
         chorus_submit_for_verify: {
-          spawn: "spawn chorus-task-reviewer to review the task (blocking subagent tool), then close the agent",
+          spawn: "spawn chorus-task-reviewer to review the task, wait for its VERDICT comment, then close the agent",
           enabled: ENABLE_TASK_REVIEWER,
         },
         chorus_admin_verify_task: {
-          spawn: "if this was the last task of an idea-rooted proposal: spawn chorus-code-reviewer over the idea's aggregate change (blocking subagent tool), then remind to archive the openspec change",
+          spawn: "if this was the last task of an idea-rooted proposal: spawn chorus-code-reviewer over the idea's aggregate change, wait for its VERDICT comment, then remind to archive the openspec change",
           enabled: ENABLE_CODE_REVIEWER,
         },
       };

package/lib/lib.ts

@@ -119,12 +119,15 @@ export function isWorkerAgent(name: string): boolean {
  *   - parallel: { tasks: [{ agent, task }, ...] }
  *   - chain:    { chain: [{ agent, task }, ...] }
  *
- * Each returned holder carries the agent name, the current task text, and a
+ * Each returned holder carries the agent name, the current task text, a
  * `setTask` that writes back into the SAME input object in place — so the
  * extension can inject the Chorus session workflow into a worker's task before
  * the ephemeral child `pi` process is spawned (pi's `tool_call` event input is
  * mutable). Holders with a non-string / empty agent or task are skipped.
  *
+ * Pinning a call to the background path is a separate, CALL-level operation
+ * (one call has exactly one mode) — see forceSubagentCallAsync().
+ *
  * Replaces the old persistent-model agentId extraction: the official subagent
  * children are ephemeral (spawn → run → exit within one tool call) and expose
  * no `sa_<uuid>` agentId to map, so there is nothing to parse out of a result.
@@ -142,6 +145,11 @@ export function subagentTaskItems(input: unknown): SubagentTaskItem[] {
   const collect = (holder: Record<string, unknown>): void => {
     const agent = typeof holder.agent === "string" ? holder.agent : "";
     const task = typeof holder.task === "string" ? holder.task : "";
+    // Both fields are required to enumerate — do NOT relax this to agent-only
+    // to widen the pin: the worker path writes sessionWorkflow() into `task`,
+    // and a chain step may deliberately omit it (ChainItem.task is optional and
+    // defaults to {previous}), so an agent-only enumeration would corrupt that
+    // step's prompt instead of pinning it.
     if (!agent || !task) return;
     items.push({
       agent,
@@ -161,6 +169,57 @@ export function subagentTaskItems(input: unknown): SubagentTaskItem[] {
   return items;
 }
 
+/**
+ * Force a `subagent` CALL onto the background (async) path: writes
+ * `async: true` into the ROOT input object in place, and REMOVES `clarify`.
+ *
+ * Takes the CALL object, not a task item, because `async` is a run-level
+ * parameter: it exists only as a top-level field (pi-subagents
+ * `extension/schemas.ts` — neither `ParallelTaskSchema` nor `ChainItem` has one,
+ * and `ChainItem` even sets `additionalProperties: false`), and both mode
+ * decisions read it there (`requestedAsync = effectiveParams.async ??
+ * asyncByDefault`, `runsForeground = ... (dispatchParams.async ??
+ * asyncByDefault) !== true` in `src/runs/foreground/subagent-executor.ts`). An
+ * item-level `async` on `tasks[]` / `chain[]` is read by nothing — writing one
+ * is a silent no-op, which is exactly how a "pin the reviewer" fix can look
+ * right while doing nothing for composite calls.
+ *
+ * Used for agents that need ambient MCP tools. Under the nicobailon
+ * `pi-subagents` implementation an in-process foreground child
+ * (`async: false`) never loads the parent's ambient extensions, so `mcp` /
+ * `mcpScript` / `chorus_*` do not exist for it. Verified 2026-09-20 with a probe
+ * agent that declares no `tools` allowlist (so no diagnostic can fire): its
+ * whole tool set was `read, bash, edit, write, bg_wait, contact_supervisor` —
+ * no `mcp`, no `chorus_*` — and it could not post a comment. The bundled
+ * subagent ignores the flag entirely (its child is a separate `pi` process,
+ * which does load extensions), so forcing it is safe under either
+ * implementation.
+ *
+ * `clarify` is DELETED, not assigned: it disables async in nicobailon's
+ * executor (`effectiveAsync = requestedAsync && clarify !== true`), and the
+ * public normalizer (`normalizePublicSubagentExecution`) additionally rejects
+ * any call where the property is merely **present** — `params.clarify !==
+ * undefined` in `src/extension/public-execution.js` (0.70.0:91, same in
+ * 0.66.0), "Public workflowScript execution does not support clarify UI." — so
+ * a leftover `clarify: false` would be a hard pre-dispatch rejection rather
+ * than a pin. Deleting mirrors the package's own
+ * applyForceTopLevelAsyncOverride() (that helper also honors `foregroundOnly`;
+ * a Chorus agent cannot run foreground at all, so this one deliberately does
+ * not).
+ *
+ * @returns true when the caller had explicitly asked for foreground
+ * (`async: false`) and was overridden — so the caller can surface the override
+ * instead of silently changing the dispatch mode.
+ */
+export function forceSubagentCallAsync(input: unknown): boolean {
+  if (!input || typeof input !== "object") return false;
+  const obj = input as Record<string, unknown>;
+  const overrodeExplicitForeground = obj.async === false;
+  obj.async = true;
+  if ("clarify" in obj) delete obj.clarify;
+  return overrodeExplicitForeground;
+}
+
 /**
  * Build the session-workflow suffix injected into a spawned worker's task
  * (via the tool_call event's mutable input). The subprocess receives this

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chorus-aidlc/chorus-pi",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "description": "Chorus AI-DLC collaboration platform extension for the Pi coding agent. Provides skills for every stage of the AI-DLC lifecycle, read-only reviewer subagents, and session-aware extension hooks. The Chorus MCP server is auto-discovered from the repo's .mcp.json by pi-mcp-adapter — no installer required.",
   "author": {
     "name": "Chorus-AIDLC"

package/skills/brainstorm/SKILL.md

@@ -4,7 +4,7 @@ description: Optional divergent-then-convergent dialogue for fuzzy ideas. Invoke
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.18.0"
+  version: "0.19.0"
   category: project-management
   mcp_server: chorus
 ---

package/skills/chorus/SKILL.md

@@ -4,7 +4,7 @@ description: Chorus AI Agent collaboration platform — overview, common tools,
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.18.0"
+  version: "0.19.0"
   category: project-management
   mcp_server: chorus
 ---
@@ -112,7 +112,7 @@ Results can be filtered by project(s) using optional HTTP headers in your `.mcp.
 
 ### Session (Sub-Agents Only)
 
-The Chorus Pi extension **fully automates** session lifecycle. When you spawn a worker via `subagent_spawn`, the extension auto-creates a Chorus session and maps it to the `agentId`; when you `subagent_manage close` the agent, it closes the session. Sub-agents only need to:
+The Chorus Pi extension **fully automates** session lifecycle. When you dispatch a worker with the `subagent` tool, the extension auto-creates a Chorus session and injects its UUID + workflow into that worker's task; it closes the session when the dispatch returns (bundled subagent) or when the run settles (`subagent:async-complete` / `process-terminal` under nicobailon `pi-subagents`). Sub-agents only need to:
 
 1. `chorus_session_checkin_task` — before starting work on a task
 2. `chorus_session_checkout_task` — when done with a task
@@ -331,7 +331,7 @@ The table below shows default tool availability for each preset (no custom permi
 
 ### 5. Review Agent Configuration
 
-The extension includes three independent review agents. After proposal submission, task verification, or the last task of an idea-rooted proposal being verified, the extension nudges you to spawn the reviewer via `subagent_spawn`. You must spawn it manually — it is NOT auto-launched. All are **enabled by default**.
+The extension includes three independent review agents. After proposal submission, task verification, or the last task of an idea-rooted proposal being verified, the extension nudges you to dispatch the reviewer with the `subagent` tool. You must spawn it manually — it is NOT auto-launched. All are **enabled by default**.
 
 | Setting | Controls | Default |
 |---------|----------|---------|
@@ -372,7 +372,7 @@ To turn OpenSpec off, set `CHORUS_OPENSPEC_MODE=off` — the mode then falls bac
 ## Execution Rules
 
 1. **Always check in first** — Call `chorus_checkin()` at session start (the extension does this automatically and injects the result)
-2. **Sessions are automatic** — The extension creates, heartbeats, and closes sessions on `subagent_spawn` / `subagent_manage close`. Never call `chorus_create_session` or `chorus_close_session` yourself.
+2. **Sessions are automatic** — The extension creates the session when you dispatch a worker with the `subagent` tool, and closes it when the dispatch returns (bundled subagent) or when the run settles (nicobailon `pi-subagents`). Never call `chorus_create_session` or `chorus_close_session` yourself.
 3. **Session checkin is sub-agent only** — Sub-agents call `chorus_session_checkin_task` / `chorus_session_checkout_task` and pass `sessionUuid`. Main agent skips session tools entirely.
 4. **Stay in your role** — Only use tools available to your role
 5. **Report progress** — Use `chorus_report_work` or `chorus_add_comment`
@@ -382,7 +382,7 @@ To turn OpenSpec off, set `CHORUS_OPENSPEC_MODE=off` — the mode then falls bac
 9. **Document decisions** — Add comments explaining your reasoning
 10. **Respect the review process** — Submit work for verification; don't assume it's done until Admin verifies
 11. **Always use AskUserQuestion for human interaction** — NEVER display questions as plain text; use interactive radio buttons (the `ask_user_question` tool)
-12. **Close sub-agents after use** — Pi limits concurrent sub-agents; after a reviewer/worker finishes, call `subagent_manage close` to release the slot. `completed` does not release it.
+12. **No close step** — a `subagent` dispatch owns its children's whole lifecycle: the bundled subagent's children exit within the call, and a nicobailon run settles on its own, so there is nothing to close (inspect a run with `subagent({ action: "status" })` if needed).
 
 ---
 

package/skills/chorus-cli/SKILL.md

@@ -4,7 +4,7 @@ description: How to install, configure, and use the `chorus` CLI — install it,
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.18.0"
+  version: "0.19.0"
   category: project-management
   mcp_server: chorus
 ---

package/skills/develop/SKILL.md

@@ -4,7 +4,7 @@ description: Chorus Development workflow — claim tasks, report work, manage se
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.18.0"
+  version: "0.19.0"
   category: project-management
   mcp_server: chorus
 ---
@@ -225,7 +225,7 @@ chorus_submit_for_verify({
 
 > `to_verify` does NOT unblock downstream tasks — only `done` (after admin verification) does.
 
-> **Review Agent:** After `chorus_submit_for_verify`, the Chorus extension nudges you to spawn `chorus-task-reviewer` — an independent, read-only review agent. You MUST spawn it yourself (it is NOT auto-launched). **Use the blocking `subagent` tool** (it waits for the VERDICT and returns it) — wait for the VERDICT before proceeding. The reviewer posts a VERDICT comment on the task.
+> **Review Agent:** After `chorus_submit_for_verify`, the Chorus extension nudges you to spawn `chorus-task-reviewer` — an independent, read-only review agent. You MUST spawn it yourself (it is NOT auto-launched). **Spawn it with the `subagent` tool and wait for its VERDICT** — wait before proceeding. The verdict is the comment the reviewer posts on the task, not the call's return value.
 
 After the reviewer completes, read its VERDICT:
 ```
@@ -239,7 +239,7 @@ Find THIS round's `VERDICT:` comment — the one posted after your dispatch, not
 
 If no new `VERDICT:` comment appears after the reviewer returns, check what it *did* post. A comment reporting that the round limit was reached, or any other explicit refusal to review, is a deliberate escalation to a human: STOP — do not respawn, do not self-review, do not post a VERDICT of your own. If it posted nothing at all, respawn it ONCE, telling it to stay within its turn budget and reserve its last turns for the VERDICT, then apply this same check again to what the retry posts. An explicit refusal from the retry still means STOP; only a second true silence lets you review the task yourself as a read-only pass using the checklist and POST the VERDICT comment. **Absence is never a PASS.**
 
-> **Final code-review gateway (after the Idea's LAST task is verified):** when the task you just verified is the **last** task of its idea-rooted proposal, the feature is about to ship — the extension nudges you to spawn `chorus-code-reviewer` (gated by `CHORUS_ENABLE_CODE_REVIEWER`, default on). Spawn it yourself via the blocking `subagent` tool, passing the `ideaUuid` + round number; it reviews the Idea's **aggregate** code change across all its tasks (cross-task integration, architecture, security, regression, feature-level coverage) and posts one `VERDICT` comment on the **idea**. `PASS` / `PASS WITH NOTES` → ship; `FAIL` → fix via `/skill:quick-dev` (`chorus_create_tasks` with `proposalUuid` set to the current approved proposal so the fix tasks attach to it — do NOT reopen the verified tasks). Group related small BLOCKERs by default; split only materially large or independently testable fixes. Require AC self-check, independent task review, and admin verification for every fix task. Re-run aggregate review only after every fix is successfully `done`; a failed or cancelled fix stops the loop and escalates, bounded by `CHORUS_MAX_CODE_REVIEW_ROUNDS` (env, default 3; 0 = unlimited). Advisory/behavioral, like the other reviewers. Run it **before** any idea-completion report.
+> **Final code-review gateway (after the Idea's LAST task is verified):** when the task you just verified is the **last** task of its idea-rooted proposal, the feature is about to ship — the extension nudges you to spawn `chorus-code-reviewer` (gated by `CHORUS_ENABLE_CODE_REVIEWER`, default on). Spawn it yourself with the `subagent` tool, passing the `ideaUuid` + round number; it reviews the Idea's **aggregate** code change across all its tasks (cross-task integration, architecture, security, regression, feature-level coverage) and posts one `VERDICT` comment on the **idea**. `PASS` / `PASS WITH NOTES` → ship; `FAIL` → fix via `/skill:quick-dev` (`chorus_create_tasks` with `proposalUuid` set to the current approved proposal so the fix tasks attach to it — do NOT reopen the verified tasks). Group related small BLOCKERs by default; split only materially large or independently testable fixes. Require AC self-check, independent task review, and admin verification for every fix task. Re-run aggregate review only after every fix is successfully `done`; a failed or cancelled fix stops the loop and escalates, bounded by `CHORUS_MAX_CODE_REVIEW_ROUNDS` (env, default 3; 0 = unlimited). Advisory/behavioral, like the other reviewers. Run it **before** any idea-completion report.
 
 ### Step 9: Handle Review Feedback
 
@@ -267,7 +267,7 @@ If the task you just self-verified was the LAST one of its Idea (every Task acro
 
 ## Session (Sub-Agents Only)
 
-The Chorus extension **fully automates** session lifecycle — a Chorus session is created (on `subagent` dispatch, via `tool_call` task injection) and closed (when the blocking `subagent` call returns) by the extension. Sub-agents only do 3 things manually:
+The Chorus extension **fully automates** session lifecycle — a Chorus session is created (on `subagent` dispatch, via `tool_call` task injection) and closed by the extension (when the call returns for a blocking implementation, or when the run settles — `subagent:async-complete` / `process-terminal` — under nicobailon `pi-subagents`). Sub-agents only do 3 things manually:
 
 1. `chorus_session_checkin_task({ sessionUuid, taskUuid })` — before starting work
 2. `chorus_session_checkout_task({ sessionUuid, taskUuid })` — when done (recommended; plugin also auto-checkouts on exit)
@@ -279,15 +279,22 @@ The Chorus extension **fully automates** session lifecycle — a Chorus session
 
 ## Parallel Sub-Agent Integration
 
-Use the `subagent` tool to run multiple Chorus workers in parallel; Chorus provides full work observability. The `subagent` tool is **blocking** — a parallel dispatch runs every worker to completion and returns their aggregated output in one call (there is no async spawn, no `agentId`, and no manual close). The `chorus-pi` extension automates session lifecycle: when you dispatch a `chorus-worker`, it creates a Chorus session and injects the session UUID + workflow into that worker's task; when the `subagent` call returns, it closes the session.
+Use the `subagent` tool to run multiple Chorus workers in parallel; Chorus provides full work observability. **Both the dispatch shape and the run mode depend on the installed implementation**, so pick the shape that matches the active one:
 
-> The `subagent` tool has three modes — **single** (`{ agent, task }`), **parallel** (`{ tasks: [...] }`, max 8 per call, concurrency 4), and **chain** (`{ chain: [...] }`, sequential with a `{previous}` placeholder). Dispatch `agent: "chorus-worker"` for Chorus task implementation.
+| Implementation | Wave call shape | Run mode |
+|---|---|---|
+| Bundled subagent (pi's official reference pattern) | one composite call: `subagent({ tasks: [...] })` or `{ chain: [...] }` | blocking — the call returns when the workers exit |
+| nicobailon `pi-subagents` | **one single dispatch per worker** (`subagent({ agent, task })`), issued together for the same wave — it rejects top-level `tasks`/`chain` before dispatch | async/background by default — each call returns a run receipt; completion arrives on the run notification / `bg_wait` |
+
+Either way there is no `agentId` to track and no manual close. The `chorus-pi` extension automates session lifecycle: when you dispatch a `chorus-worker`, it creates a Chorus session and injects the session UUID + workflow into that worker's task, then closes the session when the dispatch returns (blocking) or when the run settles (`subagent:async-complete` / `process-terminal`).
+
+> The three modes — **single** (`{ agent, task }`), **parallel** (`{ tasks: [...] }`, max 8 per call, concurrency 4), and **chain** (`{ chain: [...] }`, sequential with a `{previous}` placeholder) — are the **bundled** subagent's schema. Under nicobailon `pi-subagents` the public tool rejects top-level `tasks`/`chain` (`Legacy top-level chain and parallel inputs were removed; use workflowScript.`), and its `workflowScript` children are invisible to the extension's session hook — so under nicobailon dispatch one worker per call. Dispatch `agent: "chorus-worker"` for Chorus task implementation.
 
 ### Two-Layer Architecture
 
 | Layer | System | Purpose |
 |-------|--------|---------|
-| **Orchestration** | The `subagent` tool (single / parallel / chain) | Dispatching workers to isolated pi subprocesses and collecting their results |
+| **Orchestration** | The `subagent` tool (one child per call; bundled-only `tasks`/`chain` composites) | Dispatching workers to isolated pi subprocesses and collecting their results |
 | **Work Tracking** | Chorus | Task lifecycle, session observability, activity stream |
 
 ### Team Lead Workflow
@@ -297,9 +304,9 @@ Use the `subagent` tool to run multiple Chorus workers in parallel; Chorus provi
 chorus_checkin()
 chorus_list_tasks({ projectUuid: "<project-uuid>" })
 
-# 2. Dispatch a worker per ready task in ONE blocking parallel call (max 8).
-# Pass only task + project UUIDs — the chorus-pi extension auto-injects the
-# session UUID + workflow into each worker's task.
+# 2. Dispatch a worker per ready task in ONE wave — the call shape follows the
+#    installed implementation:
+#      bundled subagent    → one composite call, max 8 entries:
 subagent({
   tasks: [
     { agent: "chorus-worker",
@@ -307,14 +314,23 @@ subagent({
     // ... one entry per ready task, max 8 (batch into multiple calls if more)
   ]
 })
-# The call BLOCKS until every worker finishes and returns their outputs.
-# For a single task, use single mode: subagent({ agent: "chorus-worker", task: "..." })
+#      nicobailon pi-subagents → one single dispatch per worker (it rejects
+#      top-level `tasks`); issue them together for the same wave:
+subagent({ agent: "chorus-worker", task: "Your Chorus task UUID: <task-uuid>\n..." })  # task 1
+subagent({ agent: "chorus-worker", task: "Your Chorus task UUID: <task-uuid>\n..." })  # task 2
+# Pass only task + project UUIDs — the chorus-pi extension auto-injects the
+# session UUID + workflow into each worker's task.
+# The composite call returns when every worker finishes (bundled subagent); each
+# nicobailon call returns a run receipt (async by default) — wait for the wave to
+# settle either way.
+# For a single task, single mode is all you need:
+#   subagent({ agent: "chorus-worker", task: "..." })
 ```
 
 **What the Team Lead prompt needs:**
 - Task UUID(s) + Project UUID
 - NO session UUID, NO workflow boilerplate — the extension auto-injects everything
-- No `agentId` to track and no close step — the blocking call owns the worker's whole lifecycle
+- No `agentId` to track and no close step — the dispatch owns the worker's whole lifecycle
 
 ### Sub-Agent Workflow
 
@@ -338,7 +354,7 @@ chorus_submit_for_verify({ taskUuid: "<my-task-uuid>", summary: "..." })
 
 # The worker's final message is returned to the Team Lead as the subagent result.
 # DO NOT call chorus_close_session — the extension closes the session when the
-# blocking `subagent` call returns.
+# dispatch returns (blocking) or when the run settles (async).
 ```
 
 ### Handling Task Dependencies (DAG)
@@ -347,12 +363,12 @@ chorus_submit_for_verify({ taskUuid: "<my-task-uuid>", summary: "..." })
 
 **Wave-based execution (recommended):**
 1. `chorus_get_unblocked_tasks` — find ready tasks
-2. Dispatch a `chorus-worker` per ready task in ONE blocking `subagent({ tasks: [...] })` call (max 8; batch if more). The call returns when the whole wave has finished (each worker at `to_verify`).
+2. Dispatch a `chorus-worker` per ready task as one wave — one `subagent({ tasks: [...] })` call under the bundled subagent (max 8; batch if more), or one `subagent({ agent, task })` call per ready task under nicobailon `pi-subagents` (which rejects top-level `tasks`). Wait for the whole wave to settle (each worker at `to_verify`): the bundled call returns when its workers exit; under nicobailon each call returns a run receipt, so wait on the run notifications / `bg_wait`.
 3. **Verify each task** — spawn `chorus-task-reviewer`, act on its VERDICT, then `chorus_admin_verify_task` → `done`.
 4. `chorus_get_unblocked_tasks` — find newly unblocked tasks (Wave 2)
 5. Repeat until all tasks done
 
-> **Critical:** `to_verify` does NOT resolve dependencies — only `done` or `closed` does. The Team Lead must verify tasks between waves. The blocking `subagent` call already released each worker's slot on return, so there is nothing to close.
+> **Critical:** `to_verify` does NOT resolve dependencies — only `done` or `closed` does. The Team Lead must verify tasks between waves. The dispatch already released each worker's slot once the wave settled, so there is nothing to close.
 
 ### Multiple Tasks Per Sub-Agent
 
@@ -365,7 +381,7 @@ subagent({
 })
 ```
 
-For strictly dependent stages where each step consumes the previous output, use chain mode: `subagent({ chain: [{ agent: "chorus-worker", task: "..." }, { agent: "chorus-worker", task: "... {previous} ..." }] })`.
+For strictly dependent stages where each step consumes the previous output, use chain mode — **bundled subagent only** (nicobailon `pi-subagents` has no top-level `chain`; run its stages as separate dispatches, or as `workflowScript` steps, which the session hook cannot reach): `subagent({ chain: [{ agent: "chorus-worker", task: "..." }, { agent: "chorus-worker", task: "... {previous} ..." }] })`.
 
 ### MCP Access for Sub-Agents
 

package/skills/docs/SKILL.md

@@ -4,7 +4,7 @@ description: Chorus documentation router — consult the live Chorus docs site t
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.18.0"
+  version: "0.19.0"
   category: project-management
   mcp_server: chorus
 ---

package/skills/idea/SKILL.md

@@ -4,7 +4,7 @@ description: Chorus Idea workflow — claim ideas, run elaboration rounds, and p
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.18.0"
+  version: "0.19.0"
   category: project-management
   mcp_server: chorus
 ---

package/skills/openspec-aware/SKILL.md

@@ -4,7 +4,7 @@ description: OpenSpec-mode authoring for Chorus PM workflows in Pi. The default
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.18.0"
+  version: "0.19.0"
   category: project-management
   mcp_server: chorus
 ---

package/skills/orchestrate/SKILL.md

@@ -4,7 +4,7 @@ description: Multi-agent orchestration playbook — coordinate OTHER agents and
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.18.0"
+  version: "0.19.0"
   category: project-management
   mcp_server: chorus
 ---
@@ -77,7 +77,7 @@ The extension ships three read-only reviewer subagents. As orchestrator you spaw
 | `chorus-task-reviewer` | a task is submitted for verify | one task vs its acceptance criteria (VERDICT on the task) |
 | `chorus-code-reviewer` | the idea's last task is verified | the idea's **aggregate** code change — the final ship gateway (VERDICT on the idea) |
 
-Spawn a reviewer via `subagent_spawn` with the reviewer skill and the target UUID; after it posts, `subagent_manage close` it to release Pi's concurrency slot. Each posts exactly one `VERDICT: PASS` / `PASS WITH NOTES` / `FAIL` comment. Verdicts are **advisory** — they do not auto-approve, auto-verify, or hard-block; you read the BLOCKERs and decide. A `FAIL` means route the BLOCKERs back for a fix before advancing (for a code-review FAIL, add fix tasks to the *approved* proposal via `/skill:quick-dev` and re-run once they are `done`). See `/skill:review` for the full pattern.
+Dispatch a reviewer with the `subagent` tool — `{ agent: "chorus-proposal-reviewer" | "chorus-task-reviewer" | "chorus-code-reviewer", task: "<target UUID> + what to review" }` — and wait for its VERDICT comment. There is no handle to close and no slot to release: the dispatch owns the child's lifecycle, and a reviewer gets no Chorus session. Each posts exactly one `VERDICT: PASS` / `PASS WITH NOTES` / `FAIL` comment. Verdicts are **advisory** — they do not auto-approve, auto-verify, or hard-block; you read the BLOCKERs and decide. A `FAIL` means route the BLOCKERs back for a fix before advancing (for a code-review FAIL, add fix tasks to the *approved* proposal via `/skill:quick-dev` and re-run once they are `done`). See `/skill:review` for the full pattern.
 
 ---
 

package/skills/proposal/SKILL.md

@@ -4,7 +4,7 @@ description: Chorus Proposal workflow — create proposals with document and tas
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.18.0"
+  version: "0.19.0"
   category: project-management
   mcp_server: chorus
 ---

package/skills/quick-dev/SKILL.md

@@ -4,7 +4,7 @@ description: Quick Task workflow — skip Idea→Proposal, create tasks directly
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.18.0"
+  version: "0.19.0"
   category: project-management
   mcp_server: chorus
 ---
@@ -152,7 +152,7 @@ chorus_submit_for_verify({
 })
 ```
 
-Submitting is not final verification. Spawn the required task-reviewer agent with `subagent_spawn` as described in `/skill:develop`, wait for it, and read THIS round's `VERDICT:` Task comment — the one posted after your dispatch, not an older round's. `PASS` and `PASS WITH NOTES` continue. On `FAIL`, do not verify or hand off: fix every unresolved BLOCKER, repeat AC self-check and submission, then run a fresh independent task review.
+Submitting is not final verification. Dispatch the required `chorus-task-reviewer` with the `subagent` tool as described in `/skill:develop`, wait for its VERDICT, and read THIS round's `VERDICT:` Task comment — the one posted after your dispatch, not an older round's. `PASS` and `PASS WITH NOTES` continue. On `FAIL`, do not verify or hand off: fix every unresolved BLOCKER, repeat AC self-check and submission, then run a fresh independent task review.
 
 ### Step 8: Permission-Aware Verification
 

package/skills/review/SKILL.md

@@ -4,7 +4,7 @@ description: Chorus Review workflow — approve/reject proposals, verify tasks,
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.18.0"
+  version: "0.19.0"
   category: project-management
   mcp_server: chorus
 ---
@@ -64,7 +64,7 @@ Key responsibilities:
 
 When reviewing proposals, tasks, or an Idea's final aggregate code change, prefer spawning an independent reviewer sub-agent over reviewing manually:
 
-1. **Try the reviewer first.** Spawn `chorus-proposal-reviewer` (for proposals), `chorus-task-reviewer` (for tasks), or `chorus-code-reviewer` (the final ship-time gateway over an Idea's aggregate code change, after its last task is verified — pass the `ideaUuid`; it posts its VERDICT on the **idea**) as a read-only sub-agent. **Use the blocking `subagent` tool** (it waits for the VERDICT and returns it) — you must wait for the VERDICT before proceeding. It posts a VERDICT comment with detailed findings.
+1. **Try the reviewer first.** Spawn `chorus-proposal-reviewer` (for proposals), `chorus-task-reviewer` (for tasks), or `chorus-code-reviewer` (the final ship-time gateway over an Idea's aggregate code change, after its last task is verified — pass the `ideaUuid`; it posts its VERDICT on the **idea**) as a read-only sub-agent. **Spawn it with the `subagent` tool and wait for its VERDICT** — you must wait before proceeding. The verdict is the VERDICT comment it posts on the entity, not the call's return value, so read the comment (step 2). It posts a VERDICT comment with detailed findings.
 2. **Read the VERDICT.** After the reviewer completes, call `chorus_get_comments` and find THIS round's `VERDICT:` comment — the one posted after your dispatch, not an older round's. There are exactly three possible outcomes:
    - **VERDICT: PASS** — No issues found. Approve (proposals) or mark AC passed and verify (tasks).
    - **VERDICT: PASS WITH NOTES** — Minor non-blocking notes. Still approve/verify. Notes are informational.
@@ -145,7 +145,7 @@ chorus_get_comments({ targetType: "proposal", targetUuid: "<proposal-uuid>" })
 
 #### A3.5: Independent Review
 
-Spawn `chorus-proposal-reviewer` per the [Review Strategy](#review-strategy) above — use the blocking `subagent` tool (it waits). Read its VERDICT comment before proceeding.
+Spawn `chorus-proposal-reviewer` per the [Review Strategy](#review-strategy) above — spawn it with the `subagent` tool and wait for its VERDICT. Read its VERDICT comment before proceeding.
 
 #### A4: Approve or Reject
 
@@ -210,14 +210,14 @@ chorus_get_comments({ targetType: "task", targetUuid: "<task-uuid>" })
 
 #### B2.5: Independent Review
 
-Spawn `chorus-task-reviewer` per the [Review Strategy](#review-strategy) above — use the blocking `subagent` tool (it waits). After it completes, read its VERDICT:
+Spawn `chorus-task-reviewer` per the [Review Strategy](#review-strategy) above — spawn it with the `subagent` tool and wait for its VERDICT. After it completes, read its VERDICT:
 
 - **VERDICT: PASS** or **PASS WITH NOTES** → proceed to B3 (mark AC) and B4 (verify).
 - **VERDICT: FAIL** → skip to B4 and **reopen** the task. Do NOT mark AC as passed.
 
 #### B2.6: Final Code-Review Gateway (after an Idea's LAST task is verified)
 
-When the task you just verified is the **last** task of its idea-rooted proposal, run the ship-time code-review gateway before the Idea's code is considered shipped. The the extension injects a reminder to spawn `chorus-code-reviewer` (gated by `enableCodeReviewer`, default on). Spawn it per the [Review Strategy](#review-strategy) — via the blocking `subagent` tool, passing the `ideaUuid` + round number. It reviews the Idea's **aggregate** code change across all its tasks — cross-task integration, architecture/convention consistency, security, regression/performance, feature-level test coverage — dimensions a single-task review cannot see — and posts one `VERDICT` comment on the **idea**.
+When the task you just verified is the **last** task of its idea-rooted proposal, run the ship-time code-review gateway before the Idea's code is considered shipped. The the extension injects a reminder to spawn `chorus-code-reviewer` (gated by `enableCodeReviewer`, default on). Spawn it per the [Review Strategy](#review-strategy) — with the `subagent` tool, passing the `ideaUuid` + round number. It reviews the Idea's **aggregate** code change across all its tasks — cross-task integration, architecture/convention consistency, security, regression/performance, feature-level test coverage — dimensions a single-task review cannot see — and posts one `VERDICT` comment on the **idea**.
 
 - **VERDICT: PASS** / **PASS WITH NOTES** → the feature may ship.
 - **VERDICT: FAIL** → do not reopen the verified tasks; instead add new fix tasks to the approved proposal via `/skill:quick-dev` (`chorus_create_tasks` with `proposalUuid` set to the current approved proposal so the fix tasks attach to it). Group related small BLOCKERs by default; split only materially large or independently testable fixes. Require AC self-check, independent task review, and admin verification for every fix task. Re-run aggregate review only after every fix is successfully `done`; a failed or cancelled fix stops the loop and escalates. Bounded by `CHORUS_MAX_CODE_REVIEW_ROUNDS` (env, default 3; 0 = unlimited).
@@ -339,7 +339,7 @@ chorus_pm_update_document({ documentUuid: "<doc-uuid>", content: "Updated..." })
 - **Unblock the team** — Prioritize proposal reviews to keep PM and Developer work flowing
 - **Use delete sparingly** — Prefer closing over deleting; closing preserves history
 - **Document decisions** — Use comments to explain approval/rejection reasoning
-- **Verify between waves** — In parallel-subagent mode, verify tasks to `done` between waves to unblock downstream dependencies (and `subagent_manage close` finished workers to release their slots)
+- **Verify between waves** — In wave mode, verify tasks to `done` between waves to unblock downstream dependencies; each worker's dispatch/run owns its own lifecycle, so there is no handle to close
 
 ---
 

package/skills/spec-lite/SKILL.md

@@ -4,7 +4,7 @@ description: Lightweight, Chorus-native local specs for Chorus PM workflows in P
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.18.0"
+  version: "0.19.0"
   category: project-management
   mcp_server: chorus
 ---

package/skills/yolo/SKILL.md

@@ -4,7 +4,7 @@ description: Full-auto AI-DLC pipeline — from prompt to done. Automates the en
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.18.0"
+  version: "0.19.0"
   category: project-management
   mcp_server: chorus
 ---
@@ -266,7 +266,7 @@ In /yolo mode, the agent generates elaboration questions and answers them itself
    ```
    chorus_pm_submit_proposal({ proposalUuid: "<proposal-uuid>" })
    ```
-   After this call, the extension nudges you to spawn `chorus-proposal-reviewer`. You MUST spawn it yourself via the blocking `subagent` tool (it waits for the VERDICT) — it is NOT auto-launched.
+   After this call, the extension nudges you to spawn `chorus-proposal-reviewer`. You MUST spawn it yourself with the `subagent` tool and wait for its VERDICT — it is NOT auto-launched.
 
 ---
 
@@ -274,7 +274,7 @@ In /yolo mode, the agent generates elaboration questions and answers them itself
 
 Every gate in Phases 2, 4 and 4.5 follows the same three steps. They are written once here; the phases below only name their entity and their stage-specific actions.
 
-1. **Spawn and wait.** Spawn the reviewer as a read-only sub-agent, then wait for it: spawn it via the blocking `subagent` tool, which waits for the reviewer to finish. Read the verdict from the reviewer's `VERDICT:` comment on the entity.
+1. **Spawn and wait.** Spawn the reviewer as a read-only sub-agent, then wait for it to finish. Read the verdict from the reviewer's `VERDICT:` comment on the entity — the verdict is that comment, not the dispatch's return value.
 2. **Read THIS round's VERDICT.** Call `chorus_get_comments` on the entity and find the `VERDICT:` comment posted **after your dispatch**, not an older round's. Do not advance the gate before you have read it.
 3. **No VERDICT for this round?** Check what the reviewer *did* post:
    - **A reported round limit, or any other explicit refusal to review** — a deliberate escalation to a human. STOP: do not respawn, do not self-review, do not post a VERDICT of your own.
@@ -286,7 +286,7 @@ Every gate in Phases 2, 4 and 4.5 follows the same three steps. They are written
 
 ### Phase 2: Proposal Review Loop
 
-After `chorus_pm_submit_proposal`, the extension nudges you to spawn `chorus-proposal-reviewer`. You MUST manually spawn it as a read-only sub-agent via the blocking `subagent` tool (it waits for the VERDICT). Wait for it to complete, then:
+After `chorus_pm_submit_proposal`, the extension nudges you to spawn `chorus-proposal-reviewer`. You MUST manually spawn it as a read-only sub-agent with the `subagent` tool and wait for its VERDICT. Wait for it to complete, then:
 
 1. **Read the reviewer's VERDICT:**
    ```
@@ -336,7 +336,7 @@ After proposal approval, tasks exist in `open` status. Execute them in dependenc
 
 #### Primary: subagent parallel dispatch (wave-based)
 
-The `subagent` tool is **blocking** — a parallel dispatch runs every worker in the wave to completion and returns their aggregated output in one call. There is no async spawn, no `agentId` to track, and no manual close. The chorus-pi extension auto-injects each worker's Chorus session UUID + workflow at `tool_call` time and closes the sessions when the dispatch returns.
+The **dispatch shape and the run mode both depend on the installed implementation**: the bundled subagent takes one composite call (`subagent({ tasks: [...] })`, max 8 per call, concurrency 4) and is blocking (the call returns when every worker in the wave has exited); nicobailon `pi-subagents` takes **one single dispatch per worker** (its public tool rejects top-level `tasks`/`chain` before dispatch) and is **async/background by default** (each call returns a run receipt; completion arrives on the run notification / `bg_wait`). Either way there is no `agentId` to track and no manual close. The chorus-pi extension auto-injects each worker's Chorus session UUID + workflow at `tool_call` time and closes the sessions when the dispatch returns (blocking) or when the run settles (`subagent:async-complete` / `process-terminal`).
 
 ```
 wave = 1
@@ -352,32 +352,42 @@ loop:
     # Stuck -- tasks failed review and can't proceed
     break with escalation report
 
-  # 2. Dispatch one chorus-worker per unblocked task in a SINGLE blocking
-  #    parallel call. Max 8 tasks per call (concurrency 4) — if the wave has
-  #    more than 8 ready tasks, split into batches of <=8 sequential calls.
+  # 2. Dispatch one chorus-worker per unblocked task as a single wave.
+  #    Shape follows the installed implementation:
+  #      bundled subagent    → ONE composite call (max 8 tasks/call,
+  #        concurrency 4; a bigger wave splits into batches of <=8 calls)
+  #      nicobailon          → ONE single dispatch per worker, issued together
+  #        (it rejects top-level `tasks`/`chain` before dispatch)
   #    Pass only task + project UUIDs; the chorus-pi extension auto-injects the
   #    session UUID + workflow into each worker's task at tool_call time.
   subagent({
     tasks: [
       { agent: "chorus-worker",
         task: "Your Chorus task UUID: {task.uuid}\nProject UUID: {project-uuid}\n\nImplement the task per its description and acceptance criteria. Read the task, proposal, and project documents for context." },
-      // ... one entry per unblocked task, max 8
+      // ... one entry per unblocked task, max 8  (bundled subagent only)
     ]
   })
-  # The call BLOCKS until EVERY worker in the wave finishes. Each worker follows
+  # ... or, under nicobailon `pi-subagents`, one call per worker in the wave:
+  subagent({ agent: "chorus-worker", task: "Your Chorus task UUID: {task.uuid}\n..." })  # worker 1
+  subagent({ agent: "chorus-worker", task: "Your Chorus task UUID: {task.uuid}\n..." })  # worker 2
+  # Wait for the whole wave to settle — the bundled composite call returns when
+  # every worker finishes; under nicobailon each call returns a run receipt, so
+  # wait on the run notifications / `bg_wait`. Each worker follows
   # the /skill:develop workflow: claim -> in_progress -> report -> self-check AC
   # -> submit_for_verify (leaving its task at to_verify).
-  # For a single ready task, use single mode instead:
+  # For a single ready task, single mode is all you need:
   #   subagent({ agent: "chorus-worker", task: "..." })
 
   # 3. Proceed to Phase 4 (verification) for this wave
   wave += 1
 ```
 
+> Do **not** dispatch Chorus workers from a `workflowScript` — children created there are invisible to the extension's session hook, so they would get no Chorus session. One call per worker (or one bundled `tasks` composite) is the supported shape.
+
 **What each worker task needs:**
 - Task UUID + Project UUID
 - NO session UUID, NO workflow boilerplate -- the extension auto-injects via tool_call mutation
-- No `agentId` and no close step — the blocking call owns the worker's whole lifecycle
+- No `agentId` and no close step — the dispatch owns the worker's whole lifecycle
 
 
 #### Fallback: Main Agent (sequential)
@@ -418,7 +428,7 @@ for each task in wave_tasks:
     continue
 
   # 2. Spawn chorus-task-reviewer (the extension nudges you; you must spawn it yourself)
-  #    Use the blocking `subagent` tool (it waits for the VERDICT before returning)
+  #    Use the `subagent` tool and wait for its VERDICT comment
   subagent({ agent: "chorus-task-reviewer", task: "Review task <task-uuid>..." })
 
   # 3. Read task-reviewer VERDICT
@@ -467,7 +477,7 @@ Continue with remaining tasks -- do not halt the entire pipeline for one stuck t
 
 ### Phase 4.5: Code-Review Gateway (mandatory pre-ship)
 
-Once **every** task of the idea's proposal is verified (`done`) — i.e. Phase 3 finds no more unblocked tasks and all are terminal — run the final ship-time code-review gateway **before** declaring the Idea done and **before** the Phase 5b completion report. After the last task is verified, the extension nudges you to spawn the code-reviewer; you MUST spawn it yourself via the blocking `subagent` tool (it waits for the VERDICT).
+Once **every** task of the idea's proposal is verified (`done`) — i.e. Phase 3 finds no more unblocked tasks and all are terminal — run the final ship-time code-review gateway **before** declaring the Idea done and **before** the Phase 5b completion report. After the last task is verified, the extension nudges you to spawn the code-reviewer; you MUST spawn it yourself with the `subagent` tool and wait for its VERDICT.
 
 ```
 # Spawn the code-reviewer for the IDEA (not a task). Determine the round