@gotgenes/pi-permission-system 25.4.0 → 26.0.0

package/src/log-field-cap.ts

@@ -0,0 +1,82 @@
+/**
+ * The permission review log's width bound (ADR 0011 §6).
+ *
+ * The log renders the prompt payload under its own configured limits, and this
+ * is the limit: every string it writes is narrowed to a configured width. The
+ * bound is applied at `writeLine`, the single place a log line is produced, so
+ * a write path cannot be added that escapes it — the same discipline redaction
+ * already has there.
+ *
+ * A cap is not redaction, and the two must not be conflated
+ * (`docs/decisions/0010-permission-log-secret-exposure.md`). This narrows by
+ * length alone and never reads a value to decide what to shorten; redaction
+ * masks a value because of the key name it is bound to, and still does, so a
+ * sensitive-keyed value is masked whole however long it was.
+ */
+
+/**
+ * The width when the operator configures none.
+ *
+ * Not a new number: it is the bound that already governed `toolInputPreview`,
+ * promoted from one field to every field so the log has one limit rather than
+ * one limit and an unbounded remainder.
+ */
+export const DEFAULT_REVIEW_LOG_FIELD_MAX_WIDTH = 1000;
+
+/** The two-field shape this module reads off the extension config. */
+export interface ReviewLogWidthConfig {
+  readonly reviewLogFieldMaxWidth?: number;
+}
+
+/** The configured review-log field width, or the built-in default. */
+export function resolveReviewLogFieldWidth(
+  config: ReviewLogWidthConfig,
+): number {
+  return config.reviewLogFieldMaxWidth ?? DEFAULT_REVIEW_LOG_FIELD_MAX_WIDTH;
+}
+
+/**
+ * Narrow every string in a log-detail record to `maxWidth`.
+ *
+ * Recurses through plain objects and arrays so a nested detail is bounded too,
+ * and touches strings only — a number, a boolean, or a null passes through as
+ * it was. A shortened value is marked with a bare ellipsis, the same marker the
+ * dialog uses: a character count is a number the reader cannot act on
+ * (ADR 0011 §4).
+ */
+export function capLogFieldWidths<T>(details: T, maxWidth: number): T {
+  return capValue(details, maxWidth) as T;
+}
+
+function capValue(value: unknown, maxWidth: number): unknown {
+  if (typeof value === "string") {
+    return value.length <= maxWidth
+      ? value
+      : `${value.slice(0, maxWidth)}\u2026`;
+  }
+  if (Array.isArray(value)) {
+    return value.map((entry) => capValue(entry, maxWidth));
+  }
+  if (isPlainObject(value)) {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, entry]) => [
+        key,
+        capValue(entry, maxWidth),
+      ]),
+    );
+  }
+  return value;
+}
+
+/**
+ * Whether a value is a record this cap should descend into.
+ *
+ * A class instance (a `Date`, an `Error`) is left alone: rebuilding it as a
+ * plain object would change what the writer serializes, and the cap's job is
+ * to shorten strings, not to reshape a value.
+ */
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  if (typeof value !== "object" || value === null) return false;
+  const prototype: unknown = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}

package/src/logging.ts

@@ -4,6 +4,7 @@ import {
   EXTENSION_ID,
   type PermissionSystemExtensionConfig,
 } from "./extension-config";
+import { capLogFieldWidths, resolveReviewLogFieldWidth } from "./log-field-cap";
 import {
   OWNER_ONLY_FILE_MODE,
   restrictExistingPathToOwner,
@@ -37,11 +38,20 @@ export function createPermissionSystemLogger(
   // re-invoked per session, unlike module scope, which now outlives one.
   const hardened = new Set<string>();
 
+  /**
+   * The only place a log line is produced.
+   *
+   * `maxFieldWidth` bounds every string the line carries; it is supplied for
+   * the review stream and withheld for the debug stream, which is opt-in and
+   * exists to be read in full. Capping happens before redaction, which masks
+   * by key name and so still masks a sensitive value whole.
+   */
   const writeLine = (
     stream: "debug" | "review",
     path: string,
     event: string,
     details: Record<string, unknown>,
+    maxFieldWidth?: number,
   ): string | undefined => {
     const directoryError = ensureLogsDirectory();
     if (directoryError) {
@@ -49,12 +59,16 @@ export function createPermissionSystemLogger(
     }
 
     try {
+      const bounded =
+        maxFieldWidth === undefined
+          ? details
+          : capLogFieldWidths(details, maxFieldWidth);
       const line = redactedJsonStringify({
         timestamp: new Date().toISOString(),
         extension: EXTENSION_ID,
         stream,
         event,
-        ...details,
+        ...bounded,
       });
       if (!line) {
         return `Failed to write permission-system ${stream} log '${path}': event could not be serialized.`;
@@ -89,11 +103,18 @@ export function createPermissionSystemLogger(
     event: string,
     details: Record<string, unknown> = {},
   ): string | undefined => {
-    if (!options.getConfig().permissionReviewLog) {
+    const config = options.getConfig();
+    if (!config.permissionReviewLog) {
       return undefined;
     }
 
-    return writeLine("review", reviewLogPath, event, details);
+    return writeLine(
+      "review",
+      reviewLogPath,
+      event,
+      details,
+      resolveReviewLogFieldWidth(config),
+    );
   };
 
   return { debug, review };

package/src/permission-events.ts

@@ -8,6 +8,8 @@
  * removed or renamed without a semver-major version bump.
  */
 
+import type { PromptRequestFacts } from "#src/presentation/prompt-payload";
+
 /** Minimal event bus interface required by the emit helpers. */
 export interface PermissionEventBus {
   emit(channel: string, data: unknown): void;
@@ -79,8 +81,19 @@ export interface PermissionUiPromptEvent {
   value: string | null;
   /** Agent name (when known). */
   agentName: string | null;
-  /** Message displayed to the user. */
-  message: string;
+  /**
+   * The ask's invariant core (ADR 0011 §3), verbatim from the prompt payload.
+   *
+   * Nested rather than flattened so the event and the payload share one shape:
+   * a fact added to `PromptRequestFacts` reaches the bus without a second
+   * hand-maintained declaration. Carries no evidence and no annotations — the
+   * bus is the narrowest renderer (ADR 0011 §6), observable by any loaded
+   * extension without the operator having named it.
+   *
+   * `request.surface` is the *gate* surface the rule fired on; the top-level
+   * `surface` is the display projection. Both are here on purpose.
+   */
+  request: PromptRequestFacts;
   /** Forwarding context, or null for a direct prompt. */
   forwarding: ForwardedPromptContext | null;
 }

package/src/permission-prompts.ts

@@ -1,8 +1,9 @@
 import { classifyToolKind } from "./access-intent/tool-kind";
 
-// NOTE: the ask prompts are now payload builders under src/presentation/;
-// denial text lives in denial-messages.ts. This module retains only the
-// pre-check reasons, which are agent-facing rather than user-facing.
+// NOTE: the ask prompts are now payload builders under src/presentation/, and
+// denial text is a render over the payload (presentation/agent-renderer.ts).
+// This module retains only the pre-check reasons, refused before any payload
+// exists to render.
 
 export function formatMissingToolNameReason(): string {
   return "Tool call was blocked because no tool name was provided. Use a registered tool name from pi.getAllTools().";

package/src/permission-session.ts

@@ -219,7 +219,7 @@ export class PermissionSession implements ToolCallGateInputs {
    * so the pipeline reads a clean value rather than pulling raw config.
    */
   getToolPreviewLimits(): ToolPreviewFormatterOptions {
-    return resolveToolPreviewLimits(this.config);
+    return resolveToolPreviewLimits();
   }
 
   /**

package/src/permission-ui-prompt.ts

@@ -11,6 +11,7 @@
  * prompter or forwarding modules (no import cycles, correct layering).
  */
 
+import type { PromptPayload } from "#src/presentation/prompt-payload";
 import type {
   ForwardedPromptContext,
   PermissionUiPromptEvent,
@@ -21,7 +22,8 @@ export interface DirectPromptInput {
   requestId: string;
   source: "tool_call" | "skill_input" | "skill_read";
   agentName: string | null;
-  message: string;
+  /** The ask's complete payload; the event carries its invariant core alone. */
+  payload: PromptPayload;
   toolName?: string;
   skillName?: string;
   path?: string;
@@ -62,7 +64,7 @@ export function buildUiPrompt(input: UiPromptInput): PermissionUiPromptEvent {
     surface: input.surface !== undefined ? input.surface : directSurface(input),
     value: input.value !== undefined ? input.value : directValue(input),
     agentName: input.agentName,
-    message: input.message,
+    request: input.payload.request,
     forwarding: input.forwarding ?? null,
   };
 }

package/src/presentation/agent-renderer.ts

@@ -0,0 +1,215 @@
+import { EXTENSION_ID } from "#src/extension-config";
+import { DEFAULT_RENDER_BUDGET } from "#src/presentation/dialog-renderer";
+import {
+  describeBashCommandContext,
+  flaggedElementLabel,
+  flaggedElements,
+} from "#src/presentation/fact-vocabulary";
+import {
+  allEvidence,
+  findEvidence,
+  type PromptPayload,
+} from "#src/presentation/prompt-payload";
+
+/**
+ * The agent-facing render of a refused permission ask (ADR 0011 §7).
+ *
+ * The rule that governs this renderer and no other:
+ *
+ * > The agent renderer identifies the call; it does not reproduce it.
+ *
+ * The agent authored the tool call, and the harness returns this text as that
+ * call's own tool result with its arguments still in context, so echoing the
+ * input back tells it nothing it did not already have. What is new is the
+ * verdict: which surface gated the call, which rule matched, which of the
+ * call's operands tripped it, and what the human said.
+ *
+ * The command is the one value never rendered — it is the payload that took
+ * over the viewport in #710 and the context window on every denial. The
+ * flagged element (a path, an MCP target, a skill) *is* rendered, because
+ * which operand a rule fired on is below tool-call granularity and the agent
+ * cannot recover it from its own arguments; being agent input, it is capped
+ * rather than structurally bounded.
+ */
+
+/** Attribution tag on every block reason this extension produces. */
+export const EXTENSION_TAG = `[${EXTENSION_ID}]`;
+
+/** How much room the flagged element has, as the operator configured it. */
+export interface AgentRenderBudget {
+  /** Maximum characters of the flagged element's text. */
+  readonly fieldMaxWidth: number;
+}
+
+/** The agent-facing render of a policy deny. */
+export function renderPolicyDenial(
+  payload: PromptPayload,
+  ruleReason: string | null,
+  budget: AgentRenderBudget = DEFAULT_RENDER_BUDGET,
+): string {
+  return tagged(
+    `Denied by policy: ${identification(payload, budget, "")}${boundaryClause(payload)}${provenanceClause(payload)}.`,
+    ruleReason,
+  );
+}
+
+/** The agent-facing render of a human's denial at an interactive prompt. */
+export function renderUserDenial(
+  payload: PromptPayload,
+  denialReason: string | null,
+  budget: AgentRenderBudget = DEFAULT_RENDER_BUDGET,
+): string {
+  return tagged(
+    `The user denied this ${identification(payload, budget, "call")}${boundaryClause(payload)}${provenanceClause(payload)}.`,
+    denialReason,
+  );
+}
+
+/** The agent-facing render when no live authority could answer the ask. */
+export function renderUnavailableDenial(
+  payload: PromptPayload,
+  denialReason: string | null,
+  budget: AgentRenderBudget = DEFAULT_RENDER_BUDGET,
+): string {
+  return tagged(
+    `This ${identification(payload, budget, "call")} requires approval, but no interactive UI is available.`,
+    denialReason,
+  );
+}
+
+// ── Sentence assembly ──────────────────────────────────────────────────────
+
+function tagged(sentence: string, reason: string | null): string {
+  return `${EXTENSION_TAG} ${sentence}${reasonClause(reason)}`;
+}
+
+/**
+ * What was refused, in the order a reader needs it: the gate surface, the tool
+ * that reached it, who asked, which of the call's operands was flagged, and the
+ * rule that fired.
+ *
+ * `callWord` is the noun the verdict needs after the surface — a user or
+ * unavailable verdict refuses a *call*, while a policy deny refuses the
+ * surface itself.
+ */
+function identification(
+  payload: PromptPayload,
+  budget: AgentRenderBudget,
+  callWord: string,
+): string {
+  return [
+    `'${payload.request.surface}'`,
+    callWord,
+    invokedAsClause(payload),
+    toolClause(payload),
+    agentClause(payload),
+    flaggedClause(payload, budget),
+    ruleClause(payload),
+  ]
+    .filter((clause) => clause !== "")
+    .join(" ");
+}
+
+/** The gated tool, named only when the surface has not already named it. */
+function toolClause(payload: PromptPayload): string {
+  const { toolName, surface } = payload.request;
+  return toolName === null || toolName === surface
+    ? ""
+    : `for tool '${toolName}'`;
+}
+
+/** The name the agent actually called, when a shell alias re-exposed bash. */
+function invokedAsClause(payload: PromptPayload): string {
+  const { invokedToolName } = payload.request;
+  return invokedToolName === null ? "" : `(invoked as '${invokedToolName}')`;
+}
+
+/** Which agent asked, when the ask carries a name. */
+function agentClause(payload: PromptPayload): string {
+  const { agentName } = payload.request.requester;
+  return agentName ? `for agent '${agentName}'` : "";
+}
+
+/**
+ * Which of the call's operands the rule fired on.
+ *
+ * Omitted for a bash ask, whose flagged element is the command §7 forbids
+ * echoing; for a generic tool ask, whose value is the tool name an earlier
+ * clause already stated; and for a payload-less forwarded relay, whose value
+ * shape is unknown, so it cannot be shown to not be a command.
+ */
+function flaggedClause(
+  payload: PromptPayload,
+  budget: AgentRenderBudget,
+): string {
+  if (payload.kind === "bash" || payload.kind === "forwarded") {
+    return "";
+  }
+  const label = flaggedElementLabel(payload);
+  const elements = flaggedElements(payload).filter(
+    (element) => element !== payload.request.toolName,
+  );
+  if (elements.length === 0) {
+    return "";
+  }
+  const noun = elements.length === 1 ? label : `${label}s`;
+  return `for ${noun} ${elements
+    .map(
+      (element) =>
+        `'${cap(element, budget)}'${resolvedAlias(payload, element)}`,
+    )
+    .join(", ")}`;
+}
+
+/** The canonical target of a flagged path, when it names somewhere else. */
+function resolvedAlias(payload: PromptPayload, element: string): string {
+  const resolved =
+    findEvidence(payload, "resolves to")?.text ??
+    allEvidence(payload, "external path").find(
+      (entry) => entry.text === element,
+    )?.detail;
+  return resolved ? ` (resolves to '${resolved}')` : "";
+}
+
+/** The rule that fired, with the nested context that makes it intelligible. */
+function ruleClause(payload: PromptPayload): string {
+  const { matchedPattern, commandContext } = payload.request;
+  const parts: string[] = [];
+  if (matchedPattern !== null) {
+    parts.push(`rule '${matchedPattern}'`);
+  }
+  const context = describeBashCommandContext(commandContext);
+  if (context !== undefined) {
+    parts.push(`inside ${context}`);
+  }
+  return parts.length > 0 ? `(${parts.join(", ")})` : "";
+}
+
+/** The working directory the flagged paths escaped. */
+function boundaryClause(payload: PromptPayload): string {
+  const cwd = findEvidence(payload, "working directory")?.text;
+  return cwd ? `: outside working directory '${cwd}'` : "";
+}
+
+/** The path a skill read reached its skill through. */
+function provenanceClause(payload: PromptPayload): string {
+  const readPath = findEvidence(payload, "read path")?.text;
+  return readPath ? `, reached via '${readPath}'` : "";
+}
+
+function reasonClause(reason: string | null): string {
+  return reason ? ` Reason: ${reason}.` : "";
+}
+
+/**
+ * Narrow the flagged element to the budget.
+ *
+ * The command is never rendered, so this bounds the only agent-supplied value
+ * that reaches the agent. A quantity bound applied uniformly, never a content
+ * filter, with the same bare-ellipsis marker the dialog uses (ADR 0011 §4).
+ */
+function cap(text: string, budget: AgentRenderBudget): string {
+  return text.length <= budget.fieldMaxWidth
+    ? text
+    : `${text.slice(0, budget.fieldMaxWidth)}\u2026`;
+}

package/src/presentation/dialog-renderer.ts

@@ -1,9 +1,10 @@
-import { describeBashCommandContext } from "#src/denial-messages";
-import { fitLinesToWidth } from "#src/presentation/line-fitting";
 import {
-  allEvidence,
-  type PromptPayload,
-} from "#src/presentation/prompt-payload";
+  describeBashCommandContext,
+  flaggedElements,
+  valueLabel,
+} from "#src/presentation/fact-vocabulary";
+import { fitLinesToWidth } from "#src/presentation/line-fitting";
+import type { PromptPayload } from "#src/presentation/prompt-payload";
 
 /**
  * Render a {@link PromptPayload} for a human deciding an ask (ADR 0011 §5).
@@ -31,7 +32,7 @@ export function renderPromptDialog(
   );
   const blocks = layout(
     [...core, ...evidence],
-    flaggedTexts(payload),
+    flaggedElements(payload),
     paint,
   ).map((block) => fitLinesToWidth(block, budget.width));
   const fitted = fitToRows(
@@ -122,21 +123,6 @@ export function completeViewBudget(width: number): DialogBudget {
 
 const plainText: HighlightPaint = (text) => text;
 
-/**
- * What the ask is flagging.
- *
- * The decision-relevant value for every shape but one: a bash ask that escaped
- * the working directory flags the paths it referenced, not the command that
- * referenced them — the command is the context, and the paths are what the
- * operator is ruling on.
- */
-function flaggedTexts(payload: PromptPayload): string[] {
-  if (payload.kind === "bash_external_directory") {
-    return allEvidence(payload, "external path").map((entry) => entry.text);
-  }
-  return payload.request.value === "" ? [] : [payload.request.value];
-}
-
 /** One rendered fact. */
 interface Fact {
   readonly label: string;
@@ -242,9 +228,7 @@ function coreFacts(payload: PromptPayload): Fact[] {
   if (request.executedUnit !== null) {
     facts.push({ label: "runs", text: request.executedUnit });
   }
-  const context = describeBashCommandContext(
-    request.commandContext ?? undefined,
-  );
+  const context = describeBashCommandContext(request.commandContext);
   if (context !== undefined) {
     facts.push({ label: "context", text: context });
   }
@@ -293,46 +277,6 @@ function toolText(payload: PromptPayload): string {
     : `${String(toolName)} (invoked as ${invokedToolName})`;
 }
 
-/** What the decision-relevant value is called, per ask shape. */
-function valueLabel(payload: PromptPayload): string {
-  switch (payload.kind) {
-    case "bash":
-    case "bash_external_directory":
-      return "command";
-    case "mcp":
-      return "target";
-    case "tool":
-      return "tool";
-    case "path":
-    case "external_directory":
-      return "path";
-    case "skill":
-    case "skill_read":
-      return "skill";
-    case "forwarded":
-      return forwardedValueLabel(payload.request.surface);
-  }
-}
-
-/**
- * A forwarded request carries the child's *display* projection — its tool name
- * as the surface — rather than the child's own payload, so the label is
- * inferred from it and falls back to a neutral one.
- *
- * Dissolves when the payload replaces `message` on the wire (#745): the
- * serving node will then hold the child's real `kind`.
- */
-function forwardedValueLabel(surface: string): string {
-  switch (surface) {
-    case "bash":
-      return "command";
-    case "skill":
-      return "skill";
-    default:
-      return "value";
-  }
-}
-
 /**
  * Align the labels into a `label : value` column.
  *

package/src/presentation/fact-vocabulary.ts

@@ -0,0 +1,103 @@
+import {
+  allEvidence,
+  type PromptPayload,
+} from "#src/presentation/prompt-payload";
+import type { BashCommandContext } from "#src/types";
+
+/**
+ * The render vocabulary shared by every renderer over a {@link PromptPayload}.
+ *
+ * Which element an ask flags, what that element is called, and how a nested
+ * execution context reads are all answers a render needs and none of them is
+ * a payload fact — the payload carries `value`, `kind`, and `commandContext`,
+ * and this module is where they acquire a name. It lives apart from any one
+ * renderer so the dialog, the agent-facing text, and the review log cannot
+ * disagree about what a given ask is flagging.
+ */
+
+/**
+ * What the ask is flagging.
+ *
+ * The decision-relevant value for every shape but one: a bash ask that escaped
+ * the working directory flags the paths it referenced, not the command that
+ * referenced them — the command is the context, and the paths are what the
+ * operator is ruling on.
+ */
+export function flaggedElements(payload: PromptPayload): readonly string[] {
+  if (payload.kind === "bash_external_directory") {
+    return allEvidence(payload, "external path").map((entry) => entry.text);
+  }
+  return payload.request.value === "" ? [] : [payload.request.value];
+}
+
+/**
+ * What {@link flaggedElements} returns is called.
+ *
+ * Differs from {@link valueLabel} for exactly one shape: a bash ask that
+ * escaped the working directory flags paths while its value is the command,
+ * so the two nouns are for two different things.
+ */
+export function flaggedElementLabel(payload: PromptPayload): string {
+  return payload.kind === "bash_external_directory"
+    ? "path"
+    : valueLabel(payload);
+}
+
+/** What the decision-relevant value is called, per ask shape. */
+export function valueLabel(payload: PromptPayload): string {
+  switch (payload.kind) {
+    case "bash":
+    case "bash_external_directory":
+      return "command";
+    case "mcp":
+      return "target";
+    case "tool":
+      return "tool";
+    case "path":
+    case "external_directory":
+      return "path";
+    case "skill":
+    case "skill_read":
+      return "skill";
+    case "forwarded":
+      return forwardedValueLabel(payload.request.surface);
+  }
+}
+
+/**
+ * Labels the version-skew render only: a payload-bearing forwarded ask carries
+ * the child's real `kind` and never reaches this arm (#745).
+ *
+ * Without a payload all that survives is the child's *display* projection — its
+ * tool name as the surface — so the label is inferred from it and falls back to
+ * a neutral one.
+ */
+function forwardedValueLabel(surface: string): string {
+  switch (surface) {
+    case "bash":
+      return "command";
+    case "skill":
+      return "skill";
+    default:
+      return "value";
+  }
+}
+
+/**
+ * Human-readable label for a nested bash execution context, or `undefined` for
+ * a current-shell (top-level) command.
+ */
+export function describeBashCommandContext(
+  context: BashCommandContext | null,
+): string | undefined {
+  switch (context) {
+    case "command_substitution":
+      return "command substitution";
+    case "process_substitution":
+      return "process substitution";
+    case "subshell":
+      return "subshell";
+    case null:
+      return undefined;
+  }
+}