@gotgenes/pi-permission-system 25.3.0 → 25.4.0

package/CHANGELOG.md

@@ -5,6 +5,21 @@ 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).
 
+## [25.4.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v25.3.0...pi-permission-system-v25.4.0) (2026-08-15)
+
+
+### Features
+
+* **pi-permission-system:** adopt the requester's request id as the forwarded request id ([3f8d3fd](https://github.com/gotgenes/pi-packages/commit/3f8d3fd69940211c6a92b99f8eae0396936afedf)), closes [#752](https://github.com/gotgenes/pi-packages/issues/752)
+* **pi-permission-system:** carry the request id on permissions:decision ([95c001c](https://github.com/gotgenes/pi-packages/commit/95c001cf6b35c68991143826d8621b1e94fc0b32)), closes [#752](https://github.com/gotgenes/pi-packages/issues/752)
+* **pi-permission-system:** give the gate-error review entry a request id ([172bc68](https://github.com/gotgenes/pi-packages/commit/172bc689ea0f18c88672a22c0b5e84c0f3576fd1)), closes [#752](https://github.com/gotgenes/pi-packages/issues/752)
+* **pi-permission-system:** mint a permission request id at request creation ([336842d](https://github.com/gotgenes/pi-packages/commit/336842de6c34e96bd90ed411eaca9649c4b9fac2)), closes [#752](https://github.com/gotgenes/pi-packages/issues/752)
+
+
+### Documentation
+
+* **pi-permission-system:** record the minted request id in the API and architecture docs ([84f5856](https://github.com/gotgenes/pi-packages/commit/84f5856868a548c9454ef3e23ca75c608ce3f308)), closes [#752](https://github.com/gotgenes/pi-packages/issues/752)
+
 ## [25.3.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v25.2.2...pi-permission-system-v25.3.0) (2026-08-15)
 
 

package/dist/public.d.ts

@@ -207,6 +207,12 @@ interface PermissionUiPromptEvent {
 type PermissionDecisionResolution = "policy_allow" | "policy_deny" | "session_approved" | "infrastructure_auto_allowed" | "user_approved" | "user_approved_for_session" | "user_denied" | "auto_approved" | "confirmation_unavailable";
 /** Payload emitted on `permissions:decision`. */
 interface PermissionDecisionEvent {
+    /**
+     * Identifies the permission request this decision resolves, minted when the
+     * request was created. Distinct from the host's tool-call id: one tool call
+     * runs several gates and so raises several requests.
+     */
+    requestId: string;
     /** Permission surface: "bash", "read", "mcp", "skill", "external_directory", etc. */
     surface: string;
     /** The value that was evaluated (command, tool name, skill name, path). */

package/docs/cross-extension-api.md

@@ -336,15 +336,15 @@ pi.events.on("permissions:ui_prompt", (raw) => {
 
 ### Payload Fields
 
-| Field        | Type                             | Description                                                            |
-| ------------ | -------------------------------- | ---------------------------------------------------------------------- |
-| `requestId`  | `string`                         | Unique ID for the permission request being prompted                    |
-| `source`     | `PermissionUiPromptSource`       | Prompt origin: `"tool_call"`, `"skill_input"`, or `"skill_read"`       |
-| `surface`    | `string \| null`                 | Normalized display surface (e.g. `"bash"`, `"skill"`), when known      |
-| `value`      | `string \| null`                 | Normalized display value (command, path, skill name, etc.), when known |
-| `agentName`  | `string \| null`                 | Active/requesting agent name, when known                               |
-| `message`    | `string`                         | Message displayed in the permission prompt                             |
-| `forwarding` | `ForwardedPromptContext \| null` | Forwarding context, or `null` for a direct prompt                      |
+| Field        | Type                             | Description                                                             |
+| ------------ | -------------------------------- | ----------------------------------------------------------------------- |
+| `requestId`  | `string`                         | Id of the permission request being prompted, minted when it was created |
+| `source`     | `PermissionUiPromptSource`       | Prompt origin: `"tool_call"`, `"skill_input"`, or `"skill_read"`        |
+| `surface`    | `string \| null`                 | Normalized display surface (e.g. `"bash"`, `"skill"`), when known       |
+| `value`      | `string \| null`                 | Normalized display value (command, path, skill name, etc.), when known  |
+| `agentName`  | `string \| null`                 | Active/requesting agent name, when known                                |
+| `message`    | `string`                         | Message displayed in the permission prompt                              |
+| `forwarding` | `ForwardedPromptContext \| null` | Forwarding context, or `null` for a direct prompt                       |
 
 Forwarding is orthogonal to origin: a forwarded subagent prompt keeps its original `source` and is identified by a non-null `forwarding` field, not by a dedicated source value.
 
@@ -367,6 +367,10 @@ 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.
 
+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.
+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.
+
 ```typescript
 pi.events.on("permissions:decision", (raw) => {
   const event = raw as import("@gotgenes/pi-permission-system").PermissionDecisionEvent;
@@ -379,6 +383,7 @@ pi.events.on("permissions:decision", (raw) => {
 
 | 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                                                                             |

package/package.json

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

package/src/authority/approval-escalator.ts

@@ -34,6 +34,7 @@ import {
 } from "#src/authority/permission-forwarding";
 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 { DebugReviewLogger } from "#src/session-logger";
 import { toRecord } from "#src/value-guards";
@@ -75,6 +76,12 @@ function getContextSystemPrompt(ctx: ForwarderContext): string | undefined {
  * relayed value instead of three positional optionals.
  */
 interface ForwardedRequestFacts {
+  /**
+   * The requester's own permission request id, adopted as the forwarded
+   * request's id so one id runs from the child's gate to the serving node's
+   * decision instead of a third being minted here.
+   */
+  requestId: string;
   message: string;
   display?: ForwardedPromptDisplay;
   sessionApproval?: ForwardedSessionApproval;
@@ -111,6 +118,23 @@ function abandon(denialReason: string): PermissionPromptDecision {
   };
 }
 
+/** Ids this node is willing to use as a request/response filename. */
+const FILENAME_SAFE_REQUEST_ID = /^[A-Za-z0-9._-]+$/;
+
+/**
+ * The id to write on the forwarded request: the requester's own, or a fresh
+ * mint when that id could not safely name a file.
+ *
+ * At a relay hop the adopted id came from a request file on disk, which the
+ * tolerant reader validates only as a string — so this is the boundary that
+ * keeps an inbound id from choosing an outbound path.
+ */
+function forwardableRequestId(requesterRequestId: string): string {
+  return FILENAME_SAFE_REQUEST_ID.test(requesterRequestId)
+    ? requesterRequestId
+    : createPermissionRequestId();
+}
+
 /**
  * Authorizer for a subagent session: escalate the ask up the tree to the
  * parent's authority.
@@ -146,6 +170,7 @@ export class ParentAuthorizer implements TerminalAuthorizer {
   ): Promise<PermissionPromptDecision> {
     const uiPrompt = buildUiPrompt(details);
     return this.waitForForwardedApproval(this.ctx, {
+      requestId: details.requestId,
       message: details.message,
       display: {
         source: uiPrompt.source,
@@ -250,7 +275,7 @@ export class ParentAuthorizer implements TerminalAuthorizer {
     requesterSessionId: string,
     targetSessionId: string,
   ): ForwardedPermissionRequest {
-    const requestId = `${Date.now()}-${Math.random().toString(36).slice(2, 10)}-${process.pid}`;
+    const requestId = forwardableRequestId(facts.requestId);
     const requesterAgentName =
       getActiveAgentName(ctx) ??
       getActiveAgentNameFromSystemPrompt(getContextSystemPrompt(ctx)) ??

package/src/handlers/gates/descriptor.ts

@@ -51,6 +51,15 @@ export interface GateDescriptor {
   preCheck?: PermissionCheckResult;
 }
 
+/**
+ * A decision event's facts, before the runner stamps the request id it minted.
+ *
+ * A gate knows what was decided but not which request it was deciding — the id
+ * is minted in `GateRunner.run`. Producing this type rather than the full event
+ * is what routes every emit through the runner's single stamping site.
+ */
+export type DecisionEventFacts = Omit<PermissionDecisionEvent, "requestId">;
+
 /**
  * Early allow result — gate has determined the action without needing the runner.
  *
@@ -62,7 +71,7 @@ export interface GateBypass {
   /** Optional review log entry to emit. */
   log?: { event: string; details: Record<string, unknown> };
   /** Optional decision event to emit. */
-  decision?: PermissionDecisionEvent;
+  decision?: DecisionEventFacts;
 }
 
 /** Union of possible gate function return values. */

package/src/handlers/gates/helpers.ts

@@ -1,11 +1,9 @@
 import type { AccessPath } from "#src/access-intent/access-path";
 import { classifyToolKind } from "#src/access-intent/tool-kind";
 import type { ForwardedAccessFacts } from "#src/authority/permission-forwarding";
-import type {
-  PermissionDecisionEvent,
-  PermissionDecisionResolution,
-} from "#src/permission-events";
+import type { PermissionDecisionResolution } from "#src/permission-events";
 import type { PermissionCheckResult } from "#src/types";
+import type { DecisionEventFacts } from "./descriptor";
 
 /**
  * Build the child-fixed access facts for a path-shaped gate from its
@@ -62,11 +60,12 @@ export function deriveDecisionValue(
 }
 
 /**
- * Build a `PermissionDecisionEvent` from the gate's inputs.
+ * Build a decision event's facts from the gate's inputs.
  *
  * Centralises the `origin / agentName / matchedPattern ?? null` normalization
  * that is otherwise duplicated across the session-hit path and the gate-result
- * path in `runGateCheck`.
+ * path in `runGateCheck`. The request id is stamped by the runner, which is
+ * where it was minted.
  */
 export function buildDecisionEvent(
   decision: { surface: string; value: string },
@@ -74,7 +73,7 @@ export function buildDecisionEvent(
   agentName: string | null,
   result: "allow" | "deny",
   resolution: PermissionDecisionResolution,
-): PermissionDecisionEvent {
+): DecisionEventFacts {
   return {
     surface: decision.surface,
     value: decision.value,

package/src/handlers/gates/runner.ts

@@ -7,10 +7,15 @@ import {
   formatUserDeniedReason,
 } from "#src/denial-messages";
 import { applyPermissionGate } from "#src/permission-gate";
+import { createPermissionRequestId } from "#src/permission-request-id";
 import type { ScopedPermissionResolver } from "#src/permission-resolver";
 import type { SessionApprovalRecorder } from "#src/session-approval-recorder";
 import type { PermissionCheckResult } from "#src/types";
-import type { GateDescriptor, GateResult } from "./descriptor";
+import type {
+  DecisionEventFacts,
+  GateDescriptor,
+  GateResult,
+} from "./descriptor";
 import { isGateBypass } from "./descriptor";
 import {
   buildDecisionEvent,
@@ -46,33 +51,44 @@ export class GateRunner {
   /**
    * Execute a gate: null → allow; bypass → log/emit side effects then allow;
    * descriptor → full check→log→emit→approve cycle.
+   *
+   * The request id is minted here, before the branch, so a request that never
+   * prompts is identified exactly as one that does.
    */
-  async run(
-    gate: GateResult,
-    agentName: string | null,
-    toolCallId: string,
-  ): Promise<GateOutcome> {
+  async run(gate: GateResult, agentName: string | null): Promise<GateOutcome> {
     if (!gate) {
       return { action: "allow" };
     }
+    const requestId = createPermissionRequestId();
     if (isGateBypass(gate)) {
       if (gate.log) {
-        this.reporter.writeReviewLog(gate.log.event, gate.log.details);
+        this.reporter.writeReviewLog(gate.log.event, {
+          ...gate.log.details,
+          requestId,
+        });
       }
       if (gate.decision) {
-        this.reporter.emitDecision(gate.decision);
+        this.emitDecision(requestId, gate.decision);
       }
       return { action: "allow" };
     }
-    return this.runDescriptor(gate, agentName, toolCallId);
+    return this.runDescriptor(gate, agentName, requestId);
   }
 
   // ── Private helpers ──────────────────────────────────────────────────────
 
+  /**
+   * The one place a decision event acquires its request id, so no emit path
+   * can be added that forgets it.
+   */
+  private emitDecision(requestId: string, facts: DecisionEventFacts): void {
+    this.reporter.emitDecision({ requestId, ...facts });
+  }
+
   private async runDescriptor(
     descriptor: GateDescriptor,
     agentName: string | null,
-    toolCallId: string,
+    requestId: string,
   ): Promise<GateOutcome> {
     // 1. Resolve permission state — pre-check, pre-resolved, or via resolver
     let check: PermissionCheckResult;
@@ -94,15 +110,19 @@ export class GateRunner {
       });
     }
 
+    // The fields every review-log write for this gate shares, whatever the
+    // resolution — built once so a field added here reaches all of them.
+    const logContext = { ...descriptor.logContext, agentName, requestId };
+
     // 2. Session-hit fast path
     if (check.source === "session") {
       this.reporter.writeReviewLog("permission_request.session_approved", {
-        ...descriptor.logContext,
-        agentName,
+        ...logContext,
         resolution: "session_approved",
         sessionApprovalPattern: check.matchedPattern,
       });
-      this.reporter.emitDecision(
+      this.emitDecision(
+        requestId,
         buildDecisionEvent(
           descriptor.decision,
           check,
@@ -121,11 +141,11 @@ export class GateRunner {
     const yoloGrant = resolveYoloGrant(check, this.isYoloEnabled());
     if (yoloGrant) {
       this.reporter.writeReviewLog("permission_request.auto_approved", {
-        ...descriptor.logContext,
-        agentName,
+        ...logContext,
         resolution: "auto_approved",
       });
-      this.reporter.emitDecision(
+      this.emitDecision(
+        requestId,
         buildDecisionEvent(
           descriptor.decision,
           yoloGrant,
@@ -159,7 +179,7 @@ export class GateRunner {
       sessionApproval: descriptor.sessionApproval?.toGateApproval(),
       promptForApproval: async () => {
         const decision = await this.prompter.escalate({
-          requestId: toolCallId,
+          requestId,
           ...descriptor.promptDetails,
           ...(descriptor.sessionApproval
             ? { sessionApproval: descriptor.sessionApproval.toForwardedData() }
@@ -171,7 +191,7 @@ export class GateRunner {
       },
       writeLog: (event, details) =>
         this.reporter.writeReviewLog(event, details),
-      logContext: { ...descriptor.logContext, agentName },
+      logContext,
       messages,
     });
 
@@ -180,7 +200,8 @@ export class GateRunner {
       gateResult.action === "allow" && gateResult.sessionApproval !== undefined;
 
     // 5. Emit decision event
-    this.reporter.emitDecision(
+    this.emitDecision(
+      requestId,
       buildDecisionEvent(
         descriptor.decision,
         check,

package/src/handlers/gates/skill-input-gate-pipeline.ts

@@ -40,7 +40,7 @@ export interface GateNotifier {
 
 /**
  * Owns the skill-input gate assembly: raw permission pre-check, deny notify,
- * `describeSkillInputGate` descriptor, request-id mint, and `runner.run(...)`.
+ * `describeSkillInputGate` descriptor, and `runner.run(...)`.
  *
  * Constructed once in the composition root and injected into
  * `PermissionGateHandler`, mirroring `ToolCallGatePipeline` for the `input`
@@ -70,23 +70,12 @@ export class SkillInputGatePipeline {
     return runner.run(
       describeSkillInputGate(skillName, agentName, check),
       agentName,
-      createSkillInputRequestId(),
     );
   }
 }
 
 // ── Helpers ───────────────────────────────────────────────────────────────────
 
-/**
- * Mint a unique id for a skill-input permission request.
- *
- * Format is `skill-input-<timestamp>-<random>-<pid>`, matching the
- * `createPermissionRequestId("skill-input")` pattern it replaces (#330).
- */
-export function createSkillInputRequestId(): string {
-  return `skill-input-${Date.now()}-${Math.random().toString(36).slice(2, 10)}-${process.pid}`;
-}
-
 /**
  * Format the deny warning shown in the UI when a skill is blocked.
  *

package/src/handlers/gates/skill-read.ts

@@ -68,6 +68,7 @@ export function describeSkillReadGate(
     },
     logContext: {
       source: "skill_read",
+      toolCallId: tcc.toolCallId,
       skillName: matchedSkill.name,
       agentName: tcc.agentName,
       path,

package/src/handlers/gates/tool-call-gate-pipeline.ts

@@ -137,11 +137,7 @@ export class ToolCallGatePipeline {
     ];
 
     for (const produce of gateProducers) {
-      const outcome = await runner.run(
-        await produce(),
-        tcc.agentName,
-        tcc.toolCallId,
-      );
+      const outcome = await runner.run(await produce(), tcc.agentName);
       if (outcome.action === "block") {
         return outcome;
       }

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

@@ -1,6 +1,7 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { DecisionRecorder } from "#src/decision-audit";
 import type { DecisionReporter } from "#src/decision-reporter";
+import { createPermissionRequestId } from "#src/permission-request-id";
 import { toRecord } from "#src/value-guards";
 import type { GateOutcome } from "./gates/types";
 
@@ -53,18 +54,40 @@ export function createFailClosedToolCall(
         ? { block: true, reason: outcome.reason }
         : {};
     } catch (error) {
-      audit.recordError();
-      reporter.writeReviewLog("permission_request.blocked", {
-        toolName: bestEffortToolName(event),
-        command: bestEffortCommand(event),
-        resolution: "gate_error",
-        error: errorMessage(error),
-      });
+      recordGateError(reporter, audit, event, error);
       return { block: true, reason: formatGateErrorReason(error) };
     }
   };
 }
 
+/**
+ * Record a gate error without ever throwing.
+ *
+ * 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.
+ */
+function recordGateError(
+  reporter: DecisionReporter,
+  audit: DecisionRecorder,
+  event: unknown,
+  error: unknown,
+): void {
+  try {
+    audit.recordError();
+    reporter.writeReviewLog("permission_request.blocked", {
+      requestId: createPermissionRequestId(),
+      toolName: bestEffortToolName(event),
+      command: bestEffortCommand(event),
+      resolution: "gate_error",
+      error: errorMessage(error),
+    });
+  } catch {
+    // The block is the guarantee; its bookkeeping is not.
+  }
+}
+
 // ── Defensive event readers (never throw) ──────────────────────────────────
 
 /** Best-effort tool name from a raw event; never throws. */

package/src/permission-events.ts

@@ -101,6 +101,12 @@ export type PermissionDecisionResolution =
 
 /** Payload emitted on `permissions:decision`. */
 export interface PermissionDecisionEvent {
+  /**
+   * Identifies the permission request this decision resolves, minted when the
+   * request was created. Distinct from the host's tool-call id: one tool call
+   * runs several gates and so raises several requests.
+   */
+  requestId: string;
   /** Permission surface: "bash", "read", "mcp", "skill", "external_directory", etc. */
   surface: string;
   /** The value that was evaluated (command, tool name, skill name, path). */

package/src/permission-request-id.ts

@@ -0,0 +1,17 @@
+import { randomUUID } from "node:crypto";
+
+/**
+ * Mint the identifier for one permission request, at the moment the request is
+ * created rather than at the moment it prompts.
+ *
+ * Distinct from the host's `toolCallId`, which keeps flowing alongside it as
+ * the join back to the Pi transcript: a single tool call runs several gates and
+ * therefore raises several permission requests, so the SDK's id cannot identify
+ * one of them.
+ *
+ * The `perm-` prefix keeps the id self-identifying in a review log that also
+ * carries SDK tool-call ids.
+ */
+export function createPermissionRequestId(): string {
+  return `perm-${randomUUID()}`;
+}