@erichll/pi-auto-review 0.14.0 → 0.15.1

package/CHANGELOG.md

@@ -1,5 +1,66 @@
 # Changelog
 
+## 0.15.1 - 2026-08-31
+
+- Adapt the policy audit to `@gotgenes/pi-permission-system` v28.0.0. Ask
+  decisions made by a registered authorizer chain link — including
+  pi-auto-review's own model review — now broadcast `authorizer_allowed` /
+  `authorizer_denied` instead of `user_approved` / `user_denied`. The audit
+  whitelist records both new values verbatim instead of collapsing them into
+  `unknown`, and approval sources surface them under their own name.
+- Keep suggestion evidence strictly human/session-based: `authorizer_allowed`
+  deliberately does not join `SUCCESS_RESOLUTIONS`, because counting the
+  extension's own machine review as evidence would create a feedback loop
+  (model review allows → evidence → suggested auto-allow rule → future review
+  bypassed). Authorizer-resolved rows still count as "reviewed" for the
+  display-only low-risk candidate list so those surfaces stay visible.
+- Bump the `@gotgenes/pi-permission-system` peer range to `^28.0.0`.
+
+## 0.15.0 - 2026-08-29
+
+- Fix a deterministic reviewer-unavailable denial for large CJK tool inputs.
+  The reviewer input estimator counted one token per UTF-8 byte, tripling the
+  estimate for CJK text, so multi-kilobyte Chinese payloads (e.g. a long plan
+  document submitted through a tool call) synchronously failed the
+  `reviewer_input_budget_exceeded` preflight before the reviewer model was
+  ever called, and the request was denied as "Automatic review is
+  unavailable." CJK code points now estimate at one token each and remaining
+  code points at their UTF-8 byte length over three (estimator
+  `conservative:cjk-aware`).
+- Record the denial when a reviewer-unavailable review fails closed, so
+  `/auto-review-approve` — the recovery command that verdict recommends —
+  actually has a matching denial to approve. Previously the recommendation
+  was dead text for this failure class.
+- Let an explicit human override (`/auto-review-approve` trusted exact retry)
+  bypass the reviewer input-budget preflight failure. A sizing estimate is
+  not a safety verdict and must not veto an already-authorized retry; the
+  review proceeds with truncated evidence.
+- Show "waiting for you" in the review widget while a `ctx.ui` prompt blocks
+  the session during an active review (pi >= 0.84.4 `ui_prompt_start` /
+  `ui_prompt_end`). The widget previously kept claiming "Waiting for
+  <model>…" while pi was actually waiting on the user (permission dialog,
+  `/review-denials`, break-glass challenge). Completed outcome summaries and
+  sessions without a live widget are unaffected.
+- Fix `/auto-review-approve` and `/auto-review-break-glass` never applying in
+  real TUI sessions. The exact-match request hash included `toolCallId`, but a
+  retry is always a brand-new model tool call with a fresh tool call ID, so
+  the authorization could never match the retried request. The hash now
+  excludes both retry-minted identifiers (`id` was already excluded).
+- Fix break-glass authorization being discarded on every retry. The stored
+  authorization was bound to the denial-time turn scope, but the command flow
+  appends a user message (`pi.sendUserMessage`) before the agent retries, so
+  the retry always lands in a later turn whose scope differs. Consumption now
+  binds on session and request hash plus the confirmation TTL instead of the
+  turn scope. The non-critical approve path already behaved this way.
+- Reset the turn circuit breaker when a break-glass allow is consumed, so the
+  human-authorized scope can continue instead of staying blocked for the rest
+  of the turn. Fresh repeated denials still trip it again after three
+  consecutive failures.
+- Clean up break-glass authorization bookkeeping: an expired authorization
+  that was never consumed no longer blocks re-approving the same action, and
+  a fresh denial of an action whose approval was already consumed re-arms
+  one-shot approval (one approval per denial).
+
 ## 0.14.0 - 2026-08-28
 
 - Upgrade `/auto-review-policy-audit` from redacted statistics to an

package/README.md

@@ -192,7 +192,9 @@ The host-generated override:
 - expires after 60 seconds and is consumed once;
 - remains separate from untrusted user/tool evidence;
 - still goes through deterministic hard denies and model review; and
-- cannot be reissued for the same request semantics in that session.
+- cannot be reissued while a previous authorization for it is pending, or
+  again after consumption until the same action is denied afresh (one approval
+  per denial).
 
 It is authorization evidence, not a direct allow.
 
@@ -202,11 +204,15 @@ same session made in the last five minutes. After showing the rationale,
 surface, cwd, command or target summary, and request-hash fingerprint, it
 requires an explicit confirmation and a random `BREAK-GLASS <CODE>` phrase
 within 60 seconds. Successful confirmation creates a 60-second, one-use
-authorization bound to the complete request hash, session, scope, and original
-request ID. The exact retry reruns local hard-deny checks, then allows directly
-without calling the reviewer and, for sandbox adapters, still issues the normal
-one-shot grant. Break glass does not reset circuit-breaker history and can be
-disabled in trusted or project configuration with `breakGlassEnabled: false`.
+authorization bound to the complete request hash, session, and original
+request ID. The request hash deliberately excludes the per-attempt `id` and
+`toolCallId` fields: the exact retry is a brand-new model tool call issued in
+a later turn, so retry-minted identifiers cannot participate in the match.
+The exact retry reruns local hard-deny checks, then allows directly without
+calling the reviewer and, for sandbox adapters, still issues the normal
+one-shot grant. A break-glass allow resets the turn circuit breaker (a human
+re-authorized the scope), and break glass can be disabled in trusted or
+project configuration with `breakGlassEnabled: false`.
 
 ## Boundary broker API
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@erichll/pi-auto-review",
-  "version": "0.14.0",
+  "version": "0.15.1",
   "description": "Fail-closed, model-backed approval broker for Pi: deterministically hard-denies dangerous operations, reviews dangerous boundaries with a reviewer model, and issues one-shot expiring grants that OS sandbox adapters must consume before retrying.",
   "type": "module",
   "license": "MIT",
@@ -47,14 +47,14 @@
     "test": "node --disable-warning=ExperimentalWarning --experimental-loader ./test/typescript-loader.mjs --test test/*.test.ts"
   },
   "peerDependencies": {
-    "@earendil-works/pi-ai": "^0.84.1",
-    "@earendil-works/pi-coding-agent": "^0.84.1",
-    "@gotgenes/pi-permission-system": "^27.0.0"
+    "@earendil-works/pi-ai": "^0.84.4",
+    "@earendil-works/pi-coding-agent": "^0.84.4",
+    "@gotgenes/pi-permission-system": "^28.0.0"
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "^0.84.1",
-    "@earendil-works/pi-coding-agent": "^0.84.1",
-    "@gotgenes/pi-permission-system": "27.1.0",
+    "@earendil-works/pi-ai": "^0.84.4",
+    "@earendil-works/pi-coding-agent": "^0.84.4",
+    "@gotgenes/pi-permission-system": "28.0.0",
     "@types/node": "^26.2.0",
     "typescript": "^6.0.3"
   }

package/src/broker/broker.ts

@@ -99,6 +99,9 @@ export class BoundaryApprovalBroker {
       ? this.#denials.consumeCritical(request, context)
       : undefined;
     if (breakGlass) {
+      // A human explicitly authorized this action; treat the scope as healthy
+      // again, exactly like a reviewer allow would.
+      this.#breaker.record(context.scopeKey, false);
       const review: BoundaryReview = {
         outcome: "allow",
         riskLevel: "critical",
@@ -166,9 +169,15 @@ export class BoundaryApprovalBroker {
         };
       }
       const breaker = this.#breaker.record(context.scopeKey, true);
+      // Record the failure denial so /auto-review-approve — the exact recovery
+      // command this verdict recommends — has a matching denial to approve.
+      // Without this the override path was unreachable for reviewer
+      // unavailability, and the recovery advice was dead text.
+      const review = { ...FAILURE_REVIEW, rationale: reason };
+      this.#denials.record(request, context, review);
       return {
         kind: "deny",
-        review: { ...FAILURE_REVIEW, rationale: reason },
+        review,
         circuitBreakerTripped: breaker.tripped,
         denialSource: "reviewer",
         recoveryCommand: "/auto-review-approve",

package/src/broker/grants.ts

@@ -1,6 +1,9 @@
 import { createHash, randomUUID } from "node:crypto";
 import type { BoundaryGrant, BoundaryRequest } from "./types.ts";
 
+// Retry stability: a retried action mints a fresh requestId and toolCallId (the
+// model issues a new tool call), so neither may take part in the exact-match
+// hash. Everything else must be identical for an authorization to apply.
 function stableValue(value: unknown): unknown {
   if (Array.isArray(value)) return value.map(stableValue);
   if (!value || typeof value !== "object") return value;
@@ -25,7 +28,6 @@ export function boundaryRequestHash(request: BoundaryRequest): string {
     destinationHost: request.destinationHost,
     destinationPort: request.destinationPort,
     destinationProtocol: request.destinationProtocol,
-    toolCallId: request.toolCallId,
     toolName: request.toolName,
     skillName: request.skillName,
     toolInputPreview: request.toolInputPreview,

package/src/broker/overrides.ts

@@ -13,9 +13,7 @@ type PendingOverride = {
   approvedAt: number;
 };
 
-type PendingBreakGlass = BoundaryBreakGlassAuthorization & {
-  scopeKey: string;
-};
+type PendingBreakGlass = BoundaryBreakGlassAuthorization;
 
 export class RecentDenialStore {
   readonly #denials: RecentBoundaryDenial[] = [];
@@ -63,6 +61,10 @@ export class RecentDenialStore {
       scopeKey: context.scopeKey,
       deniedAt: this.#now(),
     });
+    // A fresh denial is a fresh human decision point: re-enable one-shot
+    // approval for this exact action even if a previous approval was already
+    // consumed earlier in the session.
+    this.#used.delete(this.key(context.sessionId, requestHash));
     if (this.#denials.length > this.#limit) {
       this.#denials.length = this.#limit;
     }
@@ -144,15 +146,18 @@ export class RecentDenialStore {
     if (index < 0) return;
     const denial = this.#denials[index];
     const key = this.key(sessionId, denial.requestHash);
-    if (this.#breakGlassPending.has(key)) return;
+    const pending = this.#breakGlassPending.get(key);
+    if (pending) {
+      // A pending authorization that was never consumed (the retry never
+      // arrived) must not lock break-glass forever once it has expired.
+      if (this.#now() - pending.confirmedAt <= this.#overrideTtlMs) return;
+      this.#breakGlassPending.delete(key);
+    }
     const authorization = {
       originalRequestId: denial.requestId,
       confirmedAt: this.#now(),
     };
-    this.#breakGlassPending.set(key, {
-      ...authorization,
-      scopeKey,
-    });
+    this.#breakGlassPending.set(key, { ...authorization });
     this.#denials.splice(index, 1);
     return {
       denial: structuredClone(denial),
@@ -164,10 +169,13 @@ export class RecentDenialStore {
     request: BoundaryRequest,
     context: BoundaryReviewContext,
   ): BoundaryBreakGlassAuthorization | undefined {
+    // Note: the retry always lands in a later turn than the denial (the
+    // command flow appends a user message before retrying), so the scope key
+    // is intentionally not compared here; the session + request hash and the
+    // confirmation TTL bound the match.
     const key = this.key(context.sessionId, boundaryRequestHash(request));
     const pending = this.#breakGlassPending.get(key);
     if (!pending) return;
-    if (pending.scopeKey !== context.scopeKey) return;
     this.#breakGlassPending.delete(key);
     if (this.#now() - pending.confirmedAt > this.#overrideTtlMs) {
       return;

package/src/index.ts

@@ -178,7 +178,7 @@ type ReviewAttemptObservation = {
 type PreflightPart = { characters: number; estimatedTokens: number };
 
 type ReviewPreflight = {
-  estimator: "conservative:utf8";
+  estimator: "conservative:cjk-aware";
   maxReviewerInputTokens: number;
   framingReserveTokens: number;
   fixedPrompt: PreflightPart;
@@ -898,10 +898,51 @@ function sharedReviewContext(
   });
 }
 
+/**
+ * Conservative token estimate for reviewer prompt sizing.
+ *
+ * CJK code points are estimated at one token each: UTF-8 encodes them as
+ * three bytes, so the previous byte-for-token estimator overestimated
+ * CJK-heavy review payloads ~3x and synchronously failed the input-budget
+ * preflight ("reviewer_input_budget_exceeded") for large CJK tool inputs
+ * such as long Chinese plan documents — before the reviewer model was ever
+ * called. Remaining code points are estimated from their UTF-8 byte length
+ * at 3 bytes per token, slightly conservative for ASCII (typical tokenizers
+ * average ~4 bytes per token) and safely conservative for 2-4 byte scripts.
+ */
+const OTHER_BYTES_PER_TOKEN = 3;
+
+function codePointUtf8Bytes(code: number): number {
+  return code < 0x80 ? 1 : code < 0x800 ? 2 : code < 0x10000 ? 3 : 4;
+}
+
+function isCjkCodePoint(code: number): boolean {
+  return (
+    (code >= 0x3000 && code <= 0x9fff) || // CJK symbols, punctuation, ideographs
+    (code >= 0x3400 && code <= 0x4dbf) || // CJK extension A
+    (code >= 0xf900 && code <= 0xfaff) || // CJK compatibility ideographs
+    (code >= 0xac00 && code <= 0xd7af) || // Hangul syllables
+    (code >= 0x3040 && code <= 0x30ff) || // Hiragana + Katakana
+    (code >= 0xff00 && code <= 0xffef) // fullwidth/halfwidth forms
+  );
+}
+
+/** Exported for tests; see the estimator doc comment above. */
+export function estimateReviewerTokens(text: string): number {
+  let tokens = 0;
+  for (const char of text) {
+    const code = char.codePointAt(0) ?? 0;
+    tokens += isCjkCodePoint(code)
+      ? 1
+      : codePointUtf8Bytes(code) / OTHER_BYTES_PER_TOKEN;
+  }
+  return Math.ceil(tokens);
+}
+
 function preflightPart(text: string): PreflightPart {
   return {
     characters: text.length,
-    estimatedTokens: Buffer.byteLength(text, "utf8"),
+    estimatedTokens: estimateReviewerTokens(text),
   };
 }
 
@@ -910,7 +951,7 @@ function combinedPreflightPart(values: readonly string[]): PreflightPart {
     (total, value) => ({
       characters: total.characters + value.length,
       estimatedTokens:
-        total.estimatedTokens + Buffer.byteLength(value, "utf8"),
+        total.estimatedTokens + estimateReviewerTokens(value),
     }),
     { characters: 0, estimatedTokens: 0 },
   );
@@ -966,7 +1007,7 @@ function reviewPreflight(
       REVIEWER_FRAMING_RESERVE_TOKENS,
   };
   return {
-    estimator: "conservative:utf8",
+    estimator: "conservative:cjk-aware",
     maxReviewerInputTokens,
     framingReserveTokens: REVIEWER_FRAMING_RESERVE_TOKENS,
     fixedPrompt,
@@ -1489,7 +1530,7 @@ function noModelSummary(): ReviewExecutionSummary {
       compactionState: "none",
     },
     preflight: {
-      estimator: "conservative:utf8",
+      estimator: "conservative:cjk-aware",
       maxReviewerInputTokens: DEFAULT_CONFIG.maxReviewerInputTokens,
       framingReserveTokens: REVIEWER_FRAMING_RESERVE_TOKENS,
       fixedPrompt: zero,
@@ -1726,7 +1767,12 @@ async function complete(
   });
 
   try {
-    if (transcript.failureCode) {
+    // A budget preflight failure is a sizing estimate, not a safety verdict.
+    // When a human explicitly authorized this exact retry, their decision
+    // must not be vetoed by an estimator: proceed with the truncated
+    // evidence and let the reviewer see the override. The failureCode stays
+    // on the transcript for observability.
+    if (transcript.failureCode && !reviewerContext?.userOverride) {
       incrementError(errorCounts, transcript.failureCode);
       throw new ReviewExecutionError(
         transcript.failureCode,
@@ -1964,6 +2010,69 @@ export type PiAutoReviewExtensionOptions = {
 
 const POLICY_AUDIT_ENTRY_TYPE = "pi-auto-review-policy-audit";
 
+// Headings flagged for "this is actionable" emphasis. The visual weight
+// otherwise matches the rest of the report and a user skimming the TUI can
+// miss the two sections that actually drive decisions.
+const EMPHASIS_HEADINGS = new Set([
+  "Suggested allow rules",
+  "Keep ask",
+]);
+
+function wrapWidth(text: string, width: number): string[] {
+  if (width <= 0) return [text];
+  const lines: string[] = [];
+  for (const paragraph of text.split("\n")) {
+    if (paragraph.length === 0) {
+      lines.push("");
+      continue;
+    }
+    const tokens = paragraph.split(/(\s+)/);
+    let current = "";
+    let currentWidth = 0;
+    const flush = () => {
+      lines.push(current);
+      current = "";
+      currentWidth = 0;
+    };
+    for (const token of tokens) {
+      if (token.length === 0) continue;
+      const tokenWidth = [...token].reduce(
+        (sum, ch) => sum + ((ch.codePointAt(0) ?? 0) > 0xff ? 2 : 1),
+        0,
+      );
+      if (tokenWidth > width) {
+        if (current.length > 0) flush();
+        for (const char of token) {
+          const charWidth = (char.codePointAt(0) ?? 0) > 0xff ? 2 : 1;
+          if (currentWidth + charWidth > width) flush();
+          current += char;
+          currentWidth += charWidth;
+        }
+        continue;
+      }
+      if (currentWidth + tokenWidth > width && current.length > 0) flush();
+      current += token;
+      currentWidth += tokenWidth;
+    }
+    if (current.length > 0) flush();
+  }
+  return lines.length > 0 ? lines : [""];
+}
+
+function styleAuditLine(theme: { fg(color: string, text: string): string }, line: string): string {
+  if (line.length === 0) return line;
+  if (line.startsWith("```")) return theme.fg("mdCodeBlockBorder", line);
+  if (line.startsWith("# ")) return theme.fg("mdHeading", line);
+  if (line.startsWith("## ")) {
+    const title = line.slice(3).trim();
+    return theme.fg(EMPHASIS_HEADINGS.has(title) ? "success" : "mdHeading", line);
+  }
+  // JSON payload inside the config code block — color it so it reads as a
+  // config block, not a paragraph the user is expected to read.
+  if (/^[ {]/.test(line) || /^["}{,]/.test(line)) return theme.fg("mdCodeBlock", line);
+  return theme.fg("muted", line);
+}
+
 function renderPolicyAuditEntry(
   entry: { data?: unknown },
   _options: unknown,
@@ -1977,13 +2086,7 @@ function renderPolicyAuditEntry(
   return {
     render(width: number) {
       const max = Math.max(20, width - 2);
-      return markdown.split("\n").flatMap((line) => {
-        const output: string[] = [];
-        for (let offset = 0; offset < Math.max(1, line.length); offset += max) {
-          output.push(theme.fg("muted", line.slice(offset, offset + max)));
-        }
-        return output;
-      });
+      return markdown.split("\n").flatMap((line) => wrapWidth(line, max).map((visual) => styleAuditLine(theme, visual)));
     },
     invalidate() {},
   };
@@ -2025,6 +2128,20 @@ export function createPiAutoReviewExtension(
     () => config.autoConfirmBoundedAllows,
   );
   const reviewWidget = new UserReviewWidgetController();
+  // pi >= 0.84.4 notification-only events: while a ctx.ui prompt blocks the
+  // session during an active review, show "waiting for you" instead of the
+  // misleading "Waiting for <model>…". Best-effort registration: on older
+  // pi these event names do not exist and the overlay stays off.
+  try {
+    pi.on("ui_prompt_start", (event) => {
+      reviewWidget.promptStart(event);
+    });
+    pi.on("ui_prompt_end", () => {
+      reviewWidget.promptEnd();
+    });
+  } catch {
+    // Older pi: widget behavior is unchanged.
+  }
   const policyAudit = new PolicyAuditController({
     config: () => config.policyAudit,
     cwd: () => context?.cwd,

package/src/policy-audit/index.ts

@@ -32,6 +32,8 @@ const PERMISSION_RESOLUTIONS = new Set([
   "user_approved_for_session",
   "user_denied",
   "auto_approved",
+  "authorizer_allowed",
+  "authorizer_denied",
   "confirmation_unavailable",
   "gate_error",
 ]);

package/src/policy-audit/report.ts

@@ -42,6 +42,11 @@ export type PolicyAuditReportOptions = {
   scope: "current" | "all"; days: number; top: number; minCount: number;
 };
 
+// Suggestion evidence must stay strictly human/session-based. Since
+// permission-system v28, decisions made by a registered authorizer chain link
+// (including pi-auto-review's own model review) resolve to `authorizer_allowed`
+// instead of `user_approved`. Counting those here would create a feedback loop:
+// machine review allows → evidence → suggested auto-allow rule → review bypassed.
 const SUCCESS_RESOLUTIONS = new Set([
   "user_approved", "user_approved_for_session", "session_approved", "auto_approved",
 ]);
@@ -70,8 +75,15 @@ function rank(
     .slice(0, top);
 }
 
+// "Reviewed" marks ask-path rows that some reviewer resolved — human clicks and,
+// since permission-system v28, named authorizer links alike — so low-risk
+// candidates stay visible even when only the machine authorizer decides them.
+// Display-only: SUCCESS_RESOLUTIONS still gates suggestion evidence.
 function reviewed(row: PolicyAuditAggregateRow): boolean {
-  return ["user_approved", "user_approved_for_session", "user_denied", "auto_approved"].includes(row.resolution);
+  return [
+    "user_approved", "user_approved_for_session", "user_denied", "auto_approved",
+    "authorizer_allowed", "authorizer_denied",
+  ].includes(row.resolution);
 }
 
 type CandidateGroup = {
@@ -243,10 +255,14 @@ export function buildPolicyAuditReport(
   };
 }
 
-function itemLines(items: readonly PolicyAuditReportItem[]): string[] {
+// Shared renderer helpers — kept terse so the TUI can fit one full report
+// on a typical screen without scrolling past statistics.
+type Row = { label: string; count: number; denied: number; denialRate: number };
+
+function itemLines(items: readonly Row[]): string[] {
   return items.length === 0
     ? ["- None above the minimum count."]
-    : items.map((item) => `- ${item.name}: ${item.count} (${item.denied} denied, ${item.denialRate}% denial)`);
+    : items.map((item) => `- ${item.label}: ${item.count} (${item.denied} denied, ${item.denialRate}% denial)`);
 }
 
 function recommendationLines(items: readonly PolicyRecommendationItem[]): string[] {
@@ -255,33 +271,67 @@ function recommendationLines(items: readonly PolicyRecommendationItem[]): string
     : items.map((item) => `- ${displayRule(item)}: ${item.successfulEvidence} successful, ${item.denied} denied — ${item.reason}`);
 }
 
+// Compress the five "hotspot" rankings (surface / signature / bash category /
+// approval source / low-risk) into one table-like section. Each row keeps the
+// original three fields (count, denied, denial rate); zero-denied rows drop
+// the redundant denial-rate field so the eye can scan allowed-only traffic.
+function hotspotRow(item: PolicyAuditReportItem): string {
+  const denied = `${item.denied} denied`;
+  const rate = item.denied === 0 ? "" : `, ${item.denialRate}% denial`;
+  return `- ${item.name}: ${item.count} (${denied}${rate})`;
+}
+
+function renderHotspotSections(report: PolicyAuditReport): string[] {
+  // Approval sources already encodes the same count as surfaces via a
+  // different key, so skip it when nothing was denied — it is allowed-only
+  // noise in that case. Low-risk review candidates overlap with the generic
+  // keep-ask section and are dropped entirely; the keep-ask section is the
+  // authoritative place for "what still asks".
+  const groups: Array<{ title: string; items: PolicyAuditReportItem[] }> = [
+    { title: "Surface hotspots", items: report.surfaces },
+    { title: "Tool and command signatures", items: report.tools },
+    { title: "Bash semantic categories", items: report.bashCategories },
+  ];
+  if (report.approvalSources.some((item) => item.denied > 0)) {
+    groups.push({ title: "Approval sources with denials", items: report.approvalSources });
+  }
+  if (report.ruleFingerprints.length > 0) {
+    groups.push({ title: "Anonymous rule-hit fingerprints",
+      items: report.ruleFingerprints.map((f) => ({ name: f.fingerprint, count: f.count, denied: 0, denialRate: 0 })) });
+  }
+  return groups.flatMap((group) => ["", `## ${group.title}`, "", ...group.items.map(hotspotRow)]);
+}
+
 export function renderPolicyAuditMarkdown(report: PolicyAuditReport): string {
   const suggested = report.suggestedAllowRules.length === 0
     ? ["- None."]
     : report.suggestedAllowRules.map((item) =>
       `- ${displayRule(item)} = allow: ${item.successfulEvidence} successful ask-path samples, zero denials — ${item.rationale}`
     );
-  const fingerprints = report.ruleFingerprints.length === 0
-    ? ["- None above the minimum count."]
-    : report.ruleFingerprints.map((item) => `- ${item.fingerprint}: ${item.count}`);
+  // The candidate keep-ask list (denied / blocked candidates) is the
+  // actionable one; the generic keep-ask and the ranked recommendations
+  // overlap heavily and are kept only as a single fallback line so the
+  // user sees they exist without a wall of duplicates.
+  const candidateKeepAsk = report.keepAskRules.filter((item) => item.denied > 0 ||
+    /denied|forwarded|unsafe|unparseable|authorization failure|parse_failed/i.test(item.reason));
+  const genericKeepAsk = report.keepAskRules.filter((item) => !candidateKeepAsk.includes(item));
+  const keepAskFallback = genericKeepAsk.length > 0
+    ? [`- ${genericKeepAsk.length} more surface(s) remain ask-by-default with no copyable rule; see full report for details.`]
+    : [];
   return [
     "# Permission policy audit", "",
-    `Scope: **${report.scope}** · Window: **${report.fromDay}–${report.throughDay}** · Collecting since: **${report.collectingSince}** · Recommendations since: **${report.recommendationsSince}**`,
+    `Scope: **${report.scope}** · Window: **${report.fromDay}–${report.throughDay}** · Collecting since: **${report.collectingSince}**`,
     `Decisions: **${report.total}** · Allowed: **${report.allowed}** · Denied: **${report.denied}** · Denial rate: **${report.denialRate}%**`, "",
     "## Suggested allow rules", "", ...suggested, "",
-    "## Copyable permission config", "", `Target: \`${report.configTarget}\``, "",
+    "## Copyable permission config", "", `Target: \`${report.configTarget}\``,
+    "Place narrow allow entries after broader matching ask entries (last-match-wins).", "",
     "```json", report.configFragment, "```", "",
-    "Merge Bash patterns into the existing `permission.bash` map at this same scope. Permission-system uses last-match-wins, so place these narrow allow patterns after any broader ask rule that would match them.", "",
-    "## Keep ask", "",
-    "Denied candidates, authorization failures, structurally unsafe Bash variants, forwarded requests, and values without a valid rule remain ask-by-default.",
-    ...recommendationLines(report.keepAskRules), ...itemLines(report.keepAskRecommendations), "",
-    "## Insufficient evidence", "", ...recommendationLines(report.insufficientEvidence), "",
-    "## Surface hotspots", "", ...itemLines(report.surfaces), "",
-    "## Tool and command signatures", "", ...itemLines(report.tools), "",
-    "## Bash semantic categories", "", ...itemLines(report.bashCategories), "",
-    "## Approval sources", "", ...itemLines(report.approvalSources), "",
-    "## Low-risk review candidates", "", ...itemLines(report.lowRiskReviewCandidates), "",
-    "## Anonymous rule-hit fingerprints", "", ...fingerprints, "",
-    "## Warnings", "", ...report.warnings.map((warning) => `- ${warning}`),
+    "## Keep ask",
+    "Denied candidates, authorization failures, unsafe Bash variants, and forwarded requests remain ask-by-default.",
+    ...recommendationLines(candidateKeepAsk), ...keepAskFallback, "",
+    "## Insufficient evidence", "", ...recommendationLines(report.insufficientEvidence),
+    ...renderHotspotSections(report), "",
+    "## Warnings", "",
+    "- Suggestions are evidence-based decision aids and never modify permission configuration. See the package README for the full list of caveats.",
   ].join("\n");
 }

package/src/user-feedback.ts

@@ -543,9 +543,33 @@ export function notifyUserReview(
 }
 
 export type UserReviewWidgetData = UserReviewEntryData & {
-  phase: "reviewing" | "complete";
+  phase: "reviewing" | "waiting_user" | "complete";
 };
 
+/**
+ * Overlay shown while a `ctx.ui` prompt blocks the session during an active
+ * review. Without it the widget kept claiming "Waiting for <model>…" while
+ * pi was actually waiting on the user (permission dialog, /review-denials,
+ * break-glass challenge, ...). Driven by the notification-only
+ * `ui_prompt_start` / `ui_prompt_end` events (pi >= 0.84.4).
+ */
+export function buildUserWaitingWidgetData(input: {
+  kind?: unknown;
+  title?: unknown;
+}): UserReviewWidgetData {
+  const kind = typeof input.kind === "string" ? input.kind.trim() : "";
+  const title = typeof input.title === "string" ? input.title.trim() : "";
+  const label = truncateReviewText(title || kind || "input", 48);
+  return {
+    phase: "waiting_user",
+    outcome: "defer",
+    type: "info",
+    lines: joinNoticeLines([
+      `Auto-review · waiting for you · ${label}`,
+    ]),
+  };
+}
+
 export function buildUserReviewingWidgetData(input: {
   surface: string;
   target?: string;
@@ -582,10 +606,12 @@ export function renderUserReviewWidgetLines(
   const rendered: string[] = [];
   const verb = data.phase === "reviewing"
     ? "reviewing"
+    : data.phase === "waiting_user"
+    ? "waiting"
     : outcomeVerb(data.outcome);
-  const accent = data.phase === "reviewing"
-    ? "muted"
-    : outcomeAccent(data.outcome);
+  const accent = data.phase === "complete"
+    ? outcomeAccent(data.outcome)
+    : "muted";
   const verbAnsi = theme.getFgAnsi(accent);
   const mutedAnsi = theme.getFgAnsi("muted");
   for (const [index, line] of data.lines.entries()) {
@@ -629,6 +655,8 @@ function setWidget(
 /** Owns the single live widget and rejects stale concurrent completions. */
 export class UserReviewWidgetController {
   #generation = 0;
+  /** Set while a `ctx.ui` prompt blocks the session (ui_prompt span). */
+  #waiting?: { kind?: unknown; title?: unknown };
   #current?: {
     requestId: string;
     generation: number;
@@ -643,11 +671,38 @@ export class UserReviewWidgetController {
     input: { surface: string; target?: string; model?: string },
   ): number {
     const generation = ++this.#generation;
-    this.#current = { requestId, generation, ctx };
-    setWidget(ctx, buildUserReviewingWidgetData(input));
+    this.#current = { requestId, generation, ctx, data: buildUserReviewingWidgetData(input) };
+    this.#render();
     return generation;
   }
 
+  /**
+   * Flip the reviewing widget to a "waiting for you" state while a
+   * `ctx.ui` prompt blocks the session. Only overlays the reviewing phase:
+   * completed outcome summaries make no running claim, and without a live
+   * widget there is nothing misleading to correct.
+   */
+  promptStart(event: { kind?: unknown; title?: unknown }): void {
+    this.#waiting = { kind: event?.kind, title: event?.title };
+    this.#render();
+  }
+
+  promptEnd(): void {
+    if (!this.#waiting) return;
+    this.#waiting = undefined;
+    this.#render();
+  }
+
+  /** Single render path; ordering of begin/complete/prompt events is irrelevant. */
+  #render(): void {
+    const current = this.#current;
+    if (!current) return;
+    const data = this.#waiting && current.data?.phase === "reviewing"
+      ? buildUserWaitingWidgetData(this.#waiting)
+      : current.data;
+    if (data) setWidget(current.ctx, data);
+  }
+
   complete(
     requestId: string,
     generation: number,
@@ -689,6 +744,7 @@ export class UserReviewWidgetController {
 
   clear(ctx?: ExtensionContext): void {
     ++this.#generation;
+    this.#waiting = undefined;
     const current = this.#current;
     this.#current = undefined;
     if (current) setWidget(ctx ?? current.ctx, undefined);