@gotgenes/pi-permission-system 25.3.0 → 26.0.0

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

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;