@gotgenes/pi-permission-system 9.2.0 → 10.1.0

package/src/mcp-targets.ts

@@ -1,5 +1,28 @@
 import { getNonEmptyString, toRecord } from "./common";
 
+/**
+ * An ordered accumulator that owns the uniqueness invariant.
+ *
+ * `add` ignores null/empty values and silently skips duplicates (first-insertion
+ * wins). `toArray` returns the ordered result as an independent copy.
+ */
+export class McpTargetList {
+  private readonly targets: string[] = [];
+
+  add(value: string | null): void {
+    if (!value) {
+      return;
+    }
+    if (!this.targets.includes(value)) {
+      this.targets.push(value);
+    }
+  }
+
+  toArray(): string[] {
+    return [...this.targets];
+  }
+}
+
 /**
  * Parse a qualified MCP tool name of the form `server:tool`.
  *
@@ -31,7 +54,7 @@ export function parseQualifiedMcpToolName(
 function addDerivedMcpServerTargets(
   toolName: string,
   configuredServerNames: readonly string[],
-  pushTarget: (value: string | null) => void,
+  targets: McpTargetList,
 ): void {
   const trimmedToolName = toolName.trim();
   if (!trimmedToolName) {
@@ -52,9 +75,9 @@ function addDerivedMcpServerTargets(
       continue;
     }
 
-    pushTarget(`${trimmedServerName}_${trimmedToolName}`);
-    pushTarget(`${trimmedServerName}:${trimmedToolName}`);
-    pushTarget(trimmedServerName);
+    targets.add(`${trimmedServerName}_${trimmedToolName}`);
+    targets.add(`${trimmedServerName}:${trimmedToolName}`);
+    targets.add(trimmedServerName);
   }
 }
 
@@ -62,22 +85,22 @@ function pushMcpToolPermissionTargets(
   rawReference: string,
   serverHint: string | null,
   configuredServerNames: readonly string[],
-  pushTarget: (value: string | null) => void,
+  targets: McpTargetList,
 ): void {
   const qualified = parseQualifiedMcpToolName(rawReference);
   const resolvedServer = serverHint ?? qualified?.server ?? null;
   const resolvedTool = qualified?.tool ?? rawReference;
 
   if (resolvedServer) {
-    pushTarget(`${resolvedServer}_${resolvedTool}`);
-    pushTarget(`${resolvedServer}:${resolvedTool}`);
-    pushTarget(resolvedServer);
+    targets.add(`${resolvedServer}_${resolvedTool}`);
+    targets.add(`${resolvedServer}:${resolvedTool}`);
+    targets.add(resolvedServer);
   } else {
-    addDerivedMcpServerTargets(resolvedTool, configuredServerNames, pushTarget);
+    addDerivedMcpServerTargets(resolvedTool, configuredServerNames, targets);
   }
 
-  pushTarget(resolvedTool);
-  pushTarget(rawReference);
+  targets.add(resolvedTool);
+  targets.add(rawReference);
 }
 
 /**
@@ -98,32 +121,19 @@ export function createMcpPermissionTargets(
   const describe = getNonEmptyString(record.describe);
   const search = getNonEmptyString(record.search);
 
-  const targets: string[] = [];
-  const pushTarget = (value: string | null) => {
-    if (!value) {
-      return;
-    }
-    if (!targets.includes(value)) {
-      targets.push(value);
-    }
-  };
+  const targets = new McpTargetList();
 
   if (tool) {
-    pushMcpToolPermissionTargets(
-      tool,
-      server,
-      configuredServerNames,
-      pushTarget,
-    );
-    pushTarget("mcp_call");
-    return targets;
+    pushMcpToolPermissionTargets(tool, server, configuredServerNames, targets);
+    targets.add("mcp_call");
+    return targets.toArray();
   }
 
   if (connect) {
-    pushTarget(`mcp_connect_${connect}`);
-    pushTarget(connect);
-    pushTarget("mcp_connect");
-    return targets;
+    targets.add(`mcp_connect_${connect}`);
+    targets.add(connect);
+    targets.add("mcp_connect");
+    return targets.toArray();
   }
 
   if (describe) {
@@ -131,30 +141,30 @@ export function createMcpPermissionTargets(
       describe,
       server,
       configuredServerNames,
-      pushTarget,
+      targets,
     );
-    pushTarget("mcp_describe");
-    return targets;
+    targets.add("mcp_describe");
+    return targets.toArray();
   }
 
   if (search) {
     if (server) {
-      pushTarget(`mcp_server_${server}`);
-      pushTarget(server);
+      targets.add(`mcp_server_${server}`);
+      targets.add(server);
     }
 
-    pushTarget(search);
-    pushTarget("mcp_search");
-    return targets;
+    targets.add(search);
+    targets.add("mcp_search");
+    return targets.toArray();
   }
 
   if (server) {
-    pushTarget(`mcp_server_${server}`);
-    pushTarget(server);
-    pushTarget("mcp_list");
-    return targets;
+    targets.add(`mcp_server_${server}`);
+    targets.add(server);
+    targets.add("mcp_list");
+    return targets.toArray();
   }
 
-  pushTarget("mcp_status");
-  return targets;
+  targets.add("mcp_status");
+  return targets.toArray();
 }

package/src/permission-event-rpc.ts

@@ -21,11 +21,13 @@ import type {
   PermissionsRpcReply,
 } from "./permission-events";
 import {
+  emitUiPromptEvent,
   PERMISSIONS_PROTOCOL_VERSION,
   PERMISSIONS_RPC_CHECK_CHANNEL,
   PERMISSIONS_RPC_PROMPT_CHANNEL,
 } from "./permission-events";
 import type { PermissionManager } from "./permission-manager";
+import { buildRpcUiPrompt } from "./permission-ui-prompt";
 import type { Rule } from "./rule";
 
 /** Dependencies injected into the RPC handler registry. */
@@ -155,6 +157,11 @@ async function handlePromptRpc(
       ? `Permission request${agentName ? ` from ${agentName}` : ""}`
       : "Permission request";
 
+    emitUiPromptEvent(
+      events,
+      buildRpcUiPrompt({ requestId, surface, value, agentName, message }),
+    );
+
     const decision = await deps.requestPermissionDecisionFromUi(
       ctx.ui,
       title,

package/src/permission-events.ts

@@ -27,6 +27,9 @@ export const PERMISSIONS_PROTOCOL_VERSION = 1;
 /** Emitted at `session_start`, after the service is published. */
 export const PERMISSIONS_READY_CHANNEL = "permissions:ready";
 
+/** Emitted when a permission request is committed to the active UI prompt path. */
+export const PERMISSIONS_UI_PROMPT_CHANNEL = "permissions:ui_prompt";
+
 /** Emitted after every permission gate resolution. */
 export const PERMISSIONS_DECISION_CHANNEL = "permissions:decision";
 
@@ -61,9 +64,63 @@ export type PermissionsRpcReply<T = void> =
 
 // ── permissions:ready ──────────────────────────────────────────────────────
 
-/** Payload emitted on `permissions:ready`. */
-export interface PermissionsReadyEvent {
-  protocolVersion: number;
+/**
+ * Payload emitted on `permissions:ready`.
+ *
+ * Intentionally empty: the channel is a readiness signal. Version negotiation
+ * lives in the RPC envelope (`PermissionsRpcReply`), not in broadcast payloads —
+ * the published types plus package semver define the broadcast contract.
+ */
+export type PermissionsReadyEvent = Record<string, never>;
+
+// ── permissions:ui_prompt ──────────────────────────────────────────────────
+
+/**
+ * Origin of a UI 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.
+ */
+export type PermissionUiPromptSource =
+  | "tool_call"
+  | "skill_input"
+  | "skill_read"
+  | "rpc_prompt";
+
+/** Forwarding context, present only when a prompt was forwarded from a non-UI subagent. */
+export interface ForwardedPromptContext {
+  /** Requesting subagent's display name, when known. */
+  requesterAgentName: string | null;
+  /** Requesting subagent's session id, when known. */
+  requesterSessionId: string | null;
+}
+
+/**
+ * Payload emitted on `permissions:ui_prompt`, immediately before the active
+ * user-facing permission UI is shown.
+ *
+ * Lean by design: `surface`/`value` are the normalized display projection a
+ * notification consumer reads; `source` is the origin; `forwarding` is non-null
+ * only for forwarded subagent prompts. There is no `protocolVersion` — the
+ * published types plus package semver define the broadcast contract, and
+ * consumers should read defensively.
+ */
+export interface PermissionUiPromptEvent {
+  /** Unique ID for the permission request being prompted. */
+  requestId: string;
+  /** Prompt origin. */
+  source: PermissionUiPromptSource;
+  /** Normalized display surface (e.g. "bash", "skill"), when known. */
+  surface: string | null;
+  /** Normalized display value (command, path, skill name, etc.), when known. */
+  value: string | null;
+  /** Agent name (when known). */
+  agentName: string | null;
+  /** Message displayed to the user. */
+  message: string;
+  /** Forwarding context, or null for a direct prompt. */
+  forwarding: ForwardedPromptContext | null;
 }
 
 // ── permissions:decision ───────────────────────────────────────────────────
@@ -164,10 +221,29 @@ export interface PermissionsPromptReplyData {
  * reacting to ready can immediately resolve `getPermissionsService()`.
  */
 export function emitReadyEvent(events: PermissionEventBus): void {
-  const payload: PermissionsReadyEvent = {
-    protocolVersion: PERMISSIONS_PROTOCOL_VERSION,
-  };
-  events.emit(PERMISSIONS_READY_CHANNEL, payload);
+  const payload: PermissionsReadyEvent = {};
+  try {
+    events.emit(PERMISSIONS_READY_CHANNEL, payload);
+  } catch {
+    // Broadcasts are best-effort. A throwing listener must not block the
+    // permission system from completing session startup.
+  }
+}
+
+/**
+ * Emit a `permissions:ui_prompt` broadcast.
+ * Call immediately before invoking the active user-facing permission UI.
+ */
+export function emitUiPromptEvent(
+  events: PermissionEventBus,
+  event: PermissionUiPromptEvent,
+): void {
+  try {
+    events.emit(PERMISSIONS_UI_PROMPT_CHANNEL, event);
+  } catch {
+    // UI-prompt broadcasts are observational. A consumer failure must not block
+    // the permission dialog itself.
+  }
 }
 
 /**
@@ -178,5 +254,10 @@ export function emitDecisionEvent(
   events: PermissionEventBus,
   event: PermissionDecisionEvent,
 ): void {
-  events.emit(PERMISSIONS_DECISION_CHANNEL, event);
+  try {
+    events.emit(PERMISSIONS_DECISION_CHANNEL, event);
+  } catch {
+    // Broadcasts are best-effort. A throwing listener must not block the
+    // permission gate from resolving.
+  }
 }

package/src/permission-forwarding.ts

@@ -1,6 +1,7 @@
 import { join } from "node:path";
 
 import type { PermissionDecisionState } from "./permission-dialog";
+import type { PermissionUiPromptSource } from "./permission-events";
 import type { SubagentSessionRegistry } from "./subagent-registry";
 
 export const PERMISSION_FORWARDING_POLL_INTERVAL_MS = 250;
@@ -38,6 +39,19 @@ const SESSION_FORWARDING_ROOT_DIRECTORY_NAME = "sessions";
 const SESSION_FORWARDING_REQUESTS_DIRECTORY_NAME = "requests";
 const SESSION_FORWARDING_RESPONSES_DIRECTORY_NAME = "responses";
 
+/**
+ * Display fields relayed from a forwarding child to the parent UI so the parent
+ * can emit a non-degraded `permissions:ui_prompt` event.
+ *
+ * Carried separately from the prompt message because the parent reconstructs
+ * the original event through `buildForwardedUiPrompt`, not from the message text.
+ */
+export interface ForwardedPromptDisplay {
+  source: PermissionUiPromptSource;
+  surface: string | null;
+  value: string | null;
+}
+
 export type ForwardedPermissionRequest = {
   id: string;
   createdAt: number;
@@ -45,6 +59,15 @@ export type ForwardedPermissionRequest = {
   targetSessionId: string;
   requesterAgentName: string;
   message: string;
+  /**
+   * Original prompt display fields, persisted so the parent emits a
+   * non-degraded event. Optional for version-skew tolerance: a parent on a
+   * newer version may read a request written by an older child during an
+   * upgrade, in which case the reader defaults `source` to `"tool_call"`.
+   */
+  source?: PermissionUiPromptSource;
+  surface?: string | null;
+  value?: string | null;
 };
 
 export type ForwardedPermissionResponse = {

package/src/permission-prompter.ts

@@ -1,15 +1,12 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { PermissionSystemExtensionConfig } from "./extension-config";
-import type { ForwardedPermissionLogger } from "./forwarded-permissions/io";
+import type { ApprovalRequester } from "./forwarded-permissions/permission-forwarder";
+import type { PermissionPromptDecision } from "./permission-dialog";
 import {
-  confirmPermission,
-  type PermissionForwardingDeps,
-} from "./forwarded-permissions/polling";
-import type {
-  PermissionPromptDecision,
-  RequestPermissionOptions,
-} from "./permission-dialog";
-import type { SubagentSessionRegistry } from "./subagent-registry";
+  emitUiPromptEvent,
+  type PermissionEventBus,
+} from "./permission-events";
+import { buildDirectUiPrompt } from "./permission-ui-prompt";
 import { shouldAutoApprovePermissionState } from "./yolo-mode";
 
 export type PermissionReviewSource = "tool_call" | "skill_input" | "skill_read";
@@ -43,27 +40,18 @@ export interface PermissionPrompterApi {
  * 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.
+ * access, review-log writing, the UI-prompt event bus, and the forwarder
+ * that owns the UI/subagent-forwarding branching logic.
  */
 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;
-  /** In-process subagent session registry for detection and forwarding target resolution. */
-  registry?: SubagentSessionRegistry;
-  /** Show the interactive permission dialog in the UI. */
-  requestPermissionDecisionFromUi(
-    ui: ExtensionContext["ui"],
-    title: string,
-    message: string,
-    options?: RequestPermissionOptions,
-  ): Promise<PermissionPromptDecision>;
+  /** Event bus used for UI prompt broadcasts. */
+  events: PermissionEventBus;
+  /** Resolves the permission decision: direct UI dialog or forwarded to parent. */
+  forwarder: ApprovalRequester;
 }
 
 /**
@@ -91,11 +79,24 @@ export class PermissionPrompter implements PermissionPrompterApi {
 
     this.writeReviewEntry("permission_request.waiting", details);
 
-    const decision = await confirmPermission(
+    // Build the event once. When this session has UI it broadcasts directly;
+    // when it does not (a forwarding subagent), the display fields ride along
+    // to the parent so the parent emits a non-degraded event from the
+    // forwarded path instead of here.
+    const uiPrompt = buildDirectUiPrompt(details);
+    if (ctx.hasUI) {
+      emitUiPromptEvent(this.deps.events, uiPrompt);
+    }
+
+    const decision = await this.deps.forwarder.requestApproval(
       ctx,
       details.message,
-      this.buildForwardingDeps(),
       details.sessionLabel ? { sessionLabel: details.sessionLabel } : undefined,
+      {
+        source: uiPrompt.source,
+        surface: uiPrompt.surface,
+        value: uiPrompt.value,
+      },
     );
 
     this.writeReviewEntry(
@@ -137,34 +138,4 @@ export class PermissionPrompter implements PermissionPrompterApi {
       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 = {
-      // eslint-disable-next-line @typescript-eslint/unbound-method -- logger methods are plain function closures; no this-binding issue
-      writeReviewLog: deps.writeReviewLog,
-      writeDebugLog: () => undefined,
-    };
-    return {
-      forwardingDir: deps.forwardingDir,
-      subagentSessionsDir: deps.subagentSessionsDir,
-      registry: deps.registry,
-      logger,
-      // eslint-disable-next-line @typescript-eslint/unbound-method -- logger methods are plain function closures; no this-binding issue
-      writeReviewLog: deps.writeReviewLog,
-      // eslint-disable-next-line @typescript-eslint/unbound-method -- same as above
-      requestPermissionDecisionFromUi: deps.requestPermissionDecisionFromUi,
-      shouldAutoApprove: () => false,
-    };
-  }
 }

package/src/permission-resolver.ts

@@ -0,0 +1,17 @@
+import type { PermissionCheckResult } from "./types";
+
+/**
+ * Resolves the effective permission for a surface/input, applying the current
+ * session rules internally.
+ *
+ * Collapses the `checkPermission` + `getSessionRuleset` relay that every gate
+ * previously threaded by hand: the ruleset was only ever fetched to be passed
+ * straight back into `checkPermission`, so the two are one operation.
+ */
+export interface PermissionResolver {
+  resolve(
+    surface: string,
+    input: unknown,
+    agentName?: string,
+  ): PermissionCheckResult;
+}

package/src/permission-session.ts

@@ -4,18 +4,28 @@ import {
   getActiveAgentName,
   getActiveAgentNameFromSystemPrompt,
 } from "./active-agent";
+import type { AgentPrepSession } from "./agent-prep-session";
 import type { PermissionSystemExtensionConfig } from "./extension-config";
 import type { ExtensionPaths } from "./extension-paths";
 import type { ForwardingController } from "./forwarding-manager";
+import type { GateHandlerSession } from "./gate-handler-session";
+import type { GatePrompter } from "./gate-prompter";
 import type { PermissionPromptDecision } from "./permission-dialog";
 import type { PermissionManager } from "./permission-manager";
 import type { PromptPermissionDetails } from "./permission-prompter";
+import type { PermissionResolver } from "./permission-resolver";
 import type { Rule } from "./rule";
 import { createPermissionManagerForCwd } from "./runtime";
 import type { SessionApproval } from "./session-approval";
+import type { SessionApprovalRecorder } from "./session-approval-recorder";
+import type { SessionLifecycleSession } from "./session-lifecycle-session";
 import type { SessionLogger } from "./session-logger";
 import { SessionRules } from "./session-rules";
 import type { SkillPromptEntry } from "./skill-prompt-sanitizer";
+import {
+  resolveToolPreviewLimits,
+  type ToolPreviewFormatterOptions,
+} from "./tool-preview-formatter";
 import type { PermissionCheckResult, PermissionState } from "./types";
 
 /**
@@ -54,7 +64,15 @@ export interface PermissionSessionRuntimeDeps {
  * - `ForwardingController` — polling lifecycle
  * - `PermissionSessionRuntimeDeps` — config refresh + log delegates
  */
-export class PermissionSession {
+export class PermissionSession
+  implements
+    PermissionResolver,
+    SessionApprovalRecorder,
+    GatePrompter,
+    GateHandlerSession,
+    AgentPrepSession,
+    SessionLifecycleSession
+{
   private context: ExtensionContext | null = null;
   private permissionManager: PermissionManager;
   private readonly sessionRules = new SessionRules();
@@ -110,6 +128,24 @@ export class PermissionSession {
     );
   }
 
+  /**
+   * Resolve the effective permission for a surface/input, applying the current
+   * session rules. Composes `checkPermission` with `getSessionRuleset` so
+   * callers never thread the ruleset by hand.
+   */
+  resolve(
+    surface: string,
+    input: unknown,
+    agentName?: string,
+  ): PermissionCheckResult {
+    return this.checkPermission(
+      surface,
+      input,
+      agentName,
+      this.getSessionRuleset(),
+    );
+  }
+
   getToolPermission(toolName: string, agentName?: string): PermissionState {
     return this.permissionManager.getToolPermission(toolName, agentName);
   }
@@ -251,13 +287,25 @@ export class PermissionSession {
 
   // ── Infrastructure paths ───────────────────────────────────────────────
 
-  getInfrastructureDirs(): readonly string[] {
-    return this.paths.piInfrastructureDirs;
+  /**
+   * Combined infrastructure read directories: static paths from
+   * `ExtensionPaths` plus config-derived paths.
+   */
+  getInfrastructureReadDirs(): string[] {
+    return [
+      ...this.paths.piInfrastructureDirs,
+      ...(this.config.piInfrastructureReadPaths ?? []),
+    ];
   }
 
-  /** Config-derived infrastructure read paths (current at call time). */
-  getInfrastructureReadPaths(): string[] {
-    return this.config.piInfrastructureReadPaths ?? [];
+  /**
+   * Resolved tool-preview formatter options from the current config.
+   *
+   * Replaces the handler's `resolveToolPreviewLimits(session.config)` reach
+   * so the pipeline reads a clean value rather than pulling raw config.
+   */
+  getToolPreviewLimits(): ToolPreviewFormatterOptions {
+    return resolveToolPreviewLimits(this.config);
   }
 
   // ── Prompting ──────────────────────────────────────────────────────────
@@ -275,8 +323,28 @@ export class PermissionSession {
     return this.runtimeDeps.promptPermission(ctx, details);
   }
 
-  /** Generate a unique ID for a permission request. */
-  createPermissionRequestId(prefix: string): string {
-    return `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 10)}-${process.pid}`;
+  /**
+   * Whether an interactive confirmation is possible using the stored context.
+   * Returns `false` when no context is active (before `activate` is called).
+   * Implements {@link GatePrompter}.
+   */
+  canConfirm(): boolean {
+    return this.context !== null && this.canPrompt(this.context);
+  }
+
+  /**
+   * Prompt the user for a permission decision using the stored context.
+   * Throws if no context is active — `canConfirm()` guards this in normal use.
+   * Implements {@link GatePrompter}.
+   */
+  promptPermission(
+    details: PromptPermissionDetails,
+  ): Promise<PermissionPromptDecision> {
+    if (this.context === null) {
+      return Promise.reject(
+        new Error("promptPermission called before the session was activated"),
+      );
+    }
+    return this.prompt(this.context, details);
   }
 }