@hank-warren/pi-auto-permissions 0.11.1 → 0.12.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @hank-warren/pi-auto-permissions
 
+## 0.12.0
+
+### Minor Changes
+
+- 897739d: Framed approval card, fresh-session launch, and a loop-safe permission posture.
+
+  **pi-loop**
+
+  - The approval card is now a framed `customType` transcript block, emitted once per draft, with its choices in an action menu. It used to go out twice and neither copy was a card: `loop_propose` returned it as tool-result markdown (re-spending the objective's tokens in the model's own context) and `/loop` re-printed it as a toast.
+  - `startLoop` is split into `buildLoop` and `installLoop`, and the menu gains **Start loop in a fresh session** — the loop is built in the planning session and installed in a new one, so only the objective crosses and the drafting conversation does not.
+  - A loop publishes `PI_LOOP_ACTIVE=1` and `PI_LOOP_ID` on the process while active. This is a contract for other extensions, mirroring `PI_SUBAGENT_CHILD`: no import, no dependency, no RPC.
+  - The autonomy posture is reconciled with it. Reshaping a command to get _around_ a permission gate stays forbidden; revising it to satisfy a concern a guardian actually stated is legitimate and bounded. The `⚠ loop blocked` detector is unchanged.
+
+  **pi-auto-permissions**
+
+  - While `PI_LOOP_ACTIVE=1`, an `ask_user` verdict returns the guardian's concern to the agent as a non-blocking block instead of opening a modal. A session waiting on a modal is busy, and a busy session starves a loop's continuation path — the prompt would not be answered, it would deadlock the loop until it expired. **The verdict is unchanged; only its delivery is.** The absence of a user is never authorization.
+  - Revision is bounded — per concern, per gate, and by consecutive blocked attempts — after which the block names `loop_wait` instead of inviting another try. The bounds survive a compaction and a session restore.
+
+  Detection is fail-open in both directions: with the environment variables absent, behaviour is exactly as before, and neither package requires the other.
+
 ## 0.11.1
 
 ### Patch Changes

package/README.md

@@ -313,6 +313,22 @@ When a session is a [pi-subagents](https://github.com/nicobailon/pi-subagents) c
 
 Subagent sessions have no interactive user, so an `ask_user` verdict blocks the command immediately with a reason instructing the child to route around the gated operation or report the blocker. Reviewer usage records from subagent sessions carry `"subagent": true` in the usage sidecar.
 
+## Unattended loop sessions
+
+When the session is running an unattended loop, the guardian's decisions are unchanged and only their *delivery* changes: an `ask_user` verdict returns the concern to the agent as a block instead of opening a prompt. This is not a relaxation. A session waiting on a modal is busy, and a busy session starves the loop's own continuation path — no turn completes, no cap trips, and nothing ends the loop until it expires, potentially days later. The prompt would not be answered; it would simply deadlock.
+
+Detection is an environment contract, not a dependency. [pi-loop](https://github.com/hank-warren/pi-extensions/tree/main/packages/pi-loop) sets `PI_LOOP_ACTIVE=1` and `PI_LOOP_ID=<id>` on the process while a loop is active and removes them when it is not; this extension reads them exactly as it reads `PI_SUBAGENT_CHILD`. Neither package imports or depends on the other, and with the variables absent — pi-loop not installed, or no loop running — behavior is identical to today.
+
+The agent is given a bounded number of revision rounds against the guardian's stated concern, after which the block stops offering that option and instructs it to call `loop_wait` (pi-loop's non-deadlocking way to reach a human). The bound is what keeps "address the objection" from becoming "retry until something is approved":
+
+- **3 blocked attempts per concern**, so there are two real revisions: enough for a misread of a terse objection plus a considered fix.
+- **5 blocked attempts per gate.**
+- **5 consecutive blocked attempts**, at any gate, for any concern — the backstop. An approved command resets it, since an agent getting real work past the guardian is not grinding against it.
+
+The block reports whichever bound is closest, and the stated remainder falls every time. Both of the first two bounds are keyed on something the *command* determines, and a canary walked through each in turn. The guardian rewords its objection between rounds, so a count keyed on that prose stops advancing and the block repeats "1 revision round remains" forever — the agent read two identical blocks, called the number ambiguous, and stopped trusting it. Then, blocked on `git branch -D`, it tried `git branch --delete`: the same operation under a different rule, which reset both the gate counter and the concern key embedded in it. The consecutive-block count is immune to both, because it measures the argument rather than the command, and a concern or gate first seen mid-argument inherits the argument's length instead of starting over.
+
+Counts are held in memory *and* persisted as a session entry, so neither a context compaction nor a session resume hands back a fresh budget. A review that fails for infrastructure reasons blocks without charging a round, since that is not a guardian judgment.
+
 ## Guardian dispatch
 
 Reviewer requests dispatch through the host's model runtime rather than pi-ai's compat layer, so provider transports registered by other extensions (for example `@gotgenes/pi-anthropic-auth` OAuth request shaping) apply to guardian calls. When the runtime seam is unavailable, dispatch falls back to `compat.completeSimple`.

package/index.ts

@@ -2,6 +2,12 @@ import { cleanupSessionResources, type Message } from "@earendil-works/pi-ai";
 import { resolveGuardianCompleteSimple } from "./guardian-transport.js";
 import { isOpenAICodexModel } from "./openai-codex-transport.js";
 import { detectSubagentContext } from "./subagent-context.js";
+import { detectLoopContext } from "./loop-context.js";
+import {
+  LoopReviseBudget,
+  loopBlockReason,
+  type LoopReviseCharge,
+} from "./loop-revise-budget.js";
 import * as PiCodingAgent from "@earendil-works/pi-coding-agent";
 import {
   getSelectListTheme,
@@ -50,6 +56,7 @@ import {
   applyFullRebuildEviction,
   buildReviewEnvelope,
   collectReviewEvidence,
+  LOOP_CONTEXT_SYSTEM_PROMPT,
   OVERRIDE_FEEDBACK_SYSTEM_PROMPT,
   parsePermissionVerdict,
   SUBAGENT_CONTEXT_SYSTEM_PROMPT,
@@ -242,6 +249,17 @@ export default function autoPermissionsExtension(pi: ExtensionAPI) {
   let lastConfigError: string | undefined;
   let lastEvaluationLogError: string | undefined;
   let sessionActive = true;
+  /**
+   * Revision rounds spent per guardian concern while a loop is active.
+   *
+   * Session-scoped and held here rather than in the review closure, so a
+   * context compaction (which rewrites the conversation, not this process)
+   * cannot reset it. Restored from the session branch at session_start so a
+   * resume cannot reset it either.
+   */
+  const loopReviseBudget = new LoopReviseBudget();
+  /** The loop these counts belong to, so a new loop starts with a clean budget. */
+  let loopReviseBudgetLoopId: string | undefined;
   let bashRendererRegistered = false;
   let bashRendererSourcePath: string | undefined;
   let clearWidgetTimer: ReturnType<typeof setTimeout> | undefined;
@@ -347,9 +365,12 @@ export default function autoPermissionsExtension(pi: ExtensionAPI) {
     // buildReviewerSystemPrompt append the untrusted project-instructions
     // evidence block, keeping policy contiguous and evidence terminal.
     const subagentContext = detectSubagentContext(ctx.cwd);
-    const basePolicyPrompt = subagentContext
-      ? `${config.systemPrompt}\n\n${SUBAGENT_CONTEXT_SYSTEM_PROMPT}`
-      : config.systemPrompt;
+    const loopContext = detectLoopContext();
+    const basePolicyPrompt = [
+      config.systemPrompt,
+      ...(subagentContext ? [SUBAGENT_CONTEXT_SYSTEM_PROMPT] : []),
+      ...(loopContext ? [LOOP_CONTEXT_SYSTEM_PROMPT] : []),
+    ].join("\n\n");
     // Appended outside config.systemPrompt so sessions using a customized
     // systemPromptFile still learn how to weigh override records.
     const policyPrompt = `${basePolicyPrompt}\n\n${OVERRIDE_FEEDBACK_SYSTEM_PROMPT}`;
@@ -382,7 +403,13 @@ export default function autoPermissionsExtension(pi: ExtensionAPI) {
       cwd: ctx.cwd,
       gate: gate.label,
       group: gate.group,
-      ...(subagentContext ? { execution: subagentContext } : {}),
+      ...(subagentContext && loopContext
+        ? { execution: { ...subagentContext, ...loopContext } }
+        : subagentContext
+          ? { execution: subagentContext }
+          : loopContext
+            ? { execution: loopContext }
+            : {}),
     };
     const makeUserMessage = (records: readonly ReviewEvidenceRecord[], mode: "full" | "delta"): Message => ({
       role: "user",
@@ -766,6 +793,33 @@ export default function autoPermissionsExtension(pi: ExtensionAPI) {
     }).finally(() => indicator?.stop());
   }
 
+  /**
+   * Charge one revision round against a guardian concern and persist the
+   * budget. A loop id different from the one the counts belong to means a new
+   * loop: it inherits nothing from the last one's arguments with the guardian.
+   */
+  function chargeLoopRevision(
+    loopId: string | undefined,
+    gateLabel: string,
+    reason: string,
+  ): LoopReviseCharge {
+    if (loopReviseBudgetLoopId !== loopId) {
+      loopReviseBudget.clear();
+      loopReviseBudgetLoopId = loopId;
+    }
+    const charge = loopReviseBudget.charge(gateLabel, reason);
+    try {
+      pi.appendEntry(LoopReviseBudget.entryType, {
+        ...loopReviseBudget.snapshot(),
+        ...(loopId ? { loopId } : {}),
+      });
+    } catch {
+      // Persistence is what survives a restore; the in-memory count is what
+      // survives a compaction. Losing the former never widens the bound now.
+    }
+    return charge;
+  }
+
   async function askUser(
     gate: Gate,
     command: string,
@@ -913,8 +967,33 @@ export default function autoPermissionsExtension(pi: ExtensionAPI) {
       }
       if (verdict.decision === "approve") {
         showReviewDisplay(ctx, config, gate, command, target, "approved", verdict.reason, true);
+        // An approval ends the argument at this gate: the per-gate bound exists
+        // to stop an agent grinding, not to ration a long loop's whole session.
+        loopReviseBudget.settle(gate.label);
         return;
       }
+      // An unattended loop cannot answer a modal and must not be handed an
+      // unbounded retry loop either, so both non-approving verdicts come back
+      // as one bounded block. The verdict itself is unchanged: nothing is
+      // approved here that would not have been approved with a user present.
+      const loopContext = detectLoopContext();
+      if (loopContext) {
+        const charge = chargeLoopRevision(loopContext.loopId, gate.label, verdict.reason);
+        showReviewDisplay(
+          ctx,
+          config,
+          gate,
+          command,
+          target,
+          verdict.decision === "revise" ? "revise" : "blocked",
+          verdict.reason,
+          true,
+        );
+        return {
+          block: true,
+          reason: loopBlockReason({ gateLabel: gate.label, reason: verdict.reason, ...charge }),
+        };
+      }
       if (verdict.decision === "revise") {
         showReviewDisplay(ctx, config, gate, command, target, "revise", verdict.reason, true);
         return {
@@ -929,6 +1008,16 @@ export default function autoPermissionsExtension(pi: ExtensionAPI) {
         return { block: true, reason: "Auto Permissions review cancelled" };
       }
       const reason = error instanceof Error ? error.message : String(error);
+      // A review that failed is an infrastructure fault, not a guardian
+      // judgment, so it charges no revision round — but it still must not open
+      // a modal in a session with nobody to answer it.
+      if (detectLoopContext()) {
+        showReviewDisplay(ctx, config, gate, command, target, "blocked", reason, true);
+        return {
+          block: true,
+          reason: `${gate.label} could not be reviewed (${reason}), and this session is running an unattended /loop, so there is no one to ask. Do not retry the same command hoping the reviewer recovers: call loop_wait naming the reviewer failure, or advance the objective another way.`,
+        };
+      }
       return askUser(
         gate,
         command,
@@ -1151,6 +1240,10 @@ export default function autoPermissionsExtension(pi: ExtensionAPI) {
     allowedConventionCommands.clear();
     permissionOverrides.length = 0;
     overrideSeq = 0;
+    // Rebuild the revise budget before the first tool call: a resumed session
+    // that forgot its spent rounds would hand the agent a fresh set of them.
+    loopReviseBudget.restore(ctx.sessionManager.getBranch());
+    loopReviseBudgetLoopId = detectLoopContext()?.loopId;
     for (const entry of ctx.sessionManager.getBranch()) {
       if (entry.type !== "message" || entry.message.role !== "toolResult") continue;
       if (entry.message.toolName !== "request_override") continue;

package/loop-context.ts

@@ -0,0 +1,41 @@
+/**
+ * Detecting an unattended pi-loop session.
+ *
+ * A guardian that decides "ask_user" opens a modal and waits. In an ordinary
+ * session that is the whole point — the boundary this extension exists to
+ * hold. In a session running a pi-loop it is a deadlock: a session waiting on
+ * a modal is `busy`, `busy` makes every loop continuation and every fallback
+ * tick skip, so no turn ever completes, no cap ever trips, and nothing ends
+ * the loop until it expires — up to seven days later.
+ *
+ * So the verdict stays exactly the same and only its *delivery* changes: the
+ * guardian's concern comes back as a non-blocking block the agent can read and
+ * act on, instead of a prompt nobody is there to answer. Nothing is approved
+ * that would not have been approved before.
+ *
+ * Detection mirrors `detectSubagentContext` deliberately: an environment
+ * variable, read the same way, with no import of and no dependency on the
+ * extension that sets it. pi-loop publishes `PI_LOOP_ACTIVE=1` and
+ * `PI_LOOP_ID` while a loop is active and removes them when it is not (see
+ * `packages/pi-loop/src/loop-env.ts`). Absent that env — pi-loop not
+ * installed, or installed with no loop running — behaviour is unchanged.
+ */
+
+/** Runtime facts about an active loop, forwarded to the guardian as evidence. */
+export interface LoopExecutionContext {
+  loop: true;
+  /** The loop's id (PI_LOOP_ID), when present. */
+  loopId?: string;
+}
+
+export function detectLoopContext(
+  env: Record<string, string | undefined> = process.env,
+): LoopExecutionContext | undefined {
+  if (env.PI_LOOP_ACTIVE !== "1") return undefined;
+  const context: LoopExecutionContext = { loop: true };
+  // The id reaches the guardian prompt, so cap length and charset the way the
+  // subagent run id is capped: an identifier, never a payload.
+  const loopId = env.PI_LOOP_ID?.trim().replace(/[^\w.:-]/g, "").slice(0, 128);
+  if (loopId) context.loopId = loopId;
+  return context;
+}

package/loop-revise-budget.ts

@@ -0,0 +1,305 @@
+/**
+ * Bounding the revise path for an unattended loop.
+ *
+ * Turning "ask_user" into a readable block removes the deadlock, but on its
+ * own it replaces one failure with a worse one: an agent that can always try
+ * again will always try again, and "keep adjusting the command until the
+ * guardian stops objecting" is a search for the phrasing that slips past the
+ * gate. That is precisely what pi-loop's own autonomy posture forbids, and it
+ * is not made safe by the guardian re-reviewing each attempt — the guardian
+ * reviews commands, and the thing being optimised against it is the command.
+ *
+ * So the rounds are counted, per concern, and they run out. Within the bound
+ * the agent may revise to *address* what the guardian said. Past it the block
+ * stops offering that option and names `loop_wait` instead, which is the only
+ * way a loop can ask a human anything without deadlocking itself.
+ *
+ * The count is keyed on the concern rather than the command precisely because
+ * the command is what changes: counting per command would reset the budget on
+ * every reshape, which is the behaviour being bounded.
+ *
+ * Two bounds, not one, and this is the load-bearing detail. A per-concern
+ * count is what makes the block specific enough to act on ("one round remains
+ * against *this*"), but a concern is prose and prose gets reworded, so a
+ * guardian phrasing the same objection differently would hand back a fresh
+ * budget — the failure mode this exists to prevent, arriving through the back
+ * door. The per-gate count is immune to wording and bounds the whole argument
+ * regardless. Whichever runs out first ends it.
+ */
+
+const LOOP_REVISIONS_ENTRY_TYPE = "auto-permissions-loop-revisions";
+
+/**
+ * How many revisions an agent gets against one concern before it must wait.
+ *
+ * Three blocked attempts, so there are two real revisions: the first is often
+ * an honest misunderstanding of a terse concern and the second is the
+ * considered fix. A third attempt at the same objection is not a better
+ * command, it is a search.
+ */
+export const LOOP_REVISE_ROUNDS = 3;
+
+/**
+ * How many blocked attempts an agent gets at one gate before it must wait,
+ * whatever the concerns were.
+ *
+ * Deliberately larger than the per-concern bound: a second, genuinely
+ * different objection deserves its own rounds. Deliberately finite: an agent
+ * collecting objection after objection at the same gate is not converging on
+ * an authorized command, and the wording of the objection is not what makes
+ * that true.
+ */
+export const LOOP_GATE_ROUNDS = 5;
+
+/**
+ * How many times in a row an agent may be blocked, at any gate, for any
+ * concern, before it must wait.
+ *
+ * The backstop, and the only bound nothing can reshape its way out of. Both
+ * bounds above are keyed on something the *command* determines: the concern is
+ * the guardian's prose, and the gate is whichever rule the command text
+ * matched. A canary walked straight through both — blocked on
+ * `git branch -D`, the agent tried `git branch --delete`, which is the same
+ * operation under a different rule, and the budget started over.
+ *
+ * Counting blocks is immune to both, because it measures the argument rather
+ * than the command. Only resolving that argument — an approval at a gate that
+ * has been blocking — resets it.
+ */
+export const LOOP_STREAK_ROUNDS = 5;
+
+/** Words too common to distinguish one guardian concern from another. */
+const STOPWORDS = new Set([
+  "a", "an", "and", "are", "as", "at", "be", "been", "but", "by", "for", "from", "has", "have",
+  "in", "is", "it", "its", "not", "of", "on", "or", "that", "the", "this", "to", "was", "were",
+  "which", "with", "would", "user", "command", "action", "request", "because", "without",
+]);
+
+/** Cap on the tokens that form a concern's signature. */
+const SIGNATURE_TOKENS = 10;
+
+/**
+ * A stable key for "the same objection, restated".
+ *
+ * A guardian writes one concise sentence and writes it slightly differently
+ * each time, so exact text would reset the budget on every round. The sorted
+ * set of significant words survives rewording, and when two genuinely
+ * different concerns do collide the budget only ever binds *tighter* — the
+ * safe direction for a bound whose failure mode is unbounded retrying.
+ */
+export function concernKey(gateLabel: string, reason: string): string {
+  const tokens = [
+    ...new Set(
+      reason
+        .toLowerCase()
+        .replace(/[^a-z0-9\s]/g, " ")
+        .split(/\s+/)
+        .map(stem)
+        .filter((token) => token.length > 2 && !STOPWORDS.has(token)),
+    ),
+  ]
+    .sort()
+    .slice(0, SIGNATURE_TOKENS);
+  return `${gateLabel}::${tokens.join(" ")}`;
+}
+
+/**
+ * Crude suffix stripping, so "authorize", "authorized" and "authorizing" are
+ * one token. Not linguistics: just enough that the commonest rewording of the
+ * same objection lands on the same key. Anything it misses is caught by the
+ * per-gate bound, which is why it can afford to be crude.
+ */
+function stem(token: string): string {
+  for (const suffix of ["ing", "ed", "es", "s"]) {
+    if (token.length > suffix.length + 3 && token.endsWith(suffix)) {
+      return token.slice(0, -suffix.length);
+    }
+  }
+  return token;
+}
+
+interface PersistedBudget {
+  concerns?: unknown;
+  gates?: unknown;
+  streak?: unknown;
+}
+
+/**
+ * Per-concern revision counts for this session.
+ *
+ * Held in memory *and* persisted as a custom session entry. The memory copy is
+ * what survives a context compaction (the process does not restart, so the map
+ * is untouched while the conversation around it is rewritten); the persisted
+ * copy is what survives a session restore, and what makes the bound
+ * reconstructible rather than merely lucky. Both matter: a bound that a
+ * compaction silently reset would hand the agent unlimited rounds at exactly
+ * the moment its own memory of the concern was summarised away.
+ */
+/** What one charged round leaves the agent with. */
+export interface LoopReviseCharge {
+  /** Rounds spent against this concern, including the one being reported. */
+  concernSpent: number;
+  /** Blocked attempts at this gate, including the one being reported. */
+  gateSpent: number;
+  /** Consecutive blocked attempts anywhere, including the one being reported. */
+  streakSpent: number;
+}
+
+export class LoopReviseBudget {
+  private concerns = new Map<string, number>();
+  private gates = new Map<string, number>();
+  private streak = 0;
+
+  /** Rebuild from a session branch, fail-open: unreadable state means no rounds spent. */
+  restore(entries: readonly unknown[]): void {
+    this.concerns = new Map();
+    this.gates = new Map();
+    this.streak = 0;
+    for (let index = entries.length - 1; index >= 0; index -= 1) {
+      const entry = entries[index] as
+        | { type?: string; customType?: string; data?: unknown }
+        | undefined;
+      if (entry?.type !== "custom" || entry.customType !== LOOP_REVISIONS_ENTRY_TYPE) continue;
+      const data = entry.data as PersistedBudget | undefined;
+      readCounts(data?.concerns, this.concerns);
+      readCounts(data?.gates, this.gates);
+      const streak = data?.streak;
+      if (typeof streak === "number" && Number.isSafeInteger(streak) && streak > 0) {
+        this.streak = streak;
+      }
+      return;
+    }
+  }
+
+  /** The whole budget, as the data half of a session entry. */
+  snapshot(): {
+    concerns: Record<string, number>;
+    gates: Record<string, number>;
+    streak: number;
+  } {
+    return {
+      concerns: Object.fromEntries(this.concerns),
+      gates: Object.fromEntries(this.gates),
+      streak: this.streak,
+    };
+  }
+
+  /** The custom-entry type this budget persists under. */
+  static get entryType(): string {
+    return LOOP_REVISIONS_ENTRY_TYPE;
+  }
+
+  /** What `charge` would report without charging. */
+  spent(gateLabel: string, reason: string): LoopReviseCharge {
+    return {
+      concernSpent: this.concerns.get(concernKey(gateLabel, reason)) ?? 0,
+      gateSpent: this.gates.get(gateLabel) ?? 0,
+      streakSpent: this.streak,
+    };
+  }
+
+  /**
+   * Charge one blocked attempt and return the new totals.
+   *
+   * A concern seen for the first time *during an argument already under way at
+   * this gate* inherits that argument's length rather than starting at one.
+   * Without it the count silently stops advancing whenever the guardian
+   * rewords its objection, and the block repeats "1 revision round remains"
+   * forever. Observed live in a canary, where the agent read two identical
+   * blocks and said so: "it says again '1 revision round remains' —
+   * ambiguous". A budget whose displayed remainder does not fall is not a
+   * budget, and the agent is right not to trust it.
+   */
+  charge(gateLabel: string, reason: string): LoopReviseCharge {
+    const key = concernKey(gateLabel, reason);
+    this.streak += 1;
+    const gateSpent = (this.gates.get(gateLabel) ?? 0) + 1;
+    const seen = this.concerns.get(key);
+    // A concern or a gate first seen mid-argument inherits the argument's
+    // length from the streak, which is the only count a reshape cannot move.
+    const concernSpent = seen === undefined ? this.streak : seen + 1;
+    this.concerns.set(key, concernSpent);
+    this.gates.set(gateLabel, gateSpent);
+    return { concernSpent, gateSpent, streakSpent: this.streak };
+  }
+
+  /**
+   * An approved command ends the argument at that gate.
+   *
+   * Without this a long loop would accumulate unrelated objections all session
+   * and eventually refuse to revise anything. The per-concern counts stay:
+   * approving one command is not an answer to a different objection.
+   *
+   * The streak resets only when the approval lands on a gate that was actually
+   * blocking. Resetting it on *any* approval looked reasonable and was not: a
+   * canary agent ran three read-only `git log` and `git merge-base` calls
+   * between two blocked deletions, each approved, and every one of them handed
+   * the budget back. The backstop has to survive an agent looking things up in
+   * the middle of an argument, which is exactly what a thoughtful agent does.
+   */
+  settle(gateLabel: string): void {
+    if (this.gates.delete(gateLabel)) this.streak = 0;
+  }
+
+  /** Forget everything: a new loop is not answerable for the last one's rounds. */
+  clear(): void {
+    this.concerns = new Map();
+    this.gates = new Map();
+    this.streak = 0;
+  }
+}
+
+function readCounts(value: unknown, into: Map<string, number>): void {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return;
+  for (const [key, count] of Object.entries(value as Record<string, unknown>)) {
+    if (typeof count !== "number" || !Number.isSafeInteger(count) || count <= 0) continue;
+    if (!key || key.length > 512) continue;
+    into.set(key, count);
+  }
+}
+
+export interface LoopBlockOptions extends LoopReviseCharge {
+  gateLabel: string;
+  reason: string;
+  maxRounds?: number;
+  maxGateRounds?: number;
+  maxStreakRounds?: number;
+}
+
+/**
+ * The block an unattended loop receives instead of a modal.
+ *
+ * Within the bound it is an invitation to address the concern; past it, it is
+ * not. The final block deliberately offers exactly one next action, because a
+ * block that merely says "no" leaves the agent to invent its own way forward,
+ * and inventing a way forward past a permission gate is the failure mode.
+ */
+export function loopBlockReason(options: LoopBlockOptions): string {
+  const maxRounds = options.maxRounds ?? LOOP_REVISE_ROUNDS;
+  const maxGateRounds = options.maxGateRounds ?? LOOP_GATE_ROUNDS;
+  const head = `${options.gateLabel} needs user approval, and this session is running an unattended /loop, so there is no one to ask: ${options.reason}`;
+  // One number, and it is the binding one. Reporting the per-concern budget
+  // alone let a reworded objection hold it still; reporting the per-gate one
+  // alone would promise rounds the concern budget will not honour.
+  const remaining = Math.min(
+    maxRounds - options.concernSpent,
+    maxGateRounds - options.gateSpent,
+    (options.maxStreakRounds ?? LOOP_STREAK_ROUNDS) - options.streakSpent,
+  );
+  if (remaining <= 0) {
+    return [
+      head,
+      `You have used every revision round this loop gets against it. Stop reshaping the command — further variations of it will not be approved, and searching for one that is would be an end run around the gate.`,
+      "Call loop_wait naming this concern, and record the options in the ledger so a human can answer in one word. If the objective can be advanced another way that does not involve this operation, do that instead.",
+    ].join("\n");
+  }
+  return [
+    head,
+    `You may revise the command to address that specific concern. ${remaining} revision ${plural(remaining, "round")} ${remaining === 1 ? "remains" : "remain"}; after that you must call loop_wait rather than reshaping further.`,
+    "Revise only to satisfy the concern as stated. Do not split, obfuscate, or re-route the command to avoid the gate — that is an end run, not a revision.",
+  ].join("\n");
+}
+
+function plural(count: number, word: string): string {
+  return count === 1 ? word : `${word}s`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hank-warren/pi-auto-permissions",
-  "version": "0.11.1",
+  "version": "0.12.0",
   "description": "Fork of @ogulcancelik/pi-auto-permissions with dialog-answer user evidence: context-aware Bash permissions for Pi with automated guardian review.",
   "type": "module",
   "keywords": [
@@ -46,6 +46,8 @@
     "guardian-transport.ts",
     "openai-codex-transport.ts",
     "subagent-context.ts",
+    "loop-context.ts",
+    "loop-revise-budget.ts",
     "evaluation-log.ts",
     "gates.ts",
     "override-evidence.ts",

package/review.ts

@@ -1,4 +1,5 @@
 import type { SubagentExecutionContext } from "./subagent-context.js";
+import type { LoopExecutionContext } from "./loop-context.js";
 
 export type PermissionDecision = "approve" | "revise" | "ask_user";
 
@@ -13,8 +14,13 @@ export interface CommandReviewRequest {
   cwd: string;
   gate: string;
   group: string;
-  /** Present only in subagent child sessions; runtime facts for the reviewer. */
-  execution?: SubagentExecutionContext;
+  /**
+   * Runtime facts for the reviewer, present only in a session that has some:
+   * a subagent child, a session running an unattended loop, or both at once
+   * (a subagent launched by a looping session is unattended for the same
+   * reason its parent is).
+   */
+  execution?: SubagentExecutionContext | LoopExecutionContext | (SubagentExecutionContext & LoopExecutionContext);
 }
 
 export interface ReviewEvidenceRecord {
@@ -144,6 +150,17 @@ Judge risk by effect scope and reversibility relative to the subagent's own work
 - Lifecycle commands (including with sudo) for containers or services the subagent itself stood up are part of that workflow. Restarting, reconfiguring, or disabling shared host daemons and system services is host-level configuration, not subagent scope.
 - Reserve "ask_user" for effects that escape the subagent's scope: shared or default branches, remote resources it does not own, host-level configuration, production systems, credential or secret access, and data leaving the machine.`;
 
+/**
+ * Appended to the reviewer system prompt only when an unattended pi-loop is
+ * running (detectLoopContext). Like the subagent section it changes how the
+ * reviewer weighs the *absence of a user*, and nothing about what is safe.
+ */
+export const LOOP_CONTEXT_SYSTEM_PROMPT = `UNATTENDED LOOP EXECUTION CONTEXT
+This session is working a long-running objective under an automated loop, with no human watching it. There is no interactive user: an "ask_user" decision does not open a prompt, it returns your concern to the agent as a block. The latest proposed action carries an "execution" object with the loop's runtime facts.
+Decide exactly as you would with a user present. The absence of a user is not authorization, and it is not a reason to approve a medium- or high-risk action that the evidence does not support; it only changes how your decision is delivered.
+The agent is told it may revise the command a bounded number of times to address the concern you state, and must then stop. Write the concern so that a revision is possible where one exists: name the specific property that made the action unsafe, not merely that it was refused.
+An agent that returns with a command differing only cosmetically, split into parts, or re-routed through another tool has not addressed your concern — judge the new command on its own effects and say so again.`;
+
 /**
  * Appended to the reviewer policy prompt unconditionally (so sessions using a
  * customized systemPromptFile still receive it). Explains the user-source