@chorus-aidlc/chorus-pi 0.17.2 → 0.18.0

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.
@@ -88,6 +89,7 @@ These are the dimensions that per-task review structurally cannot catch. Cover e
 4. **Regression risk / impact on untouched areas / performance** — Does the change break or degrade code no single task "owned"? N+1s, hot-path cost, shared-state contention introduced by the aggregate.
 5. **Feature-level test coverage adequacy** — Across the whole feature, are the integration seams and end-to-end paths tested, or only per-task units? Gaps between tasks.
 6. **Code soundness, simplicity, correctness** — Is the aggregate change correct, reasonably simple, and free of obvious defects when read as one body of work?
+7. **Intent alignment (whole-feature)** — Also read the Idea's resolved elaboration (`chorus_get_elaboration`); using ONLY human-authored intent (Idea body + human-answered elaboration + human-authored comments; agent-authored entries are audit context, not intent) as the baseline, judge whether the aggregate change still serves the original intent. Flag scope creep, dropped requirements, or intent missed despite passing AC as a **BLOCKER**, unless a cited human entry / human override authorizes it.
 
 **Step 4: Run feature-level build/test**
 

package/agents/chorus-proposal-reviewer.md

@@ -1,10 +1,11 @@
 ---
 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.
+CRITICAL: READ-ONLY proposal review. You CANNOT edit, write, or create files. Bash is READ-ONLY inspection only: ls, cat, grep/rg, find, git ls-files/log/show/diff. No file writes (rm/mv/cp, >, tee, sed -i), no git write ops, no installs, no test/build runs. Use it to confirm a file or directory exists before flagging it as missing.
 USE THE chorus_* MCP TOOLS for all Chorus data access — do NOT use curl or raw HTTP. The mcp gateway tool is available (the tool name prefix may be chorus_chorus_* or chorus_* depending on the session's MCP exposure mode; probe with a checkin if unsure).
 - chorus_get_proposal({ proposalUuid, section: "full" }) — fetch the full proposal (docs + tasks)
 - chorus_get_comments({ targetType: "proposal", targetUuid }) — prior review comments (check for Round 2+)
@@ -27,7 +28,7 @@ You have two failure patterns. **Rubber-stamping**: skimming the proposal and wr
 === CRITICAL: DO NOT MODIFY THE PROJECT ===
 You are STRICTLY PROHIBITED from:
 - Creating, modifying, or deleting any files
-- Running any shell commands beyond read-only inspection (git diff/log/show only)
+- Any shell command beyond read-only inspection (the read-only Bash rule in the CRITICAL line above is the full list)
 - Installing dependencies or packages
 
 === WHAT YOU RECEIVE ===
@@ -72,6 +73,7 @@ For each task draft, check:
 - Do tasks cover ALL requirements from the documents?
 - Are there scope additions not in the original idea?
 - Are there contradictions between documents and tasks?
+- **Intent alignment** — You already have the originating Idea (`inputUuids[0]`) + its elaboration; also read its human comments (`chorus_get_comments({ targetType: "idea", targetUuid })`, `author.type == "user"`). Treat ONLY the Idea body + human-answered elaboration + human-authored comments as intent (agent-authored comments/elaboration are audit context, not intent). Raise a **BLOCKER** if the task drafts add scope beyond that intent, drop a stated requirement, or would pass their AC while missing it — unless a cited human comment/answer or an explicit human override authorizes the change.
 
 === FINDING CLASSIFICATION ===
 

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.
@@ -92,6 +93,10 @@ 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.
 
+**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.
+
 === FINDING CLASSIFICATION ===
 
 Every finding MUST be classified as one of:

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.18.0"}}}
 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,7 +44,9 @@ import {
   isWorkerAgent,
   subagentTaskItems,
   sessionWorkflow,
-  detectOpenSpec,
+  hasSessionMarker,
+  extractRunIdFromToolResultEvent,
+  resolveSpecMode,
   buildSessionBanner,
   parseMaxCodeReviewRounds,
   resolveChorusBin,
@@ -71,7 +77,18 @@ const _mcp = _envUrl && _envKey
     })();
 const CHORUS_URL = _envUrl || _mcp.url;
 const CHORUS_API_KEY = _envKey || _mcp.apiKey;
-const OPENSPEC_OPTOUT = process.env.CHORUS_OPENSPEC_MODE === "off";
+
+// A neutral SpecModeResult for the not-configured / connection-failed banners,
+// where buildSessionBanner returns before reading the spec fields.
+const NO_SPEC = {
+  specMode: "off" as const,
+  specReason: "",
+  specFail: "",
+  openspecUsable: false,
+  openspecUsableReason: "",
+  openspecHint: "",
+  chorusOpenspecActive: false,
+};
 
 // Reviewer toggle envs (mirror Claude Code plugin userConfig; Pi has no plugin
 // settings UI, so env vars drive them). Defaults: all enabled.
@@ -196,6 +213,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;
 
@@ -255,11 +276,14 @@ async function closeCallSessions(
 // ─── Extension ────────────────────────────────────────────────────────────
 export default function (pi: ExtensionAPI) {
   // SessionStart → checkin + build context (replaces Claude's on-session-start.sh)
-  // Emits a user-visible one-line banner (ctx.ui.notify) mirroring the Claude
-  // plugin's SessionStart `systemMessage` / the Codex `$chorus` toast (#442):
-  //   connected + active   -> "Chorus connected at <url> (OpenSpec Enabled)"
-  //   connected + opt-out   -> "Chorus connected at <url> (OpenSpec off)"
-  //   connected + unset     -> "Chorus connected at <url> (OpenSpec off — run /skill:chorus enable openspec to set it up)"
+  // Resolves the spec mode once (resolveSpecMode, the TS mirror of the bash
+  // resolver) and injects a `## Spec Mode` block, plus a user-visible one-line
+  // banner (ctx.ui.notify) mirroring the Claude plugin `systemMessage` / Codex
+  // `$chorus` toast:
+  //   connected + openspec -> "Chorus connected at <url> (spec: OpenSpec)"
+  //   connected + lite      -> "Chorus connected at <url> (spec: spec-lite)"
+  //   connected + off       -> "Chorus connected at <url> (spec: off — free-form)"
+  //   connected + openspec-requested-but-unusable -> warning "(spec: OpenSpec requested but unusable — …)"
   //   not configured        -> warning (env vars missing)
   //   connection failed     -> error (checkin couldn't reach Chorus)
   pi.on("session_start", async (event, ctx) => {
@@ -269,7 +293,7 @@ export default function (pi: ExtensionAPI) {
         configured: false,
         connected: false,
         chorusUrl: CHORUS_URL,
-        openspec: { active: false, reason: "not configured", optout: false, hint: "" },
+        spec: NO_SPEC,
       });
       ctx.ui.notify(banner.message, banner.level);
       return;
@@ -278,13 +302,30 @@ export default function (pi: ExtensionAPI) {
     try {
       const checkin = await mcpCall("chorus_checkin");
       connected = true;
-      // eslint-disable-next-line @typescript-eslint/no-require-imports
-      const os = detectOpenSpec(
-        ctx.cwd,
-        OPENSPEC_OPTOUT,
+      // Resolve the spec mode once per session (single source of truth — the TS
+      // reimplementation of the bash resolver). Rule: explicit CHORUS_SPEC_MODE
+      // wins; unset → OpenSpec when usable, else spec-lite.
+      const spec = resolveSpecMode(
+        {
+          specMode: process.env.CHORUS_SPEC_MODE,
+          openspecMode: process.env.CHORUS_OPENSPEC_MODE,
+          enableOpenSpec: process.env.CLAUDE_PLUGIN_OPTION_ENABLEOPENSPEC,
+          projectRoot: ctx.cwd,
+        },
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
         require("node:fs"),
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
         require("node:child_process").execSync,
       );
+      // Route note per resolved mode (mirrors the bash/Codex `## Spec Mode` block).
+      const specRoute =
+        spec.specMode === "lite"
+          ? "Routing: lite → follow the `spec-lite` skill (/skill:spec-lite). A capability's durable spec is `.chorus/specs/<slug>/spec.md` (edited in place, **never synced**, git history is its record); each change is a dated folder `.chorus/specs/<slug>/<YYYY-MM-DD>-<change-slug>/` of Chorus-typed docs (`prd.md` required; `tech_design.md` / `adr.md` / `guide.md` / `spec.md` optional) that **are** mirrored 1:1 into persistent Chorus Documents via `chorus mcp call … --arg-file content=<file>` (fallback `chorus-mcp-call.sh`). Put a `Spec-lite: .chorus/specs/<slug>/<YYYY-MM-DD>-<change-slug>/` locator line in the proposal description. Do NOT scaffold `openspec/changes/` or add an `OpenSpec change slug:` line."
+          : spec.specMode === "off"
+            ? "Routing: off → free-form, no spec artifact. Do NOT create `.chorus/specs/` or `openspec/changes/` files; author document drafts inline via direct MCP."
+            : spec.specFail
+              ? `Routing: openspec → **cannot be honored** — ${spec.specFail}. The proposal / yolo skill MUST halt after resolving the mode; do NOT silently fall back to lite/free-form. Surface this to the user.${spec.openspecHint ? ` Install hint: ${spec.openspecHint}.` : ""}`
+              : `CHORUS_OPENSPEC_ACTIVE=1 (${spec.openspecUsableReason})\n\nRouting: openspec → load the openspec-aware skill (/skill:openspec-aware) and follow §3 (OpenSpec authoring) — do NOT re-run the §1 detection block, the answer is already known.\n\nCritical rule (openspec-aware §2 Rule 1): document mirror calls (\`chorus_pm_add_document_draft\` / \`chorus_pm_update_document_draft\` / \`chorus_pm_update_document\`) MUST fill \`content\` from the local file — prefer \`chorus mcp call <tool> '<json>' --arg-file content=<file>\`, falling back to \`chorus-mcp-call.sh\` when \`chorus\` is not on PATH. Do NOT invoke these MCP tools directly with hand-typed \`content\` in OpenSpec mode.`;
       checkinContext = [
         "# Chorus Plugin — Active",
         "",
@@ -296,16 +337,11 @@ export default function (pi: ExtensionAPI) {
         JSON.stringify(checkin, null, 2),
         "```",
         "",
-        "## OpenSpec Mode",
+        "## Spec Mode",
         "",
-        `CHORUS_OPENSPEC_ACTIVE=${os.active} (${os.reason})`,
-        os.active
-          ? "OpenSpec mode is **active**. proposal/develop/yolo skills follow the openspec-aware path."
-          : os.optout
-            ? "OpenSpec was **explicitly turned off** — do not nag."
-            : os.hint
-              ? `Note: this repo has an \`openspec/\` directory but the \`openspec\` CLI is not installed — ${os.hint}. Run \`/skill:chorus enable openspec\` to set it up.`
-              : "OpenSpec is not set up in this repo. Spec-driven authoring is optional — free-form works fine. If the user wants spec-driven mode, run `/skill:chorus enable openspec` (§6 walks the install + re-launch).",
+        `CHORUS_SPEC_MODE=${spec.specMode} (${spec.specReason})`,
+        "",
+        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.",
@@ -315,13 +351,13 @@ export default function (pi: ExtensionAPI) {
         (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."
           : "- **OpenSpec wrapper**: `bin/chorus-mcp-call.sh` was not resolved relative to the extension — it is the CLI-absent fallback for OpenSpec-mode document mirrors (prefer `chorus mcp call <tool> '<json>' --arg-file content=<file>`). If you need it, locate it with `find ~/.pi/agent/npm -path '*chorus-pi/bin/chorus-mcp-call.sh'`. See /skill:openspec-aware §2."),
-        "- **Skills**: /skill:chorus, /skill:idea, /skill:proposal, /skill:develop, /skill:review, /skill:quick-dev, /skill:yolo",
+        "- **Skills**: /skill:chorus, /skill:idea, /skill:proposal, /skill:develop, /skill:review, /skill:quick-dev, /skill:yolo, /skill:spec-lite, /skill:openspec-aware",
       ].join("\n");
       const banner = buildSessionBanner({
         configured: true,
         connected: true,
         chorusUrl: CHORUS_URL,
-        openspec: os,
+        spec,
       });
       ctx.ui.notify(banner.message, banner.level);
     } catch (e) {
@@ -330,7 +366,7 @@ export default function (pi: ExtensionAPI) {
         configured: true,
         connected: false,
         chorusUrl: CHORUS_URL,
-        openspec: { active: false, reason: "connection failed", optout: false, hint: "" },
+        spec: NO_SPEC,
       });
       ctx.ui.notify(banner.message, banner.level);
     }
@@ -360,6 +396,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 +420,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 +483,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;