pi-herdr-subagents 0.1.0 → 0.1.2

package/pi-extension/subagents/index.ts

@@ -26,6 +26,7 @@ import {
   renameCurrentWorkspace,
   readPane,
   readPaneAsync,
+  inspectPane,
 } from "./terminal.ts";
 import { waitForCompletion } from "./completion.ts";
 
@@ -35,16 +36,11 @@ import {
   seedSubagentSessionFile,
 } from "./session.ts";
 import {
-  type StatusSnapshot,
   type SubagentStatusState,
-  advanceStatusState,
   capStatusLines,
-  classifyStatus,
-  createStatusState,
-  forceStatusAfterInterrupt,
+  formatElapsedDuration,
   formatStatusAggregate,
-  formatTransitionLine,
-  observeStatus,
+  normalizeStatusName,
   loadStatusConfig,
 } from "./status.ts";
 import {
@@ -53,16 +49,33 @@ import {
   type ActivityReadResult,
   type SubagentActivityState,
 } from "./activity.ts";
+import {
+  createLifecycle,
+  formatLifecycleTransitionLine,
+  lifecycleTransition,
+  markCompleted,
+  markCompletionDetected,
+  markDelivery,
+  markFailed,
+  markInterruptRequested,
+  markProcessRunning,
+  observeActivity,
+  observePaneInspection,
+  projectLifecycle,
+  type LifecycleProjection,
+  type SubagentLifecycle,
+  type PaneInspection,
+} from "./lifecycle.ts";
 
 /** Absolute path to `pi-extension/subagents`. https://github.com/nodejs/node/issues/37845 */
 const SUBAGENTS_DIR = dirname(fileURLToPath(import.meta.url));
 
-// Survive /reload: clear timers and abort poll loops from the previous module load.
-// /reload re-imports this file, giving fresh module-level state, but closures from
-// the old module keep running. These global symbols preserve reload compatibility.
+// Survive /reload: replace presentation timers while keeping active completion
+// watchers and their registry alive. Old module closures continue watching the
+// children; the reloaded module adopts the shared registry for status/interrupts.
 const WIDGET_INTERVAL_KEY = Symbol.for("pi-subagents/widget-interval");
 const STATUS_INTERVAL_KEY = Symbol.for("pi-subagents/status-interval");
-const POLL_ABORT_KEY = Symbol.for("pi-subagents/poll-abort-controller");
+const RUNTIME_KEY = Symbol.for("pi-subagents/runtime");
 
 {
   const prevInterval = (globalThis as any)[WIDGET_INTERVAL_KEY];
@@ -75,13 +88,6 @@ const POLL_ABORT_KEY = Symbol.for("pi-subagents/poll-abort-controller");
     clearInterval(prevStatusInterval);
     (globalThis as any)[STATUS_INTERVAL_KEY] = null;
   }
-  const prevAbort = (globalThis as any)[POLL_ABORT_KEY] as AbortController | undefined;
-  if (prevAbort) prevAbort.abort();
-  (globalThis as any)[POLL_ABORT_KEY] = new AbortController();
-}
-
-function getModuleAbortSignal(): AbortSignal {
-  return ((globalThis as any)[POLL_ABORT_KEY] as AbortController).signal;
 }
 
 const SubagentParams = Type.Object({
@@ -417,25 +423,6 @@ function getArtifactDir(sessionDir: string, sessionId: string): string {
 
 const statusConfig = loadStatusConfig();
 
-function formatWidgetRightLabel(snapshot: StatusSnapshot): string {
-  if (snapshot.kind === "starting") return " starting… ";
-  if (snapshot.kind === "running") return ` running ${snapshot.elapsedText} `;
-  if (snapshot.kind === "active") {
-    const label = snapshot.activityLabel ?? snapshot.activeScope;
-    const duration = snapshot.activeDurationText ? ` ${snapshot.activeDurationText}` : "";
-    return label ? ` active · ${label}${duration} ` : " active ";
-  }
-  if (snapshot.kind === "waiting") {
-    const duration = snapshot.waitingDurationText ? ` ${snapshot.waitingDurationText}` : "";
-    const detail = snapshot.statusLabel ? ` · ${snapshot.statusLabel}` : "";
-    return ` waiting${duration}${detail} `;
-  }
-
-  const detail = snapshot.statusLabel ? ` · ${snapshot.statusLabel}` : "";
-  const duration = snapshot.snapshotProblemText ? ` ${snapshot.snapshotProblemText}` : "";
-  return ` stalled${detail}${duration} `;
-}
-
 function resolveResultPresentation(
   result: Pick<
     SubagentResult,
@@ -505,7 +492,14 @@ interface RunningSubagent {
   abortController?: AbortController;
   cli?: string;
   sentinelFile?: string;
-  statusState: SubagentStatusState;
+  /**
+   * Optional legacy status snapshot retained only for hydrating pre-lifecycle
+   * runtime entries after /reload. Live observation uses `lifecycle` only.
+   */
+  statusState?: SubagentStatusState;
+  lifecycle: SubagentLifecycle;
+  /** Last projected kind used to detect stalled/recovered transitions. */
+  lastProjectedKind?: LifecycleProjection["kind"];
   /**
    * When true, status transitions (stalled/recovered) do not wake the parent
    * session via a steer message. The widget still updates locally. Used for
@@ -515,13 +509,54 @@ interface RunningSubagent {
   interactive: boolean;
 }
 
-/** All currently running subagents, keyed by id. */
-const runningSubagents = new Map<string, RunningSubagent>();
+interface SubagentRuntime {
+  runningSubagents: Map<string, RunningSubagent>;
+  pi?: ExtensionAPI;
+  latestCtx?: ExtensionContext;
+}
 
-// ── Widget management ──
+function createSubagentRuntime(): SubagentRuntime {
+  return { runningSubagents: new Map<string, RunningSubagent>() };
+}
+
+/** Runtime state preserved across /reload. */
+const runtime: SubagentRuntime =
+  (globalThis as any)[RUNTIME_KEY] ??
+  ((globalThis as any)[RUNTIME_KEY] = createSubagentRuntime());
+const runningSubagents = runtime.runningSubagents;
+
+export function shouldPreserveSubagentsOnShutdown(reason: unknown): boolean {
+  return reason === "reload";
+}
 
-/** Latest ExtensionContext from session_start, used for widget updates. */
-let latestCtx: ExtensionContext | null = null;
+export function cleanupSubagentsForShutdown(
+  reason: unknown,
+  agents: Map<string, Pick<RunningSubagent, "abortController" | "lifecycle">>,
+): void {
+  if (shouldPreserveSubagentsOnShutdown(reason)) return;
+
+  for (const agent of agents.values()) {
+    if (agent.lifecycle) {
+      agent.lifecycle = markDelivery(agent.lifecycle, "suppressed");
+    }
+    agent.abortController?.abort();
+  }
+  agents.clear();
+}
+
+export function shouldDeliverSubagentCompletion(
+  running: Pick<RunningSubagent, "lifecycle">,
+): boolean {
+  // Authoritative gate: only pending deliveries may be sent.
+  // Missing lifecycle (pre-migration fixtures) defaults to pending/true.
+  return (running.lifecycle?.delivery ?? "pending") === "pending";
+}
+
+export function selectCompletionApi<T>(previous: T, current: T | undefined): T {
+  return current ?? previous;
+}
+
+// ── Widget management ──
 
 /** Interval timer for widget re-renders. */
 let widgetInterval: ReturnType<typeof setInterval> | null = null;
@@ -529,23 +564,24 @@ let widgetInterval: ReturnType<typeof setInterval> | null = null;
 /** Interval timer for status transition checks. */
 let statusInterval: ReturnType<typeof setInterval> | null = null;
 
-function formatElapsedMMSS(startTime: number): string {
-  const seconds = Math.floor((Date.now() - startTime) / 1000);
+function formatElapsedMMSS(startTime: number, endTime = Date.now()): string {
+  const seconds = Math.floor((endTime - startTime) / 1000);
   const m = Math.floor(seconds / 60);
   const s = seconds % 60;
   return `${String(m).padStart(2, "0")}:${String(s).padStart(2, "0")}`;
 }
 
-const ACCENT = "\x1b[38;2;77;163;255m";
+const ACTIVE_ACCENT = "\x1b[38;2;77;163;255m";
+const OPEN_ACCENT = "\x1b[38;2;214;158;46m";
 const RST = "\x1b[0m";
 
 /**
  * Build a bordered content line: │left          right│
  * Left content is truncated if needed, right is preserved, padded to fill width.
  */
-function borderLine(left: string, right: string, width: number): string {
+function borderLine(left: string, right: string, width: number, accent = ACTIVE_ACCENT): string {
   if (width <= 0) return "";
-  if (width === 1) return `${ACCENT}│${RST}`;
+  if (width === 1) return `${accent}│${RST}`;
 
   // width = total visible chars for the whole line including │ and │
   const contentWidth = Math.max(0, width - 2); // space inside the two │ chars
@@ -556,23 +592,23 @@ function borderLine(left: string, right: string, width: number): string {
   if (rightVis >= contentWidth) {
     const truncRight = truncateToWidth(right, contentWidth);
     const rightPad = Math.max(0, contentWidth - visibleWidth(truncRight));
-    return `${ACCENT}│${RST}${truncRight}${" ".repeat(rightPad)}${ACCENT}│${RST}`;
+    return `${accent}│${RST}${truncRight}${" ".repeat(rightPad)}${accent}│${RST}`;
   }
 
   const maxLeft = Math.max(0, contentWidth - rightVis);
   const truncLeft = truncateToWidth(left, maxLeft);
   const leftVis = visibleWidth(truncLeft);
   const pad = Math.max(0, contentWidth - leftVis - rightVis);
-  return `${ACCENT}│${RST}${truncLeft}${" ".repeat(pad)}${right}${ACCENT}│${RST}`;
+  return `${accent}│${RST}${truncLeft}${" ".repeat(pad)}${right}${accent}│${RST}`;
 }
 
 /**
  * Build the bordered top line: ╭─ Title ──── info ─╮
  * All chars are accounted for within `width`.
  */
-function borderTop(title: string, info: string, width: number): string {
+function borderTop(title: string, info: string, width: number, accent = ACTIVE_ACCENT): string {
   if (width <= 0) return "";
-  if (width === 1) return `${ACCENT}╭${RST}`;
+  if (width === 1) return `${accent}╭${RST}`;
 
   // ╭─ Title ───...─── info ─╮
   // overhead: ╭─ (2) + space around title (2) + space around info (2) + ─╮ (2) = but we simplify
@@ -582,46 +618,84 @@ function borderTop(title: string, info: string, width: number): string {
   const fillLen = Math.max(0, inner - titlePart.length - infoPart.length);
   const fill = "─".repeat(fillLen);
   const content = `${titlePart}${fill}${infoPart}`.slice(0, inner).padEnd(inner, "─");
-  return `${ACCENT}╭${content}╮${RST}`;
+  return `${accent}╭${content}╮${RST}`;
 }
 
 /**
  * Build the bordered bottom line: ╰──────────────────╯
  */
-function borderBottom(width: number): string {
+function borderBottom(width: number, accent = ACTIVE_ACCENT): string {
   if (width <= 0) return "";
-  if (width === 1) return `${ACCENT}╰${RST}`;
+  if (width === 1) return `${accent}╰${RST}`;
 
   const inner = Math.max(0, width - 2);
-  return `${ACCENT}╰${"─".repeat(inner)}╯${RST}`;
+  return `${accent}╰${"─".repeat(inner)}╯${RST}`;
 }
 
-function renderSubagentWidgetLines(agents: RunningSubagent[], width: number): string[] {
-  const count = agents.length;
-  const title = "Subagents";
-  const info = `${count} running`;
-
-  const lines: string[] = [borderTop(title, info, width)];
+function formatLifecycleWidgetLabel(
+  projection: ReturnType<typeof projectLifecycle>,
+  now: number,
+): string {
+  const duration = projection.stateDurationSince == null
+    ? ""
+    : ` ${formatElapsedDuration(now - projection.stateDurationSince)}`;
+  if (projection.kind === "active") return projection.label
+    ? ` active · ${projection.label}${duration} `
+    : ` active${duration} `;
+  if (projection.kind === "blocked") return ` blocked${duration} `;
+  if (projection.kind === "running") return " running… ";
+  if (projection.kind === "waiting") return ` waiting${duration} `;
+  if (projection.kind === "interrupted") return ` interrupted${duration} `;
+  if (projection.kind === "stalled") return ` stalled${duration} `;
+  // completed/failed exist as lifecycle projections for delivery bookkeeping,
+  // but the row is removed immediately after result delivery — so the only
+  // visible terminal handoff label is finalizing.
+  if (
+    projection.kind === "finalizing" ||
+    projection.kind === "completed" ||
+    projection.kind === "failed"
+  ) {
+    return " finalizing… ";
+  }
+  return " starting… ";
+}
 
-  for (const agent of agents) {
-    const elapsed = formatElapsedMMSS(agent.startTime);
+function renderSubagentWidgetLines(agents: RunningSubagent[], width: number): string[] {
+  const now = Date.now();
+  const rendered = agents.map((agent) => ({ agent, projection: projectLifecycle(ensureLifecycle(agent), now) }));
+  const activeCount = rendered.filter(({ projection }) =>
+    projection.kind === "active" ||
+    projection.kind === "starting" ||
+    projection.kind === "running" ||
+    projection.kind === "blocked"
+  ).length;
+  const openCount = agents.length - activeCount;
+  const info = activeCount > 0
+    ? openCount > 0 ? `${activeCount} active · ${openCount} open` : `${activeCount} active`
+    : `${openCount} open`;
+  const accent = activeCount > 0 ? ACTIVE_ACCENT : OPEN_ACCENT;
+
+  const lines: string[] = [borderTop("Subagents", info, width, accent)];
+
+  for (const { agent, projection } of rendered) {
+    const elapsed = formatElapsedMMSS(agent.startTime, projection.runtimeEndedAt ?? now);
     const agentTag = agent.agent ? ` (${agent.agent})` : "";
     const left = ` ${elapsed}  ${agent.name}${agentTag} `;
-    const snapshot = classifyStatus(agent.statusState, Date.now());
     const right = statusConfig.enabled
-      ? formatWidgetRightLabel(snapshot)
+      ? formatLifecycleWidgetLabel(projection, now)
       : agent.cli === "claude"
         ? " running… "
         : " starting… ";
 
-    lines.push(borderLine(left, right, width));
+    lines.push(borderLine(left, right, width, accent));
   }
 
-  lines.push(borderBottom(width));
+  lines.push(borderBottom(width, accent));
   return lines;
 }
 
 function updateWidget() {
+  const latestCtx = runtime.latestCtx;
   if (!latestCtx?.hasUI) return;
 
   if (runningSubagents.size === 0) {
@@ -706,15 +780,59 @@ function buildPiPromptArgs(params: {
   ];
 }
 
-function activityLabel(activity: SubagentActivityState): string | undefined {
-  if (activity.phase !== "active") return undefined;
-  if (activity.activeScope === "tool") return activity.toolName ?? "tool";
-  if (activity.activeScope === "provider") return "provider";
-  if (activity.activeScope === "streaming") return "streaming";
-  return activity.activeScope;
+function ensureLifecycle(running: RunningSubagent): SubagentLifecycle {
+  if (running.lifecycle) return running.lifecycle;
+  let lifecycle = createLifecycle(running.startTime);
+  // Claude agents have no activity snapshots; treat confirmed launch as running.
+  if (running.cli === "claude") {
+    lifecycle = markProcessRunning(lifecycle, running.startTime);
+    running.lifecycle = lifecycle;
+    return lifecycle;
+  }
+  const state = running.statusState;
+  if (state?.activityLabel === "interrupted" && state.localOverrideAtMs != null) {
+    lifecycle = markInterruptRequested(lifecycle, state.localOverrideAtMs);
+  } else if (state?.phase === "done") {
+    // Legacy activity "done" means the turn ended, not that completion
+    // evidence was recorded. Hydrate as Herdr-style waiting and let the
+    // preserved watcher consume sidecar/sentinel evidence.
+    const observedAt = state.lastActivityAtMs ?? running.startTime;
+    lifecycle = observePaneInspection(
+      lifecycle,
+      { kind: "present", observedAt, agentStatus: "done" },
+      observedAt,
+    );
+  } else if (state?.phase === "active" || state?.phase === "waiting" || state?.phase === "starting") {
+    lifecycle = observeActivity(lifecycle, {
+      ok: true,
+      activity: {
+        version: 1,
+        runningChildId: running.id,
+        createdAt: running.startTime,
+        updatedAt: state.lastActivityAtMs ?? running.startTime,
+        sequence: state.lastActivitySequence ?? 0,
+        latestEvent: state.latestEvent === "agent_end" ? "agent_end" : "agent_start",
+        phase: state.phase,
+        agentActive: state.phase === "active",
+        turnActive: state.phase === "active",
+        providerActive: false,
+        toolActive: state.activeScope === "tool",
+        ...(state.activeScope ? { activeScope: state.activeScope as any } : {}),
+        ...(state.activeSinceMs != null ? { activeSince: state.activeSinceMs } : {}),
+        ...(state.waitingSinceMs != null ? { waitingSince: state.waitingSinceMs } : {}),
+        ...(state.activityLabel && state.activeScope === "tool" ? { toolName: state.activityLabel } : {}),
+      },
+    }, state.lastActivityAtMs ?? running.startTime);
+  } else if (state?.source === "claude" || running.startTime) {
+    // Pre-lifecycle Pi agents without a known phase still get a running process.
+    lifecycle = markProcessRunning(lifecycle, running.startTime);
+  }
+  running.lifecycle = lifecycle;
+  return lifecycle;
 }
 
 function observeRunningSubagent(running: RunningSubagent, observedAt = Date.now()) {
+  ensureLifecycle(running);
   if (running.cli === "claude") return;
 
   const activityFile = running.activityFile;
@@ -726,27 +844,8 @@ function observeRunningSubagent(running: RunningSubagent, observedAt = Date.now(
     ? { ok: true }
     : { ok: false, reason: read.reason, error: read.error };
 
-  if (read.ok) {
-    running.activity = read.activity;
-    running.statusState = observeStatus(running.statusState, {
-      snapshot: "present",
-      updatedAt: read.activity.updatedAt,
-      sequence: read.activity.sequence,
-      phase: read.activity.phase,
-      active: read.activity.phase === "active",
-      activeScope: read.activity.activeScope,
-      activeSince: read.activity.activeSince,
-      waitingSince: read.activity.waitingSince,
-      latestEvent: read.activity.latestEvent,
-      activityLabel: activityLabel(read.activity),
-    }, observedAt);
-    return;
-  }
-
-  running.statusState = observeStatus(running.statusState, {
-    snapshot: read.reason,
-    snapshotError: read.error,
-  }, observedAt);
+  if (read.ok) running.activity = read.activity;
+  running.lifecycle = observeActivity(ensureLifecycle(running), read, observedAt);
 }
 
 function resolveInterruptTarget(params: { id?: string; name?: string }):
@@ -824,7 +923,7 @@ function handleSubagentInterrupt(
     };
   }
 
-  running.statusState = forceStatusAfterInterrupt(running.statusState, now);
+  running.lifecycle = markInterruptRequested(ensureLifecycle(running), now);
   updateWidget();
 
   return {
@@ -851,19 +950,30 @@ function startStatusRefresh(pi: ExtensionAPI) {
     let shouldRefreshWidget = false;
 
     for (const running of runningSubagents.values()) {
+      // Dual-writes lifecycle + statusState for reload hydration; steers use lifecycle only.
       observeRunningSubagent(running, now);
-      const { nextState, snapshot, transition } = advanceStatusState(running.statusState, now);
-      if (nextState.currentKind !== running.statusState.currentKind) {
+      const projection = projectLifecycle(ensureLifecycle(running), now);
+      const transition = lifecycleTransition(running.lastProjectedKind, projection.kind);
+      if (running.lastProjectedKind !== projection.kind) {
         shouldRefreshWidget = true;
       }
-      running.statusState = nextState;
+      running.lastProjectedKind = projection.kind;
 
       // Interactive subagents (long-running, user-driven) intentionally don't
       // wake the parent session on stalled/recovered transitions — the user is
       // working in the subagent's pane, and a steer message here would burn an
       // orchestrator turn on a no-op "still waiting" ping. Widget still updates.
       if (transition && !running.interactive) {
-        transitionLines.push(formatTransitionLine(running.name, snapshot, transition));
+        transitionLines.push(
+          formatLifecycleTransitionLine(
+            normalizeStatusName(running.name),
+            projection,
+            transition,
+            now,
+            running.startTime,
+            formatElapsedDuration,
+          ),
+        );
       }
     }
 
@@ -902,7 +1012,6 @@ export const __test__ = {
   resolveEffectiveInteractive,
   buildSubagentToolAllowlist,
   buildPiPromptArgs,
-  formatWidgetRightLabel,
   observeRunningSubagent,
   resolveDenyTools,
   resolveInterruptTarget,
@@ -1068,10 +1177,7 @@ async function launchSubagent(
       cli: "claude",
       sentinelFile,
       interactive: effectiveInteractive,
-      statusState: createStatusState({
-        source: "claude",
-        startTimeMs: startTime,
-      }),
+      lifecycle: markProcessRunning(createLifecycle(startTime), Date.now()),
     };
 
     runningSubagents.set(id, running);
@@ -1206,10 +1312,7 @@ async function launchSubagent(
     launchScriptFile,
     activityFile,
     interactive: effectiveInteractive,
-    statusState: createStatusState({
-      source: "pi",
-      startTimeMs: startTime,
-    }),
+    lifecycle: createLifecycle(startTime),
   };
 
   runningSubagents.set(id, running);
@@ -1249,17 +1352,26 @@ async function watchSubagent(
   const { name, task, surface, startTime, sessionFile } = running;
 
   try {
-    const result = await waitForCompletion(AbortSignal.any([signal, getModuleAbortSignal()]), {
+    const result = await waitForCompletion(signal, {
       intervalMs: 1000,
       sessionFile,
       sentinelFile: running.sentinelFile,
       readTerminalTail: () => readPaneAsync(surface, 5),
+      inspectPane: async () => inspectPane(surface),
+      onPaneInspection: (inspection: PaneInspection, observedAt: number) => {
+        ensureLifecycle(running);
+        running.lifecycle = observePaneInspection(running.lifecycle, inspection, observedAt);
+        updateWidget();
+      },
       onTick() {
         observeRunningSubagent(running);
       },
     });
 
-    const elapsed = Math.floor((Date.now() - startTime) / 1000);
+    const detectedAt = Date.now();
+    running.lifecycle = markCompletionDetected(running.lifecycle, result, detectedAt);
+    updateWidget();
+    const elapsed = Math.floor((detectedAt - startTime) / 1000);
 
     if (running.cli === "claude") {
       // Claude Code result extraction
@@ -1292,7 +1404,9 @@ async function watchSubagent(
       }
 
       closePane(surface);
-      runningSubagents.delete(running.id);
+      running.lifecycle = result.exitCode === 0
+        ? markCompleted(running.lifecycle, Date.now())
+        : markFailed(running.lifecycle, result.errorMessage ?? summary, Date.now(), result.exitCode);
 
       return { name, task, summary, exitCode: result.exitCode, elapsed, ...(sessionId ? { claudeSessionId: sessionId } : {}) };
     }
@@ -1317,7 +1431,9 @@ async function watchSubagent(
     }
 
     closePane(surface);
-    runningSubagents.delete(running.id);
+    running.lifecycle = result.exitCode === 0
+      ? markCompleted(running.lifecycle, Date.now())
+      : markFailed(running.lifecycle, result.errorMessage ?? summary, Date.now(), result.exitCode);
 
     return {
       name,
@@ -1333,7 +1449,13 @@ async function watchSubagent(
     try {
       closePane(surface);
     } catch {}
-    runningSubagents.delete(running.id);
+    running.lifecycle = markFailed(
+      running.lifecycle,
+      signal.aborted ? "Subagent cancelled." : err?.message ?? String(err),
+      Date.now(),
+      1,
+    );
+    updateWidget();
 
     if (signal.aborted) {
       return {
@@ -1358,13 +1480,21 @@ async function watchSubagent(
 }
 
 export default function subagentsExtension(pi: ExtensionAPI) {
-  // Capture the UI context for widget updates
+  runtime.pi = pi;
+
+  // Capture the UI context for widget updates and restore presentation for
+  // subagents whose watchers survived a reload.
   pi.on("session_start", (_event, ctx) => {
-    latestCtx = ctx;
+    runtime.latestCtx = ctx;
+    if (runningSubagents.size > 0) {
+      startWidgetRefresh();
+      startStatusRefresh(pi);
+      updateWidget();
+    }
   });
 
   // Clean up on session shutdown
-  pi.on("session_shutdown", (_event, _ctx) => {
+  pi.on("session_shutdown", (event, _ctx) => {
     if (widgetInterval) {
       clearInterval(widgetInterval);
       widgetInterval = null;
@@ -1375,17 +1505,13 @@ export default function subagentsExtension(pi: ExtensionAPI) {
       statusInterval = null;
       (globalThis as any)[STATUS_INTERVAL_KEY] = null;
     }
-    const moduleAbort = (globalThis as any)[POLL_ABORT_KEY] as AbortController | undefined;
-    if (moduleAbort) moduleAbort.abort();
-    for (const [_id, agent] of runningSubagents) {
-      agent.abortController?.abort();
-    }
-    runningSubagents.clear();
+
+    cleanupSubagentsForShutdown((event as any).reason, runningSubagents);
   });
 
   // Tools denied via PI_DENY_TOOLS env var (set by parent agent based on frontmatter)
   const deniedTools = new Set(
-    (process.env.PI_DENY_TOOLS ?? "")
+    (process.env.PI_SUBAGENT_ID ? process.env.PI_DENY_TOOLS ?? "" : "")
       .split(",")
       .map((s) => s.trim())
       .filter(Boolean),
@@ -1461,12 +1587,21 @@ export default function subagentsExtension(pi: ExtensionAPI) {
         // Fire-and-forget: start watching in background
         watchSubagent(running, watcherAbort.signal)
           .then((result) => {
-            updateWidget(); // reflect removal from Map immediately
+            if (!shouldDeliverSubagentCompletion(running)) {
+              running.lifecycle = markDelivery(running.lifecycle, "suppressed");
+              runningSubagents.delete(running.id);
+              updateWidget();
+              return;
+            }
+            running.lifecycle = markDelivery(running.lifecycle, "delivered");
+            runningSubagents.delete(running.id);
+            updateWidget();
+            const completionApi = selectCompletionApi(pi, runtime.pi);
 
             if (result.ping) {
               // Subagent is requesting help — steer a ping message with session path for resume
               const sessionRef = `\n\nSession: ${result.sessionFile}\nResume: pi --session ${result.sessionFile}`;
-              pi.sendMessage(
+              completionApi.sendMessage(
                 {
                   customType: "subagent_ping",
                   content: `Sub-agent "${result.ping.name}" needs help (${formatElapsed(result.elapsed)}):\n\n${result.ping.message}${sessionRef}`,
@@ -1485,7 +1620,7 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 
             const presentation = resolveResultPresentation(result, running.name);
 
-            pi.sendMessage(
+            completionApi.sendMessage(
               {
                 customType: "subagent_result",
                 content: presentation,
@@ -1505,8 +1640,16 @@ export default function subagentsExtension(pi: ExtensionAPI) {
             );
           })
           .catch((err) => {
+            if (!shouldDeliverSubagentCompletion(running)) {
+              running.lifecycle = markDelivery(running.lifecycle, "suppressed");
+              runningSubagents.delete(running.id);
+              updateWidget();
+              return;
+            }
+            running.lifecycle = markDelivery(running.lifecycle, "delivered");
+            runningSubagents.delete(running.id);
             updateWidget();
-            pi.sendMessage(
+            selectCompletionApi(pi, runtime.pi).sendMessage(
               {
                 customType: "subagent_result",
                 content: `Sub-agent "${running.name}" error: ${err?.message ?? String(err)}`,
@@ -1873,10 +2016,7 @@ export default function subagentsExtension(pi: ExtensionAPI) {
           launchScriptFile,
           activityFile,
           interactive,
-          statusState: createStatusState({
-            source: "pi",
-            startTimeMs: startTime,
-          }),
+          lifecycle: createLifecycle(startTime),
         };
         runningSubagents.set(id, running);
         startWidgetRefresh();
@@ -1888,11 +2028,20 @@ export default function subagentsExtension(pi: ExtensionAPI) {
 
         watchSubagent(running, watcherAbort.signal)
           .then((result) => {
+            if (!shouldDeliverSubagentCompletion(running)) {
+              running.lifecycle = markDelivery(running.lifecycle, "suppressed");
+              runningSubagents.delete(running.id);
+              updateWidget();
+              return;
+            }
+            running.lifecycle = markDelivery(running.lifecycle, "delivered");
+            runningSubagents.delete(running.id);
             updateWidget();
+            const completionApi = selectCompletionApi(pi, runtime.pi);
 
             if (result.ping) {
               const sessionRef = `\n\nSession: ${params.sessionPath}\nResume: pi --session ${params.sessionPath}`;
-              pi.sendMessage(
+              completionApi.sendMessage(
                 {
                   customType: "subagent_ping",
                   content: `Sub-agent "${result.ping.name}" needs help (${formatElapsed(result.elapsed)}):\n\n${result.ping.message}${sessionRef}`,
@@ -1920,7 +2069,7 @@ export default function subagentsExtension(pi: ExtensionAPI) {
               name,
             );
 
-            pi.sendMessage(
+            completionApi.sendMessage(
               {
                 customType: "subagent_result",
                 content: presentation,
@@ -1938,8 +2087,16 @@ export default function subagentsExtension(pi: ExtensionAPI) {
             );
           })
           .catch((err) => {
+            if (!shouldDeliverSubagentCompletion(running)) {
+              running.lifecycle = markDelivery(running.lifecycle, "suppressed");
+              runningSubagents.delete(running.id);
+              updateWidget();
+              return;
+            }
+            running.lifecycle = markDelivery(running.lifecycle, "delivered");
+            runningSubagents.delete(running.id);
             updateWidget();
-            pi.sendMessage(
+            selectCompletionApi(pi, runtime.pi).sendMessage(
               {
                 customType: "subagent_result",
                 content: `Resume error: ${err?.message ?? String(err)}`,