@erichll/pi-auto-review 0.8.1 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## 0.9.0 - 2026-08-22
+
+- Require `@gotgenes/pi-permission-system` `^27.0.0` and register through the
+  session-keyed `getPermissionsService(sessionId)` locator. Repeated ready
+  broadcasts are idempotent; session changes, shutdown, and late asynchronous
+  imports cannot retain or revive a stale authorizer registration. In-process
+  child nodes register against their own service without replacing the
+  parent's process-local broker capability.
+- Group local TUI review results by `(sessionId, toolCallId)` into one
+  transcript entry while preserving independent asks, model calls, verdicts,
+  grants, confirmations, and audit records. Denials flush immediately; tool
+  start, terminal permission denial, turn/agent/session end, a 60-second TTL,
+  and bounded-capacity eviction provide lossless fallback flushes. Forwarded,
+  uncorrelated, and non-TUI reviews remain immediate.
+- Add `toolCallId` to each `pi_auto_review_decision` audit entry and retain
+  compatibility rendering for historical single-result transcript entries.
+- Remove the review entry's left quote bar and combine each target with its
+  rationale and member surface/outcome on one line, keeping model/token/duration
+  metadata separate.
+- Label every displayed model token count with `toks` in both grouped and
+  single-result output.
+
+## 0.8.2 - 2026-08-21
+
+- Structure interactive review results as headline, target, rationale, and a
+  meta line with the reviewer model name, input/output tokens, duration, and extra
+  calls. The TUI renders them as markdown-style quote rows (`│` + `mdQuote`),
+  with allow/deny verbs and token counts tinted from the theme. The model id is
+  shown without a provider prefix; audit still records the full `provider/id`.
+  Local hard denies omit model and token fields because no model ran.
+
 ## 0.8.1 - 2026-08-21
 
 - Restore TUI auto-confirm for capped `path` / `external_directory` allows on

package/README.md

@@ -16,7 +16,7 @@ that dependency is a hard prerequisite (see [Install and enable](#install-and-en
 > **Prerequisite:** pi-auto-review is an authorizer inside
 > `@gotgenes/pi-permission-system`. Pi does not auto-install peer packages, so
 > install the permission system separately (once per machine) before this
-> extension:
+> extension. Version 0.9.0 requires permission-system 27.x:
 
 ```bash
 pi install npm:@gotgenes/pi-permission-system
@@ -49,7 +49,7 @@ adapters must consume the exact grant before retrying an operation. Changing
 the command, path, resolved path, destination, cwd, agent, or tool input
 invalidates that grant.
 
-Permission-system v24 downgrades authorizer allows on `path` and
+Permission-system downgrades authorizer allows on `path` and
 `external_directory` to `defer`. In an interactive TUI,
 `autoConfirmBoundedAllows` can bind the exact model allow to the immediately
 following recognized permission dialog. The bridge is request-ID-bound,
@@ -132,9 +132,16 @@ only a fixed, budget-checked schema correction.
 
 ## Operator feedback and exact retry
 
-Interactive sessions show a best-effort footer while review is running and a
-short result toast for allow, local confirmation, defer, deny, or circuit
-breaker outcomes. UI delivery never changes the authorization result.
+Interactive sessions show a best-effort footer while review is running and
+structured results for allow, local confirmation, defer, deny, or circuit
+breaker outcomes. Local permission-system asks that belong to the same tool
+call are grouped into one TUI entry; each request still has its own model call,
+verdict, grant, local confirmation, and audit record. Forwarded asks and
+non-TUI modes remain immediate and ungrouped. Group members retain their own
+surface, outcome, target, rationale, model, token usage, and duration. UI
+entries use unbordered muted text and place each target and rationale together
+on the same line as that member's surface and outcome. UI delivery never
+changes the authorization result.
 
 In an interactive TUI, `/auto-review-approve` lists up to ten recent
 non-critical model denials from the current session. Selecting one asks the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@erichll/pi-auto-review",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "Model-backed boundary approval broker for Pi",
   "type": "module",
   "license": "MIT",
@@ -49,12 +49,12 @@
   "peerDependencies": {
     "@earendil-works/pi-ai": "^0.84.1",
     "@earendil-works/pi-coding-agent": "^0.84.1",
-    "@gotgenes/pi-permission-system": "^26.0.0"
+    "@gotgenes/pi-permission-system": "^27.0.0"
   },
   "devDependencies": {
     "@earendil-works/pi-ai": "^0.84.1",
     "@earendil-works/pi-coding-agent": "^0.84.1",
-    "@gotgenes/pi-permission-system": "^26.0.0",
+    "@gotgenes/pi-permission-system": "^27.0.0",
     "@types/node": "^26.2.0",
     "typescript": "^6.0.3"
   }

package/src/index.ts

@@ -37,12 +37,18 @@ import {
 } from "./broker/index.ts";
 import { PermissionUiAutoConfirmer } from "./ui-auto-confirm.ts";
 import {
+  buildUserReviewEntryData,
   buildUserReviewNotice,
   buildUserReviewStatus,
   notifyUserReview,
+  presentUserReview,
+  ReviewEntryBatcher,
+  renderUserReviewEntry,
   reviewTargetFromRequest,
   setUserReviewStatus,
+  USER_REVIEW_ENTRY_TYPE,
   type UserReviewOutcome,
+  type UserReviewUsage,
 } from "./user-feedback.ts";
 
 export {
@@ -268,9 +274,6 @@ const USER_CONFIG_RELATIVE_PATH = join(
   "pi-auto-review",
   "config.json",
 );
-const PERMISSIONS_SERVICE_KEY = Symbol.for(
-  "@gotgenes/pi-permission-system:service",
-);
 const BOUNDED_SURFACES = new Set(["path", "external_directory"]);
 const REVIEWER_FRAMING_RESERVE_TOKENS = 64;
 const REVIEWER_RETRY_DELAY_MS = 250;
@@ -723,10 +726,50 @@ type PermissionsService = {
   ): () => void;
 };
 
-function permissionsService(): PermissionsService | undefined {
-  return (globalThis as Record<symbol, unknown>)[
-    PERMISSIONS_SERVICE_KEY
-  ] as PermissionsService | undefined;
+function promptPayloadRecord(
+  details: PromptPermissionDetails,
+): Record<string, unknown> | undefined {
+  const payload = (details as unknown as Record<string, unknown>).payload;
+  return payload && typeof payload === "object" && !Array.isArray(payload)
+    ? payload as Record<string, unknown>
+    : undefined;
+}
+
+function promptIsForwarded(details: PromptPermissionDetails): boolean {
+  if ((details as unknown as Record<string, unknown>).forwarding) return true;
+  const request = promptPayloadRecord(details)?.request;
+  if (!request || typeof request !== "object" || Array.isArray(request)) {
+    return false;
+  }
+  const requester = (request as Record<string, unknown>).requester;
+  return Boolean(
+    requester && typeof requester === "object" && !Array.isArray(requester) &&
+    (requester as Record<string, unknown>).forwarded === true
+  );
+}
+
+function reliableFullCommand(
+  details: PromptPermissionDetails,
+): string | undefined {
+  const payload = promptPayloadRecord(details);
+  const evidence = payload?.evidence;
+  if (Array.isArray(evidence)) {
+    for (const item of evidence) {
+      if (!item || typeof item !== "object" || Array.isArray(item)) continue;
+      const entry = item as Record<string, unknown>;
+      if (entry.label === "full command" && typeof entry.text === "string" &&
+          entry.text.trim()) {
+        return entry.text;
+      }
+    }
+  }
+  if (payload?.kind !== "bash_external_directory") return undefined;
+  const request = payload.request;
+  if (!request || typeof request !== "object" || Array.isArray(request)) {
+    return undefined;
+  }
+  const value = (request as Record<string, unknown>).value;
+  return typeof value === "string" && value.trim() ? value : undefined;
 }
 
 function boundaryRequest(
@@ -1330,6 +1373,33 @@ function aggregateUsage(attempts: readonly ReviewAttemptObservation[]): {
   return { availability, usage };
 }
 
+function userReviewMetaFromResult(
+  result: ReviewResult | undefined,
+  fallbackModel: string,
+): {
+  model?: string;
+  usage?: UserReviewUsage;
+  durationMs?: number;
+  attempts?: number;
+} {
+  if (!result) return {};
+  const attempts = result.summary.attempts;
+  const aggregate = aggregateUsage(attempts);
+  return {
+    ...(attempts.length > 0
+      ? {
+          model: attempts.at(-1)?.model ?? fallbackModel,
+          usage: {
+            availability: aggregate.availability,
+            ...aggregate.usage,
+          },
+        }
+      : {}),
+    durationMs: result.durationMs,
+    attempts: result.attempts,
+  };
+}
+
 function completeTelemetry(
   request: BoundaryRequest,
   config: Readonly<Config>,
@@ -1885,9 +1955,17 @@ export function createPiAutoReviewExtension(
     process.env.PI_AUTO_REVIEW_ALLOW_UNTRUSTED_DEV === "1";
 
   return (pi: ExtensionAPI): void => {
+  try {
+    pi.registerEntryRenderer(USER_REVIEW_ENTRY_TYPE, renderUserReviewEntry);
+  } catch {
+    // Renderer registration is observational.
+  }
   let context: ExtensionContext | undefined;
   let config: Readonly<Config> = trustedConfig;
   let disposeAuthorizer: (() => void) | undefined;
+  let registeredSessionId: string | undefined;
+  let registrationEpoch = 0;
+  let shuttingDown = false;
   let disposeBrokerService: (() => void) | undefined;
   const reviewResults = new Map<string, ReviewResult>();
   const telemetryCompleted = new Set<string>();
@@ -1898,6 +1976,7 @@ export function createPiAutoReviewExtension(
   const uiAutoConfirmer = new PermissionUiAutoConfirmer(
     () => config.autoConfirmBoundedAllows,
   );
+  const reviewEntryBatcher = new ReviewEntryBatcher(pi);
 
   const emitTelemetry = (event: ReviewerTelemetryEvent): void => {
     writeOptionalAuditFile(event);
@@ -1938,6 +2017,23 @@ export function createPiAutoReviewExtension(
           const execution = error instanceof ReviewExecutionError
             ? error
             : new ReviewExecutionError("unknown", noModelSummary());
+          if (request.source === "permission-system") {
+            reviewResults.set(request.id, {
+              decision: {
+                outcome: config.failureMode,
+                risk_level: "high",
+                user_authorization: "unknown",
+                rationale: "Automatic review is unavailable.",
+              },
+              attempts: execution.summary.attempts.length,
+              retryErrors: execution.summary.attempts
+                .map((attempt) => attempt.errorClass)
+                .filter((errorClass) => errorClass !== "none"),
+              durationMs: execution.summary.durationMs,
+              transcript: execution.summary.transcript,
+              summary: execution.summary,
+            });
+          }
           emitTelemetry(
             completeTelemetry(
               request,
@@ -2213,6 +2309,12 @@ export function createPiAutoReviewExtension(
   });
 
   pi.on("session_start", (_event, ctx) => {
+    shuttingDown = false;
+    registrationEpoch++;
+    disposeAuthorizer?.();
+    disposeAuthorizer = undefined;
+    registeredSessionId = undefined;
+    reviewEntryBatcher.flushAll();
     disposeBrokerService?.();
     broker?.clear();
     reviewResults.clear();
@@ -2226,7 +2328,17 @@ export function createPiAutoReviewExtension(
       );
       context = ctx;
       broker = createBroker();
-      disposeBrokerService = publishBoundaryBroker(broker);
+      try {
+        disposeBrokerService = publishBoundaryBroker(broker);
+      } catch (error) {
+        if (!(error instanceof Error) ||
+            error.message !== "pi-auto-review boundary broker is already published") {
+          throw error;
+        }
+        // In-process child nodes still need their own reviewer/authorizer.
+        // The process-global broker capability remains owned by the parent.
+        disposeBrokerService = undefined;
+      }
     } catch (error) {
       context = undefined;
       broker = undefined;
@@ -2246,12 +2358,57 @@ export function createPiAutoReviewExtension(
     if (context) uiAutoConfirmer.handlePrompt(event, context);
   });
 
-  pi.events.on("permissions:ready", () => {
-    try {
-      const service = permissionsService();
-      if (!service) return;
+  pi.events.on("permissions:decision", (event) => {
+    reviewEntryBatcher.permissionDecision(event);
+  });
+
+  pi.on("tool_execution_start", (event, ctx) => {
+    reviewEntryBatcher.toolExecutionStarted(
+      ctx.sessionManager.getSessionId(),
+      event.toolCallId,
+      event.args,
+    );
+  });
+  pi.on("turn_end", () => reviewEntryBatcher.flushAll());
+  pi.on("agent_end", () => reviewEntryBatcher.flushAll());
+
+  pi.events.on("permissions:ready", (event) => {
+    const ready = event && typeof event === "object" && !Array.isArray(event)
+      ? event as Record<string, unknown>
+      : undefined;
+    const sessionId = typeof ready?.sessionId === "string" &&
+        ready.sessionId.trim()
+      ? ready.sessionId
+      : undefined;
+    if (!sessionId) {
+      console.error(
+        `${EXTENSION_NAME}: ignored permissions:ready without a session id`,
+      );
+      return;
+    }
+    if (registeredSessionId === sessionId && disposeAuthorizer) return;
+
+    const epoch = ++registrationEpoch;
+    if (registeredSessionId && registeredSessionId !== sessionId) {
       disposeAuthorizer?.();
-      disposeAuthorizer = service.registerAuthorizer(
+      disposeAuthorizer = undefined;
+      registeredSessionId = undefined;
+    }
+
+    void import("@gotgenes/pi-permission-system").then((module) => {
+      if (shuttingDown || epoch !== registrationEpoch || !context) return;
+      const service = module.getPermissionsService(sessionId) as
+        | PermissionsService
+        | undefined;
+      if (!service) {
+        console.error(
+          `${EXTENSION_NAME}: permissions service unavailable for session ${sessionId}`,
+        );
+        return;
+      }
+      let dispose: (() => void) | undefined;
+      try {
+        dispose = service.registerAuthorizer(
         EXTENSION_NAME,
         async (details, query, log: AuthorizerLog) => {
           const evidence = normalizePermissionEvidence(details);
@@ -2263,13 +2420,16 @@ export function createPiAutoReviewExtension(
               surface,
               reason,
             });
-            notifyUserReview(
+            const unavailable = {
+              outcome: "unavailable" as const,
+              surface,
+              rationale: reason,
+            };
+            presentUserReview(
+              pi,
               context,
-              buildUserReviewNotice({
-                outcome: "unavailable",
-                surface,
-                rationale: reason,
-              }),
+              buildUserReviewNotice(unavailable),
+              buildUserReviewEntryData(unavailable),
             );
             return { kind: "deny", reason };
           }
@@ -2310,24 +2470,50 @@ export function createPiAutoReviewExtension(
             } else {
               userOutcome = "deny";
             }
-            notifyUserReview(
-              context,
-              buildUserReviewNotice({
-                outcome: userOutcome,
-                surface,
-                target,
-                rationale: decision.review.rationale,
-                recoveryCommand:
-                  decision.kind === "deny"
-                    ? decision.recoveryCommand
-                    : undefined,
-              }),
-            );
+            const reviewMeta = userReviewMetaFromResult(result, config.model);
+            const noticeInput = {
+              outcome: userOutcome,
+              surface,
+              target,
+              rationale: decision.review.rationale,
+              recoveryCommand:
+                decision.kind === "deny"
+                  ? decision.recoveryCommand
+                  : undefined,
+              ...reviewMeta,
+            };
+            const notice = buildUserReviewNotice(noticeInput);
+            const entryData = buildUserReviewEntryData(noticeInput);
+            const localSessionId = context.sessionManager.getSessionId();
+            if (
+              context.mode === "tui" &&
+              context.hasUI &&
+              request.toolCallId &&
+              localSessionId &&
+              !promptIsForwarded(details)
+            ) {
+              reviewEntryBatcher.enqueue({
+                sessionId: localSessionId,
+                toolCallId: request.toolCallId,
+                fullCommand: reliableFullCommand(details),
+                member: {
+                  requestId: request.id,
+                  ...noticeInput,
+                },
+                notice,
+                data: entryData,
+                ctx: context,
+              });
+            } else {
+              presentUserReview(pi, context, notice, entryData);
+            }
 
             log.review("pi_auto_review_decision", {
               requestId: request.id,
+              toolCallId: request.toolCallId,
               surface,
               model: config.model,
+              reviewerModel: reviewMeta.model,
               outcome: allowCapped ? "defer" : decision.kind,
               reviewerOutcome: decision.review.outcome,
               riskLevel: decision.review.riskLevel,
@@ -2343,6 +2529,8 @@ export function createPiAutoReviewExtension(
               attempts: result?.attempts ?? 0,
               retryErrors: result?.retryErrors ?? [],
               durationMs: result?.durationMs,
+              usageAvailability: reviewMeta.usage?.availability,
+              usage: reviewMeta.usage,
               transcriptUserCharacters: result?.transcript.userCharacters,
               transcriptToolCharacters: result?.transcript.toolCharacters,
               transcriptRelevantResultCharacters:
@@ -2380,22 +2568,45 @@ export function createPiAutoReviewExtension(
           } finally {
             setUserReviewStatus(context, undefined);
           }
-        },
-      );
-      writeOptionalAuditFile({ type: "authorizer_registered" });
-    } catch (error) {
+          },
+        );
+        if (shuttingDown || epoch !== registrationEpoch || !context) {
+          dispose();
+          return;
+        }
+        disposeAuthorizer?.();
+        disposeAuthorizer = dispose;
+        registeredSessionId = sessionId;
+        writeOptionalAuditFile({
+          type: "authorizer_registered",
+          sessionId,
+        });
+      } catch (error) {
+        dispose?.();
+        console.error(
+          `${EXTENSION_NAME}: authorizer registration failed: ${
+            error instanceof Error ? error.message : String(error)
+          }`,
+        );
+      }
+    }).catch((error) => {
+      if (shuttingDown || epoch !== registrationEpoch) return;
       console.error(
-        `${EXTENSION_NAME}: authorizer registration failed: ${
+        `${EXTENSION_NAME}: permission-system import failed: ${
           error instanceof Error ? error.message : String(error)
         }`,
       );
-    }
+    });
   });
 
   pi.on("session_shutdown", () => {
+    shuttingDown = true;
+    registrationEpoch++;
     setUserReviewStatus(context, undefined);
+    reviewEntryBatcher.flushAll();
     disposeAuthorizer?.();
     disposeAuthorizer = undefined;
+    registeredSessionId = undefined;
     disposeBrokerService?.();
     disposeBrokerService = undefined;
     broker?.clear();

package/src/user-feedback.ts

@@ -1,6 +1,10 @@
-import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
 
 export const USER_REVIEW_STATUS_KEY = "pi-auto-review";
+export const USER_REVIEW_ENTRY_TYPE = "pi-auto-review";
 
 export type UserReviewOutcome =
   | "allow"
@@ -11,6 +15,23 @@ export type UserReviewOutcome =
   | "circuit_breaker"
   | "unavailable";
 
+export type UserReviewUsageAvailability =
+  | "reported"
+  | "estimated"
+  | "unavailable"
+  | "unknown_provenance";
+
+export type UserReviewUsage = {
+  availability: UserReviewUsageAvailability;
+  input?: number;
+  output?: number;
+  cacheRead?: number;
+  cacheWrite?: number;
+  reasoning?: number;
+  totalTokens?: number;
+  observedInputTokens?: number;
+};
+
 export type UserReviewNotice = {
   message: string;
   type: "info" | "warning" | "error";
@@ -41,7 +62,7 @@ export function reviewTargetFromRequest(request: {
     request.toolName ??
     request.skillName ??
     request.operation;
-  const compact = compactReviewText(target, 90);
+  const compact = compactReviewText(target, 100);
   return compact || undefined;
 }
 
@@ -52,70 +73,486 @@ export function buildUserReviewStatus(
 ): string {
   const compact = compactReviewText(target, 48);
   return compact
-    ? `auto-review: reviewing ${surface} · ${compact}`
-    : `auto-review: reviewing ${surface}`;
+    ? `auto-review · reviewing · ${surface} · ${compact}`
+    : `auto-review · reviewing · ${surface}`;
 }
 
-/**
- * User-facing (not agent-facing) notice after a review decision.
- * Kept short so TUI toasts remain readable.
- */
-export function buildUserReviewNotice(input: {
+export function formatReviewTokenCount(count: number): string {
+  if (!Number.isFinite(count) || count < 0) return "0";
+  if (count < 1000) return String(Math.round(count));
+  if (count < 10_000) {
+    return `${(count / 1000).toFixed(1).replace(/\.0$/, "")}k`;
+  }
+  if (count < 1_000_000) return `${Math.round(count / 1000)}k`;
+  return `${(count / 1_000_000).toFixed(1).replace(/\.0$/, "")}M`;
+}
+
+export function formatReviewDuration(durationMs: number): string | undefined {
+  if (!Number.isFinite(durationMs) || durationMs < 0) return undefined;
+  if (durationMs < 1000) return `${Math.round(durationMs)}ms`;
+  const seconds = durationMs / 1000;
+  return seconds < 10 ? `${seconds.toFixed(1)}s` : `${Math.round(seconds)}s`;
+}
+
+export function formatReviewUsage(usage: UserReviewUsage): string | undefined {
+  if (usage.availability === "unavailable") return undefined;
+  const parts: string[] = [];
+  const input = usage.input ?? usage.observedInputTokens;
+  if (input !== undefined) {
+    const cache =
+      usage.cacheRead && usage.cacheRead > 0
+        ? ` (${formatReviewTokenCount(usage.cacheRead)} toks cache)`
+        : "";
+    parts.push(`${formatReviewTokenCount(input)} toks in${cache}`);
+  }
+  if (usage.output !== undefined) {
+    parts.push(`${formatReviewTokenCount(usage.output)} toks out`);
+  }
+  if (parts.length === 0 && usage.totalTokens !== undefined) {
+    parts.push(`${formatReviewTokenCount(usage.totalTokens)} toks`);
+  }
+  if (parts.length === 0) return undefined;
+  const approx = usage.availability === "estimated" ? "~" : "";
+  return `${approx}${parts.join(" · ")}`;
+}
+
+/** Display-only model id; drop a leading provider segment when present. */
+export function formatReviewModelName(model: unknown): string | undefined {
+  const raw = String(model ?? "")
+    .replace(/\s+/g, " ")
+    .trim();
+  if (!raw) return undefined;
+  const slash = raw.indexOf("/");
+  const name =
+    slash > 0 && slash < raw.length - 1 ? raw.slice(slash + 1) : raw;
+  return compactReviewText(name, 42) || undefined;
+}
+
+export function formatReviewMeta(input: {
+  model?: string;
+  usage?: UserReviewUsage;
+  durationMs?: number;
+  attempts?: number;
+}): string | undefined {
+  const parts: string[] = [];
+  const model = formatReviewModelName(input.model);
+  if (model) parts.push(model);
+  if (input.usage) {
+    const usage = formatReviewUsage(input.usage);
+    if (usage) parts.push(usage);
+  }
+  const duration = input.durationMs !== undefined
+    ? formatReviewDuration(input.durationMs)
+    : undefined;
+  if (duration) parts.push(duration);
+  if (input.attempts && input.attempts > 1) {
+    parts.push(`${input.attempts} calls`);
+  }
+  return parts.length > 0 ? parts.join(" · ") : undefined;
+}
+
+function reviewHeadline(outcome: UserReviewOutcome, surface: string): string {
+  switch (outcome) {
+    case "allow":
+      return `Auto-review · allowed · ${surface}`;
+    case "auto_confirm":
+      return `Auto-review · allowed · auto-confirm · ${surface}`;
+    case "needs_confirmation":
+      return `Auto-review · allowed · confirm locally · ${surface}`;
+    case "defer":
+      return `Auto-review · deferred · ${surface}`;
+    case "deny":
+      return `Auto-review · denied · ${surface}`;
+    case "circuit_breaker":
+      return `Auto-review · stopped · ${surface}`;
+    case "unavailable":
+      return `Auto-review · unavailable · ${surface}`;
+  }
+}
+
+function recoveryLine(
+  outcome: UserReviewOutcome,
+  recoveryCommand?: "/auto-review-approve" | "/auto-review-break-glass" | false,
+): string | undefined {
+  if (outcome === "circuit_breaker") {
+    return "use /auto-review-approve for one exact retry";
+  }
+  if (outcome !== "deny") return undefined;
+  if (recoveryCommand === false) {
+    return "local safety denials cannot be overridden";
+  }
+  if (recoveryCommand) {
+    return `use ${recoveryCommand} for one exact retry`;
+  }
+  return undefined;
+}
+
+function joinNoticeLines(lines: Array<string | undefined>): string[] {
+  return lines
+    .map((line) => (typeof line === "string" ? line.trimEnd() : ""))
+    .filter((line) => line.length > 0);
+}
+
+function reviewTargetRationaleLine(input: {
+  target?: string;
+  rationale?: string;
+}): string | undefined {
+  const target = compactReviewText(input.target, 100);
+  const rationale = compactReviewText(input.rationale, 180);
+  if (target && rationale) return `${target} · ${rationale}`;
+  return target || rationale || undefined;
+}
+
+export type UserReviewNoticeInput = {
   outcome: UserReviewOutcome;
   surface: string;
   target?: string;
   rationale?: string;
   recoveryCommand?: "/auto-review-approve" | "/auto-review-break-glass" | false;
-}): UserReviewNotice {
-  const target = compactReviewText(input.target, 70);
-  const rationale = compactReviewText(input.rationale, 120);
-  const subject = target ? `${input.surface} · ${target}` : input.surface;
-  const why = rationale ? ` — ${rationale}` : "";
+  model?: string;
+  usage?: UserReviewUsage;
+  durationMs?: number;
+  attempts?: number;
+};
+
+export type UserReviewEntryData = {
+  outcome: UserReviewOutcome;
+  type: UserReviewNotice["type"];
+  lines: string[];
+};
+
+export type UserReviewGroupMember = UserReviewNoticeInput & {
+  requestId: string;
+  permissionResult?: "allow" | "deny";
+};
+
+export type UserReviewGroupEntryData = {
+  kind: "group";
+  type: UserReviewNotice["type"];
+  sessionId: string;
+  toolCallId: string;
+  fullCommand?: string;
+  members: UserReviewGroupMember[];
+};
+
+export type AnyUserReviewEntryData =
+  | UserReviewEntryData
+  | UserReviewGroupEntryData;
+
+type UserReviewTheme = {
+  fg(color: string, text: string): string;
+  italic(text: string): string;
+  getFgAnsi(color: string): string;
+};
 
-  switch (input.outcome) {
+function noticeType(outcome: UserReviewOutcome): UserReviewNotice["type"] {
+  if (outcome === "unavailable") return "error";
+  if (outcome === "deny" || outcome === "circuit_breaker") return "warning";
+  return "info";
+}
+
+function outcomeAccent(
+  outcome: UserReviewOutcome,
+): "success" | "warning" | "error" | "muted" {
+  switch (outcome) {
+    case "allow":
+    case "auto_confirm":
+    case "needs_confirmation":
+      return "success";
+    case "defer":
+      return "muted";
+    case "deny":
+    case "circuit_breaker":
+      return "warning";
+    case "unavailable":
+      return "error";
+  }
+}
+
+function outcomeVerb(outcome: UserReviewOutcome): string {
+  switch (outcome) {
     case "allow":
-      return {
-        type: "info",
-        message: `Auto-review allowed ${subject}${why}`,
-      };
     case "auto_confirm":
-      return {
-        type: "info",
-        message: `Auto-review allowed ${subject}; auto-confirming the local dialog${why}`,
-      };
     case "needs_confirmation":
-      return {
-        type: "info",
-        message: `Auto-review allowed ${subject}; local confirmation is still required${why}`,
-      };
+      return "allowed";
     case "defer":
-      return {
-        type: "info",
-        message: `Auto-review deferred ${subject} to you${why}`,
-      };
+      return "deferred";
     case "deny":
-      return {
-        type: "warning",
-        message: `Auto-review denied ${subject}${why}${
-          input.recoveryCommand === false
-            ? " — local safety denials cannot be overridden"
-            : input.recoveryCommand
-              ? ` — use ${input.recoveryCommand} for one exact retry`
-              : ""
-        }`,
-      };
+      return "denied";
     case "circuit_breaker":
-      return {
-        type: "warning",
-        message: `Auto-review stopped after repeated denials this turn${
-          why || " — use /auto-review-approve for one exact retry"
-        }`,
-      };
+      return "stopped";
     case "unavailable":
-      return {
-        type: "error",
-        message: `Auto-review is unavailable${why}`,
-      };
+      return "unavailable";
+  }
+}
+
+function memberOutcomeText(outcome: UserReviewOutcome): string {
+  switch (outcome) {
+    case "auto_confirm":
+      return "allowed · auto-confirm";
+    case "needs_confirmation":
+      return "allowed · confirm locally";
+    default:
+      return outcomeVerb(outcome);
+  }
+}
+
+export function buildUserReviewLines(input: UserReviewNoticeInput): string[] {
+  return joinNoticeLines([
+    reviewHeadline(input.outcome, input.surface),
+    reviewTargetRationaleLine(input),
+    recoveryLine(input.outcome, input.recoveryCommand),
+    formatReviewMeta({
+      model: input.model,
+      usage: input.usage,
+      durationMs: input.durationMs,
+      attempts: input.attempts,
+    }),
+  ]);
+}
+
+/**
+ * User-facing (not agent-facing) notice after a review decision.
+ * Structured for TUI wrapping: headline, target+rationale, then model/tokens.
+ */
+export function buildUserReviewNotice(
+  input: UserReviewNoticeInput,
+): UserReviewNotice {
+  return {
+    type: noticeType(input.outcome),
+    message: buildUserReviewLines(input).join("\n"),
+  };
+}
+
+export function buildUserReviewEntryData(
+  input: UserReviewNoticeInput,
+): UserReviewEntryData {
+  return {
+    outcome: input.outcome,
+    type: noticeType(input.outcome),
+    lines: buildUserReviewLines(input),
+  };
+}
+
+export function formatUserReviewQuoteMessage(message: string): string {
+  return message;
+}
+
+function displayWidth(text: string): number {
+  let width = 0;
+  for (const char of text) {
+    const code = char.codePointAt(0) ?? 0;
+    width += code > 0xff ? 2 : 1;
+  }
+  return width;
+}
+
+export function wrapReviewDisplayText(text: string, width: number): string[] {
+  if (width <= 0) return [text];
+  const lines: string[] = [];
+  let current = "";
+  let currentWidth = 0;
+  const flush = () => {
+    if (current.length > 0) lines.push(current);
+    current = "";
+    currentWidth = 0;
+  };
+  for (const token of text.split(/(\s+)/)) {
+    const tokenWidth = displayWidth(token);
+    if (currentWidth + tokenWidth <= width) {
+      current += token;
+      currentWidth += tokenWidth;
+      continue;
+    }
+    if (/^\s+$/.test(token)) {
+      flush();
+      continue;
+    }
+    if (currentWidth > 0) flush();
+    if (tokenWidth <= width) {
+      current = token;
+      currentWidth = tokenWidth;
+      continue;
+    }
+    for (const char of token) {
+      const charWidth = (char.codePointAt(0) ?? 0) > 0xff ? 2 : 1;
+      if (currentWidth + charWidth > width) flush();
+      current += char;
+      currentWidth += charWidth;
+    }
+  }
+  flush();
+  return lines.length > 0 ? lines : [""];
+}
+
+function withQuoteStyle(theme: UserReviewTheme, text: string): string {
+  const marker = "\u0000";
+  const prefix = theme.italic(theme.fg("mdQuote", marker)).split(marker)[0] ?? "";
+  const body = theme.italic(theme.fg("mdQuote", text));
+  return prefix ? body.replace(/\x1b\[0m/g, `\x1b[0m${prefix}`) : body;
+}
+
+export function renderUserReviewQuoteLines(
+  data: UserReviewEntryData,
+  theme: UserReviewTheme,
+  width: number,
+): string[] {
+  const contentWidth = Math.max(1, width);
+  const verb = outcomeVerb(data.outcome);
+  const verbAnsi = theme.getFgAnsi(outcomeAccent(data.outcome));
+  const numberAnsi = theme.getFgAnsi("success");
+  const rendered: string[] = [];
+  for (const [index, line] of data.lines.entries()) {
+    for (const visual of wrapReviewDisplayText(line, contentWidth)) {
+      let painted = visual;
+      if (index === 0) {
+        painted = painted.replace(
+          verb,
+          `${verbAnsi}${verb}\x1b[0m`,
+        );
+      }
+      if (index === data.lines.length - 1) {
+        painted = painted.replace(
+          /(\d+(?:\.\d+)?[kM]?)(?=\s(?:toks|calls)|ms\b|s\b)/g,
+          `${numberAnsi}$1\x1b[0m`,
+        );
+      }
+      rendered.push(withQuoteStyle(theme, painted));
+    }
+  }
+  return rendered;
+}
+
+function groupOutcome(members: readonly UserReviewGroupMember[]): UserReviewOutcome {
+  if (members.some((member) => member.permissionResult === "deny")) return "deny";
+  for (const outcome of [
+    "circuit_breaker",
+    "deny",
+    "unavailable",
+    "defer",
+    "needs_confirmation",
+    "auto_confirm",
+  ] as const) {
+    if (members.some((member) => member.outcome === outcome)) return outcome;
+  }
+  return "allow";
+}
+
+function groupHeadline(data: UserReviewGroupEntryData): string {
+  const outcome = groupOutcome(data.members);
+  const result = outcome === "deny" || outcome === "circuit_breaker" ||
+      outcome === "unavailable"
+    ? "denied"
+    : outcome === "defer" || outcome === "needs_confirmation"
+      ? "deferred"
+      : "allowed";
+  return `Auto-review · ${result} · ${data.members.length} checks`;
+}
+
+export function buildUserReviewGroupLines(
+  data: UserReviewGroupEntryData,
+): UserReviewEntryData {
+  if (data.members.length === 1) {
+    const member = data.members[0];
+    const lines = buildUserReviewLines(member);
+    if (member.permissionResult === "deny" && member.outcome !== "deny") {
+      lines.push("Local confirmation · denied");
+    }
+    return { outcome: groupOutcome(data.members), type: data.type, lines };
+  }
+
+  const lines: string[] = [groupHeadline(data)];
+  const command = String(data.fullCommand ?? "")
+    .replace(/\s+/g, " ")
+    .trim();
+  if (command) lines.push(command);
+  for (const member of data.members) {
+    const summary = joinNoticeLines([
+      member.surface,
+      memberOutcomeText(member.outcome),
+      reviewTargetRationaleLine(member),
+    ]).join(" · ");
+    lines.push(
+      summary,
+      ...joinNoticeLines([
+        recoveryLine(member.outcome, member.recoveryCommand),
+        member.permissionResult === "deny" && member.outcome !== "deny"
+          ? "Local confirmation · denied"
+          : undefined,
+        formatReviewMeta(member),
+      ]),
+    );
+  }
+  return { outcome: groupOutcome(data.members), type: data.type, lines };
+}
+
+export function renderUserReviewEntry(
+  entry: { data?: unknown },
+  _options: unknown,
+  theme: UserReviewTheme,
+): { render(width: number): string[]; invalidate(): void } | undefined {
+  const data = entry.data;
+  if (
+    data &&
+    typeof data === "object" &&
+    (data as UserReviewGroupEntryData).kind === "group" &&
+    Array.isArray((data as UserReviewGroupEntryData).members) &&
+    (data as UserReviewGroupEntryData).members.length > 0
+  ) {
+    const parsed = data as UserReviewGroupEntryData;
+    return {
+      render(width: number) {
+        return renderUserReviewQuoteLines(
+          buildUserReviewGroupLines(parsed),
+          theme,
+          width,
+        );
+      },
+      invalidate() {},
+    };
+  }
+  if (
+    !data ||
+    typeof data !== "object" ||
+    !Array.isArray((data as UserReviewEntryData).lines) ||
+    (data as UserReviewEntryData).lines.length === 0
+  ) {
+    return undefined;
+  }
+  const parsed = data as UserReviewEntryData;
+  return {
+    render(width: number) {
+      return renderUserReviewQuoteLines(parsed, theme, width);
+    },
+    invalidate() {},
+  };
+}
+
+function presentUserReviewGroupEntry(
+  pi: ExtensionAPI | undefined,
+  ctx: ExtensionContext | undefined,
+  data: UserReviewGroupEntryData,
+): boolean {
+  if (!pi || !ctx?.hasUI || ctx.mode !== "tui") return false;
+  try {
+    pi.appendEntry(USER_REVIEW_ENTRY_TYPE, data);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function presentUserReviewEntry(
+  pi: ExtensionAPI | undefined,
+  ctx: ExtensionContext | undefined,
+  data: UserReviewEntryData,
+): boolean {
+  if (!pi || !ctx?.hasUI || ctx.mode !== "tui") return false;
+  try {
+    pi.appendEntry(USER_REVIEW_ENTRY_TYPE, data);
+    return true;
+  } catch {
+    return false;
   }
 }
 
@@ -126,12 +563,180 @@ export function notifyUserReview(
 ): void {
   if (!ctx?.hasUI) return;
   try {
-    ctx.ui.notify(notice.message, notice.type);
+    ctx.ui.notify(formatUserReviewQuoteMessage(notice.message), notice.type);
   } catch {
     // UI delivery is observational and must not change a decision.
   }
 }
 
+/** TUI structured entry when possible; otherwise a plain notify toast. */
+export function presentUserReview(
+  pi: ExtensionAPI | undefined,
+  ctx: ExtensionContext | undefined,
+  notice: UserReviewNotice,
+  data: UserReviewEntryData,
+): void {
+  if (presentUserReviewEntry(pi, ctx, data)) return;
+  notifyUserReview(ctx, notice);
+}
+
+type PendingReviewGroup = {
+  sessionId: string;
+  toolCallId: string;
+  fullCommand?: string;
+  members: Map<string, {
+    member: UserReviewGroupMember;
+    notice: UserReviewNotice;
+    data: UserReviewEntryData;
+  }>;
+  ctx: ExtensionContext;
+  createdAt: number;
+  timer: ReturnType<typeof setTimeout>;
+};
+
+export type ReviewEntryBatcherOptions = {
+  maxGroups?: number;
+  maxMembers?: number;
+  ttlMs?: number;
+  now?: () => number;
+};
+
+/** Buffers only transcript presentation; permission requests remain independent. */
+export class ReviewEntryBatcher {
+  readonly #groups = new Map<string, PendingReviewGroup>();
+  readonly #maxGroups: number;
+  readonly #maxMembers: number;
+  readonly #ttlMs: number;
+  readonly #now: () => number;
+
+  constructor(
+    private readonly pi: ExtensionAPI,
+    options: ReviewEntryBatcherOptions = {},
+  ) {
+    this.#maxGroups = options.maxGroups ?? 32;
+    this.#maxMembers = options.maxMembers ?? 8;
+    this.#ttlMs = options.ttlMs ?? 60_000;
+    this.#now = options.now ?? Date.now;
+  }
+
+  enqueue(input: {
+    sessionId: string;
+    toolCallId: string;
+    fullCommand?: string;
+    member: UserReviewGroupMember;
+    notice: UserReviewNotice;
+    data: UserReviewEntryData;
+    ctx: ExtensionContext;
+  }): void {
+    try {
+      const key = this.#key(input.sessionId, input.toolCallId);
+      let group = this.#groups.get(key);
+      if (group?.members.has(input.member.requestId)) return;
+      if (group && group.members.size >= this.#maxMembers) {
+        this.#flushKey(key);
+        group = undefined;
+      }
+      if (!group) {
+        if (this.#groups.size >= this.#maxGroups) {
+          const oldest = [...this.#groups.entries()].sort(
+            (left, right) => left[1].createdAt - right[1].createdAt,
+          )[0]?.[0];
+          if (oldest) this.#flushKey(oldest);
+        }
+        const timer = setTimeout(() => this.#flushKey(key), this.#ttlMs);
+        timer.unref?.();
+        group = {
+          sessionId: input.sessionId,
+          toolCallId: input.toolCallId,
+          fullCommand: input.fullCommand,
+          members: new Map(),
+          ctx: input.ctx,
+          createdAt: this.#now(),
+          timer,
+        };
+        this.#groups.set(key, group);
+      } else if (!group.fullCommand && input.fullCommand) {
+        group.fullCommand = input.fullCommand;
+      }
+      group.members.set(input.member.requestId, {
+        member: input.member,
+        notice: input.notice,
+        data: input.data,
+      });
+      if (input.member.outcome === "deny" ||
+          input.member.outcome === "circuit_breaker") {
+        this.#flushKey(key);
+      }
+    } catch {
+      presentUserReview(this.pi, input.ctx, input.notice, input.data);
+    }
+  }
+
+  toolExecutionStarted(
+    sessionId: string,
+    toolCallId: string,
+    args: unknown,
+  ): void {
+    const key = this.#key(sessionId, toolCallId);
+    const group = this.#groups.get(key);
+    if (!group) return;
+    if (!group.fullCommand && args && typeof args === "object" &&
+        !Array.isArray(args) &&
+        typeof (args as Record<string, unknown>).command === "string") {
+      group.fullCommand = String((args as Record<string, unknown>).command);
+    }
+    this.#flushKey(key);
+  }
+
+  permissionDecision(event: unknown): void {
+    if (!event || typeof event !== "object" || Array.isArray(event)) return;
+    const record = event as Record<string, unknown>;
+    if (typeof record.requestId !== "string" ||
+        (record.result !== "allow" && record.result !== "deny")) return;
+    for (const [key, group] of this.#groups) {
+      const pending = group.members.get(record.requestId);
+      if (!pending) continue;
+      pending.member.permissionResult = record.result;
+      if (record.result === "deny") this.#flushKey(key);
+      return;
+    }
+  }
+
+  flushAll(): void {
+    for (const key of [...this.#groups.keys()]) this.#flushKey(key);
+  }
+
+  get pendingGroups(): number {
+    return this.#groups.size;
+  }
+
+  #key(sessionId: string, toolCallId: string): string {
+    return `${sessionId}\u0000${toolCallId}`;
+  }
+
+  #flushKey(key: string): void {
+    const group = this.#groups.get(key);
+    if (!group) return;
+    this.#groups.delete(key);
+    clearTimeout(group.timer);
+    const pending = [...group.members.values()];
+    if (pending.length === 0) return;
+    const members = pending.map((entry) => entry.member);
+    const data: UserReviewGroupEntryData = {
+      kind: "group",
+      type: noticeType(groupOutcome(members)),
+      sessionId: group.sessionId,
+      toolCallId: group.toolCallId,
+      ...(group.fullCommand ? { fullCommand: group.fullCommand } : {}),
+      members,
+    };
+    if (presentUserReviewGroupEntry(this.pi, group.ctx, data)) return;
+    for (const entry of pending) {
+      presentUserReview(this.pi, group.ctx, entry.notice, entry.data);
+    }
+  }
+}
+
 /** Best-effort footer status; pass undefined to clear. */
 export function setUserReviewStatus(
   ctx: ExtensionContext | undefined,