pi-better-subagents 0.14.1 → 0.16.0

package/README.md

@@ -35,7 +35,7 @@ Linux confinement requires a usable `bubblewrap` backend and Pi SDK 0.82.1 or ne
 
 ## Delegation Modes
 
-`config.json` sets `delegationMode` to `manual`, `adaptive` (default), or
+The user config sets `delegationMode` to `manual`, `adaptive` (default), or
 `coordinator`. `/subagents settings` (or `/subagents`) opens a settings page
 for delegation mode and the concurrent-subagent cap (default 4). Edits apply to
 this session and persist across reloads; Ctrl+S saves both as defaults, and
@@ -51,6 +51,14 @@ uses `agents_catalog` to discover current role descriptions and delegates every
 nontrivial role-owned task, while the foreground coordinates, integrates, and
 verifies. See [usage notes](docs/usage.md#delegation-mode).
 
+Saved defaults live in global `~/.pi/agent/settings.json` under
+`piBetterHarness.subagents` (or under `PI_CODING_AGENT_DIR`) and survive package
+reinstalls and upgrades. The old user config migrates on first use. Global values
+override the package's `config.json`, which remains a compatibility fallback.
+Save existing mode and cap choices with `/subagents save` or Ctrl+S. Put other
+custom config keys in `piBetterHarness.subagents` as well; edits made only inside
+the installed package can be lost on upgrade.
+
 `agents_catalog` shows each role's and named agent's default model and effort,
 such as `role developer "Developer" … default openai/gpt-6.1-sol@high`. Roles are
 listed and passed by short name (`role: "developer"`); the stored id

package/agent-commands.ts

@@ -137,21 +137,23 @@ export function registerAgentCommands(pi: Pick<ExtensionAPI, "registerCommand">,
             return items.length > 0 ? items : null;
         },
         async handler(args: string, ctx: ExtensionCommandContext) {
-            // Every invocation, including help and a dismissed picker. The
-            // context argument is the current session, not the one captured
-            // when the command was registered.
-            deps.propagateCommandContext?.(ctx);
-            return executeAgentsCommand(args, {
-                cwd: ctx.cwd,
-                hasUI: ctx.hasUI,
-                mode: ctx.mode,
-                isProjectTrusted: () => ctx.isProjectTrusted(),
-                ui: ctx.ui,
-            }, deps);
+            return executeAgentsCommandContext(args, ctx, deps);
         },
     });
 }
 
+/** Slash commands and settings shortcuts must resolve against the same live context. */
+export function executeAgentsCommandContext(args: string, ctx: ExtensionCommandContext, deps: AgentCommandDeps = {}): Promise<AgentCommandResult> {
+    deps.propagateCommandContext?.(ctx);
+    return executeAgentsCommand(args, {
+        cwd: ctx.cwd,
+        hasUI: ctx.hasUI,
+        mode: ctx.mode,
+        isProjectTrusted: () => ctx.isProjectTrusted(),
+        ui: ctx.ui,
+    }, deps);
+}
+
 export async function executeAgentsCommand(args: string, host: AgentCommandHost, deps: AgentCommandDeps = {}): Promise<AgentCommandResult> {
     const parsed = parseCommandArgs(args);
     if (parsed.positionals.length === 0 && parsed.flags.size === 0 && host.mode === "tui" && host.hasUI && host.ui.custom) parsed.positionals.push("list");

package/agent-operations.ts

@@ -18,17 +18,19 @@
 import { agentsCatalogTool, type DiscoveryDeps } from "./agents-catalog-tool.ts";
 import {
     executeAgentsCommand,
+    executeAgentsCommandContext,
     registerAgentCommands,
     type AgentCommandDeps,
     type AgentCommandHost,
     type AgentCommandResult,
 } from "./agent-commands.ts";
 import { resolveRoleAssignment, type RoleAssignment, type RoleAssignmentDecision } from "./role-assignment.ts";
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 
 export interface AgentOperationsDeps extends AgentCommandDeps, DiscoveryDeps {}
 
 export interface AgentOperationsHandle {
+    openCatalog(ctx: ExtensionCommandContext): Promise<void>;
     registerCommands(pi: Pick<ExtensionAPI, "registerCommand">): void;
     createDiscoveryTool(Type: Parameters<typeof agentsCatalogTool>[0]): ReturnType<typeof agentsCatalogTool>;
     executeCommand(args: string, host: AgentCommandHost): Promise<AgentCommandResult>;
@@ -40,6 +42,9 @@ export interface AgentOperationsHandle {
 
 export function createAgentOperations(deps: AgentOperationsDeps = {}): AgentOperationsHandle {
     return {
+        async openCatalog(ctx) {
+            await executeAgentsCommandContext("", ctx, deps);
+        },
         registerCommands(pi) {
             registerAgentCommands(pi, deps);
         },

package/config.ts

@@ -1,6 +1,6 @@
 /**
- * Extension config — a single `config.json` next to this file sets defaults for
- * every subagent, each overridable per `subagent_spawn` call.
+ * User config overrides the shipped `config.json` defaults for every subagent,
+ * each overridable per `subagent_spawn` call. Saves never edit installed files.
  *
  *   { "defaultModel": "xai/grok-4.5", "defaultTools": "read, bash, web_fetch" }
  *
@@ -8,13 +8,14 @@
  * `defaultTools` absent → the built-in SAFE_DEFAULT_TOOLS.
  */
 
-import { existsSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
 import { homedir } from "node:os";
 import { SELF_SPEC } from "./extensions.ts";
 import { isDelegationMode, type DelegationMode } from "./delegation.ts";
 import type { TimingSettings } from "./timing.ts";
+import { harnessSettingsPath, readHarnessSetting, updateHarnessSetting } from "./shared-harness-settings.ts";
 
 export interface SubagentConfig extends TimingSettings {
     /** Foreground delegation policy; /subagents mode overrides this for the current session. */
@@ -89,65 +90,82 @@ export const SAFE_CLEAN_TOOLS = "read, bash";
 
 let cached: SubagentConfig | undefined;
 let configPathForTests: string | undefined;
+let bundledConfigPathForTests: string | undefined;
 
 /** Test seam. Pass undefined to reload config.json on the next loadConfig call. */
 export function setConfigForTests(next: SubagentConfig | undefined): void {
     cached = next;
 }
 
-/** Test seam. Save and load use this file instead of the package config.json. */
-export function setConfigPathForTests(path: string | undefined): void {
+/** Test seam. Isolate user config, optionally supplying a package fallback. */
+export function setConfigPathForTests(path: string | undefined, bundledPath?: string): void {
     configPathForTests = path;
+    bundledConfigPathForTests = bundledPath;
     cached = undefined;
 }
 
 export function configPath(): string {
-    return configPathForTests ?? join(dirname(fileURLToPath(import.meta.url)), "config.json");
+    return harnessSettingsPath(configSeams());
 }
 
-/** Load config.json from the extension directory. Missing/invalid → {}. */
-export function loadConfig(): SubagentConfig {
-    if (cached) return cached;
+function configSeams() {
+    return { agentDir: () => configPathForTests ? dirname(configPathForTests) : piAgentDir() };
+}
+
+function readConfig(path: string): SubagentConfig {
+    return parseConfig(JSON.parse(readFileSync(path, "utf-8")));
+}
+
+function parseConfig(parsed: unknown): SubagentConfig {
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("Config must be a JSON object.");
+    return parsed as SubagentConfig;
+}
+
+function savedConfig(): SubagentConfig {
+    const user = readHarnessSetting("subagents", configSeams(), configPathForTests ? undefined : {
+        path: join(piAgentDir(), "extensions", "pi-better-subagents-config.json"), parse: parseConfig,
+    });
+    return user === undefined ? {} : parseConfig(user);
+}
+
+function bundledConfig(): SubagentConfig {
+    const path = bundledConfigPathForTests ?? (configPathForTests ? undefined : join(selfDir(), "config.json"));
+    if (!path) return {};
     try {
-        cached = JSON.parse(readFileSync(configPath(), "utf-8")) as SubagentConfig;
+        return readConfig(path);
     } catch {
-        cached = {};
+        return {};
     }
+}
+
+/** Saved user choices take precedence; missing/invalid files contribute no keys. */
+export function loadConfig(): SubagentConfig {
+    if (cached) return cached;
+    let user: SubagentConfig = {};
+    try { user = savedConfig(); } catch { /* retain package fallback */ }
+    cached = { ...bundledConfig(), ...user };
     return cached;
 }
 
-/** Write delegationMode into config.json, preserving every other key. */
+/** Save the navigator's mode-only default without replacing the saved cap. */
 export function writeDelegationMode(mode: DelegationMode, path = configPath()): void {
     if (!isDelegationMode(mode)) throw new Error(`Invalid delegation mode: ${String(mode)}`);
-    let current: SubagentConfig = {};
-    try {
-        const parsed = JSON.parse(readFileSync(path, "utf-8")) as unknown;
-        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) current = parsed as SubagentConfig;
-    } catch { /* missing file starts as an empty config */ }
-    current.delegationMode = mode;
-    const pending = `${path}.${process.pid}.tmp`;
-    writeFileSync(pending, `${JSON.stringify(current, null, 2)}\n`);
-    renameSync(pending, path);
-    if (path === configPath()) cached = current;
+    writeConfigSettings({ delegationMode: mode }, path);
 }
 
 /** Save human-facing defaults together, preserving unrelated configuration. */
 export function writeSubagentSettings(settings: { delegationMode: DelegationMode; maxConcurrent: number }, path = configPath()): void {
     if (!isDelegationMode(settings.delegationMode)) throw new Error("Invalid delegation mode.");
     if (!isConcurrencyCap(settings.maxConcurrent)) throw new Error("Concurrent subagents must be a positive whole number.");
-    let current: Record<string, unknown> = {};
-    try {
-        const parsed: unknown = JSON.parse(readFileSync(path, "utf-8"));
-        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("Config must be a JSON object.");
-        current = parsed as Record<string, unknown>;
-    } catch (error) {
-        if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
-    }
-    Object.assign(current, settings);
-    const pending = `${path}.${process.pid}.tmp`;
-    writeFileSync(pending, `${JSON.stringify(current, null, 2)}\n`);
-    renameSync(pending, path);
-    if (path === configPath()) cached = current as SubagentConfig;
+    writeConfigSettings(settings, path);
+}
+
+function writeConfigSettings(settings: Partial<SubagentConfig>, path: string): void {
+    if (path === configPath()) savedConfig();
+    const current = updateHarnessSetting("subagents", previous => ({
+        ...(previous === undefined ? {} : parseConfig(previous)), ...settings,
+    }), { agentDir: () => dirname(path) });
+    if (path === configPath()) cached = { ...bundledConfig(), ...current };
 }
 
 /** Normalize a comma/space tool list to pi's bare comma form: "a, b" → "a,b". */

package/docs/usage.md

@@ -14,7 +14,8 @@ launch is the result · completion triggers fetch · the foreground never blocks
 
 ## Delegation Mode
 
-Set `delegationMode` in this package's `config.json` to `manual`, `adaptive`, or
+Set `delegationMode` in the user config described under
+[Tool scoping](#tool-scoping-allowlist) to `manual`, `adaptive`, or
 `coordinator` (default `adaptive`). This controls foreground delegation guidance,
 not child permissions or catalog definitions. `/subagents settings` (or simply
 `/subagents`) opens the terminal settings page with mode and concurrent-subagent
@@ -67,7 +68,7 @@ is present; without this extension it uses adaptive guidance.
   `subagent_spawn` starts a detached `pi -p` child and returns immediately,
   leaving the session free for the human. When the child finishes, it sends a
   lightweight trigger; the foreground calls `subagent_result` and presents the
-  result (as a `followUp`, never cutting into work in progress). The foreground
+  result (as a `followUp` by default; optional busy steering is described below). The foreground
   is nudged once, at completion — never on a wait/poll loop.
 - **Subagents are autonomous; communication is one-way (parent → child).** The
   parent front-loads everything the child needs into the spawn; the child runs to
@@ -247,7 +248,7 @@ given.
   its output is durable in a log file.
 - **Completions trigger one batched turn that fetches durable results.** Ordinary
   terminal callbacks stay in the harness queue while the foreground agent is
-  busy. Once Pi is idle, they accumulate for 100 ms and share one
+  busy by default. Once Pi is idle, they accumulate for 100 ms and share one
   `pi.sendMessage(..., { deliverAs: "followUp", triggerTurn: true })` notification
   with background-task completions from the same Pi host. Each row contains only
   source, id, label, terminal status, and the `subagent_result` lookup. Full
@@ -260,6 +261,23 @@ given.
   pending records retryable, and `/reload` recovers records explicitly marked
   pending. `callback:false` sends no model message; read the durable result later
   with `subagent_result`.
+- **Optional busy steering.** In `/harness-settings`, set **Completions while
+  busy** to **Steer active run** to receive ordinary completions during
+  foreground work. Changes autosave to the current session branch and apply
+  immediately; **Ctrl+S** saves the choice as the user default for future
+  sessions, including standalone callback packages. **Wait until idle** is the
+  default. The former `PI_BETTER_CALLBACK_WHILE_BUSY` environment variable is
+  no longer supported. Completions spanning multiple accumulation windows during
+  one tool call stay together until the final active tool ends, then share one
+  compact `steer` notification without triggering a new run. Parallel and nested
+  tools are tracked together by both extensions. While busy with no active tool,
+  the normal accumulation window applies. Manual compaction and branch
+  summarization hold callbacks until an agent run starts or Pi becomes idle.
+  Idle delivery remains
+  `{ deliverAs: "followUp", triggerTurn: true }`. The same byte budget, queued overflow,
+  dedupe, delivery receipts, retry, ownership checks, and `callback:false` rules
+  apply to both modes; a completion handed off by steer is not sent again at
+  idle. Urgent health/failure alerts are unchanged.
 - **The prompt guidelines forbid polling.** The foreground agent is told, in the
   tool guidelines, that spawning is done and it must not loop on `output`/`result`
   or sleep to wait.
@@ -421,7 +439,17 @@ Precedence, highest first: the per-call `tools` param → `config.json`
 web_fetch`; just `read, bash` in a `clean` child). `exclude_tools` subtracts on
 top.
 
-`config.json` (next to the extension) also sets:
+User configuration lives in
+`~/.pi/agent/settings.json` under `piBetterHarness.subagents` (under
+`PI_CODING_AGENT_DIR` when set). The old user config migrates on first use.
+Its keys override the package's `config.json`,
+which is still read as a compatibility fallback. Settings saves write only the
+user file, so saved mode and cap survive reinstalls and upgrades without freezing
+other shipped defaults. To retain custom keys from an older package-local config,
+copy those keys into the user file before upgrading. Already-overwritten values
+cannot be recovered automatically.
+
+The effective config also sets:
 
 - `defaultModel` — model for spawns that don't specify one (`null` = inherit the
   foreground model).

package/index.ts

@@ -13,7 +13,7 @@
 
 import { execSync } from "node:child_process";
 import { writeFileSync, mkdirSync, renameSync, statSync } from "node:fs";
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import * as PiCodingAgent from "@earendil-works/pi-coding-agent";
 import * as PiTui from "@earendil-works/pi-tui";
 import { CustomEditor } from "@earendil-works/pi-coding-agent";
@@ -2283,6 +2283,31 @@ export default function (pi: ExtensionAPI) {
         },
         enrich: createLaunchEnricher(),
     });
+    const openSettings = async (ctx: ExtensionCommandContext): Promise<void> => {
+        if (ctx.mode === "tui" && ctx.hasUI && typeof ctx.ui.custom === "function") {
+            await ctx.ui.custom<void>((tui, theme, _kb, done) => createSubagentSettingsPage(theme, {
+                get: () => ({
+                    mode: activeDelegationMode(), maxConcurrent: activeConcurrencyCap(),
+                    modeSource: delegationOverride ? "session" : "config",
+                    capSource: capOverride !== undefined ? "session" : "config",
+                    defaultMode: normalizeDelegationMode(loadConfig().delegationMode),
+                    defaultCap: normalizeConcurrencyCap(loadConfig().maxConcurrent),
+                }),
+                changeMode, changeCap, save: saveSettings, reset: resetSettings,
+            }, () => { refreshBackgroundWorkNavigator(ctx); tui.requestRender(); }, () => done()));
+        } else {
+            ctx.ui.notify(`Delegation mode: ${activeDelegationMode()}. Concurrent subagents: ${activeConcurrencyCap()}. Use /subagents mode <mode> or /subagents cap <number>; /subagents save persists both.`, "info");
+        }
+    };
+    const contribution = { id: "subagents", label: "Subagents", command: "/subagents settings", open: openSettings };
+    const agentsContribution = { id: "agents", label: "Agents", command: "/agents", open: agentOperations.openCatalog };
+    const registerSettings = () => {
+        pi.events?.emit("harness-settings:register", contribution);
+        pi.events?.emit("harness-settings:register", agentsContribution);
+    };
+    const unsubscribeSettingsRequest = pi.events?.on?.("harness-settings:request", registerSettings);
+    registerSettings();
+
     if (typeof pi.registerCommand === "function") {
         agentOperations.registerCommands(pi);
         pi.registerCommand("subagents", {
@@ -2291,20 +2316,7 @@ export default function (pi: ExtensionAPI) {
             async handler(args, ctx) {
                 const tokens = args.trim().split(/\s+/).filter(Boolean);
                 if (tokens.length === 0 || (tokens.length === 1 && tokens[0] === "settings")) {
-                    if (ctx.mode === "tui" && ctx.hasUI && typeof ctx.ui.custom === "function") {
-                        await ctx.ui.custom<void>((tui, theme, _kb, done) => createSubagentSettingsPage(theme, {
-                            get: () => ({
-                                mode: activeDelegationMode(), maxConcurrent: activeConcurrencyCap(),
-                                modeSource: delegationOverride ? "session" : "config",
-                                capSource: capOverride !== undefined ? "session" : "config",
-                                defaultMode: normalizeDelegationMode(loadConfig().delegationMode),
-                                defaultCap: normalizeConcurrencyCap(loadConfig().maxConcurrent),
-                            }),
-                            changeMode, changeCap, save: saveSettings, reset: resetSettings,
-                        }, () => { refreshBackgroundWorkNavigator(ctx); tui.requestRender(); }, () => done()));
-                    } else {
-                        ctx.ui.notify(`Delegation mode: ${activeDelegationMode()}. Concurrent subagents: ${activeConcurrencyCap()}. Use /subagents mode <mode> or /subagents cap <number>; /subagents save persists both.`, "info");
-                    }
+                    await openSettings(ctx);
                     return;
                 }
                 const requested = tokens[1];
@@ -2346,18 +2358,23 @@ export default function (pi: ExtensionAPI) {
     // ---- live-status lifecycle -----------------------------------------
     pi.on("agent_start", async (_event, ctx) => {
         setCallbackBatchContext(pi, ctx);
+        getCallbackBatcher(pi).setForegroundRunning(true);
         uiCtx = ctx;
         mainAgentStartedAt = Date.now();
         mainAgentTools.clear();
         refreshBackgroundWorkNavigator(ctx);
     });
 
+    pi.on("agent_end", () => { getCallbackBatcher(pi).setForegroundRunning(false); });
+
     pi.on("tool_execution_start", async (event, ctx) => {
+        getCallbackBatcher(pi).toolStarted(event.toolCallId);
         mainAgentTools.set(event.toolCallId, event.toolName);
         refreshBackgroundWorkNavigator(ctx);
     });
 
     pi.on("tool_execution_end", async (event, ctx) => {
+        await getCallbackBatcher(pi).toolEnded(event.toolCallId);
         mainAgentTools.delete(event.toolCallId);
         refreshBackgroundWorkNavigator(ctx);
     });
@@ -2378,6 +2395,7 @@ export default function (pi: ExtensionAPI) {
     });
 
     pi.on("agent_settled", async (_event, ctx) => {
+        getCallbackBatcher(pi).setForegroundRunning(false);
         setCallbackBatchContext(pi, ctx);
         mainAgentStartedAt = undefined;
         mainAgentTools.clear();
@@ -2385,6 +2403,7 @@ export default function (pi: ExtensionAPI) {
     });
 
     pi.on("session_tree", async (_event, ctx) => {
+        setCallbackBatchContext(pi, ctx);
         agentSessionSettings.restore(ctx);
         try { noteCatalogHost(catalogHostFrom(ctx)); } catch { /* catalog inspection stays undecided */ }
         restoreDelegationMode(ctx);
@@ -2446,6 +2465,7 @@ export default function (pi: ExtensionAPI) {
 
     // Tear down the timer and clear the widget when the session ends.
     pi.on("session_shutdown", async (_event, ctx) => {
+        if (typeof unsubscribeSettingsRequest === "function") unsubscribeSettingsRequest();
         // The foreground Pi session owns this work. Stop current-session
         // running/orphaned children before dropping the session origin, so they
         // cannot become live process groups with no coordinator.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-subagents",
-  "version": "0.14.1",
+  "version": "0.16.0",
   "description": "Pi extension for detached, sandboxed subagent runs that keep the foreground session free.",
   "license": "MIT",
   "type": "module",
@@ -61,6 +61,7 @@
     "@earendil-works/pi-tui": "*"
   },
   "dependencies": {
+    "proper-lockfile": "^4.1.2",
     "smol-toml": "1.9.0",
     "yaml": "^2.9.1"
   }

package/shared-callback-batcher.ts

@@ -1,6 +1,119 @@
 // Generated from packages/callback-batcher/index.ts. Do not edit directly.
+import { join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import {
+  harnessSettingsPath,
+  readHarnessSetting,
+  updateHarnessSetting,
+  type HarnessSettingsSeams,
+} from "./shared-harness-settings.ts";
+
 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 type CallbackSettingsSeams = HarnessSettingsSeams;
+
+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 parseCallbackPreferences(value: unknown): { version: 1; mode: CallbackDeliveryMode } {
+  if (!validCallbackPreferences(value)) throw new Error('Expected { version: 1, mode: "hold" | "steer" }');
+  return value;
+}
+
+function legacyCallbackPreferencesPath(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 = harnessSettingsPath(seams);
+  try {
+    const data = readHarnessSetting<{ version: 1; mode: CallbackDeliveryMode }>("callbacks", seams, {
+      path: legacyCallbackPreferencesPath(seams),
+      parse: parseCallbackPreferences,
+    });
+    return snapshot(data === undefined ? "hold" : parseCallbackPreferences(data).mode);
+  } catch (error) {
+    const prefix = (error as NodeJS.ErrnoException).code ? "Cannot read" : "Invalid";
+    throw new Error(`${prefix} 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 path = harnessSettingsPath(seams);
+  try {
+    updateHarnessSetting("callbacks", () => ({ version: 1, mode }), seams);
+  } catch (error) {
+    throw new Error(`Cannot save callback default at ${path}: ${String(error)}`, { cause: error });
+  }
+}
+
+/** 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 +183,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 +196,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 +227,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 +255,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 +559,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 +594,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 +613,8 @@ export function createCallbackBatcher(
 
   const performFlush = async (): Promise<boolean> => {
     cancelTimer();
-    if (!available()) {
+    const mode = deliveryMode();
+    if (!mode) {
       schedule(retryMs);
       return false;
     }
@@ -539,14 +668,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 +763,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 +829,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 +869,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 {

package/shared-harness-settings.ts

@@ -0,0 +1,114 @@
+// Generated from packages/harness-settings/index.ts. Do not edit directly.
+import { existsSync, lstatSync, realpathSync, readFileSync, mkdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+// Match Pi's settings lock without depending on a private SDK import.
+const lockfile = createRequire(import.meta.url)("proper-lockfile") as {
+  lockSync(path: string, options: { realpath: boolean }): () => void;
+};
+const NAMESPACE = "piBetterHarness";
+export interface HarnessSettingsSeams { agentDir?: () => string }
+
+export function harnessSettingsPath(seams: HarnessSettingsSeams = {}): string {
+  return join((seams.agentDir ?? getAgentDir)(), "settings.json");
+}
+
+function object(value: unknown, label: string): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${label} must be a JSON object.`);
+  return value as Record<string, unknown>;
+}
+
+function readSettings(path: string): Record<string, unknown> {
+  try { return object(JSON.parse(readFileSync(path, "utf8")), `Settings at ${path}`); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return {};
+    throw error;
+  }
+}
+
+function section(settings: Record<string, unknown>): Record<string, unknown> {
+  return Object.hasOwn(settings, NAMESPACE) ? object(settings[NAMESPACE], NAMESPACE) : {};
+}
+
+function acquire(path: string): () => void {
+  for (let attempt = 0; attempt < 10; attempt++) {
+    try { return lockfile.lockSync(path, { realpath: false }); }
+    catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ELOCKED" || attempt === 9) throw error;
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 20);
+    }
+  }
+  throw new Error(`Cannot lock settings at ${path}`);
+}
+
+function lockedRead(path: string): Record<string, unknown> {
+  if (!existsSync(path)) return {};
+  const release = acquire(path);
+  try { return readSettings(path); } finally { release(); }
+}
+
+function writeDestination(path: string): string {
+  let stat;
+  try { stat = lstatSync(path); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return path;
+    throw error;
+  }
+  // Keep managed dotfiles links intact. A dangling link fails rather than being replaced.
+  return stat.isSymbolicLink() ? realpathSync(path) : path;
+}
+
+function mutate<T>(seams: HarnessSettingsSeams, change: (values: Record<string, unknown>) => T): T {
+  const path = harnessSettingsPath(seams);
+  mkdirSync((seams.agentDir ?? getAgentDir)(), { recursive: true });
+  const release = acquire(path);
+  let pending: string | undefined;
+  try {
+    // Read inside the lock so another session's settings are never replaced by a stale snapshot.
+    const settings = readSettings(path);
+    const values = section(settings);
+    const result = change(values);
+    settings[NAMESPACE] = values;
+    const destination = writeDestination(path);
+    pending = `${destination}.${randomUUID()}.tmp`;
+    writeFileSync(pending, `${JSON.stringify(settings, null, 2)}\n`, { mode: 0o600, flag: "wx" });
+    renameSync(pending, destination);
+    return result;
+  } finally {
+    try { if (pending) rmSync(pending, { force: true }); } finally { release(); }
+  }
+}
+
+export function readHarnessSetting<T = unknown>(
+  key: string,
+  seams: HarnessSettingsSeams = {},
+  legacy?: { path: string; parse: (value: unknown) => T },
+): T | undefined {
+  const values = section(lockedRead(harnessSettingsPath(seams)));
+  if (Object.hasOwn(values, key)) return values[key] as T;
+  if (!legacy) return undefined;
+  let raw: string;
+  try { raw = readFileSync(legacy.path, "utf8"); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+    throw error;
+  }
+  const migrated = legacy.parse(JSON.parse(raw));
+  return mutate(seams, current => {
+    if (!Object.hasOwn(current, key)) current[key] = migrated;
+    return current[key] as T;
+  });
+}
+
+export function updateHarnessSetting<T>(
+  key: string, update: (current: unknown) => T, seams: HarnessSettingsSeams = {},
+): T {
+  return mutate(seams, values => {
+    const next = update(values[key]);
+    values[key] = next;
+    return next;
+  });
+}

package/shared-task-tools.ts

@@ -4,7 +4,7 @@
  *
  * - Guarded tools are harness adapters that go through the task's guarded file
  *   operations, so the file rules govern them. Today: apply_patch.
- * - Trusted tools are third-party tools admitted by name AND owning package.
+ * - Trusted tools are extension tools admitted by name AND owning package.
  *   They run in the child Pi process, outside the file rules; a human ticks each
  *   one in /sandbox. Network tools are refused while Network is Off.
  */
@@ -36,15 +36,17 @@ export function defaultSubagentTools(): SubagentToolSettings {
 
 /** Tools that reach the network; refused while the profile's Network access is Off. */
 export function isNetworkTool(name: string): boolean {
-    return ["web_fetch", "web_search", "firecrawl_scrape", "firecrawl_extract", "mcp", "mcpScript", "remote_bash"].includes(name) ||
+    return ["web_fetch", "web_search", "firecrawl_scrape", "firecrawl_extract", "mcp", "mcpScript", ...SSH_TOOL_NAMES].includes(name) ||
         name.startsWith("mcp__");
 }
 
 /** Names never offered as trusted: builtins and the guarded adapters. */
 export const RESERVED_TOOL_NAMES = Object.freeze(["read", "write", "edit", "bash", "grep", "find", "ls", "powershell", "apply_patch", "process_list"]);
 
-/** Packages that are this harness: their tools are never offered as trusted tools. */
+/** Harness tools stay excluded except for the explicitly supported SSH tools. */
 const HARNESS_PACKAGES = /(^|[/:])pi-better-[a-z-]+$/;
+const SSH_PACKAGE = /(^|[/:])pi-better-ssh$/;
+const SSH_TOOL_NAMES = ["remote_bash", "ssh_profile", "ssh_mux"];
 
 /** Strict decoding: a malformed tool list must not silently admit anything. */
 export function parseSubagentTools(value: unknown): SubagentToolSettings {
@@ -95,13 +97,16 @@ export function toolPackage(tool: ToolSource): DiscoveredTool | undefined {
     return { name: tool.name, package: pkg, root: base };
 }
 
-/** Candidate trusted tools in a running Pi, excluding core builtins, guarded names and this harness. */
+/** Candidate trusted tools, excluding core builtins, guarded names and non-SSH harness tools. */
 export function discoverTrustedTools(tools: readonly ToolSource[]): DiscoveredTool[] {
     const found: DiscoveredTool[] = [];
     for (const tool of tools) {
         if (RESERVED_TOOL_NAMES.includes(tool.name)) continue;
         const owner = toolPackage(tool);
-        if (!owner || [owner.package, owner.root].some((id) => HARNESS_PACKAGES.test(id.replace(/\/+$/, "")))) continue;
+        if (!owner) continue;
+        const harnessOwners = [owner.package, owner.root].map((id) => id.replace(/\/+$/, ""))
+            .filter((id) => HARNESS_PACKAGES.test(id));
+        if (harnessOwners.length && !(SSH_TOOL_NAMES.includes(tool.name) && harnessOwners.every((id) => SSH_PACKAGE.test(id)))) continue;
         if (!found.some((t) => t.name === owner.name && t.package === owner.package)) {
             found.push(tool.sourceInfo?.source === "builtin" ? { ...owner, source: "builtin" } : owner);
         }