@erichll/pi-auto-review 0.8.2 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # 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

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,13 +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
-structured result row for allow, local confirmation, defer, deny, or circuit
-breaker outcomes. In the TUI this is a quote-style entry (`│`, muted quote
-color) that separates the outcome and surface from the target and rationale,
-then shows the reviewer model name (without provider prefix), input/output
-tokens, and duration when a model call ran. 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.2",
+  "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

@@ -42,6 +42,7 @@ import {
   buildUserReviewStatus,
   notifyUserReview,
   presentUserReview,
+  ReviewEntryBatcher,
   renderUserReviewEntry,
   reviewTargetFromRequest,
   setUserReviewStatus,
@@ -273,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;
@@ -728,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(
@@ -1925,6 +1963,9 @@ export function createPiAutoReviewExtension(
   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>();
@@ -1935,6 +1976,7 @@ export function createPiAutoReviewExtension(
   const uiAutoConfirmer = new PermissionUiAutoConfirmer(
     () => config.autoConfirmBoundedAllows,
   );
+  const reviewEntryBatcher = new ReviewEntryBatcher(pi);
 
   const emitTelemetry = (event: ReviewerTelemetryEvent): void => {
     writeOptionalAuditFile(event);
@@ -2267,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();
@@ -2280,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;
@@ -2300,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);
@@ -2379,15 +2482,35 @@ export function createPiAutoReviewExtension(
                   : undefined,
               ...reviewMeta,
             };
-            presentUserReview(
-              pi,
-              context,
-              buildUserReviewNotice(noticeInput),
-              buildUserReviewEntryData(noticeInput),
-            );
+            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,
@@ -2445,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

@@ -101,15 +101,15 @@ export function formatReviewUsage(usage: UserReviewUsage): string | undefined {
   if (input !== undefined) {
     const cache =
       usage.cacheRead && usage.cacheRead > 0
-        ? ` (${formatReviewTokenCount(usage.cacheRead)} cache)`
+        ? ` (${formatReviewTokenCount(usage.cacheRead)} toks cache)`
         : "";
-    parts.push(`${formatReviewTokenCount(input)} in${cache}`);
+    parts.push(`${formatReviewTokenCount(input)} toks in${cache}`);
   }
   if (usage.output !== undefined) {
-    parts.push(`${formatReviewTokenCount(usage.output)} out`);
+    parts.push(`${formatReviewTokenCount(usage.output)} toks out`);
   }
   if (parts.length === 0 && usage.totalTokens !== undefined) {
-    parts.push(`${formatReviewTokenCount(usage.totalTokens)} tok`);
+    parts.push(`${formatReviewTokenCount(usage.totalTokens)} toks`);
   }
   if (parts.length === 0) return undefined;
   const approx = usage.availability === "estimated" ? "~" : "";
@@ -193,6 +193,16 @@ function joinNoticeLines(lines: Array<string | undefined>): string[] {
     .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;
@@ -211,6 +221,24 @@ export type UserReviewEntryData = {
   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;
@@ -258,11 +286,21 @@ function outcomeVerb(outcome: UserReviewOutcome): string {
   }
 }
 
+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),
-    compactReviewText(input.target, 100) || undefined,
-    compactReviewText(input.rationale, 180) || undefined,
+    reviewTargetRationaleLine(input),
     recoveryLine(input.outcome, input.recoveryCommand),
     formatReviewMeta({
       model: input.model,
@@ -275,7 +313,7 @@ export function buildUserReviewLines(input: UserReviewNoticeInput): string[] {
 
 /**
  * User-facing (not agent-facing) notice after a review decision.
- * Structured for TUI wrapping: headline, target, rationale, then model/tokens.
+ * Structured for TUI wrapping: headline, target+rationale, then model/tokens.
  */
 export function buildUserReviewNotice(
   input: UserReviewNoticeInput,
@@ -297,10 +335,7 @@ export function buildUserReviewEntryData(
 }
 
 export function formatUserReviewQuoteMessage(message: string): string {
-  return message
-    .split("\n")
-    .map((line) => `│ ${line}`)
-    .join("\n");
+  return message;
 }
 
 function displayWidth(text: string): number {
@@ -362,8 +397,7 @@ export function renderUserReviewQuoteLines(
   theme: UserReviewTheme,
   width: number,
 ): string[] {
-  const contentWidth = Math.max(1, width - 2);
-  const border = theme.fg("mdQuoteBorder", "│ ");
+  const contentWidth = Math.max(1, width);
   const verb = outcomeVerb(data.outcome);
   const verbAnsi = theme.getFgAnsi(outcomeAccent(data.outcome));
   const numberAnsi = theme.getFgAnsi("success");
@@ -379,22 +413,104 @@ export function renderUserReviewQuoteLines(
       }
       if (index === data.lines.length - 1) {
         painted = painted.replace(
-          /(\d+(?:\.\d+)?[kM]?)(?=\s(?:in|out|tok|cache|calls)|ms\b|s\b)/g,
+          /(\d+(?:\.\d+)?[kM]?)(?=\s(?:toks|calls)|ms\b|s\b)/g,
           `${numberAnsi}$1\x1b[0m`,
         );
       }
-      rendered.push(border + withQuoteStyle(theme, painted));
+      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" ||
@@ -412,6 +528,20 @@ export function renderUserReviewEntry(
   };
 }
 
+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,
@@ -439,7 +569,7 @@ export function notifyUserReview(
   }
 }
 
-/** TUI quote-style entry when possible; otherwise a quoted notify toast. */
+/** TUI structured entry when possible; otherwise a plain notify toast. */
 export function presentUserReview(
   pi: ExtensionAPI | undefined,
   ctx: ExtensionContext | undefined,
@@ -450,6 +580,163 @@ export function presentUserReview(
   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,