@hank-warren/pi-auto-permissions 0.16.2 → 0.18.0

package/index.ts

@@ -1,13 +1,6 @@
-import { detectLoopContext } from "./loop-context.js";
-import { createReviewQueue } from "./review-queue.js";
-import {
-  LoopReviseBudget,
-  loopBlockReason,
-  type LoopReviseCharge,
-} from "./loop-revise-budget.js";
+import { createReviewLimiter, createReviewQueue } from "./review-queue.js";
 import * as PiCodingAgent from "@earendil-works/pi-coding-agent";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { Type } from "typebox";
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { loadAutoPermissionsConfig, type AutoPermissionsConfig } from "./config.js";
@@ -22,12 +15,11 @@ import {
   classifyPromptChoice,
   expectedDecisionForChoice,
   permissionPromptOptions,
-  shouldOfferStandingApproval,
   type PromptEvaluationUserChoice,
 } from "./evaluation-log.js";
 import type { Gate } from "./gates.js";
-import { classifyCommand, untrustedMatches } from "./classify.js";
-import type { ReviewEvidenceRecord } from "./review.js";
+import { classifyCommand } from "./classify.js";
+import type { PermissionVerdict, ReviewEvidenceRecord } from "./review.js";
 import { promptSelect, setHerdrBlocked } from "./prompt-select.js";
 import { createReviewDisplay } from "./review-display.js";
 import { createSessionOverrides } from "./session-overrides.js";
@@ -75,14 +67,103 @@ function loadTrustedGroups(cwd: string): Set<string> {
 }
 
 function denyReason(gate: Gate): string {
-  return `Blocked by policy: ${gate.label}\n\n${gate.message ?? "This operation is denied by rule."}\n\nThis is a deny rule: it cannot be overridden with request_override, trusted groups, or user approval. Choose a different approach.`;
+  return `Blocked by policy: ${gate.label}\n\n${gate.message ?? "This operation is denied by rule."}\n\nThis is a deny rule: it cannot be overridden by trusted groups or user approval. Choose a different approach.`;
+}
+
+function reviewCancelledResult(): BlockResult {
+  return { block: true, reason: "Auto Permissions review cancelled" };
+}
+
+function withLifecycle(signal: AbortSignal | undefined, lifecycle: AbortSignal): AbortSignal {
+  return signal ? AbortSignal.any([signal, lifecycle]) : lifecycle;
+}
+
+/**
+ * Settle with `promise`, or reject as soon as `signal` aborts. The promise is
+ * left to finish on its own; its outcome is then ignored.
+ */
+function untilAborted<T>(promise: Promise<T>, signal: AbortSignal): Promise<T> {
+  if (signal.aborted) {
+    promise.catch(() => undefined);
+    return Promise.reject(signal.reason);
+  }
+  return new Promise<T>((resolve, reject) => {
+    const onAbort = () => reject(signal.reason);
+    signal.addEventListener("abort", onAbort, { once: true });
+    promise.then(
+      (value) => {
+        signal.removeEventListener("abort", onAbort);
+        resolve(value);
+      },
+      (error) => {
+        signal.removeEventListener("abort", onAbort);
+        reject(error);
+      },
+    );
+  });
+}
+
+/** Aborts when the turn ends or, for a codemode call, when its script does. */
+function callSignalOf(scope: ReviewScope): AbortSignal | undefined {
+  const { ctx, callSignal } = scope;
+  if (!callSignal) return ctx.signal;
+  return ctx.signal ? AbortSignal.any([ctx.signal, callSignal]) : callSignal;
+}
+
+/** How one guardian review ended, before its verdict is applied. */
+type ReviewAttempt =
+  | { kind: "verdict"; verdict: PermissionVerdict; evidenceKeys: string[] }
+  | { kind: "failed"; reason: string; evidenceKeys: string[] }
+  | { kind: "cancelled" };
+
+/**
+ * A verdict whose evidence changed while it waited (the user answered another
+ * command's prompt, a tool result landed) is reviewed again before it is
+ * applied. Bounded so evidence that never settles cannot loop forever: the
+ * last review runs holding the decision slot, so no other prompt can be
+ * answered while it runs, which is the staleness window a lone review has
+ * always had.
+ */
+const MAX_REVIEWS_PER_COMMAND = 3;
+
+/** How many finished call ids are remembered for calls a script left behind. */
+const MAX_FINISHED_CALLS = 1024;
+
+/** Abort reason for an early review replaced by a fresh one for the same call. */
+const SUPERSEDED_REVIEW = "auto-permissions: superseded review";
+
+/** A review started early for a later bash call in the same assistant message. */
+interface SiblingReview {
+  scope: ReviewScope;
+  input: string;
+  gateLabel: string;
+  attempt: Promise<ReviewAttempt>;
+  controller: AbortController;
+}
+
+interface AssistantToolCall {
+  id: string;
+  name: string;
+  arguments: unknown;
 }
 
-function conventionReason(gate: Gate, command: string): string {
-  let reason = `Convention violation: ${gate.label}\n\n${gate.message ?? "Use the configured project tooling."}`;
-  const suggestion = gate.suggest?.(command);
-  if (suggestion && suggestion !== command) reason += `\n\nSuggested command:\n  ${suggestion}`;
-  return `${reason}\n\nIf this is a legitimate edge case, explain why and call \`request_override\` with the exact command.`;
+function isBashTool(name: string): boolean {
+  return name === "bash" || name.endsWith(".bash");
+}
+
+function sameKeys(a: readonly string[], b: readonly string[]): boolean {
+  return a.length === b.length && a.every((key, index) => key === b[index]);
+}
+
+function assistantToolCalls(message: unknown): AssistantToolCall[] {
+  const candidate = message as { role?: unknown; content?: unknown } | undefined;
+  if (candidate?.role !== "assistant" || !Array.isArray(candidate.content)) return [];
+  return candidate.content.flatMap((block) => {
+    const call = block as { type?: unknown; id?: unknown; name?: unknown; arguments?: unknown } | undefined;
+    return call?.type === "toolCall" && typeof call.id === "string" && typeof call.name === "string"
+      ? [{ id: call.id, name: call.name, arguments: call.arguments }]
+      : [];
+  });
 }
 
 export default function autoPermissionsExtension(pi: ExtensionAPI) {
@@ -90,21 +171,66 @@ export default function autoPermissionsExtension(pi: ExtensionAPI) {
   let trustedGroups = new Set<string>();
   let lastConfigError: string | undefined;
   let lastEvaluationLogError: string | undefined;
-  let sessionActive = true;
+  // Guardian calls run in parallel up to config.reviewConcurrency; applying
+  // verdicts and prompting the user stay one command at a time.
+  const reviewSlots = createReviewLimiter();
+  const decisionQueue = createReviewQueue();
+  // Pi runs tool_call handlers for one assistant message's calls one after
+  // another, so the later bash calls' reviews are started early from here.
+  let lastAssistantCalls: AssistantToolCall[] = [];
+  const siblingReviews = new Map<string, SiblingReview>();
+  // One controller per tool call (a codemode script) that has made bash calls,
+  // aborted when Pi reports that call finished: its pending calls can no
+  // longer run, so their reviews and prompts are released.
+  const scriptsEnded = new Map<string, AbortController>();
+  // Calls that already finished, newest last. A script can end before Pi runs
+  // the tool_call hook of a call it fired without awaiting, and with sequential
+  // tool execution that hook can run after the turn is over, so this outlives
+  // the turn. Bounded: only a recently finished call can still have one pending.
+  const finishedCalls = new Set<string>();
+  // Nested call id → the model-issued call it descends from, so a call made
+  // several levels down still names the script whose SCRIPT record it shares.
+  const scriptRoots = new Map<string, string>();
+
+  function rememberFinished(toolCallId: string): void {
+    finishedCalls.delete(toolCallId);
+    finishedCalls.add(toolCallId);
+    if (finishedCalls.size > MAX_FINISHED_CALLS) {
+      finishedCalls.delete(finishedCalls.values().next().value!);
+    }
+  }
+
+  function callEndedSignal(toolCallId: string): AbortSignal {
+    if (finishedCalls.has(toolCallId)) return AbortSignal.abort();
+    let controller = scriptsEnded.get(toolCallId);
+    if (!controller) {
+      controller = new AbortController();
+      scriptsEnded.set(toolCallId, controller);
+    }
+    return controller.signal;
+  }
+
   /**
-   * 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.
+   * Aborts when the call that made this one ends, or the script at the top of
+   * the chain does: a tool in between may keep awaiting this call after its
+   * script has gone.
    */
-  const loopReviseBudget = new LoopReviseBudget();
-  /** The loop these counts belong to, so a new loop starts with a clean budget. */
-  let loopReviseBudgetLoopId: string | undefined;
-  const guardianReviewQueue = createReviewQueue();
-  const display = createReviewDisplay(pi, { isSessionActive: () => sessionActive });
-  const reviewer = createGuardianReviewer({ isSessionActive: () => sessionActive, overrides });
+  function scriptEndedSignal(parentToolCallId: string, scriptToolCallId: string): AbortSignal {
+    const parent = callEndedSignal(parentToolCallId);
+    return scriptToolCallId === parentToolCallId
+      ? parent
+      : AbortSignal.any([parent, callEndedSignal(scriptToolCallId)]);
+  }
+
+  function endScripts(): void {
+    for (const controller of scriptsEnded.values()) controller.abort();
+    scriptsEnded.clear();
+  }
+  // The session is active exactly while the reviewer lifecycle is unaborted:
+  // session_shutdown aborts it, session_start synchronously aborts and replaces
+  // it, and nothing else touches it.
+  const reviewer = createGuardianReviewer({ overrides });
+  const display = createReviewDisplay({ isSessionActive: () => !reviewer.lifecycleSignal.aborted });
 
   /**
    * Record a non-approved outcome: a `pi.events` emit (the PermissionDenied
@@ -182,13 +308,8 @@ export default function autoPermissionsExtension(pi: ExtensionAPI) {
    * if that package is installed. Say so once per session instead of letting the
    * first guarded command fail with a bare "review model not found".
    */
-  function warnAboutMissingReviewerProvider(ctx: ExtensionContext): void {
-    let provider: string | undefined;
-    try {
-      provider = currentConfig(ctx).reviewer?.provider;
-    } catch {
-      return; // The config error was already reported by currentConfig().
-    }
+  function warnAboutMissingReviewerProvider(ctx: ExtensionContext, config: AutoPermissionsConfig): void {
+    const provider = config.reviewer?.provider;
     if (!provider || ctx.modelRegistry.getProvider(provider)) return;
 
     const message =
@@ -199,7 +320,24 @@ export default function autoPermissionsExtension(pi: ExtensionAPI) {
   }
 
   function reviewCancelled(signal: AbortSignal | undefined): boolean {
-    return !sessionActive || signal?.aborted === true;
+    return signal?.aborted === true;
+  }
+
+  /**
+   * A cancelled turn resets the reviewer lineage. A codemode script ending
+   * does not: the reviewer conversation is intact, and dropping it would make
+   * the next reviews start cold.
+   */
+  function discardLineageIfTurnCancelled(scope: ReviewScope): void {
+    if (reviewCancelled(scope.ctx.signal)) reviewer.discardLineage();
+  }
+
+  function cancelledAfterAwait(scope: ReviewScope, lifecycleSignal: AbortSignal): BlockResult | undefined {
+    if (reviewer.isStale(lifecycleSignal)) return reviewCancelledResult();
+    if (!reviewCancelled(callSignalOf(scope))) return undefined;
+    discardLineageIfTurnCancelled(scope);
+    display.clear(scope);
+    return reviewCancelledResult();
   }
 
   function logPromptEvaluation(
@@ -243,33 +381,6 @@ export default function autoPermissionsExtension(pi: ExtensionAPI) {
     }
   }
 
-  /**
-   * 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(
     scope: ReviewScope,
     detail: string,
@@ -277,12 +388,12 @@ export default function autoPermissionsExtension(pi: ExtensionAPI) {
     decisionSource: "guardian" | "review_failure",
   ): Promise<BlockResult | undefined> {
     const { ctx, config, gate, command } = scope;
-    const signal = ctx.signal;
+    const signal = callSignalOf(scope);
     const lifecycleStale = () => reviewer.isStale(lifecycleSignal);
-    const promptSignal = signal ? AbortSignal.any([signal, lifecycleSignal]) : lifecycleSignal;
-    const cancelled = (): BlockResult => ({ block: true, reason: "Auto Permissions review cancelled" });
+    const promptSignal = withLifecycle(signal, lifecycleSignal);
+    const cancelled = reviewCancelledResult;
     if (lifecycleStale() || reviewCancelled(signal)) {
-      if (!lifecycleStale()) reviewer.discardLineage();
+      if (!lifecycleStale()) discardLineageIfTurnCancelled(scope);
       return cancelled();
     }
     display.show(scope, "ask_user", detail);
@@ -290,7 +401,7 @@ export default function autoPermissionsExtension(pi: ExtensionAPI) {
       return settle(scope, {
         display: "blocked",
         verdict: "block",
-        source: decisionSource === "guardian" ? "guardian" : "review_failure",
+        source: decisionSource,
         reason: detail,
         block: `${gate.label} requires user approval: ${detail}\nThis session has no interactive user to ask. Prefer an approach that avoids the gated operation, or report this blocker in your final output instead of retrying the same command.`,
       });
@@ -305,32 +416,24 @@ export default function autoPermissionsExtension(pi: ExtensionAPI) {
           pi,
           ctx,
           `${gate.label} — Auto Permissions needs approval\n\n${detail}\n\n${command}`,
-          permissionPromptOptions(
-            config.evaluationLog.enabled,
-            shouldOfferStandingApproval(decisionSource, config.standingApprovals.enabled),
-          ),
+          permissionPromptOptions(config.evaluationLog.enabled),
           promptSignal,
-          { allowComment: true },
         );
       } catch (error) {
         if (!lifecycleStale() && !reviewCancelled(signal)) throw error;
-        if (!lifecycleStale()) reviewer.discardLineage();
-        return cancelled();
-      }
-      if (lifecycleStale()) return cancelled();
-      if (reviewCancelled(signal)) {
-        reviewer.discardLineage();
-        if (sessionActive) display.clear(scope);
+        if (!lifecycleStale()) discardLineageIfTurnCancelled(scope);
         return cancelled();
       }
+      const cancelledResult = cancelledAfterAwait(scope, lifecycleSignal);
+      if (cancelledResult) return cancelledResult;
       const classification = classifyPromptChoice(choice);
       // Feed the user's decision back to the guardian as session-scoped
       // user-source evidence. review_failure prompts are excluded: their
       // "concern" is an infrastructure error, not a guardian judgment.
       if (decisionSource === "guardian" && classification) {
-        overrides.recordPromptDecision(scope, classification, detail, reviewer.lastEvidenceKey);
+        overrides.recordPromptDecision(gate, command, classification, detail, reviewer.lastEvidenceKey);
       }
-      if (config.evaluationLog.enabled && classification?.userChoice) {
+      if (classification?.userChoice) {
         logPromptEvaluation(scope, detail, evaluationContext, decisionSource, classification.userChoice);
       }
       if (classification?.allowsExecution) {
@@ -349,11 +452,261 @@ export default function autoPermissionsExtension(pi: ExtensionAPI) {
     }
   }
 
+  function evidenceKeys(scope: ReviewScope): string[] {
+    return reviewer.collectEvidence(scope).map((record) => record.key);
+  }
+
+  /**
+   * One guardian review, run as soon as a review slot is free. Never applies
+   * the verdict: that waits for the decision slot in `decide`.
+   *
+   * `abandon` is set for a sibling review started early. Aborting it drops the
+   * verdict; its row is cleared too, unless the abort reason is
+   * `SUPERSEDED_REVIEW`, meaning a fresh review for the same call owns the row.
+   */
+  async function runReview(
+    scope: ReviewScope,
+    input: Record<string, unknown>,
+    lifecycleSignal: AbortSignal,
+    abandon?: AbortSignal,
+  ): Promise<ReviewAttempt> {
+    const { ctx, config } = scope;
+    const lifecycleStale = () => reviewer.isStale(lifecycleSignal);
+    const abandoned = () => abandon?.aborted === true;
+    const drop = (): ReviewAttempt => {
+      if (!lifecycleStale() && abandon?.reason !== SUPERSEDED_REVIEW) display.clear(scope);
+      return { kind: "cancelled" };
+    };
+    const callSignal = callSignalOf(scope);
+    const slotSignal = AbortSignal.any([
+      lifecycleSignal,
+      ...(callSignal ? [callSignal] : []),
+      ...(abandon ? [abandon] : []),
+    ]);
+    if (reviewSlots.wouldWait(config.reviewConcurrency)) display.show(scope, "queued");
+    let releaseSlot: () => void;
+    try {
+      releaseSlot = await reviewSlots.acquire(config.reviewConcurrency, slotSignal);
+    } catch {
+      return drop();
+    }
+    try {
+      if (lifecycleStale() || reviewCancelled(callSignal) || abandoned()) return drop();
+      display.show(scope, "waiting");
+      // Collected synchronously right before the review collects the same
+      // stream, so the keys describe exactly what the guardian judged.
+      const keys = evidenceKeys(scope);
+      let attempt: ReviewAttempt;
+      try {
+        // The reviewer already follows the turn signal. A codemode call whose
+        // script ended, or an early review nobody will take, cancels its
+        // request and gives its slot back at once.
+        const stop = scope.callSignal && abandon
+          ? AbortSignal.any([scope.callSignal, abandon])
+          : scope.callSignal ?? abandon;
+        const review = reviewer.review(scope, input, stop);
+        const verdict = await (stop ? untilAborted(review, stop) : review);
+        if (!lifecycleStale() && reviewCancelled(ctx.signal)) reviewer.discardLineage();
+        attempt = { kind: "verdict", verdict, evidenceKeys: keys };
+      } catch (error) {
+        attempt = { kind: "failed", reason: error instanceof Error ? error.message : String(error), evidenceKeys: keys };
+      }
+      if (lifecycleStale() || reviewCancelled(callSignal) || abandoned()) return drop();
+      // An early sibling review now waits for Pi to reach its call.
+      if (abandon) display.show(scope, "queued");
+      return attempt;
+    } finally {
+      releaseSlot();
+    }
+  }
+
+  /** Apply one settled review. Runs holding the decision slot. */
+  function applyReview(
+    scope: ReviewScope,
+    outcome: Exclude<ReviewAttempt, { kind: "cancelled" }>,
+    lifecycleSignal: AbortSignal,
+  ): Promise<BlockResult | undefined> | BlockResult | undefined {
+    if (outcome.kind === "failed") {
+      return askUser(scope, `Automatic review failed: ${outcome.reason}`, lifecycleSignal, "review_failure");
+    }
+    const { verdict } = outcome;
+    if (verdict.decision === "approve") {
+      return settle(scope, { display: "approved", reason: verdict.reason });
+    }
+    if (verdict.decision === "revise") {
+      return settle(scope, {
+        display: "revise",
+        verdict: "revise",
+        source: "guardian",
+        reason: verdict.reason,
+        block: `Auto Permissions requested revision: ${verdict.reason}\nRevise the command and try again.`,
+      });
+    }
+    return askUser(scope, verdict.reason, lifecycleSignal, "guardian");
+  }
+
+  /**
+   * Wait for a review, then apply it in the decision slot, one command at a
+   * time. The slot spans any approval prompt, so a verdict reached while the
+   * user was answering another command's prompt is checked against the
+   * evidence that answer added, and reviewed again when it changed. The last
+   * review `MAX_REVIEWS_PER_COMMAND` allows runs inside the slot.
+   */
+  async function decide(
+    scope: ReviewScope,
+    input: Record<string, unknown>,
+    lifecycleSignal: AbortSignal,
+    firstAttempt: Promise<ReviewAttempt>,
+  ): Promise<BlockResult | undefined> {
+    const lifecycleStale = () => reviewer.isStale(lifecycleSignal);
+    const callSignal = callSignalOf(scope);
+    // Same composite the ask path builds, so Esc, a reviewer-lifecycle reset
+    // and the end of a codemode script all release a waiting command instead
+    // of stranding it behind a prompt it is no longer waiting for.
+    const queueSignal = withLifecycle(callSignal, lifecycleSignal);
+    let attempt = firstAttempt;
+    for (let reviews = 1; ; reviews += 1) {
+      const outcome = await attempt;
+      if (outcome.kind === "cancelled") return reviewCancelledResult();
+      if (decisionQueue.busy) display.show(scope, "queued");
+      let releaseDecision: () => void;
+      try {
+        releaseDecision = await decisionQueue.acquire(queueSignal);
+      } catch {
+        if (!lifecycleStale()) display.clear(scope);
+        return reviewCancelledResult();
+      }
+      try {
+        if (lifecycleStale() || reviewCancelled(callSignal)) {
+          if (!lifecycleStale()) display.clear(scope);
+          return reviewCancelledResult();
+        }
+        if (sameKeys(outcome.evidenceKeys, evidenceKeys(scope))) {
+          return await applyReview(scope, outcome, lifecycleSignal);
+        }
+        if (reviews + 1 < MAX_REVIEWS_PER_COMMAND) {
+          attempt = runReview(scope, input, lifecycleSignal);
+          continue;
+        }
+        const last = await runReview(scope, input, lifecycleSignal);
+        if (last.kind === "cancelled") return reviewCancelledResult();
+        return await applyReview(scope, last, lifecycleSignal);
+      } finally {
+        releaseDecision();
+      }
+    }
+  }
+
+  /**
+   * Start reviews for the guarded bash calls that follow `toolCallId` in the
+   * assistant message that issued it. Pi calls tool_call handlers for one
+   * message's calls one at a time, so without this their reviews could never
+   * overlap. Each result is taken by the call's own handler, and only when the
+   * input it finally receives is exactly the input that was reviewed.
+   */
+  function startSiblingReviews(
+    toolCallId: string,
+    ctx: ExtensionContext,
+    config: AutoPermissionsConfig,
+    lifecycleSignal: AbortSignal,
+  ): void {
+    if (config.reviewConcurrency <= 1) return;
+    const index = lastAssistantCalls.findIndex((call) => call.id === toolCallId);
+    if (index < 0) return;
+    for (const call of lastAssistantCalls.slice(index + 1)) {
+      if (!isBashTool(call.name) || siblingReviews.has(call.id)) continue;
+      const input = call.arguments as Record<string, unknown> | undefined;
+      const command = input?.command;
+      if (typeof command !== "string") continue;
+      const classified = classifyCommand(command, config, trustedGroups);
+      if (classified.kind !== "review") continue;
+      const controller = new AbortController();
+      const scope: ReviewScope = {
+        ctx,
+        config,
+        gate: classified.gate,
+        command,
+        target: { toolName: call.name, toolCallId: call.id },
+      };
+      siblingReviews.set(call.id, {
+        scope,
+        input: JSON.stringify(input),
+        gateLabel: classified.gate.label,
+        attempt: runReview(scope, input!, lifecycleSignal, controller.signal),
+        controller,
+      });
+    }
+  }
+
+  /**
+   * The early review of this call, when it reviewed exactly this input under
+   * this gate. `gateLabel` is undefined when the call no longer needs review
+   * (another handler changed it), in which case the early review is dropped.
+   */
+  function takeSiblingReview(
+    toolCallId: string,
+    input: unknown,
+    gateLabel: string | undefined,
+  ): Promise<ReviewAttempt> | undefined {
+    const sibling = siblingReviews.get(toolCallId);
+    if (!sibling) return undefined;
+    siblingReviews.delete(toolCallId);
+    if (gateLabel === undefined) {
+      sibling.controller.abort();
+      display.clear(sibling.scope);
+      return undefined;
+    }
+    if (sibling.input === JSON.stringify(input) && sibling.gateLabel === gateLabel) return sibling.attempt;
+    // Changed after it was reviewed early: the fresh review owns the row.
+    sibling.controller.abort(SUPERSEDED_REVIEW);
+    return undefined;
+  }
+
+  /** Drop early reviews whose calls never reached this extension. */
+  function abandonSiblingReviews(): void {
+    for (const sibling of siblingReviews.values()) {
+      sibling.controller.abort();
+      display.clear(sibling.scope);
+    }
+    siblingReviews.clear();
+  }
+
+  pi.on("message_end", (event) => {
+    const calls = assistantToolCalls((event as { message?: unknown }).message);
+    if (calls.length > 0) lastAssistantCalls = calls;
+  });
+
+  pi.on("turn_end", () => {
+    lastAssistantCalls = [];
+    abandonSiblingReviews();
+    endScripts();
+    scriptRoots.clear();
+  });
+
+  pi.on("tool_execution_start", (event) => {
+    const { toolCallId, parentToolCallId } = event as { toolCallId?: unknown; parentToolCallId?: unknown };
+    if (typeof toolCallId !== "string") return;
+    // A provider may reuse a call id in a later turn; that call is live again.
+    finishedCalls.delete(toolCallId);
+    if (typeof parentToolCallId === "string") {
+      scriptRoots.set(toolCallId, scriptRoots.get(parentToolCallId) ?? parentToolCallId);
+    }
+  });
+
+  pi.on("tool_execution_end", (event) => {
+    const { toolCallId } = event as { toolCallId?: unknown };
+    if (typeof toolCallId !== "string") return;
+    rememberFinished(toolCallId);
+    const controller = scriptsEnded.get(toolCallId);
+    if (!controller) return;
+    scriptsEnded.delete(toolCallId);
+    controller.abort();
+  });
+
   pi.on("tool_call", async (event, ctx) => {
-    if (event.toolName !== "bash" && !event.toolName.endsWith(".bash")) return;
+    if (!isBashTool(event.toolName)) return;
     const command = (event.input as { command: string }).command;
     const lifecycleSignal = reviewer.lifecycleSignal;
-    const lifecycleStale = () => reviewer.isStale(lifecycleSignal);
 
     let config: AutoPermissionsConfig;
     try {
@@ -363,11 +716,33 @@ export default function autoPermissionsExtension(pi: ExtensionAPI) {
       return { block: true, reason: error instanceof Error ? error.message : String(error) };
     }
     if (!config.enabled) return;
-    const target: ReviewTarget = { toolName: event.toolName, toolCallId: event.toolCallId };
-    const classified = classifyCommand(command, config, trustedGroups, overrides.allowedConventionCommands);
+    const parentToolCallId = (event as { parentToolCallId?: string }).parentToolCallId;
+    if (!parentToolCallId) startSiblingReviews(event.toolCallId, ctx, config, lifecycleSignal);
+    const scriptToolCallId = parentToolCallId ? scriptRoots.get(parentToolCallId) ?? parentToolCallId : undefined;
+    const target: ReviewTarget = {
+      toolName: event.toolName,
+      toolCallId: event.toolCallId,
+      ...(scriptToolCallId ? { scriptToolCallId } : {}),
+    };
+    const input = event.input as Record<string, unknown>;
+    const classified = classifyCommand(command, config, trustedGroups);
+    const early = takeSiblingReview(
+      event.toolCallId,
+      input,
+      classified.kind === "review" ? classified.gate.label : undefined,
+    );
     if (classified.kind === "pass") return;
     const gate = classified.gate;
-    const scope: ReviewScope = { ctx, config, gate, command, target };
+    const scope: ReviewScope = {
+      ctx,
+      config,
+      gate,
+      command,
+      target,
+      ...(parentToolCallId && scriptToolCallId
+        ? { callSignal: scriptEndedSignal(parentToolCallId, scriptToolCallId) }
+        : {}),
+    };
     if (classified.kind === "deny") {
       return settle(scope, {
         verdict: "block",
@@ -376,236 +751,39 @@ export default function autoPermissionsExtension(pi: ExtensionAPI) {
         block: denyReason(gate),
       });
     }
-    if (classified.kind === "convention") {
-      if (ctx.hasUI) overrides.activateOverrideTool();
-      return settle(scope, {
-        verdict: "block",
-        source: "convention",
-        reason: gate.message ?? gate.label,
-        block: conventionReason(gate, command),
-      });
-    }
 
-    // Show the queued row *before* waiting, and only when there is actually
-    // something to wait for: the critical section spans the human prompt, so a
-    // second guarded command in the same turn can sit here for as long as it
-    // takes someone to answer. Rendering nothing for that whole time reads as a
-    // hang. A lone review never flashes this, because the queue is idle.
-    if (guardianReviewQueue.busy) {
-      display.show(scope, "queued");
-    }
-    // Same composite the ask path builds, so Esc and a reviewer-lifecycle reset
-    // both release a queued command instead of stranding it behind a review it
-    // is no longer waiting for.
-    const queueSignal = ctx.signal ? AbortSignal.any([ctx.signal, lifecycleSignal]) : lifecycleSignal;
-    let releaseReviewSlot: () => void;
-    try {
-      releaseReviewSlot = await guardianReviewQueue.acquire(queueSignal);
-    } catch {
-      return { block: true, reason: "Auto Permissions review cancelled" };
-    }
-    try {
-      if (lifecycleStale() || reviewCancelled(ctx.signal)) {
-        return { block: true, reason: "Auto Permissions review cancelled" };
-      }
-      const signal = ctx.signal;
-      display.show(scope, "waiting");
-      try {
-        const verdict = await reviewer.review(scope, event.input as Record<string, unknown>);
-        if (lifecycleStale()) {
-          return { block: true, reason: "Auto Permissions review cancelled" };
-        }
-        if (reviewCancelled(signal)) {
-          reviewer.discardLineage();
-          if (sessionActive) display.clear(scope);
-          return { block: true, reason: "Auto Permissions review cancelled" };
-        }
-        if (verdict.decision === "approve") {
-          const approved = settle(scope, { display: "approved", reason: verdict.reason });
-          // 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 approved;
-        }
-        // 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);
-          return settle(scope, {
-            display: verdict.decision === "revise" ? "revise" : "blocked",
-            verdict: verdict.decision === "revise" ? "revise" : "block",
-            source: "loop",
-            reason: verdict.reason,
-            block: loopBlockReason({
-              gateLabel: gate.label,
-              reason: verdict.reason,
-              decision: verdict.decision,
-              ...charge,
-            }),
-          });
-        }
-        if (verdict.decision === "revise") {
-          return settle(scope, {
-            display: "revise",
-            verdict: "revise",
-            source: "guardian",
-            reason: verdict.reason,
-            block: `Auto Permissions requested revision: ${verdict.reason}\nRevise the command and try again.`,
-          });
-        }
-        return askUser(scope, verdict.reason, lifecycleSignal, "guardian");
-      } catch (error) {
-        if (lifecycleStale() || reviewCancelled(signal)) {
-          if (!lifecycleStale() && sessionActive) display.clear(scope);
-          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()) {
-          return settle(scope, {
-            display: "blocked",
-            verdict: "block",
-            source: "review_failure",
-            reason,
-            block: `${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(scope, `Automatic review failed: ${reason}`, lifecycleSignal, "review_failure");
-      }
-    } finally {
-      releaseReviewSlot();
-    }
+    return decide(scope, input, lifecycleSignal, early ?? runReview(scope, input, lifecycleSignal));
   });
 
-  pi.registerTool({
-    name: "request_override",
-    executionMode: "sequential",
-    label: "Request Override",
-    description: "Request a one-session exception for a command that violates a tooling convention. This cannot bypass guarded commands or deny rules.",
-    parameters: Type.Object({
-      command: Type.String({ description: "Exact command to allow" }),
-      reason: Type.String({ description: "Why the convention does not apply" }),
-    }),
-    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
-      let config: AutoPermissionsConfig;
-      try {
-        config = currentConfig(ctx);
-      } catch (error) {
-        return {
-          content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }],
-          details: { success: false },
-        };
-      }
-      const matches = untrustedMatches(params.command, config, trustedGroups);
-      if (matches.some((gate) => gate.level === "deny")) {
-        return {
-          content: [{ type: "text", text: "The command matches a deny rule, which is a hard policy boundary. Deny rules cannot be bypassed with request_override; choose a different approach." }],
-          details: { success: false },
-        };
-      }
-      if (!matches.length || matches.some((gate) => gate.level === "guarded")) {
-        return {
-          content: [{ type: "text", text: "The command is not a convention violation. Guarded commands cannot be bypassed with request_override." }],
-          details: { success: false },
-        };
-      }
-      const gate = matches[0];
-      const lifecycleSignal = reviewer.lifecycleSignal;
-      const lifecycleStale = () => reviewer.isStale(lifecycleSignal);
-      const promptSignal = signal ? AbortSignal.any([signal, lifecycleSignal]) : lifecycleSignal;
-      const cancelled = () => ({
-        content: [{ type: "text" as const, text: "Override cancelled." }],
-        details: { success: false },
-      });
-      if (lifecycleStale() || reviewCancelled(signal)) return cancelled();
-      if (!ctx.hasUI) {
-        return {
-          content: [{ type: "text", text: "Cannot request an override without an interactive UI." }],
-          details: { success: false },
-        };
-      }
-
-      setHerdrBlocked(pi, true, gate.label);
-      try {
-        let choice: string | undefined;
-        try {
-          // The override prompt never had Tab-to-comment (the monkey patch only
-          // enabled it on titles matching /needs approval/i), so keep parity.
-          choice = await promptSelect(
-            pi,
-            ctx,
-            `Convention override: ${gate.label}\n\n${params.reason}\n\n${params.command}`,
-            ["Allow for this session", "Keep blocked"],
-            promptSignal,
-            { allowComment: false },
-          );
-        } catch (error) {
-          if (!lifecycleStale() && !reviewCancelled(signal)) throw error;
-          return cancelled();
-        }
-        if (lifecycleStale() || reviewCancelled(signal)) return cancelled();
-        if (choice === "Allow for this session") {
-          overrides.allowConvention(params.command);
-          return {
-            content: [{ type: "text", text: `Override granted for this session:\n  ${params.command}` }],
-            details: { success: true, command: params.command },
-          };
-        }
-        return {
-          content: [{ type: "text", text: gate.message ?? "Use the configured project tooling." }],
-          details: { success: false },
-        };
-      } finally {
-        if (!lifecycleStale()) setHerdrBlocked(pi, false);
-      }
-    },
-  });
-
-  // The override schema is useful only after a convention denial has named an
-  // exact command. It is kept registered for replay and narrowed out of the
-  // active set at session_start — never here, because Pi refuses action methods
-  // during extension loading.
-
   registerSettingsCommand(pi, { overrides, reviewer });
 
+  function resetCallTracking(): void {
+    lastAssistantCalls = [];
+    abandonSiblingReviews();
+    endScripts();
+    finishedCalls.clear();
+    scriptRoots.clear();
+  }
+
   pi.on("session_shutdown", async (_event, ctx) => {
-    sessionActive = false;
-    reviewer.abortLifecycle();
-    reviewer.discardLineage();
+    resetCallTracking();
+    reviewer.endSession();
     display.shutdown(ctx);
     setHerdrBlocked(pi, false);
   });
 
   pi.on("session_start", async (_event, ctx) => {
-    overrides.resetForSession();
-    warnAboutMissingReviewerProvider(ctx);
-
-    reviewer.abortLifecycle();
-    reviewer.discardLineage();
-    reviewer.resetLifecycle();
-    sessionActive = true;
-    overrides.restore(ctx.sessionManager.getBranch());
-    // 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;
-    trustedGroups = ctx.isProjectTrusted() ? loadTrustedGroups(ctx.cwd) : new Set();
-    // Snapshot the trust baseline at session start: remotes configured now are
-    // inside the boundary, anything added or repointed later is not. Re-capture
-    // on every session_start (resume, branch switch) so the baseline follows
-    // the session the reviews belong to; the fingerprint covers the change.
-    reviewer.captureEnvironment(ctx.cwd);
+    let config: AutoPermissionsConfig | undefined;
     try {
-      const config = currentConfig(ctx);
-      overrides.loadStanding(config, ctx);
-      if (config.ui.placement === "toolRow") display.registerGuardedBash(ctx);
+      config = currentConfig(ctx);
     } catch {
-      // The first bash call will fail closed with the configuration error.
+      // Reported by currentConfig; the first bash call fails closed.
     }
+    if (config) warnAboutMissingReviewerProvider(ctx, config);
+
+    resetCallTracking();
+    reviewer.startSession(ctx.cwd);
+    overrides.restore(ctx.sessionManager.getBranch());
+    trustedGroups = ctx.isProjectTrusted() ? loadTrustedGroups(ctx.cwd) : new Set();
   });
 }