@gotgenes/pi-permission-system 25.4.0 → 26.1.0

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,
@@ -36,6 +37,7 @@ import type { ServingLookup } from "#src/authority/serving-registry";
 import type { SubagentSessionRegistry } from "#src/authority/subagent-registry";
 import { createPermissionRequestId } from "#src/permission-request-id";
 import { buildUiPrompt } from "#src/permission-ui-prompt";
+import type { PromptPayload } from "#src/presentation/prompt-payload";
 import type { DebugReviewLogger } from "#src/session-logger";
 import { toRecord } from "#src/value-guards";
 import type { TerminalAuthorizer } from "./authorizer";
@@ -68,7 +70,7 @@ function getContextSystemPrompt(ctx: ForwarderContext): string | undefined {
 
 /**
  * The facts a forwarded request relays unchanged from the child's ask: the
- * prompt message, the optional display projection, and the optional
+ * prompt payload, the optional display projection, and the optional
  * session-approval suggestion.
  *
  * Bundled into one object so the two-hop private chain
@@ -82,7 +84,8 @@ interface ForwardedRequestFacts {
    * decision instead of a third being minted here.
    */
   requestId: string;
-  message: string;
+  /** The child's complete prompt payload, relayed for the serving node to render. */
+  payload: PromptPayload;
   display?: ForwardedPromptDisplay;
   sessionApproval?: ForwardedSessionApproval;
   /** The child-fixed access facts; the edge completes them into a `ForwardedAccessIntent`. */
@@ -108,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 {
@@ -115,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,
+    },
   };
 }
 
@@ -171,7 +202,7 @@ export class ParentAuthorizer implements TerminalAuthorizer {
     const uiPrompt = buildUiPrompt(details);
     return this.waitForForwardedApproval(this.ctx, {
       requestId: details.requestId,
-      message: details.message,
+      payload: details.payload,
       display: {
         source: uiPrompt.source,
         surface: uiPrompt.surface,
@@ -300,7 +331,7 @@ export class ParentAuthorizer implements TerminalAuthorizer {
       requesterSessionId,
       targetSessionId,
       requesterAgentName,
-      message: facts.message,
+      payload: facts.payload,
       ...(facts.display
         ? {
             source: facts.display.source,
@@ -333,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,
@@ -341,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
@@ -49,9 +62,9 @@ export interface Authorizer {
  * ADR 0007's terminal-cannot-defer invariant.
  *
  * One method, one responsibility. `DenyingAuthorizer` ignores `details`;
- * `LocalUserAuthorizer` reads `message`/`sessionLabel` and derives the UI
- * event from it; `ParentAuthorizer` reads `message` and derives the
- * forwarded display from it.
+ * `LocalUserAuthorizer` renders `payload` for the human and derives the UI
+ * event from the request facts; `ParentAuthorizer` ships `payload` over the
+ * wire so the serving node renders it under its own budget.
  */
 export interface TerminalAuthorizer {
   authorize(

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,
@@ -14,7 +15,6 @@ import {
 } from "#src/authority/permission-forwarding";
 import type { SubagentSessionRegistry } from "#src/authority/subagent-registry";
 import { buildForwardedAskPayload } from "#src/presentation/forwarded-ask-payload";
-import { renderLegacyMessage } from "#src/presentation/legacy-message";
 import { SessionApproval } from "#src/session-approval";
 import type { SessionApprovalRecorder } from "#src/session-approval-recorder";
 import type { DebugReviewLogger } from "#src/session-logger";
@@ -23,6 +23,7 @@ import type { AskEscalator } from "./authorizer-selection";
 import {
   cleanupPermissionForwardingLocationIfEmpty,
   ensureDirectoryExists,
+  formatUnknownErrorMessage,
   getExistingPermissionForwardingLocation,
   listRequestFiles,
   logPermissionForwardingError,
@@ -100,7 +101,6 @@ function buildForwardedAskDetails(
     requestId: request.id,
     source: request.source ?? "tool_call",
     agentName: request.requesterAgentName || null,
-    message: renderLegacyMessage(payload),
     payload,
     surface: request.surface ?? null,
     value: request.value ?? null,
@@ -278,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,
@@ -300,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,
+    };
   }
 
   /**
@@ -329,6 +336,7 @@ export class ForwardedRequestServer implements InboxProcessor {
         responsePath,
         resolution: decision.state,
         denialReason: decision.denialReason ?? null,
+        decidedBy: decision.decidedBy,
       },
     );
     try {
@@ -338,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(
@@ -368,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 },
+      };
     }
   }