@gotgenes/pi-permission-system 26.0.0 → 26.1.0

package/CHANGELOG.md

@@ -5,6 +5,22 @@ 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).
 
+## [26.1.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v26.0.0...pi-permission-system-v26.1.0) (2026-08-17)
+
+
+### Features
+
+* **pi-permission-system:** attribute absent-authority denials ([225412d](https://github.com/gotgenes/pi-packages/commit/225412d485e68e886b6e958b2f53a87f9ff6cf25)), closes [#726](https://github.com/gotgenes/pi-packages/issues/726)
+* **pi-permission-system:** carry decision provenance across the forwarding boundary ([0dbf13f](https://github.com/gotgenes/pi-packages/commit/0dbf13f86c9f2d070e8b33eb4ffe808331c9185c)), closes [#726](https://github.com/gotgenes/pi-packages/issues/726)
+* **pi-permission-system:** name the authorizer link that decided an ask ([8556724](https://github.com/gotgenes/pi-packages/commit/8556724e5453ee002b24c48bebaf4d96f6502fe5)), closes [#726](https://github.com/gotgenes/pi-packages/issues/726)
+* **pi-permission-system:** record the decider on non-prompting resolutions ([5e24abf](https://github.com/gotgenes/pi-packages/commit/5e24abf6311d13928858e730b14a712e155f2bc2)), closes [#726](https://github.com/gotgenes/pi-packages/issues/726)
+* **pi-permission-system:** record the human decider on prompted decisions ([9f540ba](https://github.com/gotgenes/pi-packages/commit/9f540ba285b546976432733fced08b9fe9dc973c)), closes [#726](https://github.com/gotgenes/pi-packages/issues/726)
+
+
+### Documentation
+
+* **pi-permission-system:** record decision provenance and mark Phase 13 Step 6 complete ([e2739e7](https://github.com/gotgenes/pi-packages/commit/e2739e7f188669ee4878bbe3732958d4e1c54cbd)), closes [#726](https://github.com/gotgenes/pi-packages/issues/726)
+
 ## [26.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v25.4.0...pi-permission-system-v26.0.0) (2026-08-16)
 
 

package/docs/subagent-integration.md

@@ -54,6 +54,20 @@ None of them is reported as a user denial, because no user was ever asked.
 The two sides of the exchange are correlatable in the review log: the serving session writes `forwarded_permission.serving_started` with the id it polls, and the child writes `forwarded_permission.request_created` with the `targetSessionId` it forwarded to.
 When a forwarded request goes unanswered, comparing those two entries distinguishes a parent that was not polling from one polling a different session.
 
+When a forwarded request *is* answered, the child's own terminal entry names both which session answered and what within it decided.
+The serving node records its decider on the response — a rule of its own (with the surface, pattern, and origin that matched), the link that ruled, or the human who answered its dialog — and the child records it nested under a `forwarded` frame:
+
+```json
+{
+  "kind": "forwarded",
+  "responderSessionId": "019ff969-c34c-70be-9034-fae19c852932",
+  "decision": { "kind": "user", "via": "dialog" }
+}
+```
+
+That is the difference between a human approving a subagent's request and the parent's policy approving it on their behalf — two outcomes that were previously indistinguishable in the log.
+An older parent that sends no decider yields `"decision": null`: the hop is still recorded, and the answer is still honored.
+
 This liveness signal is process-local, so it applies to in-process children only.
 A child running as a separate `pi` process (the `PI_SUBAGENT_PARENT_SESSION` path) cannot observe its parent's polling and still waits the full timeout.
 

package/package.json

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

package/src/authority/approval-escalator.ts

@@ -23,6 +23,7 @@ import type { PermissionPromptDecision } from "#src/authority/permission-dialog"
 import {
   type ForwardedAccessFacts,
   type ForwardedPermissionRequest,
+  type ForwardedPermissionResponse,
   type ForwardedPromptDisplay,
   type ForwardedSessionApproval,
   PERMISSION_FORWARDING_POLL_INTERVAL_MS,
@@ -110,6 +111,9 @@ export interface ParentAuthorizerDeps {
  * `confirmationUnavailable` is what keeps this out of the "User denied …"
  * message (#719): a user who was never asked denied nothing. `denialReason`
  * names which path gave up, and the gate renders it to the model.
+ *
+ * The provenance record reuses that same string rather than restating it, so
+ * what the model is told and what the log attributes cannot drift (#726).
  */
 function abandon(denialReason: string): PermissionPromptDecision {
   return {
@@ -117,6 +121,31 @@ function abandon(denialReason: string): PermissionPromptDecision {
     state: "denied",
     confirmationUnavailable: true,
     denialReason,
+    decidedBy: { kind: "unavailable", reason: denialReason },
+  };
+}
+
+/**
+ * Adopt the responder's answer, recording the hop it came through.
+ *
+ * The requester's own terminal entry has to answer two questions, and they are
+ * different: *which session* answered, and *what within it* decided. Nesting
+ * keeps both rather than flattening the responder's source into this node's
+ * record, where it would read as a local decision (#726).
+ *
+ * A responder that sent no usable source yields `decision: null` — the hop is
+ * still a fact, and an older parent is not an error.
+ */
+function relayDecision(
+  response: ForwardedPermissionResponse,
+): PermissionPromptDecision {
+  return {
+    ...response,
+    decidedBy: {
+      kind: "forwarded",
+      responderSessionId: response.responderSessionId,
+      decision: response.decidedBy ?? null,
+    },
   };
 }
 
@@ -335,6 +364,7 @@ export class ParentAuthorizer implements TerminalAuthorizer {
           this.logger,
           responsePath,
         );
+        const relayed = response ? relayDecision(response) : null;
         this.logger.review("forwarded_permission.response_received", {
           requestId,
           approved: response?.approved ?? null,
@@ -343,10 +373,11 @@ export class ParentAuthorizer implements TerminalAuthorizer {
           responderSessionId: response?.responderSessionId ?? null,
           targetSessionId,
           responsePath,
+          decidedBy: relayed?.decidedBy,
         });
         this.discardRequest(location, requestPath, responsePath);
         return (
-          response ??
+          relayed ??
           abandon("The parent session's permission response could not be read")
         );
       }

package/src/authority/authorizer-chain.ts

@@ -1,10 +1,14 @@
+import type { DecisionSource } from "#src/authority/decision-source";
 import type { AuthorizerLog, PermissionQuery } from "#src/service";
 import type {
-  Authorizer,
   AuthorizerVerdict,
+  NamedAuthorizer,
   TerminalAuthorizer,
 } from "./authorizer";
-import { createDeniedPermissionDecision } from "./permission-dialog";
+import {
+  createDeniedPermissionDecision,
+  type PermissionPromptDecision,
+} from "./permission-dialog";
 
 /**
  * Compose the live-authority chain (ADR 0007): try each non-terminal `link`
@@ -12,9 +16,9 @@ import { createDeniedPermissionDecision } from "./permission-dialog";
  * context-selected `terminal` that always decides.
  *
  * The signature is the type-level terminal-cannot-defer invariant: `links` are
- * deferring {@link Authorizer}s while `terminal` is a {@link TerminalAuthorizer}
- * (returns a full decision), so a deferring link cannot occupy the terminal
- * slot.
+ * deferring {@link NamedAuthorizer}s while `terminal` is a
+ * {@link TerminalAuthorizer} (returns a full decision), so a deferring link
+ * cannot occupy the terminal slot.
  *
  * Each link is handed the session-scoped `query` and the review-log `log` at
  * `authorize` time (ADR 0007 §3) so it queries the deterministic engine at gate
@@ -24,7 +28,7 @@ import { createDeniedPermissionDecision } from "./permission-dialog";
  * ships until a link registers.
  */
 export function composeAuthorizerChain(
-  links: readonly Authorizer[],
+  links: readonly NamedAuthorizer[],
   terminal: TerminalAuthorizer,
   query: PermissionQuery,
   log: AuthorizerLog,
@@ -36,7 +40,7 @@ export function composeAuthorizerChain(
     async authorize(details) {
       for (const link of links) {
         const verdict = await link.authorize(details, query, log);
-        const decision = decideFromVerdict(verdict);
+        const decision = decideFromVerdict(link.name, verdict);
         if (decision) {
           return decision;
         }
@@ -47,16 +51,40 @@ export function composeAuthorizerChain(
   };
 }
 
-/** Map a link's decisive verdict to a decision; `defer` yields `null`. */
-function decideFromVerdict(verdict: AuthorizerVerdict) {
+/**
+ * Map a link's decisive verdict to a decision; `defer` yields `null`.
+ *
+ * The deciding link is named on the decision, not merely counted among the
+ * consulted set the selection already records: a link ahead of it that
+ * deferred decided nothing and must not be credited (#726).
+ */
+function decideFromVerdict(
+  name: string,
+  verdict: AuthorizerVerdict,
+): PermissionPromptDecision | null {
   switch (verdict.kind) {
     case "allow":
       // A link grant is non-persistent (state `approved`, never
       // `approved_for_session`), per ADR 0007's off-by-default envelope.
-      return { approved: true, state: "approved" } as const;
+      return {
+        approved: true,
+        state: "approved",
+        decidedBy: decidedByLink(name, "allow", null),
+      };
     case "deny":
-      return createDeniedPermissionDecision(verdict.reason);
+      return {
+        ...createDeniedPermissionDecision(verdict.reason),
+        decidedBy: decidedByLink(name, "deny", verdict.reason ?? null),
+      };
     case "defer":
       return null;
   }
 }
+
+function decidedByLink(
+  name: string,
+  verdict: "allow" | "deny",
+  reason: string | null,
+): DecisionSource {
+  return { kind: "authorizer", name, verdict, reason };
+}

package/src/authority/authorizer-selection.ts

@@ -2,8 +2,8 @@ import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { PermissionPromptDecision } from "#src/authority/permission-dialog";
 import type { PermissionQuery } from "#src/service";
 import {
-  type Authorizer,
   type AuthorizerSelectionDeps,
+  type NamedAuthorizer,
   type SelectedAuthority,
   selectAuthorizer,
 } from "./authorizer";
@@ -93,7 +93,7 @@ export class AuthorizerSelection
   private linksFor(
     authority: SelectedAuthority,
     requestId: string,
-  ): Authorizer[] {
+  ): NamedAuthorizer[] {
     const configured = this.deps.getAuthorizerChain();
     if (configured.length === 0) {
       return [];
@@ -123,8 +123,8 @@ export class AuthorizerSelection
   private resolveConfiguredLinks(
     configured: readonly string[],
     requestId: string,
-  ): Authorizer[] {
-    const links: Authorizer[] = [];
+  ): NamedAuthorizer[] {
+    const links: NamedAuthorizer[] = [];
     const resolved: string[] = [];
     for (const name of configured) {
       const authorize = this.deps.authorizerRegistry.get(name);
@@ -136,7 +136,7 @@ export class AuthorizerSelection
         continue;
       }
       resolved.push(name);
-      links.push({ authorize: encloseInDelegationEnvelope(authorize) });
+      links.push({ name, authorize: encloseInDelegationEnvelope(authorize) });
     }
     if (resolved.length > 0) {
       this.deps.logger.review("authorizer_chain_resolved", {

package/src/authority/authorizer.ts

@@ -42,6 +42,19 @@ export interface Authorizer {
   ): Promise<AuthorizerVerdict>;
 }
 
+/**
+ * A resolved chain link together with the operator-configured name it came
+ * from.
+ *
+ * `AuthorizerRegistry` already keys links by name, and `AuthorizerSelection`
+ * has the name in scope when it resolves the operator's `authorizerChain`; the
+ * name is carried through composition so a decision record can say *which*
+ * link decided rather than only which links were consulted.
+ */
+export interface NamedAuthorizer extends Authorizer {
+  readonly name: string;
+}
+
 /**
  * The terminal link: on `ask`, rules on a single request and is told the
  * decision. Structurally cannot defer — it always returns a full

package/src/authority/decision-source.ts

@@ -0,0 +1,235 @@
+/**
+ * What decided a permission request, recorded at the site that decided it.
+ *
+ * The decision paths are already distinct in the code — a session hit, a yolo
+ * grant, an infrastructure read, a config rule, a chain link, a human at a
+ * dialog, an unreachable authority — and each one knows what it is at the
+ * moment it decides. This is that fact, carried to the record instead of being
+ * discarded and re-guessed from an event name downstream.
+ *
+ * Every variant is **self-contained**: it repeats the detail that made it
+ * decisive rather than leaning on a sibling log column. That duplicates
+ * `surface` and the pattern on a local review line, and it is the only shape
+ * that survives the forwarding hop, where the response file has no such
+ * columns to lean on.
+ */
+
+/** Which human-facing surface the operator answered on. */
+export type UserDecisionSurface = "dialog" | "select";
+
+export type DecisionSource =
+  /** A human ruled, at the inline dialog or the `select`/`input` fallback. */
+  | { kind: "user"; via: UserDecisionSurface }
+  /** A registered `authorizerChain` link ruled; `name` is the configured name. */
+  | {
+      kind: "authorizer";
+      name: string;
+      verdict: "allow" | "deny";
+      reason: string | null;
+    }
+  /** Recorded authority: a rule in the composed ruleset matched. */
+  | {
+      kind: "rule";
+      surface: string;
+      pattern: string | null;
+      origin: string | null;
+    }
+  /** A session-scoped grant the operator made earlier in this session. */
+  | { kind: "session_approval"; surface: string; pattern: string | null }
+  /**
+   * `yoloMode`. `pattern` preserves the ask's matched rule — including a
+   * synthetic sentinel such as `<opaque-bash-wrapper>` — which is what makes a
+   * yolo grant over a synthesized ask legible.
+   */
+  | { kind: "yolo"; pattern: string | null }
+  /** A Pi infrastructure read, allowed by containment rather than by a rule. */
+  | { kind: "infrastructure_read" }
+  /**
+   * No authority ever ruled: none was reachable, or the forwarding path gave
+   * up before reaching one. `reason` names which path gave up.
+   */
+  | { kind: "unavailable"; reason: string }
+  /** A gate threw, and the boundary blocked rather than allowed. */
+  | { kind: "gate_error"; reason: string }
+  /**
+   * Another session decided. Recursive by design: the requesting side records
+   * both that the decider was elsewhere and what, within that session, decided
+   * — which is the distinction an audit of a forwarded ask needs.
+   *
+   * `decision` is `null` when the responder sent none (an older parent).
+   */
+  | {
+      kind: "forwarded";
+      responderSessionId: string | null;
+      decision: DecisionSource | null;
+    };
+
+/**
+ * How deep a `forwarded` chain may nest before {@link asDecisionSource} gives
+ * up.
+ *
+ * Forwarding is depth-1 by invariant (child → root) and a relay hop makes it
+ * two, so this is headroom rather than a working limit. It exists because the
+ * value is read off disk: a recursive reader over a file another process wrote
+ * is a stack-overflow surface, and the fail-closed answer is to stop.
+ */
+export const MAX_DECISION_SOURCE_DEPTH = 4;
+
+/**
+ * Narrow an unknown value to a {@link DecisionSource}, or `undefined`.
+ *
+ * Lives beside its type so a new variant updates the guard next door, following
+ * `asPromptPayload` and `isPermissionDecisionState`. All-or-nothing: a
+ * malformed field — at any nesting level — yields `undefined` rather than a
+ * half-parsed record, because a provenance record that names a decider who did
+ * not decide is worse than one that names none.
+ */
+export function asDecisionSource(value: unknown): DecisionSource | undefined {
+  return narrowSource(value, MAX_DECISION_SOURCE_DEPTH);
+}
+
+function narrowSource(
+  value: unknown,
+  depthBudget: number,
+): DecisionSource | undefined {
+  const candidate = asObject(value);
+  if (!candidate) return undefined;
+
+  switch (candidate.kind) {
+    case "user":
+      return narrowUser(candidate);
+    case "authorizer":
+      return narrowAuthorizer(candidate);
+    case "rule":
+      return narrowRule(candidate);
+    case "session_approval":
+      return narrowSessionApproval(candidate);
+    case "yolo":
+      return isNullableString(candidate.pattern)
+        ? { kind: "yolo", pattern: candidate.pattern }
+        : undefined;
+    case "infrastructure_read":
+      return { kind: "infrastructure_read" };
+    case "unavailable":
+      return typeof candidate.reason === "string"
+        ? { kind: "unavailable", reason: candidate.reason }
+        : undefined;
+    case "gate_error":
+      return typeof candidate.reason === "string"
+        ? { kind: "gate_error", reason: candidate.reason }
+        : undefined;
+    case "forwarded":
+      return narrowForwarded(candidate, depthBudget);
+    default:
+      return undefined;
+  }
+}
+
+function narrowUser(
+  candidate: Record<string, unknown>,
+): DecisionSource | undefined {
+  const via = USER_DECISION_SURFACES.find((entry) => entry === candidate.via);
+  return via ? { kind: "user", via } : undefined;
+}
+
+function narrowAuthorizer(
+  candidate: Record<string, unknown>,
+): DecisionSource | undefined {
+  const verdict = AUTHORIZER_VERDICTS.find(
+    (entry) => entry === candidate.verdict,
+  );
+  if (
+    !verdict ||
+    typeof candidate.name !== "string" ||
+    !isNullableString(candidate.reason)
+  ) {
+    return undefined;
+  }
+  return {
+    kind: "authorizer",
+    name: candidate.name,
+    verdict,
+    reason: candidate.reason,
+  };
+}
+
+function narrowRule(
+  candidate: Record<string, unknown>,
+): DecisionSource | undefined {
+  if (
+    typeof candidate.surface !== "string" ||
+    !isNullableString(candidate.pattern) ||
+    !isNullableString(candidate.origin)
+  ) {
+    return undefined;
+  }
+  return {
+    kind: "rule",
+    surface: candidate.surface,
+    pattern: candidate.pattern,
+    origin: candidate.origin,
+  };
+}
+
+function narrowSessionApproval(
+  candidate: Record<string, unknown>,
+): DecisionSource | undefined {
+  if (
+    typeof candidate.surface !== "string" ||
+    !isNullableString(candidate.pattern)
+  ) {
+    return undefined;
+  }
+  return {
+    kind: "session_approval",
+    surface: candidate.surface,
+    pattern: candidate.pattern,
+  };
+}
+
+/**
+ * The inner decision is narrowed against a decremented budget, so a chain
+ * deeper than {@link MAX_DECISION_SOURCE_DEPTH} is rejected whole rather than
+ * truncated — a truncated chain would silently attribute the decision to the
+ * last frame that fit.
+ */
+function narrowForwarded(
+  candidate: Record<string, unknown>,
+  depthBudget: number,
+): DecisionSource | undefined {
+  if (depthBudget <= 0 || !isNullableString(candidate.responderSessionId)) {
+    return undefined;
+  }
+  if (candidate.decision === null) {
+    return {
+      kind: "forwarded",
+      responderSessionId: candidate.responderSessionId,
+      decision: null,
+    };
+  }
+  const decision = narrowSource(candidate.decision, depthBudget - 1);
+  return decision
+    ? {
+        kind: "forwarded",
+        responderSessionId: candidate.responderSessionId,
+        decision,
+      }
+    : undefined;
+}
+
+const USER_DECISION_SURFACES = [
+  "dialog",
+  "select",
+] as const satisfies readonly UserDecisionSurface[];
+
+const AUTHORIZER_VERDICTS = ["allow", "deny"] as const;
+
+function asObject(value: unknown): Record<string, unknown> | undefined {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : undefined;
+}
+
+function isNullableString(value: unknown): value is string | null {
+  return value === null || typeof value === "string";
+}

package/src/authority/denying-authorizer.ts

@@ -1,6 +1,9 @@
 import type { PermissionPromptDecision } from "#src/authority/permission-dialog";
 import type { TerminalAuthorizer } from "./authorizer";
 
+/** Why this authorizer denies; the provenance record's `reason` (#726). */
+const NO_AUTHORITY_REASON = "No live authority was reachable for this session";
+
 /**
  * Least-privilege Authorizer: no authority is reachable for this session
  * (no UI, not a subagent), so every ask is denied.
@@ -15,6 +18,7 @@ export class DenyingAuthorizer implements TerminalAuthorizer {
       approved: false,
       state: "denied",
       confirmationUnavailable: true,
+      decidedBy: { kind: "unavailable", reason: NO_AUTHORITY_REASON },
     });
   }
 }

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

@@ -1,4 +1,5 @@
 import { join } from "node:path";
+import type { DecisionSource } from "#src/authority/decision-source";
 import {
   type ForwarderContext,
   getSessionId,
@@ -22,6 +23,7 @@ import type { AskEscalator } from "./authorizer-selection";
 import {
   cleanupPermissionForwardingLocationIfEmpty,
   ensureDirectoryExists,
+  formatUnknownErrorMessage,
   getExistingPermissionForwardingLocation,
   listRequestFiles,
   logPermissionForwardingError,
@@ -276,6 +278,9 @@ export class ForwardedRequestServer implements InboxProcessor {
    * `approved` so the child records nothing (its next identical action
    * re-forwards and resolves as recorded authority). Every other decision
    * passes through unchanged (`approved_for_session` → the child records).
+   *
+   * The translation rewrites the grant's *scope*, never its decider: the human
+   * who chose the wider scope is still the one who decided (#726).
    */
   private applyGrantScope(
     request: ForwardedPermissionRequest,
@@ -298,7 +303,11 @@ export class ForwardedRequestServer implements InboxProcessor {
         patterns: request.sessionApproval.patterns,
       });
     }
-    return { approved: true, state: "approved" };
+    return {
+      approved: true,
+      state: "approved",
+      decidedBy: decision.decidedBy,
+    };
   }
 
   /**
@@ -327,6 +336,7 @@ export class ForwardedRequestServer implements InboxProcessor {
         responsePath,
         resolution: decision.state,
         denialReason: decision.denialReason ?? null,
+        decidedBy: decision.decidedBy,
       },
     );
     try {
@@ -336,6 +346,9 @@ export class ForwardedRequestServer implements InboxProcessor {
         denialReason: decision.denialReason,
         responderSessionId: currentSessionId,
         respondedAt: Date.now(),
+        // Carried onto the wire so the requester can name what decided inside
+        // this session, not merely that this session answered (#726).
+        decidedBy: decision.decidedBy,
       } satisfies ForwardedPermissionResponse);
     } catch (error) {
       logPermissionForwardingError(
@@ -366,29 +379,48 @@ export class ForwardedRequestServer implements InboxProcessor {
     request: ForwardedPermissionRequest,
     logDetails: Record<string, unknown>,
   ): Promise<PermissionPromptDecision> {
-    const state = request.accessIntent
-      ? this.policy.resolve(request.accessIntent).state
-      : "ask";
+    const check = request.accessIntent
+      ? this.policy.resolve(request.accessIntent)
+      : null;
 
-    if (state === "allow") {
-      this.logger.review("forwarded_permission.auto_approved", logDetails);
-      return { approved: true, state: "approved" };
-    }
-    if (state === "deny") {
-      this.logger.review("forwarded_permission.auto_denied", logDetails);
-      return { approved: false, state: "denied" };
+    if (check && check.state !== "ask") {
+      // The rule is carried in full rather than left to the event name: the
+      // response file has no surface, pattern, or origin column for the
+      // requester's record to lean on.
+      const decidedBy: DecisionSource = {
+        kind: "rule",
+        surface: request.accessIntent?.surface ?? check.toolName,
+        pattern: check.matchedPattern ?? null,
+        origin: check.origin,
+      };
+      const approved = check.state === "allow";
+      this.logger.review(
+        approved
+          ? "forwarded_permission.auto_approved"
+          : "forwarded_permission.auto_denied",
+        { ...logDetails, decidedBy },
+      );
+      return approved
+        ? { approved: true, state: "approved", decidedBy }
+        : { approved: false, state: "denied", decidedBy };
     }
 
     this.logger.review("forwarded_permission.prompted", logDetails);
     try {
       return await this.escalator.escalate(buildForwardedAskDetails(request));
     } catch (error) {
+      const reason = formatUnknownErrorMessage(error);
       logPermissionForwardingError(
         this.logger,
         `Failed to escalate forwarded permission request '${request.id}'`,
         error,
       );
-      return { approved: false, state: "denied" };
+      // Nobody denied this; the escalation broke and the node failed closed.
+      return {
+        approved: false,
+        state: "denied",
+        decidedBy: { kind: "gate_error", reason },
+      };
     }
   }
 

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,
@@ -466,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,4 +1,5 @@
 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";
@@ -163,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,3 +1,4 @@
+import type { DecisionSource } from "#src/authority/decision-source";
 import type { PermissionPromptDecision } from "#src/authority/permission-dialog";
 import type {
   ForwardedAccessFacts,
@@ -131,6 +132,7 @@ export class PermissionPrompter implements PermissionPrompterApi {
           ? "confirmation_unavailable"
           : decision.state,
         denialReason: decision.denialReason,
+        decidedBy: decision.decidedBy,
       },
     );
 
@@ -139,14 +141,20 @@ 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,

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

@@ -47,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: {

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

@@ -84,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: {

package/src/handlers/gates/descriptor.ts

@@ -1,3 +1,4 @@
+import type { DecisionSource } from "#src/authority/decision-source";
 import type { PromptPermissionDetails } from "#src/authority/permission-prompter";
 import type { PermissionDecisionEvent } from "#src/permission-events";
 import type { PromptPayload } from "#src/presentation/prompt-payload";
@@ -79,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. */

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

@@ -45,6 +45,8 @@ export function describeExternalDirectoryGate(
   if (normalizer.isInfrastructureRead(tcc.toolName, accessPath, infraDirs)) {
     return {
       action: "allow",
+      // Containment allowed this, not a rule the operator wrote.
+      decidedBy: { kind: "infrastructure_read" },
       log: {
         event: "permission_request.infrastructure_auto_allowed",
         details: {

package/src/handlers/gates/runner.ts

@@ -66,6 +66,7 @@ export class GateRunner {
         this.reporter.writeReviewLog(gate.log.event, {
           ...gate.log.details,
           requestId,
+          decidedBy: gate.decidedBy,
         });
       }
       if (gate.decision) {
@@ -123,12 +124,22 @@ export class GateRunner {
       requestId,
     };
 
+    // Each resolution below states its own decider. The provenance is built
+    // at the branch that decides rather than merged into `logContext`: that
+    // context holds what every resolution of this gate shares, and who decided
+    // is by definition not shared (#726).
+
     // 2. Session-hit fast path
     if (check.source === "session") {
       this.reporter.writeReviewLog("permission_request.session_approved", {
         ...logContext,
         resolution: "session_approved",
         sessionApprovalPattern: check.matchedPattern,
+        decidedBy: {
+          kind: "session_approval",
+          surface: descriptor.surface,
+          pattern: check.matchedPattern ?? null,
+        },
       });
       this.emitDecision(
         requestId,
@@ -152,6 +163,9 @@ export class GateRunner {
       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 },
       });
       this.emitDecision(
         requestId,
@@ -202,6 +216,12 @@ export class GateRunner {
       writeLog: (event, details) =>
         this.reporter.writeReviewLog(event, details),
       logContext,
+      decidedByRule: {
+        kind: "rule",
+        surface: descriptor.surface,
+        pattern: check.matchedPattern ?? null,
+        origin: check.origin,
+      },
       messages,
     });
 

package/src/handlers/tool-call-boundary.ts

@@ -76,12 +76,15 @@ function recordGateError(
 ): void {
   try {
     audit.recordError();
+    const reason = errorMessage(error);
     reporter.writeReviewLog("permission_request.blocked", {
       requestId: createPermissionRequestId(),
       toolName: bestEffortToolName(event),
       command: bestEffortCommand(event),
       resolution: "gate_error",
-      error: errorMessage(error),
+      error: reason,
+      // The boundary decided, by failing closed -- no rule and no human did.
+      decidedBy: { kind: "gate_error", reason },
     });
   } catch {
     // The block is the guarantee; its bookkeeping is not.

package/src/permission-gate.ts

@@ -1,3 +1,4 @@
+import type { DecisionSource } from "#src/authority/decision-source";
 import type { PermissionPromptDecision } from "#src/authority/permission-dialog";
 
 /** Result of applying the permission gate. */
@@ -30,6 +31,15 @@ export interface PermissionGateParams {
   /** Log context fields shared across all log calls for this gate. */
   logContext: Record<string, unknown>;
 
+  /**
+   * The rule that resolved this gate, for 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
+   * definition not shared (#726).
+   */
+  decidedByRule: DecisionSource;
+
   /** Message strings/factories for each outcome. */
   messages: {
     denyReason: string;
@@ -52,6 +62,7 @@ export async function applyPermissionGate(
     writeLog("permission_request.blocked", {
       ...logContext,
       resolution: "policy_denied",
+      decidedBy: params.decidedByRule,
     });
     return { action: "block", reason: messages.denyReason };
   }