pi-better-harness 0.25.0 → 0.26.1

package/README.md

@@ -76,7 +76,10 @@ stays quieter than conversation text. Tool rows are indented two columns past
 the assistant text padding. 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.
+are included. Tools without a custom call renderer use a generic icon and a
+compact argument hint. Compaction summaries also collapse to one quiet row with
+the pre-compaction token count; Ctrl+O reveals their original summary.
+Execution, sandboxing, and agent-facing payloads are unchanged.
 When a foreground run ends, each consecutive block of tool calls folds further
 into one disclosure row showing the call count and any failures. Only the failure
 count uses the error color; the disclosure and total stay muted. Assistant text
@@ -91,8 +94,17 @@ all original tool details in both modes and folds them again on the next toggle.
 `/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,
+Minimal mode also covers Harness tools: Subagents, Background Tasks, Goal, Plan,
+catalog inspection, and SSH. Compact calls retain the run or task ID, launch name
+and task, background command, goal action, or plan summary without showing result
+bodies. Finished calls fold into the same disclosure blocks as built-in tools;
+expanding them restores their original package renderers. Goal and Plan widgets
+and the background-work navigator are independent UI surfaces and remain visible.
+
+Normal mode is the initial default. Changing tool output saves the choice in
+global `settings.json` under `piBetterHarness.toolOutput`, as well as the current
+session. New sessions inherit it; resumed branches retain their own saved choice.
+This is a version-sensitive internal TUI adapter,
 tested with Pi 0.82.1, 0.99.1, and the bundled Pi 1.0.0 CLI; incompatible APIs
 produce a warning and leave ordinary output enabled. Print/RPC output and
 exported transcripts are unchanged.
@@ -108,13 +120,14 @@ pi -e ./packages/pi-better-harness/extensions/minimal-output/index.ts
 
 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 duplicating their configuration, plus the **Agents** shortcut
+to the `/agents` catalog. `/sandbox`, `/subagents settings`, `/agents`, and
+`/goal settings` remain available in standalone installations.
 Packages without a settings screen are not listed. Pi's `/settings` is unchanged.
 
 The hub includes **Tool output** when the bundled renderer extension is loaded.
-Changes apply immediately to the current session and do not save a global
-default. The hub also owns **Completions while busy**, shared by Subagents and Background
+Changes apply immediately and also save the default for future sessions.
+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
@@ -122,10 +135,22 @@ 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
+`<agent-dir>/settings.json` under `piBetterHarness.callbacks` and also applies
 when either callback package is loaded standalone. The former
 `PI_BETTER_CALLBACK_WHILE_BUSY` environment variable is no longer supported.
 
+All Harness-owned defaults use the `piBetterHarness` section of global
+`~/.pi/agent/settings.json` (or `PI_CODING_AGENT_DIR/settings.json`): tool output,
+Subagents configuration, callback delivery, Goal controls, and Sandbox activation,
+permissions, and deny-rule templates. Existing preference files migrate on first
+use after validation; global choices take precedence, and old files remain intact.
+Updates preserve Pi's own settings and other packages' choices. SSH profiles,
+plans, run records, and role/agent definitions remain in their existing stores:
+they are session data or reusable definitions, not global UI defaults.
+In `/agents`, model and effort edits are session-local until Ctrl+S saves them
+to the user or project catalog definition. Saved catalog defaults also survive
+sessions and upgrades; they are not duplicated in global `settings.json`.
+
 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

package/extensions/minimal-output/hook.ts

@@ -16,6 +16,7 @@ interface ToolComponent {
   toolCallId: string;
   args: unknown;
   callRendererComponent?: Component;
+  getCallRenderer?(): unknown;
   expanded: boolean;
   isPartial?: boolean;
   result?: { isError?: boolean };
@@ -33,6 +34,14 @@ interface TranscriptComponent extends Component {
   lastMessage?: { content: { type: string; text?: string; thinking?: string }[]; stopReason?: string };
 }
 interface ToolGroup { members: ToolComponent[]; open: boolean; expanded: number }
+interface CompactionComponent extends Component {
+  expanded: boolean;
+  message: { tokensBefore: number };
+  setExpanded(expanded: boolean): void;
+}
+interface CompactionPrototype {
+  render: CompactionComponent["render"];
+}
 
 type Method = (this: ToolComponent, ...args: unknown[]) => unknown;
 interface ToolMouseEvent { type: string; button: string; x: number; y: number; screenX: number; screenY: number; width: number; shift?: boolean; alt?: boolean; ctrl?: boolean }
@@ -73,12 +82,62 @@ const TOOL_ICONS: Record<string, string> = {
   grep: "\u2315",
   find: "\u2316",
   ls: "\u2261",
+  subagent_spawn: "\u25c7",
+  subagent_spawn_batch: "\u25c7",
+  bg_task_spawn: "\u2318",
+  bg_task_watch: "\u2318",
+  bg_task: "\u2318",
+  update_goal: "\u25ce",
+  get_goal: "\u25ce",
+  goal_resume: "\u25ce",
+  update_plan: "\u2261",
+  get_plan: "\u2261",
+  remote_bash: "\u2318",
 };
 
+function harnessCallDetail(name: string, input: unknown): string | undefined {
+  const args = input && typeof input === "object" ? input as Record<string, unknown> : {};
+  const text = (value: unknown): string => typeof value === "string" ? value.replace(/\s+/g, " ").trim() : "";
+  const joinDetails = (...values: unknown[]) => values.map(text).filter(Boolean).join(" \u00b7 ");
+  const host = () => {
+    const ssh = args.ssh && typeof args.ssh === "object" ? args.ssh as Record<string, unknown> : args;
+    return text(ssh.host) ? `${text(ssh.user) ? `${text(ssh.user)}@` : ""}${text(ssh.host)}` : "";
+  };
+  switch (name) {
+    case "subagent_spawn":
+      return joinDetails(args.agent ?? args.role, args.alias ?? args.name, args.prompt);
+    case "subagent_spawn_batch":
+      return joinDetails(args.batchName, `${Array.isArray(args.jobs) ? args.jobs.length : 0} jobs`);
+    case "subagent_result": case "subagent_output": case "subagent_stop":
+    case "bg_task_status": case "bg_task_log": case "bg_task_stop":
+      return text(args.id);
+    case "subagent_list": case "bg_task_list":
+      return joinDetails(Array.isArray(args.status) ? args.status.map(text).filter(Boolean).join(", ") : args.status,
+        args.all === true ? "all sessions" : "");
+    case "agents_catalog":
+      return joinDetails(args.action, args.id);
+    case "bg_task_spawn": case "bg_task_watch": case "bg_task": case "bg_status":
+      return joinDetails(args.action, args.id, args.name, host(), args.command ??
+        (Array.isArray(args.argv) ? args.argv.map(text).filter(Boolean).join(" ") : undefined));
+    case "update_goal":
+      return text(args.status);
+    case "goal_resume":
+      return text(args.reason);
+    case "get_goal": case "get_background_activity": case "release_workflow": case "get_plan":
+      return "";
+    case "remote_bash":
+      return joinDetails(host(), args.command);
+    case "ssh_profile": case "ssh_mux":
+      return joinDetails(args.action, host(), args.all === true ? "all hosts" : "");
+    default:
+      return undefined;
+  }
+}
+
 function compactCall(component: ToolComponent, width: number, theme?: Theme, indent = 3): 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))
+  const header = Boolean(component.getCallRenderer?.()) && component.callRendererComponent?.render(Math.max(4096, width + 1))
     .map((line) => stripVTControlCharacters(line).trim())
     .find((line) => line.length > 0);
   let text = header;
@@ -90,8 +149,9 @@ function compactCall(component: ToolComponent, width: number, theme?: Theme, ind
   }
   const failed = component.result?.isError === true;
   const running = !component.result || component.isPartial;
-  const detail = text.startsWith(`${component.toolName} `) ? text.slice(component.toolName.length).trimStart()
-    : text === component.toolName ? "" : text;
+  const detail = (component.getCallRenderer?.() ? undefined : harnessCallDetail(component.toolName, component.args)) ??
+    (text.startsWith(`${component.toolName} `) ? text.slice(component.toolName.length).trimStart()
+      : text === component.toolName ? "" : text);
   const label = component.toolName === "bash" ? "Shell"
     : component.toolName.replace(/_/g, " ").replace(/^./, letter => letter.toUpperCase());
   const suffix = failed ? " (failed)" : running ? " (running)" : "";
@@ -159,6 +219,16 @@ export async function loadToolPrototype(): Promise<ToolPrototype> {
   return module.ToolExecutionComponent.prototype;
 }
 
+export async function loadCompactionPrototype(): Promise<CompactionPrototype> {
+  const entry = sdkEntry(hostRequire());
+  const path = bundledHostEntry(entry) ?? join(dirname(entry), "modes/interactive/components/compaction-summary-message.js");
+  const module = await import(pathToFileURL(path).href);
+  if (!module.CompactionSummaryMessageComponent?.prototype) {
+    throw new Error("Pi's runtime does not expose its compaction display class.");
+  }
+  return module.CompactionSummaryMessageComponent.prototype;
+}
+
 // Pi's ESM-only export cannot be resolved with require.resolve on older SDKs.
 function sdkEntry(require: ReturnType<typeof createRequire>): string {
   for (const directory of require.resolve.paths("@earendil-works/pi-coding-agent") ?? []) {
@@ -173,7 +243,7 @@ function sdkEntry(require: ReturnType<typeof createRequire>): string {
 }
 
 /** Internal TUI adapter: no tools are replaced and no result content is changed. */
-export function installMinimalOutputHook(prototype: ToolPrototype, getTheme?: () => Theme): MinimalOutputHook {
+export function installMinimalOutputHook(prototype: ToolPrototype, getTheme?: () => Theme, compactionPrototype?: CompactionPrototype): MinimalOutputHook {
   for (const name of ["updateDisplay", "getResultRenderer", "getTextOutput", "setExpanded", "invalidate", "render"] as const) {
     if (typeof prototype[name] !== "function") {
       throw new Error(`Pi's tool display API is incompatible: missing ${name}. Normal output remains enabled.`);
@@ -307,6 +377,38 @@ export function installMinimalOutputHook(prototype: ToolPrototype, getTheme?: ()
       },
     };
     const current = state;
+    const compactions = new Set<WeakRef<CompactionComponent>>();
+    const seenCompactions = new WeakSet<CompactionComponent>();
+    if (compactionPrototype) {
+      const originalRender = compactionPrototype.render;
+      const render = function(this: CompactionComponent, width: number): string[] {
+        if (!seenCompactions.has(this)) { seenCompactions.add(this); compactions.add(new WeakRef(this)); }
+        if (!current.enabled || this.expanded) return originalRender.call(this, width);
+        const detail = `from ${this.message.tokensBefore.toLocaleString()} tokens`;
+        const theme = getTheme?.();
+        const text = theme
+          ? ` ${theme.fg("muted", "\u25c7")} ${theme.fg("muted", "Compaction")}  ${theme.fg("dim", detail)}`
+          : ` \u25c7 Compaction  ${detail}`;
+        return width > 0 ? [truncateToWidth(`${" ".repeat(Math.min(3, width - 1))}${text}`, width)] : [];
+      };
+      compactionPrototype.render = render;
+      const redraw = current.redraw;
+      current.redraw = function(collapse) {
+        for (const reference of compactions) {
+          const component = reference.deref();
+          if (!component) { compactions.delete(reference); continue; }
+          if (collapse) component.setExpanded(false);
+          else component.invalidate();
+        }
+        redraw.call(this, collapse);
+      };
+      const restore = current.restore;
+      current.restore = function() {
+        if (compactionPrototype.render === render) compactionPrototype.render = originalRender;
+        compactions.clear();
+        restore.call(this);
+      };
+    }
     const wrappers = {
       updateDisplay(this: ToolComponent, ...args: unknown[]) {
         if (typeof this.ui.handleViewportInput === "function" && !inputWrappers.has(this.ui)) {

package/extensions/minimal-output/index.ts

@@ -1,6 +1,7 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { installMinimalOutputHook, loadToolPrototype, type MinimalOutputHook } from "./hook.ts";
+import { installMinimalOutputHook, loadToolPrototype, loadCompactionPrototype, type MinimalOutputHook } from "./hook.ts";
 import type { SettingsControl } from "../settings/registry.ts";
+import { readHarnessSetting, updateHarnessSetting } from "../shared-harness-settings.ts";
 
 const ENTRY = "pi-better-harness-tool-output";
 
@@ -8,6 +9,16 @@ export default function minimalOutputExtension(pi: ExtensionAPI): void {
   let hook: MinimalOutputHook | undefined;
   let enabled = false;
   let running = false;
+  let initialDefault: boolean | undefined;
+
+  function defaultEnabled(): boolean {
+    if (initialDefault !== undefined) return initialDefault;
+    const value = readHarnessSetting<{ version?: unknown; enabled?: unknown }>("toolOutput");
+    if (value !== undefined && (value?.version !== 1 || typeof value.enabled !== "boolean")) {
+      throw new Error("Invalid tool-output default in global settings.json.");
+    }
+    return initialDefault = value?.enabled === true;
+  }
 
   function status(ctx: ExtensionContext): void {
     ctx.ui.setStatus(ENTRY, enabled ? "tools: minimal" : undefined);
@@ -26,7 +37,7 @@ export default function minimalOutputExtension(pi: ExtensionAPI): void {
     }
     if (hook) return true;
     try {
-      hook = installMinimalOutputHook(await loadToolPrototype(), () => ctx.ui.theme);
+      hook = installMinimalOutputHook(await loadToolPrototype(), () => ctx.ui.theme, await loadCompactionPrototype());
       return true;
     } catch (error) {
       ctx.ui.notify(`Minimal tool output is unavailable: ${error instanceof Error ? error.message : String(error)}`, "warning");
@@ -36,7 +47,11 @@ export default function minimalOutputExtension(pi: ExtensionAPI): void {
 
   async function restore(ctx: ExtensionContext): Promise<void> {
     if (ctx.mode !== "tui") return;
-    enabled = false;
+    try { enabled = defaultEnabled(); }
+    catch (error) {
+      enabled = false;
+      ctx.ui.notify(error instanceof Error ? error.message : String(error), "warning");
+    }
     for (const entry of ctx.sessionManager.getBranch()) {
       if (entry.type === "custom" && entry.customType === ENTRY) {
         const data = entry.data as { version?: unknown; enabled?: unknown } | undefined;
@@ -59,6 +74,14 @@ export default function minimalOutputExtension(pi: ExtensionAPI): void {
     const data = { version: 1, enabled: value === "Minimal" };
     try { pi.appendEntry(ENTRY, data); }
     catch (error) { data.version = 0; data.enabled = enabled; throw error; }
+    try { updateHarnessSetting("toolOutput", () => ({ version: 1, enabled: data.enabled })); }
+    catch (error) {
+      data.version = 0;
+      data.enabled = enabled;
+      // The session entry may already be on disk; restore its prior effective value too.
+      pi.appendEntry(ENTRY, { version: 1, enabled });
+      throw error;
+    }
     enabled = data.enabled;
     if (enabled) collapseTools(ctx);
     hook!.setEnabled(enabled);
@@ -75,7 +98,7 @@ export default function minimalOutputExtension(pi: ExtensionAPI): void {
   const subscribe = () => { stopSettings ??= pi.events.on("harness-settings:request", register); };
   subscribe();
   register();
-  pi.on("session_start", async (_event, ctx) => { subscribe(); await restore(ctx); register(); });
+  pi.on("session_start", async (_event, ctx) => { initialDefault = undefined; subscribe(); await restore(ctx); register(); });
   pi.on("session_tree", async (_event, ctx) => { await restore(ctx); });
   pi.on("agent_start", () => { running = true; });
   pi.on("agent_settled", (_event, ctx) => {
@@ -91,6 +114,7 @@ export default function minimalOutputExtension(pi: ExtensionAPI): void {
     hook = undefined;
     enabled = false;
     running = false;
+    initialDefault = undefined;
   });
 
   pi.registerCommand("tool-output", {

package/extensions/settings/page.ts

@@ -23,7 +23,7 @@ export async function chooseHarnessSetting(ctx: any, links: SettingsLink[], sele
     } : undefined;
     const items: SettingItem[] = [
       ...(callbackSetting ? [callbackSetting] : []),
-      ...controls.map(control => ({ id: `setting:${control.id}`, label: control.label, currentValue: control.get(), description: "Session setting", values: control.values })),
+      ...controls.map(control => ({ id: `setting:${control.id}`, label: control.label, currentValue: control.get(), description: "User default", values: control.values })),
       ...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);
@@ -41,10 +41,10 @@ export async function chooseHarnessSetting(ctx: any, links: SettingsLink[], sele
       if (control) {
         const previous = control.get();
         changing = true;
-        report("Saving session setting...");
+        report("Saving setting...");
         Promise.resolve().then(() => control.change(value, ctx)).then(() => {
           list.updateValue(id, control.get());
-          report("Session setting saved.");
+          report("Setting saved.");
         }).catch(error => {
           list.updateValue(id, previous);
           report(error instanceof Error ? error.message : String(error), true);

package/extensions/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/node_modules/pi-better-background-tasks/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-background-tasks",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "Pi extension for durable background shell tasks, watchers, logs, and status inspection.",
   "license": "MIT",
   "type": "module",
@@ -58,5 +58,8 @@
     "typebox": "^1.1.38",
     "typescript": "^5.7.0",
     "vitest": "^3.0.0"
+  },
+  "dependencies": {
+    "proper-lockfile": "^4.1.2"
   }
 }

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

@@ -1,8 +1,12 @@
 // 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";
+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";
@@ -13,9 +17,7 @@ export interface CallbackSettingsContext {
   ui?: { notify(message: string, type: "error"): void };
 }
 
-export interface CallbackSettingsSeams {
-  agentDir?: () => string;
-}
+export type CallbackSettingsSeams = HarnessSettingsSeams;
 
 export interface CallbackSettings {
   mode: CallbackDeliveryMode;
@@ -36,7 +38,12 @@ function validCallbackPreferences(value: unknown): value is { version: 1; mode:
     && data.version === 1 && isDeliveryMode(data.mode);
 }
 
-function callbackPreferencesPath(seams: CallbackSettingsSeams): string {
+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);
 }
 
@@ -64,41 +71,27 @@ function getSessionDefault(ctx: CallbackSettingsContext, seams: CallbackSettings
     if (ctx.sessionManager) defaults.set(ctx.sessionManager, { sessionId, mode });
     return { mode, source: "default" };
   };
-  const path = callbackPreferencesPath(seams);
-  let text: string;
+  const path = harnessSettingsPath(seams);
   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);
+    const data = readHarnessSetting<{ version: 1; mode: CallbackDeliveryMode }>("callbacks", seams, {
+      path: legacyCallbackPreferencesPath(seams),
+      parse: parseCallbackPreferences,
+    });
+    return snapshot(data === undefined ? "hold" : parseCallbackPreferences(data).mode);
   } catch (error) {
-    throw new Error(`Invalid callback default at ${path}: ${String(error)}`, { cause: 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 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;
+  const path = harnessSettingsPath(seams);
   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);
+    updateHarnessSetting("callbacks", () => ({ version: 1, mode }), seams);
   } catch (error) {
     throw new Error(`Cannot save callback default at ${path}: ${String(error)}`, { cause: error });
-  } finally {
-    if (created) rmSync(tmp, { force: true });
   }
 }