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

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 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
+- Clarified background execution guidance across the coordinator prompt, `external_help` (`usage` and `workflow`), tool parameter descriptions, background launch receipts, and docs:
+  - When the parent has independent local work (`read`, `edit`, `bash`) that does not touch files the delegated run may change, pass `background: true` and complete that local work before calling `external_runs wait`.
+  - Ending a turn does not stop a background run: when the user asks to leave work running, switch tasks, or check back later, report the `runId` and proceed with the other task or end the turn without calling `external_runs wait`.
+  - Background launch receipts for `external_delegate` and `external_workflow` now instruct the model to finish independent local work or report the `runId` and proceed/end its turn before calling `external_runs`, avoiding an immediate-wait reflex.
+
 ## [5.0.0-external.0] - 2026-10-15
 
 ### Breaking

package/README.md

@@ -142,19 +142,19 @@ await tools.external_delegate({
 
 ### 2. Foreground or Background?
 
-**Use foreground when you need the result next.** Use background when useful independent work can proceed, or you explicitly want to collect the result later. A long task alone does not need background mode.
+**Use foreground when you need the result next.** Use background when independent local work can proceed first, or you want to leave the work running and check back in a later turn (ending a turn does not stop it). A long task alone does not need background mode.
 
 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 |
-| Next step | Pi checks the returned outcome | Pi keeps the run ID, does independent work, then collects and checks the outcome |
+| 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 owns collection unless you explicitly ask it to defer; you should not have to manage every run yourself.
+- **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

@@ -35,9 +35,9 @@ Workspace /path/to/project
 
 **Foreground is the default:** omit `background` or set it to `false`. The original `external_delegate` or `external_workflow` call waits for settlement and returns the result or failure. Its live card carries progress while the parent waits.
 
-**Background returns a handle:** set `background: true` when the parent has useful independent work before collection, or the user explicitly requests background execution. The receipt confirms registration, not completion; a fast run may already be settled. The launch receipt is not a live monitor. Use `/external runs` to browse, or `external_runs` to inspect, wait, or cancel.
+**Background returns a handle:** set `background: true` when the parent has independent local work to do first, or when the user asks to run in the background, switch tasks, or check back in a later turn. The receipt confirms registration, not completion; a fast run may already be settled. The launch receipt is not a live monitor. Use `/external runs` to browse, or `external_runs` to inspect, wait, or cancel.
 
-Use foreground when the result is needed next—even for a long workflow or parallel children. Do not routinely launch background then immediately wait. Both modes support `parallel()` under the same concurrency limiter; neither changes permission boundaries or budget enforcement. Prompt instructions express intent, not an enforced restriction.
+Use foreground when the result is needed next—even for a long workflow or parallel children. Never launch background then immediately wait; do your independent work first, or if leaving the run active across turns, report the run ID and proceed or end your turn without waiting. Both modes support `parallel()` under the same concurrency limiter; neither changes permission boundaries or budget enforcement. Prompt instructions express intent, not an enforced restriction.
 
 ### Background Example: Launch → Independent Work → Collect
 
@@ -94,14 +94,14 @@ return { run, view, encoding, text, checklist };
 - **Check the run, not just `ok`.** `wait.ok` means supervision worked, even if a child failed. Read each `completed[i].state.outcome` and all `pending` IDs. With multiple targets, a failed workflow can return early even in `mode: "all"`; pending work continues. Keep collecting it unless the user defers, or cancel it explicitly.
 - **Avoid redundant calls.** If settlement is already known, inspect directly rather than wait again. Successful inline output needs no second fetch. A successful workflow can still have `children.failed` when the script handled child errors; check the returned reports.
 - **Read every page.** Otherwise use `final` for verified success or `diagnostics`/`output` for failure. `final` is empty without verified success. Follow `page.nextCursor`, concatenate text, and only then parse if `encoding` is `json`. Workflow final JSON wraps the value in `{ runId, result, finalAvailable }`; agent finals are text.
-- **Keep ownership.** The parent retains IDs and collects/checks results unless the user explicitly defers collection. A script's local variables do not survive a separate codemode call; pass the retained handle or ID explicitly. If independent work or collection fails, report any still-running IDs rather than abandoning them silently. Never retry a child automatically.
+- **Keep ownership.** The parent retains IDs and collects/checks results after its independent work finishes, unless the user asks to leave work running or check back later—in which case it reports the IDs and switches tasks or ends the turn without waiting. A script's local variables do not survive a separate codemode call; pass the retained handle or ID explicitly. If independent work or collection fails, report any still-running IDs rather than abandoning them silently. Never retry a child automatically.
 
 ### Interruption, Cancellation & Session Ownership
 
 - **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:** background completion does not notify, wake, or resume the parent. Ending a turn is not the same as closing the session; work can continue between turns in the owning session.
+- **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, including parallel workflows. Use background only for useful independent work or an explicit user request; 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/check results unless the user explicitly defers. 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.0-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, including parallel workflows. Use background:true only for useful independent work before collection or an explicit user request; do not routinely launch background then immediately wait. 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. Retain the ID and own collection unless the user explicitly defers it. 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.
 
@@ -107,7 +107,7 @@ Replay: resumeFromRunId works only with persisted scriptPath and starts an expli
 
 Background is an external_workflow tool call parameter ({ script, background: true }), never a meta field — meta.background is silently ignored and does not run the workflow in the background.
 
-Example (blocking by default; pass background:true on the external_workflow call only when the parent has other work):
+Example (blocking by default; pass background:true on the external_workflow call when doing independent local work first or on a background request):
 export const meta = {
   apiVersion: 1, name: "review", description: "Map and review a repository",
   phases: [

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. Use for independent work or an explicit background request. Retain the ID and collect with external_runs; 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) => {
@@ -623,7 +656,7 @@ function createAgentTool(
         });
       }
       return receipt(textResult(
-        `Subagent "${params.description}" (${subagentType}) queued as ${runRecord.runId}. Use external_runs to inspect, wait, or cancel it.`,
+        `Subagent "${params.description}" (${subagentType}) queued as ${runRecord.runId}. Do independent local work first, or report the runId and proceed/end your turn without waiting; use external_runs when ready to inspect, wait, or cancel.`,
         {
           description: params.description,
           subagentType,
@@ -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), including parallel workflows. Use background:true only for useful independent work before collection or an explicit user request; do not routinely background then immediately wait. Retain the run ID and own collection unless the user explicitly defers it. 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 foreground 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.`;
 }
@@ -134,7 +134,7 @@ export const USAGE_INDEPENDENT_REVIEW: UsageAgentExample = {
   context: { mode: "none" },
 };
 
-/** Returns after registration. The parent reads the verified answer through external_runs. */
+/** Returns after registration. The parent does independent local work first or defers collection across turns before reading through external_runs. */
 export const USAGE_BACKGROUND_AGENT: UsageAgentExample = {
   description: "Background map",
   prompt: "Map /absolute/repo read-only and return a short file list. Do not edit.",
@@ -215,9 +215,9 @@ 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, even for a long or parallel workflow: the original call waits for settlement and its live card carries progress. Use background:true for useful independent work or an explicit user request, not routinely followed by an immediate wait. The returned handle means accepted, not completed; the run may already be settled. Keep its ID and collect/check the outcome yourself unless the user explicitly defers collection. 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.
 
-After independent work, use external_runs wait if settlement is not already known. 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.
+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.
 
 One external_delegate call. Permission stays omitted; the prompt carries the no-edit intent:
 ${jsonBlock(USAGE_ONE_AGENT)}

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. Use for independent work or an explicit background request. Retain the ID and collect with external_runs; 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) => ({
@@ -649,7 +652,7 @@ export function createWorkflowTool(
       }
       return {
         ...workflowResult(
-          `Workflow "${metaName}" queued as ${identity.runId}. Use external_runs to inspect, wait, or cancel it.`,
+          `Workflow "${metaName}" queued as ${identity.runId}. Do independent local work first, or report the runId and proceed/end your turn without waiting; use external_runs when ready to inspect, wait, or cancel.`,
           { ...cloneSnapshot(snapshot), backgroundReceipt: true },
         ),
         ...workflowReceipt(options.registry.get(identity.runId)!, { inspectable: true }),