pi-better-harness 0.19.0 → 0.20.0

package/README.md

@@ -65,12 +65,13 @@ need interactive confirmation. Full policy: [pi-better-sandbox](https://github.c
 ## Minimal Tool Output
 
 The bundled harness also provides `/tool-output minimal`, `/tool-output normal`,
-and `/tool-output` (toggle). Minimal mode hides tool blocks entirely, including
-running calls, headers, results, images, summary rows, and tool spacers. Built-in,
+and `/tool-output` (toggle). Minimal mode folds each tool call into a single-line
+header, including running calls. Long headers are truncated to the terminal
+width; result bodies, images, boxes, and tool spacers are hidden. Built-in,
 extension, and MCP calls are included. Execution, sandboxing, and agent-facing
 payloads are unchanged. Ctrl+O reveals the original tool blocks; Ctrl+O again
-hides them. `/tool-output normal` restores ordinary rendering. Error results
-are also hidden in minimal mode and remain available when revealed.
+folds them. `/tool-output normal` restores ordinary rendering. Error result
+bodies are also hidden in minimal mode and remain available when expanded.
 
 Normal mode is the default. The preference is saved in the current session,
 including resume/reload. This is a version-sensitive internal TUI adapter,

package/extensions/minimal-output/hook.ts

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

package/extensions/minimal-output/index.ts

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

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

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-background-tasks",
-  "version": "0.6.5",
+  "version": "0.6.6",
   "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-failure-observations.ts

@@ -2,6 +2,7 @@
 import { appendFileSync, closeSync, existsSync, openSync, readFileSync, mkdirSync, statSync } from "node:fs";
 import { dirname } from "node:path";
 import { createHash } from "node:crypto";
+import { isPermissionBlocker, permissionBlockerKey, type PermissionBlocker } from "./shared-permission-blocker.ts";
 
 /**
  * Explicit, append-only incident dispositions (#315).
@@ -30,6 +31,7 @@ export interface FailureEvent {
   disposition?: IncidentDisposition;
   /** Disposition events only: why the incidents are classified this way. */
   reason?: string;
+  permissionBlockers?: PermissionBlocker[];
 }
 export interface DispositionRecord {
   eventId: string;
@@ -38,6 +40,7 @@ export interface DispositionRecord {
   reason: string;
   evidence?: string;
   at: number;
+  permissionBlockers?: PermissionBlocker[];
 }
 export interface FailureObservation {
   id: string;
@@ -56,6 +59,8 @@ export interface FailureObservation {
   resolvedAt?: number;
   /** Latest explicit disposition applied to this incident. */
   disposition?: DispositionRecord;
+  /** Retained even after recovery; active surfaces filter by current actionability. */
+  permissionBlockers?: PermissionBlocker[];
 }
 export interface FailureState {
   version: 1;
@@ -247,12 +252,26 @@ export function validateDisposition(state: FailureState, event: FailureEvent): s
     if (current.status !== "unresolved") return `Incident ${id} is already disposed (${failureLabel(current).toLowerCase()})`;
     if (event.disposition === "open" && current.disposition?.disposition === "open") return `Incident ${id} is already open`;
   }
+  if (event.permissionBlockers !== undefined) {
+    if (event.disposition !== "open" || !Array.isArray(event.permissionBlockers) || !event.permissionBlockers.length ||
+      event.permissionBlockers.length > 20 || !event.permissionBlockers.every(isPermissionBlocker)) return "Invalid permission blocker metadata";
+    const bound = new Set<string>();
+    for (const blocker of event.permissionBlockers) {
+      const current = blocker.incidentId ? findIncident(state, blocker.incidentId) : undefined;
+      if (!current || !ids.includes(current.id) || current.category !== "tool" || current.operation !== blocker.operation ||
+        blocker.context !== "worker" || blocker.basis !== "agent-reported" || blocker.remoteOutcome !== "unknown" ||
+        blocker.policySnapshotId !== undefined || bound.has(current.id)) return "Permission blocker must name an unresolved failed worker attempt";
+      bound.add(current.id);
+    }
+    if (bound.size !== ids.length) return "Permission blocker metadata must cover every target";
+  }
   return undefined;
 }
 
 /** Pure transition. Lifecycle is deliberately not an input or an output. */
 export function reduceFailure(state: FailureState, event: FailureEvent, observedAt: number): FailureState {
   if (state.seen.includes(event.id)) return state;
+  if (event.permissionBlockers !== undefined && event.kind !== "disposition") return state;
   // Invalid dispositions fail closed: nothing changes and the id is not consumed.
   if (event.kind === "disposition" && validateDisposition(state, event)) return state;
   const next: FailureState = { ...state, seen: [...state.seen, event.id],
@@ -265,11 +284,13 @@ export function reduceFailure(state: FailureState, event: FailureEvent, observed
     const at = event.at ?? observedAt;
     const record: DispositionRecord = { eventId: event.id, disposition: event.disposition!, incidents: [...event.incidents!],
       reason: text(event.reason, ""), ...(event.evidence ? { evidence: text(event.evidence, "") } : {}), at };
+    if (event.permissionBlockers) record.permissionBlockers = event.permissionBlockers.map(x => ({ ...x }));
     for (const id of record.incidents) {
       const [key, current] = Object.entries(next.observations).find(([, item]) => item.id === id)!;
       const status = record.disposition === "recovered" ? "resolved" : record.disposition === "superseded" ? "superseded"
         : record.disposition === "expected" ? "expected" : current.status;
       next.observations[key] = { ...current, status, disposition: record,
+        ...(record.permissionBlockers ? { permissionBlockers: record.permissionBlockers.filter(x => x.incidentId === id) } : {}),
         ...(status === "resolved" || status === "superseded" ? { resolvedAt: at } : {}) };
       if (status === "resolved" || status === "superseded") next.resolved = { ...next.resolved, [id]: at };
     }
@@ -298,6 +319,7 @@ export function reduceFailure(state: FailureState, event: FailureEvent, observed
     lastObservedAt: observedAt, lastSequence: next.seen.length, at: event.at,
     count: active ? previous.count + 1 : 1,
     ...(active && previous.disposition ? { disposition: previous.disposition } : {}),
+    ...(active && previous.permissionBlockers ? { permissionBlockers: previous.permissionBlockers } : {}),
   };
   return next;
 }
@@ -315,6 +337,16 @@ export function activeFailures(state: FailureState): FailureObservation[] {
 export function actionableFailures(state: FailureState): FailureObservation[] {
   return activeFailures(state).filter(needsAction);
 }
+/** Only currently actionable reports, not closed history or arbitrary tool-result claims. */
+export function actionablePermissionBlockers(state: FailureState): PermissionBlocker[] {
+  const unique = new Map<string, PermissionBlocker>();
+  for (const incident of actionableFailures(state)) {
+    for (const blocker of incident.permissionBlockers ?? []) {
+      if (isPermissionBlocker(blocker)) unique.set(permissionBlockerKey(blocker), { ...blocker });
+    }
+  }
+  return [...unique.values()];
+}
 function closedOrder(a: FailureObservation, b: FailureObservation): number {
   return (b.lastSequence ?? 0) - (a.lastSequence ?? 0) || b.lastObservedAt - a.lastObservedAt;
 }
@@ -449,12 +481,20 @@ export function shortEvidence(evidence: string): string {
 function failureRow(x: FailureObservation, detail: IncidentDetail = "compact"): string {
   const time = x.at === undefined ? `observed ${new Date(x.firstObservedAt).toISOString()}` : new Date(x.at).toISOString();
   const compact = detail !== "full";
+  const permission = Boolean(x.permissionBlockers?.length);
+  let annotation = "";
+  if (x.permissionBlockers?.length) {
+    const resources = x.permissionBlockers.map(b => b.resource).join(", ");
+    annotation = ` · Worker permission blocker: ${resources} (agent-reported; remote outcome unknown; not a foreground denial). No remote authorization or successful validation inferred.`;
+    if (needsAction(x)) annotation += " Changed worker settings require a fresh launch.";
+  }
   // Full rows (raw evidence) show the journal summary verbatim; compact rows unwrap and cap it.
-  const summary = compact ? capUtf8(dropLoneSurrogates(unwrapToolResultText(x.summary)).replace(/\s+/g, " ").trim(), COMPACT_EXCERPT_BYTES) : x.summary;
+  const summary = compact && permission ? "Permission access failure" : compact ? capUtf8(dropLoneSurrogates(unwrapToolResultText(x.summary)).replace(/\s+/g, " ").trim(), COMPACT_EXCERPT_BYTES) : x.summary;
   const reason = x.disposition ? text(x.disposition.reason, "") : "";
-  const disposition = x.disposition ? ` · ${x.disposition.disposition}: ${compact ? capUtf8(reason, COMPACT_EXCERPT_BYTES) : reason}` : "";
-  const evidence = x.evidence ? text(x.evidence, "") : "";
-  return `${failureLabel(x)} · ${time} · ${summary}${x.count > 1 ? ` (${x.count} occurrences)` : ""}${disposition}${evidence ? ` · evidence: ${compact ? shortEvidence(evidence) : evidence}` : ""}`;
+  const disposition = x.disposition ? ` · ${x.disposition.disposition}${compact && permission ? "" : `: ${compact ? capUtf8(reason, COMPACT_EXCERPT_BYTES) : reason}`}` : "";
+  const evidence = x.evidence && !(compact && permission) ? text(x.evidence, "") : "";
+  const proof = !compact && permission && x.disposition?.evidence ? ` · disposition evidence: ${text(x.disposition.evidence, "")}` : "";
+  return `${failureLabel(x)} · ${time} · ${summary}${x.count > 1 ? ` (${x.count} occurrences)` : ""}${disposition}${evidence ? ` · evidence: ${compact ? shortEvidence(evidence) : evidence}` : ""}${proof}${annotation}`;
 }
 
 /**
@@ -573,13 +613,15 @@ export interface FailureIncidentPage {
  */
 export function failureRevision(state: FailureState): string {
   return failureIdentity(Object.values(state.observations)
-    .map((item) => [item.id, item.status, item.category, item.count, item.lastSequence ?? 0, item.summary, item.evidence ?? ""])
+    .map((item) => [item.id, item.status, item.category, item.count, item.lastSequence ?? 0, item.summary, item.evidence ?? "",
+      ...(item.permissionBlockers ? [item.permissionBlockers.map(permissionBlockerKey).sort()] : [])])
     .sort((a, b) => String(a[0]).localeCompare(String(b[0]))));
 }
 
 /** Digest of the rows a cursor pages. Scope and detail are part of it: the same incidents render different bytes. */
 function incidentRevision(state: FailureState, scope: IncidentScope = "actionable", detail: IncidentDetail = "compact"): string {
-  return failureIdentity(scope, detail, scopedFailures(state, scope).map((item) => [item.id, item.status, item.count, item.summary, item.evidence ?? ""])).slice(0, 16);
+  return failureIdentity(scope, detail, scopedFailures(state, scope).map((item) => [item.id, item.status, item.count, item.summary, item.evidence ?? "",
+    ...(item.permissionBlockers ? [item.permissionBlockers.map(permissionBlockerKey).sort()] : [])])).slice(0, 16);
 }
 
 /** Cursors carry a digest of their resource/scope, not the scope text. */
@@ -999,6 +1041,8 @@ function readStoredState(path: string): FailureState {
           !Number.isFinite(row.observedAt) || Math.abs(row.observedAt) > 8.64e15 ||
           (e.at !== undefined && (!Number.isFinite(e.at) || Math.abs(e.at) > 8.64e15)) ||
           (e.incidents !== undefined && (!Array.isArray(e.incidents) || !e.incidents.every((id: unknown) => typeof id === "string"))) ||
+          (e.permissionBlockers !== undefined && (e.kind !== "disposition" ||
+            (!state.seen.includes(e.id) && validateDisposition(state, e) !== undefined))) ||
           [e.summary, e.category, e.evidence, e.reason].some((v) => v !== undefined && typeof v !== "string")) throw new Error("invalid record");
       state = reduceFailure(state, e, row.observedAt);
     } catch { state = storageProblem(state, "Failure journal contains unreadable records; observations may be incomplete"); }
@@ -1021,6 +1065,7 @@ export function observeFailures(path: string, events: readonly FailureEvent[], n
     }
     // Rejected dispositions are never journaled or marked seen.
     if (raw.kind === "disposition" && validateDisposition(state, raw)) continue;
+    if (raw.permissionBlockers !== undefined && raw.kind !== "disposition") continue;
     const event = { ...raw, ...(raw.summary ? { summary: text(raw.summary, "") } : {}),
       ...(raw.evidence ? { evidence: text(raw.evidence, "") } : {}), ...(raw.reason ? { reason: text(raw.reason, "") } : {}) };
     try {

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

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

package/node_modules/pi-better-goal/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/node_modules/pi-better-goal/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/node_modules/pi-better-goal/src/index.ts

@@ -28,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,
@@ -91,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";
 }
 
@@ -229,6 +231,7 @@ function formatGoal(
   continuation: ReturnType<typeof currentContinuationState> = null,
   stall = observeGoalStall(goal, continuation),
   preferences: GoalPreferences = { autoContinue: true, conversationalResume: true, pauseOnEscape: true },
+  permissions?: PermissionHold | null,
 ): string {
   const settings = formatPreferences(preferences);
   if (!goal) {
@@ -242,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`,
@@ -375,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);
@@ -418,7 +433,9 @@ 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.");
   };
@@ -457,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 };
@@ -489,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 {
@@ -511,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;
     }
@@ -541,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);
@@ -603,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);
@@ -861,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;
       }
 
@@ -938,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 },
       };
     },
   });
@@ -1104,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");
@@ -1159,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;
@@ -1173,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;
     }
@@ -1199,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.` : "") +
@@ -1214,7 +1264,8 @@ 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}` : ""),
     };
   });
 
@@ -1255,6 +1306,40 @@ export default function (pi: ExtensionAPI): void {
     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) => {
     if (!BLOCKING_QUESTION_TOOLS.has(event.toolName)) return;
     currentCtx = ctx;
@@ -1291,6 +1376,16 @@ export default function (pi: ExtensionAPI): void {
     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;
     }