@gotgenes/pi-permission-system 28.0.0 → 28.0.1

package/CHANGELOG.md

@@ -5,6 +5,15 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [28.0.1](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v28.0.0...pi-permission-system-v28.0.1) (2026-08-30)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** carry a serving session's deny reason to the requesting agent ([b2010d7](https://github.com/gotgenes/pi-packages/commit/b2010d7bfbf766592b4ae0b98f16a612f96ff706)), closes [#844](https://github.com/gotgenes/pi-packages/issues/844)
+* **pi-permission-system:** name the rule that refused a forwarded call instead of blaming the user ([3d83641](https://github.com/gotgenes/pi-packages/commit/3d83641ad9bf6b045a86a4fb2879a7761c0aefc3)), closes [#844](https://github.com/gotgenes/pi-packages/issues/844)
+* **pi-permission-system:** tell the agent when the permission authority failed to answer ([8f70380](https://github.com/gotgenes/pi-packages/commit/8f70380005733546fa2df1d8694c50985332de19)), closes [#844](https://github.com/gotgenes/pi-packages/issues/844)
+
 ## [28.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v27.1.3...pi-permission-system-v28.0.0) (2026-08-30)
 
 

package/package.json

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

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

@@ -5,7 +5,10 @@ import {
   type ForwarderContext,
   getSessionId,
 } from "#src/authority/forwarder-context";
-import type { PermissionPromptDecision } from "#src/authority/permission-dialog";
+import {
+  createDeniedPermissionDecision,
+  type PermissionPromptDecision,
+} from "#src/authority/permission-dialog";
 import {
   type ForwardedAccessFacts,
   type ForwardedAccessIntent,
@@ -456,9 +459,12 @@ export class ForwardedRequestServer implements InboxProcessor {
           : "forwarded_permission.auto_denied",
         { ...logDetails, decidedBy },
       );
+      // A deny-with-reason rule's text is the operator's own explanation, and
+      // the requesting session relays it to its agent — so it travels with the
+      // verdict rather than stopping at the node that holds the config (#844).
       return approved
         ? { approved: true, state: "approved", decidedBy }
-        : { approved: false, state: "denied", decidedBy };
+        : { ...createDeniedPermissionDecision(check.reason), decidedBy };
     }
 
     this.logger.review("forwarded_permission.prompted", logDetails);

package/src/presentation/agent-renderer.ts

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