@gotgenes/pi-permission-system 25.2.2 → 25.3.0

package/src/access-intent/bash/wrapper-analysis.ts

@@ -0,0 +1,335 @@
+/**
+ * Wrapper interpretation for a bash command unit: what kind of wrapper it is,
+ * and — where it can be established — what it actually runs.
+ *
+ * Pure and word-based; the AST walk that produces the words lives in
+ * `command-enumeration.ts`. Both questions live here together deliberately: the
+ * shape that floors a unit to `ask` and the shape that names its inner command
+ * must agree, and two classifiers over the same vocabulary would drift.
+ */
+
+/** One word of a command unit: its text, and its offset into the unit's text. */
+export interface CommandWord {
+  readonly text: string;
+  readonly offset: number;
+}
+
+/**
+ * Why a command unit's decision is floored to at least `ask`.
+ * `"opaque-payload"` — an inline-shell payload (`bash -c`/`eval`) whose inner
+ * program is not re-parsed (#481).
+ * `"indirection"` — a prefix/exec wrapper (`sudo`/`env`/`xargs`/`find -exec`/…)
+ * whose inner command is a visible argument but is not gated on its own (#490).
+ * The kind selects the audit sentinel; both floor identically.
+ */
+export type WrapperKind = "opaque-payload" | "indirection";
+
+/**
+ * Classify a command unit's words as a floored wrapper, or `undefined` for an
+ * ordinary command. `words[0]` is the command name; a leading
+ * `variable_assignment` prefix is already stripped by the caller. The command
+ * name is matched on its basename, so `/bin/bash -c …` counts.
+ *
+ * `"opaque-payload"`: `eval`, or a shell (`bash`/`sh`/`dash`/`zsh`/`ksh`) with a
+ * `-c` short-flag cluster (`-c`, `-ec`, `-xc`) — the inner program is a quoted
+ * argument the enumerator does not re-parse (#481).
+ *
+ * `"indirection"`: an always-invoking prefix/exec wrapper
+ * ({@link INDIRECTION_WRAPPER_NAMES}), or a search tool
+ * ({@link EXEC_CONDITIONAL_WRAPPERS}, `find`/`fd`) carrying a per-result exec
+ * flag — the inner command is a visible argument that a `<cmd> *` rule would
+ * otherwise never match (#490). A bare `find`/`fd` search runs no subcommand and
+ * is not flagged.
+ */
+export function classifyWrapperWords(
+  words: readonly CommandWord[],
+): WrapperKind | undefined {
+  const commandName = wrapperName(words);
+  if (commandName === undefined) return undefined;
+  const args = words.slice(1).map((word) => word.text);
+  if (commandName === "eval") return "opaque-payload";
+  if (SHELL_WRAPPER_NAMES.has(commandName) && hasShortFlagC(args)) {
+    return "opaque-payload";
+  }
+  if (INDIRECTION_WRAPPER_NAMES.has(commandName)) return "indirection";
+  if (execFlagIndex(commandName, args) !== -1) return "indirection";
+  return undefined;
+}
+
+// ── Wrapper vocabulary ───────────────────────────────────────────────────────
+
+/**
+ * The command a wrapper unit actually runs, or `null` when it cannot be
+ * established or adds nothing over the unit itself.
+ *
+ * Display-only (ADR 0011 §3.5, #713): the result is never gated and never
+ * becomes a `BashCommand`, so the wrapper floor is untouched. Because it is
+ * shown on a decision surface, the rule is to fail to `null` rather than to a
+ * guess — an unrecognized option shape yields nothing rather than a remainder
+ * that might name the wrong command.
+ *
+ * Nested wrappers unwrap to the innermost command (`sudo timeout 5 xargs grep
+ * foo` → `grep foo`), bounded by {@link MAX_UNWRAP_DEPTH}.
+ */
+export function executedUnitOf(
+  unitText: string,
+  words: readonly CommandWord[],
+): string | null {
+  let text = unitText;
+  let current = words;
+
+  for (let depth = 0; depth < MAX_UNWRAP_DEPTH; depth++) {
+    const kind = classifyWrapperWords(current);
+    if (kind === undefined) break;
+
+    if (kind === "opaque-payload") {
+      // The payload is an inner *program*, not a slice of this command line, so
+      // it is unquoted and terminal — unwrapping it further would need a parse.
+      return nothingNew(opaquePayload(current), unitText);
+    }
+
+    const start = innerCommandIndex(current);
+    if (start === -1 || start >= current.length) break;
+    const end = execTerminatorIndex(current, start);
+    text = sliceWords(text, current, start, end).trimEnd();
+    current = rebase(current, start, end);
+  }
+
+  return nothingNew(text, unitText);
+}
+
+/** How many wrapper layers to unwrap before giving up. */
+const MAX_UNWRAP_DEPTH = 4;
+
+/**
+ * The extracted text, or `null` when it establishes nothing new — it is absent
+ * or empty, it still begins with an option (so the inner command was never
+ * reached), or it simply repeats the unit.
+ */
+function nothingNew(text: string | null, unitText: string): string | null {
+  if (text === null || text === "" || text === unitText) return null;
+  return text.startsWith("-") ? null : text;
+}
+
+/** The inline-shell payload argument, unquoted; `null` when absent. */
+function opaquePayload(words: readonly CommandWord[]): string | null {
+  const args = words.slice(1);
+  // `eval` takes its program as the first argument (no `-c`, so the index is
+  // -1); a shell takes it after the `-c` cluster.
+  const flagIndex = shortFlagCIndex(args.map((word) => word.text));
+  const payload = args[flagIndex + 1] as CommandWord | undefined;
+  return payload === undefined ? null : unquote(payload.text);
+}
+
+/** Strip one matching pair of surrounding quotes. */
+function unquote(text: string): string {
+  const first = text.at(0);
+  const quoted =
+    (first === "'" || first === '"') &&
+    text.length >= 2 &&
+    text.endsWith(first);
+  return quoted ? text.slice(1, -1) : text;
+}
+
+/**
+ * Index of the word beginning the inner command, or `-1` when the wrapper's own
+ * options run out first.
+ *
+ * Skips the wrapper name, environment assignments, options (consuming a
+ * following value for the options in {@link VALUE_TAKING_FLAGS}), and a leading
+ * operand for the wrappers that take one. An exec-conditional wrapper instead
+ * starts immediately after its exec flag.
+ */
+function innerCommandIndex(words: readonly CommandWord[]): number {
+  const name = wrapperName(words);
+  if (name === undefined) return -1;
+
+  const argTexts = words.slice(1).map((word) => word.text);
+  const execFlag = execFlagIndex(name, argTexts);
+  if (execFlag !== -1) return execFlag + 2;
+
+  const valueTaking = VALUE_TAKING_FLAGS.get(name) ?? EMPTY_FLAGS;
+  let operandPending = LEADING_OPERAND_WRAPPERS.has(name);
+  let index = 1;
+
+  while (index < words.length) {
+    const word = words[index].text;
+    if (word === "--") return index + 1;
+    if (isEnvironmentAssignment(word)) {
+      index++;
+      continue;
+    }
+    if (word.startsWith("-")) {
+      index += valueTaking.has(word) ? 2 : 1;
+      continue;
+    }
+    if (operandPending) {
+      operandPending = false;
+      index++;
+      continue;
+    }
+    return index;
+  }
+  return -1;
+}
+
+/**
+ * Index of an exec wrapper's `;`/`+` terminator, or `words.length` — the
+ * terminator belongs to `find`, not to the command it runs.
+ */
+function execTerminatorIndex(
+  words: readonly CommandWord[],
+  start: number,
+): number {
+  const terminator = words.findIndex(
+    (word, index) =>
+      index >= start && EXEC_TERMINATORS.has(word.text.replace(/^\\/, "")),
+  );
+  return terminator === -1 ? words.length : terminator;
+}
+
+/** The unit text spanned by `words[start..end)`. */
+function sliceWords(
+  unitText: string,
+  words: readonly CommandWord[],
+  start: number,
+  end: number,
+): string {
+  const from = words[start].offset;
+  return end < words.length
+    ? unitText.slice(from, words[end].offset)
+    : unitText.slice(from);
+}
+
+/** `words[start..end)` with offsets rebased onto the sliced text. */
+function rebase(
+  words: readonly CommandWord[],
+  start: number,
+  end: number,
+): CommandWord[] {
+  const origin = words[start].offset;
+  return words
+    .slice(start, end)
+    .map((word) => ({ text: word.text, offset: word.offset - origin }));
+}
+
+/** True for a `NAME=value` environment prefix. */
+function isEnvironmentAssignment(word: string): boolean {
+  return /^[A-Za-z_][A-Za-z0-9_]*=/.test(word);
+}
+
+/**
+ * Shell command names whose `-c` flag introduces an opaque inline program.
+ */
+const SHELL_WRAPPER_NAMES = new Set(["bash", "sh", "dash", "zsh", "ksh"]);
+
+/**
+ * Indirection wrappers that always invoke a following command, so the wrapper
+ * (not the inner command) is what a bash rule matches. Floored by command-name
+ * basename alone. Extend this set to cover another always-invoking wrapper.
+ */
+const INDIRECTION_WRAPPER_NAMES = new Set([
+  "sudo",
+  "env",
+  "xargs",
+  "time",
+  "nohup",
+  "timeout",
+  "nice",
+  // Exec-capable rewrites and prefix wrappers surveyed in #575: parallelizers
+  // (parallel/rust-parallel/rush), a sudo rewrite (doas), and prefix wrappers
+  // (setsid/stdbuf/watch/flock) that all always invoke a following command.
+  "parallel",
+  "rust-parallel",
+  "rush",
+  "doas",
+  "setsid",
+  "stdbuf",
+  "watch",
+  "flock",
+]);
+
+/**
+ * Search tools that invoke a command per result only when an exec flag is
+ * present; a bare search runs no subcommand. Floored only when an argument
+ * exactly matches one of the tool's exec flags. Extend by adding a tool with
+ * its exec-flag set.
+ */
+const EXEC_CONDITIONAL_WRAPPERS = new Map<string, ReadonlySet<string>>([
+  ["find", new Set(["-exec", "-execdir", "-ok", "-okdir"])],
+  ["fd", new Set(["-x", "--exec", "-X", "--exec-batch"])],
+]);
+
+/**
+ * Curated per-wrapper options that consume the following word, so skipping a
+ * wrapper's own arguments does not mistake an option's value for the inner
+ * command. Attached forms (`-I{}`, `--user=root`) need no entry — they are one
+ * word. Only the display-side extraction reads this, and a missing or wrong
+ * entry yields `null` (see {@link executedUnitOf}), never a weaker gate.
+ */
+const VALUE_TAKING_FLAGS = new Map<string, ReadonlySet<string>>([
+  ["sudo", new Set(["-u", "-g", "-p", "-C", "-h", "-U", "-r", "-t"])],
+  ["doas", new Set(["-u", "-C"])],
+  ["env", new Set(["-u", "-C", "--unset", "--chdir"])],
+  [
+    "xargs",
+    new Set(["-n", "-P", "-I", "-i", "-d", "-E", "-L", "-l", "-s", "-a"]),
+  ],
+  ["timeout", new Set(["-s", "-k", "--signal", "--kill-after"])],
+  ["nice", new Set(["-n", "--adjustment"])],
+  ["time", new Set(["-o", "-f", "--output", "--format"])],
+  ["stdbuf", new Set(["-i", "-o", "-e", "--input", "--output", "--error"])],
+  ["watch", new Set(["-n", "--interval"])],
+  ["flock", new Set(["-w", "-E", "--timeout", "--conflict-exit-code"])],
+]);
+
+const EMPTY_FLAGS: ReadonlySet<string> = new Set<string>();
+
+/**
+ * Wrappers whose first bare word is an operand (a duration, a lock file) rather
+ * than the start of the inner command.
+ */
+const LEADING_OPERAND_WRAPPERS = new Set(["timeout", "flock"]);
+
+/** Words ending a `find -exec` clause; they belong to `find`, not its command. */
+const EXEC_TERMINATORS = new Set([";", "+"]);
+
+// ── Shared helpers ───────────────────────────────────────────────────────────
+
+/** The wrapper's command-name basename, or `undefined` for an empty unit. */
+function wrapperName(words: readonly CommandWord[]): string | undefined {
+  return words.length === 0 ? undefined : basename(words[0].text);
+}
+
+/**
+ * True when an argument list has a short-flag cluster containing `c` before any
+ * `--` end-of-options marker (`-c`, `-ec`, `-xc`) — the inline-shell payload
+ * flag for `bash`/`sh`/`dash`/`zsh`/`ksh`.
+ */
+function hasShortFlagC(args: readonly string[]): boolean {
+  return shortFlagCIndex(args) !== -1;
+}
+
+/** Index within `args` of the `-c` short-flag cluster, or `-1`. */
+function shortFlagCIndex(args: readonly string[]): number {
+  for (const [index, arg] of args.entries()) {
+    if (arg === "--") return -1;
+    if (arg.startsWith("-") && !arg.startsWith("--") && arg.includes("c")) {
+      return index;
+    }
+  }
+  return -1;
+}
+
+/** Index within `args` of a matched per-result exec flag, or `-1`. */
+function execFlagIndex(commandName: string, args: readonly string[]): number {
+  const execFlags = EXEC_CONDITIONAL_WRAPPERS.get(commandName);
+  if (!execFlags) return -1;
+  return args.findIndex((arg) => execFlags.has(arg));
+}
+
+/** The final path segment of a command name (`/bin/bash` → `bash`). */
+function basename(name: string): string {
+  const slash = name.lastIndexOf("/");
+  return slash === -1 ? name : name.slice(slash + 1);
+}

package/src/authority/forwarded-request-server.ts

@@ -13,6 +13,8 @@ import {
   type PermissionForwardingLocation,
 } from "#src/authority/permission-forwarding";
 import type { SubagentSessionRegistry } from "#src/authority/subagent-registry";
+import { buildForwardedAskPayload } from "#src/presentation/forwarded-ask-payload";
+import { renderLegacyMessage } from "#src/presentation/legacy-message";
 import { SessionApproval } from "#src/session-approval";
 import type { SessionApprovalRecorder } from "#src/session-approval-recorder";
 import type { DebugReviewLogger } from "#src/session-logger";
@@ -78,19 +80,6 @@ export interface ForwardedRequestServerDeps {
 
 // ── Module-private helpers ────────────────────────────────────────────────
 
-function formatForwardedPermissionPrompt(
-  request: ForwardedPermissionRequest,
-): string {
-  const agentName = request.requesterAgentName || "unknown";
-  const sessionId = request.requesterSessionId || "unknown";
-  return [
-    `Subagent '${agentName}' requested permission.`,
-    `Session ID: ${sessionId}`,
-    "",
-    request.message,
-  ].join("\n");
-}
-
 /**
  * Map a forwarded request onto the escalated ask's details, carrying the
  * forwarded provenance (requester agent/session + the child's original display
@@ -106,11 +95,13 @@ function formatForwardedPermissionPrompt(
 function buildForwardedAskDetails(
   request: ForwardedPermissionRequest,
 ): PromptPermissionDetails {
+  const payload = buildForwardedAskPayload(request);
   return {
     requestId: request.id,
     source: request.source ?? "tool_call",
     agentName: request.requesterAgentName || null,
-    message: formatForwardedPermissionPrompt(request),
+    message: renderLegacyMessage(payload),
+    payload,
     surface: request.surface ?? null,
     value: request.value ?? null,
     forwarding: {

package/src/authority/local-user-authorizer.ts

@@ -53,13 +53,12 @@ export class LocalUserAuthorizer implements TerminalAuthorizer {
       {
         mode: this.deps.mode,
         ui: this.deps.ui,
-        doublePressToConfirm:
-          this.deps.getPromptPreferences().doublePressToConfirm,
+        ...this.deps.getPromptPreferences(),
       },
       details.forwarding
         ? "Permission Required (Subagent)"
         : "Permission Required",
-      details.message,
+      details.payload,
       buildRequestOptions(details),
     );
   }

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) {