@gotgenes/pi-permission-system 4.2.0 → 4.4.0

package/CHANGELOG.md

@@ -5,6 +5,42 @@ 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).
 
+## [4.4.0](https://github.com/gotgenes/pi-permission-system/compare/v4.3.0...v4.4.0) (2026-05-05)
+
+
+### Features
+
+* wire PermissionPrompter and remove runtime promptPermission ([#80](https://github.com/gotgenes/pi-permission-system/issues/80)) ([8e0980a](https://github.com/gotgenes/pi-permission-system/commit/8e0980a207f9f665ad2af3ad635d73e28d313c91))
+
+
+### Documentation
+
+* add permission-prompter architecture note ([#80](https://github.com/gotgenes/pi-permission-system/issues/80)) ([6cc1b60](https://github.com/gotgenes/pi-permission-system/commit/6cc1b6089a332f262919d20ad27d5ca7a69b0b6d))
+* add permission-prompter to target architecture module map ([#80](https://github.com/gotgenes/pi-permission-system/issues/80)) ([c5cf101](https://github.com/gotgenes/pi-permission-system/commit/c5cf101af827dc108c66c5dffff94e05d4234e4c))
+* add permission-prompter to v3 architecture module map ([#80](https://github.com/gotgenes/pi-permission-system/issues/80)) ([94be5b5](https://github.com/gotgenes/pi-permission-system/commit/94be5b58b9018b1918102089bb2fff8401d8bad5))
+* plan extract PermissionPrompter class ([#80](https://github.com/gotgenes/pi-permission-system/issues/80)) ([50fcf34](https://github.com/gotgenes/pi-permission-system/commit/50fcf3400ed8574b036cacd2afc1b9e2161d41c6))
+* remove interim permission-prompter from target architecture map ([#80](https://github.com/gotgenes/pi-permission-system/issues/80)) ([f300f08](https://github.com/gotgenes/pi-permission-system/commit/f300f086b42d9d52ff0668b63a191addebe3140e))
+* **retro:** add retro notes for issue [#51](https://github.com/gotgenes/pi-permission-system/issues/51) ([79a564d](https://github.com/gotgenes/pi-permission-system/commit/79a564d24977da7cffa3d9d65391a75dd0d7e99c))
+* update target architecture for completed work and new issues ([#80](https://github.com/gotgenes/pi-permission-system/issues/80)) ([e661345](https://github.com/gotgenes/pi-permission-system/commit/e661345c8a699e702cbaa9adb7d61c80a25010d2))
+
+## [4.3.0](https://github.com/gotgenes/pi-permission-system/compare/v4.2.0...v4.3.0) (2026-05-04)
+
+
+### Features
+
+* add pattern-suggest module for session approval patterns ([0752604](https://github.com/gotgenes/pi-permission-system/commit/0752604ea63a3bcbf4a8d15f6a9760dde4de9b9d))
+* dynamic session approval label in permission dialog ([4737f0d](https://github.com/gotgenes/pi-permission-system/commit/4737f0dbe69b579dca057a149788408cb63e52ec))
+* extend checkPermission session evaluation to all surfaces ([ffc6731](https://github.com/gotgenes/pi-permission-system/commit/ffc67312e09fb0df0c4dbcb572a625b92c3cd018))
+* extend permission gate with sessionApproval pass-through ([a77bad7](https://github.com/gotgenes/pi-permission-system/commit/a77bad7d9193a5500678bf18ac7854da0be2e79f))
+* generalize session approvals to all permission surfaces ([#51](https://github.com/gotgenes/pi-permission-system/issues/51)) ([2fcc2e3](https://github.com/gotgenes/pi-permission-system/commit/2fcc2e37db4f704702fd3d4c64a1388ab417c407))
+
+
+### Documentation
+
+* document generalized session approvals ([#51](https://github.com/gotgenes/pi-permission-system/issues/51)) ([233666e](https://github.com/gotgenes/pi-permission-system/commit/233666e496dd81165dec44ef4242bca090750edd))
+* plan generalized session approvals for all surfaces ([#51](https://github.com/gotgenes/pi-permission-system/issues/51)) ([3b40cf9](https://github.com/gotgenes/pi-permission-system/commit/3b40cf954c9f598c7c3c199a4137e897c4fce4b2))
+* **retro:** add retro notes for issue [#74](https://github.com/gotgenes/pi-permission-system/issues/74) ([0eb2ea0](https://github.com/gotgenes/pi-permission-system/commit/0eb2ea001669cba1436d564af9e28ca0ff26c77e))
+
 ## [4.2.0](https://github.com/gotgenes/pi-permission-system/compare/v4.1.1...v4.2.0) (2026-05-04)
 
 

package/README.md

@@ -437,20 +437,28 @@ Current agent requested tool 'edit' for '.gitignore' (1 replacement: edit #1 rep
 
 ### Session-Scoped Approvals
 
-When `external_directory` resolves to `ask`, the permission dialog offers four options:
+When any permission resolves to `ask`, the permission dialog offers four options:
 
 ```text
-Yes | Yes, for this session | No | No, provide reason
+Yes | Yes, allow "<pattern>" for this session | No | No, provide reason
 ```
 
-Selecting **Yes, for this session** approves the current request and caches the directory prefix so that subsequent accesses under the same directory skip the prompt for the remainder of the session.
-For example, approving access to `~/other-project/src/foo.ts` covers all paths under `~/other-project/src/` until the session ends.
+Selecting **Yes, allow "\<pattern\>" for this session** approves the current request and records the suggested wildcard pattern as a session rule.
+Subsequent requests that match the pattern skip the prompt for the remainder of the session.
 
-Session approvals are ephemeral — they are never persisted to disk and are cleared on `session_shutdown`.
-The review log records these decisions with `resolution: "session_approved"` so they remain auditable.
+The suggested pattern is surface-specific:
+
+|Surface|Example request|Suggested session pattern|
+|---|---|---|
+|bash|`git status --short`|`git *`|
+|mcp (qualified)|`exa:search`|`exa:*`|
+|mcp (munged)|`exa_search`|`exa_*`|
+|skill|`librarian`|`librarian`|
+|tool (read, write, …)|`read`|`*`|
+|external_directory|`/other/project/src/foo.ts`|`/other/project/src/*`|
 
-This is currently scoped to the `external_directory` surface only.
-Other permission surfaces (tools, bash patterns, MCP, skills) always use the standard one-time approval flow.
+Session approvals are ephemeral — they are never persisted to disk and are cleared on `session_shutdown`.
+The review log records these decisions: `resolution: "approved_for_session"` when the user approves, and `resolution: "session_approved"` when a later request is matched by an existing session rule.
 
 ### Subagent Permission Forwarding
 
@@ -496,7 +504,8 @@ This makes it easy to verify which files the extension actually loaded:
 index.ts                    → Root Pi entrypoint shim
 src/
 ├── index.ts                → Extension bootstrap, permission checks, readable prompts, review logging, reload handling, and subagent forwarding
-├── session-rules.ts          → Ephemeral session-scoped approval rules (Ruleset-based, external-directory access)
+├── pattern-suggest.ts        → Per-surface session approval pattern suggestions
+├── session-rules.ts          → Ephemeral session-scoped approval rules (Ruleset-based, wildcard patterns across all surfaces)
 ├── config-loader.ts        → Unified config loader, merger, and legacy-path detection
 ├── config-paths.ts         → Path derivation for global, project, and legacy config locations
 ├── config-reporter.ts      → Resolved config path reporting for diagnostic logs

package/package.json

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

package/src/forwarded-permissions/polling.ts

@@ -7,7 +7,10 @@ import {
   getActiveAgentNameFromSystemPrompt,
 } from "../active-agent";
 import { toRecord } from "../common";
-import type { PermissionPromptDecision } from "../permission-dialog";
+import type {
+  PermissionPromptDecision,
+  RequestPermissionOptions,
+} from "../permission-dialog";
 import {
   type ForwardedPermissionRequest,
   type ForwardedPermissionResponse,
@@ -42,6 +45,7 @@ export interface PermissionForwardingDeps {
     ui: ExtensionContext["ui"],
     title: string,
     message: string,
+    options?: RequestPermissionOptions,
   ) => Promise<PermissionPromptDecision>;
   shouldAutoApprove: () => boolean;
 }
@@ -339,12 +343,14 @@ export async function confirmPermission(
   ctx: ExtensionContext,
   message: string,
   deps: PermissionForwardingDeps,
+  options?: RequestPermissionOptions,
 ): Promise<PermissionPromptDecision> {
   if (ctx.hasUI) {
     return deps.requestPermissionDecisionFromUi(
       ctx.ui,
       "Permission Required",
       message,
+      options,
     );
   }
 

package/src/handlers/tool-call.ts

@@ -18,6 +18,7 @@ import {
   normalizePathForComparison,
   PATH_BEARING_TOOLS,
 } from "../external-directory";
+import { suggestSessionPattern } from "../pattern-suggest";
 import type { PermissionPromptDecision } from "../permission-dialog";
 import { applyPermissionGate } from "../permission-gate";
 import {
@@ -359,12 +360,35 @@ export async function handleToolCall(
     agentName ?? undefined,
     deps.runtime.sessionRules.getRuleset(),
   );
+
+  // Session-hit: already approved by a session rule — skip the gate entirely.
+  if (check.source === "session") {
+    deps.runtime.writeReviewLog("permission_request.session_approved", {
+      source: "tool_call",
+      toolCallId: (event as { toolCallId: string }).toolCallId,
+      toolName,
+      agentName,
+      resolution: "session_approved",
+      sessionApprovalPattern: check.matchedPattern,
+    });
+    return {};
+  }
+
   const permissionLogContext = getPermissionLogContext(
     check,
     input,
     PATH_BEARING_TOOLS,
   );
 
+  // Compute session approval suggestion for the "for this session" option.
+  const suggestionValue =
+    toolName === "bash"
+      ? (check.command ?? "")
+      : toolName === "mcp"
+        ? (check.target ?? "mcp")
+        : "*";
+  const suggestion = suggestSessionPattern(toolName, suggestionValue);
+
   const toolUnavailableReason =
     toolName === "bash" && isToolCallEventType("bash", event as ToolCallEvent)
       ? `Running bash command '${(event as ToolCallEvent & { input: { command: string } }).input.command}' requires approval, but no interactive UI is available.`
@@ -376,6 +400,10 @@ export async function handleToolCall(
   const toolGate = await applyPermissionGate({
     state: check.state,
     canConfirm: deps.canRequestPermissionConfirmation(ctx),
+    sessionApproval: {
+      surface: suggestion.surface,
+      pattern: suggestion.pattern,
+    },
     promptForApproval: () =>
       deps.promptPermission(ctx, {
         requestId: (event as { toolCallId: string }).toolCallId,
@@ -384,6 +412,7 @@ export async function handleToolCall(
         message: toolAskMessage,
         toolCallId: (event as { toolCallId: string }).toolCallId,
         toolName,
+        sessionLabel: suggestion.label,
         ...permissionLogContext,
       }),
     writeLog: deps.runtime.writeReviewLog,
@@ -407,5 +436,12 @@ export async function handleToolCall(
     return { block: true, reason: toolGate.reason };
   }
 
+  if (toolGate.sessionApproval) {
+    deps.runtime.sessionRules.approve(
+      toolGate.sessionApproval.surface,
+      toolGate.sessionApproval.pattern,
+    );
+  }
+
   return {};
 }

package/src/handlers/types.ts

@@ -19,6 +19,8 @@ export interface PromptPermissionDetails {
   command?: string;
   target?: string;
   toolInputPreview?: string;
+  /** Override label for the "for this session" dialog option. */
+  sessionLabel?: string;
 }
 
 /**

package/src/index.ts

@@ -12,11 +12,11 @@ import {
   handleToolCall,
 } from "./handlers";
 import { requestPermissionDecisionFromUi } from "./permission-dialog";
+import { PermissionPrompter } from "./permission-prompter";
 import {
   createExtensionRuntime,
   createPermissionManagerForCwd,
   logResolvedConfigPaths,
-  promptPermission,
   refreshExtensionConfig,
   resolveAgentName,
   saveExtensionConfig,
@@ -32,6 +32,14 @@ import {
 export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
   const runtime = createExtensionRuntime();
 
+  const prompter = new PermissionPrompter({
+    getConfig: () => runtime.config,
+    writeReviewLog: runtime.writeReviewLog.bind(runtime),
+    subagentSessionsDir: runtime.subagentSessionsDir,
+    forwardingDir: runtime.forwardingDir,
+    requestPermissionDecisionFromUi,
+  });
+
   const forwardingDeps: PermissionForwardingDeps = {
     forwardingDir: runtime.forwardingDir,
     subagentSessionsDir: runtime.subagentSessionsDir,
@@ -74,8 +82,7 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
           runtime.subagentSessionsDir,
         ),
       }),
-    promptPermission: (ctx, details) =>
-      promptPermission(runtime, forwardingDeps, ctx, details),
+    promptPermission: (ctx, details) => prompter.prompt(ctx, details),
     createPermissionRequestId,
     startForwardedPermissionPolling: (ctx) =>
       startForwardedPermissionPolling(runtime, forwardingDeps, ctx),

package/src/pattern-suggest.ts

@@ -0,0 +1,91 @@
+import { deriveApprovalPattern } from "./session-rules";
+
+/** The suggestion returned for a "Yes, for this session" dialog option. */
+export interface SessionApprovalSuggestion {
+  /** The permission surface this approval applies to. */
+  surface: string;
+  /** The wildcard pattern to store as a session rule. */
+  pattern: string;
+  /** Human-readable label for the "for session" dialog option. */
+  label: string;
+}
+
+/**
+ * Suggest a bash session-approval pattern from a command string.
+ *
+ * Heuristic: split on the first space to get the base command.
+ * Multi-word commands → `<command> *`.
+ * Single-word commands → exact command (no wildcard).
+ *
+ * This is intentionally conservative. The arity table (#52) will refine
+ * suggestions later (e.g. `git checkout *` instead of `git *`).
+ */
+export function suggestBashPattern(command: string): string {
+  const trimmed = command.trim();
+  const spaceIndex = trimmed.indexOf(" ");
+  if (spaceIndex === -1) {
+    return trimmed;
+  }
+  return `${trimmed.slice(0, spaceIndex)} *`;
+}
+
+/**
+ * Suggest an MCP session-approval pattern from a resolved target string.
+ *
+ * - Qualified target (`server:tool`) → `server:*`
+ * - Munged target (`server_tool`) → `server_*`
+ * - Bare target (no separator) → `*`
+ */
+export function suggestMcpPattern(target: string): string {
+  const trimmed = target.trim();
+
+  const colonIndex = trimmed.indexOf(":");
+  if (colonIndex > 0) {
+    return `${trimmed.slice(0, colonIndex)}:*`;
+  }
+
+  const underscoreIndex = trimmed.indexOf("_");
+  if (underscoreIndex > 0) {
+    return `${trimmed.slice(0, underscoreIndex)}_*`;
+  }
+
+  return "*";
+}
+
+function buildLabel(pattern: string): string {
+  return `Yes, allow "${pattern}" for this session`;
+}
+
+/**
+ * Suggest a session-approval pattern for the given permission surface and value.
+ *
+ * Returns a `SessionApprovalSuggestion` with the surface, the wildcard pattern
+ * to store in `SessionRules`, and a human-readable dialog label.
+ */
+export function suggestSessionPattern(
+  surface: string,
+  value: string,
+): SessionApprovalSuggestion {
+  let pattern: string;
+
+  switch (surface) {
+    case "bash":
+      pattern = suggestBashPattern(value);
+      break;
+    case "mcp":
+      pattern = suggestMcpPattern(value);
+      break;
+    case "skill":
+      pattern = value;
+      break;
+    case "external_directory":
+      pattern = deriveApprovalPattern(value);
+      break;
+    default:
+      // Tool surfaces (read, write, edit, grep, find, ls, extension tools)
+      pattern = "*";
+      break;
+  }
+
+  return { surface, pattern, label: buildLabel(pattern) };
+}

package/src/permission-dialog.ts

@@ -64,13 +64,27 @@ export function isPermissionDecisionState(
   );
 }
 
+export interface RequestPermissionOptions {
+  /** Override the "for this session" option label (e.g. to show the suggested pattern). */
+  sessionLabel?: string;
+}
+
 export async function requestPermissionDecisionFromUi(
   ui: PermissionDecisionUi,
   title: string,
   message: string,
+  options?: RequestPermissionOptions,
 ): Promise<PermissionPromptDecision> {
+  const sessionOption = options?.sessionLabel ?? APPROVE_FOR_SESSION_OPTION;
+  const decisionOptions = [
+    APPROVE_OPTION,
+    sessionOption,
+    DENY_OPTION,
+    DENY_WITH_REASON_OPTION,
+  ] as const;
+
   const selected = await ui.select(`${title}\n${message}`, [
-    ...PERMISSION_DECISION_OPTIONS,
+    ...decisionOptions,
   ]);
 
   if (selected === APPROVE_OPTION) {
@@ -80,7 +94,7 @@ export async function requestPermissionDecisionFromUi(
     };
   }
 
-  if (selected === APPROVE_FOR_SESSION_OPTION) {
+  if (selected === sessionOption) {
     return {
       approved: true,
       state: "approved_for_session",

package/src/permission-gate.ts

@@ -2,7 +2,7 @@ import type { PermissionPromptDecision } from "./permission-dialog";
 
 /** Result of applying the permission gate. */
 export type PermissionGateResult =
-  | { action: "allow" }
+  | { action: "allow"; sessionApproval?: { surface: string; pattern: string } }
   | { action: "block"; reason: string };
 
 /** Everything the gate needs — no direct dependency on ExtensionContext. */
@@ -16,6 +16,13 @@ export interface PermissionGateParams {
   /** Prompt the user for approval. Only called when state === "ask" and canConfirm is true. */
   promptForApproval: () => Promise<PermissionPromptDecision>;
 
+  /**
+   * Session approval suggestion to record when the user selects
+   * "for this session". When present and the decision is `approved_for_session`,
+   * the result carries the suggestion back to the caller for recording.
+   */
+  sessionApproval?: { surface: string; pattern: string };
+
   /** Write a review-log entry. Called for deny and ask-but-unavailable paths. */
   writeLog: (event: string, extra: Record<string, unknown>) => void;
 
@@ -68,6 +75,9 @@ export async function applyPermissionGate(
     if (!decision.approved) {
       return { action: "block", reason: messages.userDeniedReason(decision) };
     }
+    if (decision.state === "approved_for_session" && params.sessionApproval) {
+      return { action: "allow", sessionApproval: params.sessionApproval };
+    }
   }
 
   return { action: "allow" };

package/src/permission-manager.ts

@@ -493,6 +493,20 @@ export class PermissionManager {
     if (normalizedToolName === "skill") {
       const skillName = toRecord(input).name;
       const lookupValue = typeof skillName === "string" ? skillName : "*";
+
+      // Session check.
+      if (sessionRules && sessionRules.length > 0) {
+        const sessionRule = evaluate("skill", lookupValue, sessionRules);
+        if (sessionRules.includes(sessionRule)) {
+          return {
+            toolName,
+            state: "allow",
+            matchedPattern: sessionRule.pattern,
+            source: "session",
+          };
+        }
+      }
+
       const rule = evaluate("skill", lookupValue, composedRules);
       return {
         toolName,
@@ -506,6 +520,21 @@ export class PermissionManager {
     if (normalizedToolName === "bash") {
       const record = toRecord(input);
       const command = typeof record.command === "string" ? record.command : "";
+
+      // Session check.
+      if (sessionRules && sessionRules.length > 0) {
+        const sessionRule = evaluate("bash", command, sessionRules);
+        if (sessionRules.includes(sessionRule)) {
+          return {
+            toolName,
+            state: "allow",
+            command,
+            matchedPattern: sessionRule.pattern,
+            source: "session",
+          };
+        }
+      }
+
       const rule = evaluate("bash", command, composedRules);
       return {
         toolName,
@@ -527,6 +556,22 @@ export class PermissionManager {
       ];
       const fallbackTarget = mcpTargets[0] || "mcp";
 
+      // Session check: try each candidate target against session rules.
+      if (sessionRules && sessionRules.length > 0) {
+        for (const target of mcpTargets) {
+          const sessionRule = evaluate("mcp", target, sessionRules);
+          if (sessionRules.includes(sessionRule)) {
+            return {
+              toolName,
+              state: "allow",
+              matchedPattern: sessionRule.pattern,
+              target,
+              source: "session",
+            };
+          }
+        }
+      }
+
       // Try each candidate target. Stop on the first non-default match.
       for (const target of mcpTargets) {
         const rule = evaluate("mcp", target, composedRules);
@@ -552,6 +597,20 @@ export class PermissionManager {
     }
 
     // --- Tools (read, write, edit, grep, find, ls, extension tools) ---
+
+    // Session check.
+    if (sessionRules && sessionRules.length > 0) {
+      const sessionRule = evaluate(normalizedToolName, "*", sessionRules);
+      if (sessionRules.includes(sessionRule)) {
+        return {
+          toolName,
+          state: "allow",
+          matchedPattern: sessionRule.pattern,
+          source: "session",
+        };
+      }
+    }
+
     const rule = evaluate(normalizedToolName, "*", composedRules);
 
     if (BUILT_IN_TOOL_PERMISSION_NAMES.has(normalizedToolName)) {

package/src/permission-prompter.ts

@@ -0,0 +1,146 @@
+import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+import type { PermissionSystemExtensionConfig } from "./extension-config";
+import type { ForwardedPermissionLogger } from "./forwarded-permissions/io";
+import {
+  confirmPermission,
+  type PermissionForwardingDeps,
+} from "./forwarded-permissions/polling";
+import type { PromptPermissionDetails } from "./handlers/types";
+import type {
+  PermissionPromptDecision,
+  RequestPermissionOptions,
+} from "./permission-dialog";
+import { shouldAutoApprovePermissionState } from "./yolo-mode";
+
+/** Mockable contract exposed to handlers via HandlerDeps. */
+export interface PermissionPrompterApi {
+  prompt(
+    ctx: ExtensionContext,
+    details: PromptPermissionDetails,
+  ): Promise<PermissionPromptDecision>;
+}
+
+/**
+ * Dependencies required by PermissionPrompter.
+ *
+ * Keeps the prompter's external surface narrow: callers provide config
+ * access, review-log writing, path constants, and the UI dialog function.
+ * The prompter synthesises the PermissionForwardingDeps it needs internally.
+ */
+export interface PermissionPrompterDeps {
+  /** Read current config for yolo-mode check (called at prompt time). */
+  getConfig(): PermissionSystemExtensionConfig;
+  /** Write structured entries to the permission review log. */
+  writeReviewLog(event: string, details: Record<string, unknown>): void;
+  /** Directory containing subagent session state. */
+  subagentSessionsDir: string;
+  /** Directory used for file-based permission forwarding requests/responses. */
+  forwardingDir: string;
+  /** Show the interactive permission dialog in the UI. */
+  requestPermissionDecisionFromUi(
+    ui: ExtensionContext["ui"],
+    title: string,
+    message: string,
+    options?: RequestPermissionOptions,
+  ): Promise<PermissionPromptDecision>;
+}
+
+/**
+ * Encapsulates the full permission-prompt flow:
+ *   1. Yolo-mode auto-approval check.
+ *   2. Review-log "waiting" entry.
+ *   3. UI-present vs. subagent-forwarding branching (via confirmPermission).
+ *   4. Review-log "approved" / "denied" entry.
+ *
+ * Injecting a single PermissionPrompter instance into HandlerDeps means
+ * adding a new prompt parameter (e.g. a future sessionLabel variant) only
+ * requires changing PromptPermissionDetails and this class — not the full
+ * 4-file threading chain.
+ */
+export class PermissionPrompter implements PermissionPrompterApi {
+  constructor(private readonly deps: PermissionPrompterDeps) {}
+
+  async prompt(
+    ctx: ExtensionContext,
+    details: PromptPermissionDetails,
+  ): Promise<PermissionPromptDecision> {
+    if (shouldAutoApprovePermissionState("ask", this.deps.getConfig())) {
+      this.writeReviewEntry("permission_request.auto_approved", details);
+      return { approved: true, state: "approved" };
+    }
+
+    this.writeReviewEntry("permission_request.waiting", details);
+
+    const decision = await confirmPermission(
+      ctx,
+      details.message,
+      this.buildForwardingDeps(),
+      details.sessionLabel ? { sessionLabel: details.sessionLabel } : undefined,
+    );
+
+    this.writeReviewEntry(
+      decision.approved
+        ? "permission_request.approved"
+        : "permission_request.denied",
+      {
+        ...details,
+        resolution: decision.state,
+        denialReason: decision.denialReason,
+      },
+    );
+
+    return decision;
+  }
+
+  // ── Private helpers ──────────────────────────────────────────────────────
+
+  private writeReviewEntry(
+    event: string,
+    details: PromptPermissionDetails & {
+      resolution?: string;
+      denialReason?: string;
+    },
+  ): void {
+    this.deps.writeReviewLog(event, {
+      requestId: details.requestId,
+      source: details.source,
+      agentName: details.agentName,
+      message: details.message,
+      toolCallId: details.toolCallId ?? null,
+      toolName: details.toolName ?? null,
+      skillName: details.skillName ?? null,
+      path: details.path ?? null,
+      command: details.command ?? null,
+      target: details.target ?? null,
+      toolInputPreview: details.toolInputPreview ?? null,
+      resolution: details.resolution ?? null,
+      denialReason: details.denialReason ?? null,
+    });
+  }
+
+  /**
+   * Build a PermissionForwardingDeps to pass to confirmPermission.
+   *
+   * Yolo-mode is already handled at the prompter level, so shouldAutoApprove
+   * returns false here (confirmPermission does not call it; only
+   * processForwardedPermissionRequests does, and that has its own deps).
+   *
+   * The logger delegates writeReviewLog to deps and uses a no-op writeDebugLog
+   * (trace-level forwarding debug is deferred — see open question in the plan).
+   */
+  private buildForwardingDeps(): PermissionForwardingDeps {
+    const { deps } = this;
+    const logger: ForwardedPermissionLogger = {
+      writeReviewLog: deps.writeReviewLog,
+      writeDebugLog: () => undefined,
+    };
+    return {
+      forwardingDir: deps.forwardingDir,
+      subagentSessionsDir: deps.subagentSessionsDir,
+      logger,
+      writeReviewLog: deps.writeReviewLog,
+      requestPermissionDecisionFromUi: deps.requestPermissionDecisionFromUi,
+      shouldAutoApprove: () => false,
+    };
+  }
+}