@tt-a1i/openpi 0.2.0 → 0.3.1

package/extensions/shared/editor-layers.ts

@@ -0,0 +1,150 @@
+import {
+  CustomEditor,
+  type ExtensionAPI,
+  type ExtensionContext,
+  type KeybindingsManager,
+} from "@earendil-works/pi-coding-agent";
+import type { EditorComponent, EditorTheme, TUI } from "@earendil-works/pi-tui";
+
+const CLAIM_CHANNEL = "openpi:editor-layers:claim";
+const REGISTER_CHANNEL = "openpi:editor-layers:register";
+const REMOVE_CHANNEL = "openpi:editor-layers:remove";
+
+type EditorFactory = NonNullable<
+  ReturnType<ExtensionContext["ui"]["getEditorComponent"]>
+>;
+
+export interface EditorLayer {
+  readonly id: string;
+  readonly order: number;
+  readonly wrap: (
+    base: EditorComponent,
+    tui: TUI,
+    theme: EditorTheme,
+    keybindings: KeybindingsManager,
+  ) => EditorComponent;
+}
+
+interface EditorLayerRegistration {
+  readonly ctx: ExtensionContext;
+  readonly layer: EditorLayer;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function readRegistration(value: unknown) {
+  if (!isRecord(value) || !isRecord(value.layer)) return undefined;
+  const { ctx, layer } = value;
+  if (
+    !isRecord(ctx) ||
+    typeof layer.id !== "string" ||
+    typeof layer.order !== "number" ||
+    typeof layer.wrap !== "function"
+  ) {
+    return undefined;
+  }
+  return {
+    ctx: ctx as unknown as ExtensionContext,
+    layer: layer as unknown as EditorLayer,
+  } satisfies EditorLayerRegistration;
+}
+
+function readLayerId(value: unknown) {
+  if (!isRecord(value) || typeof value.id !== "string") return undefined;
+  return value.id;
+}
+
+function composeEditorFactory(
+  previous: EditorFactory | undefined,
+  layers: readonly EditorLayer[],
+) {
+  return ((tui, theme, keybindings) => {
+    let editor =
+      previous?.(tui, theme, keybindings) ??
+      new CustomEditor(tui, theme, keybindings);
+    for (const layer of layers) {
+      editor = layer.wrap(editor, tui, theme, keybindings);
+    }
+    return editor;
+  }) satisfies EditorFactory;
+}
+
+/**
+ * Each extension is evaluated in its own jiti module graph, so ordinary module
+ * singletons are not shared. The first OpenPI editor contributor claims the
+ * runtime EventBus and coordinates the rest through that host-owned boundary.
+ */
+function ensureCoordinator(pi: ExtensionAPI) {
+  const claim = { claimed: false };
+  pi.events.emit(CLAIM_CHANNEL, claim);
+  if (claim.claimed) return;
+
+  let ctx: ExtensionContext | undefined;
+  let installTimer: ReturnType<typeof setTimeout> | undefined;
+  const layers = new Map<string, EditorLayer>();
+
+  const cancelInstall = () => {
+    if (installTimer) clearTimeout(installTimer);
+    installTimer = undefined;
+  };
+
+  const install = () => {
+    installTimer = undefined;
+    const current = ctx;
+    if (!current || current.mode !== "tui" || layers.size === 0) return;
+    const ordered = [...layers.values()].sort(
+      (left, right) =>
+        left.order - right.order || left.id.localeCompare(right.id),
+    );
+    current.ui.setEditorComponent(
+      composeEditorFactory(current.ui.getEditorComponent(), ordered),
+    );
+  };
+
+  const scheduleInstall = () => {
+    if (installTimer) return;
+    installTimer = setTimeout(install, 0);
+  };
+
+  pi.events.on(CLAIM_CHANNEL, (value) => {
+    if (isRecord(value) && value.claimed === false) value.claimed = true;
+  });
+  pi.events.on(REGISTER_CHANNEL, (value) => {
+    const registration = readRegistration(value);
+    if (!registration || registration.ctx.mode !== "tui") return;
+    if (ctx !== registration.ctx) {
+      cancelInstall();
+      layers.clear();
+      ctx = registration.ctx;
+    }
+    layers.set(registration.layer.id, registration.layer);
+    scheduleInstall();
+  });
+  pi.events.on(REMOVE_CHANNEL, (value) => {
+    const id = readLayerId(value);
+    if (!id) return;
+    layers.delete(id);
+    if (layers.size > 0) return;
+    cancelInstall();
+    ctx = undefined;
+  });
+}
+
+export function registerEditorLayer(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  layer: EditorLayer,
+) {
+  if (ctx.mode !== "tui") return;
+  ensureCoordinator(pi);
+  pi.events.emit(REGISTER_CHANNEL, {
+    ctx,
+    layer,
+  } satisfies EditorLayerRegistration);
+}
+
+export function removeEditorLayer(pi: ExtensionAPI, id: string) {
+  pi.events.emit(REMOVE_CHANNEL, { id });
+}

package/extensions/shared/setup-config.ts

@@ -67,23 +67,12 @@ export const CAPABILITY_DISCOVERY_MODES = ["explicit", "adaptive"] as const;
 export type CapabilityDiscoveryMode =
   (typeof CAPABILITY_DISCOVERY_MODES)[number];
 
-/** Canonical default layout: one-line Powerline dashboard with flex alignment. */
+/** Canonical default layout: one-line plain footer with flex alignment. */
 export const DEFAULT_FOOTER_LINES: FooterLines = [
-  [
-    "cwd",
-    "model",
-    "thinking",
-    "context",
-    "cache",
-    "cost",
-    "throughput",
-    "flex",
-    "git",
-    "pr",
-  ],
+  ["cwd", "git", "pr", "flex", "model", "context", "cost"],
 ];
 
-export const DEFAULT_FOOTER_STYLE: FooterStyle = "powerline";
+export const DEFAULT_FOOTER_STYLE: FooterStyle = "plain";
 
 export const DEFAULT_FOOTER_ITEMS: readonly FooterItem[] =
   flattenFooterItems(DEFAULT_FOOTER_LINES);
@@ -967,7 +956,7 @@ export function formatSetupConfig(
     suggestions,
     `Workflows: ${config.workflows.concurrency} concurrent agents · ${config.workflows.maxAgentCalls} total calls`,
     `UI: large header ${config.ui.showHeader ? "on" : "off"} · custom footer ${footer}`,
-    `Subagent results: ${config.ui.subagentResultDisplay === "full" ? "full by default" : "compact preview (expand for full output)"}`,
+    `Subagent results: ${config.ui.subagentResultDisplay === "full" ? "full by default" : "compact status summary (Ctrl+O expands full output)"}`,
     `Bash operations: ${config.ui.bashToolDisplay === "full" ? "expanded by default" : "folded preview (Ctrl+O expands all)"}`,
     `Write/Edit operations: ${config.ui.fileMutationDisplay === "full" ? "expanded by default" : "folded preview (Ctrl+O expands all)"}`,
     `Post-edit command: ${config.postEdit.command ? config.postEdit.command : "off"}`,

package/extensions/subagents/index.ts

@@ -31,9 +31,9 @@ import type {
   ExtensionCommandContext,
   ExtensionContext,
   ExtensionUIContext,
+  MessageRenderer,
 } from "@earendil-works/pi-coding-agent";
 import {
-  CustomEditor,
   DEFAULT_MAX_BYTES,
   DEFAULT_MAX_LINES,
   defineTool,
@@ -69,6 +69,10 @@ import {
   OPENPI_TOOL_SURFACE,
   patchOwnedTools,
 } from "../shared/tool-surface.ts";
+import {
+  registerEditorLayer,
+  removeEditorLayer,
+} from "../shared/editor-layers.ts";
 import { formatContextUtilization } from "./src/format.ts";
 import { SubagentManager, type SubagentManagerShape } from "./src/manager.ts";
 import {
@@ -91,8 +95,7 @@ import {
   SUBAGENT_WAIT_PARAMETER_DESCRIPTIONS,
   SUBAGENT_WAIT_TOOL_DESCRIPTION,
 } from "./src/prompt.ts";
-import { createDeferredResultDelivery } from "./src/result-delivery.ts";
-import { resultDeliveryOptions } from "../background-terminals/src/result-delivery.ts";
+import { createSubagentResultDelivery } from "./src/result-delivery.ts";
 import {
   effectiveChildToolAllowlist,
   resolveStandaloneChildProjectTrust,
@@ -125,6 +128,7 @@ import {
 } from "./navigation.ts";
 import { openSubagentPicker, openSubagentTakeover } from "./src/ui/takeover.ts";
 import {
+  buildWaitResultPreview,
   renderWaitResult,
   type WaitResultDetails,
 } from "./src/ui/wait-result.ts";
@@ -148,6 +152,23 @@ interface SubagentFinishedData {
   readonly elapsed: string;
 }
 
+interface SubagentResultDetails {
+  readonly id?: string;
+  readonly title?: string;
+  readonly status?: SubagentSnapshot["status"];
+  readonly count?: number;
+  readonly results?: ReadonlyArray<{
+    readonly id: string;
+    readonly title: string;
+    readonly status: SubagentSnapshot["status"];
+  }>;
+}
+
+interface SubagentResultEntryData {
+  readonly content: string;
+  readonly details: SubagentResultDetails;
+}
+
 interface BtwResultData {
   readonly id: string;
   readonly title: string;
@@ -184,6 +205,104 @@ function truncatedOutput(
   return text;
 }
 
+export function createSubagentResultDispatcher(
+  pi: ExtensionAPI,
+  outputFor: (snap: SubagentSnapshot) => string = truncatedOutput,
+) {
+  return (snaps: readonly SubagentSnapshot[]) => {
+    if (snaps.length === 0) return;
+    const content = snaps
+      .map((snap) =>
+        buildSubagentResultMessage({
+          id: snap.id,
+          title: snap.title,
+          status: snap.status,
+          errorText: snap.errorText,
+          output: outputFor(snap),
+        }),
+      )
+      .join("\n\n");
+    const details: SubagentResultDetails =
+      snaps.length === 1
+        ? {
+            id: snaps[0]!.id,
+            title: snaps[0]!.title,
+            status: snaps[0]!.status,
+          }
+        : {
+            count: snaps.length,
+            results: snaps.map((snap) => ({
+              id: snap.id,
+              title: snap.title,
+              status: snap.status,
+            })),
+          };
+    pi.appendEntry<SubagentResultEntryData>("subagent-result", {
+      content,
+      details,
+    });
+    pi.sendMessage(
+      {
+        customType: "subagent-result",
+        content,
+        display: false,
+        details,
+      },
+      { deliverAs: "followUp", triggerTurn: true },
+    );
+  };
+}
+
+type SubagentResultTheme = Parameters<MessageRenderer>[2];
+
+function renderSubagentResult(
+  content: string,
+  details: SubagentResultDetails,
+  expanded: boolean,
+  theme: SubagentResultTheme,
+) {
+  if (!expanded && loadSetupConfig().ui.subagentResultDisplay === "compact") {
+    const results = details.results?.length
+      ? details.results
+      : details.id
+        ? [
+            {
+              id: details.id,
+              title: details.title,
+              status: details.status,
+            },
+          ]
+        : [];
+    return new Text(buildWaitResultPreview(content, { results }, theme), 0, 0);
+  }
+
+  const failed = details.status === "error";
+  const icon = failed ? theme.fg("error", "x") : theme.fg("success", "■");
+  const header =
+    `${icon} ` +
+    theme.fg("accent", theme.bold(`subagent ${details.id ?? "?"}`)) +
+    theme.fg(
+      "muted",
+      ` · ${details.title ?? ""} · ${failed ? "failed" : "finished"}`,
+    );
+
+  // Remove only the summary line. The following Error line (when present)
+  // is part of the actual result and must remain visible.
+  const body = content.split("\n").slice(1).join("\n").trim();
+  const md = new Markdown(body, 0, 0, getMarkdownTheme());
+  const container = new Text(header, 0, 0);
+  return {
+    render: (width: number) => [
+      ...container.render(width),
+      ...md.render(width),
+    ],
+    invalidate: () => {
+      container.invalidate();
+      md.invalidate();
+    },
+  };
+}
+
 export default function (pi: ExtensionAPI) {
   let runtime: SubagentRuntime | undefined;
   let managerPromise: Promise<SubagentManagerShape> | undefined;
@@ -200,8 +319,16 @@ export default function (pi: ExtensionAPI) {
   let navigationManager: SubagentManagerShape | undefined;
   let widgetVisible = false;
   let requestWidgetRender: (() => void) | undefined;
+  let navigationLayerRegistered = false;
   let dashboardOpen = false;
-  const resultDelivery = createDeferredResultDelivery<SubagentSnapshot>();
+  const dispatchResults = createSubagentResultDispatcher(pi);
+  const resultDelivery = createSubagentResultDelivery<SubagentSnapshot>({
+    isIdle: () => sessionContext?.isIdle() === true,
+    // Every unconsumed fire-and-forget result must reach the parent. The
+    // delivery coordinator batches results that settled while it was busy.
+    deliver: dispatchResults,
+  });
+  pi.on("agent_settled", () => resultDelivery.parentSettled());
   const hideLifecycleTools = () =>
     patchOwnedTools(pi, "subagents", {
       disable: OPENPI_TOOL_SURFACE.subagents.deferred,
@@ -292,79 +419,26 @@ export default function (pi: ExtensionAPI) {
 
   const installSubagentNavigation = (ctx: ExtensionContext) => {
     if (ctx.mode !== "tui") return;
-    const previous = ctx.ui.getEditorComponent();
-    ctx.ui.setEditorComponent((tui, theme, keybindings) => {
-      const base =
-        previous?.(tui, theme, keybindings) ??
-        new CustomEditor(tui, theme, keybindings);
-      return new BelowEditorNavigationEditor(
-        base,
-        keybindings,
-        stripState,
-        () => Boolean(stripEntry()),
-        () => {
-          const entry = stripEntry();
-          if (entry) void openDashboard(ctx, entry.snapshot.id);
-        },
-        () => {
-          requestWidgetRender?.();
-          tui.requestRender();
-        },
-      );
+    registerEditorLayer(pi, ctx, {
+      id: "subagents",
+      order: 100,
+      wrap: (base, tui, _theme, keybindings) =>
+        new BelowEditorNavigationEditor(
+          base,
+          keybindings,
+          stripState,
+          () => Boolean(stripEntry()),
+          () => {
+            const entry = stripEntry();
+            if (entry) void openDashboard(ctx, entry.snapshot.id);
+          },
+          () => {
+            requestWidgetRender?.();
+            tui.requestRender();
+          },
+        ),
     });
-  };
-
-  /**
-   * `wake` decides whether this costs the model a turn. A subagent that
-   * settled while the model sits idle is the result it is waiting on. A
-   * backlog that piled up while it worked is not: waking once per stale
-   * subagent forces a turn each, and the model can only answer "that one
-   * already finished". `nextTurn` still enters context with the user's next
-   * message, without demanding a reply.
-   */
-  const deliverResults = (
-    snaps: readonly SubagentSnapshot[],
-    wake: boolean,
-  ) => {
-    if (snaps.length === 0) return;
-    pi.sendMessage(
-      {
-        customType: "subagent-result",
-        // One message per flush, not per subagent.
-        content: snaps
-          .map((snap) =>
-            buildSubagentResultMessage({
-              id: snap.id,
-              title: snap.title,
-              status: snap.status,
-              errorText: snap.errorText,
-              output: truncatedOutput(snap),
-            }),
-          )
-          .join("\n\n"),
-        display: true,
-        details:
-          snaps.length === 1
-            ? {
-                id: snaps[0]!.id,
-                title: snaps[0]!.title,
-                status: snaps[0]!.status,
-              }
-            : {
-                count: snaps.length,
-                results: snaps.map((snap) => ({
-                  id: snap.id,
-                  title: snap.title,
-                  status: snap.status,
-                })),
-              },
-      },
-      resultDeliveryOptions(wake),
-    );
-  };
-
-  const flushResults = (wake: boolean) => {
-    deliverResults(resultDelivery.drain(), wake);
+    navigationLayerRegistered = true;
   };
 
   const deliverBtwResult = (snap: SubagentSnapshot) => {
@@ -412,10 +486,10 @@ export default function (pi: ExtensionAPI) {
     // subagent_wait can consume it before agent_settled flushes follow-ups.
     // Defer a copy: the live snapshot keeps mutating if the subagent is
     // restarted before the deferred result flushes.
+    // The delivery coordinator closes both sides of the wake-up race: it
+    // flushes now if the parent is already idle, otherwise the parent's next
+    // agent_settled edge rechecks this same pending Map.
     resultDelivery.defer({ ...snap, meta: { ...snap.meta } });
-    // Settled while the model sits idle: it has nothing else in flight, so
-    // this is the result it is waiting on — wake it.
-    if (sessionContext?.isIdle()) flushResults(true);
   };
 
   pi.on("session_start", (_event, ctx) => {
@@ -442,11 +516,11 @@ export default function (pi: ExtensionAPI) {
     managerPromise?.then(updateStatus).catch(() => undefined);
   });
 
-  // These settled while the model was working on something else, so they go
-  // into context without forcing a turn per stale subagent.
-  pi.on("agent_settled", () => flushResults(false));
-
   pi.on("session_shutdown", async () => {
+    if (navigationLayerRegistered) {
+      removeEditorLayer(pi, "subagents");
+      navigationLayerRegistered = false;
+    }
     resultDelivery.clear();
     unsubStatus?.();
     unsubStatus = undefined;
@@ -1051,52 +1125,28 @@ export default function (pi: ExtensionAPI) {
   pi.registerMessageRenderer(
     "subagent-result",
     (message, { expanded }, theme) => {
-      const details = (message.details ?? {}) as {
-        id?: string;
-        title?: string;
-        status?: string;
-      };
-      const failed = details.status === "error";
-      const icon = failed ? theme.fg("error", "x") : theme.fg("success", "■");
-      const header =
-        `${icon} ` +
-        theme.fg("accent", theme.bold(`subagent ${details.id ?? "?"}`)) +
-        theme.fg(
-          "muted",
-          ` · ${details.title ?? ""} · ${failed ? "failed" : "finished"}`,
-        );
-
       const content =
         typeof message.content === "string" ? message.content : "";
-      // Remove only the summary line. The following Error line (when present)
-      // is part of the actual result and must remain visible.
-      const body = content.split("\n").slice(1).join("\n").trim();
-
-      if (expanded || loadSetupConfig().ui.subagentResultDisplay === "full") {
-        const md = new Markdown(`${body}`, 0, 0, getMarkdownTheme());
-        const container = new Text(header, 0, 0);
-        return {
-          render: (width: number) => [
-            ...container.render(width),
-            ...md.render(width),
-          ],
-          invalidate: () => {
-            container.invalidate();
-            md.invalidate();
-          },
-        };
-      }
-
-      const previewLines = body.split("\n").slice(0, 8);
-      let text = header;
-      for (const line of previewLines)
-        text += `\n${theme.fg("toolOutput", line)}`;
-      if (body.split("\n").length > 8)
-        text += `\n${theme.fg("dim", `... (${keyHint("app.tools.expand", "to expand")})`)}`;
-      return new Text(text, 0, 0);
+      return renderSubagentResult(
+        content,
+        (message.details ?? {}) as SubagentResultDetails,
+        expanded,
+        theme,
+      );
     },
   );
 
+  pi.registerEntryRenderer<SubagentResultEntryData>(
+    "subagent-result",
+    (entry, { expanded }, theme) =>
+      renderSubagentResult(
+        entry.data?.content ?? "",
+        entry.data?.details ?? {},
+        expanded,
+        theme,
+      ),
+  );
+
   pi.registerEntryRenderer<SubagentFinishedData>(
     "subagent-finished",
     (entry, _options, theme) => {

package/extensions/subagents/src/prompt.ts

@@ -8,7 +8,7 @@ import { MAX_RUNNING } from "./manager.ts";
 
 /** Describes subagent_spawn, including the fixed concurrency cap. */
 export const SUBAGENT_SPAWN_TOOL_DESCRIPTION =
-  "Spawn a background subagent: a fully autonomous, headless pi session with its own context window, this environment's tools and config, and normal host permissions. Fire-and-forget: this returns immediately with an id. The subagent's final output is queued back to you as a message when it settles, or collect it explicitly with subagent_wait. Children cannot orchestrate more agents/workflows or ask the user, and cannot see this conversation, so the prompt must be self-contained. Only use trusted working directories. " +
+  "Spawn a background subagent: a fully autonomous, headless pi session with its own context window, this environment's tools and config, and normal host permissions. Fire-and-forget: this returns immediately with an id, and the subagent's final output is automatically queued back to you as a message when it settles. In an interactive session, keep working or end your turn so the user remains able to interact; do not block merely because a later step depends on the result. Children cannot orchestrate more agents/workflows or ask the user, and cannot see this conversation, so the prompt must be self-contained. Only use trusted working directories. " +
   `Max ${MAX_RUNNING} subagents can be running at once.`;
 
 /**
@@ -62,7 +62,7 @@ export const SUBAGENT_SPAWN_PROMPT_SNIPPET =
 /** Guides the parent model to delegate standalone tasks and avoid unnecessary blocking waits. */
 export const SUBAGENT_SPAWN_PROMPT_GUIDELINES = [
   "Reserve subagent_spawn for substantial, self-contained work; give it a complete, standalone prompt. For a single lookup or edit you can do inline, just do it — each subagent spends a fresh context window and cannot see this conversation.",
-  "After subagent_spawn, keep working on other things; results arrive automatically and you are re-invoked when a subagent settles. Do not poll with subagent_check and do not subagent_wait just to sit idle — wait only when your next step genuinely cannot proceed without the result, and never answer from a guessed result before it arrives.",
+  "After subagent_spawn, keep working on independent work. If none remains in an interactive session, briefly tell the user the subagent is running in the background and end your turn; its result arrives automatically and you are re-invoked when it settles. Do not poll with subagent_check. Do not call subagent_wait merely because your next step depends on the result or because you have nothing else to do. Block only when the user explicitly asks you to keep the current response open for these results, or when a non-interactive automation must return them in the same invocation. Never answer from a guessed result before it arrives.",
 ];
 
 /** Model-facing schema descriptions for subagent_spawn task and execution options. */
@@ -113,14 +113,14 @@ export function buildSubagentSpawnResult(options: {
     : "";
   return (
     `Spawned subagent ${options.id} "${options.title}" (${options.harness}: ${options.modelLabel}, ${options.cwd}).${typeNote}${toolNote}${worktreeNote}\n` +
-    `It runs in the background — keep working on other things; its result is delivered to you automatically when it finishes, so do not poll or wait for it. ` +
-    `Only if your next step truly cannot proceed without it, subagent_wait(ids: ["${options.id}"]) blocks for it; subagent_cancel stops it, subagent_check peeks at a running one, subagent_list shows all.`
+    `It runs in the background — keep working on independent work. If none remains in an interactive session, briefly tell the user it is still running and end your turn; its result is delivered automatically and you are automatically re-invoked when it finishes. Do not poll or call subagent_wait merely because a later step depends on it. ` +
+    `Use subagent_wait(ids: ["${options.id}"]) only if the user explicitly asked you to keep the current response open for this result, or a non-interactive automation must return it in the same invocation; subagent_cancel stops it, subagent_check peeks at a running one, subagent_list shows all.`
   );
 }
 
 /** Describes explicit blocking collection of one or more subagent results. */
 export const SUBAGENT_WAIT_TOOL_DESCRIPTION =
-  "Block until all listed subagents have settled, then return their final outputs. This is the EXCEPTION, not the default: after spawning, keep doing other useful work — each subagent's result is delivered to you automatically when it settles, and you'll be re-invoked then. Call subagent_wait only when your very next step cannot proceed without the result (e.g. you must synthesize several children's outputs and have nothing else to do first). Never poll for completion and never answer from a guessed result before it arrives.";
+  "Block until all listed subagents have settled, then return their final outputs. This is an explicit synchronous barrier, not the default. In an interactive session, call it only when the user explicitly asks you to keep the current response open for these results. A dependent next step or having nothing else to do is not sufficient: end your turn and let automatic result delivery re-invoke you while the user remains free to interact. In a non-interactive automation, use it only when the same invocation must return the completed results. Never poll for completion and never answer from a guessed result before it arrives.";
 
 /** Model-facing schema description for the subagent ids to await. */
 export const SUBAGENT_WAIT_PARAMETER_DESCRIPTIONS = {
@@ -154,7 +154,7 @@ export function buildSubagentSendResult(options: {
 }) {
   return options.wasRunning
     ? `Steered ${options.id} "${options.title}". It is queued into the active run; the result is delivered when it settles.`
-    : `Restarted ${options.id} "${options.title}" for another turn on its existing transcript. The result is delivered when it settles, or use subagent_wait(ids: ["${options.id}"]) to block for it.`;
+    : `Restarted ${options.id} "${options.title}" for another turn on its existing transcript. The result is delivered automatically when it settles.`;
 }
 
 /** Describes nonblocking inspection of a subagent without consuming its result. */

package/extensions/subagents/src/result-delivery.ts

@@ -1,17 +1,62 @@
-export function createDeferredResultDelivery<T extends { id: string }>() {
+export interface SubagentResultDeliveryOptions<T> {
+  /** True only when the parent has no run or queued continuation in flight. */
+  readonly isIdle: () => boolean;
+  /** Deliver one drained batch and wake the parent. */
+  readonly deliver: (results: readonly T[]) => void;
+}
+
+/**
+ * One-shot result delivery for fire-and-forget subagents.
+ *
+ * The tool contract promises that a settled child re-invokes the parent. A
+ * child that settles while the parent is busy therefore remains retractable
+ * until the parent's `agent_settled` event, but it must never be downgraded to
+ * a `nextTurn` message that needs another user prompt. There are two symmetric
+ * wake-up edges so no ordering can lose the notification:
+ *
+ * 1. child settles after the parent became idle -> `defer` flushes now;
+ * 2. parent settles after the child -> `parentSettled` flushes the batch.
+ *
+ * The parent boundary wakes even if an earlier extension handler has already
+ * started another turn: Pi queues the follow-up into that active run.
+ *
+ * The Map is the one-shot gate: `subagent_wait` may consume a result before it
+ * is delivered, and whichever path drains first prevents duplicate delivery.
+ */
+export function createSubagentResultDelivery<T extends { id: string }>(
+  options: SubagentResultDeliveryOptions<T>,
+) {
   const pending = new Map<string, T>();
 
+  const flush = () => {
+    if (pending.size === 0) return;
+    const results = [...pending.values()];
+    pending.clear();
+    try {
+      options.deliver(results);
+    } catch (error) {
+      // A synchronous session teardown may reject append/send. Preserve the
+      // original batch ahead of anything deferred re-entrantly while delivery
+      // ran, so a later boundary can retry without loss or reordering.
+      const current = [...pending.values()];
+      pending.clear();
+      for (const result of results) pending.set(result.id, result);
+      for (const result of current) pending.set(result.id, result);
+      throw error;
+    }
+  };
+
   return {
     defer(result: T) {
       pending.set(result.id, result);
+      if (options.isIdle()) flush();
     },
     consume(ids: Iterable<string>) {
       for (const id of ids) pending.delete(id);
     },
-    drain() {
-      const results = [...pending.values()];
-      pending.clear();
-      return results;
+    /** Flush at the authoritative parent boundary. */
+    parentSettled() {
+      flush();
     },
     clear() {
       pending.clear();