@gotgenes/pi-permission-system 26.2.2 → 26.3.0

package/CHANGELOG.md

@@ -5,6 +5,19 @@ 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.3.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v26.2.2...pi-permission-system-v26.3.0) (2026-08-18)
+
+
+### Features
+
+* **pi-permission-system:** broadcast a terminal decision when a gate error blocks a tool call ([2ccb8e5](https://github.com/gotgenes/pi-packages/commit/2ccb8e50a4ef376ced8448efba2d5f9f3658e98f)), closes [#753](https://github.com/gotgenes/pi-packages/issues/753)
+* **pi-permission-system:** broadcast the terminal decision for a served forwarded ask ([f2d6b17](https://github.com/gotgenes/pi-packages/commit/f2d6b176abdd47a2b3ce5c3cf6973ba316d5eea6)), closes [#610](https://github.com/gotgenes/pi-packages/issues/610)
+
+
+### Documentation
+
+* **pi-permission-system:** document the served forwarded decision broadcast ([fc2b00b](https://github.com/gotgenes/pi-packages/commit/fc2b00bb801468b450a725e0cb4e9da7e5279844))
+
 ## [26.2.2](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v26.2.1...pi-permission-system-v26.2.2) (2026-08-18)
 
 

package/README.md

@@ -19,9 +19,9 @@ Permission enforcement extension for the [Pi](https://pi.mariozechner.at/) codin
 - **Gates MCP and skill access** at server, tool, and skill-name granularity
 - **Protects sensitive file patterns** — cross-cutting `path` rules deny `.env`, `~/.ssh/*`, etc. across all tools and bash at once, matching both the path as referenced and its symlink-resolved form so a deny cannot be evaded through a symlink alias
 - **Guards external paths** — prompts before file tools or bash commands reach outside `cwd`
-- **Fails closed** — an internal gate error blocks the tool (with a `gate_error` review-log entry), and an unparseable bash command — or an indirection wrapper that hides the gated command (`bash -c`/`eval`, `sudo`, `env`, `xargs`, `find -exec`, …) — prompts (`ask`) rather than passing silently
+- **Fails closed** — an internal gate error blocks the tool (with a `gate_error` review-log entry and a matching `permissions:decision` broadcast), and an unparseable bash command — or an indirection wrapper that hides the gated command (`bash -c`/`eval`, `sudo`, `env`, `xargs`, `find -exec`, …) — prompts (`ask`) rather than passing silently
 - **Forwards prompts from subagents** — `ask` policies work even in non-UI execution contexts
-- **Broadcasts UI prompt events** — `permissions:ui_prompt` fires only when the permission system is about to invoke the active user-facing permission UI
+- **Broadcasts UI prompt events** — `permissions:ui_prompt` fires only when the permission system is about to invoke the active user-facing permission UI, and every prompt it announces — including one forwarded up from a subagent — is answered by a `permissions:decision` on the same bus
 - **Native [`@gotgenes/pi-subagents`](https://github.com/gotgenes/pi-subagents) integration** — in-process child sessions register with the permission system automatically, enabling per-agent policy enforcement and `ask`-state forwarding to the parent UI without configuration
 
 ## Install

package/dist/public.d.ts

@@ -225,7 +225,9 @@ interface PermissionUiPromptEvent {
     forwarding: ForwardedPromptContext | null;
 }
 /** 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";
+type PermissionDecisionResolution = "policy_allow" | "policy_deny" | "session_approved" | "infrastructure_auto_allowed" | "user_approved" | "user_approved_for_session" | "user_denied" | "auto_approved" | "confirmation_unavailable"
+/** The gate threw, or an escalation failed, and the request was blocked. */
+ | "gate_error";
 /** Payload emitted on `permissions:decision`. */
 interface PermissionDecisionEvent {
     /**
@@ -248,6 +250,16 @@ interface PermissionDecisionEvent {
     agentName: string | null;
     /** Matched pattern from the winning rule (when available). */
     matchedPattern: string | null;
+    /**
+     * Forwarding context for a decision this session made while serving another
+     * session's forwarded request; absent on an ordinary local decision.
+     *
+     * The same `ForwardedPromptContext` the request's `permissions:ui_prompt`
+     * carried, so a consumer that never saw the prompt can still tell a served
+     * ask from a local one. Requester identity beyond it — the requester's cwd
+     * and principal — stays off the bus.
+     */
+    forwarding?: ForwardedPromptContext | null;
 }
 
 /**

package/docs/cross-extension-api.md

@@ -315,6 +315,7 @@ It is not a generic "permission request entered waiting state" event, and it doe
 Policy decisions that resolve without an active UI prompt, such as `policy_allow`, `policy_deny`, `session_approved`, `infrastructure_auto_allowed`, or `auto_approved`, do not emit this event.
 Non-UI child sessions also do not emit this event when they create a forwarded permission request; the parent UI session emits it immediately before showing the forwarded permission dialog.
 A forwarded request the parent's own recorded policy decides (a matching `allow` or `deny`) is answered without a prompt and emits no event; the event fires only when the parent is actually about to ask the human.
+The matching terminal `permissions:decision` is emitted in the parent session too, so a consumer that reacts to this event has a signal on the same bus telling it the prompt is over.
 Forwarded prompts that do reach the human are not degraded: the parent emits the child's original `source` and the same `surface`/`value` display projection, plus a populated `forwarding` context identifying the requesting subagent.
 
 The payload is lean by design — `surface`/`value` are the normalized display projection a notification consumer reads, not a mirror of the internal review log.
@@ -393,7 +394,13 @@ The stability guarantee is additive, so any can be reintroduced in a later minor
 Every permission gate resolution emits a `permissions:decision` event, regardless of outcome.
 This is useful for dashboards, telemetry, or audit overlays.
 
+A session serving another session's forwarded request emits one too, on its own bus, for every forwarded ask it escalates.
+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.
+
 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.
 It identifies a permission *request*, not a tool call: one tool call runs several gates and so raises several requests, each with its own id.
 Use the review log's `toolCallId` to join back to the Pi transcript.
 
@@ -407,16 +414,17 @@ pi.events.on("permissions:decision", (raw) => {
 
 ### Payload Fields
 
-| Field            | Type                | Description                                                                               |
-| ---------------- | ------------------- | ----------------------------------------------------------------------------------------- |
-| `requestId`      | `string`            | Id of the permission request this decision resolves                                       |
-| `surface`        | `string`            | Permission surface (`"bash"`, `"read"`, `"mcp"`, `"skill"`, `"external_directory"`, etc.) |
-| `value`          | `string`            | Value evaluated (command, tool name, skill name, path)                                    |
-| `result`         | `"allow" \| "deny"` | Final outcome                                                                             |
-| `resolution`     | `string`            | How the outcome was reached (see table below)                                             |
-| `origin`         | `string \| null`    | Config scope that contributed the winning rule                                            |
-| `agentName`      | `string \| null`    | Active agent name when known                                                              |
-| `matchedPattern` | `string \| null`    | Pattern from the winning rule                                                             |
+| Field            | Type                                        | Description                                                                                           |
+| ---------------- | ------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `requestId`      | `string`                                    | Id of the permission request this decision resolves                                                   |
+| `surface`        | `string`                                    | Permission surface (`"bash"`, `"read"`, `"mcp"`, `"skill"`, `"external_directory"`, etc.)             |
+| `value`          | `string`                                    | Value evaluated (command, tool name, skill name, path)                                                |
+| `result`         | `"allow" \| "deny"`                         | Final outcome                                                                                         |
+| `resolution`     | `string`                                    | How the outcome was reached (see table below)                                                         |
+| `origin`         | `string \| null`                            | Config scope that contributed the winning rule                                                        |
+| `agentName`      | `string \| null`                            | Active agent name when known                                                                          |
+| `matchedPattern` | `string \| null`                            | Pattern from the winning rule                                                                         |
+| `forwarding`     | `ForwardedPromptContext \| null` (optional) | Requesting subagent, on a decision made while serving a forwarded request; absent on a local decision |
 
 ### Resolution Values
 
@@ -431,6 +439,7 @@ pi.events.on("permissions:decision", (raw) => {
 | `user_denied`                 | User denied via dialog                                               |
 | `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": "26.2.2",
+  "version": "26.3.0",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
   "exports": {

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

@@ -14,6 +14,11 @@ import {
   type PermissionForwardingLocation,
 } 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 { buildForwardedAskPayload } from "#src/presentation/forwarded-ask-payload";
 import { SessionApproval } from "#src/session-approval";
 import type { SessionApprovalRecorder } from "#src/session-approval-recorder";
@@ -70,6 +75,14 @@ export interface ForwardedRequestServerDeps {
   policy: ServingPolicy;
   /** Escalation seam to the serving session's selected `Authorizer` on `ask`. */
   escalator: AskEscalator;
+  /**
+   * Terminal-decision broadcast for an ask this session served.
+   *
+   * A forwarded ask is prompted here but gated in the requesting session — on
+   * another event bus for an out-of-process child — so without this the
+   * parent's own consumers observe a prompt that never ends (#610).
+   */
+  broadcaster: DecisionBroadcaster;
   /**
    * The serving session's `SessionRules`. Records a whole-session grant when a
    * human approves a forwarded request for the entire serving session.
@@ -143,6 +156,68 @@ function toAccessFacts(intent: ForwardedAccessIntent): ForwardedAccessFacts {
   };
 }
 
+/**
+ * Build the terminal `permissions:decision` for an ask this session served.
+ *
+ * Rendered from the same {@link PromptPermissionDetails} the `ui_prompt`
+ * broadcast was built from, so prompt and decision carry one projection by
+ * construction rather than by convention — which is what makes them joinable
+ * beyond the shared request id.
+ *
+ * `origin` and `matchedPattern` are `null` by construction: an escalated
+ * request is one recorded authority did *not* decide, so no rule won. The
+ * decider stays off the bus, which discloses request facts and verdicts only
+ * (ADR 0011 §6, #726).
+ */
+function buildServedDecisionEvent(
+  details: PromptPermissionDetails,
+  decision: PermissionPromptDecision,
+): PermissionDecisionEvent {
+  const facts = details.payload.request;
+  return {
+    requestId: details.requestId,
+    // The child's display projection, falling back to the payload's own facts
+    // for a version-skewed request that carried none. Both are non-nullable
+    // there, so the event's non-null contract holds without a sentinel.
+    surface: details.surface ?? facts.surface,
+    value: details.value ?? facts.value,
+    agentName: details.agentName,
+    result: decision.approved ? "allow" : "deny",
+    resolution: servedResolution(decision),
+    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 ────────────────────────────────────────────────
 
 /**
@@ -158,6 +233,7 @@ export class ForwardedRequestServer implements InboxProcessor {
   private readonly logger: DebugReviewLogger;
   private readonly policy: ServingPolicy;
   private readonly escalator: AskEscalator;
+  private readonly broadcaster: DecisionBroadcaster;
   private readonly recorder: SessionApprovalRecorder;
   private readonly registry: SubagentSessionRegistry | undefined;
 
@@ -166,6 +242,7 @@ export class ForwardedRequestServer implements InboxProcessor {
     this.logger = deps.logger;
     this.policy = deps.policy;
     this.escalator = deps.escalator;
+    this.broadcaster = deps.broadcaster;
     this.recorder = deps.recorder;
     this.registry = deps.registry;
   }
@@ -406,16 +483,35 @@ export class ForwardedRequestServer implements InboxProcessor {
     }
 
     this.logger.review("forwarded_permission.prompted", logDetails);
+    const details = buildForwardedAskDetails(request);
+    const decision = await this.escalateAsk(details);
+    // Announced before the grant-scope translation and before the response is
+    // written: the ask this session broadcast is over once someone here has
+    // answered it, whatever becomes of the file the child polls for (#610).
+    this.broadcaster.emitDecision(buildServedDecisionEvent(details, decision));
+    return decision;
+  }
+
+  /**
+   * Escalate a forwarded ask to the serving session's selected `Authorizer`,
+   * failing closed instead of throwing: an escalation that breaks is nobody's
+   * denial, so the node records itself as the decider.
+   *
+   * Separate from {@link resolveDecision} so the ask's details outlive the
+   * call — every record of the served ask is a render over that one object.
+   */
+  private async escalateAsk(
+    details: PromptPermissionDetails,
+  ): Promise<PermissionPromptDecision> {
     try {
-      return await this.escalator.escalate(buildForwardedAskDetails(request));
+      return await this.escalator.escalate(details);
     } catch (error) {
       const reason = formatUnknownErrorMessage(error);
       logPermissionForwardingError(
         this.logger,
-        `Failed to escalate forwarded permission request '${request.id}'`,
+        `Failed to escalate forwarded permission request '${details.requestId}'`,
         error,
       );
-      // Nobody denied this; the escalation broke and the node failed closed.
       return {
         approved: false,
         state: "denied",

package/src/decision-reporter.ts

@@ -5,14 +5,25 @@ import {
 } from "./permission-events";
 import type { SessionLogger } from "./session-logger";
 
+/**
+ * Broadcasts a terminal permission decision on the `permissions:decision`
+ * channel.
+ *
+ * Narrow by design (ISP): a collaborator that only announces an outcome — the
+ * serving session answering another session's forwarded request — depends on
+ * this rather than on the review-log half it never writes.
+ */
+export interface DecisionBroadcaster {
+  emitDecision(event: PermissionDecisionEvent): void;
+}
+
 /**
  * Reports a permission gate's outcome to the review log and the decision
  * channel. Groups the two side effects that always travel together:
  * writing a structured review-log entry and broadcasting a decision event.
  */
-export interface DecisionReporter {
+export interface DecisionReporter extends DecisionBroadcaster {
   writeReviewLog(event: string, details: Record<string, unknown>): void;
-  emitDecision(event: PermissionDecisionEvent): void;
 }
 
 /**

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

@@ -66,7 +66,12 @@ export function createFailClosedToolCall(
  * The block below this must be reached: the SDK does not catch a throwing
  * handler, so an exception escaping the recording work would leave the command
  * ungated. The request id is minted here rather than borrowed — the throw may
- * have come from anywhere in the pipeline, so no gate's id is available.
+ * have come from anywhere in the pipeline, so no gate's id is available — and
+ * shared by both records, so the terminal broadcast joins the review entry.
+ *
+ * The broadcast carries what the raw event yields and nothing inferred: no
+ * rule won, and the boundary holds no session, so `origin`, `matchedPattern`,
+ * and `agentName` are `null` (#753).
  */
 function recordGateError(
   reporter: DecisionReporter,
@@ -77,15 +82,28 @@ function recordGateError(
   try {
     audit.recordError();
     const reason = errorMessage(error);
+    const requestId = createPermissionRequestId();
+    const toolName = bestEffortToolName(event);
+    const command = bestEffortCommand(event);
     reporter.writeReviewLog("permission_request.blocked", {
-      requestId: createPermissionRequestId(),
-      toolName: bestEffortToolName(event),
-      command: bestEffortCommand(event),
+      requestId,
+      toolName,
+      command,
       resolution: "gate_error",
       error: reason,
       // The boundary decided, by failing closed -- no rule and no human did.
       decidedBy: { kind: "gate_error", reason },
     });
+    reporter.emitDecision({
+      requestId,
+      surface: toolName,
+      value: command ?? toolName,
+      result: "deny",
+      resolution: "gate_error",
+      origin: null,
+      agentName: null,
+      matchedPattern: null,
+    });
   } catch {
     // The block is the guarantee; its bookkeeping is not.
   }

package/src/index.ts

@@ -181,11 +181,19 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
       ),
   };
 
+  // Constructed here rather than beside the gate runner below: the serving
+  // side broadcasts its own decisions, so both readers share one reporter over
+  // this session's event bus.
+  const reporter = new GateDecisionReporter(logger, pi.events);
+
   const requestServer = new ForwardedRequestServer({
     forwardingDir: paths.forwardingDir,
     logger,
     policy: servingPolicy,
     escalator: authorizerSelection,
+    // The forwarded ask's own gate lives in the requesting session, so the
+    // serving side announces the terminal decision on this session's bus.
+    broadcaster: reporter,
     // Records a whole-session grant into the same SessionRules the resolver and
     // gate runner read, so a serving-scope grant governs the parent and future
     // forwarded resolutions.
@@ -275,7 +283,6 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
     },
   );
 
-  const reporter = new GateDecisionReporter(logger, pi.events);
   const gateRunner = new GateRunner(
     resolver,
     sessionRules,

package/src/permission-events.ts

@@ -110,7 +110,9 @@ export type PermissionDecisionResolution =
   | "user_approved_for_session"
   | "user_denied"
   | "auto_approved"
-  | "confirmation_unavailable";
+  | "confirmation_unavailable"
+  /** The gate threw, or an escalation failed, and the request was blocked. */
+  | "gate_error";
 
 /** Payload emitted on `permissions:decision`. */
 export interface PermissionDecisionEvent {
@@ -134,6 +136,16 @@ export interface PermissionDecisionEvent {
   agentName: string | null;
   /** Matched pattern from the winning rule (when available). */
   matchedPattern: string | null;
+  /**
+   * Forwarding context for a decision this session made while serving another
+   * session's forwarded request; absent on an ordinary local decision.
+   *
+   * The same `ForwardedPromptContext` the request's `permissions:ui_prompt`
+   * carried, so a consumer that never saw the prompt can still tell a served
+   * ask from a local one. Requester identity beyond it — the requester's cwd
+   * and principal — stays off the bus.
+   */
+  forwarding?: ForwardedPromptContext | null;
 }
 
 // ── Emit helpers ───────────────────────────────────────────────────────────