@gotgenes/pi-permission-system 10.0.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-prompter.ts

@@ -1,20 +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 {
-  confirmPermission,
-  type PermissionForwardingDeps,
-} from "./forwarded-permissions/polling";
-import type {
-  PermissionPromptDecision,
-  RequestPermissionOptions,
-} from "./permission-dialog";
+import type { ApprovalRequester } from "./forwarded-permissions/permission-forwarder";
+import type { PermissionPromptDecision } from "./permission-dialog";
 import {
   emitUiPromptEvent,
   type PermissionEventBus,
 } from "./permission-events";
 import { buildDirectUiPrompt } from "./permission-ui-prompt";
-import type { SubagentSessionRegistry } from "./subagent-registry";
 import { shouldAutoApprovePermissionState } from "./yolo-mode";
 
 export type PermissionReviewSource = "tool_call" | "skill_input" | "skill_read";
@@ -48,29 +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;
   /** Event bus used for UI prompt broadcasts. */
   events: PermissionEventBus;
-  /** Show the interactive permission dialog in the UI. */
-  requestPermissionDecisionFromUi(
-    ui: ExtensionContext["ui"],
-    title: string,
-    message: string,
-    options?: RequestPermissionOptions,
-  ): Promise<PermissionPromptDecision>;
+  /** Resolves the permission decision: direct UI dialog or forwarded to parent. */
+  forwarder: ApprovalRequester;
 }
 
 /**
@@ -107,10 +88,9 @@ export class PermissionPrompter implements PermissionPrompterApi {
       emitUiPromptEvent(this.deps.events, uiPrompt);
     }
 
-    const decision = await confirmPermission(
+    const decision = await this.deps.forwarder.requestApproval(
       ctx,
       details.message,
-      this.buildForwardingDeps(),
       details.sessionLabel ? { sessionLabel: details.sessionLabel } : undefined,
       {
         source: uiPrompt.source,
@@ -158,35 +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,
-      events: deps.events,
-      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);
   }
 }

package/src/permissions-service.ts

@@ -0,0 +1,53 @@
+import { buildInputForSurface } from "./input-normalizer";
+import type { PermissionManager } from "./permission-manager";
+import type { PermissionsService } from "./service";
+import type { SessionRules } from "./session-rules";
+import type {
+  ToolInputFormatter,
+  ToolInputFormatterRegistry,
+} from "./tool-input-formatter-registry";
+
+/**
+ * In-process implementation of the cross-extension {@link PermissionsService}.
+ *
+ * Constructed once in the composition root and backed by the runtime's
+ * permission manager and session rules. Both injected instances are stable
+ * for the lifetime of the factory — `runtime.permissionManager` is never
+ * reassigned on the runtime object (only `PermissionSession` reassigns its
+ * own internal copy), and `runtime.sessionRules` is `readonly`.
+ */
+export class LocalPermissionsService implements PermissionsService {
+  constructor(
+    private readonly permissionManager: PermissionManager,
+    private readonly sessionRules: SessionRules,
+    private readonly formatterRegistry: ToolInputFormatterRegistry,
+  ) {}
+
+  checkPermission(
+    surface: string,
+    value?: string,
+    agentName?: string,
+  ): ReturnType<PermissionsService["checkPermission"]> {
+    const input = buildInputForSurface(surface, value);
+    return this.permissionManager.checkPermission(
+      surface,
+      input,
+      agentName,
+      this.sessionRules.getRuleset(),
+    );
+  }
+
+  getToolPermission(
+    toolName: string,
+    agentName?: string,
+  ): ReturnType<PermissionsService["getToolPermission"]> {
+    return this.permissionManager.getToolPermission(toolName, agentName);
+  }
+
+  registerToolInputFormatter(
+    toolName: string,
+    formatter: ToolInputFormatter,
+  ): ReturnType<PermissionsService["registerToolInputFormatter"]> {
+    return this.formatterRegistry.register(toolName, formatter);
+  }
+}

package/src/service-lifecycle.ts

@@ -0,0 +1,49 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import { emitReadyEvent, type PermissionEventBus } from "./permission-events";
+import {
+  type PermissionsService,
+  publishPermissionsService,
+  unpublishPermissionsService,
+} from "./service";
+import { isRegisteredSubagentChild } from "./subagent-context";
+import type { SubagentSessionRegistry } from "./subagent-registry";
+
+/** The session-scoped service lifecycle that the lifecycle handler drives. */
+export interface ServiceLifecycle {
+  activate(ctx: ExtensionContext): void;
+  teardown(): void;
+}
+
+/**
+ * Owns the process-global service publication lifecycle for one extension
+ * instance.
+ *
+ * - `activate` publishes the service (skipped for registered subagent children
+ *   so they never clobber the parent's slot — see #302), then emits the ready
+ *   event.
+ * - `teardown` runs all session-scoped subscription cleanups in order, then
+ *   unpublishes the service.
+ */
+export class PermissionServiceLifecycle implements ServiceLifecycle {
+  constructor(
+    private readonly service: PermissionsService,
+    private readonly registry: SubagentSessionRegistry,
+    private readonly events: PermissionEventBus,
+    private readonly subscriptions: readonly (() => void)[],
+  ) {}
+
+  activate(ctx: ExtensionContext): void {
+    if (!isRegisteredSubagentChild(ctx, this.registry)) {
+      publishPermissionsService(this.service);
+    }
+    emitReadyEvent(this.events);
+  }
+
+  teardown(): void {
+    for (const unsubscribe of this.subscriptions) {
+      unsubscribe();
+    }
+    unpublishPermissionsService(this.service);
+  }
+}

package/src/session-approval-recorder.ts

@@ -0,0 +1,6 @@
+import type { SessionApproval } from "./session-approval";
+
+/** Records a granted session-scoped approval into the session ruleset. */
+export interface SessionApprovalRecorder {
+  recordSessionApproval(approval: SessionApproval): void;
+}

package/src/session-lifecycle-session.ts

@@ -0,0 +1,24 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import type { SessionLogger } from "./session-logger";
+
+/**
+ * The session surface `SessionLifecycleHandler` invokes across
+ * `session_start`, `resources_discover`, and `session_shutdown`: refresh and
+ * report config, reset / reload / shut down session state, resolve the agent
+ * name, surface config issues, read the runtime context, and log.
+ *
+ * `activate` is intentionally absent — the lifecycle handler never calls it
+ * directly (ISP: do not depend on methods you do not use).
+ */
+export interface SessionLifecycleSession {
+  refreshConfig(ctx?: ExtensionContext): void;
+  resetForNewSession(ctx: ExtensionContext): void;
+  logResolvedConfigPaths(): void;
+  resolveAgentName(ctx: ExtensionContext, systemPrompt?: string): string | null;
+  getConfigIssues(agentName?: string): string[];
+  reload(): void;
+  getRuntimeContext(): ExtensionContext | null;
+  shutdown(): void;
+  readonly logger: SessionLogger;
+}

package/src/tool-input-preview.ts

@@ -1,4 +1,3 @@
-import { getNonEmptyString, toRecord } from "./common";
 import { safeJsonStringify } from "./logging";
 
 export const TOOL_INPUT_PREVIEW_MAX_LENGTH = 200;
@@ -25,67 +24,6 @@ export function formatCount(
   return `${value} ${value === 1 ? singular : plural}`;
 }
 
-export function getPromptPath(input: Record<string, unknown>): string | null {
-  return getNonEmptyString(input.path) ?? getNonEmptyString(input.file_path);
-}
-
-export function formatEditInputForPrompt(
-  input: Record<string, unknown>,
-): string {
-  const path = getPromptPath(input);
-  const rawEdits = Array.isArray(input.edits)
-    ? input.edits
-    : typeof input.oldText === "string" && typeof input.newText === "string"
-      ? [{ oldText: input.oldText, newText: input.newText }]
-      : [];
-
-  const edits = rawEdits
-    .map((edit) => toRecord(edit))
-    .filter(
-      (edit) =>
-        typeof edit.oldText === "string" && typeof edit.newText === "string",
-    );
-
-  const pathPart = path ? `for '${path}'` : "";
-  if (edits.length === 0) {
-    return pathPart ? `${pathPart} with edit input` : "with edit input";
-  }
-
-  const firstEdit = edits[0];
-  const oldText = String(firstEdit.oldText);
-  const newText = String(firstEdit.newText);
-  const firstEditSummary = `edit #1 replaces ${formatCount(countTextLines(oldText), "line", "lines")} with ${formatCount(countTextLines(newText), "line", "lines")}`;
-  const extraEdits =
-    edits.length > 1
-      ? `, plus ${formatCount(edits.length - 1, "additional edit", "additional edits")}`
-      : "";
-  const summary = `(${formatCount(edits.length, "replacement", "replacements")}: ${firstEditSummary}${extraEdits})`;
-  return pathPart ? `${pathPart} ${summary}` : summary;
-}
-
-export function formatWriteInputForPrompt(
-  input: Record<string, unknown>,
-): string {
-  const path = getPromptPath(input);
-  const content = typeof input.content === "string" ? input.content : "";
-  const summary = `(${formatCount(countTextLines(content), "line", "lines")}, ${formatCount(content.length, "character", "characters")})`;
-  return path ? `for '${path}' ${summary}` : summary;
-}
-
-export function formatReadInputForPrompt(
-  input: Record<string, unknown>,
-): string {
-  const path = getPromptPath(input);
-  const parts = path ? [`path '${path}'`] : [];
-  if (typeof input.offset === "number") {
-    parts.push(`offset ${input.offset}`);
-  }
-  if (typeof input.limit === "number") {
-    parts.push(`limit ${input.limit}`);
-  }
-  return parts.length > 0 ? `for ${parts.join(", ")}` : "";
-}
-
 export function serializeToolInputPreview(input: unknown): string {
   const serialized = safeJsonStringify(input);
   if (!serialized || serialized === "{}" || serialized === "null") {