@gotgenes/pi-permission-system 25.3.0 → 26.0.0

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

package/src/denial-messages.ts

@@ -1,269 +0,0 @@
-import { classifyToolKind, isMcpCheck } from "./access-intent/tool-kind";
-import { EXTENSION_ID } from "./extension-config";
-import type { BashCommandContext, PermissionCheckResult } from "./types";
-
-// ── Extension attribution tag ──────────────────────────────────────────────
-
-export const EXTENSION_TAG = `[${EXTENSION_ID}]`;
-
-// ── External-path resolved-target disclosure ────────────────────────────────
-
-/** 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;
-}
-
-/** ` (resolves to '<canonical>')` when a distinct target exists, else `""`. */
-export function resolvesToSuffix(resolvedPath?: string): string {
-  return resolvedPath ? ` (resolves to '${resolvedPath}')` : "";
-}
-
-// ── Denial context discriminated union ─────────────────────────────────────
-
-export type DenialContext =
-  | {
-      kind: "tool";
-      check: PermissionCheckResult;
-      agentName?: string;
-      input?: unknown;
-    }
-  | {
-      kind: "path";
-      toolName: string;
-      pathValue: string;
-      agentName?: string;
-    }
-  | {
-      kind: "external_directory";
-      toolName: string;
-      pathValue: string;
-      resolvedPath?: string;
-      cwd: string;
-      agentName?: string;
-    }
-  | {
-      kind: "bash_external_directory";
-      command: string;
-      externalPaths: ExternalPathDisclosure[];
-      cwd: string;
-      agentName?: string;
-    }
-  | {
-      kind: "bash_path";
-      command: string;
-      pathValue: string;
-      agentName?: string;
-    }
-  | {
-      kind: "skill_read";
-      skillName: string;
-      readPath: string;
-      agentName?: string;
-    }
-  | {
-      kind: "skill_input";
-      skillName: string;
-      agentName?: string;
-    };
-
-// ── Public formatter API ───────────────────────────────────────────────────
-
-/** Format the block reason when permission policy denies an operation. */
-export function formatDenyReason(ctx: DenialContext): string {
-  return `${EXTENSION_TAG} ${buildDenyBody(ctx)}`;
-}
-
-/**
- * Format the block reason when no live authority could answer the ask.
- *
- * `denialReason` is optional because the plain no-UI case has nothing to add;
- * an authority that abandoned for a specific reason (a forwarding target that
- * is not serving, a request that could not be written) supplies one, and the
- * model sees it (#719).
- */
-export function formatUnavailableReason(
-  ctx: DenialContext,
-  denialReason?: string,
-): string {
-  return `${EXTENSION_TAG} ${buildUnavailableBody(ctx, denialReason)}`;
-}
-
-/** Format the block reason when the user denies at an interactive prompt. */
-export function formatUserDeniedReason(
-  ctx: DenialContext,
-  denialReason?: string,
-): string {
-  return `${EXTENSION_TAG} ${buildUserDeniedBody(ctx, denialReason)}`;
-}
-
-// ── Private body builders ──────────────────────────────────────────────────
-
-function subject(agentName?: string): string {
-  return agentName ? `Agent '${agentName}'` : "Current agent";
-}
-
-function reasonSuffix(denialReason?: string): string {
-  return denialReason ? ` Reason: ${denialReason}.` : "";
-}
-
-function buildDenyBody(ctx: DenialContext): string {
-  switch (ctx.kind) {
-    case "tool":
-      return buildToolDenyBody(ctx);
-    case "path":
-      return `${subject(ctx.agentName)} is not permitted to access path '${ctx.pathValue}' via tool '${ctx.toolName}'.`;
-    case "external_directory":
-      return `${subject(ctx.agentName)} is not permitted to run tool '${ctx.toolName}' for path '${ctx.pathValue}'${resolvesToSuffix(ctx.resolvedPath)} outside working directory '${ctx.cwd}'.`;
-    case "bash_external_directory":
-      return `${subject(ctx.agentName)} is not permitted to run bash command '${ctx.command}' which references path(s) outside working directory '${ctx.cwd}': ${formatExternalPathList(ctx.externalPaths)}.`;
-    case "bash_path":
-      return `${subject(ctx.agentName)} is not permitted to access path '${ctx.pathValue}' via tool 'bash'.`;
-    case "skill_read":
-      return `${subject(ctx.agentName)} is not permitted to access skill '${ctx.skillName}' via '${ctx.readPath}'.`;
-    case "skill_input":
-      return `${subject(ctx.agentName)} is not permitted to access skill '${ctx.skillName}'.`;
-  }
-}
-
-function buildToolDenyBody(
-  ctx: Extract<DenialContext, { kind: "tool" }>,
-): string {
-  const parts: string[] = [];
-  const { check, agentName } = ctx;
-
-  if (agentName) {
-    parts.push(`Agent '${agentName}'`);
-  }
-
-  if (isMcpCheck(check) && check.target) {
-    parts.push(`is not permitted to run MCP target '${check.target}'`);
-  } else {
-    parts.push(`is not permitted to run '${check.toolName}'`);
-  }
-
-  if (check.command) {
-    parts.push(`command '${check.command}'`);
-  }
-
-  const qualifier = matchQualifier(check.matchedPattern, check.commandContext);
-  if (qualifier) {
-    parts.push(qualifier);
-  }
-
-  // reasonSuffix appends ` Reason: <reason>.` after the sentence-ending period.
-  return `${parts.join(" ")}.${reasonSuffix(check.reason)}`;
-}
-
-/**
- * Human-readable label for a nested bash execution context, or `undefined` for
- * a current-shell (top-level) command.
- */
-export function describeBashCommandContext(
-  context?: BashCommandContext,
-): string | undefined {
-  switch (context) {
-    case "command_substitution":
-      return "command substitution";
-    case "process_substitution":
-      return "process substitution";
-    case "subshell":
-      return "subshell";
-    default:
-      return undefined;
-  }
-}
-
-/**
- * Build the parenthetical qualifier for a bash decision, folding the matched
- * rule and (for a nested command) its execution context into one clause, e.g.
- * `(matched 'rm *', inside command substitution)`. Returns `""` when neither
- * applies.
- */
-export function matchQualifier(
-  matchedPattern?: string,
-  context?: BashCommandContext,
-): string {
-  const parts: string[] = [];
-  if (matchedPattern) {
-    parts.push(`matched '${matchedPattern}'`);
-  }
-  const label = describeBashCommandContext(context);
-  if (label) {
-    parts.push(`inside ${label}`);
-  }
-  return parts.length > 0 ? `(${parts.join(", ")})` : "";
-}
-
-function buildUnavailableBody(
-  ctx: DenialContext,
-  denialReason?: string,
-): string {
-  return `${buildUnavailableSentence(ctx)}${reasonSuffix(denialReason)}`;
-}
-
-function buildUnavailableSentence(ctx: DenialContext): string {
-  switch (ctx.kind) {
-    case "tool": {
-      const { check } = ctx;
-      if (classifyToolKind(check.toolName) === "bash" && check.command) {
-        return `Running bash command '${check.command}' requires approval, but no interactive UI is available.`;
-      }
-      if (isMcpCheck(check) && check.target) {
-        return "Using tool 'mcp' requires approval, but no interactive UI is available.";
-      }
-      return `Using tool '${check.toolName}' requires approval, but no interactive UI is available.`;
-    }
-    case "path":
-      return `Accessing '${ctx.pathValue}' requires approval, but no interactive UI is available.`;
-    case "external_directory":
-      return `Accessing '${ctx.pathValue}'${resolvesToSuffix(ctx.resolvedPath)} outside the working directory requires approval, but no interactive UI is available.`;
-    case "bash_external_directory":
-      return `Bash command '${ctx.command}' references path(s) outside the working directory and requires approval, but no interactive UI is available.`;
-    case "bash_path":
-      return `Bash command '${ctx.command}' accesses path '${ctx.pathValue}' which requires approval, but no interactive UI is available.`;
-    case "skill_read":
-      return `Accessing skill '${ctx.skillName}' requires approval, but no interactive UI is available.`;
-    case "skill_input":
-      return `Accessing skill '${ctx.skillName}' requires approval, but no interactive UI is available.`;
-  }
-}
-
-function buildUserDeniedBody(
-  ctx: DenialContext,
-  denialReason?: string,
-): string {
-  switch (ctx.kind) {
-    case "tool": {
-      const { check } = ctx;
-      if (isMcpCheck(check) && check.target) {
-        return `User denied MCP target '${check.target}'.${reasonSuffix(denialReason)}`;
-      }
-      if (classifyToolKind(check.toolName) === "bash" && check.command) {
-        return `User denied bash command '${check.command}'.${reasonSuffix(denialReason)}`;
-      }
-      return `User denied tool '${check.toolName}'.${reasonSuffix(denialReason)}`;
-    }
-    case "path":
-      return `User denied access to path '${ctx.pathValue}'.${reasonSuffix(denialReason)}`;
-    case "external_directory":
-      return `User denied external directory access for tool '${ctx.toolName}' path '${ctx.pathValue}'${resolvesToSuffix(ctx.resolvedPath)}.${reasonSuffix(denialReason)}`;
-    case "bash_external_directory":
-      return `User denied external directory access for bash command '${ctx.command}'.${reasonSuffix(denialReason)}`;
-    case "bash_path":
-      return `User denied path access for bash command '${ctx.command}' (path '${ctx.pathValue}').${reasonSuffix(denialReason)}`;
-    case "skill_read":
-      return `User denied access to skill '${ctx.skillName}'.${reasonSuffix(denialReason)}`;
-    case "skill_input":
-      return `User denied access to skill '${ctx.skillName}'.${reasonSuffix(denialReason)}`;
-  }
-}
-
-/** Render an external-path disclosure list for the bash deny body's path clause. */
-function formatExternalPathList(paths: ExternalPathDisclosure[]): string {
-  return paths
-    .map(({ path, resolvedPath }) => `${path}${resolvesToSuffix(resolvedPath)}`)
-    .join(", ");
-}