pi-better-background-tasks 0.6.5 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-better-background-tasks",
-  "version": "0.6.5",
+  "version": "0.7.0",
   "description": "Pi extension for durable background shell tasks, watchers, logs, and status inspection.",
   "license": "MIT",
   "type": "module",

package/src/shared-callback-batcher.ts

@@ -1,6 +1,126 @@
 // Generated from packages/callback-batcher/index.ts. Do not edit directly.
+import { closeSync, mkdirSync, openSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
 export type CallbackSource = "subagent" | "background-task";
 export type CallbackDetailTool = "subagent_result" | "bg_task_status";
+export type CallbackDeliveryMode = "hold" | "steer";
+
+export interface CallbackSettingsContext {
+  sessionManager?: { getBranch?(): readonly unknown[]; getSessionId?(): string };
+  ui?: { notify(message: string, type: "error"): void };
+}
+
+export interface CallbackSettingsSeams {
+  agentDir?: () => string;
+}
+
+export interface CallbackSettings {
+  mode: CallbackDeliveryMode;
+  source: "session" | "default";
+}
+
+export const CALLBACK_SETTINGS_ENTRY = "pi-better-callback-settings";
+const CALLBACK_PREFERENCES_FILE = "pi-better-callback-preferences.json";
+
+function isDeliveryMode(mode: unknown): mode is CallbackDeliveryMode {
+  return mode === "hold" || mode === "steer";
+}
+
+function validCallbackPreferences(value: unknown): value is { version: 1; mode: CallbackDeliveryMode } {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const data = value as Record<string, unknown>;
+  return Object.keys(data).length === 2 && Object.hasOwn(data, "version") && Object.hasOwn(data, "mode")
+    && data.version === 1 && isDeliveryMode(data.mode);
+}
+
+function callbackPreferencesPath(seams: CallbackSettingsSeams): string {
+  return join((seams.agentDir ?? getAgentDir)(), "extensions", CALLBACK_PREFERENCES_FILE);
+}
+
+/** Branch history is authoritative; abandoned branches and invalid entries are ignored. */
+export function getCallbackSettings(
+  ctx: CallbackSettingsContext,
+  seams: CallbackSettingsSeams = {},
+): CallbackSettings {
+  const branch = ctx.sessionManager?.getBranch?.() ?? [];
+  for (let i = branch.length - 1; i >= 0; i--) {
+    const entry = branch[i] as { type?: unknown; customType?: unknown; data?: unknown } | null;
+    if (entry?.type === "custom" && entry.customType === CALLBACK_SETTINGS_ENTRY && validCallbackPreferences(entry.data)) {
+      return { mode: entry.data.mode, source: "session" };
+    }
+  }
+  return getSessionDefault(ctx, seams);
+}
+
+function getSessionDefault(ctx: CallbackSettingsContext, seams: CallbackSettingsSeams): CallbackSettings {
+  const sessionId = ctx.sessionManager?.getSessionId?.();
+  const defaults = globalState().sessionDefaults ??= new WeakMap<object, { sessionId?: string; mode: CallbackDeliveryMode }>();
+  const initial = ctx.sessionManager ? defaults.get(ctx.sessionManager) : undefined;
+  if (initial && initial.sessionId === sessionId) return { mode: initial.mode, source: "default" };
+  const snapshot = (mode: CallbackDeliveryMode): CallbackSettings => {
+    if (ctx.sessionManager) defaults.set(ctx.sessionManager, { sessionId, mode });
+    return { mode, source: "default" };
+  };
+  const path = callbackPreferencesPath(seams);
+  let text: string;
+  try {
+    text = readFileSync(path, "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return snapshot("hold");
+    throw new Error(`Cannot read callback default at ${path}: ${String(error)}`, { cause: error });
+  }
+  try {
+    const data: unknown = JSON.parse(text);
+    if (!validCallbackPreferences(data)) throw new Error('Expected { version: 1, mode: "hold" | "steer" }');
+    return snapshot(data.mode);
+  } catch (error) {
+    throw new Error(`Invalid callback default at ${path}: ${String(error)}`, { cause: error });
+  }
+}
+
+/** Saves only the future-session default; never changes the active branch or batcher. */
+export function saveCallbackDefault(mode: CallbackDeliveryMode, seams: CallbackSettingsSeams = {}): void {
+  if (!isDeliveryMode(mode)) throw new Error("Invalid callback delivery mode. Nothing saved.");
+  const dir = join((seams.agentDir ?? getAgentDir)(), "extensions");
+  const path = join(dir, CALLBACK_PREFERENCES_FILE);
+  const tmp = join(dir, `.${CALLBACK_PREFERENCES_FILE}.${randomUUID()}.tmp`);
+  let created = false;
+  try {
+    mkdirSync(dir, { recursive: true });
+    const fd = openSync(tmp, "wx", 0o600);
+    created = true;
+    try { writeFileSync(fd, `${JSON.stringify({ version: 1, mode })}\n`); }
+    finally { closeSync(fd); }
+    renameSync(tmp, path);
+  } catch (error) {
+    throw new Error(`Cannot save callback default at ${path}: ${String(error)}`, { cause: error });
+  } finally {
+    if (created) rmSync(tmp, { force: true });
+  }
+}
+
+/** Persist first so a failed append cannot become a transient delivery-mode change. */
+export function changeCallbackSetting(
+  host: CallbackBatchHost & { appendEntry(customType: string, data: unknown): void },
+  ctx: CallbackSettingsContext & { isIdle(): boolean },
+  mode: CallbackDeliveryMode,
+): void {
+  if (!isDeliveryMode(mode)) throw new Error("Invalid callback delivery mode. Nothing changed.");
+  const data = { version: 1, mode };
+  try { host.appendEntry(CALLBACK_SETTINGS_ENTRY, data); }
+  catch (error) {
+    // Pi advances its in-memory branch before disk persistence. Invalidate
+    // our payload so that failed entry cannot become a restored setting.
+    data.version = 0;
+    throw error;
+  }
+  const batcher = bindCallbackBatcher(host, ctx);
+  batcher.setWhileBusy(mode);
+  batcher.setAvailability(() => ctx.isIdle());
+}
 
 export interface CallbackBatchHost {
   /** Older Pi shares this object; newer Pi supplies per-extension wrappers. */
@@ -70,6 +190,8 @@ export interface CallbackBatcherOptions {
   retryMs?: number;
   /** Ordinary callbacks stay here, not in Pi's follow-up queue, while unavailable. */
   isAvailable?: () => boolean;
+  /** Internal initial mode. Session/default settings are restored with context. */
+  whileBusy?: CallbackDeliveryMode;
   /** UTF-8 byte cap for one sendMessage payload. Defaults to 2 KiB. */
   maxBytes?: number;
 }
@@ -81,6 +203,14 @@ export interface CallbackBatcher {
   setHost(host: CallbackBatchHost): void;
   /** Update the session predicate and schedule an asynchronous drain when available. */
   setAvailability(isAvailable: () => boolean): void;
+  /** Change delivery immediately without clearing pending callbacks or handoff receipts. */
+  setWhileBusy(mode: CallbackDeliveryMode): void;
+  /** Non-idle context operations are not foreground agent runs. */
+  setForegroundRunning(running: boolean): void;
+  /** Shared IDs make duplicate notifications from both extensions idempotent. */
+  toolStarted(toolCallId: string): void;
+  /** Await the final active tool's handoff before Pi checks its steering queue. */
+  toolEnded(toolCallId: string): Promise<boolean>;
   deliverUrgent(event: UrgentCallbackEvent): boolean | Promise<boolean>;
   cancel(): void;
   pendingCount(): number;
@@ -104,6 +234,7 @@ interface PendingEvent {
 interface SharedCallbackBatcherState {
   byHost: WeakMap<object, CallbackBatcher>;
   bySession?: WeakMap<object, CallbackBatcher>;
+  sessionDefaults?: WeakMap<object, { sessionId?: string; mode: CallbackDeliveryMode }>;
 }
 
 const GLOBAL_STATE_KEY = Symbol.for("@1aboveio/pi-better-harness/callback-batcher");
@@ -131,7 +262,6 @@ const RETRIEVAL_FOOTER =
 
 export const CALLBACK_BATCH_WINDOW_ENV = "PI_BETTER_CALLBACK_BATCH_MS";
 export const DEFAULT_CALLBACK_BATCH_WINDOW_MS = DEFAULT_WINDOW_MS;
-
 export function resolveCallbackBatchWindowMs(
   value: unknown = process.env[CALLBACK_BATCH_WINDOW_ENV],
 ): number {
@@ -436,26 +566,31 @@ export function createCallbackBatcher(
 ): CallbackBatcher {
   const windowMs = options.windowMs ?? resolveCallbackBatchWindowMs();
   const retryMs = Math.max(0, options.retryMs ?? DEFAULT_RETRY_MS);
+  let whileBusy = options.whileBusy ?? "hold";
   const maxBytes = callbackBatchBudget(options.maxBytes);
   const pending = new Map<string, PendingEvent>();
   const inFlight = new Set<string>();
   const urgentInFlight = new Set<string>();
   const handedOff = new Map<string, number>();
+  const activeTools = new Set<string>();
   let sequence = 0;
   let timer: ReturnType<typeof setTimeout> | undefined;
   let flushPromise: Promise<boolean> | undefined;
   let isAvailable = options.isAvailable ?? (() => true);
   let gated = options.isAvailable !== undefined;
   let awaitingRun = false;
+  let cancelled = false;
+  let foregroundRunning = false;
 
-  const available = (): boolean => {
+  const deliveryMode = (): "followUp" | "steer" | undefined => {
+    if (cancelled) return undefined;
     try {
       if (!isAvailable()) {
         awaitingRun = false;
-        return false;
+        return whileBusy === "steer" && foregroundRunning && activeTools.size === 0 ? "steer" : undefined;
       }
-      return !awaitingRun;
-    } catch { return false; }
+      return !awaitingRun ? "followUp" : undefined;
+    } catch { return undefined; }
   };
 
   const cancelTimer = (): void => {
@@ -466,7 +601,7 @@ export function createCallbackBatcher(
   const schedule = (delayMs: number): void => {
     if (timer || pending.size === 0) return;
     // Some idle transitions (manual compaction) have no agent_settled event.
-    const delay = available() ? delayMs : retryMs;
+    const delay = deliveryMode() ? delayMs : retryMs;
     timer = setTimeout(() => {
       timer = undefined;
       void api.flush();
@@ -485,7 +620,8 @@ export function createCallbackBatcher(
 
   const performFlush = async (): Promise<boolean> => {
     cancelTimer();
-    if (!available()) {
+    const mode = deliveryMode();
+    if (!mode) {
       schedule(retryMs);
       return false;
     }
@@ -539,14 +675,16 @@ export function createCallbackBatcher(
     try {
       // Pi may defer the requested run while settled handlers finish, leaving
       // isIdle() true. Permit no second handoff until a run starts.
-      awaitingRun = gated;
+      awaitingRun = mode === "followUp" && gated;
       await host.sendMessage(
         {
           customType: "background-completion-batch",
           content: packed.text,
           display: true,
         },
-        { deliverAs: "followUp", triggerTurn: true },
+        // Newer Pi requires triggerTurn for steering too; false only appends
+        // a custom message at the turn boundary without continuing the agent.
+        { deliverAs: mode, triggerTurn: true },
       );
     } catch {
       awaitingRun = false;
@@ -632,15 +770,42 @@ export function createCallbackBatcher(
     setAvailability(check) {
       gated = true;
       isAvailable = check;
-      available();
+      cancelled = false;
+      deliveryMode();
       cancelTimer();
       schedule(windowMs);
     },
+    setWhileBusy(mode) {
+      if (!isDeliveryMode(mode)) throw new Error("Invalid callback delivery mode. Nothing changed.");
+      whileBusy = mode;
+      cancelTimer();
+      schedule(windowMs);
+    },
+    setForegroundRunning(running) {
+      foregroundRunning = running;
+      cancelTimer();
+      schedule(windowMs);
+    },
+    toolStarted(toolCallId) {
+      activeTools.add(toolCallId);
+    },
+    async toolEnded(toolCallId) {
+      const ended = activeTools.delete(toolCallId);
+      if (activeTools.size > 0 || whileBusy !== "steer" || cancelled) return false;
+      if (!ended) return flushPromise ?? false;
+      // A timer may still be completing a deferred flush. Recheck after it so
+      // the tool boundary cannot lose the pending batch to that older attempt.
+      if (flushPromise) await flushPromise;
+      return pending.size > 0 ? api.flush() : true;
+    },
     deliverUrgent,
     cancel() {
       cancelTimer();
       pending.clear();
       awaitingRun = false;
+      activeTools.clear();
+      foregroundRunning = false;
+      cancelled = true;
     },
     pendingCount() {
       return pending.size;
@@ -671,11 +836,39 @@ export function cancelCallbackBatch(host: CallbackBatchHost): void {
   batcher?.cancel();
 }
 
-/** Called on session_start, agent_start and agent_settled by both extensions. */
+/** Restore current branch/default mode without resetting foreground tools or receipts. */
 export function setCallbackBatchContext(
   host: CallbackBatchHost,
-  ctx: { isIdle(): boolean; sessionManager?: object },
+  ctx: CallbackSettingsContext & { isIdle(): boolean },
+  seams: CallbackSettingsSeams = {},
 ): void {
+  const batcher = bindCallbackBatcher(host, ctx);
+  let mode: CallbackDeliveryMode = "hold";
+  try {
+    const settings = getCallbackSettings(ctx, seams);
+    if (settings.source === "session") {
+      // Capture the initial default even when an override currently hides it,
+      // so navigating to an unconfigured branch cannot inherit a later save.
+      try { getSessionDefault(ctx, seams); }
+      catch {
+        if (ctx.sessionManager) {
+          const defaults = globalState().sessionDefaults ??= new WeakMap();
+          defaults.set(ctx.sessionManager, { sessionId: ctx.sessionManager.getSessionId?.(), mode: "hold" });
+        }
+      }
+    }
+    mode = settings.mode;
+  } catch (error) {
+    try { ctx.ui?.notify(`Callback delivery restored to hold: ${String(error)}`, "error"); }
+    catch { /* A failing UI must not retain the prior session's delivery mode. */ }
+  }
+  batcher.setWhileBusy(mode);
+  // Schedule rather than await delivery inside agent_settled: its handlers are
+  // still settling the previous run, and sendMessage may start a new one.
+  batcher.setAvailability(() => ctx.isIdle());
+}
+
+function bindCallbackBatcher(host: CallbackBatchHost, ctx: CallbackSettingsContext): CallbackBatcher {
   const state = globalState();
   const bySession = state.bySession ??= new WeakMap<object, CallbackBatcher>();
   const shared = ctx.sessionManager ? bySession.get(ctx.sessionManager) : undefined;
@@ -683,9 +876,7 @@ export function setCallbackBatchContext(
   if (ctx.sessionManager) bySession.set(ctx.sessionManager, batcher);
   state.byHost.set(host.events ?? host, batcher);
   batcher.setHost(host);
-  // Schedule rather than await delivery inside agent_settled: its handlers are
-  // still settling the previous run, and sendMessage may start a new one.
-  batcher.setAvailability(() => ctx.isIdle());
+  return batcher;
 }
 
 function globalState(): SharedCallbackBatcherState {

package/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/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/tools.ts

@@ -13,7 +13,7 @@ import {
   type OutputOptions,
 } from "./output.js";
 import { readOutputControls } from "./shared-log-utils.js";
-import { cancelCallbackBatch, setCallbackBatchContext } from "./shared-callback-batcher.js";
+import { cancelCallbackBatch, getCallbackBatcher, 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";
@@ -203,8 +203,18 @@ 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("agent_start", (_event, ctx) => {
+    setCallbackBatchContext(pi, ctx);
+    getCallbackBatcher(pi).setForegroundRunning(true);
+  });
+  pi.on("session_tree", (_event, ctx) => { setCallbackBatchContext(pi, ctx); });
+  pi.on("agent_end", () => { getCallbackBatcher(pi).setForegroundRunning(false); });
+  pi.on("agent_settled", (_event, ctx) => {
+    getCallbackBatcher(pi).setForegroundRunning(false);
+    setCallbackBatchContext(pi, ctx);
+  });
+  pi.on("tool_execution_start", (event) => { getCallbackBatcher(pi).toolStarted(event.toolCallId); });
+  pi.on("tool_execution_end", async (event) => { await getCallbackBatcher(pi).toolEnded(event.toolCallId); });
   pi.on("session_before_switch", () => {
     activeSession = undefined;
     cancelCallbackBatch(pi);