pi-better-goal 0.7.0 → 0.8.1

package/README.md

@@ -13,8 +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.
-- `/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. Both controls default to `on`. Automatic continuation controls idle and background-drain wakes; conversational resume controls the agent's Escape-pause resume tool. Goal kickoff, `/goal resume`, and `alt+g` remain available with either control off. For scripts or non-interactive sessions, use `/goal settings auto-continue on|off` and `/goal settings conversational-resume on|off`; bare `/goal settings` prints the saved values outside the TUI.
-- `escape` pauses the active goal, and it stays paused while you talk to the agent. 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.
+- `/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/package.json

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

package/src/continuation.ts

@@ -53,6 +53,10 @@ function resultContent(content: unknown): unknown[] {
 export function continuationEvidence(messages: readonly unknown[]): ContinuationEvidence {
   const records: unknown[] = [];
   const toolNames: string[] = [];
+  const hasActions = messages.some((candidate) => isRecord(candidate) && (
+    candidate.role === "toolResult" || (candidate.role === "assistant" && Array.isArray(candidate.content) &&
+      candidate.content.some((block) => isRecord(block) && block.type === "toolCall"))
+  ));
 
   for (const candidate of messages) {
     if (!isRecord(candidate)) {
@@ -67,7 +71,7 @@ export function continuationEvidence(messages: readonly unknown[]): Continuation
         toolNames.push(block.name);
         return [{ name: block.name, arguments: block.arguments }];
       });
-      const text = message.content.flatMap((block) =>
+      const text = hasActions ? [] : message.content.flatMap((block) =>
         isRecord(block) && block.type === "text" ? [{ text: block.text }] : [],
       );
       if (actions.length > 0 || text.length > 0) {

package/src/goal-state.ts

@@ -66,7 +66,7 @@ function isGoalStatus(value: unknown): value is GoalStatus {
 }
 
 function isPauseReason(value: unknown): value is GoalPauseReason {
-  return value === "interrupt";
+  return value === "interrupt" || value === "permission-blocker";
 }
 
 function isGoalLike(value: unknown): value is GoalLike {

package/src/index.ts

@@ -1,5 +1,6 @@
-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";
@@ -27,6 +28,7 @@ import {
   type GoalEntrySource,
 } from "./goal-state.js";
 import { continuationEvidence, type ContinuationEvidence } from "./continuation.js";
+import { currentPermissionHold, logicalPermissionBlockerKey, MAX_PERMISSION_BLOCKERS, MAX_PERMISSION_RECORDS, permissionHoldRecord, permissionInstruction, permissionRecord, reportedPermissionBlockers, reportedPermissionGap, type PermissionHold } from "./permission-hold.js";
 import { observeGoalStall } from "./stall.js";
 import {
   flattenObjectiveForRail,
@@ -90,6 +92,7 @@ export function agentResumable(goal: GoalSnapshot | null, conversationalResume =
 
 /** Footer status for a paused goal, telling the user how to resume it. */
 export function pausedGoalStatus(goal: GoalSnapshot, conversationalResume = true): string {
+  if (goal.pauseReason === "permission-blocker") return "goal held: permission blocker · /goal resume (one retry)";
   return agentResumable(goal, conversationalResume) ? 'goal paused · say "go" or /goal resume' : "goal paused · /goal resume";
 }
 
@@ -108,10 +111,10 @@ 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 and conversational resume controls" },
+  { value: "settings", label: "settings", description: "Inspect or persist goal continuation, conversational resume, and Escape pause controls" },
 ];
 
-const GOAL_SETTINGS = ["auto-continue", "conversational-resume"] as const;
+const GOAL_SETTINGS = ["auto-continue", "conversational-resume", "pause-on-escape"] as const;
 
 export function goalArgumentCompletions(argumentPrefix: string): AutocompleteItem[] | null {
   const prefix = argumentPrefix.trimStart().toLowerCase();
@@ -227,7 +230,8 @@ function formatGoal(
   goal: GoalSnapshot | null,
   continuation: ReturnType<typeof currentContinuationState> = null,
   stall = observeGoalStall(goal, continuation),
-  preferences: GoalPreferences = { autoContinue: true, conversationalResume: true },
+  preferences: GoalPreferences = { autoContinue: true, conversationalResume: true, pauseOnEscape: true },
+  permissions?: PermissionHold | null,
 ): string {
   const settings = formatPreferences(preferences);
   if (!goal) {
@@ -241,6 +245,11 @@ function formatGoal(
   return [
     `Goal: ${goal.objective}`,
     `Status: ${goal.status}`,
+    ...(goal.pauseReason ? [`Pause reason: ${goal.pauseReason}`] : []),
+    ...(permissions?.blockers.length ? [
+      `Permission hold: ${permissions.blockers.length} scope(s); ${permissions.recordCount} history records; retry ${permissions.retryPending ? "released once" : "held"}`,
+      ...(permissions.saturated ? ["Permission observation incomplete: history/scope limit reached; release refused."] : []),
+    ] : []),
     `Token budget: ${budget}`,
     `Tokens used: ${goal.usage.tokensUsed}`,
     `Active time: ${timing.activeSeconds}s`,
@@ -260,6 +269,7 @@ 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");
 }
 
@@ -291,6 +301,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;
@@ -306,8 +318,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 };
+  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>>();
 
@@ -368,6 +383,13 @@ export default function (pi: ExtensionAPI): void {
   };
 
   const setGoal = (goal: GoalSnapshot, ctx: ExtensionContext, source: GoalEntrySource): void => {
+    const permissionHold = currentPermissionHold(ctx, goal.goalId);
+    if (goal.status === "paused" && permissionHold.blockers.length > 0) {
+      if (permissionHold.retryPending && permissionHold.recordCount < MAX_PERMISSION_RECORDS) {
+        pi.appendEntry(EXTENSION_NAME, permissionRecord(goal.goalId, "permission-retry-finished"));
+      }
+      goal = { ...goal, pauseReason: "permission-blocker" };
+    }
     executionGeneration += 1;
     lastAgentEvidence = null;
     const previous = getGoal(ctx);
@@ -411,11 +433,18 @@ export default function (pi: ExtensionAPI): void {
       return;
     }
     setGoal(goalWithStatus(goal, "paused", undefined, "interrupt"), ctx, "runtime");
-    notifyGoal(ctx, preferences.conversationalResume
+    notifyGoal(ctx, currentPermissionHold(ctx, goal.goalId).blockers.length > 0
+      ? "Goal remains permission-held. Use /goal resume or alt+g for one same-scope retry."
+      : 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)) {
@@ -445,6 +474,18 @@ export default function (pi: ExtensionAPI): void {
       return { ok: false, message: blocker };
     }
     const goal = held ? current : goalWithStatus(current, "active");
+    const permissions = currentPermissionHold(ctx, current.goalId);
+    if (current.pauseReason === "permission-blocker" && permissions.blockers.length === 0) {
+      return { ok: false, message: "Permission hold evidence is unavailable. The goal stays held; inspect the report before replacing this goal explicitly." };
+    }
+    if (permissions.blockers.length > 0) {
+      if (source === "tool" || permissions.saturated) {
+        return { ok: false, message: permissions.saturated
+          ? "Permission hold history is full. The goal stays held; inspect it and create a new goal explicitly if needed."
+          : "Only /goal resume or alt+g can release one permission retry." };
+      }
+      pi.appendEntry(EXTENSION_NAME, permissionRecord(current.goalId, "permission-release"));
+    }
     setGoal(goal, ctx, source);
     queueGoalContinuation(goal, ctx);
     return { ok: true, goal };
@@ -477,8 +518,11 @@ export default function (pi: ExtensionAPI): void {
     if (!boundCommandReady(goal, ctx)) return;
     clearIdleContinuation();
     continuationQueuedFor = goal.goalId;
-    resetContinuationState(goal);
-    sendGoalContinuation(goal, continuationPrompt(goal, getWorkflow(ctx)), "continuation");
+    const permissions = currentPermissionHold(ctx, goal.goalId);
+    if (permissions.blockers.length === 0) resetContinuationState(goal);
+    sendGoalContinuation(goal, permissions.blockers.length > 0
+      ? `${continuationPrompt(goal, getWorkflow(ctx))}\n\n${permissionInstruction(permissions)}`
+      : continuationPrompt(goal, getWorkflow(ctx)), "continuation");
   };
 
   function clearIdleContinuation(): void {
@@ -499,6 +543,7 @@ export default function (pi: ExtensionAPI): void {
     if (WAKE_DISABLED || !preferences.autoContinue || !isPokeable(goal) || continuationQueuedFor === goal.goalId) {
       return;
     }
+    if (currentPermissionHold(ctx, goal.goalId).blockers.length > 0) return;
     if (kind === "continuation" && currentContinuationState(ctx, goal.goalId)?.blocked) {
       return;
     }
@@ -529,6 +574,7 @@ export default function (pi: ExtensionAPI): void {
       if (WAKE_DISABLED || !preferences.autoContinue || execution !== executionGeneration || wake !== wakeGeneration) return false;
       const current = currentGoalSnapshot(ctx);
       return isPokeable(current) && current.goalId === goalId &&
+        currentPermissionHold(ctx, goalId).blockers.length === 0 &&
         continuationQueuedFor !== goalId && !isForegroundBusy(ctx);
     };
     const goal = currentGoalSnapshot(ctx);
@@ -591,7 +637,7 @@ export default function (pi: ExtensionAPI): void {
     const goal = currentGoalSnapshot(ctx);
     const wakePlan = planBackgroundDrainWake(backgroundDrainTracker, goal, snapshot);
     backgroundDrainTracker = wakePlan.nextTracker;
-    if (isPokeable(goal) && wakePlan.wakeSignature) {
+    if (isPokeable(goal) && wakePlan.wakeSignature && currentPermissionHold(ctx, goal.goalId).blockers.length === 0) {
       // Persist external progress now: a foreground/callback turn may cancel its delayed wake.
       clearIdleContinuation();
       resetContinuationState(goal);
@@ -723,6 +769,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);
@@ -746,6 +802,7 @@ export default function (pi: ExtensionAPI): void {
         return {
           dispose() {
             scheduler.dispose();
+            if (terminalInputIsEditor === inputIsEditor) terminalInputIsEditor = undefined;
             if (refreshGoalWidget === refresh) {
               refreshGoalWidget = undefined;
             }
@@ -818,12 +875,14 @@ export default function (pi: ExtensionAPI): void {
         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 on|off]", "warning");
+          notifyGoal(ctx, "Usage: /goal settings [auto-continue|conversational-resume|pause-on-escape on|off]", "warning");
           return;
         }
         if (setting !== undefined) {
           try {
-            await changePreference(setting === "auto-continue" ? "autoContinue" : "conversationalResume", mode === "on");
+            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;
@@ -836,7 +895,8 @@ export default function (pi: ExtensionAPI): void {
       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 }), preferences), "info");
+        ctx.ui.notify(formatGoal(current, continuation, observeGoalStall(current, continuation, { foregroundRunning }), preferences,
+          current ? currentPermissionHold(ctx, current.goalId) : null), "info");
         return;
       }
 
@@ -913,8 +973,8 @@ export default function (pi: ExtensionAPI): void {
         backgroundRunning: latestSnapshot?.backgroundRunning ?? false,
       });
       return {
-        content: [{ type: "text", text: formatGoal(goal, continuation, stall, preferences) }],
-        details: { goal, continuation, stall, preferences: { ...preferences }, timing: goal ? goalTiming(goal) : null, hasGoal: goal !== null },
+        content: [{ type: "text", text: formatGoal(goal, continuation, stall, preferences, goal ? currentPermissionHold(ctx, goal.goalId) : null) }],
+        details: { goal, continuation, permissionHold: goal ? currentPermissionHold(ctx, goal.goalId) : null, stall, preferences: { ...preferences }, timing: goal ? goalTiming(goal) : null, hasGoal: goal !== null },
       };
     },
   });
@@ -1058,8 +1118,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;
@@ -1074,6 +1139,10 @@ export default function (pi: ExtensionAPI): void {
       notifyGoal(ctx, error instanceof Error ? error.message : String(error), "error");
     }
     const restoredGoal = getGoal(ctx);
+    if (restoredGoal?.status === "active" && currentPermissionHold(ctx, restoredGoal.goalId).blockers.length > 0) {
+      // A persisted release is not a replayable dispatch ticket after reload.
+      setGoal(goalWithStatus(restoredGoal, "paused", undefined, "permission-blocker"), ctx, "runtime");
+    }
     if (restoredGoal?.status === "active" && !restoredGoal.command && skillCommandName(restoredGoal.objective)) {
       setGoal(goalWithStatus(restoredGoal, "paused"), ctx, "runtime");
       notifyGoal(ctx, "Goal paused: invoke its skill directly before resuming.", "error");
@@ -1081,6 +1150,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();
@@ -1089,6 +1175,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;
@@ -1109,7 +1198,7 @@ export default function (pi: ExtensionAPI): void {
     // A paused goal stays paused while the user talks: the message is ordinary
     // conversation. Only /goal resume, the hotkey, or goal_resume resume it.
     const goal = getGoal(ctx);
-    if (goal?.status === "active") {
+    if (goal?.status === "active" && currentPermissionHold(ctx, goal.goalId).blockers.length === 0) {
       executionGeneration += 1;
       clearIdleContinuation();
       lastAgentEvidence = null;
@@ -1123,8 +1212,17 @@ export default function (pi: ExtensionAPI): void {
     const owner = getWorkflow(ctx);
     const snapshot = await publishSnapshot(ctx);
     if (!snapshot) return;
-    const pausedInstruction = goal?.status === "paused" && goal.pauseReason === "interrupt"
-      ? pausedGoalPrompt(goal, preferences.conversationalResume) : "";
+    const permissions = goal ? currentPermissionHold(ctx, goal.goalId) : null;
+    const permissionPrompt = permissions && goal?.status !== "complete" &&
+      (permissions.blockers.length > 0 || goal?.pauseReason === "permission-blocker")
+      ? permissionInstruction({ ...permissions, retryPending: permissions.retryPending && goal?.status === "active" }) +
+        (permissions.blockers.length === 0 ? "\nBlocker evidence is unavailable. Stay held; do not invent a retry scope." : "") : "";
+    // A held goal overrides workflow ownership without invoking or invalidating that workflow.
+    if (permissionPrompt && goal?.status === "paused") {
+      return { systemPrompt: `${event.systemPrompt}\n\n${permissionPrompt}` };
+    }
+    const pausedInstruction = permissionPrompt || (goal?.status === "paused" && goal.pauseReason === "interrupt"
+      ? pausedGoalPrompt(goal, preferences.conversationalResume) : "");
     if (!isPokeable(goal) && !owner) {
       return pausedInstruction ? { systemPrompt: `${event.systemPrompt}\n\n${pausedInstruction}` } : undefined;
     }
@@ -1149,7 +1247,9 @@ export default function (pi: ExtensionAPI): void {
       return {
         systemPrompt: `${event.systemPrompt}\n\n` +
           (pausedInstruction
-            ? `${pausedInstruction}\nWhile the goal is paused, this overrides the workflow instructions below: do not advance the workflow until the goal is resumed.\n\n`
+            ? `${pausedInstruction}\n` + (permissionPrompt
+              ? "These permission constraints override the workflow instructions below.\n\n"
+              : "While the goal is paused, this overrides the workflow instructions below: do not advance the workflow until the goal is resumed.\n\n")
             : "") +
           `Active workflow: ${owner.name} (${owner.path}). Its task plan owns planning and the parent is a coordinator, not a product-code implementer. Follow the workflow instructions below, including on resumed turns:\n\n${instructions}` +
           (isPokeable(goal) ? `\n\nActive objective: ${goal.objective}. Complete it only after the workflow completion audit.` : "") +
@@ -1164,12 +1264,15 @@ export default function (pi: ExtensionAPI): void {
     return {
       systemPrompt:
         `${event.systemPrompt}\n\n` +
-        `Pi Better Goal active objective: ${goal.objective}. Keep working through clear low-risk next steps, and mark complete only after an evidence-backed completion audit.${backgroundInstruction}${questionInstruction}`,
+        `Pi Better Goal active objective: ${goal.objective}. Keep working through clear low-risk next steps, and mark complete only after an evidence-backed completion audit.${backgroundInstruction}${questionInstruction}` +
+        (permissionPrompt ? `\n\n${permissionPrompt}` : ""),
     };
   });
 
   pi.on("agent_start", async (_event, ctx) => {
     executionGeneration += 1;
+    turnGeneration += 1;
+    escapeAbortSuppression = undefined;
     agentGeneration = executionGeneration;
     currentCtx = ctx;
     foregroundRunning = true;
@@ -1178,10 +1281,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);
@@ -1189,13 +1298,46 @@ 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_result", (event, ctx) => {
+    const goal = getGoal(ctx);
+    if (!goal || (goal.status !== "active" && goal.status !== "paused")) return;
+    const reports = reportedPermissionBlockers(pi, event.toolName, event.details);
+    const incomplete = reportedPermissionGap(pi, event.toolName, event.details);
+    if (reports.length === 0 && !incomplete) return;
+    let hold = currentPermissionHold(ctx, goal.goalId);
+    let changed = false;
+    for (const blocker of reports) {
+      const previous = hold.blockers.find((item) => logicalPermissionBlockerKey(item) === logicalPermissionBlockerKey(blocker));
+      if (!hold.retryPending && previous && JSON.stringify(previous) === JSON.stringify(blocker)) continue;
+      if (hold.saturated || (!previous && hold.blockers.length >= MAX_PERMISSION_BLOCKERS)) {
+        if (!hold.saturated && hold.recordCount < MAX_PERMISSION_RECORDS) {
+          pi.appendEntry(EXTENSION_NAME, permissionRecord(goal.goalId, "permission-gap"));
+        }
+        break;
+      }
+      pi.appendEntry(EXTENSION_NAME, permissionHoldRecord(goal.goalId, blocker));
+      changed = true;
+      hold = currentPermissionHold(ctx, goal.goalId);
+    }
+    if (incomplete && !hold.saturated && hold.recordCount < MAX_PERMISSION_RECORDS) {
+      pi.appendEntry(EXTENSION_NAME, permissionRecord(goal.goalId, "permission-gap"));
+      changed = true;
+      hold = currentPermissionHold(ctx, goal.goalId);
+    }
+    if (hold.retryPending && hold.recordCount < MAX_PERMISSION_RECORDS) {
+      pi.appendEntry(EXTENSION_NAME, permissionRecord(goal.goalId, "permission-retry-finished"));
+    }
+    if (!changed && goal.status === "paused" && goal.pauseReason === "permission-blocker") return;
+    setGoal(goalWithStatus(goal, "paused", undefined, "permission-blocker"), ctx, "runtime");
+    notifyGoal(ctx, "Goal held for a permission blocker. /goal resume or alt+g releases one same-scope retry.", "warning");
   });
 
   pi.on("tool_execution_start", async (event, ctx) => {
@@ -1228,11 +1370,22 @@ 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);
     if (!snapshot) return;
     const goal = getGoal(ctx);
+    if (isPokeable(goal)) {
+      const permissions = currentPermissionHold(ctx, goal.goalId);
+      if (permissions.blockers.length > 0) {
+        if (permissions.retryPending && permissions.recordCount < MAX_PERMISSION_RECORDS) {
+          pi.appendEntry(EXTENSION_NAME, permissionRecord(goal.goalId, "permission-retry-finished"));
+        }
+        setGoal(goalWithStatus(goal, "paused", undefined, "permission-blocker"), ctx, "runtime");
+        return;
+      }
+    }
     if (!isPokeable(goal) || snapshot.backgroundRunning) {
       return;
     }
@@ -1274,6 +1427,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();

package/src/permission-hold.ts

@@ -0,0 +1,150 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { readFileSync, realpathSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { isPermissionBlocker, permissionBlockerKey, type PermissionBlocker } from "./shared-permission-blocker.js";
+import { EXTENSION_NAME } from "./types.js";
+
+export const MAX_PERMISSION_BLOCKERS = 32;
+export const MAX_PERMISSION_RECORDS = 128;
+
+export type PermissionRecord =
+  | { version: 1; kind: "permission-hold"; goalId: string; blocker: PermissionBlocker; at: number }
+  | { version: 1; kind: "permission-release" | "permission-retry-finished" | "permission-gap"; goalId: string; at: number };
+
+export interface PermissionHold {
+  blockers: PermissionBlocker[];
+  retryPending: boolean;
+  recordCount: number;
+  saturated: boolean;
+}
+
+/** Worker/incident references describe evidence, not authority for a different retry scope. */
+export function logicalPermissionBlockerKey(blocker: PermissionBlocker): string {
+  return permissionBlockerKey({
+    version: 1, kind: "permission-blocker", context: blocker.context, resource: blocker.resource,
+    basis: blocker.basis, operation: blocker.operation, remoteOutcome: "unknown",
+  });
+}
+
+/** Replay only compact goal-owned authority records, independently of progress resets. */
+export function currentPermissionHold(ctx: ExtensionContext, goalId: string): PermissionHold {
+  const blockers = new Map<string, PermissionBlocker>();
+  let retryPending = false;
+  let recordCount = 0;
+  let saturated = false;
+  for (const entry of ctx.sessionManager.getBranch()) {
+    if (entry.type !== "custom" || entry.customType !== EXTENSION_NAME || !entry.data || typeof entry.data !== "object") continue;
+    const data = entry.data as Partial<PermissionRecord>;
+    // Only attributable authority records can make this goal's retry scope incomplete.
+    if (data.goalId !== goalId || (data.kind !== "permission-hold" && data.kind !== "permission-release" &&
+        data.kind !== "permission-retry-finished" && data.kind !== "permission-gap")) continue;
+    if (data.version !== 1 || typeof data.at !== "number" || !Number.isFinite(data.at) ||
+        (data.kind === "permission-hold" && !isPermissionBlocker(data.blocker))) {
+      saturated = true;
+      retryPending = false;
+      recordCount += 1;
+      continue;
+    }
+    if (data.kind === "permission-hold" && isPermissionBlocker(data.blocker)) {
+      const key = logicalPermissionBlockerKey(data.blocker);
+      if (blockers.has(key) || blockers.size < MAX_PERMISSION_BLOCKERS) blockers.set(key, compactBlocker(data.blocker));
+      else saturated = true;
+      retryPending = false;
+    } else if (data.kind === "permission-release" && blockers.size > 0) {
+      retryPending = !saturated;
+    } else if (data.kind === "permission-retry-finished") {
+      retryPending = false;
+    } else if (data.kind === "permission-gap") {
+      saturated = true;
+      retryPending = false;
+    } else continue;
+    recordCount += 1;
+    // Reserve room to record an incomplete scope and consume an outstanding release.
+    if (recordCount >= MAX_PERMISSION_RECORDS - 2) saturated = true;
+  }
+  return { blockers: [...blockers.values()], retryPending, recordCount, saturated };
+}
+
+function compactBlocker(blocker: PermissionBlocker): PermissionBlocker {
+  return {
+    version: 1, kind: "permission-blocker", context: blocker.context,
+    resource: blocker.resource, basis: blocker.basis, operation: blocker.operation, remoteOutcome: blocker.remoteOutcome,
+    ...(blocker.incidentId ? { incidentId: blocker.incidentId } : {}),
+    ...(blocker.runId ? { runId: blocker.runId } : {}),
+    ...(blocker.policySnapshotId ? { policySnapshotId: blocker.policySnapshotId } : {}),
+  };
+}
+
+function packageName(root: string): unknown {
+  try {
+    return (JSON.parse(readFileSync(join(root, "package.json"), "utf8")) as { name?: unknown }).name;
+  } catch {
+    return undefined;
+  }
+}
+
+function isSubagentEntry(path: string): boolean {
+  const root = dirname(path);
+  const name = packageName(root);
+  return (name === "pi-better-subagents" || name === "@vanillagreen/pi-better-subagents") &&
+    path === realpathSync(join(root, "index.ts"));
+}
+
+/** Trust the registered parent producer's canonical entry, never a tool name alone. */
+export function isParentBlockerProducer(pi: ExtensionAPI, toolName: string): boolean {
+  if (toolName !== "subagent_result" && toolName !== "subagent_output") return false;
+  try {
+    const source = pi.getAllTools().find((tool) => tool.name === toolName)?.sourceInfo.path;
+    if (!source) return false;
+    const path = realpathSync(source);
+    if (isSubagentEntry(path)) return true;
+    const root = dirname(dirname(dirname(path)));
+    if (packageName(root) !== "pi-better-harness" || path !== join(root, "extensions/subagents/index.ts")) return false;
+    const manifest = JSON.parse(readFileSync(join(root, "package.json"), "utf8")) as {
+      pi?: { extensions?: unknown }; dependencies?: Record<string, unknown>; bundledDependencies?: unknown;
+    };
+    if (!Array.isArray(manifest.pi?.extensions) || !manifest.pi.extensions.includes("extensions/subagents/index.ts") ||
+        typeof manifest.dependencies?.["pi-better-subagents"] !== "string" ||
+        !Array.isArray(manifest.bundledDependencies) || !manifest.bundledDependencies.includes("pi-better-subagents")) return false;
+    // The SDK attributes tools to the loaded wrapper. Admit only the shipped literal shim, not arbitrary imports.
+    if (readFileSync(path, "utf8").trim() !== 'export { default } from "../../node_modules/pi-better-subagents/index.ts";') return false;
+    return isSubagentEntry(realpathSync(join(root, "node_modules/pi-better-subagents/index.ts")));
+  } catch {
+    return false;
+  }
+}
+
+/** The parent emits actionable open reports; child errors/prose are not this contract. */
+export function reportedPermissionBlockers(pi: ExtensionAPI, toolName: string, details: unknown): PermissionBlocker[] {
+  if (!isParentBlockerProducer(pi, toolName) || !details || typeof details !== "object") return [];
+  const reports = (details as { permissionBlockers?: unknown }).permissionBlockers;
+  if (!Array.isArray(reports) || reports.length > MAX_PERMISSION_BLOCKERS) return [];
+  // Reject a malformed batch whole rather than accidentally widening a partial retry scope.
+  if (!reports.every((report) => isPermissionBlocker(report) && report.context === "worker")) return [];
+  return reports.map(compactBlocker);
+}
+
+export function reportedPermissionGap(pi: ExtensionAPI, toolName: string, details: unknown): boolean {
+  if (!isParentBlockerProducer(pi, toolName) || !details || typeof details !== "object") return false;
+  const omitted = (details as { permissionBlockersOmitted?: unknown }).permissionBlockersOmitted;
+  return typeof omitted === "number" && Number.isSafeInteger(omitted) && omitted > 0;
+}
+
+export function permissionRecord(goalId: string, kind: "permission-release" | "permission-retry-finished" | "permission-gap"): PermissionRecord {
+  return { version: 1, kind, goalId, at: Math.floor(Date.now() / 1000) };
+}
+
+export function permissionHoldRecord(goalId: string, blocker: PermissionBlocker): PermissionRecord {
+  return { version: 1, kind: "permission-hold", goalId, blocker: compactBlocker(blocker), at: Math.floor(Date.now() / 1000) };
+}
+
+export function permissionInstruction(hold: PermissionHold): string {
+  return [
+    hold.retryPending
+      ? "The human explicitly released ONE bounded retry of the held operation and scope below. This is not a permission grant or evidence of success."
+      : "The goal is paused for a permission blocker. Answer ordinary questions, but do not advance goal or workflow work. Only /goal resume or alt+g releases one bounded retry; goal_resume cannot release it.",
+    ...hold.blockers.map((blocker) => `- ${blocker.context}: ${blocker.resource}; operation=${blocker.operation}; basis=${blocker.basis}; remoteOutcome=${blocker.remoteOutcome}` +
+      (blocker.runId ? `; runId=${blocker.runId}` : "") + (blocker.policySnapshotId ? `; policySnapshotId=${blocker.policySnapshotId}` : "")),
+    "Keep the same operation and scope. Do not switch to foreground execution, copy credentials, change authentication, or broaden permissions. Changed worker settings require a fresh worker; retain the logical operation identity. Runtime-observed refusals and agent-reported blockers are distinct. Unknown remote outcome is never evidence of success.",
+  ].join("\n");
+}

package/src/preferences.ts

@@ -5,6 +5,7 @@ import { dirname, join } from "node:path";
 export interface GoalPreferences {
   autoContinue: boolean;
   conversationalResume: boolean;
+  pauseOnEscape: boolean;
 }
 
 export interface GoalPreferenceSeams {
@@ -22,7 +23,7 @@ export function readGoalPreferences(seams: GoalPreferenceSeams = {}): GoalPrefer
     raw = readFileSync(path, "utf8");
   } catch (error) {
     if ((error as NodeJS.ErrnoException).code === "ENOENT") {
-      return { autoContinue: true, conversationalResume: true };
+      return { autoContinue: true, conversationalResume: true, pauseOnEscape: true };
     }
     throw new Error(`Goal preferences at ${path} could not be read: ${messageOf(error)}`);
   }
@@ -35,16 +36,18 @@ export function readGoalPreferences(seams: GoalPreferenceSeams = {}): GoalPrefer
   const value = parsed as Partial<GoalPreferences> & { version?: unknown } | null;
   if (value?.version !== 1 ||
       (value.autoContinue !== undefined && typeof value.autoContinue !== "boolean") ||
-      (value.conversationalResume !== undefined && typeof value.conversationalResume !== "boolean")) {
-    throw new Error(`Goal preferences at ${path} must contain version 1 and boolean autoContinue/conversationalResume settings.`);
+      (value.conversationalResume !== undefined && typeof value.conversationalResume !== "boolean") ||
+      (value.pauseOnEscape !== undefined && typeof value.pauseOnEscape !== "boolean")) {
+    throw new Error(`Goal preferences at ${path} must contain version 1 and boolean autoContinue/conversationalResume/pauseOnEscape settings.`);
   }
   return {
     autoContinue: value.autoContinue ?? true,
     conversationalResume: value.conversationalResume ?? true,
+    pauseOnEscape: value.pauseOnEscape ?? true,
   };
 }
 
-/** Persist one control without replacing the other session's saved choice. */
+/** Persist one control without replacing another session's saved choices. */
 export function writeGoalPreference(
   key: keyof GoalPreferences,
   enabled: boolean,

package/src/settings-page.ts

@@ -5,6 +5,7 @@ import type { GoalPreferences } from "./preferences.js";
 const rows: { key: keyof GoalPreferences; label: string }[] = [
   { key: "autoContinue", label: "Automatic continuation" },
   { key: "conversationalResume", label: "Conversational resume" },
+  { key: "pauseOnEscape", label: "Pause on Esc" },
 ];
 
 export function createGoalSettingsPage(

package/src/shared-permission-blocker.ts

@@ -0,0 +1,48 @@
+// Generated from packages/failure-observations/permission-blocker.ts. Do not edit directly.
+/** Privacy-safe wire contract. Context and identity must be assigned by a trusted adapter. */
+export const PERMISSION_RESOURCES = Object.freeze([
+  "credential-files", "process-inspection", "project-files", "outside-project-files",
+  "runtime-control-files", "command-execution", "network-access", "unknown",
+] as const);
+export type PermissionResource = typeof PERMISSION_RESOURCES[number];
+export interface PermissionBlocker {
+  version: 1;
+  kind: "permission-blocker";
+  context: "worker" | "foreground";
+  resource: PermissionResource;
+  basis: "policy-refusal" | "os-permission-error" | "agent-reported";
+  /** A stable hash or bounded logical identifier, never a command or path. */
+  operation: string;
+  remoteOutcome: "unknown" | "not-started";
+  incidentId?: string;
+  runId?: string;
+  policySnapshotId?: string;
+}
+const FIELDS = new Set(["version", "kind", "context", "resource", "basis", "operation", "remoteOutcome", "incidentId", "runId", "policySnapshotId"]);
+const LOGICAL_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,199}$/;
+// Responses SDK references join call_id and item_id with "|"; these are opaque evidence ids,
+// not caller-chosen logical operations. Keep the same bound and exclude paths and prose.
+const INCIDENT_REFERENCE = /^[A-Za-z0-9][A-Za-z0-9._:|\-]{0,199}$/;
+export function isPermissionResource(value: unknown): value is PermissionResource {
+  return typeof value === "string" && (PERMISSION_RESOURCES as readonly string[]).includes(value);
+}
+/** Pure and strict: no coercion, unknown fields, paths, argv, or free-form prose. */
+export function isPermissionBlocker(value: unknown): value is PermissionBlocker {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) return false;
+  if (Reflect.ownKeys(value).some(key => typeof key !== "string" || !FIELDS.has(key))) return false;
+  const v = value as Record<string, unknown>;
+  if (v.version !== 1 || v.kind !== "permission-blocker" || !["worker", "foreground"].includes(v.context as string) ||
+    !isPermissionResource(v.resource) || !["policy-refusal", "os-permission-error", "agent-reported"].includes(v.basis as string) ||
+    !["unknown", "not-started"].includes(v.remoteOutcome as string) ||
+    typeof v.operation !== "string" || v.operation.length > 64 || !LOGICAL_ID.test(v.operation)) return false;
+  if (Object.hasOwn(v, "incidentId") && (typeof v.incidentId !== "string" || !INCIDENT_REFERENCE.test(v.incidentId))) return false;
+  return ["runId", "policySnapshotId"].every(key => !Object.hasOwn(v, key) ||
+    (typeof v[key] === "string" && LOGICAL_ID.test(v[key] as string)));
+}
+/** Order-independent identity without I/O or a platform-specific crypto dependency. */
+export function permissionBlockerKey(blocker: PermissionBlocker): string {
+  return JSON.stringify([blocker.version, blocker.kind, blocker.context, blocker.resource, blocker.basis,
+    blocker.operation, blocker.remoteOutcome, blocker.incidentId ?? null, blocker.runId ?? null, blocker.policySnapshotId ?? null]);
+}

package/src/types.ts

@@ -71,9 +71,11 @@ export type GoalStatus = "active" | "paused" | "budgetLimited" | "complete";
  * resume a goal on their own. An `interrupt` pause may be resumed by the agent
  * with `goal_resume` when the user clearly says to proceed. A paused goal
  * without a reason (`/goal pause`, an unavailable command or workflow) resumes
- * only through `/goal resume` or the resume hotkey.
+ * only through `/goal resume` or the resume hotkey. `permission-blocker` also
+ * requires those human controls, and releases just one same-scope retry while
+ * keeping its separate blocker/release history.
  */
-export type GoalPauseReason = "interrupt";
+export type GoalPauseReason = "interrupt" | "permission-blocker";
 
 export interface GoalUsage {
   tokensUsed: number;