@gotgenes/pi-permission-system 27.1.2 → 28.0.0

package/CHANGELOG.md

@@ -5,6 +5,43 @@ 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.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)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** gate commands hosted by declarations, test commands, and assignments ([dfde822](https://github.com/gotgenes/pi-packages/commit/dfde8227d3bf11de5258dcbe376dd0b8b75045e0)), closes [#742](https://github.com/gotgenes/pi-packages/issues/742)
+* **pi-permission-system:** gate commands inside a for loop's body and word list ([6e96464](https://github.com/gotgenes/pi-packages/commit/6e9646486db849afdf80819150a203d293b3847c)), closes [#742](https://github.com/gotgenes/pi-packages/issues/742)
+* **pi-permission-system:** gate commands inside control-flow bodies and function definitions ([3a2f232](https://github.com/gotgenes/pi-packages/commit/3a2f232d9c12588ea1feacf41cade0e56e66a44b)), closes [#742](https://github.com/gotgenes/pi-packages/issues/742)
+* **pi-permission-system:** project a command-name substitution's path operands ([9807d44](https://github.com/gotgenes/pi-packages/commit/9807d444b6d81526b01bc542cd4a829a1b2640c3)), closes [#742](https://github.com/gotgenes/pi-packages/issues/742)
+
+
+### Documentation
+
+* **pi-permission-system:** bound the path-slice claim on behavior, not diff footprint ([91ef5c9](https://github.com/gotgenes/pi-packages/commit/91ef5c9f2d0578fb64fe317bcddd3ec7d9418d4c)), closes [#742](https://github.com/gotgenes/pi-packages/issues/742)
+* **pi-permission-system:** commit the instrument behind Step 4's measurement ([e634c2c](https://github.com/gotgenes/pi-packages/commit/e634c2cf068340cc0deae86648330e44c2741f06)), closes [#742](https://github.com/gotgenes/pi-packages/issues/742)
+
 ## [27.1.2](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v27.1.1...pi-permission-system-v27.1.2) (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.2",
+  "version": "28.0.0",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
   "exports": {
@@ -90,6 +90,7 @@
     "test:watch": "vitest",
     "verify:public-types": "bash scripts/verify-public-types.sh",
     "measure:core-coverage": "node scripts/measure-core-coverage.mjs",
+    "measure:statement-descent": "node scripts/measure-statement-descent.mjs",
     "measure:wrapper-transparency": "node scripts/measure-wrapper-transparency.mjs",
     "lint:md": "rumdl check *.md docs/**/*.md",
     "lint": "biome check . && eslint . && pnpm run lint:md"

package/src/access-intent/bash/command-enumeration.ts

@@ -1,6 +1,6 @@
 import {
   EXECUTION_HOST_TYPES,
-  forEachNestedExecution,
+  forEachExecutionIn,
 } from "#src/access-intent/bash/nested-execution";
 import type { TSNode } from "#src/access-intent/bash/parser";
 import { redirectMayWriteFile } from "#src/access-intent/bash/redirect-analysis";
@@ -79,7 +79,7 @@ interface UnitScope {
 /** A top-level command in the current shell, writing no file. */
 const TOP_LEVEL_SCOPE: UnitScope = { writesViaRedirect: false };
 
-// ── Command enumeration ──────────────────────────────────────────────────────
+// ── Node-type vocabulary ─────────────────────────────────────────────────────
 
 /**
  * Container node types descended into with the enclosing scope unchanged.
@@ -89,6 +89,39 @@ const TOP_LEVEL_SCOPE: UnitScope = { writesViaRedirect: false };
  */
 const COMMAND_ENUM_DESCEND = new Set(["program", "list", "pipeline"]);
 
+/**
+ * Compound statements: emitted whole, then descended for their statements.
+ *
+ * The whole emit is what keeps the #306 never-weaker invariant — the commands
+ * found inside are additional units, never a replacement.
+ *
+ * `select` parses as `for_statement` and `until` as `while_statement`, so each
+ * pair is one entry.
+ */
+const COMPOUND_STATEMENT_TYPES = new Set([
+  "if_statement",
+  "while_statement",
+  "for_statement",
+  "c_style_for_statement",
+  "case_statement",
+  "function_definition",
+  "compound_statement",
+  "negated_command",
+]);
+
+/**
+ * Syntactic groupings inside a compound statement: descended, never emitted.
+ *
+ * None of these is something anybody runs — a `do_group` is the loop body's
+ * punctuation — so emitting one would produce a `do rm $f; done` unit.
+ */
+const STATEMENT_GROUP_TYPES = new Set([
+  "do_group",
+  "case_item",
+  "elif_clause",
+  "else_clause",
+]);
+
 /**
  * Named node types abandoned during command enumeration: they are neither
  * commands nor able to host one, so nothing in their subtree ever runs.
@@ -104,6 +137,33 @@ const COMMAND_ENUM_DESCEND = new Set(["program", "list", "pipeline"]);
  */
 const COMMAND_ENUM_SKIP = new Set(["comment", "heredoc_end"]);
 
+/**
+ * Every node type the enumerator recognizes as a statement.
+ *
+ * This is the enumerator's third question, beside "is this a command?" and
+ * "can this host one?": "is this a *statement*, so that descending an enclosing
+ * compound reaches it?" A compound statement's named children are a mix —
+ * `for_statement` carries its loop variable and word list, `case_statement` its
+ * subject, `function_definition` its name — and descending all of them emits
+ * operand words as bash command units, naming `a` as the offending *command* in
+ * a prompt. Membership is what {@link descendStatementChildren} filters on.
+ */
+const STATEMENT_TYPES = new Set([
+  "command",
+  "redirected_statement",
+  "subshell",
+  "declaration_command",
+  "variable_assignment",
+  "test_command",
+  "unset_command",
+  "ERROR",
+  ...COMMAND_ENUM_DESCEND,
+  ...COMPOUND_STATEMENT_TYPES,
+  ...STATEMENT_GROUP_TYPES,
+]);
+
+// ── Command enumeration ──────────────────────────────────────────────
+
 /**
  * Enumerate the command units of a bash program, in source order.
  *
@@ -114,10 +174,14 @@ const COMMAND_ENUM_SKIP = new Set(["comment", "heredoc_end"]);
  * subshells (`( … )`) — emitting each inner command as its own unit *in
  * addition to* the enclosing command, since those inner commands really execute
  * (#306).
- * Control-flow bodies and `{ … }` brace groups are emitted whole without
- * descending (deferred).
+ * A compound statement (control flow, a function definition, a `{ … }` brace
+ * group) is emitted whole and then descended for the statements it contains,
+ * while its operand words — a loop variable, a word list, a `case` subject, a
+ * function's own name — are not commands and are left unemitted. An `ERROR`
+ * node is the one exception: its recovered structure is invented rather than
+ * observed, so the unparsed blob is emitted whole and never descended (#742).
  *
- * The enclosing command/subshell is always still emitted whole, so adding the
+ * The enclosing command/statement is always still emitted whole, so adding the
  * nested units can only ever produce a more-restrictive decision, never weaker.
  *
  * Each emitted command unit has any leading `variable_assignment` prefix
@@ -172,9 +236,33 @@ function collectCommandsInto(
     return;
   }
 
+  if (COMPOUND_STATEMENT_TYPES.has(node.type)) {
+    out.push(makeUnit(node.text, scope)); // never-weaker whole emit
+    descendStatementChildren(node, scope, out);
+    return;
+  }
+
+  if (STATEMENT_GROUP_TYPES.has(node.type)) {
+    descendStatementChildren(node, scope, out);
+    return;
+  }
+
+  if (node.type === "ERROR") {
+    // Tree-sitter's error recovery *invents* structure, so the node types
+    // inside an ERROR subtree are not evidence that anything runs: descending
+    // one turns backtick-quoted prose in an unterminated heredoc into command
+    // units. Emit the unparsed blob whole and stop (#742).
+    out.push(makeUnit(node.text, scope));
+    return;
+  }
+
   // Any other named statement (compound_statement `{ … }`, if/while/for/case,
   // function_definition): emit whole, do not descend — deferred (#306).
+  // A declaration, assignment, test, or `unset` still hosts executions that
+  // really run (`local x=$(rm y)`, `[[ $(rm x) ]]`), so those are enumerated
+  // in addition to the statement (#742).
   out.push(makeUnit(node.text, scope));
+  collectHostedCommands(node, out);
 }
 
 /** The wrapper facts a `command` node's words establish about its unit. */
@@ -291,6 +379,35 @@ function descendCommandChildren(
   }
 }
 
+/**
+ * Descend a compound statement's children, enumerating only the ones that are
+ * themselves statements.
+ *
+ * The filter is the whole difference from {@link descendCommandChildren}, whose
+ * container types (`program` / `list` / `pipeline` / `redirected_statement` /
+ * `subshell`) have nothing but statement children. Here the children are a mix,
+ * and a non-statement one is an operand word rather than something that runs.
+ *
+ * A non-statement child is not abandoned, though: `for f in $(rm x)` hosts a
+ * real execution in its word list, which is what the second branch reaches.
+ *
+ * The scope is relayed unchanged — a compound statement's body runs in the
+ * current shell, so a write established by an enclosing `redirected_statement`
+ * covers every unit beneath it (#803).
+ */
+function descendStatementChildren(
+  node: TSNode,
+  scope: UnitScope,
+  out: BashCommand[],
+): void {
+  for (let i = 0; i < node.childCount; i++) {
+    const child = node.child(i);
+    if (!child?.isNamed) continue;
+    if (STATEMENT_TYPES.has(child.type)) collectCommandsInto(child, scope, out);
+    else collectHostedCommands(child, out);
+  }
+}
+
 /**
  * Enumerate the commands of every nested execution context in a subtree, each
  * tagged with the context it was found in.
@@ -298,9 +415,12 @@ function descendCommandChildren(
  * The traversal itself lives in `nested-execution.ts` so the bash path surface
  * shares one definition of what counts as a nested execution (#741); this
  * function supplies the command-surface interpretation of each one found.
+ *
+ * `node` may be a context outright or merely host one, so the traversal is the
+ * root-inclusive `forEachExecutionIn`.
  */
 function collectHostedCommands(node: TSNode, out: BashCommand[]): void {
-  forEachNestedExecution(node, (contextNode, context) => {
+  forEachExecutionIn(node, (contextNode, context) => {
     // A nested execution starts fresh: an enclosing statement's redirect is
     // that statement's, not the substitution's, exactly as #807 attributes a
     // nested command's path tokens to its own command.

package/src/access-intent/bash/nested-execution.ts

@@ -47,6 +47,24 @@ export const EXECUTION_HOST_TYPES: ReadonlySet<string> = new Set([
   "heredoc_body",
 ]);
 
+/**
+ * Visit every execution context `node` *is or contains*, in source order.
+ *
+ * The root-inclusive question, and the one nearly every consumer asks: a node
+ * handed in can be a substitution outright (`> $(cmd)`) or merely host one
+ * (`> ${DIR}/$(cmd)`), and both really execute. {@link forEachNestedExecution}
+ * answers the strictly-within question instead, which is what a visitor needs
+ * once it has already decided to treat a context's interior itself.
+ */
+export function forEachExecutionIn(
+  node: TSNode,
+  visit: (contextNode: TSNode, context: BashCommandContext) => void,
+): void {
+  const context = NESTED_EXECUTION_CONTEXTS.get(node.type);
+  if (context) visit(node, context);
+  else forEachNestedExecution(node, visit);
+}
+
 /**
  * Visit every nested execution context in `node`'s subtree, in source order.
  *
@@ -58,6 +76,10 @@ export const EXECUTION_HOST_TYPES: ReadonlySet<string> = new Set([
  * A substitution can nest under `command_name` (when the whole command is
  * `$(…)`), under an argument, inside a redirect destination, or inside an
  * interpolating heredoc body, so the entire subtree is searched.
+ *
+ * `node` itself is never visited, however it is typed — use
+ * {@link forEachExecutionIn} when it may *be* a context rather than merely
+ * contain one.
  */
 export function forEachNestedExecution(
   node: TSNode,

package/src/access-intent/bash/token-collection.ts

@@ -2,8 +2,7 @@ import { basename } from "node:path";
 import { proveCommandEffect } from "#src/access-intent/bash/command-effects";
 import {
   EXECUTION_HOST_TYPES,
-  forEachNestedExecution,
-  NESTED_EXECUTION_CONTEXTS,
+  forEachExecutionIn,
 } from "#src/access-intent/bash/nested-execution";
 import {
   ARG_NODE_TYPES,
@@ -129,15 +128,12 @@ export function collectRedirectTokens(node: TSNode): PathToken[] {
  * its prose stays out of the path surface entirely.
  *
  * `node` may be a context outright (`> $(cmd)`) or merely contain one
- * (`> ${DIR}/$(cmd)`); `forEachNestedExecution` searches strictly within a
- * subtree, so the first case is checked here.
+ * (`> ${DIR}/$(cmd)`), so the traversal is the root-inclusive
+ * `forEachExecutionIn`.
  */
 function collectHostedExecutionTokens(node: TSNode): PathToken[] {
-  if (NESTED_EXECUTION_CONTEXTS.has(node.type)) {
-    return collectPathCandidateTokens(node);
-  }
   const tokens: PathToken[] = [];
-  forEachNestedExecution(node, (contextNode) => {
+  forEachExecutionIn(node, (contextNode) => {
     tokens.push(...collectPathCandidateTokens(contextNode));
   });
   return tokens;
@@ -201,6 +197,23 @@ function commandArgumentWords(node: TSNode): string[] {
   return words;
 }
 
+/**
+ * The children of a `command` node that supply no operand text of their own:
+ * its head word, and any env-var prefix assignment.
+ *
+ * Both are skipped as operands — the head word is not an argument, and a prefix
+ * assignment's value is assigned rather than accessed — but either can *host* a
+ * substitution that really runs (`$(cat /etc/shadow)`,
+ * `FOO=$(cat /etc/shadow) echo hi`), whose own operands are candidates like any
+ * other position (ADR 0009's positional invariance). The two walkers below are
+ * different state machines and so each carry their own skip, which is why the
+ * question is named here once rather than spelled twice (#742).
+ */
+const COMMAND_PREFIX_TYPES: ReadonlySet<string> = new Set([
+  "command_name",
+  "variable_assignment",
+]);
+
 /**
  * A long or short option carrying its value inline: one or two leading dashes,
  * a name containing no `=` or whitespace, then `=` and a non-empty value.
@@ -527,9 +540,11 @@ function collectPatternCommandTokens(
     const child = node.child(i);
     if (!child) continue;
 
-    // Skip command_name and variable_assignment nodes.
-    if (child.type === "command_name" || child.type === "variable_assignment")
+    if (COMMAND_PREFIX_TYPES.has(child.type)) {
+      // Supplies no operand of its own, but may host one that really runs.
+      tokens.push(...collectHostedExecutionTokens(child));
       continue;
+    }
 
     const isArgNode = ARG_NODE_TYPES.has(child.type);
     const text = resolveNodeText(child);
@@ -682,12 +697,12 @@ function collectGenericCommandTokens(
     const child = node.child(i);
     if (!child) continue;
 
-    if (child.type === "command_name") {
-      seenCommandName = true;
+    if (COMMAND_PREFIX_TYPES.has(child.type)) {
+      // Supplies no operand of its own, but may host one that really runs.
+      if (child.type === "command_name") seenCommandName = true;
+      tokens.push(...collectHostedExecutionTokens(child));
       continue;
     }
-    // Skip variable_assignment nodes (FOO=/bar)
-    if (child.type === "variable_assignment") continue;
 
     // If there was no explicit command_name node, the first word-like
     // child is the command name itself — skip it.

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,4 +1,5 @@
 import { join } from "node:path";
+import { resolutionFor } from "#src/authority/decision-resolution";
 import type { DecisionSource } from "#src/authority/decision-source";
 import {
   type ForwarderContext,
@@ -15,10 +16,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 +181,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 ────────────────────────────────────────────────
 
 /**

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 {
@@ -41,6 +45,55 @@ 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);
+  switch (decider.kind) {
+    case "authorizer":
+      return renderAuthorizerDenial(
+        payload,
+        decider.name,
+        denialReason,
+        budget,
+      );
+    case "unavailable":
+      return renderUnavailableDenial(payload, denialReason, budget);
+    // A `rule` here is a rule in the *serving* session, whose pattern and
+    // origin are not on this payload — `matchedPattern` is the pattern that
+    // raised this session's own ask, so naming a rule would name the wrong
+    // one. That render, and the `gate_error` one beside it, are #844. The
+    // remaining kinds never refuse: they only ever allow.
+    case "user":
+    case "rule":
+    case "gate_error":
+    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,
@@ -65,6 +118,26 @@ export function renderUserDenial(
   );
 }
 
+/**
+ * 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")}${boundaryClause(payload)}${provenanceClause(payload)}.`,
+    denialReason,
+  );
+}
+
 /** The agent-facing render when no live authority could answer the ask. */
 export function renderUnavailableDenial(
   payload: PromptPayload,