@gotgenes/pi-permission-system 25.2.2 → 25.4.0

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-input.ts

@@ -1,4 +1,5 @@
-import { formatSkillAskPrompt } from "#src/permission-prompts";
+import { renderLegacyMessage } from "#src/presentation/legacy-message";
+import { buildSkillAskPayload } from "#src/presentation/skill-ask-payload";
 import type { PermissionCheckResult } from "#src/types";
 import type { GateDescriptor } from "./descriptor";
 import { accessFactsFromValue } from "./helpers";
@@ -15,7 +16,8 @@ export function describeSkillInputGate(
   agentName: string | null,
   preCheck: PermissionCheckResult,
 ): GateDescriptor {
-  const message = formatSkillAskPrompt(skillName, agentName ?? undefined);
+  const payload = buildSkillAskPayload(skillName, agentName);
+  const message = renderLegacyMessage(payload);
   return {
     surface: "skill",
     input: { name: skillName },
@@ -29,6 +31,7 @@ export function describeSkillInputGate(
       source: "skill_input",
       agentName,
       message,
+      payload,
       skillName,
       accessIntent: accessFactsFromValue("skill", skillName),
     },

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

@@ -1,5 +1,6 @@
 import type { PathNormalizer } from "#src/path-normalizer";
-import { formatSkillPathAskPrompt } from "#src/permission-prompts";
+import { renderLegacyMessage } from "#src/presentation/legacy-message";
+import { buildSkillPathAskPayload } from "#src/presentation/skill-ask-payload";
 import type { SkillPromptEntry } from "#src/skill-prompt-sanitizer";
 import { findSkillPathMatch } from "#src/skill-prompt-sanitizer";
 import { toRecord } from "#src/value-guards";
@@ -42,11 +43,8 @@ export function describeSkillReadGate(
     return null;
   }
 
-  const skillReadMessage = formatSkillPathAskPrompt(
-    matchedSkill,
-    path,
-    tcc.agentName ?? undefined,
-  );
+  const payload = buildSkillPathAskPayload(matchedSkill, path, tcc.agentName);
+  const skillReadMessage = renderLegacyMessage(payload);
 
   return {
     surface: "skill",
@@ -61,6 +59,7 @@ export function describeSkillReadGate(
       source: "skill_read",
       agentName: tcc.agentName,
       message: skillReadMessage,
+      payload,
       toolCallId: tcc.toolCallId,
       toolName: tcc.toolName,
       skillName: matchedSkill.name,
@@ -69,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/gates/tool.ts

@@ -6,7 +6,8 @@ import {
   type ShellInvocation,
 } from "#src/access-intent/tool-kind";
 import { suggestSessionPattern } from "#src/pattern-suggest";
-import { formatAskPrompt } from "#src/permission-prompts";
+import { renderLegacyMessage } from "#src/presentation/legacy-message";
+import { buildToolAskPayload } from "#src/presentation/tool-ask-payload";
 import { SessionApproval } from "#src/session-approval";
 import type { ToolPreviewFormatter } from "#src/tool-preview-formatter";
 import type { PermissionCheckResult } from "#src/types";
@@ -72,12 +73,15 @@ export function describeToolGate(
     deriveSuggestionValue(gateSurface, check, accessPath),
   );
 
-  const askMessage = formatAskPrompt(
+  const payload = buildToolAskPayload({
     check,
-    tcc.agentName ?? undefined,
-    tcc.input,
+    agentName: tcc.agentName,
+    surface: gateSurface,
+    invokedToolName: tcc.toolName,
+    input: tcc.input,
     formatter,
-  );
+  });
+  const askMessage = renderLegacyMessage(payload);
 
   const decisionValue = deriveDecisionValue(
     gateSurface,
@@ -108,6 +112,7 @@ export function describeToolGate(
       source: "tool_call",
       agentName: tcc.agentName,
       message: askMessage,
+      payload,
       toolCallId: tcc.toolCallId,
       toolName: tcc.toolName,
       sessionLabel: suggestion.label,

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/index.ts

@@ -38,6 +38,7 @@ import { PermissionManager } from "./permission-manager";
 import { PermissionResolver } from "./permission-resolver";
 import { PermissionSession } from "./permission-session";
 import { LocalPermissionsService } from "./permissions-service";
+import { resolveRenderBudget } from "./presentation/dialog-renderer";
 import { PermissionServiceLifecycle } from "./service-lifecycle";
 import { PermissionSessionLogger } from "./session-logger";
 import { SessionRules } from "./session-rules";
@@ -115,6 +116,7 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
     events: pi.events,
     getPromptPreferences: () => ({
       doublePressToConfirm: configStore.current().doublePressToConfirm,
+      budget: resolveRenderBudget(configStore.current()),
     }),
     requestPermissionDecision,
     forwardingDir: paths.forwardingDir,

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-prompts.ts

@@ -1,13 +1,8 @@
-import { classifyToolKind, isMcpCheck } from "./access-intent/tool-kind";
-import { matchQualifier } from "./denial-messages";
-import type { SkillPromptEntry } from "./skill-prompt-sanitizer";
-import type { ToolPreviewFormatter } from "./tool-preview-formatter";
-import type { PermissionCheckResult } from "./types";
-import { getNonEmptyString, toRecord } from "./value-guards";
+import { classifyToolKind } from "./access-intent/tool-kind";
 
-// NOTE: formatDenyReason, formatUserDeniedReason, and
-// formatPermissionHardStopHint have been moved to denial-messages.ts.
-// This module retains only pre-check messages and user-facing ask prompts.
+// NOTE: the ask prompts are now payload builders under src/presentation/;
+// denial text lives in denial-messages.ts. This module retains only the
+// pre-check reasons, which are agent-facing rather than user-facing.
 
 export function formatMissingToolNameReason(): string {
   return "Tool call was blocked because no tool name was provided. Use a registered tool name from pi.getAllTools().";
@@ -29,66 +24,3 @@ export function formatUnknownToolReason(
 
   return `Tool '${toolName}' is not registered in this runtime and was blocked before permission checks.${mcpHint} Registered tools: ${availableList}.`;
 }
-
-export function formatAskPrompt(
-  result: PermissionCheckResult,
-  agentName?: string,
-  input?: unknown,
-  formatter?: ToolPreviewFormatter,
-): string {
-  const subject = agentName ? `Agent '${agentName}'` : "Current agent";
-
-  if (classifyToolKind(result.toolName) === "bash") {
-    const subCommand = result.command ?? "";
-    const qualifier = matchQualifier(
-      result.matchedPattern,
-      result.commandContext,
-    );
-    const qualifierInfo = qualifier ? ` ${qualifier}` : "";
-    const fullCommand = getNonEmptyString(toRecord(input).command);
-    const fullCommandInfo =
-      fullCommand && fullCommand !== subCommand
-        ? ` (full command: '${fullCommand}')`
-        : "";
-    return `${subject} requested bash command '${subCommand}'${qualifierInfo}${fullCommandInfo}. Allow this command?`;
-  }
-
-  if (isMcpCheck(result) && result.target) {
-    const patternInfo = result.matchedPattern
-      ? ` (matched '${result.matchedPattern}')`
-      : "";
-    const mcpPreview = formatter
-      ? formatter.formatToolInputForPrompt("mcp", input)
-      : "";
-    const previewSuffix = mcpPreview ? ` ${mcpPreview}` : "";
-    return `${subject} requested MCP target '${result.target}'${patternInfo}${previewSuffix}. Allow this call?`;
-  }
-
-  const patternInfo = result.matchedPattern
-    ? ` (matched '${result.matchedPattern}')`
-    : "";
-  const inputPreview = formatter
-    ? formatter.formatToolInputForPrompt(result.toolName, input)
-    : "";
-  const inputSuffix = inputPreview ? ` ${inputPreview}` : "";
-  return `${subject} requested tool '${result.toolName}'${patternInfo}${inputSuffix}. Allow this call?`;
-}
-
-export function formatSkillAskPrompt(
-  skillName: string,
-  agentName?: string,
-): string {
-  const subject = agentName ? `Agent '${agentName}'` : "Current agent";
-  return `${subject} requested skill '${skillName}'. Allow loading this skill?`;
-}
-
-export function formatSkillPathAskPrompt(
-  skill: SkillPromptEntry,
-  readPath: string,
-  agentName?: string,
-): string {
-  const subject = agentName ? `Agent '${agentName}'` : "Current agent";
-  return `${subject} requested access to skill '${skill.name}' via '${readPath}'. Allow this read?`;
-}
-
-// formatSkillPathDenyReason has been moved to denial-messages.ts.

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()}`;
+}