@gotgenes/pi-permission-system 25.4.0 → 26.1.0

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

@@ -1,7 +1,6 @@
 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";
@@ -46,6 +45,8 @@ export function describeExternalDirectoryGate(
   if (normalizer.isInfrastructureRead(tcc.toolName, accessPath, infraDirs)) {
     return {
       action: "allow",
+      // Containment allowed this, not a rule the operator wrote.
+      decidedBy: { kind: "infrastructure_read" },
       log: {
         event: "permission_request.infrastructure_auto_allowed",
         details: {
@@ -87,26 +88,16 @@ export function describeExternalDirectoryGate(
     agentName: tcc.agentName,
     matchedPattern: preCheck.matchedPattern,
   });
-  const extDirMessage = renderLegacyMessage(payload);
 
   return {
     surface: "external_directory",
     input: {},
     preCheck,
-    denialContext: {
-      kind: "external_directory",
-      toolName: tcc.toolName,
-      pathValue: externalDirectoryPath,
-      resolvedPath: resolvedAlias,
-      cwd: tcc.cwd,
-      agentName: tcc.agentName ?? undefined,
-    },
+    payload,
     sessionApproval: SessionApproval.single("external_directory", pattern),
     promptDetails: {
       source: "tool_call",
       agentName: tcc.agentName,
-      message: extDirMessage,
-      payload,
       toolCallId: tcc.toolCallId,
       toolName: tcc.toolName,
       path: externalDirectoryPath,
@@ -118,7 +109,6 @@ export function describeExternalDirectoryGate(
       toolName: tcc.toolName,
       agentName: tcc.agentName,
       path: externalDirectoryPath,
-      message: extDirMessage,
     },
     decision: {
       surface: "external_directory",

package/src/handlers/gates/path.ts

@@ -1,7 +1,6 @@
 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";
@@ -59,18 +58,11 @@ export function describePathGate(
   const descriptor: GateDescriptor = {
     surface: "path",
     input: { path: filePath },
-    denialContext: {
-      kind: "path",
-      toolName: tcc.toolName,
-      pathValue: filePath,
-      agentName: tcc.agentName ?? undefined,
-    },
+    payload,
     sessionApproval: SessionApproval.single("path", pattern),
     promptDetails: {
       source: "tool_call",
       agentName: tcc.agentName,
-      message: renderLegacyMessage(payload),
-      payload,
       toolCallId: tcc.toolCallId,
       toolName: tcc.toolName,
       path: filePath,

package/src/handlers/gates/runner.ts

@@ -1,14 +1,15 @@
 import type { AskEscalator } from "#src/authority/authorizer-selection";
 import type { PermissionPromptDecision } from "#src/authority/permission-dialog";
 import type { DecisionReporter } from "#src/decision-reporter";
-import {
-  formatDenyReason,
-  formatUnavailableReason,
-  formatUserDeniedReason,
-} from "#src/denial-messages";
 import { applyPermissionGate } from "#src/permission-gate";
 import { createPermissionRequestId } from "#src/permission-request-id";
 import type { ScopedPermissionResolver } from "#src/permission-resolver";
+import {
+  renderPolicyDenial,
+  renderUnavailableDenial,
+  renderUserDenial,
+} from "#src/presentation/agent-renderer";
+import { renderReviewLogFacts } from "#src/presentation/review-log-renderer";
 import type { SessionApprovalRecorder } from "#src/session-approval-recorder";
 import type { PermissionCheckResult } from "#src/types";
 import type {
@@ -65,6 +66,7 @@ export class GateRunner {
         this.reporter.writeReviewLog(gate.log.event, {
           ...gate.log.details,
           requestId,
+          decidedBy: gate.decidedBy,
         });
       }
       if (gate.decision) {
@@ -111,8 +113,21 @@ export class GateRunner {
     }
 
     // The fields every review-log write for this gate shares, whatever the
-    // resolution — built once so a field added here reaches all of them.
-    const logContext = { ...descriptor.logContext, agentName, requestId };
+    // resolution — built once so a field added here reaches all of them. The
+    // payload's request facts are stamped here rather than by each gate, for
+    // the same reason `requestId` is: a gate cannot forget what it never
+    // supplies (ADR 0011 §6).
+    const logContext = {
+      ...descriptor.logContext,
+      ...renderReviewLogFacts(descriptor.payload),
+      agentName,
+      requestId,
+    };
+
+    // Each resolution below states its own decider. The provenance is built
+    // at the branch that decides rather than merged into `logContext`: that
+    // context holds what every resolution of this gate shares, and who decided
+    // is by definition not shared (#726).
 
     // 2. Session-hit fast path
     if (check.source === "session") {
@@ -120,6 +135,11 @@ export class GateRunner {
         ...logContext,
         resolution: "session_approved",
         sessionApprovalPattern: check.matchedPattern,
+        decidedBy: {
+          kind: "session_approval",
+          surface: descriptor.surface,
+          pattern: check.matchedPattern ?? null,
+        },
       });
       this.emitDecision(
         requestId,
@@ -143,6 +163,9 @@ export class GateRunner {
       this.reporter.writeReviewLog("permission_request.auto_approved", {
         ...logContext,
         resolution: "auto_approved",
+        // The pattern that raised the ask, sentinel included: "yolo allowed
+        // it" alone does not say why it was asked in the first place.
+        decidedBy: { kind: "yolo", pattern: check.matchedPattern ?? null },
       });
       this.emitDecision(
         requestId,
@@ -160,16 +183,16 @@ export class GateRunner {
     // 3. Apply the deny/ask/allow gate — always escalate on ask; the selected
     // Authorizer answers (the DenyingAuthorizer by denying with a marker).
 
-    // Construct messages from the centralized formatter.
+    // The agent-facing renders of this ask. The rule reason is the operator's
+    // deny-with-reason text, which lives on the resolved check rather than the
+    // payload: no human render wants it, because a deny never prompts.
+    const { payload } = descriptor;
     const messages = {
-      denyReason: formatDenyReason(descriptor.denialContext),
+      denyReason: renderPolicyDenial(payload, check.reason ?? null),
       unavailableReason: (decision: PermissionPromptDecision) =>
-        formatUnavailableReason(
-          descriptor.denialContext,
-          decision.denialReason,
-        ),
+        renderUnavailableDenial(payload, decision.denialReason ?? null),
       userDeniedReason: (decision: PermissionPromptDecision) =>
-        formatUserDeniedReason(descriptor.denialContext, decision.denialReason),
+        renderUserDenial(payload, decision.denialReason ?? null),
     };
 
     let autoApproved = false;
@@ -180,6 +203,7 @@ export class GateRunner {
       promptForApproval: async () => {
         const decision = await this.prompter.escalate({
           requestId,
+          payload,
           ...descriptor.promptDetails,
           ...(descriptor.sessionApproval
             ? { sessionApproval: descriptor.sessionApproval.toForwardedData() }
@@ -192,6 +216,12 @@ export class GateRunner {
       writeLog: (event, details) =>
         this.reporter.writeReviewLog(event, details),
       logContext,
+      decidedByRule: {
+        kind: "rule",
+        surface: descriptor.surface,
+        pattern: check.matchedPattern ?? null,
+        origin: check.origin,
+      },
       messages,
     });
 

package/src/handlers/gates/skill-input-gate-pipeline.ts

@@ -80,8 +80,8 @@ export class SkillInputGatePipeline {
  * Format the deny warning shown in the UI when a skill is blocked.
  *
  * Intentionally untagged (no `[pi-permission-system]` prefix) — this is a
- * UI notify distinct from the gate deny reasons the runner routes through
- * `formatDenyReason`.
+ * UI notify distinct from the agent-facing deny reasons the runner routes
+ * through `renderPolicyDenial`.
  */
 export function formatSkillDenyNotice(
   skillName: string,

package/src/handlers/gates/skill-input.ts

@@ -1,4 +1,3 @@
-import { renderLegacyMessage } from "#src/presentation/legacy-message";
 import { buildSkillAskPayload } from "#src/presentation/skill-ask-payload";
 import type { PermissionCheckResult } from "#src/types";
 import type { GateDescriptor } from "./descriptor";
@@ -17,21 +16,14 @@ export function describeSkillInputGate(
   preCheck: PermissionCheckResult,
 ): GateDescriptor {
   const payload = buildSkillAskPayload(skillName, agentName);
-  const message = renderLegacyMessage(payload);
   return {
     surface: "skill",
     input: { name: skillName },
     preCheck,
-    denialContext: {
-      kind: "skill_input",
-      skillName,
-      agentName: agentName ?? undefined,
-    },
+    payload,
     promptDetails: {
       source: "skill_input",
       agentName,
-      message,
-      payload,
       skillName,
       accessIntent: accessFactsFromValue("skill", skillName),
     },
@@ -39,7 +31,6 @@ export function describeSkillInputGate(
       source: "skill_input",
       skillName,
       agentName,
-      message,
     },
     decision: {
       surface: "skill",

package/src/handlers/gates/skill-read.ts

@@ -1,5 +1,4 @@
 import type { PathNormalizer } from "#src/path-normalizer";
-import { renderLegacyMessage } from "#src/presentation/legacy-message";
 import { buildSkillPathAskPayload } from "#src/presentation/skill-ask-payload";
 import type { SkillPromptEntry } from "#src/skill-prompt-sanitizer";
 import { findSkillPathMatch } from "#src/skill-prompt-sanitizer";
@@ -44,22 +43,14 @@ export function describeSkillReadGate(
   }
 
   const payload = buildSkillPathAskPayload(matchedSkill, path, tcc.agentName);
-  const skillReadMessage = renderLegacyMessage(payload);
 
   return {
     surface: "skill",
     input: { name: matchedSkill.name },
-    denialContext: {
-      kind: "skill_read",
-      skillName: matchedSkill.name,
-      readPath: path,
-      agentName: tcc.agentName ?? undefined,
-    },
+    payload,
     promptDetails: {
       source: "skill_read",
       agentName: tcc.agentName,
-      message: skillReadMessage,
-      payload,
       toolCallId: tcc.toolCallId,
       toolName: tcc.toolName,
       skillName: matchedSkill.name,
@@ -72,7 +63,6 @@ export function describeSkillReadGate(
       skillName: matchedSkill.name,
       agentName: tcc.agentName,
       path,
-      message: skillReadMessage,
     },
     decision: {
       surface: "skill",

package/src/handlers/gates/tool.ts

@@ -6,7 +6,6 @@ import {
   type ShellInvocation,
 } from "#src/access-intent/tool-kind";
 import { suggestSessionPattern } from "#src/pattern-suggest";
-import { renderLegacyMessage } from "#src/presentation/legacy-message";
 import { buildToolAskPayload } from "#src/presentation/tool-ask-payload";
 import { SessionApproval } from "#src/session-approval";
 import type { ToolPreviewFormatter } from "#src/tool-preview-formatter";
@@ -81,7 +80,6 @@ export function describeToolGate(
     input: tcc.input,
     formatter,
   });
-  const askMessage = renderLegacyMessage(payload);
 
   const decisionValue = deriveDecisionValue(
     gateSurface,
@@ -98,12 +96,7 @@ export function describeToolGate(
   return {
     surface: gateSurface,
     input: tcc.input,
-    denialContext: {
-      kind: "tool",
-      check,
-      agentName: tcc.agentName ?? undefined,
-      input: tcc.input,
-    },
+    payload,
     sessionApproval: SessionApproval.single(
       suggestion.surface,
       suggestion.pattern,
@@ -111,8 +104,6 @@ export function describeToolGate(
     promptDetails: {
       source: "tool_call",
       agentName: tcc.agentName,
-      message: askMessage,
-      payload,
       toolCallId: tcc.toolCallId,
       toolName: tcc.toolName,
       sessionLabel: suggestion.label,
@@ -123,7 +114,6 @@ export function describeToolGate(
       source: "tool_call",
       toolCallId: tcc.toolCallId,
       toolName: tcc.toolName,
-      message: askMessage,
       ...permissionLogContext,
     },
     decision: {

package/src/handlers/tool-call-boundary.ts

@@ -76,12 +76,15 @@ function recordGateError(
 ): void {
   try {
     audit.recordError();
+    const reason = errorMessage(error);
     reporter.writeReviewLog("permission_request.blocked", {
       requestId: createPermissionRequestId(),
       toolName: bestEffortToolName(event),
       command: bestEffortCommand(event),
       resolution: "gate_error",
-      error: errorMessage(error),
+      error: reason,
+      // The boundary decided, by failing closed -- no rule and no human did.
+      decidedBy: { kind: "gate_error", reason },
     });
   } catch {
     // The block is the guarantee; its bookkeeping is not.

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-gate.ts

@@ -1,3 +1,4 @@
+import type { DecisionSource } from "#src/authority/decision-source";
 import type { PermissionPromptDecision } from "#src/authority/permission-dialog";
 
 /** Result of applying the permission gate. */
@@ -30,6 +31,15 @@ export interface PermissionGateParams {
   /** Log context fields shared across all log calls for this gate. */
   logContext: Record<string, unknown>;
 
+  /**
+   * The rule that resolved this gate, for the deny arm's review entry.
+   *
+   * A sibling of `logContext` rather than a member of it: the context holds
+   * what every resolution of this gate shares, and the decider is by
+   * definition not shared (#726).
+   */
+  decidedByRule: DecisionSource;
+
   /** Message strings/factories for each outcome. */
   messages: {
     denyReason: string;
@@ -52,6 +62,7 @@ export async function applyPermissionGate(
     writeLog("permission_request.blocked", {
       ...logContext,
       resolution: "policy_denied",
+      decidedBy: params.decidedByRule,
     });
     return { action: "block", reason: messages.denyReason };
   }

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,
   };
 }