@gotgenes/pi-permission-system 25.4.0 → 26.0.0

package/src/presentation/forwarded-ask-payload.ts

@@ -1,34 +1,56 @@
 import type { ForwardedPermissionRequest } from "#src/authority/permission-forwarding";
-import type { PromptPayload } from "#src/presentation/prompt-payload";
+import type {
+  PromptPayload,
+  PromptRequester,
+} from "#src/presentation/prompt-payload";
 
 /**
  * Build the payload for an ask forwarded up from a subagent.
  *
- * The child still ships a pre-rendered sentence, so the serving node carries it
- * as a single evidence entry rather than inventing facts it was not sent: what
- * arrives is prose, and calling it anything else would be a fiction the
- * bounded renderers would then have to trust.
+ * A projection, not a synthesizer: the child ships its own complete payload, so
+ * the serving node renders the child's facts under the *parent's* budget — which
+ * is what makes a forwarded ask and a local one consistent in kind, a forwarded
+ * bash ask reading `command : …` exactly as a local one does (ADR 0011 §2).
  *
- * When the payload replaces `message` on the wire, this builder projects the
- * child's own payload instead, and the serving node renders the child's facts
- * under its own budget — which is what makes a forwarded ask and a local one
- * consistent for the first time (ADR 0011 §2).
- *
- * A request missing a field renders from whatever it does carry: fail-closed
+ * A request carrying no payload renders from whatever it does hold: fail-closed
  * applies to presentation as it does to policy, so a version-skewed ask still
  * reaches the human rather than resolving without one (ADR 0011 §9).
  */
 export function buildForwardedAskPayload(
   request: ForwardedPermissionRequest,
+): PromptPayload {
+  // The child built its payload with `localRequester` — `forwarded: false`,
+  // `sessionId: null`. The serving node is the only party that knows the ask
+  // arrived over the wire, and the request's own provenance is authoritative
+  // (#292); everything else is the child's fact and passes through untouched.
+  const requester: PromptRequester = {
+    agentName: request.requesterAgentName,
+    forwarded: true,
+    sessionId: request.requesterSessionId,
+  };
+
+  return request.payload
+    ? {
+        ...request.payload,
+        request: { ...request.payload.request, requester },
+      }
+    : degradedForwardedPayload(request, requester);
+}
+
+/**
+ * The render for an ask that arrived without a payload.
+ *
+ * `kind: "forwarded"` narrows to meaning exactly this — not "an ask from a
+ * subagent", which every branch above is too.
+ */
+function degradedForwardedPayload(
+  request: ForwardedPermissionRequest,
+  requester: PromptRequester,
 ): PromptPayload {
   return {
     kind: "forwarded",
     request: {
-      requester: {
-        agentName: request.requesterAgentName,
-        forwarded: true,
-        sessionId: request.requesterSessionId,
-      },
+      requester,
       // The child's display projection: what the ask was about, as the child's
       // own gate named it.
       surface: request.surface ?? "",
@@ -39,7 +61,10 @@ export function buildForwardedAskPayload(
       commandContext: null,
       executedUnit: null,
     },
-    evidence: [{ label: "requested", text: request.message, detail: null }],
+    // Nothing to carry: the wire no longer relays a sentence, and inventing
+    // evidence the child never sent is exactly the fiction the bounded
+    // renderers would then have to trust.
+    evidence: [],
     annotations: [],
   };
 }

package/src/presentation/path-ask-payload.ts

@@ -1,10 +1,17 @@
-import type { ExternalPathDisclosure } from "#src/denial-messages";
 import type {
   PromptEvidence,
   PromptPayload,
 } from "#src/presentation/prompt-payload";
 import { localRequester } from "#src/presentation/prompt-payload";
 
+/** A displayed external path paired with its resolved target, when distinct. */
+export interface ExternalPathDisclosure {
+  /** The path as displayed (typed for tools, lexical-absolute for bash). */
+  path: string;
+  /** The canonical symlink-resolved target; present only when it differs. */
+  resolvedPath?: string;
+}
+
 /** The facts a path-shaped gate holds when it raises an ask. */
 interface PathAskFacts {
   toolName: string;

package/src/presentation/prompt-payload.ts

@@ -22,10 +22,10 @@ export interface PromptPayload {
  *
  * Present because the ask shapes are not separable by surface alone: a tool
  * external-directory ask and a bash one share the `external_directory` surface,
- * and the `path` gate and the per-tool gate differ only in wording. It mirrors
- * `DenialContext`'s discriminated union, the shape ADR 0011 §7 names as already
- * correct, and gives every renderer an exhaustive switch rather than a set of
- * string comparisons a new variant sails past.
+ * and the `path` gate and the per-tool gate differ only in wording. It gives
+ * every renderer an exhaustive switch rather than a set of string comparisons a
+ * new variant sails past — which is what let the parallel denial-context union
+ * ADR 0011 §7 described dissolve into this one (#746).
  */
 export type PromptPayloadKind =
   | "bash"
@@ -120,6 +120,167 @@ export function localRequester(agentName: string | null): PromptRequester {
   return { agentName, forwarded: false, sessionId: null };
 }
 
+/** Every {@link PromptPayloadKind}, for tolerant reads of a serialized payload. */
+const PROMPT_PAYLOAD_KINDS = [
+  "bash",
+  "mcp",
+  "tool",
+  "path",
+  "external_directory",
+  "bash_external_directory",
+  "skill",
+  "skill_read",
+  "forwarded",
+] as const satisfies readonly PromptPayloadKind[];
+
+const BASH_COMMAND_CONTEXTS = [
+  "command_substitution",
+  "process_substitution",
+  "subshell",
+] as const satisfies readonly BashCommandContext[];
+
+/**
+ * Narrow an unknown value to a {@link PromptPayload}, or `undefined`.
+ *
+ * Lives beside its type so a new request fact updates the guard next door
+ * rather than in a distant reader, following `isPermissionDecisionState`'s
+ * precedent.
+ *
+ * All-or-nothing: any malformed field yields `undefined` rather than a
+ * half-payload, so a consumer renders its own degraded view instead of
+ * presenting corrupt facts (ADR 0011 §9).
+ */
+export function asPromptPayload(value: unknown): PromptPayload | undefined {
+  const candidate = asObject(value);
+  if (!candidate) return undefined;
+
+  const kind = PROMPT_PAYLOAD_KINDS.find((entry) => entry === candidate.kind);
+  const request = asPromptRequestFacts(candidate.request);
+  const evidence = asArrayOf(candidate.evidence, asPromptEvidence);
+  const annotations = asArrayOf(candidate.annotations, asPromptAnnotation);
+  if (!kind || !request || !evidence || !annotations) return undefined;
+
+  return { kind, request, evidence, annotations };
+}
+
+function asPromptRequestFacts(value: unknown): PromptRequestFacts | undefined {
+  const candidate = asObject(value);
+  if (!candidate) return undefined;
+
+  const requester = asPromptRequester(candidate.requester);
+  const commandContext = asNullableMember(
+    candidate.commandContext,
+    BASH_COMMAND_CONTEXTS,
+  );
+  if (
+    !requester ||
+    commandContext === undefined ||
+    typeof candidate.surface !== "string" ||
+    typeof candidate.value !== "string" ||
+    !isNullableString(candidate.toolName) ||
+    !isNullableString(candidate.invokedToolName) ||
+    !isNullableString(candidate.matchedPattern) ||
+    !isNullableString(candidate.executedUnit)
+  ) {
+    return undefined;
+  }
+
+  return {
+    requester,
+    surface: candidate.surface,
+    toolName: candidate.toolName,
+    invokedToolName: candidate.invokedToolName,
+    value: candidate.value,
+    matchedPattern: candidate.matchedPattern,
+    commandContext: commandContext.value,
+    executedUnit: candidate.executedUnit,
+  };
+}
+
+function asPromptRequester(value: unknown): PromptRequester | undefined {
+  const candidate = asObject(value);
+  if (
+    !candidate ||
+    typeof candidate.forwarded !== "boolean" ||
+    !isNullableString(candidate.agentName) ||
+    !isNullableString(candidate.sessionId)
+  ) {
+    return undefined;
+  }
+  return {
+    agentName: candidate.agentName,
+    forwarded: candidate.forwarded,
+    sessionId: candidate.sessionId,
+  };
+}
+
+function asPromptEvidence(value: unknown): PromptEvidence | undefined {
+  const candidate = asObject(value);
+  if (
+    !candidate ||
+    typeof candidate.label !== "string" ||
+    typeof candidate.text !== "string" ||
+    !isNullableString(candidate.detail)
+  ) {
+    return undefined;
+  }
+  return {
+    label: candidate.label,
+    text: candidate.text,
+    detail: candidate.detail,
+  };
+}
+
+function asPromptAnnotation(value: unknown): PromptAnnotation | undefined {
+  const candidate = asObject(value);
+  if (
+    !candidate ||
+    typeof candidate.source !== "string" ||
+    typeof candidate.text !== "string"
+  ) {
+    return undefined;
+  }
+  return { source: candidate.source, text: candidate.text };
+}
+
+function asObject(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === "object" && value !== null
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
+/** Narrow every entry, or `undefined` when the array or any entry is malformed. */
+function asArrayOf<T>(
+  value: unknown,
+  narrow: (entry: unknown) => T | undefined,
+): T[] | undefined {
+  if (!Array.isArray(value)) return undefined;
+  const narrowed: T[] = [];
+  for (const entry of value) {
+    const result = narrow(entry);
+    if (!result) return undefined;
+    narrowed.push(result);
+  }
+  return narrowed;
+}
+
+function isNullableString(value: unknown): value is string | null {
+  return value === null || typeof value === "string";
+}
+
+/**
+ * Narrow to `null` or a member of `members`, boxed so a valid `null` is
+ * distinguishable from the malformed `undefined`.
+ */
+function asNullableMember<T extends string>(
+  value: unknown,
+  members: readonly T[],
+): { value: T | null } | undefined {
+  if (value === null) return { value: null };
+  const member = members.find((entry) => entry === value);
+  return member ? { value: member } : undefined;
+}
+
 /** Find the evidence entry a renderer knows by label. */
 export function findEvidence(
   payload: PromptPayload,

package/src/presentation/review-log-renderer.ts

@@ -0,0 +1,51 @@
+import type { PromptPayload } from "#src/presentation/prompt-payload";
+
+/**
+ * The payload facts the permission review log persists (ADR 0011 §6).
+ *
+ * The log is a renderer over the payload like any other, and this is its
+ * content decision: the request facts, and only those the log's own structured
+ * columns do not already carry. `toolName`, `command`, `path`, `target`, and
+ * `toolInputPreview` are written by the gates; restating them under a second
+ * name would grow the log rather than sharpen it.
+ *
+ * Evidence and annotations are deliberately absent.
+ * `docs/decisions/0010-permission-log-secret-exposure.md` bounds what the logs
+ * accumulate, and evidence is exactly the unbounded part — the point of this
+ * render is that the log's growth is a decision, not a side effect of how a
+ * prompt happened to be worded.
+ *
+ * A fact the ask does not carry is omitted rather than written as `null`, so a
+ * line states what was true rather than enumerating what was not.
+ */
+export function renderReviewLogFacts(
+  payload: PromptPayload,
+): Record<string, unknown> {
+  const { request } = payload;
+  return {
+    surface: request.surface,
+    ...present("matchedPattern", request.matchedPattern),
+    ...present("executedUnit", request.executedUnit),
+    ...present("commandContext", request.commandContext),
+    ...present("invokedToolName", request.invokedToolName),
+    ...forwardingFacts(payload),
+  };
+}
+
+/**
+ * Where the ask came from, when it came from somewhere else.
+ *
+ * A local ask is the default and states nothing; a forwarded one names the
+ * session that raised it, so a decision can be correlated back to the child
+ * that asked.
+ */
+function forwardingFacts(payload: PromptPayload): Record<string, unknown> {
+  const { forwarded, sessionId } = payload.request.requester;
+  return forwarded
+    ? { forwarded: true, ...present("requesterSessionId", sessionId) }
+    : {};
+}
+
+function present<T>(key: string, value: T | null): Record<string, T> {
+  return value === null ? {} : { [key]: value };
+}

package/src/service.ts

@@ -49,6 +49,17 @@ export {
   PERMISSIONS_READY_CHANNEL,
   PERMISSIONS_UI_PROMPT_CHANNEL,
 } from "./permission-events";
+// The declaration bundle already inlines these through `PromptPermissionDetails`
+// and `PermissionUiPromptEvent`; the named exports are what a consumer needs to
+// annotate a variable of their own.
+export type {
+  PromptAnnotation,
+  PromptEvidence,
+  PromptPayload,
+  PromptPayloadKind,
+  PromptRequester,
+  PromptRequestFacts,
+} from "./presentation/prompt-payload";
 export type { PermissionCheckResult, PermissionState, ToolInputFormatter };
 
 /** Process-global key for the service slot. */

package/src/tool-input-preview.ts

@@ -2,7 +2,6 @@ import { safeJsonStringify } from "./json-safe-stringify";
 import { redactedJsonStringify } from "./log-redaction";
 
 export const TOOL_INPUT_PREVIEW_MAX_LENGTH = 200;
-export const TOOL_INPUT_LOG_PREVIEW_MAX_LENGTH = 1000;
 export const TOOL_TEXT_SUMMARY_MAX_LENGTH = 80;
 
 export function truncateInlineText(value: string, maxLength: number): string {

package/src/tool-preview-formatter.ts

@@ -1,10 +1,8 @@
 import { classifyToolKind, isMcpCheck } from "./access-intent/tool-kind";
-import type { PermissionSystemExtensionConfig } from "./extension-config";
 import type { ToolInputFormatterLookup } from "./tool-input-formatter-registry";
 import {
   serializeRedactedToolInputPreview,
   serializeToolInputPreview,
-  TOOL_INPUT_LOG_PREVIEW_MAX_LENGTH,
   TOOL_INPUT_PREVIEW_MAX_LENGTH,
   TOOL_TEXT_SUMMARY_MAX_LENGTH,
   truncateInlineText,
@@ -21,27 +19,21 @@ import { getNonEmptyString, toRecord } from "./value-guards";
 export interface ToolPreviewFormatterOptions {
   toolInputPreviewMaxLength: number;
   toolTextSummaryMaxLength: number;
-  toolInputLogPreviewMaxLength: number;
 }
 
-type ConfigurablePreviewLimits = Pick<
-  PermissionSystemExtensionConfig,
-  "toolInputPreviewMaxLength" | "toolTextSummaryMaxLength"
->;
-
 /**
- * Resolve `ToolPreviewFormatterOptions` from a config object, falling back to
- * the built-in defaults for any field that is absent.
+ * The built-in `ToolPreviewFormatterOptions`.
+ *
+ * Takes no config: `toolInputPreviewMaxLength` and `toolTextSummaryMaxLength`
+ * are subsumed by the renderer budgets (`promptMaxRows` / `promptFieldMaxWidth`,
+ * ADR 0011 §5), so an operator's values no longer take effect. The constants
+ * remain because they still shape a *prompt* preview; what the review log
+ * persists is bounded by `reviewLogFieldMaxWidth` at the writer instead.
  */
-export function resolveToolPreviewLimits(
-  config: ConfigurablePreviewLimits,
-): ToolPreviewFormatterOptions {
+export function resolveToolPreviewLimits(): ToolPreviewFormatterOptions {
   return {
-    toolInputPreviewMaxLength:
-      config.toolInputPreviewMaxLength ?? TOOL_INPUT_PREVIEW_MAX_LENGTH,
-    toolTextSummaryMaxLength:
-      config.toolTextSummaryMaxLength ?? TOOL_TEXT_SUMMARY_MAX_LENGTH,
-    toolInputLogPreviewMaxLength: TOOL_INPUT_LOG_PREVIEW_MAX_LENGTH,
+    toolInputPreviewMaxLength: TOOL_INPUT_PREVIEW_MAX_LENGTH,
+    toolTextSummaryMaxLength: TOOL_TEXT_SUMMARY_MAX_LENGTH,
   };
 }
 
@@ -147,14 +139,16 @@ export class ToolPreviewFormatter {
   // ── Log formatting ──────────────────────────────────────────────────────
 
   /**
-   * Serialize `input` to inline JSON and truncate at
-   * `toolInputLogPreviewMaxLength`, masking sensitive-keyed values.
+   * Serialize `input` to inline JSON for the review log, masking
+   * sensitive-keyed values.
+   *
+   * Unbounded here: the writer narrows every field it persists to
+   * `reviewLogFieldMaxWidth`, so a second bound at the producer would be a
+   * limit the operator cannot see or change.
    */
   formatGenericToolInputForLog(input: unknown): string | undefined {
     const inline = serializeRedactedToolInputPreview(input);
-    return inline
-      ? `input ${truncateInlineText(inline, this.options.toolInputLogPreviewMaxLength)}`
-      : undefined;
+    return inline ? `input ${inline}` : undefined;
   }
 
   /** Derive a loggable input preview string for the review log. */
@@ -168,16 +162,7 @@ export class ToolPreviewFormatter {
     }
 
     if (pathBearingTools.has(result.toolName)) {
-      const inputPreview = this.formatToolInputForPrompt(
-        result.toolName,
-        input,
-      );
-      return inputPreview
-        ? truncateInlineText(
-            inputPreview,
-            this.options.toolInputLogPreviewMaxLength,
-          )
-        : undefined;
+      return this.formatToolInputForPrompt(result.toolName, input) || undefined;
     }
 
     return this.formatGenericToolInputForLog(input);