pi-better-harness 0.17.1 → 0.19.0

package/README.md

@@ -1,5 +1,7 @@
 # pi-better-harness
 
+<img src="https://raw.githubusercontent.com/1aboveio/pi-better-harness/main/docs/images/brand/logo.png" alt="Pi Better Harness logo" width="128" height="128" />
+
 `pi-better-harness` is a Pi meta package that installs the core Pi Better Harness extensions: an opt-in foreground write sandbox, delegated subagents, durable background tasks, synchronous SSH commands, goal tracking, and structured plans.
 
 ## Quick Answer

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

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-background-tasks",
-  "version": "0.6.3",
+  "version": "0.6.5",
   "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

@@ -3,6 +3,8 @@ export type CallbackSource = "subagent" | "background-task";
 export type CallbackDetailTool = "subagent_result" | "bg_task_status";
 
 export interface CallbackBatchHost {
+  /** Older Pi shares this object; newer Pi supplies per-extension wrappers. */
+  events?: object;
   sendMessage(
     message: { customType: string; content: string; display: boolean },
     options: Record<string, unknown>,
@@ -66,6 +68,8 @@ export interface UrgentCallbackEvent {
 export interface CallbackBatcherOptions {
   windowMs?: number;
   retryMs?: number;
+  /** Ordinary callbacks stay here, not in Pi's follow-up queue, while unavailable. */
+  isAvailable?: () => boolean;
   /** UTF-8 byte cap for one sendMessage payload. Defaults to 2 KiB. */
   maxBytes?: number;
 }
@@ -73,6 +77,10 @@ export interface CallbackBatcherOptions {
 export interface CallbackBatcher {
   enqueue(event: CallbackBatchEvent): boolean;
   flush(): Promise<boolean>;
+  /** Refresh the API wrapper after reload without losing handoff receipts. */
+  setHost(host: CallbackBatchHost): void;
+  /** Update the session predicate and schedule an asynchronous drain when available. */
+  setAvailability(isAvailable: () => boolean): void;
   deliverUrgent(event: UrgentCallbackEvent): boolean | Promise<boolean>;
   cancel(): void;
   pendingCount(): number;
@@ -95,6 +103,7 @@ interface PendingEvent {
 
 interface SharedCallbackBatcherState {
   byHost: WeakMap<object, CallbackBatcher>;
+  bySession?: WeakMap<object, CallbackBatcher>;
 }
 
 const GLOBAL_STATE_KEY = Symbol.for("@1aboveio/pi-better-harness/callback-batcher");
@@ -435,6 +444,19 @@ export function createCallbackBatcher(
   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;
+
+  const available = (): boolean => {
+    try {
+      if (!isAvailable()) {
+        awaitingRun = false;
+        return false;
+      }
+      return !awaitingRun;
+    } catch { return false; }
+  };
 
   const cancelTimer = (): void => {
     if (timer) clearTimeout(timer);
@@ -443,10 +465,12 @@ 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;
     timer = setTimeout(() => {
       timer = undefined;
       void api.flush();
-    }, Math.max(0, delayMs));
+    }, Math.max(1, delay));
     timer.unref?.();
   };
 
@@ -461,6 +485,10 @@ export function createCallbackBatcher(
 
   const performFlush = async (): Promise<boolean> => {
     cancelTimer();
+    if (!available()) {
+      schedule(retryMs);
+      return false;
+    }
     const snapshot = [...pending.entries()]
       .sort((a, b) => a[1].sequence - b[1].sequence);
     pending.clear();
@@ -509,6 +537,9 @@ export function createCallbackBatcher(
     const overflowItems = deliverable.filter(([, item]) => !representedSet.has(item.event));
 
     try {
+      // Pi may defer the requested run while settled handlers finish, leaving
+      // isIdle() true. Permit no second handoff until a run starts.
+      awaitingRun = gated;
       await host.sendMessage(
         {
           customType: "background-completion-batch",
@@ -518,6 +549,7 @@ export function createCallbackBatcher(
         { deliverAs: "followUp", triggerTurn: true },
       );
     } catch {
+      awaitingRun = false;
       for (const [key] of deliverable) inFlight.delete(key);
       const retryItems = [...deliverable, ...pending.entries()]
         .sort((a, b) => a[1].sequence - b[1].sequence);
@@ -596,10 +628,19 @@ export function createCallbackBatcher(
   const api: CallbackBatcher = {
     enqueue,
     flush,
+    setHost(next) { host = next; },
+    setAvailability(check) {
+      gated = true;
+      isAvailable = check;
+      available();
+      cancelTimer();
+      schedule(windowMs);
+    },
     deliverUrgent,
     cancel() {
       cancelTimer();
       pending.clear();
+      awaitingRun = false;
     },
     pendingCount() {
       return pending.size;
@@ -613,16 +654,38 @@ export function getCallbackBatcher(
   options: CallbackBatcherOptions = {},
 ): CallbackBatcher {
   const state = globalState();
-  const key = host as object;
+  const key = host.events ?? host;
   const existing = state.byHost.get(key);
-  if (existing) return existing;
+  if (existing) {
+    existing.setHost(host);
+    return existing;
+  }
   const created = createCallbackBatcher(host, options);
   state.byHost.set(key, created);
   return created;
 }
 
 export function cancelCallbackBatch(host: CallbackBatchHost): void {
-  globalState().byHost.get(host as object)?.cancel();
+  const batcher = globalState().byHost.get(host.events ?? host);
+  batcher?.setAvailability(() => false);
+  batcher?.cancel();
+}
+
+/** Called on session_start, agent_start and agent_settled by both extensions. */
+export function setCallbackBatchContext(
+  host: CallbackBatchHost,
+  ctx: { isIdle(): boolean; sessionManager?: object },
+): void {
+  const state = globalState();
+  const bySession = state.bySession ??= new WeakMap<object, CallbackBatcher>();
+  const shared = ctx.sessionManager ? bySession.get(ctx.sessionManager) : undefined;
+  const batcher = shared ?? getCallbackBatcher(host);
+  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());
 }
 
 function globalState(): SharedCallbackBatcherState {

package/node_modules/pi-better-background-tasks/src/shared-sandbox-core.ts

@@ -60,6 +60,8 @@ export type SandboxPermissions = {
     storedCredentials: "off" | "read" | "read-write";
     commands: boolean;
     network: boolean;
+    /** Fixed process_list adapter only; omitted legacy profiles keep it Off. */
+    processAccess?: "off" | "read";
 };
 
 /** Whether a file access level allows creating and overwriting files. */

package/node_modules/pi-better-background-tasks/src/tools.ts

@@ -13,7 +13,7 @@ import {
   type OutputOptions,
 } from "./output.js";
 import { readOutputControls } from "./shared-log-utils.js";
-import { cancelCallbackBatch } from "./shared-callback-batcher.js";
+import { cancelCallbackBatch, setCallbackBatchContext } from "./shared-callback-batcher.js";
 import { inspectMeta, listMetasForOrigin, readMeta, writeMeta } from "./registry.js";
 import { awaitFirstWatchCheck, FIRST_WATCH_CHECK_WAIT_MS, resumeRunningTask, spawnTask, startWatchTask, stopTask, type WatchTaskParams } from "./runtime.js";
 import { runTaskMaintenance } from "./maintenance.js";
@@ -194,6 +194,7 @@ export function registerTools(pi: ExtensionAPI): void {
   const getActiveSession = () => activeSession;
 
   pi.on("session_start", async (_event, ctx) => {
+    setCallbackBatchContext(pi, ctx);
     activeSession = getCallbackOrigin(ctx);
     for (const meta of listMetasForOrigin(activeSession)) {
       if (meta.status === "running" || (meta.callback !== false && !meta.callbackSentAt && !meta.callbackSuppressedAt)) {
@@ -202,6 +203,8 @@ export function registerTools(pi: ExtensionAPI): void {
     }
     runTaskMaintenance({ activeOrigin: activeSession });
   });
+  pi.on("agent_start", (_event, ctx) => { setCallbackBatchContext(pi, ctx); });
+  pi.on("agent_settled", (_event, ctx) => { setCallbackBatchContext(pi, ctx); });
   pi.on("session_before_switch", () => {
     activeSession = undefined;
     cancelCallbackBatch(pi);

package/node_modules/pi-better-goal/README.md

@@ -13,7 +13,8 @@ Use `pi-better-goal` when a Pi session should keep an explicit objective visible
 ## Core Features
 
 - `/goal` runtime for starting, pausing, resuming, completing, and clearing the current objective.
-- `escape` pauses the active goal, and it stays paused while you talk to the agent. Say "go" (the agent then calls `goal_resume`), or use `/goal resume` or `alt+g`. `/goal pause` resumes only through `/goal resume` or `alt+g`. The status line shows `goal paused · say "go" or /goal resume`, and paused goals are never poked. On a macOS terminal without Option-as-Meta, `alt+g` types `©`; use `/goal resume` there.
+- `/goal settings` opens an interactive settings page in the TUI. Select a row with Up/Down and toggle with Space/Enter; changes save immediately, and Escape closes the page. All three controls default to `on`. Automatic continuation controls idle and background-drain wakes; conversational resume controls the agent's Escape-pause resume tool; **Pause on Esc** controls whether editor Escape pauses the active goal. Goal kickoff, `/goal resume`, and `alt+g` remain available with these controls off. For scripts or non-interactive sessions, use `/goal settings auto-continue on|off`, `/goal settings conversational-resume on|off`, and `/goal settings pause-on-escape on|off`; bare `/goal settings` prints the saved values outside the TUI.
+- `escape` pauses the active goal by default, and it stays paused while you talk to the agent. With **Pause on Esc** off, observed editor Escape leaves the goal active while preserving native streaming interruption and menu/dialog cancellation. Automatic continuation remains independent. Hosts without terminal/focus inspection and unknown custom editors retain generic abort-to-pause behavior because they cannot identify Escape reliably. With conversational resume enabled, say "go" (the agent then calls `goal_resume`), or use `/goal resume` or `alt+g`. `/goal pause` resumes only through `/goal resume` or `alt+g`. The status line shows the available resume path, and paused goals are never poked. On a macOS terminal without Option-as-Meta, `alt+g` types `©`; use `/goal resume` there.
 - Background work that finishes while an `ask_user_question` is pending is handed to the agent right after the answer.
 - A compact goal widget that does not replace Pi's footer.
 - Background activity tracking for subagents and other registered providers.

package/node_modules/pi-better-goal/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-goal",
-  "version": "0.6.1",
+  "version": "0.8.0",
   "description": "Pi extension for goal tracking with background-aware continuation.",
   "license": "MIT",
   "type": "module",

package/node_modules/pi-better-goal/src/index.ts

@@ -1,8 +1,11 @@
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { CustomEditor, ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { AutocompleteItem } from "@earendil-works/pi-tui";
+import { isKeyRelease, matchesKey } from "@earendil-works/pi-tui";
 import { readFileSync } from "node:fs";
 import { Type } from "typebox";
 import { commandAvailable, commandInvocation, resolveGoalCommand } from "./command-binding.js";
+import { goalPreferencesPath, readGoalPreferences, writeGoalPreference, type GoalPreferences } from "./preferences.js";
+import { createGoalSettingsPage } from "./settings-page.js";
 
 import {
   collectActivitySnapshot,
@@ -82,20 +85,20 @@ const GOAL_RESUME_RULE =
   "or answers a decision you explicitly asked for in your previous message with a choice that means proceed. Never call it for questions, \"why...\", \"what about...\", \"let me think\", or discussion.";
 
 /** True when the agent may resume this goal with `goal_resume`. */
-export function agentResumable(goal: GoalSnapshot | null): boolean {
-  return goal?.status === "paused" && goal.pauseReason === "interrupt";
+export function agentResumable(goal: GoalSnapshot | null, conversationalResume = true): boolean {
+  return conversationalResume && goal?.status === "paused" && goal.pauseReason === "interrupt";
 }
 
 /** Footer status for a paused goal, telling the user how to resume it. */
-export function pausedGoalStatus(goal: GoalSnapshot): string {
-  return agentResumable(goal) ? 'goal paused · say "go" or /goal resume' : "goal paused · /goal resume";
+export function pausedGoalStatus(goal: GoalSnapshot, conversationalResume = true): string {
+  return agentResumable(goal, conversationalResume) ? 'goal paused · say "go" or /goal resume' : "goal paused · /goal resume";
 }
 
-function pausedGoalPrompt(goal: GoalSnapshot): string {
+function pausedGoalPrompt(goal: GoalSnapshot, conversationalResume: boolean): string {
   return [
     `Pi Better Goal is paused because the user pressed escape. Goal: ${goal.objective}`,
     "Treat the user's messages as ordinary conversation: answer them, but do not continue the goal's work until it is resumed.",
-    GOAL_RESUME_RULE,
+    conversationalResume ? GOAL_RESUME_RULE : "Only the user can resume this goal, with /goal resume or alt+g. A conversational go-ahead does not resume it.",
   ].join("\n");
 }
 
@@ -106,10 +109,21 @@ const GOAL_ACTIONS: readonly AutocompleteItem[] = [
   { value: "resume", label: "resume", description: "Resume the paused goal" },
   { value: "clear", label: "clear", description: "Remove the current goal" },
   { value: "complete", label: "complete", description: "Mark the current goal complete" },
+  { value: "settings", label: "settings", description: "Inspect or persist goal continuation, conversational resume, and Escape pause controls" },
 ];
 
+const GOAL_SETTINGS = ["auto-continue", "conversational-resume", "pause-on-escape"] as const;
+
 export function goalArgumentCompletions(argumentPrefix: string): AutocompleteItem[] | null {
   const prefix = argumentPrefix.trimStart().toLowerCase();
+  if (prefix.startsWith("settings ")) {
+    const settingPrefix = prefix.slice("settings ".length);
+    const choices = GOAL_SETTINGS.flatMap((setting) => settingPrefix.startsWith(`${setting} `)
+      ? ["on", "off"].map((mode) => `settings ${setting} ${mode}`)
+      : [`settings ${setting}`]);
+    const matches = choices.filter((value) => value.startsWith(prefix)).map((value) => ({ value, label: value }));
+    return matches.length > 0 ? matches : null;
+  }
   const matches = GOAL_ACTIONS.filter((action) => action.value.startsWith(prefix));
   return matches.length > 0 ? [...matches] : null;
 }
@@ -214,9 +228,11 @@ function formatGoal(
   goal: GoalSnapshot | null,
   continuation: ReturnType<typeof currentContinuationState> = null,
   stall = observeGoalStall(goal, continuation),
+  preferences: GoalPreferences = { autoContinue: true, conversationalResume: true, pauseOnEscape: true },
 ): string {
+  const settings = formatPreferences(preferences);
   if (!goal) {
-    return "No goal is set.";
+    return `No goal is set.\n${settings}`;
   }
   const budget = goal.tokenBudget === null ? "none" : String(goal.tokenBudget);
   const timing = goalTiming(goal);
@@ -232,14 +248,23 @@ function formatGoal(
     `Elapsed time: ${timing.elapsedSeconds}s`,
     `Observable progress: ${stall?.state ?? "unknown"}`,
     continuationStatus,
+    settings,
     ...(goal.status === "paused"
-      ? [agentResumable(goal)
+      ? [agentResumable(goal, preferences.conversationalResume)
         ? 'Resume: say "go" (the agent calls goal_resume), /goal resume, or alt+g'
         : "Resume: /goal resume or alt+g"]
       : []),
   ].join("\n");
 }
 
+function formatPreferences(preferences: GoalPreferences): string {
+  return [
+    `Automatic continuation setting: ${preferences.autoContinue ? "on" : "off"}${WAKE_DISABLED ? " (disabled by environment)" : ""}`,
+    `Conversational resume setting: ${preferences.conversationalResume ? "on" : "off"}`,
+    `Pause on Esc setting: ${preferences.pauseOnEscape ? "on" : "off"}`,
+  ].join("\n");
+}
+
 function formatSnapshot(snapshot: ActivitySnapshot): string {
   const providers = snapshot.providers.map((provider) => {
     const active = provider.items.filter((item) => item.active).length;
@@ -268,6 +293,8 @@ export default function (pi: ExtensionAPI): void {
   let currentCtx: ExtensionContext | undefined;
   let executionGeneration = 0;
   let agentGeneration = -1;
+  let turnGeneration = 0;
+  let escapeAbortSuppression: { session: number; turn: number; execution: number } | undefined;
   let sessionGeneration = 0;
   let wakeGeneration = 0;
   let snapshotSequence = 0;
@@ -283,7 +310,11 @@ export default function (pi: ExtensionAPI): void {
   let idleContinuationTimer: ReturnType<typeof setTimeout> | undefined;
   let idleContinuationSignature = "";
   let refreshGoalWidget: ((force?: boolean) => void) | undefined;
+  let terminalInputUnsubscribe: (() => void) | undefined;
+  let terminalInputIsEditor: (() => boolean) | undefined;
+  let uiPromptDepth = 0;
   let lastAgentEvidence: ContinuationEvidence | null = null;
+  let preferences: GoalPreferences = { autoContinue: true, conversationalResume: true, pauseOnEscape: true };
   /** Background items active when each pending blocking question started, keyed by tool call id. */
   const pendingQuestions = new Map<string, Map<string, BackgroundWorkItem>>();
 
@@ -387,9 +418,16 @@ export default function (pi: ExtensionAPI): void {
       return;
     }
     setGoal(goalWithStatus(goal, "paused", undefined, "interrupt"), ctx, "runtime");
-    notifyGoal(ctx, 'Goal paused. Say "go" to resume it, or use /goal resume.');
+    notifyGoal(ctx, preferences.conversationalResume
+      ? 'Goal paused. Say "go" to resume it, or use /goal resume.'
+      : "Goal paused. Use /goal resume or alt+g to resume it.");
   };
 
+  const escapeAbortIsSuppressed = (): boolean =>
+    escapeAbortSuppression?.session === sessionGeneration &&
+    escapeAbortSuppression.turn === turnGeneration &&
+    escapeAbortSuppression.execution === executionGeneration;
+
   /** Why a paused goal cannot become active again, or null when it can. */
   const resumeBlocker = (goal: GoalSnapshot): string | null => {
     if (!goal.command && skillCommandName(goal.objective)) {
@@ -470,7 +508,7 @@ export default function (pi: ExtensionAPI): void {
     kind: "continuation" | "background-drained",
     snapshot?: ActivitySnapshot,
   ): void => {
-    if (WAKE_DISABLED || !isPokeable(goal) || continuationQueuedFor === goal.goalId) {
+    if (WAKE_DISABLED || !preferences.autoContinue || !isPokeable(goal) || continuationQueuedFor === goal.goalId) {
       return;
     }
     if (kind === "continuation" && currentContinuationState(ctx, goal.goalId)?.blocked) {
@@ -500,7 +538,7 @@ export default function (pi: ExtensionAPI): void {
     const execution = executionGeneration;
     const wake = wakeGeneration;
     const auditIsCurrent = (): boolean => {
-      if (execution !== executionGeneration || wake !== wakeGeneration) return false;
+      if (WAKE_DISABLED || !preferences.autoContinue || execution !== executionGeneration || wake !== wakeGeneration) return false;
       const current = currentGoalSnapshot(ctx);
       return isPokeable(current) && current.goalId === goalId &&
         continuationQueuedFor !== goalId && !isForegroundBusy(ctx);
@@ -603,7 +641,7 @@ export default function (pi: ExtensionAPI): void {
     const background = snapshot?.backgroundRunning
       ? `bg ${snapshot.activeBackgroundCount}${snapshot.unhealthyBackgroundCount ? `, ${snapshot.unhealthyBackgroundCount} unhealthy` : ""}`
       : undefined;
-    if (goal?.status === "paused") return background ? `${pausedGoalStatus(goal)} · ${background}` : pausedGoalStatus(goal);
+    if (goal?.status === "paused") return background ? `${pausedGoalStatus(goal, preferences.conversationalResume)} · ${background}` : pausedGoalStatus(goal, preferences.conversationalResume);
     if (background) return background;
     const continuation = goal ? currentContinuationState(ctx, goal.goalId) : null;
     if (continuation?.blocked) return "waiting: no progress";
@@ -633,7 +671,7 @@ export default function (pi: ExtensionAPI): void {
     if (typeof pi.getActiveTools !== "function" || typeof pi.setActiveTools !== "function") return;
     try {
       const active = pi.getActiveTools();
-      const wanted = agentResumable(goal);
+      const wanted = agentResumable(goal, preferences.conversationalResume);
       if (active.includes(GOAL_RESUME_TOOL) === wanted) return;
       pi.setActiveTools(wanted ? [...active, GOAL_RESUME_TOOL] : active.filter((name) => name !== GOAL_RESUME_TOOL));
     } catch {
@@ -697,6 +735,16 @@ export default function (pi: ExtensionAPI): void {
     ctx.ui.setWidget(
       EXTENSION_NAME,
       (tui, theme) => {
+        const inputIsEditor = (): boolean => {
+          const focus = tui as typeof tui & { getFocusedComponent?(): Partial<CustomEditor> | null };
+          if (typeof focus.getFocusedComponent !== "function" || tui.hasOverlay()) return false;
+          // Duck typing survives Pi's bundled/jiti module boundaries. Unknown
+          // custom editors and dialog components keep ownership of Escape.
+          const editor = focus.getFocusedComponent();
+          return typeof editor?.onEscape === "function" &&
+            typeof editor.isShowingAutocomplete === "function" && !editor.isShowingAutocomplete();
+        };
+        terminalInputIsEditor = inputIsEditor;
         const requestRender = (force = false): void => {
           try {
             tui.requestRender(force);
@@ -720,6 +768,7 @@ export default function (pi: ExtensionAPI): void {
         return {
           dispose() {
             scheduler.dispose();
+            if (terminalInputIsEditor === inputIsEditor) terminalInputIsEditor = undefined;
             if (refreshGoalWidget === refresh) {
               refreshGoalWidget = undefined;
             }
@@ -760,17 +809,59 @@ export default function (pi: ExtensionAPI): void {
   });
 
   pi.registerCommand("goal", {
-    description: "Create, inspect, pause, resume, clear, or complete the active goal",
+    description: "Create, inspect, pause, resume, clear, or complete the active goal; configure persistent goal settings",
     getArgumentCompletions: goalArgumentCompletions,
     handler: async (args, ctx) => {
       currentCtx = ctx;
       const trimmed = args.trim();
       const current = getGoal(ctx);
 
+      if (trimmed === "settings" || trimmed.startsWith("settings ")) {
+        const changePreference = async (key: keyof GoalPreferences, enabled: boolean): Promise<void> => {
+          const previous = preferences;
+          preferences = writeGoalPreference(key, enabled);
+          if (previous.autoContinue !== preferences.autoContinue) clearIdleContinuation();
+          syncResumeTool(getGoal(ctx));
+          applyStatus(ctx);
+          if (!previous.autoContinue && preferences.autoContinue) {
+            const snapshot = await publishSnapshot(ctx);
+            const goal = getGoal(ctx);
+            if (snapshot && isPokeable(goal) && !isForegroundBusy(ctx) && !snapshot.backgroundRunning) {
+              scheduleIdleContinuation(goal, ctx, "continuation", snapshot);
+            }
+          }
+        };
+        if (trimmed === "settings" && ctx.hasUI && ctx.mode !== "rpc" && typeof ctx.ui.custom === "function") {
+          await ctx.ui.custom<void>((tui, theme, _kb, done) => createGoalSettingsPage(theme, {
+            get: () => ({ ...preferences }),
+            change: changePreference,
+          }, () => tui.requestRender(), () => done()));
+          return;
+        }
+        const [, setting, mode, ...extra] = trimmed.split(/\s+/);
+        if (setting !== undefined && (!GOAL_SETTINGS.includes(setting as typeof GOAL_SETTINGS[number]) ||
+            (mode !== "on" && mode !== "off") || extra.length > 0)) {
+          notifyGoal(ctx, "Usage: /goal settings [auto-continue|conversational-resume|pause-on-escape on|off]", "warning");
+          return;
+        }
+        if (setting !== undefined) {
+          try {
+            const key = setting === "auto-continue" ? "autoContinue"
+              : setting === "conversational-resume" ? "conversationalResume" : "pauseOnEscape";
+            await changePreference(key, mode === "on");
+          } catch (error) {
+            notifyGoal(ctx, error instanceof Error ? error.message : String(error), "error");
+            return;
+          }
+        }
+        ctx.ui.notify(`${formatPreferences(preferences)}\nPreferences: ${goalPreferencesPath()}`, "info");
+        return;
+      }
+
       if (!trimmed) {
         const continuation = current ? currentContinuationState(ctx, current.goalId) : null;
         // Inspection is always explicit user intent; show the full summary even while busy.
-        ctx.ui.notify(formatGoal(current, continuation, observeGoalStall(current, continuation, { foregroundRunning })), "info");
+        ctx.ui.notify(formatGoal(current, continuation, observeGoalStall(current, continuation, { foregroundRunning }), preferences), "info");
         return;
       }
 
@@ -847,8 +938,8 @@ export default function (pi: ExtensionAPI): void {
         backgroundRunning: latestSnapshot?.backgroundRunning ?? false,
       });
       return {
-        content: [{ type: "text", text: formatGoal(goal, continuation, stall) }],
-        details: { goal, continuation, stall, timing: goal ? goalTiming(goal) : null, hasGoal: goal !== null },
+        content: [{ type: "text", text: formatGoal(goal, continuation, stall, preferences) }],
+        details: { goal, continuation, stall, preferences: { ...preferences }, timing: goal ? goalTiming(goal) : null, hasGoal: goal !== null },
       };
     },
   });
@@ -904,7 +995,13 @@ export default function (pi: ExtensionAPI): void {
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
       const reason = (params as { reason?: string }).reason;
       const current = getGoal(ctx);
-      if (!agentResumable(current)) {
+      if (!preferences.conversationalResume) {
+        return {
+          content: [{ type: "text", text: "Conversational goal resume is disabled. Only the user can resume with /goal resume or alt+g." }],
+          details: { ok: false, goal: current },
+        };
+      }
+      if (!agentResumable(current, preferences.conversationalResume)) {
         const text = current?.status === "paused"
           ? "This goal was paused with /goal pause or by the runtime. Only the user can resume it, with /goal resume."
           : "No goal is paused, so there is nothing to resume.";
@@ -986,8 +1083,13 @@ export default function (pi: ExtensionAPI): void {
   });
 
   pi.on("session_start", async (_event, ctx) => {
+    terminalInputUnsubscribe?.();
+    terminalInputUnsubscribe = undefined;
+    terminalInputIsEditor = undefined;
+    uiPromptDepth = 0;
     executionGeneration += 1;
     sessionGeneration += 1;
+    escapeAbortSuppression = undefined;
     clearIdleContinuation();
     continuationQueuedFor = null;
     backgroundDrainTracker = null;
@@ -996,6 +1098,11 @@ export default function (pi: ExtensionAPI): void {
     collectionPending = false;
     currentCtx = ctx;
     foregroundRunning = !ctx.isIdle();
+    try {
+      preferences = readGoalPreferences();
+    } catch (error) {
+      notifyGoal(ctx, error instanceof Error ? error.message : String(error), "error");
+    }
     const restoredGoal = getGoal(ctx);
     if (restoredGoal?.status === "active" && !restoredGoal.command && skillCommandName(restoredGoal.objective)) {
       setGoal(goalWithStatus(restoredGoal, "paused"), ctx, "runtime");
@@ -1004,6 +1111,23 @@ export default function (pi: ExtensionAPI): void {
     pi.events.emit(EVENT_READY, { version: EXTENSION_VERSION });
     syncResumeTool(getGoal(ctx));
     installGoalWidget(ctx);
+    if (ctx.mode === "tui" && ctx.hasUI && typeof ctx.ui.onTerminalInput === "function") {
+      const session = sessionGeneration;
+      terminalInputUnsubscribe = ctx.ui.onTerminalInput((data) => {
+        if (session === sessionGeneration && uiPromptDepth === 0 &&
+            !isKeyRelease(data) && matchesKey(data, "escape") && terminalInputIsEditor?.()) {
+          if (preferences.pauseOnEscape) {
+            pauseGoalOnInterrupt(ctx);
+          } else if (foregroundRunning) {
+            // The original key reaches Pi next and may abort this run. Preserve
+            // this keypress's choice through both abort notifications only.
+            escapeAbortSuppression = { session, turn: turnGeneration, execution: executionGeneration };
+          }
+        }
+        // Observe only: Pi must still interrupt streams or handle editor Escape.
+        return undefined;
+      });
+    }
     const snapshot = await publishSnapshot(ctx);
     if (!snapshot) return;
     syncPollingState();
@@ -1012,6 +1136,9 @@ export default function (pi: ExtensionAPI): void {
     }
   });
 
+  pi.on("ui_prompt_start", () => { uiPromptDepth += 1; });
+  pi.on("ui_prompt_end", () => { uiPromptDepth = Math.max(0, uiPromptDepth - 1); });
+
   pi.on("input", async (event, ctx) => {
     if (event.source === "extension") {
       return;
@@ -1046,7 +1173,8 @@ export default function (pi: ExtensionAPI): void {
     const owner = getWorkflow(ctx);
     const snapshot = await publishSnapshot(ctx);
     if (!snapshot) return;
-    const pausedInstruction = agentResumable(goal) ? pausedGoalPrompt(goal!) : "";
+    const pausedInstruction = goal?.status === "paused" && goal.pauseReason === "interrupt"
+      ? pausedGoalPrompt(goal, preferences.conversationalResume) : "";
     if (!isPokeable(goal) && !owner) {
       return pausedInstruction ? { systemPrompt: `${event.systemPrompt}\n\n${pausedInstruction}` } : undefined;
     }
@@ -1092,6 +1220,8 @@ export default function (pi: ExtensionAPI): void {
 
   pi.on("agent_start", async (_event, ctx) => {
     executionGeneration += 1;
+    turnGeneration += 1;
+    escapeAbortSuppression = undefined;
     agentGeneration = executionGeneration;
     currentCtx = ctx;
     foregroundRunning = true;
@@ -1100,10 +1230,16 @@ export default function (pi: ExtensionAPI): void {
     lastAgentEvidence = null;
     const turnSignal = ctx.signal;
     if (turnSignal) {
+      const session = sessionGeneration;
+      const turn = turnGeneration;
+      const onAbort = (): void => {
+        if (session !== sessionGeneration || turn !== turnGeneration) return;
+        if (!escapeAbortIsSuppressed()) pauseGoalOnInterrupt(ctx);
+      };
       if (turnSignal.aborted) {
-        pauseGoalOnInterrupt(ctx);
+        onAbort();
       } else {
-        turnSignal.addEventListener("abort", () => pauseGoalOnInterrupt(ctx), { once: true });
+        turnSignal.addEventListener("abort", onAbort, { once: true });
       }
     }
     await publishSnapshot(ctx);
@@ -1111,13 +1247,12 @@ export default function (pi: ExtensionAPI): void {
 
   pi.on("agent_end", async (event, ctx) => {
     lastAgentEvidence = agentGeneration === executionGeneration ? continuationEvidence(event.messages) : null;
-    // `escape` is a pi-reserved built-in shortcut (`app.interrupt`), so extensions
-    // cannot register it. Observe the interrupt instead: when a running turn is
-    // aborted (escape / ctrl+c while streaming), pause the active goal so it does
-    // not auto-continue after the user stopped the agent.
-    if (wasTurnAborted(event.messages)) {
+    // Only an observed editor Escape with pause disabled exempts this abort.
+    // Unknown interrupt sources retain the safety fallback on every host.
+    if (wasTurnAborted(event.messages) && !escapeAbortIsSuppressed()) {
       pauseGoalOnInterrupt(ctx);
     }
+    escapeAbortSuppression = undefined;
   });
 
   pi.on("tool_execution_start", async (event, ctx) => {
@@ -1150,6 +1285,7 @@ export default function (pi: ExtensionAPI): void {
 
   pi.on("agent_settled", async (_event, ctx) => {
     executionGeneration += 1;
+    escapeAbortSuppression = undefined;
     currentCtx = ctx;
     foregroundRunning = false;
     const snapshot = await publishSnapshot(ctx);
@@ -1196,6 +1332,11 @@ export default function (pi: ExtensionAPI): void {
   pi.on("session_shutdown", async (_event, ctx) => {
     executionGeneration += 1;
     sessionGeneration += 1;
+    escapeAbortSuppression = undefined;
+    terminalInputUnsubscribe?.();
+    terminalInputUnsubscribe = undefined;
+    terminalInputIsEditor = undefined;
+    uiPromptDepth = 0;
     stopPolling();
     foregroundRunning = false;
     pendingQuestions.clear();