@tranhoangnguyen0310/pi-flow-external 5.0.1-external.0 → 5.1.0-external.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to pi-flow external are documented here.
 
+## [5.1.0-external.0] - 2026-10-19
+
+### Added
+- Live background run status bar (`pi-flow-runs`), completion notifications, and debounced follow-up wake messages (`pi-flow-background-settled`) for UI sessions:
+  - Active background root runs (`external_delegate` and `external_workflow` launched with `background: true`) display a live footer indicator (`pi-flow N bg (...)`) without colliding with usage reporting (`pi-flow`) or double-counting workflow child tasks.
+  - When an uncollected background root run settles across a turn boundary, UI sessions emit a completion notice and queue a debounced follow-up wake message (`deliverAs: "followUp"`) carrying the redacted `PublicRun` summary and `external_runs` inspection command.
+  - Wake delivery is automatically suppressed for foreground runs, workflow children, caller cancellations (`external_runs cancel`), closed or switched sessions, and runs already collected in the turn via `external_runs wait` or `inspect`.
+
 ## [5.0.1-external.0] - 2026-10-19
 
 ### Changed

package/README.md

@@ -149,12 +149,12 @@ Both `external_delegate` and `external_workflow` support these modes:
 | | Foreground (default) | Background (`background: true`) |
 |---|---|---|
 | Original call returns | When the work finishes or fails | After registration, with a run ID; work may already have finished |
-| Progress | Live execution card | A static launch receipt; inspect with `/external runs` or ask Pi for status |
+| Progress | Live execution card | A static launch receipt plus a live status bar count (`pi-flow N bg`); inspect with `/external runs` |
 | Next step | Pi checks the returned outcome | Pi keeps the run ID and does independent work before collecting, or reports the ID and switches tasks/ends its turn if left running across turns |
 
 > **You:** "Have Claude audit the API in the background while we review the release checklist. Then bring me the findings."
 
-- **No automatic completion message:** background work does not notify or wake the parent. Pi collects once its independent work is done; if you ask to leave work running or check back later, Pi reports the run ID and proceeds or ends its turn without waiting.
+- **Status bar & completion wake-up:** UI sessions show active background runs in the footer status bar, notify on completion, and automatically queue a follow-up wake message when an uncollected background run finishes across turns. If Pi already collected the run in the same turn, no duplicate message is sent.
 - **Keep Pi open:** background work belongs to its originating session, not a persistent service. Orderly shutdown requests cancellation with bounded cleanup; restart does not adopt unfinished work.
 - **Stopping is different from waiting:** interrupting the original foreground call cancels it. Interrupting `external_runs wait` only stops waiting; use `/external runs` or `external_runs cancel` to stop background work.
 

package/docs/supervision-and-runtime.md

@@ -101,7 +101,7 @@ return { run, view, encoding, text, checklist };
 - **Foreground interruption:** interrupting the original blocking call cancels that work.
 - **Wait interruption:** interrupting `external_runs wait` only stops waiting; it does not cancel the selected runs. Use `external_runs cancel` to stop background work. Cancellation requests are not proof of completed cleanup; check settlement.
 - **Workflow cancellation:** cancelling the root stops its active children. Cancelling one child throws a catchable child error; a script that handles it may continue.
-- **No automatic delivery:** ending a turn does not stop background work; it continues in the owning session. Background completion does not notify, wake, or resume the parent.
+- **Status bar & completion wake-up:** ending a turn does not stop background work; it continues in the owning session. UI sessions display active background root runs in the status bar (`pi-flow-runs`), show a completion notification, and queue a debounced follow-up wake message (`pi-flow-background-settled`) when an uncollected background root run settles across turns. Runs already collected in the turn or cancelled by the caller do not send a wake message.
 - **Not a persistent service:** keep the owning Pi session open. Orderly shutdown requests cancellation and waits for bounded cleanup. Crashes or force-kills leave unfinished evidence `interrupted_or_uncertain`; restarting Pi never adopts live orphan work.
 
 ---

package/docs/workflows.md

@@ -54,7 +54,7 @@ Put the same roadmap in `meta.phases`, an optional ordered array of `{ title, de
 
 **A plan is intent, not proof of execution.** The briefing is an agent instruction, not a runtime-verified chat message. Runtime validation checks phase metadata, not whether the script follows its prose. Child states and activity are the source of truth for observed execution. Do not invent completion estimates or call a quiet agent healthy merely because a spinner moves.
 
-Choose foreground by default when you need the result next, including parallel workflows. Use background when you have independent local work to do first, or when the user asks to leave the workflow running across turns; it does not make children more parallel. While a foreground call runs, the live card carries progress; the parent cannot reliably send chat updates from inside that call. A background receipt is not a live monitor, and completion does not wake the parent. Keep the owning session open and collect results after independent work finishes, or report the run ID and switch tasks/end the turn when the user wants to check back later. See [execution and collection](supervision-and-runtime.md#foreground-background--lifecycle) for the complete lifecycle and interruption rules.
+Choose foreground by default when you need the result next, including parallel workflows. Use background when you have independent local work to do first, or when the user asks to leave the workflow running across turns; it does not make children more parallel. While a foreground call runs, the live card carries progress; the parent cannot reliably send chat updates from inside that call. A background receipt is not a live monitor, though UI sessions show active background runs in the status bar and wake the session with a follow-up message when an uncollected background run settles across turns. Keep the owning session open and collect results after independent work finishes, or report the run ID and switch tasks/end the turn when the user wants to check back later. See [execution and collection](supervision-and-runtime.md#foreground-background--lifecycle) for the complete lifecycle and interruption rules.
 
 The recorded purpose and phase details remain accessible in explicit launch inspection, during execution and after completion:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tranhoangnguyen0310/pi-flow-external",
-  "version": "5.0.1-external.0",
+  "version": "5.1.0-external.0",
   "description": "External Claude Code, Codex CLI, Antigravity, Grok Build CLI, Muse Code, and OpenCode delegation for pi.",
   "type": "module",
   "main": "./index.ts",

package/src/core/run-registry.ts

@@ -20,17 +20,29 @@ export interface RegisteredRunEntry {
   sessionId: string;
   project: string;
   workflowRunId?: string;
+  background?: boolean;
   state: RegisteredRunState;
   observation?: unknown;
   outcome?: RegisteredRunOutcome;
 }
 
+export interface BackgroundRunEvent {
+  type: "started" | "settled";
+  entry: RegisteredRunEntry;
+  sessionVersion: number;
+  suppressed: boolean;
+}
+
 export interface RegisteredRunHandle<T> {
   result: Promise<T>;
   terminal: Promise<RegisteredRunOutcome>;
 }
 
 interface InternalEntry extends RegisteredRunEntry {
+  sessionVersion: number;
+  background: boolean;
+  collected: boolean;
+  userCancelled: boolean;
   controller: AbortController;
   terminal: Promise<RegisteredRunOutcome>;
   resolveTerminal: (outcome: RegisteredRunOutcome) => void;
@@ -45,6 +57,7 @@ export interface StartRegisteredRun<T> {
   sessionVersion?: number;
   project: string;
   workflowRunId?: string;
+  background?: boolean;
   signal?: AbortSignal;
   run: (signal: AbortSignal) => Promise<T> | T;
   outcome?: (result: T, signal: AbortSignal) => Omit<RegisteredRunOutcome, "runId" | "kind" | "settledAt">;
@@ -62,8 +75,10 @@ const DEFAULT_COMPLETED_LIMIT = 100;
 export class RunRegistry {
   private readonly entries = new Map<string, InternalEntry>();
   private readonly completed: string[] = [];
+  private readonly collectedIds = new Set<string>();
   private readonly sessionVersions = new Map<string, number>();
   private readonly closedSessions = new Set<string>();
+  private readonly backgroundListeners = new Set<(event: BackgroundRunEvent) => void>();
 
   constructor(private readonly completedLimit = DEFAULT_COMPLETED_LIMIT, private readonly shutdownGraceMs = 4_000) {
     if (!Number.isInteger(completedLimit) || completedLimit < 0) {
@@ -97,8 +112,12 @@ export class RunRegistry {
       runId: params.runId,
       kind: params.kind,
       sessionId: params.sessionId,
+      sessionVersion: params.sessionVersion ?? this.sessionVersion(params.sessionId),
       project: params.project,
       ...(params.workflowRunId ? { workflowRunId: params.workflowRunId } : {}),
+      background: params.background === true,
+      collected: false,
+      userCancelled: false,
       state: "running",
       controller,
       terminal,
@@ -107,6 +126,9 @@ export class RunRegistry {
       listeners: new Set(),
     };
     this.entries.set(entry.runId, entry);
+    if (entry.background && !entry.workflowRunId) {
+      this.emitBackground({ type: "started", entry: this.publicEntry(entry), sessionVersion: entry.sessionVersion, suppressed: false });
+    }
 
     const abortFromCaller = () => controller.abort(params.signal?.reason);
     if (params.signal?.aborted) abortFromCaller();
@@ -168,6 +190,35 @@ export class RunRegistry {
       .map((entry) => this.publicEntry(entry));
   }
 
+  listBackgroundRoots(sessionId: string): RegisteredRunEntry[] {
+    return [...this.entries.values()]
+      .filter((entry) => entry.sessionId === sessionId && entry.background && !entry.workflowRunId && entry.state === "running")
+      .map((entry) => this.publicEntry(entry));
+  }
+
+  onBackgroundEvent(listener: (event: BackgroundRunEvent) => void): () => void {
+    this.backgroundListeners.add(listener);
+    return () => this.backgroundListeners.delete(listener);
+  }
+
+  markCollected(runId: string): void {
+    if (this.collectedIds.size >= 512 && !this.collectedIds.has(runId)) {
+      const oldest = this.collectedIds.values().next().value;
+      if (oldest) this.collectedIds.delete(oldest);
+    }
+    this.collectedIds.add(runId);
+    const entry = this.entries.get(runId);
+    if (entry) entry.collected = true;
+  }
+
+  isCollected(runId: string): boolean {
+    return this.collectedIds.has(runId) || Boolean(this.entries.get(runId)?.collected);
+  }
+
+  isSessionActive(sessionId: string, sessionVersion?: number): boolean {
+    return !this.closedSessions.has(sessionId) && (sessionVersion === undefined || this.sessionVersion(sessionId) === sessionVersion);
+  }
+
   update(runId: string, observation: unknown): void {
     const entry = this.entries.get(runId);
     if (entry && entry.state === "running") entry.observation = observation;
@@ -176,6 +227,8 @@ export class RunRegistry {
   cancel(runId: string, reason = "run cancelled"): "requested" | "terminal" | "unknown" {
     const entry = this.entries.get(runId);
     if (!entry) return "unknown";
+    entry.userCancelled = true;
+    this.markCollected(runId);
     if (entry.state === "terminal") return "terminal";
     entry.controller.abort(new Error(reason));
     return "requested";
@@ -242,7 +295,17 @@ export class RunRegistry {
     entry.resolveTerminal(outcome);
     for (const listener of [...entry.listeners]) listener(outcome);
     entry.listeners.clear();
-    if (this.entries.get(entry.runId) !== entry) return;
+    const isCurrent = this.entries.get(entry.runId) === entry;
+    if (entry.background && !entry.workflowRunId) {
+      const suppressed =
+        !isCurrent ||
+        entry.collected ||
+        this.collectedIds.has(entry.runId) ||
+        entry.userCancelled ||
+        !this.isSessionActive(entry.sessionId, entry.sessionVersion);
+      this.emitBackground({ type: "settled", entry: this.publicEntry(entry), sessionVersion: entry.sessionVersion, suppressed });
+    }
+    if (!isCurrent) return;
     this.completed.push(entry.runId);
     while (this.completed.length > this.completedLimit) {
       const evicted = this.completed.shift();
@@ -250,6 +313,16 @@ export class RunRegistry {
     }
   }
 
+  private emitBackground(event: BackgroundRunEvent): void {
+    for (const listener of [...this.backgroundListeners]) {
+      try {
+        listener(event);
+      } catch {
+        // Never allow a UI or notification listener error to corrupt registry state.
+      }
+    }
+  }
+
   private publicEntry(entry: InternalEntry): RegisteredRunEntry {
     return {
       runId: entry.runId,
@@ -257,6 +330,7 @@ export class RunRegistry {
       sessionId: entry.sessionId,
       project: entry.project,
       ...(entry.workflowRunId ? { workflowRunId: entry.workflowRunId } : {}),
+      ...(entry.background ? { background: true } : {}),
       state: entry.state,
       ...(entry.observation !== undefined ? { observation: entry.observation } : {}),
       ...(entry.outcome ? { outcome: entry.outcome } : {}),

package/src/external-help.ts

@@ -99,7 +99,7 @@ Before calling external_workflow, explain the purpose, assignments, parallel/seq
 
 APIs: agent(prompt, { description, label, role, harness, subagent_type, permission, max_budget_usd, resume, context, schema, phase }); parallel(thunks); pipeline(items, ...stages); phase(title); log(message). Globals: args and cwd. Agent options other than the profile selector are optional. "description" is the common task-name option shared with the direct external_delegate tool; "label" is a compatible alias — set only one, or both to the same value. Choose role/harness or legacy exact subagent_type, never both. Use unique descriptions/labels and clear task prompts. An agent() succeeds with its value or throws ChildRunError { runId, outcome, message, outputRef, diagnosticsRef }; catch optional failures explicitly. Uncaught failures terminate the workflow and drain siblings. Helpers never convert failures to null. Context options: {mode:"none"} (default), {mode:"recent",turns:N} (positive integer, includes current user turn), or {mode:"full"} (available context after compaction). All children share invocation-time context/settings; earlier child results must still be passed explicitly. Context excludes thinking/system instructions and pending calls; images and snapshots over 1 MiB fail without truncation. Context sharing cannot be combined with resume. Use schema for results that control branching or aggregation. Imports, filesystem globals, Date APIs, and Math.random() are unavailable.
 
-Execution mode: foreground is blocking by default when you need the result next, including parallel workflows. Pass background:true when you have independent local work (read, edit, bash) that does not touch files the workflow may change, or on an explicit background request; do that independent work first and never launch background then immediately wait. Ending a turn does not stop a background run: if the user asks to leave the workflow running, switch tasks, or check back later, report the runId and work on the other task or end your turn without waiting; otherwise retain the ID and collect it after your independent work finishes. Both modes support parallel([() => agent(...), ...]) under the same maxConcurrentSubagents cap; sequential awaits stay serial. Background changes neither permissions nor budget enforcement. Its stable handle means accepted, not completed; the receipt is not a live monitor. No completion notification wakes this session. Keep the session open: orderly shutdown requests cancellation with bounded cleanup; crashes leave uncertain evidence and restart does not adopt work. Topic usage contains the worked collection guidance.
+Execution mode: foreground is blocking by default when you need the result next, including parallel workflows. Pass background:true when you have independent local work (read, edit, bash) that does not touch files the workflow may change, or on an explicit background request; do that independent work first and never launch background then immediately wait. Ending a turn does not stop a background run: if the user asks to leave the workflow running, switch tasks, or check back later, report the runId and work on the other task or end your turn without waiting; otherwise retain the ID and collect it after your independent work finishes. Both modes support parallel([() => agent(...), ...]) under the same maxConcurrentSubagents cap; sequential awaits stay serial. Background changes neither permissions nor budget enforcement. Its stable handle means accepted, not completed; the receipt is not a live monitor, though UI sessions show active background runs in the status bar and wake the session with a follow-up message when an uncollected background run settles across turns. Keep the session open: orderly shutdown requests cancellation with bounded cleanup; crashes leave uncertain evidence and restart does not adopt work. Topic usage contains the worked collection guidance.
 
 Supervision: external_runs selects targets with runIds. list takes optional workflowRunId, cursor, workflowCursor, and limit. inspect with one id reads summary/output/diagnostics/final/launch and pages with cursor and limitBytes; several ids (up to 20) batch summary only. wait takes up to 100 runIds in mode any or all; check ok for the operation, then each completed run's outcome and pending IDs. It never cancels pending work and can return early on a failed workflow even in all mode. If settlement is already known, skip wait. Use inline successful output when available; otherwise inspect final and follow nextCursor. Failures need diagnostics/output, not final. Follow nextWorkflowCursor for workflow listings too. Foreground-call interruption cancels that call; interrupting wait only stops waiting. Use cancel with one id and an optional reason to stop background work. Cancelling a workflow stops active children; cancelling one child is a catchable workflow error. There is no live steering.
 

package/src/external-runs.ts

@@ -953,6 +953,7 @@ export function createExternalRunsTool(
           }
         }
         const served = entries.slice(startIndex, index);
+        for (const entry of served) if (!entry.run.live) options.registry.markCollected(entry.run.runId);
         const nextCursor = index < entries.length ? encodeBatchCursor(scope, runIds, index) : undefined;
         const payload = { entries: served.map((entry) => entry.legacy), ...(nextCursor ? { nextCursor } : {}) };
         return { ...result(JSON.stringify(payload), payload), data: { mode: "batch", entries: served.map((entry) => entry.run), ...(nextCursor ? { nextCursor } : {}) } };
@@ -962,12 +963,15 @@ export function createExternalRunsTool(
         assertRunId(params.runId);
         const runId = params.runId;
         const view = params.view ?? "summary";
-        const single = (text: string, encoding: "json" | "text", details: Record<string, unknown>, extra: { finalAvailable?: boolean; outputStatus?: string } = {}, contentText = text) => ({
-          ...result(contentText, details),
-          data: { mode: "single", runId, view, page: { text, encoding, complete: typeof details.nextCursor !== "string", ...(typeof details.nextCursor === "string" ? { nextCursor: details.nextCursor } : {}) }, ...compact(extra) },
-        });
         const entry = options.registry.get(runId);
         if (entry) assertOwned(entry, sessionId, project);
+        const single = (text: string, encoding: "json" | "text", details: Record<string, unknown>, extra: { finalAvailable?: boolean; outputStatus?: string } = {}, contentText = text) => {
+          if (!entry || entry.state === "terminal") options.registry.markCollected(runId);
+          return {
+            ...result(contentText, details),
+            data: { mode: "single", runId, view, page: { text, encoding, complete: typeof details.nextCursor !== "string", ...(typeof details.nextCursor === "string" ? { nextCursor: details.nextCursor } : {}) }, ...compact(extra) },
+          };
+        };
         const isWorkflowId = WORKFLOW_ID.test(runId);
         const workflowDir = getSessionWorkflowDir(ctx);
         const historical = !entry && isWorkflowId ? await loadOwnedJournal(workflowDir, runId, project) : undefined;
@@ -1162,6 +1166,7 @@ export function createExternalRunsTool(
       const outcomeByRunId = new Map(outcomes.map((outcome) => [outcome.runId, outcome] as const));
       const settled = known.flatMap((target) => {
         const outcome = outcomeByRunId.get(target.runId);
+        if (outcome) options.registry.markCollected(target.runId);
         return outcome ? [{ target, outcome }] : [];
       });
       const projected = await collectOutcomes(settled.map(({ outcome }) => outcome), runsDirectory, params.limitBytes);

package/src/pi-subagent.ts

@@ -1,6 +1,7 @@
 import { ExpectedFlowError } from "./core/errors.ts";
 import { agentOutputSchema, agentReceipt } from "./contract/agent.ts";
 import type { PublicError } from "./contract/envelope.ts";
+import { liveAgentRun, liveWorkflowRun, type PublicRun } from "./contract/run.ts";
 import { getRunRecord } from "./core/run-inspection.ts";
 import { redactSecrets } from "./core/run-record.ts";
 import {
@@ -66,6 +67,9 @@ const DEFAULT_SUBAGENT_TIMEOUT_MS = DEFAULT_EXTERNAL_SETTINGS.subagentTimeoutMs;
 const MAX_CONCURRENT_SUBAGENTS_FLAG = "max-concurrent-subagents";
 const SUBAGENT_TIMEOUT_MS_FLAG = "subagent-timeout-ms";
 const STATUS_KEY = "pi-flow";
+const BG_STATUS_KEY = "pi-flow-runs";
+const BACKGROUND_SETTLED_CUSTOM_TYPE = "pi-flow-background-settled";
+const DEFAULT_BACKGROUND_WAKE_DEBOUNCE_MS = 150;
 
 export const agentToolParameters = Type.Object({
   context: Type.Optional(parentContextSchema),
@@ -76,7 +80,7 @@ export const agentToolParameters = Type.Object({
     description: "The task briefing to send to the subagent.",
   }),
   background: Type.Optional(Type.Boolean({
-    description: "Defaults to false: wait for settlement. True returns a stable session-owned run handle after registration; work may already be settled. Pass true when you have independent local work to do first (do it, then call external_runs wait), or when the user asks to leave work running across turns (report the runId and do not call external_runs wait this turn). No completion notification; keep the owning session open.",
+    description: "Defaults to false: wait for settlement. True returns a stable session-owned run handle after registration; work may already be settled. Pass true when you have independent local work to do first (do it, then call external_runs wait), or when the user asks to leave work running across turns (report the runId and do not call external_runs wait this turn). UI sessions show active background runs in the status bar and wake the session when an uncollected run settles across turns. Keep the owning session open.",
   })),
   role: Type.Optional(Type.String({
     minLength: 1,
@@ -162,6 +166,7 @@ interface CreateAgentToolOptions {
   /** Effective default harness for render paths: cwd only, no trust signal. */
   getDefaultHarness: (cwd: string) => string;
   updateStatus: (ctx: ExtensionContext, toolCallId: string, usage: SubagentUsage) => void;
+  onSessionContext?: (ctx: ExtensionContext, sessionId: string) => void;
 }
 
 const PROGRESS_STATUSES: SubagentProgressNode["status"][] = ["queued", "running", "done", "error", "aborted"];
@@ -284,6 +289,32 @@ function formatUsageStatus(totals: SubagentUsage, theme: Theme): string {
   return `${theme.fg("dim", "pi-flow ")}${theme.fg("dim", formatUsage(totals))}`;
 }
 
+function formatBackgroundRunsStatus(roots: RegisteredRunEntry[], theme?: Theme): string | undefined {
+  if (roots.length === 0) return undefined;
+  const ids = roots.slice(0, 2).map((r) => r.runId.slice(-8)).join(", ") + (roots.length > 2 ? ", …" : "");
+  const text = `pi-flow ${roots.length} bg (${ids})`;
+  return typeof theme?.fg === "function" ? theme.fg("accent", text) : text;
+}
+
+function buildBackgroundWakePayload(entries: RegisteredRunEntry[]): { text: string; runs: PublicRun[] } {
+  const runs = entries.map((entry) =>
+    (entry.kind === "workflow" ? liveWorkflowRun(entry, { inlineBudget: 0 }) : liveAgentRun(entry, { inlineBudget: 0 })).run,
+  );
+  const lines = runs.map((run) => {
+    const label = run.task.name ?? run.task.description ?? run.kind;
+    const outcome = run.state.outcome ?? run.state.status;
+    const view = outcome === "succeeded" ? "final" : "diagnostics";
+    const failedChildren = run.children?.failed ? ` (${run.children.failed} handled child failure(s))` : "";
+    return `- ${run.runId} (${run.kind} "${label}"): ${outcome}${failedChildren} — inspect with external_runs { action: "inspect", runIds: ["${run.runId}"], view: "${view}" }`;
+  });
+  const rawText = [
+    "Background run(s) settled:",
+    ...lines,
+    "Use external_runs inspect (view: \"final\" for succeeded runs, \"diagnostics\" or \"output\" for failed runs) to read the results and report back to the user.",
+  ].join("\n");
+  return redactSecrets({ text: rawText, runs }) as { text: string; runs: PublicRun[] };
+}
+
 function publishUsageStatus(ctx: ExtensionContext, state: SubagentUsageStatusState): void {
   const totals = getUsageTotals(state);
   if (totals.input === 0 && totals.output === 0 && totals.cacheRead === 0 && totals.cacheWrite === 0) {
@@ -454,6 +485,7 @@ function createAgentTool(
 
       const queuedAt = Date.now();
       const sessionId = ctx.sessionManager?.getSessionId?.() ?? `unpersisted:${toolCallId}`;
+      options.onSessionContext?.(ctx, sessionId);
       const sessionVersion = state.registry.sessionVersion(sessionId);
       const project = resolve(ctx.cwd);
       // modelRegistry must survive into the execution context: the pi backend
@@ -595,6 +627,7 @@ function createAgentTool(
         sessionId,
         sessionVersion,
         project,
+        background,
         ...(background ? {} : { signal }),
         run: executeRun,
         outcome: (result, runSignal) => {
@@ -776,6 +809,118 @@ export function createSubagentExtension(options: SubagentExtensionOptions = {}):
       return rootState;
     };
     const usageStatusState = createUsageStatusState();
+    const wakeDebounceMs =
+      typeof options.backgroundWakeDebounceMs === "number" &&
+      Number.isInteger(options.backgroundWakeDebounceMs) &&
+      options.backgroundWakeDebounceMs >= 0
+        ? options.backgroundWakeDebounceMs
+        : DEFAULT_BACKGROUND_WAKE_DEBOUNCE_MS;
+    let activeSessionId: string | undefined;
+    let activeUiCtx: ExtensionContext | undefined;
+    let inAgentTurn = false;
+    let wakeTimer: ReturnType<typeof setTimeout> | undefined;
+    const pendingWakeBySession = new Map<string, Map<string, { entry: RegisteredRunEntry; sessionVersion: number }>>();
+
+    const rememberSessionContext = (ctx: ExtensionContext, sessionId = ctx.sessionManager?.getSessionId?.()) => {
+      if (sessionId && !sessionId.startsWith("unpersisted:")) {
+        if (activeSessionId !== sessionId) activeUiCtx = ctx;
+        activeSessionId = sessionId;
+      } else if (!activeSessionId && sessionId) {
+        activeSessionId = sessionId;
+      }
+      if (ctx.hasUI || !activeUiCtx) activeUiCtx = ctx;
+    };
+
+    const updateBackgroundStatus = (sessionId = activeSessionId) => {
+      if (!sessionId || sessionId !== activeSessionId || !activeUiCtx?.hasUI || typeof activeUiCtx.ui?.setStatus !== "function") return;
+      const roots = rootState.registry.listBackgroundRoots(sessionId);
+      try {
+        activeUiCtx.ui.setStatus(BG_STATUS_KEY, formatBackgroundRunsStatus(roots, activeUiCtx.ui.theme));
+      } catch {
+        // Ignore stale or disposed UI contexts.
+      }
+    };
+
+    const clearWakeTimer = () => {
+      if (wakeTimer) {
+        clearTimeout(wakeTimer);
+        wakeTimer = undefined;
+      }
+    };
+
+    const flushPendingWakes = (sessionId: string) => {
+      if (inAgentTurn || sessionId !== activeSessionId) return;
+      const pending = pendingWakeBySession.get(sessionId);
+      if (!pending || pending.size === 0) return;
+      pendingWakeBySession.delete(sessionId);
+      const uncollected = [...pending.values()].filter(
+        (item) =>
+          !rootState.registry.isCollected(item.entry.runId) &&
+          rootState.registry.isSessionActive(sessionId, item.sessionVersion),
+      );
+      if (uncollected.length === 0) return;
+      const payload = buildBackgroundWakePayload(uncollected.map((item) => item.entry));
+      try {
+        pi.sendMessage(
+          {
+            customType: BACKGROUND_SETTLED_CUSTOM_TYPE,
+            content: [{ type: "text", text: payload.text }],
+            display: true,
+            details: { runs: payload.runs },
+          },
+          { triggerTurn: true, deliverAs: "followUp" },
+        );
+        for (const item of uncollected) rootState.registry.markCollected(item.entry.runId);
+      } catch {
+        if (activeSessionId === sessionId) {
+          activeSessionId = undefined;
+          activeUiCtx = undefined;
+        }
+      }
+    };
+
+    const scheduleWakeFlush = (sessionId: string) => {
+      if (inAgentTurn || sessionId !== activeSessionId) return;
+      const pending = pendingWakeBySession.get(sessionId);
+      if (!pending || pending.size === 0) return;
+      clearWakeTimer();
+      wakeTimer = setTimeout(() => {
+        wakeTimer = undefined;
+        flushPendingWakes(sessionId);
+      }, wakeDebounceMs);
+      (wakeTimer as { unref?: () => void }).unref?.();
+    };
+
+    rootState.registry.onBackgroundEvent((event) => {
+      updateBackgroundStatus(event.entry.sessionId);
+      if (event.type !== "settled") return;
+      if (event.suppressed) {
+        pendingWakeBySession.get(event.entry.sessionId)?.delete(event.entry.runId);
+        return;
+      }
+      if (
+        activeUiCtx?.hasUI &&
+        activeSessionId === event.entry.sessionId &&
+        typeof activeUiCtx.ui?.notify === "function"
+      ) {
+        const outcome = event.entry.outcome?.outcome ?? "settled";
+        const label = event.entry.kind === "workflow" ? "Background workflow" : "Background subagent";
+        activeUiCtx.ui.notify(
+          redactSecrets(`${label} ${event.entry.runId} ${outcome}.`) as string,
+          outcome === "succeeded" ? "info" : "warning",
+        );
+      }
+      const shouldWake = options.backgroundWake ?? Boolean(activeUiCtx?.hasUI);
+      if (!shouldWake) return;
+      let sessionPending = pendingWakeBySession.get(event.entry.sessionId);
+      if (!sessionPending) {
+        sessionPending = new Map();
+        pendingWakeBySession.set(event.entry.sessionId, sessionPending);
+      }
+      sessionPending.set(event.entry.runId, { entry: event.entry, sessionVersion: event.sessionVersion });
+      scheduleWakeFlush(event.entry.sessionId);
+    });
+
     const toolOptions: CreateAgentToolOptions = {
       getLimiter: () => syncMaxConcurrentSubagents().limiter,
       getThinkingLevel: () => pi.getThinkingLevel(),
@@ -788,6 +933,7 @@ export function createSubagentExtension(options: SubagentExtensionOptions = {}):
         }
         updateUsageStatus(usageStatusState, ctx, toolCallId, usage);
       },
+      onSessionContext: rememberSessionContext,
     };
 
     pi.registerTool(createAgentTool(syncMaxConcurrentSubagents, toolOptions));
@@ -856,12 +1002,30 @@ export function createSubagentExtension(options: SubagentExtensionOptions = {}):
             }
             updateUsageStatus(usageStatusState, ctx, toolCallId, usage);
           },
+          onSessionContext: rememberSessionContext,
         }),
       );
     }
 
+    pi.on("agent_start", (_event, ctx) => {
+      if (!activeSessionId) rememberSessionContext(ctx);
+      inAgentTurn = true;
+      clearWakeTimer();
+    });
+
+    pi.on("agent_end", (_event, ctx) => {
+      if (!activeSessionId) rememberSessionContext(ctx);
+      inAgentTurn = false;
+      if (activeSessionId) scheduleWakeFlush(activeSessionId);
+    });
+
     pi.on("session_start", (_event, ctx) => {
-      rootState.registry.openSession(ctx.sessionManager.getSessionId());
+      const sessionId = ctx.sessionManager.getSessionId();
+      rememberSessionContext(ctx, sessionId);
+      inAgentTurn = false;
+      clearWakeTimer();
+      pendingWakeBySession.clear();
+      rootState.registry.openSession(sessionId);
       syncMaxConcurrentSubagents();
       usageStatusState.calls.clear();
       usageStatusState.latestCacheHitRate = undefined;
@@ -869,12 +1033,24 @@ export function createSubagentExtension(options: SubagentExtensionOptions = {}):
       void pruneRunRecords(runRecordsDirectory(), rootState.maxRunRecords).catch(() => undefined);
       if (ctx.hasUI) {
         ctx.ui.setStatus(STATUS_KEY, undefined);
+        ctx.ui.setStatus(BG_STATUS_KEY, undefined);
       }
     });
 
     pi.on("session_shutdown", async (_event, ctx) => {
+      const sessionId = ctx.sessionManager.getSessionId();
+      inAgentTurn = false;
+      clearWakeTimer();
+      pendingWakeBySession.delete(sessionId);
+      if (activeSessionId === sessionId) {
+        activeSessionId = undefined;
+        activeUiCtx = undefined;
+      }
       for (const controller of readinessControllers) controller.abort(new Error('Session shutting down'));
-      const cleanup = await rootState.registry.shutdownSession(ctx.sessionManager.getSessionId());
+      const cleanup = await rootState.registry.shutdownSession(sessionId);
+      if (ctx.hasUI) {
+        ctx.ui.setStatus(BG_STATUS_KEY, undefined);
+      }
       if (cleanup.pending.length && ctx.hasUI) {
         const shown = cleanup.pending.slice(0, 10);
         ctx.ui.notify(`External run cleanup could not be confirmed for ${shown.join(", ")}${cleanup.pending.length > shown.length ? ` and ${cleanup.pending.length - shown.length} more` : ""}; their evidence is interrupted or uncertain.`, "warning");
@@ -882,6 +1058,7 @@ export function createSubagentExtension(options: SubagentExtensionOptions = {}):
     });
 
     pi.on("before_agent_start", (event, ctx) => {
+      if (!activeSessionId) rememberSessionContext(ctx);
       const tools = pi.getAllTools();
       if (!tools.some((tool) => tool.name === EXTERNAL_DELEGATE_TOOL)) {
         return;

package/src/prompts.ts

@@ -100,7 +100,7 @@ Give every child an objective, the context it needs, the changes it may make, a
 
 Choose a fresh child or resume on purpose. Omit context for independent work. context {mode:"recent", turns:N} shares the last N user turns, including the current turn; {mode:"full"} shares the available post-compaction conversation. Snapshots drop thinking, system instructions, and pending calls, reject images and payloads over 1 MiB, and are sent to that harness. resume continues the same CLI child and cannot be combined with sharing. A named pi-* harness has no persisted session and no enforced budget. Prefer resume for the same task and a new child for an independent review.
 
-Default to foreground (blocking) when you need the result next, including parallel workflows. When you have independent local work (read, edit, bash) that does not touch files the delegated run may change, or the user asks for background execution, pass background:true, do that other work first, and only call external_runs wait once you actually need the result; never background then immediately wait. Ending a turn does not stop a background run: if the user asks to leave it running, switch tasks, or check back later, report the runId and end your turn or work on the other task without waiting. Otherwise retain the runId and collect it in this turn after your independent work finishes. Foreground has a live card; a background receipt is not a live monitor and completion never notifies or wakes this session. Use external_runs wait only when needed; check each run's outcome and pending IDs. Read inline successful output or inspect view final; inspect failures with diagnostics. Interrupting foreground cancels that call; interrupting wait only stops waiting. Explicit cancel stops background work. Keep the owning session open: orderly shutdown requests cancellation; restart does not adopt work. Prefer one external_workflow with parallel() for coordinated parallel tasks; all children share maxConcurrentSubagents. Sequential awaits stay serial. Report milestones. Retry a failed run, or switch its model or harness, only when the user authorized that step. agy alone may make one disclosed infrastructure retry. Nested agents may start in another workspace.
+Default to foreground (blocking) when you need the result next, including parallel workflows. When you have independent local work (read, edit, bash) that does not touch files the delegated run may change, or the user asks for background execution, pass background:true, do that other work first, and only call external_runs wait once you actually need the result; never background then immediately wait. Ending a turn does not stop a background run: if the user asks to leave it running, switch tasks, or check back later, report the runId and end your turn or work on the other task without waiting. Otherwise retain the runId and collect it in this turn after your independent work finishes. Foreground has a live card; a background receipt is not a live monitor, though UI sessions show active background runs in the status bar and wake the session with a follow-up message when an uncollected background run settles across turns. Use external_runs wait only when needed; check each run's outcome and pending IDs. Read inline successful output or inspect view final; inspect failures with diagnostics. Interrupting foreground cancels that call; interrupting wait only stops waiting. Explicit cancel stops background work. Keep the owning session open: orderly shutdown requests cancellation; restart does not adopt work. Prefer one external_workflow with parallel() for coordinated parallel tasks; all children share maxConcurrentSubagents. Sequential awaits stay serial. Report milestones. Retry a failed run, or switch its model or harness, only when the user authorized that step. agy alone may make one disclosed infrastructure retry. Nested agents may start in another workspace.
 
 Catalog availability reflects enabled harnesses and built-in/authored roles, not CLI installation or authentication. Disabled harnesses reject calls without fallback; manage them through /external config. Harness and role lifecycle commands live under /external config harness and /external config role. Role selection never falls back. external_help topic usage is the playbook; roles, permissions, and workflow are the references.`;
 }
@@ -215,7 +215,7 @@ Tell each child the objective, the context it needs, what it may change, the del
 
 Choose fresh context or resume deliberately. Omit context, or pass {"mode":"none"}, for independent work such as a review. {"mode":"recent","turns":N} and {"mode":"full"} share parent conversation and cannot be combined with resume. resume continues one prior CLI run that recorded a session id, on the same backend: ${EXTERNAL_HARNESSES.join(", ")}. A named pi-* harness has no persisted session, so resume does not continue it. Prefer resume for the same task and a new child when you want an independent judgment.
 
-Choose foreground by default when you need the result next, even for a long or parallel workflow: the original call waits for settlement and its live card carries progress. Pass background:true when you have independent local work (read, edit, bash) that does not touch files the delegated run may change, or when the user asks for background execution. Do that independent work first and never follow a background launch with an immediate external_runs wait. Ending a turn does not stop a background run: if the user asks to leave the workflow running, attend to another task, or check back later, report the runId and proceed with the other task or end your turn without waiting. Otherwise keep the ID and collect/check the outcome after your independent work finishes. The returned handle means accepted, not completed; the run may already be settled. No completion notification wakes the session. Keep Pi open: orderly shutdown requests cancellation with bounded cleanup; crashes leave uncertain evidence and restart does not adopt work.
+Choose foreground by default when you need the result next, even for a long or parallel workflow: the original call waits for settlement and its live card carries progress. Pass background:true when you have independent local work (read, edit, bash) that does not touch files the delegated run may change, or when the user asks for background execution. Do that independent work first and never follow a background launch with an immediate external_runs wait. Ending a turn does not stop a background run: if the user asks to leave the workflow running, attend to another task, or check back later, report the runId and proceed with the other task or end your turn without waiting. Otherwise keep the ID and collect/check the outcome after your independent work finishes. The returned handle means accepted, not completed; the run may already be settled. UI sessions display active background runs in the status bar and send a follow-up wake message when an uncollected background run settles across turns. Keep Pi open: orderly shutdown requests cancellation with bounded cleanup; crashes leave uncertain evidence and restart does not adopt work.
 
 Unless the user deferred collection, after independent work use external_runs wait if settlement is not already known. When the user later asks about a deferred run, inspect its runId first and wait only if it is still running. Check ok for the operation, then each completed run's state.outcome and pending IDs; a failed workflow can return wait early even in mode all. Use successful output when delivery is inline (null/false/0 are valid); otherwise inspect view final, following cursor pages. For failures inspect diagnostics or output; final is empty without verified success. A successful workflow may still have children.failed when its script caught child errors; read the reports. Interrupting the original foreground call cancels its work. Interrupting wait only stops waiting; cancel explicitly to stop background work. Cancelling a workflow stops active children; cancelling one child throws a catchable child error. Both modes share permissions, budget enforcement, and concurrency limits. A failed or aborted run stays failed. Retry it, or switch model or harness, only when the user authorized that step. agy may make one disclosed infrastructure retry; that exception is not yours to extend.
 

package/src/types.ts

@@ -76,6 +76,13 @@ export interface SubagentExtensionOptions {
    * one product, two entry points. Set to false for a subagents-only surface.
    */
   workflow?: boolean;
+  /**
+   * Automatically wake the parent session with a follow-up message when an
+   * uncollected background root run settles across a turn. Defaults to `ctx.hasUI`.
+   */
+  backgroundWake?: boolean;
+  /** Debounce window in milliseconds for batching background completion wake-ups (default: 150). */
+  backgroundWakeDebounceMs?: number;
 }
 
 export type FlowExtensionOptions = SubagentExtensionOptions;

package/src/workflow/source.ts

@@ -20,7 +20,7 @@ import type { WorkflowCachedAgentResult, WorkflowMetaPhase } from "./types.ts";
 
 export const workflowToolParameters = Type.Object({
   background: Type.Optional(Type.Boolean({
-    description: "Defaults to false: wait for settlement. True returns a stable session-owned workflow handle after registration; work may already be settled. Pass true when you have independent local work to do first (do it, then call external_runs wait), or when the user asks to leave work running across turns (report the runId and do not call external_runs wait this turn). No completion notification; keep the owning session open.",
+    description: "Defaults to false: wait for settlement. True returns a stable session-owned workflow handle after registration; work may already be settled. Pass true when you have independent local work to do first (do it, then call external_runs wait), or when the user asks to leave work running across turns (report the runId and do not call external_runs wait this turn). UI sessions show active background runs in the status bar and wake the session when an uncollected run settles across turns. Keep the owning session open.",
   })),
   script: Type.Optional(
     Type.String({

package/src/workflow/tool.ts

@@ -47,6 +47,7 @@ export interface CreateWorkflowToolOptions {
   getThinkingLevel: () => ReturnType<ExtensionAPI["getThinkingLevel"]>;
   getSubagentTimeoutMs: () => number;
   updateStatus: (ctx: ExtensionContext, toolCallId: string, usage: SubagentUsage) => void;
+  onSessionContext?: (ctx: ExtensionContext, sessionId: string) => void;
   getDefaultPermission: () => PermissionTier;
   getDefaultHarness: (ctx: ExtensionContext) => string;
   getDefaultMaxBudgetUsd: () => number | undefined;
@@ -146,6 +147,7 @@ export function createWorkflowTool(
       return await withContract<WorkflowToolDetails>({ tool: EXTERNAL_WORKFLOW_TOOL, action: "run", failureData: { run: null }, redact: true }, async () => {
       const parentMessages = captureParentContext(ctx.sessionManager);
       const sessionId = ctx.sessionManager?.getSessionId?.() ?? `unpersisted:${toolCallId}`;
+      options.onSessionContext?.(ctx, sessionId);
       const sessionVersion = options.registry.sessionVersion(sessionId);
       const project = resolve(ctx.cwd);
       // modelRegistry must survive into the execution context: the pi backend
@@ -615,6 +617,7 @@ export function createWorkflowTool(
           sessionId,
           sessionVersion,
           project,
+          background,
           ...(background ? {} : { signal }),
           run: executeWorkflow,
           outcome: (result, workflowSignal) => ({