@chorus-aidlc/chorus 0.18.0 → 0.19.0

package/.next/standalone/public/chorus-plugin/agents/task-reviewer.md

@@ -12,10 +12,13 @@ disallowedTools:
 criticalSystemReminder_EXPERIMENTAL: >
   CRITICAL: READ-ONLY task review. You CANNOT edit, write, or create files in the project directory.
   Bash is READ-ONLY: only test/build commands, cat, grep, ls, git diff/log/show. No git write ops, no rm/mv/cp, no file writes.
-  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.
   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.
+  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 the command you actually re-ran. 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.
   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.
   Do NOT confirm — find what's wrong. Be efficient: batch data gathering, then one final comment.
 ---
@@ -91,6 +94,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.
@@ -112,15 +128,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.
@@ -133,14 +194,20 @@ 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 — `<command you re-ran>` → <result observed>
+- B1-<other-slug>: still-open — `<command you re-ran>` → <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]
@@ -150,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 — that evidence is unbounded, so never truncate it to shorten the comment. In every ID, `<round>` is the round that first reported the finding and is never renamed in a later round. 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. No preamble, no summary paragraph.
 
 === POSTING RESULTS ===
 Post the full results as a single comment:

package/.next/standalone/public/chorus-plugin/bin/chorus-api.sh

@@ -292,7 +292,7 @@ cmd_mcp_tool() {
     # Step 1: Initialize MCP session
     local init_payload
     init_payload=$(cat <<JSONEOF
-{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"chorus-hook","version":"0.18.0"}}}
+{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"chorus-hook","version":"0.19.0"}}}
 JSONEOF
 )
 

package/.next/standalone/public/chorus-plugin/bin/on-pre-spawn-agent.sh

@@ -28,27 +28,35 @@ fi
 CHORUS_SESSION_ID=$(printf '%s' "$EVENT" | jq -r '.session_id // .sessionId // empty' 2>/dev/null) || true
 export CHORUS_SESSION_ID
 
-# Try to extract subagent_type and name from the tool input
+# Try to extract subagent_type and name from the tool input.
+# `tool_input.name` does not exist on CC's Task tool today — it is read for
+# forward-compatibility and falls back to subagent_type, which is the value the
+# SubagentStart hook also receives as agent_type (and uses as the session name).
 AGENT_TYPE=""
 AGENT_NAME=""
 if [ -n "$EVENT" ]; then
   AGENT_TYPE=$(echo "$EVENT" | jq -r '.tool_input.subagent_type // .input.subagent_type // empty' 2>/dev/null) || true
   AGENT_NAME=$(echo "$EVENT" | jq -r '.tool_input.name // .input.name // empty' 2>/dev/null) || true
 fi
+AGENT_NAME="${AGENT_NAME:-$AGENT_TYPE}"
 
-# Skip non-worker types — no need to remind for Explore/Plan agents
+# Skip non-worker types — no need to remind for Explore/Plan agents.
+# This list MUST stay identical to the skip list in on-subagent-start.sh:
+# a type skipped by only one hook leaves an orphan pending file that a later
+# internal/cleanup agent could FIFO-claim, defeating the spawn gate.
 case "$(printf '%s' "$AGENT_TYPE" | tr '[:upper:]' '[:lower:]')" in
-  explore|plan|haiku|claude-code-guide|statusline-setup)
+  explore|plan|haiku|claude-code-guide|statusline-setup|chorus:proposal-reviewer|chorus:task-reviewer)
     exit 0
     ;;
 esac
 
 # Write a per-agent pending file for SubagentStart to claim.
-# SubagentStart only receives agent_id + agent_type — not the name.
-# CC sometimes uses the agent name as agent_type, so we store both.
+#
+# The pending file is a SPAWN GATE, not a name channel: its presence proves a
+# SubagentStart came from a real Task spawn. The session name is derived by
+# on-subagent-start.sh from the event's own agent_type, never from this file.
 #
 # Each spawn gets its own file — no shared state, no concurrency issues.
-# File name is the agent name (or a unique fallback if name is empty).
 # SubagentStart claims by mv (atomic on same filesystem).
 #
 # CC may internally spawn cleanup agents that bypass PreToolUse:Task —
@@ -59,10 +67,15 @@ esac
 PENDING_DIR="${CHORUS_STATE_DIR:-${CLAUDE_PROJECT_DIR:-.}/.chorus}/pending"
 mkdir -p "$PENDING_DIR" 2>/dev/null || true
 
-# Use agent name as filename; fall back to timestamp-based unique name
-PENDING_NAME="${AGENT_NAME:-unknown-$(date +%s%N)}"
+# Filename stem: sanitized subagent_type (":" and "/" in namespaced types such as
+# chorus:code-reviewer become "_"), plus epoch seconds and the PID for uniqueness.
+# $$ is required: BSD date (macOS) has no %N, so two same-second spawns of the same
+# type would otherwise collide on a single filename and one would be lost.
+PENDING_STEM=$(printf '%s' "${AGENT_TYPE:-worker}" | tr -c '[:alnum:]._-' '_')
+[ -z "$PENDING_STEM" ] && PENDING_STEM="worker"
+PENDING_NAME="${PENDING_STEM}__$(date +%s)-$$"
 printf '{"name":"%s","type":"%s","ts":"%s"}\n' \
-  "${AGENT_NAME:-}" "${AGENT_TYPE:-}" "$(date -u +%Y-%m-%dT%H:%M:%S.%3NZ)" \
+  "${AGENT_NAME:-}" "${AGENT_TYPE:-}" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
   > "${PENDING_DIR}/${PENDING_NAME}"
 
 CONTEXT="[Chorus Plugin — Sub-agent Spawn]

package/.next/standalone/public/chorus-plugin/bin/on-subagent-start.sh

@@ -2,8 +2,12 @@
 # on-subagent-start.sh — SubagentStart hook
 # Triggered SYNCHRONOUSLY when a sub-agent (teammate) is spawned.
 #
-# Name resolution: Claims a per-agent pending file written by PreToolUse:Task
-# using atomic mv (only one process can successfully mv a given file).
+# Name resolution: the session name is the event's own agent_type (the value the
+# spawning Task call passed as subagent_type), falling back to worker-<agentId8>.
+#
+# Spawn gate: claims a per-spawn pending file written by PreToolUse:Task using
+# atomic mv (only one process can successfully mv a given file). The file only
+# proves the spawn was a real Task call — it never carries the name.
 #
 # Session reuse logic:
 #   1. List existing sessions via MCP
@@ -45,14 +49,14 @@ export CHORUS_SESSION_ID
 [ -f "${SCRIPT_DIR}/chorus-paths.sh" ] && { . "${SCRIPT_DIR}/chorus-paths.sh" 2>/dev/null || true; }
 CHORUS_STATE_DIR="${CHORUS_STATE_DIR:-${CLAUDE_PROJECT_DIR:-.}/.chorus}"
 
-# Extract agent info from event
-# Note: SubagentStart only provides agent_id and agent_type — NOT the name
-# from the Task tool call. The name is captured by on-pre-spawn-agent.sh
-# (PreToolUse:Task) and stored as a per-agent file in .chorus/pending/.
+# Extract agent info from event.
+# agent_type is the same value the spawning Task call passed as subagent_type,
+# so it is the session name source (see SESSION_NAME below).
 AGENT_ID=$(echo "$EVENT" | jq -r '.agent_id // .agentId // empty' 2>/dev/null) || true
 AGENT_TYPE=$(echo "$EVENT" | jq -r '.agent_type // .agentType // empty' 2>/dev/null) || true
 
-# Skip non-worker agent types (read-only agents don't need sessions)
+# Skip non-worker agent types (read-only agents don't need sessions).
+# This list MUST stay identical to the skip list in on-pre-spawn-agent.sh.
 case "$(printf '%s' "$AGENT_TYPE" | tr '[:upper:]' '[:lower:]')" in
   explore|plan|haiku|claude-code-guide|statusline-setup|chorus:proposal-reviewer|chorus:task-reviewer)
     exit 0
@@ -66,35 +70,24 @@ fi
 # Claim a pending file written by PreToolUse:Task (on-pre-spawn-agent.sh).
 # Each pending file represents one expected sub-agent spawn.
 #
-# Claim strategy (atomic mv — only one process can succeed per file):
-#   1. Try exact match: mv .chorus/pending/{agent_type} → claimed/{agent_id}
-#      (CC often sets agent_type to the name from the Task tool call)
-#   2. Fallback: claim the oldest pending file (FIFO by modification time)
+# The pending file is a SPAWN GATE, not a name channel: it only proves this
+# SubagentStart corresponds to a real Task spawn. Neither its filename nor its
+# contents influence the session name, so plain FIFO claiming is safe even when a
+# mixed parallel batch pairs this agent with another spawn's file.
 #
-# If no pending file exists, this is an internal/cleanup agent → skip.
-AGENT_NAME=""
+# Claim strategy: FIFO by modification time, atomic mv (only one process can
+# succeed per file). If no pending file can be claimed, this is one of Claude
+# Code's internal/cleanup agents (they bypass PreToolUse:Task) → skip.
 PENDING_DIR="${CHORUS_STATE_DIR}/pending"
 CLAIMED_DIR="${CHORUS_STATE_DIR}/claimed"
 mkdir -p "$CLAIMED_DIR" 2>/dev/null || true
 
 CLAIMED_FILE=""
 
-# Strategy 1: exact match by agent_type (CC uses name as agent_type)
-if [ -f "${PENDING_DIR}/${AGENT_TYPE}" ]; then
-  if mv "${PENDING_DIR}/${AGENT_TYPE}" "${CLAIMED_DIR}/${AGENT_ID}" 2>/dev/null; then
-    CLAIMED_FILE="${CLAIMED_DIR}/${AGENT_ID}"
-    AGENT_NAME="$AGENT_TYPE"
-  fi
-fi
-
-# Strategy 2: FIFO — claim oldest pending file
-if [ -z "$CLAIMED_FILE" ] && [ -d "$PENDING_DIR" ]; then
+if [ -d "$PENDING_DIR" ]; then
   for candidate in $(ls -tr "$PENDING_DIR" 2>/dev/null); do
     if mv "${PENDING_DIR}/${candidate}" "${CLAIMED_DIR}/${AGENT_ID}" 2>/dev/null; then
       CLAIMED_FILE="${CLAIMED_DIR}/${AGENT_ID}"
-      # Read name from file content if available
-      FILE_NAME=$(jq -r '.name // empty' "$CLAIMED_FILE" 2>/dev/null) || true
-      AGENT_NAME="${FILE_NAME:-$candidate}"
       break
     fi
     # mv failed → another process claimed it first, try next
@@ -106,8 +99,17 @@ if [ -z "$CLAIMED_FILE" ]; then
   exit 0
 fi
 
-# Fallback: use agent_type + short ID if no name was captured
-SESSION_NAME="${AGENT_NAME:-${AGENT_TYPE:-worker}-${AGENT_ID:0:8}}"
+# Session name comes from this event's own agent_type (the same value the Task
+# call passed as subagent_type). Falls back to an agent-id-derived name only when
+# agent_type is empty — never a placeholder like "unknown-<digits>".
+SESSION_NAME="${AGENT_TYPE:-worker-${AGENT_ID:0:8}}"
+
+# Sanitized form for on-disk filenames only. Namespaced types such as
+# chorus:code-reviewer are not skipped, so they reach this path and must not put
+# a ":" or "/" into a path. The name sent to Chorus, the state keys and the
+# injected workflow text all keep the raw agent_type.
+SESSION_NAME_FILE=$(printf '%s' "$SESSION_NAME" | tr -c '[:alnum:]._-' '_')
+[ -z "$SESSION_NAME_FILE" ] && SESSION_NAME_FILE="worker-${AGENT_ID:0:8}"
 
 # === Session reuse: list existing sessions, find by name ===
 SESSION_UUID=""
@@ -187,11 +189,24 @@ fi
 "$API" state-set "session_${SESSION_NAME}" "$SESSION_UUID"
 "$API" state-set "name_for_agent_${AGENT_ID}" "$SESSION_NAME"
 
+# === Holder refcount: register this agent as a holder of the session NAME ===
+# Because the name is the repeating agent_type, two parallel sub-agents of the
+# same type converge on ONE session (reuse-by-name above). on-subagent-stop.sh
+# removes its own entry here and only tears the shared session down when no other
+# holder remains — otherwise the first sibling to exit would close the session,
+# check the other sibling's task out and delete state its sibling still reads.
+# Registered on every path (created / reused / reopened). The directory component
+# uses the SAME sanitization as the sessions/<name>.json filename — a namespaced
+# type such as chorus:code-reviewer must never put a ":" or "/" into a path.
+HOLDERS_DIR="${CHORUS_STATE_DIR}/holders/${SESSION_NAME_FILE}"
+mkdir -p "$HOLDERS_DIR" 2>/dev/null || true
+: > "${HOLDERS_DIR}/${AGENT_ID}" 2>/dev/null || true
+
 # === Session file: minimal metadata for other hooks (TeammateIdle, SubagentStop) ===
 SESSIONS_DIR="${CHORUS_STATE_DIR}/sessions"
 mkdir -p "$SESSIONS_DIR" 2>/dev/null || true
 
-cat > "${SESSIONS_DIR}/${SESSION_NAME}.json" <<SESSIONEOF
+cat > "${SESSIONS_DIR}/${SESSION_NAME_FILE}.json" <<SESSIONEOF
 {
   "sessionUuid": "${SESSION_UUID}",
   "agentId": "${AGENT_ID}",

package/.next/standalone/public/chorus-plugin/bin/on-subagent-stop.sh

@@ -4,6 +4,12 @@
 # Auto-checkout from all checked-in tasks, close the Chorus session,
 # clean up state files, and auto-verify if admin AC all passed.
 #
+# Holder-aware: session names are the repeating agent_type, so parallel same-type
+# sub-agents SHARE one session. Teardown (checkout / close / name-keyed state /
+# sessions file / auto-verify) only happens for the LAST holder of the name — see
+# the holder refcount block below. Non-last stops clean up only their own
+# id-keyed state and leave the session running for their siblings.
+#
 # NOTE: SubagentStop does NOT support additionalContext in Claude Code's
 # hookSpecificOutput schema, and systemMessage only reaches the UI —
 # not the main agent's LLM context. All agent-facing reminders must go
@@ -54,47 +60,104 @@ if [ -z "$SESSION_UUID" ]; then
   exit 0
 fi
 
-# === Auto-checkout from all checked-in tasks ===
+# Sanitized form of the name for on-disk paths (same tr sanitization as
+# on-subagent-start.sh uses for sessions/<name>.json and holders/<name>/) —
+# namespaced types such as chorus:code-reviewer must not put a ":" into a path.
+# The state keys keep the raw name.
+AGENT_NAME_FILE=""
+if [ -n "$AGENT_NAME" ]; then
+  AGENT_NAME_FILE=$(printf '%s' "$AGENT_NAME" | tr -c '[:alnum:]._-' '_')
+fi
+
+# === Holder refcount: is this the LAST agent holding the session name? ===
+# Session names are the repeating agent_type, so two parallel sub-agents of the
+# same type share ONE session (reuse-by-name in on-subagent-start.sh). Remove our
+# OWN holder entry first, then count what remains: only the last holder may close
+# the session, auto-checkout, auto-verify or delete the name-keyed state that
+# siblings (and on-teammate-idle.sh) still read.
+#
+# Races are benign and must stay benign: if a sibling's start has not registered
+# its holder yet we may see 0 holders and close the session; that sibling's start
+# then finds a closed/inactive row and reopens it via the existing reopen path.
+# Deliberately no locking.
+#
+# With no name in state we cannot refcount — fall back to the legacy
+# single-agent behaviour (treat this stop as the last holder).
+HOLDERS_DIR=""
+HOLDERS_REMAINING=0
+if [ -n "$AGENT_NAME_FILE" ]; then
+  HOLDERS_DIR="${CHORUS_STATE_DIR}/holders/${AGENT_NAME_FILE}"
+  rm -f "${HOLDERS_DIR}/${AGENT_ID}" 2>/dev/null || true
+  if [ -d "$HOLDERS_DIR" ]; then
+    HOLDERS_REMAINING=$(ls -1 "$HOLDERS_DIR" 2>/dev/null | grep -c . || true)
+  fi
+fi
+[ -n "$HOLDERS_REMAINING" ] || HOLDERS_REMAINING=0
+
+IS_LAST_HOLDER=true
+if [ "$HOLDERS_REMAINING" -gt 0 ]; then
+  IS_LAST_HOLDER=false
+fi
+
+# === Auto-checkout from all checked-in tasks (last holder only) ===
+# Open checkins on a shared session may belong to a still-running sibling, so a
+# non-last stop must not check them out — each sub-agent checks its own task out
+# per the workflow injected by on-subagent-start.sh.
 CHECKOUT_COUNT=0
-SESSION_DETAIL=$("$API" mcp-tool "chorus_get_session" "$(printf '{"sessionUuid":"%s"}' "$SESSION_UUID")" 2>/dev/null) || true
+SESSION_DETAIL=""
+CLOSE_OK=true
 
-if [ -n "$SESSION_DETAIL" ]; then
-  TASK_UUIDS=$(echo "$SESSION_DETAIL" | jq -r '
-    .checkins[]? | select(.checkoutAt == null) | .taskUuid // empty
-  ' 2>/dev/null) || true
+if [ "$IS_LAST_HOLDER" = true ]; then
+  SESSION_DETAIL=$("$API" mcp-tool "chorus_get_session" "$(printf '{"sessionUuid":"%s"}' "$SESSION_UUID")" 2>/dev/null) || true
 
-  if [ -z "$TASK_UUIDS" ]; then
+  if [ -n "$SESSION_DETAIL" ]; then
     TASK_UUIDS=$(echo "$SESSION_DETAIL" | jq -r '
-      .sessionTaskCheckins[]? | select(.checkoutAt == null) | .taskUuid // empty
+      .checkins[]? | select(.checkoutAt == null) | .taskUuid // empty
     ' 2>/dev/null) || true
-  fi
 
-  for TASK_UUID in $TASK_UUIDS; do
-    if [ -n "$TASK_UUID" ]; then
-      "$API" mcp-tool "chorus_session_checkout_task" \
-        "$(printf '{"sessionUuid":"%s","taskUuid":"%s"}' "$SESSION_UUID" "$TASK_UUID")" \
-        >/dev/null 2>&1 || true
-      CHECKOUT_COUNT=$((CHECKOUT_COUNT + 1))
+    if [ -z "$TASK_UUIDS" ]; then
+      TASK_UUIDS=$(echo "$SESSION_DETAIL" | jq -r '
+        .sessionTaskCheckins[]? | select(.checkoutAt == null) | .taskUuid // empty
+      ' 2>/dev/null) || true
     fi
-  done
-fi
 
-# Close the Chorus session via MCP
-CLOSE_OK=true
-"$API" mcp-tool "chorus_close_session" "$(printf '{"sessionUuid":"%s"}' "$SESSION_UUID")" >/dev/null 2>&1 || CLOSE_OK=false
+    for TASK_UUID in $TASK_UUIDS; do
+      if [ -n "$TASK_UUID" ]; then
+        "$API" mcp-tool "chorus_session_checkout_task" \
+          "$(printf '{"sessionUuid":"%s","taskUuid":"%s"}' "$SESSION_UUID" "$TASK_UUID")" \
+          >/dev/null 2>&1 || true
+        CHECKOUT_COUNT=$((CHECKOUT_COUNT + 1))
+      fi
+    done
+  fi
 
-# Clean up state
+  # Close the Chorus session via MCP
+  "$API" mcp-tool "chorus_close_session" "$(printf '{"sessionUuid":"%s"}' "$SESSION_UUID")" >/dev/null 2>&1 || CLOSE_OK=false
+fi
+
+# Clean up state.
+# The id-keyed keys are this agent's own and always go. The name-keyed mapping and
+# the reverse map agent_for_session_<uuid> (single-valued — siblings overwrite it)
+# are shared, so they only go on the last-holder path.
 "$API" state-delete "session_${AGENT_ID}" 2>/dev/null || true
-"$API" state-delete "agent_for_session_${SESSION_UUID}" 2>/dev/null || true
 "$API" state-delete "name_for_agent_${AGENT_ID}" 2>/dev/null || true
-if [ -n "$AGENT_NAME" ]; then
-  "$API" state-delete "session_${AGENT_NAME}" 2>/dev/null || true
+if [ "$IS_LAST_HOLDER" = true ]; then
+  "$API" state-delete "agent_for_session_${SESSION_UUID}" 2>/dev/null || true
+  if [ -n "$AGENT_NAME" ]; then
+    "$API" state-delete "session_${AGENT_NAME}" 2>/dev/null || true
+  fi
 fi
 
-# Clean up session file
+# Clean up session file + holder dir (last holder only — siblings still read
+# sessions/<name>.json, see on-teammate-idle.sh).
 SESSIONS_DIR="${CHORUS_STATE_DIR}/sessions"
-if [ -n "$AGENT_NAME" ] && [ -f "${SESSIONS_DIR}/${AGENT_NAME}.json" ]; then
-  rm -f "${SESSIONS_DIR}/${AGENT_NAME}.json"
+if [ "$IS_LAST_HOLDER" = true ]; then
+  if [ -n "$AGENT_NAME_FILE" ] && [ -f "${SESSIONS_DIR}/${AGENT_NAME_FILE}.json" ]; then
+    rm -f "${SESSIONS_DIR}/${AGENT_NAME_FILE}.json"
+  fi
+  if [ -n "$HOLDERS_DIR" ] && [ -d "$HOLDERS_DIR" ]; then
+    rmdir "$HOLDERS_DIR" 2>/dev/null || true
+  fi
 fi
 
 # Clean up claimed file (written by SubagentStart)
@@ -104,7 +167,9 @@ if [ -n "$AGENT_ID" ] && [ -f "${CLAIMED_DIR}/${AGENT_ID}" ]; then
 fi
 
 # === Auto-verify: if admin marked all AC, verify the task automatically ===
-if [ "$CLOSE_OK" = true ] && [ -n "$SESSION_DETAIL" ]; then
+# Last holder only: on a shared session the first checkin may belong to a sibling,
+# so a non-last stop must never auto-verify another agent's task.
+if [ "$IS_LAST_HOLDER" = true ] && [ "$CLOSE_OK" = true ] && [ -n "$SESSION_DETAIL" ]; then
   FIRST_TASK_UUID=$(echo "$SESSION_DETAIL" | jq -r '
     (.checkins // .sessionTaskCheckins // [])[] | .taskUuid // empty
   ' 2>/dev/null | head -1) || true
@@ -144,7 +209,13 @@ fi
 
 # === Output (UI-only, not visible to main agent LLM) ===
 DISPLAY_NAME="${AGENT_NAME:-${AGENT_ID:0:8}}"
-if [ "$CLOSE_OK" = true ]; then
+if [ "$IS_LAST_HOLDER" != true ]; then
+  # Shared session still has live holders — do not claim it was closed.
+  "$API" hook-output \
+    "Chorus session '${DISPLAY_NAME}' kept open (${HOLDERS_REMAINING} other agent(s) still using it)" \
+    "" \
+    "SubagentStop"
+elif [ "$CLOSE_OK" = true ]; then
   USER_MSG="Chorus session closed: '${DISPLAY_NAME}'"
   if [ "$CHECKOUT_COUNT" -gt 0 ]; then
     USER_MSG="${USER_MSG} (auto-checkout ${CHECKOUT_COUNT} task(s))"

package/.next/standalone/public/chorus-plugin/bin/test-syntax.sh

@@ -140,8 +140,12 @@ assert_eq "no session id -> <slug>/no-session" \
 #    the global root, and does NOT create a .chorus/ in the project dir.
 printf '%s' '{"session_id":"sess-place","tool_input":{"subagent_type":"general-purpose","name":"placer"}}' \
   | "$BASH" "$DIR/on-pre-spawn-agent.sh" >/dev/null 2>&1 || true
-assert_true "pending file written under global root" \
-  test -f "${CHORUS_PLUGIN_STATE_ROOT}/${EXPECT_SLUG}/sess-place/pending/placer"
+# The pending filename is <sanitized subagent_type>__<epoch>-<pid>, never unknown-*.
+PENDING_PLACED="$( ls "${CHORUS_PLUGIN_STATE_ROOT}/${EXPECT_SLUG}/sess-place/pending" 2>/dev/null | head -1 )"
+case "$PENDING_PLACED" in
+  general-purpose__*) assert_true "pending file written under global root" true ;;
+  *)                  assert_true "pending file written under global root" false ;;
+esac
 assert_true "no .chorus/ created in project dir" \
   test ! -d "${CLAUDE_PROJECT_DIR}/.chorus"