pi-better-harness 0.19.0 → 0.21.0

package/README.md

@@ -65,12 +65,13 @@ need interactive confirmation. Full policy: [pi-better-sandbox](https://github.c
 ## Minimal Tool Output
 
 The bundled harness also provides `/tool-output minimal`, `/tool-output normal`,
-and `/tool-output` (toggle). Minimal mode hides tool blocks entirely, including
-running calls, headers, results, images, summary rows, and tool spacers. Built-in,
+and `/tool-output` (toggle). Minimal mode folds each tool call into a single-line
+header, including running calls. Long headers are truncated to the terminal
+width; result bodies, images, boxes, and tool spacers are hidden. Built-in,
 extension, and MCP calls are included. Execution, sandboxing, and agent-facing
 payloads are unchanged. Ctrl+O reveals the original tool blocks; Ctrl+O again
-hides them. `/tool-output normal` restores ordinary rendering. Error results
-are also hidden in minimal mode and remain available when revealed.
+folds them. `/tool-output normal` restores ordinary rendering. Error result
+bodies are also hidden in minimal mode and remain available when expanded.
 
 Normal mode is the default. The preference is saved in the current session,
 including resume/reload. This is a version-sensitive internal TUI adapter,
@@ -85,6 +86,39 @@ Load the bundled harness or run it directly from a checkout:
 pi -e ./packages/pi-better-harness/extensions/minimal-output/index.ts
 ```
 
+## Harness Settings
+
+The bundled harness provides `/harness-settings`, using Pi's native settings
+list. It opens the settings screens of loaded Sandbox, Subagents, and Goal
+packages without duplicating their configuration. `/sandbox`, `/subagents
+settings`, and `/goal settings` remain available in standalone installations.
+Packages without a settings screen are not listed. Pi's `/settings` is unchanged.
+
+The hub also owns **Completions while busy**, shared by Subagents and Background
+Tasks. Choose **Wait until idle** (the default) or **Steer active run**. Changes
+apply immediately and autosave to the current session branch, including across
+reloads. Press **Ctrl+S** to save the current choice as your default for future
+Pi sessions; changing a session afterward does not change that saved default.
+Saving a default leaves already-open sessions unchanged, including when
+navigating to a branch without a session override.
+The user default is stored in
+`<agent-dir>/extensions/pi-better-callback-preferences.json` and also applies
+when either callback package is loaded standalone. The former
+`PI_BETTER_CALLBACK_WHILE_BUSY` environment variable is no longer supported.
+
+Next-prompt inference is deferred pending safe public auth/header resolution in
+Pi's SDK. It is not loaded by the bundle, has no toggle or preference store in
+this version, and makes no auxiliary model requests. The integration blocker is
+[issue #426](https://github.com/1aboveio/pi-better-harness/issues/426).
+
+The hub is TUI-only. The standalone-package installer does not install
+Harness-only extensions; load the bundle or the settings extension from the
+checkout to use the hub:
+
+```sh
+pi -e ./packages/pi-better-harness/extensions/settings/index.ts
+```
+
 ## When To Use
 
 Use the installer when you want every core extension with standalone package identities. Install an individual package instead when you only need the sandbox, subagents, shell task supervision, synchronous SSH, goal tracking, or plans.

package/extensions/minimal-output/hook.ts

@@ -1,9 +1,14 @@
+import { truncateToWidth, type Component } from "@earendil-works/pi-tui";
 import { readFileSync, realpathSync } from "node:fs";
 import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
 import { pathToFileURL } from "node:url";
+import { stripVTControlCharacters } from "node:util";
 
 interface ToolComponent {
+  toolName: string;
+  args: unknown;
+  callRendererComponent?: Component;
   expanded: boolean;
   showImages: boolean;
   resultRendererComponent?: unknown;
@@ -37,6 +42,20 @@ export interface MinimalOutputHook {
 const HOOK = Symbol.for("pi-better-harness.minimal-output-hook");
 const emptyResult = () => ({ render: () => [] as string[], invalidate() {} });
 
+function compactCall(component: ToolComponent, width: number): string[] {
+  if (width <= 0) return [];
+  // Render the call alone at a wider width so terminal wrapping becomes truncation.
+  const header = component.callRendererComponent?.render(Math.max(4096, width + 1))
+    .map((line) => stripVTControlCharacters(line).trim())
+    .find((line) => line.length > 0);
+  let text = header;
+  if (!text) {
+    const args = JSON.stringify(component.args);
+    text = `${component.toolName}${args && args !== "{}" ? ` ${args}` : ""}`;
+  }
+  return [truncateToWidth(text, width)];
+}
+
 function hostRequire(): NodeRequire {
   let require = createRequire(import.meta.url);
   if (process.argv[1]) {
@@ -145,7 +164,7 @@ export function installMinimalOutputHook(prototype: ToolPrototype): MinimalOutpu
         return current.enabled && !this.expanded ? "" : originals.getTextOutput.apply(this, args);
       },
       render(this: ToolComponent, width: number): string[] {
-        return current.enabled && !this.expanded ? [] : originals.render.call(this, width);
+        return current.enabled && !this.expanded ? compactCall(this, width) : originals.render.call(this, width);
       },
     };
     Object.assign(prototype, wrappers);

package/extensions/minimal-output/index.ts

@@ -56,11 +56,11 @@ export default function minimalOutputExtension(pi: ExtensionAPI): void {
   });
 
   pi.registerCommand("tool-output", {
-    description: "[minimal|normal] — Hide tool blocks entirely, or restore normal output. No argument toggles. Display only.",
+    description: "[minimal|normal] — Fold tool output into single-line call headers, or restore normal output. No argument toggles. Display only.",
     getArgumentCompletions: (argumentPrefix) => {
       const prefix = argumentPrefix.trimStart().toLowerCase();
       const matches = [
-        { value: "minimal", label: "minimal", description: "Hide all tool blocks, including running tools" },
+        { value: "minimal", label: "minimal", description: "Show compact call headers without result bodies" },
         { value: "normal", label: "normal", description: "Restore ordinary tool output" },
       ].filter((option) => option.value.startsWith(prefix));
       return matches.length > 0 ? matches : null;
@@ -78,7 +78,7 @@ export default function minimalOutputExtension(pi: ExtensionAPI): void {
       pi.appendEntry(ENTRY, { version: 1, enabled });
       status(ctx);
       ctx.ui.notify(enabled
-        ? "Minimal tool output on. Tool blocks are hidden. Ctrl+O reveals them."
+        ? "Minimal tool output on. Compact call headers remain visible. Ctrl+O reveals results."
         : "Normal tool output restored.", "info");
     },
   });

package/extensions/settings/index.ts

@@ -0,0 +1,46 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { chooseHarnessSetting } from "./page.ts";
+import { createSettingsRegistry } from "./registry.ts";
+import { changeCallbackSetting, getCallbackSettings, saveCallbackDefault } from "pi-better-background-tasks/src/shared-callback-batcher.ts";
+
+export default function harnessSettingsExtension(pi: ExtensionAPI): void {
+  const registry = createSettingsRegistry(pi);
+  pi.on("session_start", () => registry.refresh());
+  pi.on("session_shutdown", () => registry.dispose());
+
+  pi.registerCommand("harness-settings", {
+    description: "Open loaded package settings",
+    handler: async (_args, ctx) => {
+      if (ctx.mode !== "tui") { ctx.ui.notify("Harness settings requires the interactive TUI.", "warning"); return; }
+      registry.refresh();
+      let selected: string | undefined;
+      const reported = new Set<string>();
+      const readSettings = (): ReturnType<typeof getCallbackSettings> => {
+        try { return getCallbackSettings(ctx); }
+        catch (error) {
+          const message = `Callback default unavailable; using Wait until idle: ${error instanceof Error ? error.message : String(error)}`;
+          if (!reported.has(message)) { ctx.ui.notify(message, "error"); reported.add(message); }
+          return { mode: "hold", source: "default" };
+        }
+      };
+      while (true) {
+        const links = registry.list();
+        try {
+          selected = await chooseHarnessSetting(ctx, links, selected, {
+            get: readSettings,
+            change: mode => changeCallbackSetting(pi, ctx, mode),
+            save: () => saveCallbackDefault(readSettings().mode),
+          });
+        } catch (error) {
+          ctx.ui.notify(`Settings unavailable: ${error instanceof Error ? error.message : String(error)}`, "error");
+          return;
+        }
+        if (!selected) return;
+        const link = links.find(item => `link:${item.id}` === selected);
+        if (!link) continue;
+        try { await link.open(ctx); }
+        catch (error) { ctx.ui.notify(`Settings unavailable: ${error instanceof Error ? error.message : String(error)}`, "error"); }
+      }
+    },
+  });
+}

package/extensions/settings/page.ts

@@ -0,0 +1,79 @@
+import type { Theme } from "@earendil-works/pi-coding-agent";
+import { Container, SettingsList, Text, getKeybindings, setKeybindings, KeybindingsManager, TUI_KEYBINDINGS, matchesKey, type SettingItem } from "@earendil-works/pi-tui";
+import type { SettingsLink } from "./registry.ts";
+
+export interface CallbackSettingsControl {
+  get(): { mode: "hold" | "steer"; source: "session" | "default" };
+  change(mode: "hold" | "steer"): void;
+  save(): void;
+}
+
+const CALLBACK_SETTING_ID = "callbacks:while-busy";
+const callbackLabel = (mode: "hold" | "steer") => mode === "steer" ? "Steer active run" : "Wait until idle";
+
+export async function chooseHarnessSetting(ctx: any, links: SettingsLink[], selected?: string, callbacks?: CallbackSettingsControl): Promise<string | undefined> {
+  return ctx.ui.custom((tui: any, theme: Theme, _kb: unknown, done: (id?: string) => void) => {
+    let callbackMode = callbacks?.get().mode ?? "hold";
+    const callbackSetting: SettingItem | undefined = callbacks ? {
+      id: CALLBACK_SETTING_ID,
+      label: "Completions while busy",
+      currentValue: callbackLabel(callbackMode),
+      description: callbacks.get().source === "session" ? "Session setting" : "User default",
+      values: ["Wait until idle", "Steer active run"],
+    } : undefined;
+    const items: SettingItem[] = [
+      ...(callbackSetting ? [callbackSetting] : []),
+      ...links.map(link => ({ id: `link:${link.id}`, label: link.label, currentValue: link.command, description: "Open package settings", values: [link.command] })),
+    ];
+    const feedback = new Text("", 0, 0);
+    const report = (message: string, error = false) => {
+      feedback.setText(theme.fg(error ? "error" : "muted", message));
+      tui.requestRender?.();
+    };
+    const list = new SettingsList(items, 10, {
+      label: (text, active) => theme.fg(active ? "accent" : "text", text),
+      value: (text, active) => active ? theme.inverse(text) : theme.fg("muted", text),
+      description: text => theme.fg("muted", text), cursor: "> ", hint: text => theme.fg("dim", text),
+    }, (id, value) => {
+      if (id !== CALLBACK_SETTING_ID || !callbacks || !callbackSetting) { done(id); return; }
+      try {
+        const nextMode = value === "Steer active run" ? "steer" : "hold";
+        callbacks.change(nextMode);
+        callbackMode = nextMode;
+        callbackSetting.description = "Session setting";
+        report("Session setting saved.");
+      } catch (error) {
+        list.updateValue(CALLBACK_SETTING_ID, callbackLabel(callbackMode));
+        report(error instanceof Error ? error.message : String(error), true);
+      }
+    }, () => done(), { enableSearch: false });
+
+    const index = selected ? items.findIndex(item => item.id === selected) : 0;
+    if (index > 0) {
+      // SettingsList has no public selection setter. Restore synchronously using
+      // default navigation, then return the untouched user bindings before input.
+      const bindings = getKeybindings();
+      try {
+        setKeybindings(new KeybindingsManager(TUI_KEYBINDINGS));
+        for (let i = 0; i < index; i++) list.handleInput("\x1b[B");
+      } finally { setKeybindings(bindings); }
+    }
+    const page = new Container();
+    page.addChild(new Text(theme.fg("accent", theme.bold("Harness settings")), 0, 0));
+    page.addChild(list);
+    if (callbacks) page.addChild(new Text(theme.fg("dim", "Callbacks autosave to this session. Ctrl+S saves the default for future sessions."), 0, 0));
+    page.addChild(feedback);
+    return {
+      render: (width: number) => page.render(width),
+      invalidate: () => page.invalidate(),
+      handleInput(data: string) {
+        if (callbacks && matchesKey(data, "ctrl+s")) {
+          try { callbacks.save(); report("Callback default saved."); }
+          catch (error) { report(error instanceof Error ? error.message : String(error), true); }
+          return;
+        }
+        list.handleInput(data);
+      },
+    };
+  });
+}

package/extensions/settings/registry.ts

@@ -0,0 +1,27 @@
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+
+export interface SettingsLink {
+  id: string;
+  label: string;
+  command: string;
+  open(ctx: ExtensionCommandContext): Promise<void> | void;
+}
+
+export function createSettingsRegistry(pi: ExtensionAPI) {
+  const links = new Map<string, SettingsLink>();
+  const conflicts = new Set<string>();
+  const stop = pi.events.on("harness-settings:register", (candidate: unknown) => {
+    const link = candidate as Partial<SettingsLink> | null;
+    if (!link || !/^[a-z][a-z0-9-]*$/.test(link.id ?? "") || typeof link.label !== "string" ||
+      typeof link.command !== "string" || !link.command.startsWith("/") || typeof link.open !== "function") return;
+    if (conflicts.has(link.id!)) return;
+    const prior = links.get(link.id!);
+    if (prior && prior.open !== link.open) { links.delete(link.id!); conflicts.add(link.id!); return; }
+    links.set(link.id!, link as SettingsLink);
+  });
+  return {
+    refresh() { links.clear(); conflicts.clear(); pi.events.emit("harness-settings:request", undefined); },
+    list() { return [...links.values()].sort((a, b) => a.label.localeCompare(b.label)); },
+    dispose() { stop(); links.clear(); conflicts.clear(); },
+  };
+}

package/node_modules/pi-better-background-tasks/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-background-tasks",
-  "version": "0.6.5",
+  "version": "0.7.0",
   "description": "Pi extension for durable background shell tasks, watchers, logs, and status inspection.",
   "license": "MIT",
   "type": "module",

package/node_modules/pi-better-background-tasks/src/shared-callback-batcher.ts

@@ -1,6 +1,126 @@
 // Generated from packages/callback-batcher/index.ts. Do not edit directly.
+import { closeSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
 export type CallbackSource = "subagent" | "background-task";
 export type CallbackDetailTool = "subagent_result" | "bg_task_status";
+export type CallbackDeliveryMode = "hold" | "steer";
+
+export interface CallbackSettingsContext {
+  sessionManager?: { getBranch?(): readonly unknown[]; getSessionId?(): string };
+  ui?: { notify(message: string, type: "error"): void };
+}
+
+export interface CallbackSettingsSeams {
+  agentDir?: () => string;
+}
+
+export interface CallbackSettings {
+  mode: CallbackDeliveryMode;
+  source: "session" | "default";
+}
+
+export const CALLBACK_SETTINGS_ENTRY = "pi-better-callback-settings";
+const CALLBACK_PREFERENCES_FILE = "pi-better-callback-preferences.json";
+
+function isDeliveryMode(mode: unknown): mode is CallbackDeliveryMode {
+  return mode === "hold" || mode === "steer";
+}
+
+function validCallbackPreferences(value: unknown): value is { version: 1; mode: CallbackDeliveryMode } {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const data = value as Record<string, unknown>;
+  return Object.keys(data).length === 2 && Object.hasOwn(data, "version") && Object.hasOwn(data, "mode")
+    && data.version === 1 && isDeliveryMode(data.mode);
+}
+
+function callbackPreferencesPath(seams: CallbackSettingsSeams): string {
+  return join((seams.agentDir ?? getAgentDir)(), "extensions", CALLBACK_PREFERENCES_FILE);
+}
+
+/** Branch history is authoritative; abandoned branches and invalid entries are ignored. */
+export function getCallbackSettings(
+  ctx: CallbackSettingsContext,
+  seams: CallbackSettingsSeams = {},
+): CallbackSettings {
+  const branch = ctx.sessionManager?.getBranch?.() ?? [];
+  for (let i = branch.length - 1; i >= 0; i--) {
+    const entry = branch[i] as { type?: unknown; customType?: unknown; data?: unknown } | null;
+    if (entry?.type === "custom" && entry.customType === CALLBACK_SETTINGS_ENTRY && validCallbackPreferences(entry.data)) {
+      return { mode: entry.data.mode, source: "session" };
+    }
+  }
+  return getSessionDefault(ctx, seams);
+}
+
+function getSessionDefault(ctx: CallbackSettingsContext, seams: CallbackSettingsSeams): CallbackSettings {
+  const sessionId = ctx.sessionManager?.getSessionId?.();
+  const defaults = globalState().sessionDefaults ??= new WeakMap<object, { sessionId?: string; mode: CallbackDeliveryMode }>();
+  const initial = ctx.sessionManager ? defaults.get(ctx.sessionManager) : undefined;
+  if (initial && initial.sessionId === sessionId) return { mode: initial.mode, source: "default" };
+  const snapshot = (mode: CallbackDeliveryMode): CallbackSettings => {
+    if (ctx.sessionManager) defaults.set(ctx.sessionManager, { sessionId, mode });
+    return { mode, source: "default" };
+  };
+  const path = callbackPreferencesPath(seams);
+  let text: string;
+  try {
+    text = readFileSync(path, "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return snapshot("hold");
+    throw new Error(`Cannot read callback default at ${path}: ${String(error)}`, { cause: error });
+  }
+  try {
+    const data: unknown = JSON.parse(text);
+    if (!validCallbackPreferences(data)) throw new Error('Expected { version: 1, mode: "hold" | "steer" }');
+    return snapshot(data.mode);
+  } catch (error) {
+    throw new Error(`Invalid callback default at ${path}: ${String(error)}`, { cause: error });
+  }
+}
+
+/** Saves only the future-session default; never changes the active branch or batcher. */
+export function saveCallbackDefault(mode: CallbackDeliveryMode, seams: CallbackSettingsSeams = {}): void {
+  if (!isDeliveryMode(mode)) throw new Error("Invalid callback delivery mode. Nothing saved.");
+  const dir = join((seams.agentDir ?? getAgentDir)(), "extensions");
+  const path = join(dir, CALLBACK_PREFERENCES_FILE);
+  const tmp = join(dir, `.${CALLBACK_PREFERENCES_FILE}.${randomUUID()}.tmp`);
+  let created = false;
+  try {
+    mkdirSync(dir, { recursive: true });
+    const fd = openSync(tmp, "wx", 0o600);
+    created = true;
+    try { writeFileSync(fd, `${JSON.stringify({ version: 1, mode })}\n`); }
+    finally { closeSync(fd); }
+    renameSync(tmp, path);
+  } catch (error) {
+    throw new Error(`Cannot save callback default at ${path}: ${String(error)}`, { cause: error });
+  } finally {
+    if (created) rmSync(tmp, { force: true });
+  }
+}
+
+/** Persist first so a failed append cannot become a transient delivery-mode change. */
+export function changeCallbackSetting(
+  host: CallbackBatchHost & { appendEntry(customType: string, data: unknown): void },
+  ctx: CallbackSettingsContext & { isIdle(): boolean },
+  mode: CallbackDeliveryMode,
+): void {
+  if (!isDeliveryMode(mode)) throw new Error("Invalid callback delivery mode. Nothing changed.");
+  const data = { version: 1, mode };
+  try { host.appendEntry(CALLBACK_SETTINGS_ENTRY, data); }
+  catch (error) {
+    // Pi advances its in-memory branch before disk persistence. Invalidate
+    // our payload so that failed entry cannot become a restored setting.
+    data.version = 0;
+    throw error;
+  }
+  const batcher = bindCallbackBatcher(host, ctx);
+  batcher.setWhileBusy(mode);
+  batcher.setAvailability(() => ctx.isIdle());
+}
 
 export interface CallbackBatchHost {
   /** Older Pi shares this object; newer Pi supplies per-extension wrappers. */
@@ -70,6 +190,8 @@ export interface CallbackBatcherOptions {
   retryMs?: number;
   /** Ordinary callbacks stay here, not in Pi's follow-up queue, while unavailable. */
   isAvailable?: () => boolean;
+  /** Internal initial mode. Session/default settings are restored with context. */
+  whileBusy?: CallbackDeliveryMode;
   /** UTF-8 byte cap for one sendMessage payload. Defaults to 2 KiB. */
   maxBytes?: number;
 }
@@ -81,6 +203,14 @@ export interface CallbackBatcher {
   setHost(host: CallbackBatchHost): void;
   /** Update the session predicate and schedule an asynchronous drain when available. */
   setAvailability(isAvailable: () => boolean): void;
+  /** Change delivery immediately without clearing pending callbacks or handoff receipts. */
+  setWhileBusy(mode: CallbackDeliveryMode): void;
+  /** Non-idle context operations are not foreground agent runs. */
+  setForegroundRunning(running: boolean): void;
+  /** Shared IDs make duplicate notifications from both extensions idempotent. */
+  toolStarted(toolCallId: string): void;
+  /** Await the final active tool's handoff before Pi checks its steering queue. */
+  toolEnded(toolCallId: string): Promise<boolean>;
   deliverUrgent(event: UrgentCallbackEvent): boolean | Promise<boolean>;
   cancel(): void;
   pendingCount(): number;
@@ -104,6 +234,7 @@ interface PendingEvent {
 interface SharedCallbackBatcherState {
   byHost: WeakMap<object, CallbackBatcher>;
   bySession?: WeakMap<object, CallbackBatcher>;
+  sessionDefaults?: WeakMap<object, { sessionId?: string; mode: CallbackDeliveryMode }>;
 }
 
 const GLOBAL_STATE_KEY = Symbol.for("@1aboveio/pi-better-harness/callback-batcher");
@@ -131,7 +262,6 @@ const RETRIEVAL_FOOTER =
 
 export const CALLBACK_BATCH_WINDOW_ENV = "PI_BETTER_CALLBACK_BATCH_MS";
 export const DEFAULT_CALLBACK_BATCH_WINDOW_MS = DEFAULT_WINDOW_MS;
-
 export function resolveCallbackBatchWindowMs(
   value: unknown = process.env[CALLBACK_BATCH_WINDOW_ENV],
 ): number {
@@ -436,26 +566,31 @@ export function createCallbackBatcher(
 ): CallbackBatcher {
   const windowMs = options.windowMs ?? resolveCallbackBatchWindowMs();
   const retryMs = Math.max(0, options.retryMs ?? DEFAULT_RETRY_MS);
+  let whileBusy = options.whileBusy ?? "hold";
   const maxBytes = callbackBatchBudget(options.maxBytes);
   const pending = new Map<string, PendingEvent>();
   const inFlight = new Set<string>();
   const urgentInFlight = new Set<string>();
   const handedOff = new Map<string, number>();
+  const activeTools = new Set<string>();
   let sequence = 0;
   let timer: ReturnType<typeof setTimeout> | undefined;
   let flushPromise: Promise<boolean> | undefined;
   let isAvailable = options.isAvailable ?? (() => true);
   let gated = options.isAvailable !== undefined;
   let awaitingRun = false;
+  let cancelled = false;
+  let foregroundRunning = false;
 
-  const available = (): boolean => {
+  const deliveryMode = (): "followUp" | "steer" | undefined => {
+    if (cancelled) return undefined;
     try {
       if (!isAvailable()) {
         awaitingRun = false;
-        return false;
+        return whileBusy === "steer" && foregroundRunning && activeTools.size === 0 ? "steer" : undefined;
       }
-      return !awaitingRun;
-    } catch { return false; }
+      return !awaitingRun ? "followUp" : undefined;
+    } catch { return undefined; }
   };
 
   const cancelTimer = (): void => {
@@ -466,7 +601,7 @@ export function createCallbackBatcher(
   const schedule = (delayMs: number): void => {
     if (timer || pending.size === 0) return;
     // Some idle transitions (manual compaction) have no agent_settled event.
-    const delay = available() ? delayMs : retryMs;
+    const delay = deliveryMode() ? delayMs : retryMs;
     timer = setTimeout(() => {
       timer = undefined;
       void api.flush();
@@ -485,7 +620,8 @@ export function createCallbackBatcher(
 
   const performFlush = async (): Promise<boolean> => {
     cancelTimer();
-    if (!available()) {
+    const mode = deliveryMode();
+    if (!mode) {
       schedule(retryMs);
       return false;
     }
@@ -539,14 +675,16 @@ export function createCallbackBatcher(
     try {
       // Pi may defer the requested run while settled handlers finish, leaving
       // isIdle() true. Permit no second handoff until a run starts.
-      awaitingRun = gated;
+      awaitingRun = mode === "followUp" && gated;
       await host.sendMessage(
         {
           customType: "background-completion-batch",
           content: packed.text,
           display: true,
         },
-        { deliverAs: "followUp", triggerTurn: true },
+        // Newer Pi requires triggerTurn for steering too; false only appends
+        // a custom message at the turn boundary without continuing the agent.
+        { deliverAs: mode, triggerTurn: true },
       );
     } catch {
       awaitingRun = false;
@@ -632,15 +770,42 @@ export function createCallbackBatcher(
     setAvailability(check) {
       gated = true;
       isAvailable = check;
-      available();
+      cancelled = false;
+      deliveryMode();
       cancelTimer();
       schedule(windowMs);
     },
+    setWhileBusy(mode) {
+      if (!isDeliveryMode(mode)) throw new Error("Invalid callback delivery mode. Nothing changed.");
+      whileBusy = mode;
+      cancelTimer();
+      schedule(windowMs);
+    },
+    setForegroundRunning(running) {
+      foregroundRunning = running;
+      cancelTimer();
+      schedule(windowMs);
+    },
+    toolStarted(toolCallId) {
+      activeTools.add(toolCallId);
+    },
+    async toolEnded(toolCallId) {
+      const ended = activeTools.delete(toolCallId);
+      if (activeTools.size > 0 || whileBusy !== "steer" || cancelled) return false;
+      if (!ended) return flushPromise ?? false;
+      // A timer may still be completing a deferred flush. Recheck after it so
+      // the tool boundary cannot lose the pending batch to that older attempt.
+      if (flushPromise) await flushPromise;
+      return pending.size > 0 ? api.flush() : true;
+    },
     deliverUrgent,
     cancel() {
       cancelTimer();
       pending.clear();
       awaitingRun = false;
+      activeTools.clear();
+      foregroundRunning = false;
+      cancelled = true;
     },
     pendingCount() {
       return pending.size;
@@ -671,11 +836,39 @@ export function cancelCallbackBatch(host: CallbackBatchHost): void {
   batcher?.cancel();
 }
 
-/** Called on session_start, agent_start and agent_settled by both extensions. */
+/** Restore current branch/default mode without resetting foreground tools or receipts. */
 export function setCallbackBatchContext(
   host: CallbackBatchHost,
-  ctx: { isIdle(): boolean; sessionManager?: object },
+  ctx: CallbackSettingsContext & { isIdle(): boolean },
+  seams: CallbackSettingsSeams = {},
 ): void {
+  const batcher = bindCallbackBatcher(host, ctx);
+  let mode: CallbackDeliveryMode = "hold";
+  try {
+    const settings = getCallbackSettings(ctx, seams);
+    if (settings.source === "session") {
+      // Capture the initial default even when an override currently hides it,
+      // so navigating to an unconfigured branch cannot inherit a later save.
+      try { getSessionDefault(ctx, seams); }
+      catch {
+        if (ctx.sessionManager) {
+          const defaults = globalState().sessionDefaults ??= new WeakMap();
+          defaults.set(ctx.sessionManager, { sessionId: ctx.sessionManager.getSessionId?.(), mode: "hold" });
+        }
+      }
+    }
+    mode = settings.mode;
+  } catch (error) {
+    try { ctx.ui?.notify(`Callback delivery restored to hold: ${String(error)}`, "error"); }
+    catch { /* A failing UI must not retain the prior session's delivery mode. */ }
+  }
+  batcher.setWhileBusy(mode);
+  // Schedule rather than await delivery inside agent_settled: its handlers are
+  // still settling the previous run, and sendMessage may start a new one.
+  batcher.setAvailability(() => ctx.isIdle());
+}
+
+function bindCallbackBatcher(host: CallbackBatchHost, ctx: CallbackSettingsContext): CallbackBatcher {
   const state = globalState();
   const bySession = state.bySession ??= new WeakMap<object, CallbackBatcher>();
   const shared = ctx.sessionManager ? bySession.get(ctx.sessionManager) : undefined;
@@ -683,9 +876,7 @@ export function setCallbackBatchContext(
   if (ctx.sessionManager) bySession.set(ctx.sessionManager, batcher);
   state.byHost.set(host.events ?? host, batcher);
   batcher.setHost(host);
-  // Schedule rather than await delivery inside agent_settled: its handlers are
-  // still settling the previous run, and sendMessage may start a new one.
-  batcher.setAvailability(() => ctx.isIdle());
+  return batcher;
 }
 
 function globalState(): SharedCallbackBatcherState {