@gotgenes/pi-permission-system 19.0.0 → 20.0.0

package/src/authority/forwarded-request-server.ts

@@ -0,0 +1,285 @@
+import { join } from "node:path";
+import {
+  type ForwarderContext,
+  getSessionId,
+} from "#src/authority/forwarder-context";
+import type { ConfigReader } from "#src/config-store";
+import { isYoloModeEnabled } from "#src/extension-config";
+import type {
+  PermissionDecisionUi,
+  PermissionPromptDecision,
+  RequestPermissionOptions,
+} from "#src/permission-dialog";
+import {
+  emitUiPromptEvent,
+  type PermissionEventBus,
+} from "#src/permission-events";
+import {
+  type ForwardedPermissionRequest,
+  type ForwardedPermissionResponse,
+  isForwardedPermissionRequestForSession,
+  type PermissionForwardingLocation,
+} from "#src/permission-forwarding";
+import { buildForwardedUiPrompt } from "#src/permission-ui-prompt";
+import type { DebugReviewLogger } from "#src/session-logger";
+
+import {
+  cleanupPermissionForwardingLocationIfEmpty,
+  ensureDirectoryExists,
+  getExistingPermissionForwardingLocation,
+  listRequestFiles,
+  logPermissionForwardingError,
+  logPermissionForwardingWarning,
+  readForwardedPermissionRequest,
+  safeDeleteFile,
+  writeJsonFileAtomic,
+} from "./forwarding-io";
+
+/**
+ * Narrow seam describing what `ForwardingManager` needs from the server: a
+ * single method that drains this session's forwarded-permission inbox.
+ *
+ * Depending on the interface (not the concrete `ForwardedRequestServer`)
+ * keeps the manager's unit tests free of casts — they inject a plain
+ * `{ processInbox: vi.fn() }` mock.
+ */
+export interface InboxProcessor {
+  processInbox(ctx: ForwarderContext): Promise<void>;
+}
+
+/** Constructor config for `ForwardedRequestServer`. */
+export interface ForwardedRequestServerDeps {
+  forwardingDir: string;
+  logger: DebugReviewLogger;
+  /** Event bus used for UI prompt broadcasts. */
+  events?: PermissionEventBus;
+  requestPermissionDecisionFromUi: (
+    ui: PermissionDecisionUi,
+    title: string,
+    message: string,
+    options?: RequestPermissionOptions,
+  ) => Promise<PermissionPromptDecision>;
+  /** Read current config for the retained forwarded-inbox yolo auto-approve check. */
+  config: ConfigReader;
+}
+
+// ── Module-private helpers ────────────────────────────────────────────────
+
+function formatForwardedPermissionPrompt(
+  request: ForwardedPermissionRequest,
+): string {
+  const agentName = request.requesterAgentName || "unknown";
+  const sessionId = request.requesterSessionId || "unknown";
+  return [
+    `Subagent '${agentName}' requested permission.`,
+    `Session ID: ${sessionId}`,
+    "",
+    request.message,
+  ].join("\n");
+}
+
+// ── ForwardedRequestServer ────────────────────────────────────────────────
+
+/**
+ * Owner of the serving-down role of the forwarded-permission behavior:
+ * draining this session's forwarded-permission inbox and answering each
+ * request (auto-approve under yolo, or prompt via the injected UI).
+ */
+export class ForwardedRequestServer implements InboxProcessor {
+  private readonly forwardingDir: string;
+  private readonly events: PermissionEventBus | undefined;
+  private readonly logger: DebugReviewLogger;
+  private readonly requestPermissionDecisionFromUi: (
+    ui: PermissionDecisionUi,
+    title: string,
+    message: string,
+    options?: RequestPermissionOptions,
+  ) => Promise<PermissionPromptDecision>;
+  private readonly config: ConfigReader;
+
+  constructor(deps: ForwardedRequestServerDeps) {
+    this.forwardingDir = deps.forwardingDir;
+    this.events = deps.events;
+    this.logger = deps.logger;
+    this.requestPermissionDecisionFromUi = deps.requestPermissionDecisionFromUi;
+    this.config = deps.config;
+  }
+
+  /** Drain and respond to this session's forwarded-permission inbox. */
+  async processInbox(ctx: ForwarderContext): Promise<void> {
+    if (!ctx.hasUI) {
+      return;
+    }
+
+    const currentSessionId = getSessionId(ctx);
+    const location = getExistingPermissionForwardingLocation(
+      this.forwardingDir,
+      currentSessionId,
+    );
+    if (!location) {
+      return;
+    }
+
+    const requestFiles = listRequestFiles(this.logger, location.requestsDir);
+    if (requestFiles.length === 0) {
+      return;
+    }
+
+    // Defensively recreate responses/ before writing any response — a
+    // concurrent cleanup pass may have removed it between the requestsDir
+    // existence check above and the write inside processSingleForwardedRequest
+    // (the ENOENT write loop reported in issue #398).
+    if (
+      !ensureDirectoryExists(
+        this.logger,
+        location.responsesDir,
+        "permission forwarding responses",
+      )
+    ) {
+      return;
+    }
+
+    for (const fileName of requestFiles) {
+      const requestPath = join(location.requestsDir, fileName);
+      const request = readForwardedPermissionRequest(this.logger, requestPath);
+      if (!request) {
+        safeDeleteFile(
+          this.logger,
+          requestPath,
+          `${location.label} forwarded permission request`,
+        );
+        continue;
+      }
+
+      await this.processSingleForwardedRequest(
+        ctx,
+        request,
+        location,
+        requestPath,
+        currentSessionId,
+      );
+    }
+
+    cleanupPermissionForwardingLocationIfEmpty(this.logger, location);
+  }
+
+  // ── Private methods ────────────────────────────────────────────────────
+
+  private async processSingleForwardedRequest(
+    ctx: ForwarderContext,
+    request: ForwardedPermissionRequest,
+    location: PermissionForwardingLocation,
+    requestPath: string,
+    currentSessionId: string,
+  ): Promise<void> {
+    if (!isForwardedPermissionRequestForSession(request, currentSessionId)) {
+      logPermissionForwardingWarning(
+        this.logger,
+        `Ignoring forwarded permission request '${request.id}' because it targets session '${request.targetSessionId}' instead of '${currentSessionId}'`,
+      );
+      safeDeleteFile(
+        this.logger,
+        requestPath,
+        `${location.label} forwarded permission request`,
+      );
+      return;
+    }
+
+    const forwardedPermissionLogDetails = {
+      requestId: request.id,
+      source: location.label,
+      requesterAgentName: request.requesterAgentName,
+      requesterSessionId: request.requesterSessionId,
+      targetSessionId: request.targetSessionId,
+      requestPath,
+    };
+
+    let decision: PermissionPromptDecision = {
+      approved: false,
+      state: "denied",
+    };
+    // Last yolo check outside the composed ruleset: dissolves when
+    // processInbox is refactored onto evaluate() + Authorizer selection in
+    // the Phase 9 spine work.
+    if (isYoloModeEnabled(this.config.current())) {
+      this.logger.review(
+        "forwarded_permission.auto_approved",
+        forwardedPermissionLogDetails,
+      );
+      decision = { approved: true, state: "approved" };
+    } else {
+      this.logger.review(
+        "forwarded_permission.prompted",
+        forwardedPermissionLogDetails,
+      );
+      try {
+        const forwardedMessage = formatForwardedPermissionPrompt(request);
+        if (this.events) {
+          emitUiPromptEvent(
+            this.events,
+            buildForwardedUiPrompt({
+              requestId: request.id,
+              message: forwardedMessage,
+              requesterAgentName: request.requesterAgentName || null,
+              requesterSessionId: request.requesterSessionId || null,
+              source: request.source ?? null,
+              surface: request.surface ?? null,
+              value: request.value ?? null,
+            }),
+          );
+        }
+        decision = await this.requestPermissionDecisionFromUi(
+          ctx.ui,
+          "Permission Required (Subagent)",
+          forwardedMessage,
+        );
+      } catch (error) {
+        logPermissionForwardingError(
+          this.logger,
+          "Failed to show forwarded permission confirmation dialog",
+          error,
+        );
+        decision = { approved: false, state: "denied" };
+      }
+    }
+
+    const responsePath = join(location.responsesDir, `${request.id}.json`);
+    this.logger.review(
+      decision.approved
+        ? "forwarded_permission.approved"
+        : "forwarded_permission.denied",
+      {
+        requestId: request.id,
+        source: location.label,
+        requesterAgentName: request.requesterAgentName,
+        requesterSessionId: request.requesterSessionId,
+        targetSessionId: request.targetSessionId,
+        responsePath,
+        resolution: decision.state,
+        denialReason: decision.denialReason ?? null,
+      },
+    );
+    try {
+      writeJsonFileAtomic(this.logger, responsePath, {
+        approved: decision.approved,
+        state: decision.state,
+        denialReason: decision.denialReason,
+        responderSessionId: currentSessionId,
+        respondedAt: Date.now(),
+      } satisfies ForwardedPermissionResponse);
+    } catch (error) {
+      logPermissionForwardingError(
+        this.logger,
+        `Failed to write ${location.label} forwarded permission response '${responsePath}'`,
+        error,
+      );
+      return;
+    }
+
+    safeDeleteFile(
+      this.logger,
+      requestPath,
+      `${location.label} forwarded permission request`,
+    );
+  }
+}

package/src/authority/forwarder-context.ts

@@ -0,0 +1,32 @@
+import type { SessionEntryView } from "#src/active-agent";
+import type { PermissionDecisionUi } from "#src/permission-dialog";
+
+/**
+ * Narrow context the forwarding subsystem reads: the UI gate (`hasUI`), the
+ * dialog UI surface, and the three session-manager readers `getSessionId`
+ * and the `active-agent` helpers use.
+ *
+ * A full `ExtensionContext` satisfies this structurally, so production
+ * callers pass `ctx` unchanged.
+ */
+export interface ForwarderContext {
+  hasUI: boolean;
+  ui: PermissionDecisionUi;
+  sessionManager: {
+    getSessionId(): string;
+    getSessionDir(): string;
+    getEntries(): readonly SessionEntryView[];
+  };
+}
+
+/** Reads the current session id off `ctx`, falling back to `"unknown"`. */
+export function getSessionId(ctx: ForwarderContext): string {
+  try {
+    const sessionId = ctx.sessionManager.getSessionId();
+    if (typeof sessionId === "string" && sessionId.trim()) {
+      return sessionId.trim();
+    }
+  } catch {}
+
+  return "unknown";
+}

package/src/{forwarded-permissions/io.ts → authority/forwarding-io.ts}

@@ -24,7 +24,6 @@ const UI_PROMPT_SOURCES = [
   "tool_call",
   "skill_input",
   "skill_read",
-  "rpc_prompt",
 ] as const satisfies readonly PermissionUiPromptSource[];
 
 /** Narrow an unknown value to a valid prompt source, or `undefined`. */

package/src/{subagent-context.ts → authority/subagent-context.ts}

@@ -1,7 +1,7 @@
 import { posix as posixPath, win32 as winPath } from "node:path";
 
-import { SUBAGENT_ENV_HINT_KEYS } from "./permission-forwarding";
-import type { SubagentSessionRegistry } from "./subagent-registry";
+import { SUBAGENT_ENV_HINT_KEYS } from "#src/permission-forwarding";
+import type { SubagentSessionRegistry } from "#src/subagent-registry";
 
 /**
  * Narrow context for subagent detection — the only session-manager readers

package/src/authority/subagent-detection.ts

@@ -0,0 +1,65 @@
+import {
+  isRegisteredSubagentChild,
+  isSubagentExecutionContext,
+  type SubagentDetectionContext,
+} from "#src/authority/subagent-context";
+import type { SubagentSessionRegistry } from "#src/subagent-registry";
+
+/**
+ * Narrow seam for the ask-path consumers: "is the current session a subagent?"
+ *
+ * `PromptingGateway`, `ForwardingManager`, and `ApprovalEscalator` depend on
+ * this single-method view so their unit tests inject a one-field fake without
+ * casts. It is the Authorizer-selection predicate the Phase 9 spine consumes.
+ */
+export interface SubagentDetector {
+  isSubagent(ctx: SubagentDetectionContext): boolean;
+}
+
+/**
+ * Narrow seam for the service-publication guard (#302): "is the current
+ * session a registered in-process child?"
+ *
+ * `PermissionServiceLifecycle` depends on this single-method view so a
+ * registered child never publishes over its parent's process-global slot.
+ */
+export interface RegisteredChildDetector {
+  isRegisteredChild(ctx: SubagentDetectionContext): boolean;
+}
+
+/** Composition-root inputs for {@link SubagentDetection}. */
+export interface SubagentDetectionDeps {
+  subagentSessionsDir: string;
+  platform: NodeJS.Platform;
+  registry?: SubagentSessionRegistry;
+}
+
+/**
+ * Single owner of subagent detection.
+ *
+ * Constructed once in the composition root with the detection inputs
+ * (`subagentSessionsDir`, `platform`, `registry`) and shared across every
+ * consumer, replacing the dep triple those consumers previously threaded
+ * individually. Delegates to the pure detection functions in
+ * {@link ./subagent-context}, holding only the deps.
+ */
+export class SubagentDetection
+  implements SubagentDetector, RegisteredChildDetector
+{
+  constructor(private readonly deps: SubagentDetectionDeps) {}
+
+  isSubagent(ctx: SubagentDetectionContext): boolean {
+    return isSubagentExecutionContext(
+      ctx,
+      this.deps.subagentSessionsDir,
+      this.deps.platform,
+      this.deps.registry,
+    );
+  }
+
+  isRegisteredChild(ctx: SubagentDetectionContext): boolean {
+    return this.deps.registry
+      ? isRegisteredSubagentChild(ctx, this.deps.registry)
+      : false;
+  }
+}

package/src/forwarding-manager.ts

@@ -1,9 +1,7 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-
-import type { InboxProcessor } from "./forwarded-permissions/permission-forwarder";
+import type { InboxProcessor } from "./authority/forwarded-request-server";
+import type { SubagentDetector } from "./authority/subagent-detection";
 import { PERMISSION_FORWARDING_POLL_INTERVAL_MS } from "./permission-forwarding";
-import { isSubagentExecutionContext } from "./subagent-context";
-import type { SubagentSessionRegistry } from "./subagent-registry";
 
 /**
  * Narrow interface for the forwarding lifecycle used by `PermissionSession`.
@@ -28,10 +26,8 @@ export class ForwardingManager {
   private processing = false;
 
   constructor(
-    private readonly subagentSessionsDir: string,
+    private readonly detection: SubagentDetector,
     private readonly forwarder: InboxProcessor,
-    private readonly platform: NodeJS.Platform,
-    private readonly registry?: SubagentSessionRegistry,
   ) {}
 
   /**
@@ -41,15 +37,7 @@ export class ForwardingManager {
    * Stops any existing poll when the context does not qualify for forwarding.
    */
   start(ctx: ExtensionContext): void {
-    if (
-      !ctx.hasUI ||
-      isSubagentExecutionContext(
-        ctx,
-        this.subagentSessionsDir,
-        this.platform,
-        this.registry,
-      )
-    ) {
+    if (!ctx.hasUI || this.detection.isSubagent(ctx)) {
       this.stop();
       return;
     }

package/src/index.ts

@@ -1,5 +1,14 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { getAgentDir, getPackageDir } from "@earendil-works/pi-coding-agent";
+import {
+  ApprovalEscalator,
+  type ApprovalEscalatorDeps,
+} from "./authority/approval-escalator";
+import {
+  ForwardedRequestServer,
+  type ForwardedRequestServerDeps,
+} from "./authority/forwarded-request-server";
+import { SubagentDetection } from "./authority/subagent-detection";
 import { registerBuiltinToolInputFormatters } from "./builtin-tool-input-formatters";
 import { registerPermissionSystemCommand } from "./config-modal";
 import { getGlobalConfigPath } from "./config-paths";
@@ -8,10 +17,6 @@ import { DecisionAudit } from "./decision-audit";
 import { GateDecisionReporter } from "./decision-reporter";
 import { isYoloModeEnabled } from "./extension-config";
 import { computeExtensionPaths } from "./extension-paths";
-import {
-  PermissionForwarder,
-  type PermissionForwarderDeps,
-} from "./forwarded-permissions/permission-forwarder";
 import { ForwardingManager } from "./forwarding-manager";
 import {
   AgentPrepHandler,
@@ -23,7 +28,6 @@ import { SkillInputGatePipeline } from "./handlers/gates/skill-input-gate-pipeli
 import { ToolCallGatePipeline } from "./handlers/gates/tool-call-gate-pipeline";
 import { createFailClosedToolCall } from "./handlers/tool-call-boundary";
 import { requestPermissionDecisionFromUi } from "./permission-dialog";
-import { registerPermissionRpcHandlers } from "./permission-event-rpc";
 import { PermissionManager } from "./permission-manager";
 import { PermissionPrompter } from "./permission-prompter";
 import { PermissionResolver } from "./permission-resolver";
@@ -49,6 +53,13 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
   const hostPlatform = process.platform;
   const sessionRules = new SessionRules();
   const subagentRegistry = getSubagentSessionRegistry();
+  // Single owner of subagent detection, shared across every consumer instead of
+  // threading the (subagentSessionsDir, platform, registry) triple into each.
+  const subagentDetection = new SubagentDetection({
+    subagentSessionsDir: paths.subagentSessionsDir,
+    platform: hostPlatform,
+    registry: subagentRegistry,
+  });
   const formatterRegistry = new ToolInputFormatterRegistry();
   registerBuiltinToolInputFormatters(formatterRegistry);
   const accessExtractorRegistry = new ToolAccessExtractorRegistry();
@@ -83,39 +94,38 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
     logger,
   });
 
-  const forwardingDeps: PermissionForwarderDeps = {
+  const escalatorDeps: ApprovalEscalatorDeps = {
     forwardingDir: paths.forwardingDir,
-    subagentSessionsDir: paths.subagentSessionsDir,
-    platform: hostPlatform,
+    detection: subagentDetection,
     registry: subagentRegistry,
-    events: pi.events,
     logger,
     requestPermissionDecisionFromUi,
+  };
+  const escalator = new ApprovalEscalator(escalatorDeps);
+
+  const requestServerDeps: ForwardedRequestServerDeps = {
+    forwardingDir: paths.forwardingDir,
+    logger,
+    events: pi.events,
+    requestPermissionDecisionFromUi,
     config: configStore,
   };
-  const forwarder = new PermissionForwarder(forwardingDeps);
+  const requestServer = new ForwardedRequestServer(requestServerDeps);
 
   const prompter = new PermissionPrompter({
     logger,
     events: pi.events,
-    forwarder,
+    forwarder: escalator,
   });
 
   const gateway = new PromptingGateway({
-    subagentSessionsDir: paths.subagentSessionsDir,
-    platform: hostPlatform,
-    registry: subagentRegistry,
+    detection: subagentDetection,
     prompter,
   });
 
   session = new PermissionSession(
     paths,
-    new ForwardingManager(
-      paths.subagentSessionsDir,
-      forwarder,
-      hostPlatform,
-      subagentRegistry,
-    ),
+    new ForwardingManager(subagentDetection, requestServer),
     permissionManager,
     sessionRules,
     configStore,
@@ -139,17 +149,10 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
   });
 
   // Resolver composes the manager + session ruleset and owns the
-  // access-path → path-values unwrap; the RPC and service route their policy
-  // queries through it, so it is constructed before both.
+  // access-path → path-values unwrap; the service routes its policy
+  // queries through it, so it is constructed before it.
   const resolver = new PermissionResolver(permissionManager, sessionRules);
 
-  const rpcHandles = registerPermissionRpcHandlers(pi.events, {
-    resolver,
-    session,
-    requestPermissionDecisionFromUi,
-    logger,
-  });
-
   const permissionsService = new LocalPermissionsService(
     resolver,
     session,
@@ -171,9 +174,9 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
   // requires the session id from ctx, unavailable at factory-init time.
   const serviceLifecycle = new PermissionServiceLifecycle(
     permissionsService,
-    subagentRegistry,
+    subagentDetection,
     pi.events,
-    [rpcHandles.unsubCheck, rpcHandles.unsubPrompt, unsubSubagentLifecycle],
+    [unsubSubagentLifecycle],
   );
 
   const toolRegistry = {