@gotgenes/pi-permission-system 25.2.2 → 25.4.0

package/src/authority/permission-prompt-component.ts

@@ -3,12 +3,7 @@ import type {
   ExtensionUIContext,
   KeybindingsManager,
 } from "@earendil-works/pi-coding-agent";
-import {
-  type Component,
-  matchesKey,
-  truncateToWidth,
-  wrapTextWithAnsi,
-} from "@earendil-works/pi-tui";
+import { type Component, matchesKey } from "@earendil-works/pi-tui";
 import {
   type PermissionPromptDecision,
   type RequestPermissionOptions,
@@ -22,6 +17,14 @@ import {
   type PromptViewState,
   reducePrompt,
 } from "#src/authority/permission-prompt-decision";
+import {
+  completeViewBudget,
+  type DialogView,
+  type RenderBudget,
+  renderPromptDialog,
+} from "#src/presentation/dialog-renderer";
+import { fitLinesToWidth } from "#src/presentation/line-fitting";
+import type { PromptPayload } from "#src/presentation/prompt-payload";
 
 /**
  * Inline `ctx.ui.custom` permission dialog for TUI sessions.
@@ -43,15 +46,16 @@ export type PermissionPromptUi = Pick<
 type PromptKeybindings = Pick<KeybindingsManager, "matches">;
 
 /** The resolved presentation context selected once per activation. */
-export interface PermissionPromptView {
+export interface PermissionPromptView extends PromptPreferences {
   mode: ExtensionContext["mode"];
   ui: PermissionPromptUi;
-  doublePressToConfirm: boolean;
 }
 
 /** Live prompt-behavior preferences read at prompt time (see `doublePressToConfirm`). */
 export interface PromptPreferences {
   doublePressToConfirm: boolean;
+  /** How much room a render has; the terminal width is added per frame. */
+  budget: RenderBudget;
 }
 
 /**
@@ -64,15 +68,30 @@ export interface PromptPreferences {
 export function requestPermissionDecision(
   view: PermissionPromptView,
   title: string,
-  message: string,
+  payload: PromptPayload,
   options?: RequestPermissionOptions,
 ): Promise<PermissionPromptDecision> {
   if (view.mode === "tui") {
-    return presentInlinePermissionPrompt(view, title, message, options);
+    return presentInlinePermissionPrompt(view, title, payload, options);
   }
-  return requestPermissionDecisionFromUi(view.ui, title, message, options);
+  // The fallback renders once and cannot re-render, so it neither paints nor
+  // offers an expansion; it substitutes a nominal width for the terminal size
+  // it is never told, and the host's own select wraps from there.
+  const rendered = renderPromptDialog(payload, {
+    ...view.budget,
+    width: FALLBACK_RENDER_WIDTH,
+  });
+  return requestPermissionDecisionFromUi(
+    view.ui,
+    title,
+    rendered.lines.join("\n"),
+    options,
+  );
 }
 
+/** The width the `select`/`input` fallback renders against. */
+const FALLBACK_RENDER_WIDTH = 80;
+
 /** Minimal theme surface the dialog uses; satisfied by the real SDK theme. */
 interface PromptTheme {
   fg(color: string, text: string): string;
@@ -92,7 +111,7 @@ const OPTION_ORDER: readonly PromptKey[] = ["y", "s", "n", "r"];
 export function presentInlinePermissionPrompt(
   view: PermissionPromptView,
   title: string,
-  message: string,
+  payload: PromptPayload,
   options?: RequestPermissionOptions,
 ): Promise<PermissionPromptDecision> {
   const config: PromptModelConfig = {
@@ -106,7 +125,8 @@ export function presentInlinePermissionPrompt(
         theme,
         config,
         title,
-        message,
+        payload,
+        view.budget,
         (data) => handleToolsExpandAction(data, keybindings, view.ui),
         () => {
           tui.requestRender();
@@ -145,12 +165,15 @@ function handleToolsExpandAction(
 class PermissionPromptComponent implements Component {
   private state: PromptViewState;
   private reasonBuffer = "";
+  /** Whether the operator asked to see the complete request (ADR 0011 §4). */
+  private expanded = false;
 
   constructor(
     private readonly theme: PromptTheme,
     private readonly config: PromptModelConfig,
     private readonly title: string,
-    private readonly message: string,
+    private readonly payload: PromptPayload,
+    private readonly budget: RenderBudget,
     private readonly handleAppAction: (data: string) => boolean,
     private readonly requestRender: () => void,
     private readonly done: (decision: PermissionPromptDecision) => void,
@@ -163,26 +186,66 @@ class PermissionPromptComponent implements Component {
   }
 
   render(width: number): string[] {
-    return fitToWidth(this.renderStep(), width);
+    return fitLinesToWidth(this.renderStep(width), width);
   }
 
-  private renderStep(): string[] {
+  private renderStep(width: number): string[] {
     switch (this.state.step) {
       case "decision":
-        return this.renderDecision();
+        return this.renderDecision(width);
       case "reason":
-        return this.renderReason();
+        return this.renderReason(width);
       case "scope":
         return this.renderScope();
     }
   }
 
+  /**
+   * The ask itself, bounded to the budget at this frame's width.
+   *
+   * Rendered per frame rather than once, because the row budget is a function
+   * of the width the host gives us, which a resize changes.
+   */
+  private renderAsk(width: number): DialogView {
+    return renderPromptDialog(
+      this.payload,
+      this.expanded ? completeViewBudget(width) : { ...this.budget, width },
+      (text) => this.theme.fg("warning", text),
+    );
+  }
+
+  /**
+   * The key hints, naming the expansion only when it would do something.
+   *
+   * An affordance advertised when there is nothing to expand is noise; one
+   * left unadvertised when the render dropped something is a decision made
+   * without the evidence.
+   */
+  private hint(view: DialogView): string {
+    const keys = [
+      "↑/↓ move",
+      "enter confirm",
+      "esc deny",
+      "press a letter, then again to confirm",
+    ];
+    if (this.expanded) {
+      keys.push("ctrl+o collapse");
+    } else if (view.elided) {
+      keys.push("ctrl+o full request");
+    }
+    return this.theme.fg("muted", keys.join(" · "));
+  }
+
   handleInput(data: string): void {
     if (this.state.step === "reason") {
       this.handleReasonInput(data);
       return;
     }
     if (this.handleAppAction(data)) {
+      // One "expand" for the operator: the host expands its pending tool call
+      // and the dialog expands its own render, on the same keystroke.
+      this.expanded = !this.expanded;
+      this.requestRender();
       return;
     }
     const event = this.toEvent(data);
@@ -247,8 +310,9 @@ class PermissionPromptComponent implements Component {
     this.requestRender();
   }
 
-  private renderDecision(): string[] {
-    const lines = [this.theme.fg("accent", this.title), this.message, ""];
+  private renderDecision(width: number): string[] {
+    const ask = this.renderAsk(width);
+    const lines = [this.theme.fg("accent", this.title), ...ask.lines, ""];
     for (const key of OPTION_ORDER) {
       const label = key === "s" ? this.config.sessionLabel : OPTION_LABELS[key];
       const selected = this.state.highlightedKey === key;
@@ -257,20 +321,14 @@ class PermissionPromptComponent implements Component {
       lines.push(selected ? this.theme.fg("accent", row) : row);
     }
     lines.push("");
-    lines.push(
-      this.state.hint ||
-        this.theme.fg(
-          "muted",
-          "↑/↓ move · enter confirm · esc deny · press a letter, then again to confirm",
-        ),
-    );
+    lines.push(this.state.hint || this.hint(ask));
     return lines;
   }
 
-  private renderReason(): string[] {
+  private renderReason(width: number): string[] {
     const lines = [
       this.theme.fg("accent", this.title),
-      this.message,
+      ...this.renderAsk(width).lines,
       "",
       `Reason (required): ${this.reasonBuffer}\u2588`,
     ];
@@ -307,24 +365,6 @@ class PermissionPromptComponent implements Component {
   }
 }
 
-/**
- * Fit rendered lines to the terminal width, satisfying the `ctx.ui.custom`
- * contract that every returned line be a single visual row no wider than
- * `width`. Long lines (e.g. a wide tool-preview message) are wrapped rather
- * than clipped so no content is lost; the final `truncateToWidth` guards the
- * edge cases `wrapTextWithAnsi` cannot split (a lone wide grapheme).
- */
-function fitToWidth(lines: string[], width: number): string[] {
-  if (width <= 0) {
-    return [];
-  }
-  return lines.flatMap((line) =>
-    wrapTextWithAnsi(line, width).map((wrapped) =>
-      truncateToWidth(wrapped, width),
-    ),
-  );
-}
-
 function isPrintable(data: string): boolean {
   if (data.length !== 1) {
     return false;

package/src/authority/permission-prompter.ts

@@ -3,6 +3,7 @@ import type {
   ForwardedAccessFacts,
   ForwardedSessionApproval,
 } from "#src/authority/permission-forwarding";
+import type { PromptPayload } from "#src/presentation/prompt-payload";
 import type { ReviewLogger } from "#src/session-logger";
 import type { TerminalAuthorizer } from "./authorizer";
 
@@ -27,6 +28,14 @@ export interface PromptPermissionDetails {
   source: PermissionReviewSource;
   agentName: string | null;
   message: string;
+  /**
+   * The complete structured description of this ask (ADR 0011 §2).
+   *
+   * Required: every ask carries one, and the type is what guarantees it rather
+   * than a convention each gate has to remember. `message` is a render over it
+   * for the duration of the transition, so the two cannot disagree.
+   */
+  payload: PromptPayload;
   toolCallId?: string;
   toolName?: string;
   skillName?: string;

package/src/config-loader.ts

@@ -222,6 +222,8 @@ export function mergeUnifiedConfigs(
   // Number scalars: override replaces base when defined
   for (const key of [
     "forwardingTimeoutMs",
+    "promptMaxRows",
+    "promptFieldMaxWidth",
     "toolInputPreviewMaxLength",
     "toolTextSummaryMaxLength",
   ] as const) {

package/src/config-schema.ts

@@ -194,6 +194,20 @@ export const unifiedConfigSchema = z
         "How long a subagent waits for the parent session to answer a forwarded permission request, in milliseconds.\n\nOmit to use the default (`600000`, ten minutes). A child whose in-process parent is not draining its inbox at all gives up in a couple of seconds regardless of this value, so lower it only to bound how long you are willing to leave an *unanswered* prompt pending.",
       default: 600000,
     }),
+    promptMaxRows: z.number().int().min(1).optional().meta({
+      description:
+        "Maximum rows a permission prompt renders before eliding its evidence. Omit to use the default (24).",
+      markdownDescription:
+        "Maximum rows a permission prompt renders before eliding its evidence.\n\nOmit to use the default (24). The request's own facts — the requesting agent, the tool, the matched rule, the decision-relevant value — are never elided by this budget; what gives way is the supporting evidence, and `Ctrl+O` expands the prompt to the complete request.",
+      default: 24,
+    }),
+    promptFieldMaxWidth: z.number().int().min(1).optional().meta({
+      description:
+        "Maximum characters of any one field shown in a permission prompt. Omit to use the default (400).",
+      markdownDescription:
+        "Maximum characters of any one field shown in a permission prompt.\n\nOmit to use the default (400). This is what bounds a single pathological field — a long here-string command, say — that would otherwise fill the prompt through wrapping. A shortened field is marked with an ellipsis, and `Ctrl+O` shows it in full.",
+      default: 400,
+    }),
     toolInputPreviewMaxLength: z.number().int().min(1).optional().meta({
       description:
         "Maximum character length of the inline-JSON tool-input preview shown in permission prompts. Omit to use the default (200). Set to a large value to disable truncation.",

package/src/extension-config.ts

@@ -22,6 +22,10 @@ export interface PermissionSystemExtensionConfig {
   piInfrastructureReadPaths?: string[];
   /** How long a subagent waits for the parent's answer to a forwarded ask, in ms. Defaults to 600000. */
   forwardingTimeoutMs?: number;
+  /** Max rows a permission prompt renders before eliding its evidence. Defaults to 24. */
+  promptMaxRows?: number;
+  /** Max characters of any one field shown in a permission prompt. Defaults to 400. */
+  promptFieldMaxWidth?: number;
   /** Max length of the inline-JSON input preview shown in permission prompts. Defaults to 200. */
   toolInputPreviewMaxLength?: number;
   /** Max length of inline pattern/path summaries (grep/find/ls) in permission prompts. Defaults to 80. */
@@ -76,6 +80,12 @@ export function normalizePermissionSystemConfig(
   if (raw.forwardingTimeoutMs !== undefined) {
     result.forwardingTimeoutMs = raw.forwardingTimeoutMs;
   }
+  if (raw.promptMaxRows !== undefined) {
+    result.promptMaxRows = raw.promptMaxRows;
+  }
+  if (raw.promptFieldMaxWidth !== undefined) {
+    result.promptFieldMaxWidth = raw.promptFieldMaxWidth;
+  }
   if (raw.toolInputPreviewMaxLength !== undefined) {
     result.toolInputPreviewMaxLength = raw.toolInputPreviewMaxLength;
   }

package/src/handlers/gates/bash-command.ts

@@ -83,7 +83,7 @@ export function resolveBashCommandCheck(
       input: { command: cmd.text },
       agentName,
     });
-    const result =
+    const floored =
       cmd.wrapperKind && base.state === "allow"
         ? {
             ...base,
@@ -91,7 +91,12 @@ export function resolveBashCommandCheck(
             matchedPattern: WRAPPER_SENTINEL[cmd.wrapperKind],
           }
         : base;
-    return cmd.context ? { ...result, commandContext: cmd.context } : result;
+    const result = cmd.context
+      ? { ...floored, commandContext: cmd.context }
+      : floored;
+    return cmd.executedUnit === undefined
+      ? result
+      : { ...result, executedUnit: cmd.executedUnit };
   });
   return (
     pickMostRestrictive(results) ??

package/src/handlers/gates/bash-external-directory.ts

@@ -1,9 +1,10 @@
 import type { BashProgram } from "#src/access-intent/bash/program";
 import type { ScopedPermissionResolver } from "#src/permission-resolver";
+import { renderLegacyMessage } from "#src/presentation/legacy-message";
+import { buildBashExternalDirectoryAskPayload } from "#src/presentation/path-ask-payload";
 import { SessionApproval } from "#src/session-approval";
 import { deriveApprovalPattern } from "#src/session-rules";
 import type { GateResult } from "./descriptor";
-import { formatBashExternalDirectoryAskPrompt } from "./external-directory-messages";
 import { selectUncoveredExternalPaths } from "./external-directory-policy";
 import { accessFactsFromPath } from "./helpers";
 import type { ToolCallContext } from "./types";
@@ -76,12 +77,15 @@ export function describeBashExternalDirectoryGate(
     resolvedPath: path.resolvedAlias(),
   }));
 
-  const bashExtMessage = formatBashExternalDirectoryAskPrompt(
+  const payload = buildBashExternalDirectoryAskPayload({
     command,
-    disclosures,
-    tcc.cwd,
-    tcc.agentName ?? undefined,
-  );
+    externalPaths: disclosures,
+    cwd: tcc.cwd,
+    agentName: tcc.agentName,
+    toolName: tcc.toolName,
+    matchedPattern: preCheck.matchedPattern,
+  });
+  const bashExtMessage = renderLegacyMessage(payload);
 
   const patterns = uncoveredPaths.map((p) => deriveApprovalPattern(p));
 
@@ -100,6 +104,7 @@ export function describeBashExternalDirectoryGate(
       source: "tool_call",
       agentName: tcc.agentName,
       message: bashExtMessage,
+      payload,
       toolCallId: tcc.toolCallId,
       toolName: tcc.toolName,
       command,

package/src/handlers/gates/bash-path.ts

@@ -1,13 +1,14 @@
 import type { AccessPath } from "#src/access-intent/access-path";
 import type { BashProgram } from "#src/access-intent/bash/program";
 import type { ScopedPermissionResolver } from "#src/permission-resolver";
+import { renderLegacyMessage } from "#src/presentation/legacy-message";
+import { buildPathAskPayload } from "#src/presentation/path-ask-payload";
 import { SessionApproval } from "#src/session-approval";
 import { deriveApprovalPattern } from "#src/session-rules";
 import type { PermissionCheckResult } from "#src/types";
 import { pickMostRestrictive } from "./candidate-check";
 import type { GateResult } from "./descriptor";
 import { accessFactsFromPath } from "./helpers";
-import { formatPathAskPrompt } from "./path";
 import type { ToolCallContext } from "./types";
 
 /**
@@ -113,11 +114,13 @@ export function describeBashPathGate(
   // path), so it matches the values a later call produces. For an unknown base
   // (`forLiteral`) `value()` is the raw token.
   const pattern = deriveApprovalPattern(worstEntry.path.value());
-  const askMessage = formatPathAskPrompt(
-    tcc.toolName,
-    worstToken,
-    tcc.agentName ?? undefined,
-  );
+  const payload = buildPathAskPayload({
+    toolName: tcc.toolName,
+    pathValue: worstToken,
+    agentName: tcc.agentName,
+    matchedPattern: worstCheck.matchedPattern,
+  });
+  const askMessage = renderLegacyMessage(payload);
 
   return {
     surface: "path",
@@ -133,6 +136,7 @@ export function describeBashPathGate(
       source: "tool_call",
       agentName: tcc.agentName,
       message: askMessage,
+      payload,
       toolCallId: tcc.toolCallId,
       toolName: tcc.toolName,
       command,

package/src/handlers/gates/descriptor.ts

@@ -51,6 +51,15 @@ export interface GateDescriptor {
   preCheck?: PermissionCheckResult;
 }
 
+/**
+ * A decision event's facts, before the runner stamps the request id it minted.
+ *
+ * A gate knows what was decided but not which request it was deciding — the id
+ * is minted in `GateRunner.run`. Producing this type rather than the full event
+ * is what routes every emit through the runner's single stamping site.
+ */
+export type DecisionEventFacts = Omit<PermissionDecisionEvent, "requestId">;
+
 /**
  * Early allow result — gate has determined the action without needing the runner.
  *
@@ -62,7 +71,7 @@ export interface GateBypass {
   /** Optional review log entry to emit. */
   log?: { event: string; details: Record<string, unknown> };
   /** Optional decision event to emit. */
-  decision?: PermissionDecisionEvent;
+  decision?: DecisionEventFacts;
 }
 
 /** Union of possible gate function return values. */

package/src/handlers/gates/external-directory.ts

@@ -1,11 +1,12 @@
 import { getToolInputPath } from "#src/access-intent/tool-input-path";
 import type { PathNormalizer } from "#src/path-normalizer";
 import type { ScopedPermissionResolver } from "#src/permission-resolver";
+import { renderLegacyMessage } from "#src/presentation/legacy-message";
+import { buildExternalDirectoryAskPayload } from "#src/presentation/path-ask-payload";
 import { SessionApproval } from "#src/session-approval";
 import { deriveApprovalPattern } from "#src/session-rules";
 import type { ToolAccessExtractorLookup } from "#src/tool-access-extractor-registry";
 import type { GateResult } from "./descriptor";
-import { formatExternalDirectoryAskPrompt } from "./external-directory-messages";
 import { resolveExternalDirectoryPolicy } from "./external-directory-policy";
 import { accessFactsFromPath } from "./helpers";
 import type { ToolCallContext } from "./types";
@@ -69,13 +70,6 @@ export function describeExternalDirectoryGate(
 
   // ── Build descriptor for permission check ───────────────────────────────
   const resolvedAlias = accessPath.resolvedAlias();
-  const extDirMessage = formatExternalDirectoryAskPrompt(
-    tcc.toolName,
-    externalDirectoryPath,
-    resolvedAlias,
-    tcc.cwd,
-    tcc.agentName ?? undefined,
-  );
 
   // The runner consumes this preCheck and skips its own resolve.
   const preCheck = resolveExternalDirectoryPolicy(
@@ -85,6 +79,16 @@ export function describeExternalDirectoryGate(
   );
   const pattern = deriveApprovalPattern(accessPath.value());
 
+  const payload = buildExternalDirectoryAskPayload({
+    toolName: tcc.toolName,
+    pathValue: externalDirectoryPath,
+    resolvedPath: resolvedAlias,
+    cwd: tcc.cwd,
+    agentName: tcc.agentName,
+    matchedPattern: preCheck.matchedPattern,
+  });
+  const extDirMessage = renderLegacyMessage(payload);
+
   return {
     surface: "external_directory",
     input: {},
@@ -102,6 +106,7 @@ export function describeExternalDirectoryGate(
       source: "tool_call",
       agentName: tcc.agentName,
       message: extDirMessage,
+      payload,
       toolCallId: tcc.toolCallId,
       toolName: tcc.toolName,
       path: externalDirectoryPath,

package/src/handlers/gates/helpers.ts

@@ -1,11 +1,9 @@
 import type { AccessPath } from "#src/access-intent/access-path";
 import { classifyToolKind } from "#src/access-intent/tool-kind";
 import type { ForwardedAccessFacts } from "#src/authority/permission-forwarding";
-import type {
-  PermissionDecisionEvent,
-  PermissionDecisionResolution,
-} from "#src/permission-events";
+import type { PermissionDecisionResolution } from "#src/permission-events";
 import type { PermissionCheckResult } from "#src/types";
+import type { DecisionEventFacts } from "./descriptor";
 
 /**
  * Build the child-fixed access facts for a path-shaped gate from its
@@ -62,11 +60,12 @@ export function deriveDecisionValue(
 }
 
 /**
- * Build a `PermissionDecisionEvent` from the gate's inputs.
+ * Build a decision event's facts from the gate's inputs.
  *
  * Centralises the `origin / agentName / matchedPattern ?? null` normalization
  * that is otherwise duplicated across the session-hit path and the gate-result
- * path in `runGateCheck`.
+ * path in `runGateCheck`. The request id is stamped by the runner, which is
+ * where it was minted.
  */
 export function buildDecisionEvent(
   decision: { surface: string; value: string },
@@ -74,7 +73,7 @@ export function buildDecisionEvent(
   agentName: string | null,
   result: "allow" | "deny",
   resolution: PermissionDecisionResolution,
-): PermissionDecisionEvent {
+): DecisionEventFacts {
   return {
     surface: decision.surface,
     value: decision.value,

package/src/handlers/gates/path.ts

@@ -1,6 +1,8 @@
 import { getToolInputPath } from "#src/access-intent/tool-input-path";
 import type { PathNormalizer } from "#src/path-normalizer";
 import type { ScopedPermissionResolver } from "#src/permission-resolver";
+import { renderLegacyMessage } from "#src/presentation/legacy-message";
+import { buildPathAskPayload } from "#src/presentation/path-ask-payload";
 import { SessionApproval } from "#src/session-approval";
 import { deriveApprovalPattern } from "#src/session-rules";
 import type { ToolAccessExtractorLookup } from "#src/tool-access-extractor-registry";
@@ -47,6 +49,13 @@ export function describePathGate(
   // the policy values a later call produces.
   const pattern = deriveApprovalPattern(accessPath.value());
 
+  const payload = buildPathAskPayload({
+    toolName: tcc.toolName,
+    pathValue: filePath,
+    agentName: tcc.agentName,
+    matchedPattern: check.matchedPattern,
+  });
+
   const descriptor: GateDescriptor = {
     surface: "path",
     input: { path: filePath },
@@ -60,11 +69,8 @@ export function describePathGate(
     promptDetails: {
       source: "tool_call",
       agentName: tcc.agentName,
-      message: formatPathAskPrompt(
-        tcc.toolName,
-        filePath,
-        tcc.agentName ?? undefined,
-      ),
+      message: renderLegacyMessage(payload),
+      payload,
       toolCallId: tcc.toolCallId,
       toolName: tcc.toolName,
       path: filePath,
@@ -86,12 +92,3 @@ export function describePathGate(
 
   return descriptor;
 }
-
-export function formatPathAskPrompt(
-  toolName: string,
-  pathValue: string,
-  agentName?: string,
-): string {
-  const subject = agentName ? `Agent '${agentName}'` : "Current agent";
-  return `${subject} requested tool '${toolName}' for path '${pathValue}'. Allow this path access?`;
-}