@erichll/pi-auto-review 0.13.0 → 0.15.0

package/CHANGELOG.md

@@ -1,5 +1,72 @@
 # Changelog
 
+## 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
+  evidence-driven permission-configuration optimizer. Reports now separate
+  suggested allow rules, keep-ask rules, and insufficient evidence, and emit a
+  copyable JSON fragment targeting the selected project or global
+  permission-system configuration. Suggestions remain advisory and never read
+  or modify permission configuration.
+- Discover candidates from actual audit data without built-in tool, executable,
+  Git, RTK, package-manager, or read-only command catalogs. Valid observed
+  surfaces and sanitized Bash templates—including unknown tools and write
+  operations—can qualify after the configured minimum number of successful
+  ask-path approvals. Denials, gate failures, unavailable confirmations,
+  forwarded requests, and structurally unsafe Bash variants block a suggestion.
+- Migrate the policy-audit database transactionally to schema v2. Existing
+  aggregate counts and `collecting_since` are preserved, while the new
+  `recommendations_since` boundary prevents pre-migration data from producing
+  allow suggestions. Valid custom tool names and sanitized Bash templates are
+  retained for reporting. Templates replace paths, URLs, assignments, quoted
+  values, and option values with wildcards; raw commands and non-Bash tool
+  arguments or inputs remain excluded.
+
 ## 0.13.0 - 2026-08-28
 
 - Add compatibility with `@gotgenes/pi-permission-system` 27.1 directional

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
 
@@ -334,11 +340,18 @@ only daily, redacted aggregates. Collection is enabled by default and retains
 180 days. It starts when this version first initializes successfully; no
 permission-system JSONL or RTK history is read or imported.
 
-Before storage, Bash values become fixed signatures such as `git:push`,
-`rtk:git:status`, `npm:test`, or `<path-command>`. Paths become only
+Before storage, Bash values become observed command templates such as
+`git status --short`, `cat *`, or `npm test * --token *`. URLs, paths,
+assignments, quoted values, and option values are replaced with `*`; safe bare
+command words remain in plaintext so the report can emit a matching rule.
+Paths used for path-surface statistics become only
 `workspace`, `temp`, `home`, `external`, `sensitive`, or `unknown`. Request IDs,
-project locations, and matched-rule patterns are HMACed. The database never
-stores raw commands, paths, URLs, credentials, tool inputs, or project names.
+project locations, and matched-rule patterns are HMACed. Syntactically valid
+custom tool names are also retained in plaintext; invalid names stay anonymous
+as `<custom-tool>`. The database never stores raw commands, raw paths,
+URLs, credentials, or non-Bash tool arguments and inputs. Because safe bare Bash
+words are retained, command templates can contain non-secret filenames or
+project-specific labels; inspect suggestions before copying them.
 
 Data lives at
 `~/.pi/agent/extensions/pi-auto-review/policy-audit.sqlite`, beside an
@@ -357,6 +370,31 @@ Run `/auto-review-policy-audit` for a durable TUI report that is not sent to the
 LLM. Options are `--days 1..retention`, `--top 1..50`, `--min-count >=1`, and
 `--scope current|all`; defaults are `30`, `20`, `5`, and `current`.
 
+In addition to the redacted statistics, the report proposes copyable
+permission-system fragments. `--scope current` targets
+`.pi/extensions/pi-permission-system/config.json`; `--scope all` targets
+`~/.pi/agent/extensions/pi-permission-system/config.json`. The extension never
+reads, edits, or rewrites either file. Merge suggested Bash patterns into the
+existing `permission.bash` map and place the narrow allow entries after broader
+matching ask entries, because permission-system uses last-match-wins.
+
+Suggestions are discovered entirely from observed audit data; there is no
+built-in tool, executable, Git action, package-manager action, or read-only
+command catalog. Every valid observed permission surface and reliably templated
+Bash command can qualify, including previously unknown tools and write
+operations. Environment prefixes, compound syntax, pipelines, redirection,
+path executables, and unreliable parsing block that Bash template. Forwarded
+requests are statistics-only because the requester's cwd is not available. A
+candidate needs at least `--min-count` successful ask-path approvals and no
+denial, gate error, unavailable confirmation, blocked structural variant, or
+forwarded-only evidence in the selected window. Existing policy/infrastructure
+allows do not count as evidence of user friction. Repeated approval is evidence
+of user preference, not independent proof that a capability is safe.
+
+Schema v2 migrates v1 aggregates transactionally. Old totals remain visible,
+`collecting_since` is preserved, and `recommendations_since` records when safe
+recommendation evidence began; pre-migration data cannot produce a suggestion.
+
 The report is an extension-owned custom entry. It is deliberately not exposed
 as an Agent tool or packaged skill, so neither a tool schema nor skill metadata
 is added to the model context. Permission changes remain a separate, explicit

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@erichll/pi-auto-review",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "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,13 +47,13 @@
     "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",
+    "@earendil-works/pi-ai": "^0.84.4",
+    "@earendil-works/pi-coding-agent": "^0.84.4",
     "@gotgenes/pi-permission-system": "^27.0.0"
   },
   "devDependencies": {
-    "@earendil-works/pi-ai": "^0.84.1",
-    "@earendil-works/pi-coding-agent": "^0.84.1",
+    "@earendil-works/pi-ai": "^0.84.4",
+    "@earendil-works/pi-coding-agent": "^0.84.4",
     "@gotgenes/pi-permission-system": "27.1.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,