@gotgenes/pi-permission-system 25.2.2 → 25.3.0

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

@@ -0,0 +1,128 @@
+import type { ExternalPathDisclosure } from "#src/denial-messages";
+import type {
+  PromptEvidence,
+  PromptPayload,
+} from "#src/presentation/prompt-payload";
+import { localRequester } from "#src/presentation/prompt-payload";
+
+/** The facts a path-shaped gate holds when it raises an ask. */
+interface PathAskFacts {
+  toolName: string;
+  /** The path as the caller typed it — what the user recognizes. */
+  pathValue: string;
+  agentName: string | null;
+  matchedPattern?: string;
+}
+
+/** A tool ask gated by an explicit `path` rule. */
+export function buildPathAskPayload(facts: PathAskFacts): PromptPayload {
+  return pathPayload("path", "path", facts, []);
+}
+
+/** The facts the external-directory gate adds: the boundary and the alias. */
+interface ExternalDirectoryAskFacts extends PathAskFacts {
+  /** The canonical location, when it names somewhere other than the typed path. */
+  resolvedPath?: string;
+  /** The working directory the path escapes. */
+  cwd: string;
+}
+
+/** A tool ask for a path outside the working directory. */
+export function buildExternalDirectoryAskPayload(
+  facts: ExternalDirectoryAskFacts,
+): PromptPayload {
+  return pathPayload("external_directory", "external_directory", facts, [
+    ...resolvedAliasEvidence(facts.resolvedPath),
+    workingDirectoryEvidence(facts.cwd),
+  ]);
+}
+
+/** The facts the bash external-directory gate holds: one command, many paths. */
+interface BashExternalDirectoryAskFacts {
+  command: string;
+  /** Every uncovered path the command references, with its canonical alias. */
+  externalPaths: readonly ExternalPathDisclosure[];
+  cwd: string;
+  agentName: string | null;
+  toolName: string;
+  matchedPattern?: string;
+}
+
+/** A bash ask whose command references paths outside the working directory. */
+export function buildBashExternalDirectoryAskPayload(
+  facts: BashExternalDirectoryAskFacts,
+): PromptPayload {
+  return {
+    kind: "bash_external_directory",
+    request: {
+      requester: localRequester(facts.agentName),
+      surface: "external_directory",
+      toolName: facts.toolName,
+      invokedToolName: null,
+      value: facts.command,
+      matchedPattern: facts.matchedPattern ?? null,
+      commandContext: null,
+      executedUnit: null,
+    },
+    evidence: [
+      workingDirectoryEvidence(facts.cwd),
+      ...facts.externalPaths.map(externalPathEvidence),
+    ],
+    annotations: [],
+  };
+}
+
+// ── Shared shape ────────────────────────────────────────────────────────────
+
+/**
+ * The payload common to the single-path asks: the typed path is the
+ * decision-relevant value, and the gate surface distinguishes them.
+ */
+function pathPayload(
+  kind: "path" | "external_directory",
+  surface: string,
+  facts: PathAskFacts,
+  evidence: PromptEvidence[],
+): PromptPayload {
+  return {
+    kind,
+    request: {
+      requester: localRequester(facts.agentName),
+      surface,
+      toolName: facts.toolName,
+      invokedToolName: null,
+      value: facts.pathValue,
+      matchedPattern: facts.matchedPattern ?? null,
+      commandContext: null,
+      executedUnit: null,
+    },
+    evidence,
+    annotations: [],
+  };
+}
+
+/**
+ * The canonical location, as its own entry rather than folded into the value:
+ * the user decides on the path they typed, and the alias is what that path
+ * turns out to name.
+ */
+function resolvedAliasEvidence(resolvedPath?: string): PromptEvidence[] {
+  return resolvedPath === undefined
+    ? []
+    : [{ label: "resolves to", text: resolvedPath, detail: null }];
+}
+
+function workingDirectoryEvidence(cwd: string): PromptEvidence {
+  return { label: "working directory", text: cwd, detail: null };
+}
+
+/**
+ * One escaping path. The canonical alias rides as the entry's `detail` so a
+ * render cannot separate a path from what it resolves to.
+ */
+function externalPathEvidence({
+  path,
+  resolvedPath,
+}: ExternalPathDisclosure): PromptEvidence {
+  return { label: "external path", text: path, detail: resolvedPath ?? null };
+}

package/src/presentation/prompt-payload.ts

@@ -0,0 +1,137 @@
+import type { BashCommandContext } from "#src/types";
+
+/**
+ * The complete, structured description of a permission ask (ADR 0011 §2).
+ *
+ * A gate emits one of these instead of a sentence. It is complete by contract:
+ * it never truncates and never decides what a human will see. Every consumer is
+ * a renderer over it, eliding under its own budget — so elision is a property
+ * of a render, never of the payload.
+ */
+export interface PromptPayload {
+  readonly kind: PromptPayloadKind;
+  readonly request: PromptRequestFacts;
+  /** Complete; each renderer elides to fit its own budget. */
+  readonly evidence: readonly PromptEvidence[];
+  /** Supplied by registered annotators; always marked as model-generated. */
+  readonly annotations: readonly PromptAnnotation[];
+}
+
+/**
+ * Which ask this payload describes — the renderers' dispatch discriminant.
+ *
+ * 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.
+ */
+export type PromptPayloadKind =
+  | "bash"
+  | "mcp"
+  | "tool"
+  | "path"
+  | "external_directory"
+  | "bash_external_directory"
+  | "skill"
+  | "skill_read"
+  | "forwarded";
+
+/**
+ * The invariant core (ADR 0011 §3): the facts visible in every render, that no
+ * renderer's budget may elide.
+ *
+ * Named for what it holds — the permission request's own facts, matching the
+ * package's `PermissionRequest` / `ForwardedPermissionRequest` vocabulary —
+ * rather than for its contract, which this comment states instead.
+ */
+export interface PromptRequestFacts {
+  /** Who is asking, and whether the ask arrived from a subagent. */
+  readonly requester: PromptRequester;
+  /** The gate surface the rule fired on. */
+  readonly surface: string;
+  /** The gated tool name; `null` when the ask is not tool-shaped. */
+  readonly toolName: string | null;
+  /**
+   * The invoked tool name when a shell alias re-exposes bash under another
+   * name (#574) — "gated as bash, invoked as exec_command" is two facts.
+   * `null` when it adds nothing.
+   */
+  readonly invokedToolName: string | null;
+  /** The decision-relevant value: the command, path, MCP target, or skill name. */
+  readonly value: string;
+  /** The matched rule, including a sentinel such as `<indirection-bash-wrapper>`. */
+  readonly matchedPattern: string | null;
+  /**
+   * Where the offending bash unit runs, when it came from a substitution or a
+   * subshell. A fact rather than a rendered clause: it is what makes the
+   * matched rule intelligible, and how it reads is the renderer's choice.
+   */
+  readonly commandContext: BashCommandContext | null;
+  /**
+   * For bash, the unit that will actually run — including inside an unstrippable
+   * wrapper (#713). `null` when it adds nothing over {@link value}.
+   */
+  readonly executedUnit: string | null;
+}
+
+/** Who is asking, one hop below when the ask was forwarded. */
+export interface PromptRequester {
+  readonly agentName: string | null;
+  readonly forwarded: boolean;
+  /** The requesting session, for a forwarded ask; `null` for a local one. */
+  readonly sessionId: string | null;
+}
+
+/**
+ * One piece of decision evidence.
+ *
+ * Complete on the payload; each renderer elides entries and orders them under
+ * its own budget (ADR 0011 §4).
+ */
+export interface PromptEvidence {
+  readonly label: string;
+  readonly text: string;
+  /**
+   * A secondary fact bound to this entry that a renderer may show alongside
+   * {@link text} or elide independently — a path's symlink-resolved alias, for
+   * instance. Bound to the entry rather than listed as a second one so an
+   * elision cannot separate the two.
+   */
+  readonly detail: string | null;
+}
+
+/**
+ * A model-generated advisory (ADR 0011 §8).
+ *
+ * The slot owns the attribution and the model-generated marking, so marking is
+ * a property of the payload rather than a discipline each annotator must
+ * remember. Structurally separate from any verdict: an annotation cannot allow,
+ * deny, defer, or suppress.
+ */
+export interface PromptAnnotation {
+  readonly source: string;
+  readonly text: string;
+}
+
+/** The `requester` facts for an ask raised by this session. */
+export function localRequester(agentName: string | null): PromptRequester {
+  return { agentName, forwarded: false, sessionId: null };
+}
+
+/** Find the evidence entry a renderer knows by label. */
+export function findEvidence(
+  payload: PromptPayload,
+  label: string,
+): PromptEvidence | undefined {
+  return payload.evidence.find((entry) => entry.label === label);
+}
+
+/** Every evidence entry carrying the given label, in payload order. */
+export function allEvidence(
+  payload: PromptPayload,
+  label: string,
+): readonly PromptEvidence[] {
+  return payload.evidence.filter((entry) => entry.label === label);
+}

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

@@ -0,0 +1,50 @@
+import type { PromptPayload } from "#src/presentation/prompt-payload";
+import { localRequester } from "#src/presentation/prompt-payload";
+import type { SkillPromptEntry } from "#src/skill-prompt-sanitizer";
+
+/** A request to load a skill. */
+export function buildSkillAskPayload(
+  skillName: string,
+  agentName: string | null,
+): PromptPayload {
+  return skillPayload("skill", skillName, agentName, []);
+}
+
+/**
+ * A read that reaches a skill through one of its files.
+ *
+ * The skill is the decision-relevant value — it is what the policy names — and
+ * the path is the evidence for why this read counts as reaching it.
+ */
+export function buildSkillPathAskPayload(
+  skill: SkillPromptEntry,
+  readPath: string,
+  agentName: string | null,
+): PromptPayload {
+  return skillPayload("skill_read", skill.name, agentName, [
+    { label: "read path", text: readPath, detail: null },
+  ]);
+}
+
+function skillPayload(
+  kind: "skill" | "skill_read",
+  skillName: string,
+  agentName: string | null,
+  evidence: PromptPayload["evidence"],
+): PromptPayload {
+  return {
+    kind,
+    request: {
+      requester: localRequester(agentName),
+      surface: "skill",
+      toolName: null,
+      invokedToolName: null,
+      value: skillName,
+      matchedPattern: null,
+      commandContext: null,
+      executedUnit: null,
+    },
+    evidence,
+    annotations: [],
+  };
+}

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

@@ -0,0 +1,104 @@
+import { classifyToolKind, isMcpCheck } from "#src/access-intent/tool-kind";
+import type {
+  PromptEvidence,
+  PromptPayload,
+} from "#src/presentation/prompt-payload";
+import { localRequester } from "#src/presentation/prompt-payload";
+import type { ToolPreviewFormatter } from "#src/tool-preview-formatter";
+import type { PermissionCheckResult } from "#src/types";
+import { getNonEmptyString, toRecord } from "#src/value-guards";
+
+/** The facts the per-tool gate holds when it raises an ask. */
+export interface ToolAskFacts {
+  /** The resolved check: the gated tool, the matched rule, the offending unit. */
+  check: PermissionCheckResult;
+  agentName: string | null;
+  /** The gate surface the rule fired on — `bash` for a shell alias (#574). */
+  surface: string;
+  /** The tool the agent actually called, when a shell alias re-exposes bash. */
+  invokedToolName?: string | null;
+  /** The raw tool input, the source of the input-preview evidence. */
+  input?: unknown;
+  /** Renders the per-tool input preview; absent means no preview evidence. */
+  formatter?: ToolPreviewFormatter;
+}
+
+/**
+ * Build the payload for the per-tool gate: a bash, MCP, or generic-tool ask.
+ *
+ * The branch decides only the payload's `kind` and which fact is the
+ * decision-relevant `value`; how any of it reads is a renderer's decision.
+ */
+export function buildToolAskPayload(facts: ToolAskFacts): PromptPayload {
+  const { check } = facts;
+  const bash = classifyToolKind(check.toolName) === "bash";
+  const mcp = isMcpCheck(check) && check.target !== undefined;
+
+  return {
+    kind: bash ? "bash" : mcp ? "mcp" : "tool",
+    request: {
+      requester: localRequester(facts.agentName),
+      surface: facts.surface,
+      toolName: check.toolName,
+      invokedToolName: distinctInvokedName(facts),
+      value: askValue(check, bash, mcp),
+      matchedPattern: check.matchedPattern ?? null,
+      commandContext: check.commandContext ?? null,
+      executedUnit: check.executedUnit ?? null,
+    },
+    evidence: bash
+      ? fullCommandEvidence(facts)
+      : inputPreviewEvidence(facts, mcp),
+    annotations: [],
+  };
+}
+
+/**
+ * The decision-relevant value: the offending command for bash, the qualified
+ * target for MCP, the tool name otherwise.
+ *
+ * A bash check with no command yields the empty string rather than the tool
+ * name — the ask is about a command, and naming the surface instead would
+ * assert a command that was never resolved.
+ */
+function askValue(
+  check: PermissionCheckResult,
+  bash: boolean,
+  mcp: boolean,
+): string {
+  if (bash) return check.command ?? "";
+  if (mcp) return check.target ?? "";
+  return check.toolName;
+}
+
+/** The invoked tool name, but only when it is a fact the gated name does not carry. */
+function distinctInvokedName(facts: ToolAskFacts): string | null {
+  const invoked = facts.invokedToolName ?? null;
+  return invoked === null || invoked === facts.check.toolName ? null : invoked;
+}
+
+/** The enclosing command, when the gated unit is only part of what will run. */
+function fullCommandEvidence(facts: ToolAskFacts): PromptEvidence[] {
+  const fullCommand = getNonEmptyString(toRecord(facts.input).command);
+  if (fullCommand === null || fullCommand === facts.check.command) {
+    return [];
+  }
+  return [{ label: "full command", text: fullCommand, detail: null }];
+}
+
+/**
+ * The per-tool input preview, when a formatter is registered and produces one.
+ *
+ * An MCP ask previews under the `mcp` key rather than the qualified target, so
+ * a registered MCP formatter is consulted for every server.
+ */
+function inputPreviewEvidence(
+  facts: ToolAskFacts,
+  mcp: boolean,
+): PromptEvidence[] {
+  const preview = facts.formatter?.formatToolInputForPrompt(
+    mcp ? "mcp" : facts.check.toolName,
+    facts.input,
+  );
+  return preview ? [{ label: "input", text: preview, detail: null }] : [];
+}

package/src/tool-preview-formatter.ts

@@ -135,7 +135,7 @@ export class ToolPreviewFormatter {
       case "ls":
         return this.formatSearchInputForPrompt(toolName, inputRecord);
       case "mcp":
-        // The MCP target is already surfaced in formatAskPrompt's MCP branch.
+        // The MCP target is already a request fact on the prompt payload.
         // When no custom formatter is registered (or it declines), produce no
         // additional preview rather than leaking the raw event JSON.
         return "";

package/src/types.ts

@@ -58,6 +58,12 @@ export interface PermissionCheckResult {
    * (top-level) commands.
    */
   commandContext?: BashCommandContext;
+  /**
+   * The command the winning bash unit actually runs, when it is a wrapper whose
+   * inner command differs from the unit text (#713). Display-only: the gate
+   * still decides on `command`, so this never widens or narrows a decision.
+   */
+  executedUnit?: string;
 }
 
 export function isPermissionState(value: unknown): value is PermissionState {

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

@@ -1,28 +0,0 @@
-import {
-  type ExternalPathDisclosure,
-  resolvesToSuffix,
-} from "#src/denial-messages";
-
-export function formatExternalDirectoryAskPrompt(
-  toolName: string,
-  pathValue: string,
-  resolvedPath: string | undefined,
-  cwd: string,
-  agentName?: string,
-): string {
-  const subject = agentName ? `Agent '${agentName}'` : "Current agent";
-  return `${subject} requested tool '${toolName}' for path '${pathValue}'${resolvesToSuffix(resolvedPath)} outside working directory '${cwd}'. Allow this external directory access?`;
-}
-
-export function formatBashExternalDirectoryAskPrompt(
-  command: string,
-  externalPaths: ExternalPathDisclosure[],
-  cwd: string,
-  agentName?: string,
-): string {
-  const subject = agentName ? `Agent '${agentName}'` : "Current agent";
-  const pathList = externalPaths
-    .map(({ path, resolvedPath }) => `${path}${resolvesToSuffix(resolvedPath)}`)
-    .join(", ");
-  return `${subject} requested bash command '${command}' which references path(s) outside working directory '${cwd}': ${pathList}. Allow this external directory access?`;
-}