@chorus-aidlc/chorus-pi 0.17.2 → 0.17.3

package/README.md

@@ -93,6 +93,93 @@ packages/chorus-pi/
 
 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.
 
+
+### 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
+`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
+main-agent wave template) are never re-injected.
+
+### Coexistence with nicobailon `pi-subagents`: load-order rule
+
+The bundled subagent (pi's official reference pattern, at `extensions/subagent/`)
+registers a tool named `subagent`. The nicobailon `pi-subagents` package registers
+a tool with the **same name**. pi's extension loader rejects a duplicate tool
+registration with a conflict error (verified on pi 0.84.4:
+`Tool "subagent" conflicts with ...`), so the two cannot both register.
+
+**Recommended setup (keep nicobailon, zero conflicts)**: exclude the bundled
+subagent extension via a package filter in `settings.packages` — pi's package
+entries accept an object form with per-resource glob patterns:
+
+```json
+"packages": [
+  "npm:pi-subagents",
+  {
+    "source": "git:github.com/Chorus-AIDLC/chorus/packages/chorus-pi",
+    "extensions": ["!extensions/subagent/**"]
+  }
+]
+```
+
+This keeps `chorus.ts` (session hooks) and the `agents/*.md` files (discovered
+via `pi.subagents.agents`) while the bundled `subagent` tool never registers —
+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, 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
+`subagent({ action: "list" })`. nicobailon output shows `Package agents /
+Builtin agents / User agents` sections; the bundled subagent's output has no
+such sections.
+
+### Tips when combining with nicobailon `pi-subagents`
+
+- **Sessions work with either tool.** Chorus hooks match on the tool name,
+  so `checkin → in_progress → report → checkout → submit_for_verify` flows are
+  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
+  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
+  that declares them as a failed run (exit 1) even if the agent never
+  called them. The Chorus reviewers/worker need `mcp` to post verdicts and
+  check in, so they run as background children (nicobailon default). Wait
+  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.
+- **`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.
+- **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
+  `model:` (it reads `name`/`description`/`tools`/`model`; its schema has no
+  per-call model parameter) — set it in `~/.pi/agent/agents/chorus-*-reviewer.md`.
+- **Agent files**: bundled subagent reads package `agents/*.md` + `~/.pi/agent/agents/*.md`
+  (user overrides package). nicobailon reads builtin/package/user/project with
+  richer frontmatter (`excludeTools`, `thinking`, `inheritSkills`, `extensions`,
+  per-agent `tools` allowlists, `model`, ...).
+- **Tool-name clash**: both register a `subagent` tool and pi rejects a duplicate
+  registration with a conflict error. To keep nicobailon (needed for its
+  async/`workflowScript` features), use the package filter above (exclude
+  `extensions/subagent/**`); if you instead rely on ordering, list
+  `npm:pi-subagents` **before** chorus-pi. Either way, verify with
+  `subagent({ action: "list" })` (nicobailon shows `Package/Builtin/User agents`
+  sections; bundled does not).
 ## License
 
 AGPL-3.0

package/agents/chorus-code-reviewer.md

@@ -1,7 +1,8 @@
 ---
 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.
-tools: read, grep, find, ls, bash, mcp
+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" }
 ---
 
 CRITICAL: READ-ONLY code review of an ENTIRE Idea's aggregate change. You CANNOT edit, write, or create files in the project directory.

package/agents/chorus-proposal-reviewer.md

@@ -1,7 +1,8 @@
 ---
 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.
-tools: read, grep, find, ls, bash, mcp
+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" }
 ---
 
 CRITICAL: READ-ONLY proposal review. You CANNOT edit, write, create files, or run Bash commands beyond read-only inspection.

package/agents/chorus-task-reviewer.md

@@ -1,7 +1,8 @@
 ---
 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.
-tools: read, grep, find, ls, bash, mcp
+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" }
 ---
 
 CRITICAL: READ-ONLY task review. You CANNOT edit, write, or create files in the project directory.

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.17.2"}}}
+{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"chorus-codex-hook","version":"0.17.3"}}}
 JSON
 )
 

package/extensions/chorus.ts

@@ -18,9 +18,13 @@
  *                              lacks (Codex has no pre-spawn mutation channel, so its
  *                              workers must manage sessions manually).
  *   - tool_result            → close the ephemeral worker session(s) once the `subagent`
- *                              tool call returns (the official children are ephemeral:
- *                              spawn → run → exit within one tool call, so there is no
- *                              persistent agentId and no separate close tool).
+ *   - tool_result            → for the official blocking subagent, close the ephemeral
+ *                              worker session(s) once the `subagent` tool call returns
+ *                              (spawn → run → exit within one tool call, so there is no
+ *                              persistent agentId and no separate close tool). For the
+ *                              nicobailon `pi-subagents` tool (async/detached by default,
+ *                              `details.asyncId` on tool_result) the sessions are deferred
+ *                              and closed on subagent:async-complete / process-terminal.
  *                            → reviewer nudges after submit_proposal / submit_for_verify
  *                              / admin_verify_task (the 3 PostToolUse hooks)
  *   - tool_execution_end     → fallback close of the worker session(s) if tool_result
@@ -40,6 +44,8 @@ import {
   isWorkerAgent,
   subagentTaskItems,
   sessionWorkflow,
+  hasSessionMarker,
+  extractRunIdFromToolResultEvent,
   detectOpenSpec,
   buildSessionBanner,
   parseMaxCodeReviewRounds,
@@ -196,6 +202,10 @@ async function mcpCall<T = unknown>(tool: string, args: Record<string, unknown>
 //
 // toolCallId → the Chorus session UUIDs created for that `subagent` invocation.
 const callSessions = new Map<string, string[]>();
+// runId (nicobailon async/detached `subagent` runs) → sessionUuid(s); closed on
+// subagent:async-complete / subagent:process-terminal (blocking runs close at
+// tool_result via callSessions and never enter this map).
+const runIdToSid = new Map<string, string[]>();
 let checkinContext: string | null = null;
 let injectedOnce = false;
 
@@ -360,6 +370,8 @@ export default function (pi: ExtensionAPI) {
     const created: string[] = [];
     for (const item of subagentTaskItems(event.input)) {
       if (!isWorkerAgent(item.agent)) continue;
+      // Manual main-agent template already injected — never double-inject.
+      if (hasSessionMarker(item.task)) continue;
       try {
         const session = await mcpCall<{ uuid?: string }>("chorus_create_session", { name: item.agent });
         if (!session?.uuid) continue;
@@ -382,10 +394,24 @@ export default function (pi: ExtensionAPI) {
     if (!CONFIGURED) return;
 
     // ── subagent tool finished → close the worker session(s) ───────────
-    // Close on success OR error: the sessions were created at tool_call start,
-    // so they must be closed either way. closeCallSessions is idempotent and
-    // retains any session whose close fails for a shutdown retry.
+    // The official blocking subagent closes sessions at tool_result; the
+    // nicobailon `pi-subagents` tool is async (detached) by default, so its
+    // tool_result carries `details.asyncId` and the run completes later via
+    // the pi event bus — in that case move the sessions to runIdToSid and
+    // let subagent:async-complete / subagent:process-terminal close them.
     if (event.toolName === "subagent") {
+      const runId = extractRunIdFromToolResultEvent(event);
+      if (runId) {
+        const sids = callSessions.get(event.toolCallId);
+        if (sids && sids.length > 0) {
+          runIdToSid.set(runId, [...(runIdToSid.get(runId) ?? []), ...sids]);
+          callSessions.delete(event.toolCallId);
+          ctx.ui.notify(`Chorus session(s): ${sids.map((s) => s.slice(0, 8)).join(",")}… deferred to async run ${runId.slice(0, 8)}…`, "info");
+        }
+        return;
+      }
+      // Blocking run (or no run id) — close now. closeCallSessions is
+      // idempotent and retains any session whose close fails for a shutdown retry.
       await closeCallSessions(event.toolCallId, ctx);
       return;
     }
@@ -431,20 +457,77 @@ export default function (pi: ExtensionAPI) {
   pi.on("tool_execution_end", async (event, ctx) => {
     if (!CONFIGURED) return;
     if (event.toolName === "subagent") {
+      // tool_result already moved async sessions to runIdToSid — nothing left
+      // in callSessions for them. Blocking runs (or failed injection) close here.
       await closeCallSessions(event.toolCallId, ctx);
     }
   });
 
+  // ── nicobailon async/detached `subagent` runs: close by runId ──────
+  // tool_result deferred these sessions to runIdToSid; completion arrives on
+  // the pi event bus. Delete the mapping BEFORE issuing the close so a
+  // duplicate lifecycle event cannot double-close; re-add on failure so the
+  // shutdown sweep can still retry it.
+  //
+  // In-flight closes are tracked so session_shutdown can await them before
+  // sweeping: a close that fails after the sweep ran would otherwise re-add
+  // its entry after the map was cleared (retry lost + stale entry).
+  const inflightCloses = new Set<Promise<void>>();
+  const closeRunSessions = (runId: string): void => {
+    const sids = runIdToSid.get(runId);
+    if (!sids || sids.length === 0) return;
+    runIdToSid.delete(runId);
+    const p: Promise<void> = (async () => {
+      const failed: string[] = [];
+      for (const sid of sids) {
+        try { await mcpCall("chorus_close_session", { sessionUuid: sid }); } catch { failed.push(sid); }
+      }
+      if (failed.length > 0) {
+        runIdToSid.set(runId, failed);
+        console.warn(`[chorus-pi] failed to close ${failed.length} session(s) for run ${runId}: ${failed.join(", ")} — will retry at session_shutdown`);
+      }
+    })();
+    inflightCloses.add(p);
+    void p.finally(() => inflightCloses.delete(p));
+  };
+  // Only `runId` is trusted on async-complete; `id` (runId-or-id shape) is
+  // accepted only on process-terminal, since async-complete could carry an
+  // unrelated id field alongside runId.
+  const eventBusRunId = (data: unknown, allowId: boolean): string | null => {
+    const d = (data ?? {}) as Record<string, unknown>;
+    if (typeof d.runId === "string" && d.runId) return d.runId;
+    if (allowId && typeof d.id === "string" && d.id) return d.id;
+    return null;
+  };
+  pi.events.on("subagent:async-complete", (data) => {
+    const runId = eventBusRunId(data, false);
+    if (runId) closeRunSessions(runId);
+  });
+  pi.events.on("subagent:process-terminal", (data) => {
+    const runId = eventBusRunId(data, true);
+    if (runId) closeRunSessions(runId);
+  });
+
   // SessionEnd → close any stray worker sessions (replaces Claude's on-session-end.sh).
   // Retries every session still tracked in callSessions (e.g. a subagent call whose
   // close failed and was retained, or that never saw a tool_result/tool_execution_end).
   pi.on("session_shutdown", async () => {
+    // Wait for in-flight async closes to settle FIRST: a close that fails
+    // re-adds into runIdToSid, and the sweep below must see it (otherwise the
+    // retry is lost and a stale entry survives the clear).
+    await Promise.allSettled([...inflightCloses]);
     for (const sids of callSessions.values()) {
       for (const sid of sids) {
         await mcpCall("chorus_close_session", { sessionUuid: sid }).catch(() => {});
       }
     }
+    for (const sids of runIdToSid.values()) {
+      for (const sid of sids) {
+        await mcpCall("chorus_close_session", { sessionUuid: sid }).catch(() => {});
+      }
+    }
     callSessions.clear();
+    runIdToSid.clear();
     injectedOnce = false;
     checkinContext = null;
     mcpSessionId = null;

package/lib/lib.ts

@@ -182,6 +182,49 @@ export function sessionWorkflow(sessionUuid: string): string {
   ].join("\n");
 }
 
+/**
+ * True when a worker task already carries an injected session block.
+ *
+ * Matches the block header at the start of a line (`--- Chorus session`), so
+ * prose that merely mentions "Chorus session" does not suppress injection.
+ * Covers both this extension's injected block and any main-agent template.
+ * The header is exactly "--- Chorus session" followed by " (…)" or end of line;
+ * a hyphenated continuation like "--- Chorus session-notes" is not a header.
+ */
+export function hasSessionMarker(task: string): boolean {
+  return /^--- Chorus session(?=[ (\u2014]|$)/m.test(task);
+}
+
+/**
+ * Detect an async (detached) nicobailon pi-subagents `subagent` run from its
+ * tool_result EVENT, and extract the run id that its completion events will
+ * carry.
+ *
+ * The official bundled subagent (blocking) returns at tool_result with no run
+ * id — the session lifecycle closes there. The nicobailon `pi-subagents` tool
+ * launches async (detached) by default: spawn returns immediately with
+ * `details.asyncId`, and completion arrives later on the pi event bus as
+ * `subagent:async-complete` / `subagent:process-terminal` with `{runId}`/`{id}`.
+ * Only `details.asyncId`/`details.runId` are trusted — the nicobailon contract
+ * always carries the run id in `details` for async launches (verified against
+ * pi-subagents src/runs/foreground/subagent-executor.ts: async started returns
+ * `details: { mode, results, asyncId, asyncDir }` (:1584/:1375), and nicobailon
+ * itself reads `result.details.asyncId` (:1711/:1967/:2119); `id`/`prefix`
+ * appear only in completion-event payloads, never in tool_result details), and
+ * a blocking run's worker output (even standalone JSON) must never be
+ * misclassified as an async run (which would leak the session until
+ * session_shutdown).
+ */
+export function extractRunIdFromToolResultEvent(event: {
+  details?: unknown;
+}): string | null {
+  const d = (event.details ?? {}) as Record<string, unknown>;
+  for (const key of ["asyncId", "runId"]) {
+    if (typeof d[key] === "string" && (d[key] as string).length > 0) return d[key] as string;
+  }
+  return null;
+}
+
 /**
  * Resolved OpenSpec mode for a repo. `active` is the effective on/off; `reason`
  * is a human-readable explanation; `optout` marks an explicit opt-out (so the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chorus-aidlc/chorus-pi",
-  "version": "0.17.2",
+  "version": "0.17.3",
   "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"
@@ -52,7 +52,10 @@
   },
   "pi": {
     "extensions": ["./extensions"],
-    "skills": ["./skills"]
+    "skills": ["./skills"],
+    "subagents": {
+      "agents": ["./agents"]
+    }
   },
   "//note": "Reviewer subagents use pi's official subagent pattern, bundled at extensions/subagent/ (index.ts + agents.ts, copied from earendil-works/pi's examples). The copied agents.ts discovers this package's own agents/*.md via a package-relative BUNDLED_DIR, so the 3 reviewer agents load with ZERO manual copy into ~/.pi/agent/agents/. pi auto-loads extensions/subagent/index.ts as a subdirectory-with-index extension (no manifest entry needed)."
 }

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.17.2"
+  version: "0.17.3"
   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.17.2"
+  version: "0.17.3"
   category: project-management
   mcp_server: chorus
 ---

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.17.2"
+  version: "0.17.3"
   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.17.2"
+  version: "0.17.3"
   category: project-management
   mcp_server: chorus
 ---

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.17.2"
+  version: "0.17.3"
   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.17.2"
+  version: "0.17.3"
   category: project-management
   mcp_server: chorus
 ---

package/skills/openspec-aware/SKILL.md

@@ -4,7 +4,7 @@ description: Opt-in OpenSpec-mode authoring for Chorus PM workflows in Pi. Detec
 license: AGPL-3.0
 metadata:
   author: chorus
-  version: "0.17.2"
+  version: "0.17.3"
   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.17.2"
+  version: "0.17.3"
   category: project-management
   mcp_server: chorus
 ---

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.17.2"
+  version: "0.17.3"
   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.17.2"
+  version: "0.17.3"
   category: project-management
   mcp_server: chorus
 ---

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.17.2"
+  version: "0.17.3"
   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.17.2"
+  version: "0.17.3"
   category: project-management
   mcp_server: chorus
 ---