@gotgenes/pi-permission-system 25.4.0 → 26.1.0

package/src/authority/forwarding-io.ts

@@ -9,6 +9,7 @@ import {
   writeFileSync,
 } from "node:fs";
 
+import { asDecisionSource } from "#src/authority/decision-source";
 import { isPermissionDecisionState } from "#src/authority/permission-dialog";
 import {
   createPermissionForwardingLocation,
@@ -23,6 +24,7 @@ import {
   OWNER_ONLY_FILE_MODE,
 } from "#src/log-file-permissions";
 import type { PermissionUiPromptSource } from "#src/permission-events";
+import { asPromptPayload } from "#src/presentation/prompt-payload";
 import type { DebugReviewLogger } from "#src/session-logger";
 
 /** Valid `permissions:ui_prompt` source values, for tolerant request reads. */
@@ -396,8 +398,7 @@ export function readForwardedPermissionRequest(
       typeof parsed.createdAt !== "number" ||
       typeof parsed.requesterSessionId !== "string" ||
       typeof parsed.targetSessionId !== "string" ||
-      typeof parsed.requesterAgentName !== "string" ||
-      typeof parsed.message !== "string"
+      typeof parsed.requesterAgentName !== "string"
     ) {
       logPermissionForwardingWarning(
         logger,
@@ -412,9 +413,11 @@ export function readForwardedPermissionRequest(
       requesterSessionId: parsed.requesterSessionId,
       targetSessionId: parsed.targetSessionId,
       requesterAgentName: parsed.requesterAgentName,
-      message: parsed.message,
-      // Tolerant read: display fields are optional and may be absent (older
-      // child) or malformed; reconstruct only the well-formed ones.
+      // Tolerant read: the payload and display fields are optional and may be
+      // absent (older child) or malformed; reconstruct only the well-formed
+      // ones. An older child's `message` is deliberately not salvaged — a
+      // skewed ask renders from the fields it does carry (ADR 0011 §9).
+      payload: asPromptPayload(parsed.payload),
       source: asUiPromptSource(parsed.source),
       surface: asNullableDisplayString(parsed.surface),
       value: asNullableDisplayString(parsed.value),
@@ -464,6 +467,10 @@ export function readForwardedPermissionResponse(
         typeof parsed.respondedAt === "number"
           ? parsed.respondedAt
           : Date.now(),
+      // Tolerant like the request's `accessIntent`: an unusable provenance
+      // record is dropped, but the decision itself still has to reach the
+      // requester, so it never rejects the response.
+      decidedBy: asDecisionSource(parsed.decidedBy),
     };
   } catch (error) {
     logPermissionForwardingWarning(

package/src/authority/permission-dialog.ts

@@ -1,3 +1,5 @@
+import type { DecisionSource } from "#src/authority/decision-source";
+
 export type PermissionDecisionState =
   | "approved"
   | "approved_for_session"
@@ -26,8 +28,27 @@ export type PermissionPromptDecision = {
    * denial — a user who was never asked denied nothing (#719).
    */
   confirmationUnavailable?: true;
+  /**
+   * What decided this request, stamped by the site that decided it.
+   *
+   * Required: every decision names its decider, and the type is what
+   * guarantees it rather than a convention each producer has to remember — the
+   * same discipline `PromptPermissionDetails.payload` carries (#726).
+   */
+  decidedBy: DecisionSource;
 };
 
+/**
+ * A decision before its decider is known.
+ *
+ * The inner producers — the dialog's decision model, the `select`/`input`
+ * fallback, the verdict mapper — state the outcome; which decider to attribute
+ * it to is settled one layer up, at the site that chose the producer. The same
+ * shape `GateBypass.decision` uses for the request id: a producer emits only
+ * what it knows.
+ */
+export type UnattributedDecision = Omit<PermissionPromptDecision, "decidedBy">;
+
 export interface PermissionDecisionUi {
   select(title: string, options: string[]): Promise<string | undefined>;
   input(title: string, placeholder?: string): Promise<string | undefined>;
@@ -51,7 +72,7 @@ export function normalizePermissionDenialReason(
 
 export function createDeniedPermissionDecision(
   denialReason?: string,
-): PermissionPromptDecision {
+): UnattributedDecision {
   const normalizedReason = normalizePermissionDenialReason(denialReason);
   return normalizedReason
     ? {
@@ -96,7 +117,7 @@ export async function requestPermissionDecisionFromUi(
   title: string,
   message: string,
   options?: RequestPermissionOptions,
-): Promise<PermissionPromptDecision> {
+): Promise<UnattributedDecision> {
   const sessionOption = options?.sessionLabel ?? APPROVE_FOR_SESSION_OPTION;
   const decisionOptions = [
     APPROVE_OPTION,

package/src/authority/permission-forwarding.ts

@@ -1,5 +1,7 @@
 import { join } from "node:path";
+import type { DecisionSource } from "#src/authority/decision-source";
 import type { PermissionUiPromptSource } from "#src/permission-events";
+import type { PromptPayload } from "#src/presentation/prompt-payload";
 import type { PermissionDecisionState } from "./permission-dialog";
 import type { SubagentSessionRegistry } from "./subagent-registry";
 
@@ -53,9 +55,9 @@ const SESSION_FORWARDING_RESPONSES_DIRECTORY_NAME = "responses";
  * Display fields relayed from a forwarding child to the parent UI so the parent
  * can emit a non-degraded `permissions:ui_prompt` event.
  *
- * Carried separately from the prompt message because the parent reconstructs
+ * Carried separately from the prompt payload because the parent reconstructs
  * the original event from the escalated ask's details (`buildUiPrompt`), not
- * from the message text.
+ * from the payload's own facts.
  */
 export interface ForwardedPromptDisplay {
   source: PermissionUiPromptSource;
@@ -123,7 +125,15 @@ export type ForwardedPermissionRequest = {
   requesterSessionId: string;
   targetSessionId: string;
   requesterAgentName: string;
-  message: string;
+  /**
+   * The child's complete prompt payload (ADR 0011 §2), so the serving node
+   * renders the child's own facts under the *parent's* budget rather than
+   * relaying a sentence the child assembled under its own configuration.
+   *
+   * Optional for version-skew tolerance: an older child omits it, and the
+   * serving node renders from the display fields it does carry (ADR 0011 §9).
+   */
+  payload?: PromptPayload;
   /**
    * Original prompt display fields, persisted so the parent emits a
    * non-degraded event. Optional for version-skew tolerance: a parent on a
@@ -154,6 +164,18 @@ export type ForwardedPermissionResponse = {
   denialReason?: string;
   responderSessionId: string;
   respondedAt: number;
+  /**
+   * What decided, inside the responding session (#726).
+   *
+   * `responderSessionId` names *where* the decision was made; this names
+   * *what* made it, which is the difference between a human at the parent's
+   * dialog and the parent's policy answering on their behalf.
+   *
+   * Optional for version-skew tolerance: an older responder omits it, and the
+   * requester records the hop with a `null` inner decision rather than
+   * rejecting the answer.
+   */
+  decidedBy?: DecisionSource;
 };
 
 export type PermissionForwardingLocation = {

package/src/authority/permission-prompt-component.ts

@@ -4,10 +4,15 @@ import type {
   KeybindingsManager,
 } from "@earendil-works/pi-coding-agent";
 import { type Component, matchesKey } from "@earendil-works/pi-tui";
+import type {
+  DecisionSource,
+  UserDecisionSurface,
+} from "#src/authority/decision-source";
 import {
   type PermissionPromptDecision,
   type RequestPermissionOptions,
   requestPermissionDecisionFromUi,
+  type UnattributedDecision,
 } from "#src/authority/permission-dialog";
 import {
   initialPromptState,
@@ -64,15 +69,23 @@ export interface PromptPreferences {
  *
  * The single entry the `LocalUserAuthorizer` calls; keeps the mode dispatch in
  * one place so the fallback and the inline component never both render.
+ *
+ * It is therefore also the one place that knows which surface the human
+ * answered on, so it is where the decision is attributed to that surface
+ * (#726). Having the dialog model and the fallback each name themselves would
+ * be two sites that must agree with this branch.
  */
-export function requestPermissionDecision(
+export async function requestPermissionDecision(
   view: PermissionPromptView,
   title: string,
   payload: PromptPayload,
   options?: RequestPermissionOptions,
 ): Promise<PermissionPromptDecision> {
   if (view.mode === "tui") {
-    return presentInlinePermissionPrompt(view, title, payload, options);
+    return attributeToHuman(
+      await presentInlinePermissionPrompt(view, title, payload, options),
+      "dialog",
+    );
   }
   // The fallback renders once and cannot re-render, so it neither paints nor
   // offers an expansion; it substitutes a nominal width for the terminal size
@@ -81,14 +94,25 @@ export function requestPermissionDecision(
     ...view.budget,
     width: FALLBACK_RENDER_WIDTH,
   });
-  return requestPermissionDecisionFromUi(
-    view.ui,
-    title,
-    rendered.lines.join("\n"),
-    options,
+  return attributeToHuman(
+    await requestPermissionDecisionFromUi(
+      view.ui,
+      title,
+      rendered.lines.join("\n"),
+      options,
+    ),
+    "select",
   );
 }
 
+function attributeToHuman(
+  decision: UnattributedDecision,
+  via: UserDecisionSurface,
+): PermissionPromptDecision {
+  const decidedBy: DecisionSource = { kind: "user", via };
+  return { ...decision, decidedBy };
+}
+
 /** The width the `select`/`input` fallback renders against. */
 const FALLBACK_RENDER_WIDTH = 80;
 
@@ -113,13 +137,13 @@ export function presentInlinePermissionPrompt(
   title: string,
   payload: PromptPayload,
   options?: RequestPermissionOptions,
-): Promise<PermissionPromptDecision> {
+): Promise<UnattributedDecision> {
   const config: PromptModelConfig = {
     doublePressToConfirm: view.doublePressToConfirm,
     sessionLabel: options?.sessionLabel ?? DEFAULT_SESSION_LABEL,
     sessionScope: options?.sessionScope,
   };
-  return view.ui.custom<PermissionPromptDecision>(
+  return view.ui.custom<UnattributedDecision>(
     (tui, theme, keybindings, done) =>
       new PermissionPromptComponent(
         theme,
@@ -176,7 +200,7 @@ class PermissionPromptComponent implements Component {
     private readonly budget: RenderBudget,
     private readonly handleAppAction: (data: string) => boolean,
     private readonly requestRender: () => void,
-    private readonly done: (decision: PermissionPromptDecision) => void,
+    private readonly done: (decision: UnattributedDecision) => void,
   ) {
     this.state = initialPromptState(config);
   }

package/src/authority/permission-prompt-decision.ts

@@ -1,8 +1,8 @@
 import {
   createDeniedPermissionDecision,
   normalizePermissionDenialReason,
-  type PermissionPromptDecision,
   type RequestPermissionOptions,
+  type UnattributedDecision,
 } from "#src/authority/permission-dialog";
 
 /**
@@ -70,7 +70,7 @@ export type PromptEvent =
 /** Either a re-render or a terminal decision. */
 export type PromptOutcome =
   | { kind: "render"; state: PromptViewState }
-  | { kind: "decision"; decision: PermissionPromptDecision };
+  | { kind: "decision"; decision: UnattributedDecision };
 
 export function initialPromptState(
   _config: PromptModelConfig,
@@ -88,7 +88,11 @@ export function initialPromptState(
 
 /**
  * Advance the dialog by one input event, returning either the next view state
- * to render or the committed {@link PermissionPromptDecision}.
+ * to render or the committed {@link UnattributedDecision}.
+ *
+ * The model states the outcome and not the decider: which human surface this
+ * is gets attributed by the dispatcher that chose to render this dialog, so
+ * the two cannot disagree about the surface.
  */
 export function reducePrompt(
   config: PromptModelConfig,

package/src/authority/permission-prompter.ts

@@ -1,9 +1,11 @@
+import type { DecisionSource } from "#src/authority/decision-source";
 import type { PermissionPromptDecision } from "#src/authority/permission-dialog";
 import type {
   ForwardedAccessFacts,
   ForwardedSessionApproval,
 } from "#src/authority/permission-forwarding";
 import type { PromptPayload } from "#src/presentation/prompt-payload";
+import { renderReviewLogFacts } from "#src/presentation/review-log-renderer";
 import type { ReviewLogger } from "#src/session-logger";
 import type { TerminalAuthorizer } from "./authorizer";
 
@@ -27,13 +29,13 @@ export interface PromptPermissionDetails {
   requestId: string;
   source: PermissionReviewSource;
   agentName: string | null;
-  message: string;
   /**
    * The complete structured description of this ask (ADR 0011 §2).
    *
    * Required: every ask carries one, and the type is what guarantees it rather
-   * than a convention each gate has to remember. `message` is a render over it
-   * for the duration of the transition, so the two cannot disagree.
+   * than a convention each gate has to remember. Every consumer — the dialog,
+   * the wire, the broadcast, the review log, the agent-facing denial text — is
+   * a render over it, so no two of them can disagree.
    */
   payload: PromptPayload;
   toolCallId?: string;
@@ -130,6 +132,7 @@ export class PermissionPrompter implements PermissionPrompterApi {
           ? "confirmation_unavailable"
           : decision.state,
         denialReason: decision.denialReason,
+        decidedBy: decision.decidedBy,
       },
     );
 
@@ -138,18 +141,24 @@ export class PermissionPrompter implements PermissionPrompterApi {
 
   // ── Private helpers ──────────────────────────────────────────────────────
 
+  /**
+   * The `waiting` entry carries no `decidedBy` — nothing has decided yet, and
+   * a `null` there would read as "decided by nobody" rather than "not yet".
+   */
   private writeReviewEntry(
     event: string,
     details: PromptPermissionDetails & {
       resolution?: string;
       denialReason?: string;
+      decidedBy?: DecisionSource;
     },
   ): void {
     this.deps.logger.review(event, {
+      ...(details.decidedBy ? { decidedBy: details.decidedBy } : {}),
       requestId: details.requestId,
       source: details.source,
       agentName: details.agentName,
-      message: details.message,
+      ...renderReviewLogFacts(details.payload),
       toolCallId: details.toolCallId ?? null,
       toolName: details.toolName ?? null,
       skillName: details.skillName ?? null,

package/src/config-loader.ts

@@ -224,6 +224,7 @@ export function mergeUnifiedConfigs(
     "forwardingTimeoutMs",
     "promptMaxRows",
     "promptFieldMaxWidth",
+    "reviewLogFieldMaxWidth",
     "toolInputPreviewMaxLength",
     "toolTextSummaryMaxLength",
   ] as const) {
@@ -374,6 +375,9 @@ export function loadAndMergeConfigs(
   const bashFallbackIssue = detectPermissiveBashFallback(merged.permission);
   if (bashFallbackIssue) allIssues.push(bashFallbackIssue);
 
+  const deprecatedCapsIssue = detectDeprecatedPreviewCaps(merged);
+  if (deprecatedCapsIssue) allIssues.push(deprecatedCapsIssue);
+
   return {
     global: globalConfig,
     project: projectConfig,
@@ -414,6 +418,33 @@ export function detectPermissiveBashFallback(
   );
 }
 
+/**
+ * Detect a config still setting one of the two superseded tool-preview caps.
+ *
+ * `toolInputPreviewMaxLength` and `toolTextSummaryMaxLength` bounded one
+ * preview inside a prompt, never the prompt itself, which is why they never
+ * bounded it; `promptMaxRows` and `promptFieldMaxWidth` supersede them
+ * (ADR 0011 §5). Both stay valid in the schema so an existing config is not
+ * rejected fail-closed — they are simply no longer read.
+ *
+ * Pure, following `detectPermissiveBashFallback`: it takes the merged config
+ * and returns a message; the caller owns pushing it onto the issue list.
+ */
+export function detectDeprecatedPreviewCaps(
+  config: UnifiedPermissionConfig,
+): string | undefined {
+  const set = (
+    ["toolInputPreviewMaxLength", "toolTextSummaryMaxLength"] as const
+  ).filter((key) => config[key] !== undefined);
+  if (set.length === 0) return undefined;
+
+  return (
+    `Permission config sets ${set.map((key) => `'${key}'`).join(" and ")}, ` +
+    "which is deprecated and ignored. The prompt is bounded by " +
+    "'promptMaxRows' and 'promptFieldMaxWidth' instead; remove the setting."
+  );
+}
+
 /**
  * Load and normalize a unified config file.
  * Returns an empty config with no issues if the file does not exist.

package/src/config-schema.ts

@@ -208,17 +208,26 @@ export const unifiedConfigSchema = z
         "Maximum characters of any one field shown in a permission prompt.\n\nOmit to use the default (400). This is what bounds a single pathological field — a long here-string command, say — that would otherwise fill the prompt through wrapping. A shortened field is marked with an ellipsis, and `Ctrl+O` shows it in full.",
       default: 400,
     }),
+    reviewLogFieldMaxWidth: z.number().int().min(1).optional().meta({
+      description:
+        "Maximum characters of any one value written to the permission review log. Omit to use the default (1000).",
+      markdownDescription:
+        "Maximum characters of any one value written to the permission review log.\n\nOmit to use the default (1000). Every string the review log writes is narrowed to this width and marked with an ellipsis, so the log's growth is a decision you make rather than a side effect of how long a command happened to be. Raise it to keep longer values \u2014 a bash command exceeding the width is stored shortened.\n\nThis is a length bound, not redaction: it never inspects a value to decide what to hide. Key-name masking is unchanged and applies independently.",
+      default: 1000,
+    }),
     toolInputPreviewMaxLength: z.number().int().min(1).optional().meta({
+      deprecated: true,
       description:
-        "Maximum character length of the inline-JSON tool-input preview shown in permission prompts. Omit to use the default (200). Set to a large value to disable truncation.",
+        "Deprecated and ignored. Superseded by promptMaxRows and promptFieldMaxWidth, which bound the whole prompt rather than one preview. Still accepted so an existing config is not rejected; remove it.",
       markdownDescription:
-        "Maximum character length of the inline-JSON tool-input preview shown in permission prompts.\n\nOmit to use the default (200). Set to a large value (e.g. `10000`) to effectively disable truncation and see the full input.",
+        "**Deprecated and ignored.** Superseded by `promptMaxRows` and `promptFieldMaxWidth`, which bound the whole permission prompt rather than one preview inside it.\n\nStill accepted so an existing config is not rejected fail-closed, but the value no longer takes effect. Remove it.",
     }),
     toolTextSummaryMaxLength: z.number().int().min(1).optional().meta({
+      deprecated: true,
       description:
-        "Maximum character length of inline pattern/path summaries (e.g. grep patterns, find globs, ls paths) in permission prompts. Omit to use the default (80).",
+        "Deprecated and ignored. Superseded by promptMaxRows and promptFieldMaxWidth, which bound the whole prompt rather than one summary. Still accepted so an existing config is not rejected; remove it.",
       markdownDescription:
-        "Maximum character length of inline pattern/path summaries (e.g. grep patterns, find globs, ls paths) shown in permission prompts.\n\nOmit to use the default (80). Increase this when working with long regexes or deep paths that are being cut off.",
+        "**Deprecated and ignored.** Superseded by `promptMaxRows` and `promptFieldMaxWidth`, which bound the whole permission prompt rather than one summary inside it.\n\nStill accepted so an existing config is not rejected fail-closed, but the value no longer takes effect. Remove it.",
     }),
     piInfrastructureReadPaths: z.array(z.string().min(1)).optional().meta({
       description:

package/src/extension-config.ts

@@ -26,10 +26,8 @@ export interface PermissionSystemExtensionConfig {
   promptMaxRows?: number;
   /** Max characters of any one field shown in a permission prompt. Defaults to 400. */
   promptFieldMaxWidth?: number;
-  /** Max length of the inline-JSON input preview shown in permission prompts. Defaults to 200. */
-  toolInputPreviewMaxLength?: number;
-  /** Max length of inline pattern/path summaries (grep/find/ls) in permission prompts. Defaults to 80. */
-  toolTextSummaryMaxLength?: number;
+  /** Max characters of any one value written to the permission review log. Defaults to 1000. */
+  reviewLogFieldMaxWidth?: number;
   /** Non-bash tools that carry shell semantics, keyed by tool name. */
   shellTools?: ShellToolsConfig;
   /** Ordered names of registered live-authority chain links to consult before the terminal authorizer. */
@@ -86,12 +84,13 @@ export function normalizePermissionSystemConfig(
   if (raw.promptFieldMaxWidth !== undefined) {
     result.promptFieldMaxWidth = raw.promptFieldMaxWidth;
   }
-  if (raw.toolInputPreviewMaxLength !== undefined) {
-    result.toolInputPreviewMaxLength = raw.toolInputPreviewMaxLength;
-  }
-  if (raw.toolTextSummaryMaxLength !== undefined) {
-    result.toolTextSummaryMaxLength = raw.toolTextSummaryMaxLength;
+  if (raw.reviewLogFieldMaxWidth !== undefined) {
+    result.reviewLogFieldMaxWidth = raw.reviewLogFieldMaxWidth;
   }
+  // `toolInputPreviewMaxLength` / `toolTextSummaryMaxLength` are deliberately
+  // absent: the schema and the merge still accept them so the deprecation
+  // detector can see an operator's setting, but no runtime consumer may read
+  // one (ADR 0011 §5, #745).
   if (raw.shellTools !== undefined) {
     result.shellTools = raw.shellTools;
   }

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

@@ -1,6 +1,5 @@
 import type { BashProgram } from "#src/access-intent/bash/program";
 import type { ScopedPermissionResolver } from "#src/permission-resolver";
-import { renderLegacyMessage } from "#src/presentation/legacy-message";
 import { buildBashExternalDirectoryAskPayload } from "#src/presentation/path-ask-payload";
 import { SessionApproval } from "#src/session-approval";
 import { deriveApprovalPattern } from "#src/session-rules";
@@ -48,6 +47,15 @@ export function describeBashExternalDirectoryGate(
   if (uncoveredPaths.length === 0) {
     return {
       action: "allow",
+      // A whole-command bypass covers every external path at once, and each
+      // may have matched a different session pattern -- so the surface is one
+      // value and the pattern is not. The entry's `externalPaths` lists what
+      // was covered.
+      decidedBy: {
+        kind: "session_approval",
+        surface: "external_directory",
+        pattern: null,
+      },
       log: {
         event: "permission_request.session_approved",
         details: {
@@ -85,26 +93,17 @@ export function describeBashExternalDirectoryGate(
     toolName: tcc.toolName,
     matchedPattern: preCheck.matchedPattern,
   });
-  const bashExtMessage = renderLegacyMessage(payload);
 
   const patterns = uncoveredPaths.map((p) => deriveApprovalPattern(p));
 
   return {
     surface: "external_directory",
     input: {},
-    denialContext: {
-      kind: "bash_external_directory",
-      command,
-      externalPaths: disclosures,
-      cwd: tcc.cwd,
-      agentName: tcc.agentName ?? undefined,
-    },
+    payload,
     sessionApproval: SessionApproval.multiple("external_directory", patterns),
     promptDetails: {
       source: "tool_call",
       agentName: tcc.agentName,
-      message: bashExtMessage,
-      payload,
       toolCallId: tcc.toolCallId,
       toolName: tcc.toolName,
       command,
@@ -117,7 +116,6 @@ export function describeBashExternalDirectoryGate(
       agentName: tcc.agentName,
       command,
       externalPaths: uncoveredPaths,
-      message: bashExtMessage,
     },
     decision: {
       surface: "external_directory",

package/src/handlers/gates/bash-path.ts

@@ -1,7 +1,6 @@
 import type { AccessPath } from "#src/access-intent/access-path";
 import type { BashProgram } from "#src/access-intent/bash/program";
 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";
@@ -85,6 +84,14 @@ export function describeBashPathGate(
   if (allSessionCovered) {
     return {
       action: "allow",
+      // Every token was covered, each possibly by a different session pattern
+      // -- the surface is one value and the pattern is not. The entry's
+      // `tokens` lists what was covered.
+      decidedBy: {
+        kind: "session_approval",
+        surface: "path",
+        pattern: null,
+      },
       log: {
         event: "permission_request.session_approved",
         details: {
@@ -120,23 +127,15 @@ export function describeBashPathGate(
     agentName: tcc.agentName,
     matchedPattern: worstCheck.matchedPattern,
   });
-  const askMessage = renderLegacyMessage(payload);
 
   return {
     surface: "path",
     input: { path: worstToken },
-    denialContext: {
-      kind: "bash_path",
-      command,
-      pathValue: worstToken,
-      agentName: tcc.agentName ?? undefined,
-    },
+    payload,
     sessionApproval: SessionApproval.single("path", pattern),
     promptDetails: {
       source: "tool_call",
       agentName: tcc.agentName,
-      message: askMessage,
-      payload,
       toolCallId: tcc.toolCallId,
       toolName: tcc.toolName,
       command,

package/src/handlers/gates/descriptor.ts

@@ -1,6 +1,7 @@
+import type { DecisionSource } from "#src/authority/decision-source";
 import type { PromptPermissionDetails } from "#src/authority/permission-prompter";
-import type { DenialContext } from "#src/denial-messages";
 import type { PermissionDecisionEvent } from "#src/permission-events";
+import type { PromptPayload } from "#src/presentation/prompt-payload";
 import type { SessionApproval } from "#src/session-approval";
 import type { PermissionCheckResult, PermissionState } from "#src/types";
 
@@ -18,16 +19,27 @@ export interface GateDescriptor {
   surface: string;
   /** Input passed to checkPermission. */
   input: unknown;
-  /** Structured denial context — the runner formats messages from this. */
-  denialContext: DenialContext;
+  /**
+   * The complete structured description of this ask (ADR 0011 §2).
+   *
+   * The descriptor's one presentation fact: every render over it — the dialog,
+   * the agent-facing denial text, the review log — reads this and nothing
+   * else, so a gate states its facts once.
+   */
+  payload: PromptPayload;
   /**
    * Session-approval suggestion for the "for this session" option.
    * Wraps either a single pattern or multiple patterns behind a unified
    * interface — the runner never needs to know which case applies.
    */
   sessionApproval?: SessionApproval;
-  /** Details passed to the interactive permission prompt (requestId is added by the runner). */
-  promptDetails: Omit<PromptPermissionDetails, "requestId">;
+  /**
+   * Details passed to the interactive permission prompt.
+   *
+   * The runner stamps both `requestId` (which it mints) and `payload` (which
+   * the descriptor owns), so neither is a gate's to supply twice.
+   */
+  promptDetails: Omit<PromptPermissionDetails, "requestId" | "payload">;
   /** Extra context fields written to the review log alongside gate outcomes. */
   logContext: Record<string, unknown>;
   /** Surface and value for the decision event (may differ from the check surface). */
@@ -68,6 +80,14 @@ export type DecisionEventFacts = Omit<PermissionDecisionEvent, "requestId">;
  */
 export interface GateBypass {
   action: "allow";
+  /**
+   * What decided this short-circuit.
+   *
+   * The gate that bypasses *is* the decider, so it states its own provenance
+   * and the runner relays it onto the log entry rather than inferring one from
+   * the event name (#726). Required, so a bypass added later cannot omit it.
+   */
+  decidedBy: DecisionSource;
   /** Optional review log entry to emit. */
   log?: { event: string; details: Record<string, unknown> };
   /** Optional decision event to emit. */