@gotgenes/pi-permission-system 27.1.3 → 28.0.1

package/CHANGELOG.md

@@ -5,6 +5,36 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [28.0.1](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v28.0.0...pi-permission-system-v28.0.1) (2026-08-30)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** carry a serving session's deny reason to the requesting agent ([b2010d7](https://github.com/gotgenes/pi-packages/commit/b2010d7bfbf766592b4ae0b98f16a612f96ff706)), closes [#844](https://github.com/gotgenes/pi-packages/issues/844)
+* **pi-permission-system:** name the rule that refused a forwarded call instead of blaming the user ([3d83641](https://github.com/gotgenes/pi-packages/commit/3d83641ad9bf6b045a86a4fb2879a7761c0aefc3)), closes [#844](https://github.com/gotgenes/pi-packages/issues/844)
+* **pi-permission-system:** tell the agent when the permission authority failed to answer ([8f70380](https://github.com/gotgenes/pi-packages/commit/8f70380005733546fa2df1d8694c50985332de19)), closes [#844](https://github.com/gotgenes/pi-packages/issues/844)
+
+## [28.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v27.1.3...pi-permission-system-v28.0.0) (2026-08-30)
+
+
+### ⚠ BREAKING CHANGES
+
+* **pi-permission-system:** `PermissionDecisionResolution` gains `authorizer_allowed` and `authorizer_denied`, and existing decisions change which resolution they report. An ask decided by a registered `authorizerChain` link now reports `authorizer_allowed` / `authorizer_denied` instead of `user_approved` / `user_denied`, and a subagent's ask answered by its parent reports what decided inside that parent — `policy_allow` / `policy_deny` for a rule, `authorizer_*` for a link — instead of attributing it to the user. Consumers switching exhaustively over `resolution` must handle the two new values; a consumer counting `user_denied` as human interactions now gets the accurate count rather than one inflated by machine decisions.
+
+### Features
+
+* **pi-permission-system:** broadcast the decider that actually resolved a permission ask ([1b92386](https://github.com/gotgenes/pi-packages/commit/1b923863a00284c7bd6ca9bef5307ad83db0677d)), closes [#772](https://github.com/gotgenes/pi-packages/issues/772)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** tell the agent which authorizer refused its call ([412189b](https://github.com/gotgenes/pi-packages/commit/412189b4e32db3ca419d030c1b2195532e8ebbd4)), closes [#772](https://github.com/gotgenes/pi-packages/issues/772)
+
+
+### Documentation
+
+* **pi-permission-system:** record decision attribution and mark Phase 14 Step 5 complete ([b31f5d5](https://github.com/gotgenes/pi-packages/commit/b31f5d56d61727ab8bd146c2dfe83ce85aa7eef5)), closes [#772](https://github.com/gotgenes/pi-packages/issues/772)
+
 ## [27.1.3](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v27.1.2...pi-permission-system-v27.1.3) (2026-08-29)
 
 

package/dist/public.d.ts

@@ -274,6 +274,10 @@ interface PermissionUiPromptEvent {
 }
 /** How a permission decision was reached. */
 type PermissionDecisionResolution = "policy_allow" | "policy_deny" | "session_approved" | "infrastructure_auto_allowed" | "user_approved" | "user_approved_for_session" | "user_denied" | "auto_approved" | "confirmation_unavailable"
+/** A registered `authorizerChain` link granted the ask; no human was asked. */
+ | "authorizer_allowed"
+/** A registered `authorizerChain` link refused the ask; no human was asked. */
+ | "authorizer_denied"
 /** The gate threw, or an escalation failed, and the request was blocked. */
  | "gate_error";
 /** Payload emitted on `permissions:decision`. */

package/docs/cross-extension-api.md

@@ -420,6 +420,8 @@ A session serving another session's forwarded request emits one too, on its own
 That is what makes a forwarded prompt clearable: the ask is gated in the requesting session — a different process for an out-of-process subagent — so without it the serving session broadcasts a `permissions:ui_prompt` whose outcome never appears.
 A forwarded request the serving session's own policy allows or denies is answered without a prompt and broadcasts nothing, matching the UI-prompt channel.
 A served decision carries a non-null `forwarding` context; the requesting session still emits its own decision when the answer comes back.
+That requesting-side decision is attributed to whatever decided **inside** the responding session: a rule there reports `policy_allow` / `policy_deny`, a chain link reports `authorizer_allowed` / `authorizer_denied`, and a human there reports `user_approved` / `user_denied`.
+The `resolution` names what decided, never where.
 
 The `requestId` is the same id the request's review-log entries carry, and the same one `permissions:ui_prompt` carried if the request reached a prompt — so a prompt and its outcome are joinable, as are two concurrent prompts for the same command.
 A request that reaches a prompt is answered by exactly one terminal event on that prompt's own bus, including when the dialog itself fails.
@@ -460,6 +462,8 @@ pi.events.on("permissions:decision", (raw) => {
 | `user_approved`               | User approved once via dialog                                        |
 | `user_approved_for_session`   | User approved for the rest of the session                            |
 | `user_denied`                 | User denied via dialog                                               |
+| `authorizer_allowed`          | A registered `authorizerChain` link granted the ask — no human asked |
+| `authorizer_denied`           | A registered `authorizerChain` link refused the ask — no human asked |
 | `auto_approved`               | Yolo mode — approved automatically without dialog                    |
 | `confirmation_unavailable`    | State was `ask` but no UI was available — blocked                    |
 | `gate_error`                  | The gate threw, or an escalation failed — blocked, fail-closed       |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-permission-system",
-  "version": "27.1.3",
+  "version": "28.0.1",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
   "exports": {

package/src/authority/decision-resolution.ts

@@ -0,0 +1,69 @@
+import {
+  type DecisionSource,
+  effectiveDecider,
+} from "#src/authority/decision-source";
+import type { PermissionDecisionResolution } from "#src/permission-events";
+
+/** What became of the request, as the gate that ran it observed. */
+export interface DecisionOutcome {
+  /** Whether the request was ultimately allowed. */
+  approved: boolean;
+  /** Whether the approval was scoped to the rest of the session. */
+  forSession: boolean;
+}
+
+/**
+ * Name how a decision was reached, from the decider stamped on it.
+ *
+ * The one place a {@link DecisionSource} becomes a
+ * {@link PermissionDecisionResolution}, shared by the local gate runner and the
+ * serving node so the two records of one request cannot disagree. Every arm
+ * reads the stamp the deciding site wrote (#726) rather than re-deriving the
+ * decider from the outcome — the derivation that reported an `authorizerChain`
+ * link's verdict, and a serving session's own policy, as the operator's answer
+ * (#772).
+ *
+ * `outcome` supplies what the decider does not record: whether the request was
+ * allowed, and whether the human scoped their grant to the session. A
+ * `{ kind: "user" }` record names the surface answered on, never the scope.
+ *
+ * The switch is exhaustive with no `default`, so a new `DecisionSource` variant
+ * is a compile error here rather than a silent `user_approved`.
+ */
+export function resolutionFor(
+  decidedBy: DecisionSource,
+  outcome: DecisionOutcome,
+): PermissionDecisionResolution {
+  const decider = effectiveDecider(decidedBy);
+  switch (decider.kind) {
+    case "rule":
+      return outcome.approved ? "policy_allow" : "policy_deny";
+    case "session_approval":
+      return "session_approved";
+    case "infrastructure_read":
+      return "infrastructure_auto_allowed";
+    case "yolo":
+      return "auto_approved";
+    case "authorizer":
+      return outcome.approved ? "authorizer_allowed" : "authorizer_denied";
+    case "unavailable":
+      return "confirmation_unavailable";
+    case "gate_error":
+      return "gate_error";
+    case "user":
+    // A `forwarded` frame reaches here only when the responder named no
+    // decider — an older parent — so the hop is the only fact available and
+    // today's attribution is the fail-soft answer.
+    case "forwarded":
+      return userResolution(outcome);
+  }
+}
+
+function userResolution(
+  outcome: DecisionOutcome,
+): PermissionDecisionResolution {
+  if (!outcome.approved) {
+    return "user_denied";
+  }
+  return outcome.forSession ? "user_approved_for_session" : "user_approved";
+}

package/src/authority/decision-source.ts

@@ -88,6 +88,35 @@ export function asDecisionSource(value: unknown): DecisionSource | undefined {
   return narrowSource(value, MAX_DECISION_SOURCE_DEPTH);
 }
 
+/**
+ * The decider a `forwarded` hop is standing in for: the innermost
+ * non-`forwarded` source, or the hop itself when the responder named none.
+ *
+ * `forwarded` answers *where* a decision was made; every other variant answers
+ * *what* made it. A reader asking the second question — how to name the
+ * resolution, which refusal to render — wants the inner record, or it reports
+ * the parent's policy as the operator's own answer.
+ *
+ * `responderSessionId` is deliberately dropped: the session that answered is a
+ * separate fact, carried on the record itself and (for a served decision) on
+ * the bus event's `forwarding` context.
+ *
+ * Bounded by {@link MAX_DECISION_SOURCE_DEPTH} like its sibling guard. A value
+ * read off disk is already bounded there, and a locally-built one nests once
+ * per hop, so the bound is insurance rather than a working limit; reaching it
+ * yields the deepest frame seen, which reads as "decided elsewhere".
+ */
+export function effectiveDecider(source: DecisionSource): DecisionSource {
+  let decider = source;
+  for (let hop = 0; hop < MAX_DECISION_SOURCE_DEPTH; hop++) {
+    if (decider.kind !== "forwarded" || decider.decision === null) {
+      return decider;
+    }
+    decider = decider.decision;
+  }
+  return decider;
+}
+
 function narrowSource(
   value: unknown,
   depthBudget: number,

package/src/authority/forwarded-request-server.ts

@@ -1,10 +1,14 @@
 import { join } from "node:path";
+import { resolutionFor } from "#src/authority/decision-resolution";
 import type { DecisionSource } from "#src/authority/decision-source";
 import {
   type ForwarderContext,
   getSessionId,
 } from "#src/authority/forwarder-context";
-import type { PermissionPromptDecision } from "#src/authority/permission-dialog";
+import {
+  createDeniedPermissionDecision,
+  type PermissionPromptDecision,
+} from "#src/authority/permission-dialog";
 import {
   type ForwardedAccessFacts,
   type ForwardedAccessIntent,
@@ -15,10 +19,7 @@ import {
 } from "#src/authority/permission-forwarding";
 import type { SubagentSessionRegistry } from "#src/authority/subagent-registry";
 import type { DecisionBroadcaster } from "#src/decision-reporter";
-import type {
-  PermissionDecisionEvent,
-  PermissionDecisionResolution,
-} from "#src/permission-events";
+import type { PermissionDecisionEvent } from "#src/permission-events";
 import { buildForwardedAskPayload } from "#src/presentation/forwarded-ask-payload";
 import { SessionApproval } from "#src/session-approval";
 import type { SessionApprovalRecorder } from "#src/session-approval-recorder";
@@ -183,41 +184,22 @@ function buildServedDecisionEvent(
     value: details.value ?? facts.value,
     agentName: details.agentName,
     result: decision.approved ? "allow" : "deny",
-    resolution: servedResolution(decision),
+    resolution: resolutionFor(decision.decidedBy, {
+      approved: decision.approved,
+      // The grant scope is reported as the human chose it. `applyGrantScope`
+      // rewrites a whole-serving-session grant to a plain approval on the
+      // wire, but that translation is about what the *child* records, not
+      // about what was allowed here.
+      forSession:
+        decision.state === "approved_for_session" ||
+        decision.state === "approved_for_serving_session",
+    }),
     origin: null,
     matchedPattern: null,
     forwarding: details.forwarding ?? null,
   };
 }
 
-/**
- * Name how a served ask resolved, reading the decision's own stamp rather than
- * re-deriving it from the outcome: the site that decided already recorded what
- * it was (#726).
- *
- * The grant scope is reported as the human chose it. {@link applyGrantScope}
- * rewrites a whole-serving-session grant to a plain approval on the wire, but
- * that translation is about what the *child* records, not about what was
- * allowed here.
- */
-function servedResolution(
-  decision: PermissionPromptDecision,
-): PermissionDecisionResolution {
-  if (decision.decidedBy.kind === "gate_error") {
-    return "gate_error";
-  }
-  if (decision.confirmationUnavailable) {
-    return "confirmation_unavailable";
-  }
-  if (!decision.approved) {
-    return "user_denied";
-  }
-  return decision.state === "approved_for_session" ||
-    decision.state === "approved_for_serving_session"
-    ? "user_approved_for_session"
-    : "user_approved";
-}
-
 // ── ForwardedRequestServer ────────────────────────────────────────────────
 
 /**
@@ -477,9 +459,12 @@ export class ForwardedRequestServer implements InboxProcessor {
           : "forwarded_permission.auto_denied",
         { ...logDetails, decidedBy },
       );
+      // A deny-with-reason rule's text is the operator's own explanation, and
+      // the requesting session relays it to its agent — so it travels with the
+      // verdict rather than stopping at the node that holds the config (#844).
       return approved
         ? { approved: true, state: "approved", decidedBy }
-        : { approved: false, state: "denied", decidedBy };
+        : { ...createDeniedPermissionDecision(check.reason), decidedBy };
     }
 
     this.logger.review("forwarded_permission.prompted", logDetails);

package/src/authority/permission-dialog.ts

@@ -11,21 +11,16 @@ export type PermissionPromptDecision = {
   approved: boolean;
   state: PermissionDecisionState;
   denialReason?: string;
-  /**
-   * True when the decision was made automatically by yolo mode rather than
-   * by an interactive user prompt. Used by handlers to emit "auto_approved"
-   * rather than "user_approved" in the permissions:decision broadcast.
-   */
-  autoApproved?: true;
   /**
    * True when no human ever ruled on this ask: either no live authority was
    * reachable at all (`DenyingAuthorizer`, a no-UI non-subagent session) or the
    * forwarding path gave up before reaching one (`ParentAuthorizer` — target
    * unresolvable, request undeliverable, target not serving, or no answer
-   * within the timeout). Consumed by deriveResolution (the decision-event
-   * resolution), the gate (block reason), and PermissionPrompter (review-entry
-   * resolution) to emit "confirmation_unavailable" rather than a plain user
-   * denial — a user who was never asked denied nothing (#719).
+   * within the timeout). Consumed by the gate (block reason) and
+   * `PermissionPrompter` (review-entry resolution) to report
+   * "confirmation_unavailable" rather than a plain user denial — a user who
+   * was never asked denied nothing (#719). The decision-event resolution
+   * reads the `unavailable` decider below instead (#772).
    */
   confirmationUnavailable?: true;
   /**

package/src/handlers/gates/helpers.ts

@@ -86,33 +86,6 @@ export function buildDecisionEvent(
   };
 }
 
-/**
- * Map the gate outcome back to a PermissionDecisionResolution.
- *
- * @param state     - The permission state passed to the gate.
- * @param action    - The gate's resulting action ("allow" | "block").
- * @param hasSession - True when the gate result carries a sessionApproval
- *                    (indicates the user chose "for this session").
- * @param confirmationUnavailable - True when the denial came from the
- *                    DenyingAuthorizer (no live authority was reachable).
- */
-export function deriveResolution(
-  state: "allow" | "deny" | "ask",
-  action: "allow" | "block",
-  hasSession: boolean,
-  confirmationUnavailable: boolean,
-  autoApproved = false,
-): PermissionDecisionResolution {
-  if (state === "allow") return autoApproved ? "auto_approved" : "policy_allow";
-  if (state === "deny") return "policy_deny";
-  // state === "ask"
-  if (action === "allow") {
-    if (autoApproved) return "auto_approved";
-    return hasSession ? "user_approved_for_session" : "user_approved";
-  }
-  return confirmationUnavailable ? "confirmation_unavailable" : "user_denied";
-}
-
 /**
  * The standing yolo grant covering a gate's resolved check, or `null` when
  * yolo does not answer it.

package/src/handlers/gates/runner.ts

@@ -1,4 +1,6 @@
 import type { AskEscalator } from "#src/authority/authorizer-selection";
+import { resolutionFor } from "#src/authority/decision-resolution";
+import type { DecisionSource } from "#src/authority/decision-source";
 import type { PermissionPromptDecision } from "#src/authority/permission-dialog";
 import type { DecisionReporter } from "#src/decision-reporter";
 import { applyPermissionGate } from "#src/permission-gate";
@@ -6,8 +8,7 @@ import { createPermissionRequestId } from "#src/permission-request-id";
 import type { ScopedPermissionResolver } from "#src/permission-resolver";
 import {
   renderPolicyDenial,
-  renderUnavailableDenial,
-  renderUserDenial,
+  renderRefusal,
 } from "#src/presentation/agent-renderer";
 import { renderReviewLogFacts } from "#src/presentation/review-log-renderer";
 import type { SessionApprovalRecorder } from "#src/session-approval-recorder";
@@ -18,11 +19,7 @@ import type {
   GateResult,
 } from "./descriptor";
 import { isGateBypass } from "./descriptor";
-import {
-  buildDecisionEvent,
-  deriveResolution,
-  resolveYoloGrant,
-} from "./helpers";
+import { buildDecisionEvent, resolveYoloGrant } from "./helpers";
 import type { GateOutcome } from "./types";
 
 // ── GateRunner class ───────────────────────────────────────────────────────
@@ -160,12 +157,17 @@ export class GateRunner {
     // single auto_approved review entry + decision event so log parity holds.
     const yoloGrant = resolveYoloGrant(check, this.isYoloEnabled());
     if (yoloGrant) {
+      // The pattern that raised the ask, sentinel included: "yolo allowed it"
+      // alone does not say why it was asked in the first place. One record for
+      // both the review entry and the broadcast, so they cannot disagree.
+      const decidedByYolo: DecisionSource = {
+        kind: "yolo",
+        pattern: check.matchedPattern ?? null,
+      };
       this.reporter.writeReviewLog("permission_request.auto_approved", {
         ...logContext,
         resolution: "auto_approved",
-        // The pattern that raised the ask, sentinel included: "yolo allowed
-        // it" alone does not say why it was asked in the first place.
-        decidedBy: { kind: "yolo", pattern: check.matchedPattern ?? null },
+        decidedBy: decidedByYolo,
       });
       this.emitDecision(
         requestId,
@@ -174,7 +176,7 @@ export class GateRunner {
           yoloGrant,
           agentName,
           "allow",
-          deriveResolution(yoloGrant.state, "allow", false, false, true),
+          resolutionFor(decidedByYolo, { approved: true, forSession: false }),
         ),
       );
       return { action: "allow" };
@@ -189,14 +191,22 @@ export class GateRunner {
     const { payload } = descriptor;
     const messages = {
       denyReason: renderPolicyDenial(payload, check.reason ?? null),
-      unavailableReason: (decision: PermissionPromptDecision) =>
-        renderUnavailableDenial(payload, decision.denialReason ?? null),
-      userDeniedReason: (decision: PermissionPromptDecision) =>
-        renderUserDenial(payload, decision.denialReason ?? null),
+      refusedReason: (decision: PermissionPromptDecision) =>
+        renderRefusal(
+          payload,
+          decision.decidedBy,
+          decision.denialReason ?? null,
+        ),
     };
 
-    let autoApproved = false;
-    let confirmationUnavailable = false;
+    // The rule that resolved this gate, and the decider for every arm that
+    // never escalates: `allow` and `deny` are recorded authority answering.
+    const decidedByRule: DecisionSource = {
+      kind: "rule",
+      surface: descriptor.surface,
+      pattern: check.matchedPattern ?? null,
+      origin: check.origin,
+    };
     const gateResult = await applyPermissionGate({
       state: check.state,
       sessionApproval: descriptor.sessionApproval?.toGateApproval(),
@@ -209,19 +219,12 @@ export class GateRunner {
             ? { sessionApproval: descriptor.sessionApproval.toForwardedData() }
             : {}),
         });
-        autoApproved = decision.autoApproved === true;
-        confirmationUnavailable = decision.confirmationUnavailable === true;
         return decision;
       },
       writeLog: (event, details) =>
         this.reporter.writeReviewLog(event, details),
       logContext,
-      decidedByRule: {
-        kind: "rule",
-        surface: descriptor.surface,
-        pattern: check.matchedPattern ?? null,
-        origin: check.origin,
-      },
+      decidedByRule,
       messages,
     });
 
@@ -237,13 +240,10 @@ export class GateRunner {
         check,
         agentName,
         gateResult.action === "allow" ? "allow" : "deny",
-        deriveResolution(
-          check.state,
-          gateResult.action,
-          hasSessionApproval,
-          confirmationUnavailable,
-          autoApproved,
-        ),
+        resolutionFor(gateResult.decidedBy, {
+          approved: gateResult.action === "allow",
+          forSession: hasSessionApproval,
+        }),
       ),
     );
 

package/src/permission-events.ts

@@ -139,6 +139,10 @@ export type PermissionDecisionResolution =
   | "user_denied"
   | "auto_approved"
   | "confirmation_unavailable"
+  /** A registered `authorizerChain` link granted the ask; no human was asked. */
+  | "authorizer_allowed"
+  /** A registered `authorizerChain` link refused the ask; no human was asked. */
+  | "authorizer_denied"
   /** The gate threw, or an escalation failed, and the request was blocked. */
   | "gate_error";
 

package/src/permission-gate.ts

@@ -1,10 +1,21 @@
 import type { DecisionSource } from "#src/authority/decision-source";
 import type { PermissionPromptDecision } from "#src/authority/permission-dialog";
 
-/** Result of applying the permission gate. */
+/**
+ * Result of applying the permission gate.
+ *
+ * Both arms name what decided. The gate is the one place that knows whether
+ * recorded authority answered or an escalation did, so it reports the decider
+ * rather than leaving the caller to reconstruct it from a captured decision
+ * (#772).
+ */
 export type PermissionGateResult =
-  | { action: "allow"; sessionApproval?: { surface: string; pattern: string } }
-  | { action: "block"; reason: string };
+  | {
+      action: "allow";
+      decidedBy: DecisionSource;
+      sessionApproval?: { surface: string; pattern: string };
+    }
+  | { action: "block"; decidedBy: DecisionSource; reason: string };
 
 /** Everything the gate needs — no direct dependency on ExtensionContext. */
 export interface PermissionGateParams {
@@ -32,7 +43,8 @@ export interface PermissionGateParams {
   logContext: Record<string, unknown>;
 
   /**
-   * The rule that resolved this gate, for the deny arm's review entry.
+   * The rule that resolved this gate — the decider for both arms that never
+   * escalate, and the deny arm's review entry.
    *
    * A sibling of `logContext` rather than a member of it: the context holds
    * what every resolution of this gate shares, and the decider is by
@@ -42,9 +54,16 @@ export interface PermissionGateParams {
 
   /** Message strings/factories for each outcome. */
   messages: {
+    /** What the agent is told when recorded authority denied the request. */
     denyReason: string;
-    unavailableReason: (decision: PermissionPromptDecision) => string;
-    userDeniedReason: (decision: PermissionPromptDecision) => string;
+    /**
+     * What the agent is told when an escalation refused it.
+     *
+     * One factory rather than one per outcome: which sentence a refusal earns
+     * follows from the decision's own decider, and that dispatch belongs with
+     * the renderers rather than here (#772).
+     */
+    refusedReason: (decision: PermissionPromptDecision) => string;
   };
 }
 
@@ -64,26 +83,34 @@ export async function applyPermissionGate(
       resolution: "policy_denied",
       decidedBy: params.decidedByRule,
     });
-    return { action: "block", reason: messages.denyReason };
+    return {
+      action: "block",
+      decidedBy: params.decidedByRule,
+      reason: messages.denyReason,
+    };
   }
 
   if (state === "ask") {
     const decision = await promptForApproval();
+    const decidedBy = decision.decidedBy;
     if (!decision.approved) {
       // The gate writes no review entry for an ask denial — the prompter
-      // brackets it (waiting/denied). The block reason distinguishes an
-      // absent-authority denial (confirmationUnavailable) from a user denial.
+      // brackets it (waiting/denied).
       return {
         action: "block",
-        reason: decision.confirmationUnavailable
-          ? messages.unavailableReason(decision)
-          : messages.userDeniedReason(decision),
+        decidedBy,
+        reason: messages.refusedReason(decision),
       };
     }
     if (decision.state === "approved_for_session" && params.sessionApproval) {
-      return { action: "allow", sessionApproval: params.sessionApproval };
+      return {
+        action: "allow",
+        decidedBy,
+        sessionApproval: params.sessionApproval,
+      };
     }
+    return { action: "allow", decidedBy };
   }
 
-  return { action: "allow" };
+  return { action: "allow", decidedBy: params.decidedByRule };
 }

package/src/presentation/agent-renderer.ts

@@ -1,3 +1,7 @@
+import {
+  type DecisionSource,
+  effectiveDecider,
+} from "#src/authority/decision-source";
 import { EXTENSION_ID } from "#src/extension-config";
 import { DEFAULT_RENDER_BUDGET } from "#src/presentation/dialog-renderer";
 import {
@@ -10,6 +14,7 @@ import {
   findEvidence,
   type PromptPayload,
 } from "#src/presentation/prompt-payload";
+import type { BashCommandContext } from "#src/types";
 
 /**
  * The agent-facing render of a refused permission ask (ADR 0011 §7).
@@ -41,6 +46,70 @@ export interface AgentRenderBudget {
   readonly fieldMaxWidth: number;
 }
 
+/**
+ * The agent-facing render a refused ask earns, chosen by what refused it.
+ *
+ * The single dispatch point for the refusal renderers below, so which sentence
+ * the agent gets is decided once from the decider stamped on the decision
+ * (#726) rather than re-derived from a marker at each caller. Being told a
+ * policy extension refused the call, rather than the operator, is what lets an
+ * agent read a link's corrective reason as policy instead of as the user's
+ * instruction (ADR 0011 §7).
+ *
+ * A `forwarded` decision is dispatched on the decider inside the responding
+ * session: the hop says *where*, and the agent is told *what*.
+ *
+ * Exhaustive with no `default`, so a new {@link DecisionSource} variant is a
+ * compile error here rather than a silent user attribution.
+ */
+export function renderRefusal(
+  payload: PromptPayload,
+  decidedBy: DecisionSource,
+  denialReason: string | null,
+  budget: AgentRenderBudget = DEFAULT_RENDER_BUDGET,
+): string {
+  const decider = effectiveDecider(decidedBy);
+  // The hop the unwrap discarded: *where* the decision was made. Kept as a
+  // bare fact rather than the responder's identity, which stays undisclosed.
+  const decidedElsewhere = decidedBy.kind === "forwarded";
+  switch (decider.kind) {
+    case "authorizer":
+      return renderAuthorizerDenial(
+        payload,
+        decider.name,
+        denialReason,
+        budget,
+      );
+    case "unavailable":
+      return renderUnavailableDenial(payload, denialReason, budget);
+    case "rule":
+      return renderEscalatedPolicyDenial(
+        payload,
+        { pattern: decider.pattern, decidedElsewhere },
+        denialReason,
+        budget,
+      );
+    case "gate_error":
+      return renderGateErrorDenial(payload, {
+        reason: decider.reason,
+        decidedElsewhere,
+      });
+    // Three different reasons share this arm. `user` is the render's true
+    // subject: a human refused, and the sentence says so. The three below it
+    // never refuse at all — a session grant, an infrastructure read, and yolo
+    // only ever allow — so they are unreachable here and listed only to keep
+    // the switch exhaustive. A `forwarded` reaching this far named no inner
+    // decider (an older responder), so the hop is all that is known, and the
+    // user render is the fail-soft answer rather than the accurate one.
+    case "user":
+    case "session_approval":
+    case "infrastructure_read":
+    case "yolo":
+    case "forwarded":
+      return renderUserDenial(payload, denialReason, budget);
+  }
+}
+
 /** The agent-facing render of a policy deny. */
 export function renderPolicyDenial(
   payload: PromptPayload,
@@ -48,7 +117,7 @@ export function renderPolicyDenial(
   budget: AgentRenderBudget = DEFAULT_RENDER_BUDGET,
 ): string {
   return tagged(
-    `Denied by policy: ${identification(payload, budget, "")}${boundaryClause(payload)}${provenanceClause(payload)}.`,
+    `Denied by policy: ${identification(payload, budget, "", askRuleClause(payload))}${boundaryClause(payload)}${provenanceClause(payload)}.`,
     ruleReason,
   );
 }
@@ -60,11 +129,96 @@ export function renderUserDenial(
   budget: AgentRenderBudget = DEFAULT_RENDER_BUDGET,
 ): string {
   return tagged(
-    `The user denied this ${identification(payload, budget, "call")}${boundaryClause(payload)}${provenanceClause(payload)}.`,
+    `The user denied this ${identification(payload, budget, "call", askRuleClause(payload))}${boundaryClause(payload)}${provenanceClause(payload)}.`,
+    denialReason,
+  );
+}
+
+/**
+ * The agent-facing render of a registered `authorizerChain` link's refusal.
+ *
+ * Names the link, because "a policy extension the operator configured refused
+ * this" and "the operator refused this" are different facts and only one of
+ * them was true (#772). The name is operator configuration rather than agent
+ * input, so it is not capped — the same treatment the matched rule gets.
+ */
+export function renderAuthorizerDenial(
+  payload: PromptPayload,
+  linkName: string,
+  denialReason: string | null,
+  budget: AgentRenderBudget = DEFAULT_RENDER_BUDGET,
+): string {
+  return tagged(
+    `The '${linkName}' authorizer denied this ${identification(payload, budget, "call", askRuleClause(payload))}${boundaryClause(payload)}${provenanceClause(payload)}.`,
+    denialReason,
+  );
+}
+
+/** The rule that refused an escalated ask, and where it sat. */
+export interface EscalatedRule {
+  /** The pattern the deciding node's rule matched; `null` when none was recorded. */
+  readonly pattern: string | null;
+  /** Whether that node was reached through a forwarding hop. */
+  readonly decidedElsewhere: boolean;
+}
+
+/**
+ * The agent-facing render of a policy denial an escalation came back with.
+ *
+ * Distinct from {@link renderPolicyDenial} in which rule it names. That one
+ * renders the rule on this session's payload, which is the rule that decided
+ * when recorded authority answered locally. Here the ask was escalated, so the
+ * payload's rule is the one that raised the *ask* and the rule that *denied*
+ * lives on the decision — naming the payload's would name the wrong rule while
+ * looking correct (ADR 0011 §10, #844).
+ */
+export function renderEscalatedPolicyDenial(
+  payload: PromptPayload,
+  rule: EscalatedRule,
+  denialReason: string | null,
+  budget: AgentRenderBudget = DEFAULT_RENDER_BUDGET,
+): string {
+  const decidedRule = ruleClause(rule.pattern, payload.request.commandContext);
+  return tagged(
+    `A policy rule${servingClause(rule.decidedElsewhere)} denied this ${identification(payload, budget, "call", decidedRule)}${boundaryClause(payload)}${provenanceClause(payload)}.`,
     denialReason,
   );
 }
 
+/** The escalation failure that blocked an ask fail-closed, and where it happened. */
+export interface GateFailure {
+  /** The error text stamped on the decision, which carries the detail here. */
+  readonly reason: string;
+  /** Whether the failing authority was reached through a forwarding hop. */
+  readonly decidedElsewhere: boolean;
+}
+
+/**
+ * The agent-facing render of an escalation that threw rather than ruling.
+ *
+ * Nobody denied this call — the authority that would have answered broke, and
+ * the boundary blocked rather than allowed. Saying so is what distinguishes it
+ * from a verdict the agent should respect: a failure is worth surfacing to the
+ * operator, where a denial is worth working around (#844).
+ *
+ * The reason comes from the decision's own stamp rather than a denial reason,
+ * because that is the field the failing site writes and the field the review
+ * log records — a second source would be a second story about one failure.
+ *
+ * Like {@link renderUnavailableDenial}, it omits the escaped boundary: the
+ * ask never reached a rule, so no retry shape would change the outcome.
+ */
+export function renderGateErrorDenial(
+  payload: PromptPayload,
+  failure: GateFailure,
+  budget: AgentRenderBudget = DEFAULT_RENDER_BUDGET,
+): string {
+  return tagged(
+    `The permission authority${servingClause(failure.decidedElsewhere)} failed to answer this ${identification(payload, budget, "call", askRuleClause(payload))}, so it was blocked (fail-closed).`,
+    failure.reason,
+  );
+}
+
 /** The agent-facing render when no live authority could answer the ask. */
 export function renderUnavailableDenial(
   payload: PromptPayload,
@@ -72,13 +226,24 @@ export function renderUnavailableDenial(
   budget: AgentRenderBudget = DEFAULT_RENDER_BUDGET,
 ): string {
   return tagged(
-    `This ${identification(payload, budget, "call")} requires approval, but no interactive UI is available.`,
+    `This ${identification(payload, budget, "call", askRuleClause(payload))} requires approval, but no interactive UI is available.`,
     denialReason,
   );
 }
 
 // ── Sentence assembly ──────────────────────────────────────────────────────
 
+/**
+ * Where the deciding authority sat, when it was not this session.
+ *
+ * Says that another session decided and never which one: the responder's
+ * identity answers a question the requesting agent cannot act on, and §6 keeps
+ * it off the render (ADR 0011 §10).
+ */
+function servingClause(decidedElsewhere: boolean): string {
+  return decidedElsewhere ? " in the session serving this request" : "";
+}
+
 function tagged(sentence: string, reason: string | null): string {
   return `${EXTENSION_TAG} ${sentence}${reasonClause(reason)}`;
 }
@@ -91,11 +256,16 @@ function tagged(sentence: string, reason: string | null): string {
  * `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.
+ *
+ * `ruleText` is supplied rather than read off the payload, because an escalated
+ * refusal names the rule that *decided* it, which is not always this session's
+ * own (#844).
  */
 function identification(
   payload: PromptPayload,
   budget: AgentRenderBudget,
   callWord: string,
+  ruleText: string,
 ): string {
   return [
     `'${payload.request.surface}'`,
@@ -104,7 +274,7 @@ function identification(
     toolClause(payload),
     agentClause(payload),
     flaggedClause(payload, budget),
-    ruleClause(payload),
+    ruleText,
   ]
     .filter((clause) => clause !== "")
     .join(" ");
@@ -171,12 +341,29 @@ function resolvedAlias(payload: PromptPayload, element: string): string {
   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;
+/** The rule that raised this session's own ask. */
+function askRuleClause(payload: PromptPayload): string {
+  return ruleClause(
+    payload.request.matchedPattern,
+    payload.request.commandContext,
+  );
+}
+
+/**
+ * The rule that fired, with the nested context that makes it intelligible.
+ *
+ * The pattern is a parameter rather than a payload read: an escalated refusal
+ * renders the rule that decided it, which for a forwarded ask lives on the
+ * response's decider and never on this session's payload. The command context
+ * is a fact about the call either way, so it always comes from the payload.
+ */
+function ruleClause(
+  pattern: string | null,
+  commandContext: BashCommandContext | null,
+): string {
   const parts: string[] = [];
-  if (matchedPattern !== null) {
-    parts.push(`rule '${matchedPattern}'`);
+  if (pattern !== null) {
+    parts.push(`rule '${pattern}'`);
   }
   const context = describeBashCommandContext(commandContext);
   if (context !== undefined) {