@gotgenes/pi-permission-system 19.0.0 → 19.0.1

package/CHANGELOG.md

@@ -5,6 +5,13 @@ 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).
 
+## [19.0.1](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v19.0.0...pi-permission-system-v19.0.1) (2026-07-07)
+
+
+### Documentation
+
+* **pi-permission-system:** mark Phase 8 Step 6 complete; retarget forwarder docs ([c11d8a2](https://github.com/gotgenes/pi-packages/commit/c11d8a2653edbac3637e45c1e5c5867f0a882afe))
+
 ## [19.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v18.2.0...pi-permission-system-v19.0.0) (2026-07-06)
 
 

package/package.json

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

package/src/{forwarded-permissions/permission-forwarder.ts → authority/approval-escalator.ts}

@@ -3,86 +3,53 @@ import { join } from "node:path";
 import {
   getActiveAgentName,
   getActiveAgentNameFromSystemPrompt,
-  type SessionEntryView,
 } from "#src/active-agent";
-import type { ConfigReader } from "#src/config-store";
-import { isYoloModeEnabled } from "#src/extension-config";
+import {
+  type ForwarderContext,
+  getSessionId,
+} from "#src/authority/forwarder-context";
+import {
+  cleanupPermissionForwardingLocationIfEmpty,
+  ensurePermissionForwardingLocation,
+  logPermissionForwardingError,
+  logPermissionForwardingWarning,
+  readForwardedPermissionResponse,
+  safeDeleteFile,
+  sleep,
+  writeJsonFileAtomic,
+} from "#src/authority/forwarding-io";
+import type { SubagentDetector } from "#src/authority/subagent-detection";
 import type {
   PermissionDecisionUi,
   PermissionPromptDecision,
   RequestPermissionOptions,
 } from "#src/permission-dialog";
-import {
-  emitUiPromptEvent,
-  type PermissionEventBus,
-} from "#src/permission-events";
 import {
   type ForwardedPermissionRequest,
-  type ForwardedPermissionResponse,
   type ForwardedPromptDisplay,
-  isForwardedPermissionRequestForSession,
   PERMISSION_FORWARDING_POLL_INTERVAL_MS,
   PERMISSION_FORWARDING_TIMEOUT_MS,
   type PermissionForwardingLocation,
   resolvePermissionForwardingTargetSessionId,
   SUBAGENT_PARENT_SESSION_ENV_CANDIDATES,
 } from "#src/permission-forwarding";
-import { buildForwardedUiPrompt } from "#src/permission-ui-prompt";
 import type { DebugReviewLogger } from "#src/session-logger";
-import { isSubagentExecutionContext } from "#src/subagent-context";
 import type { SubagentSessionRegistry } from "#src/subagent-registry";
 import { toRecord } from "#src/value-guards";
 
-import {
-  cleanupPermissionForwardingLocationIfEmpty,
-  ensureDirectoryExists,
-  ensurePermissionForwardingLocation,
-  getExistingPermissionForwardingLocation,
-  listRequestFiles,
-  logPermissionForwardingError,
-  logPermissionForwardingWarning,
-  readForwardedPermissionRequest,
-  readForwardedPermissionResponse,
-  safeDeleteFile,
-  sleep,
-  writeJsonFileAtomic,
-} from "./io";
-
-/**
- * Narrow context the forwarder reads: the UI gate (`hasUI`), the dialog UI
- * surface, and the three session-manager readers it uses directly or via
- * {@link isSubagentExecutionContext} / {@link getActiveAgentName}.
- *
- * `getSystemPrompt` is read reflectively (see `getContextSystemPrompt`), so it
- * is intentionally not a typed member. 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[];
-  };
-}
-
 /**
- * Constructor config for `PermissionForwarder`.
+ * Constructor config for `ApprovalEscalator`.
  *
  * Replaces the `PermissionForwardingDeps` interface that was previously
- * threaded into free functions in `polling.ts`.  The forwarder consumes it
+ * threaded into free functions in `polling.ts`.  The escalator consumes it
  * once at construction and stores each member as a private readonly field.
  */
-export interface PermissionForwarderDeps {
+export interface ApprovalEscalatorDeps {
   forwardingDir: string;
-  subagentSessionsDir: string;
-  /** Host platform, injected from the composition root, for subagent-context path detection. */
-  platform: NodeJS.Platform;
-  /** In-process subagent session registry for detection and forwarding target resolution. */
+  /** Single owner of subagent detection; gates the forward-vs-deny decision. */
+  detection: SubagentDetector;
+  /** In-process subagent session registry for forwarding target resolution. */
   registry?: SubagentSessionRegistry;
-  /** Event bus used for UI prompt broadcasts. */
-  events?: PermissionEventBus;
   logger: DebugReviewLogger;
   requestPermissionDecisionFromUi: (
     ui: PermissionDecisionUi,
@@ -90,23 +57,10 @@ export interface PermissionForwarderDeps {
     message: string,
     options?: RequestPermissionOptions,
   ) => Promise<PermissionPromptDecision>;
-  /** Read current config for the retained forwarded-inbox yolo auto-approve check. */
-  config: ConfigReader;
 }
 
 // ── Module-private helpers ────────────────────────────────────────────────
 
-function getSessionId(ctx: ForwarderContext): string {
-  try {
-    const sessionId = ctx.sessionManager.getSessionId();
-    if (typeof sessionId === "string" && sessionId.trim()) {
-      return sessionId.trim();
-    }
-  } catch {}
-
-  return "unknown";
-}
-
 function getContextSystemPrompt(ctx: ForwarderContext): string | undefined {
   const getSystemPrompt = toRecord(ctx).getSystemPrompt;
   if (typeof getSystemPrompt !== "function") {
@@ -128,27 +82,14 @@ function getContextSystemPrompt(ctx: ForwarderContext): string | undefined {
   }
 }
 
-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");
-}
-
 // ── Public seam interfaces ────────────────────────────────────────────────
 
 /**
- * Narrow seam describing what `PermissionPrompter` needs from the forwarder:
+ * Narrow seam describing what `PermissionPrompter` needs from the escalator:
  * a single method that resolves a permission decision for the current context
  * (prompt directly when the session has UI, otherwise forward to the parent).
  *
- * Depending on the interface (not the concrete `PermissionForwarder`) keeps
+ * Depending on the interface (not the concrete `ApprovalEscalator`) keeps
  * the prompter's unit tests free of casts — they inject a plain
  * `{ requestApproval: vi.fn() }` mock.
  */
@@ -161,35 +102,20 @@ export interface ApprovalRequester {
   ): Promise<PermissionPromptDecision>;
 }
 
-/**
- * Narrow seam describing what `ForwardingManager` needs from the forwarder:
- * a single method that drains this session's forwarded-permission inbox.
- *
- * Depending on the interface (not the concrete `PermissionForwarder`) 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>;
-}
-
-// ── PermissionForwarder ───────────────────────────────────────────────────
+// ── ApprovalEscalator ────────────────────────────────────────────────
 
 /**
- * Owner of the forwarded-permission behavior.
+ * Owner of the escalation-up role of the forwarded-permission behavior.
  *
- * Holds all forwarding state as private readonly fields and provides two
- * public methods (`requestApproval`, `processInbox`) that together encapsulate
- * the full forwarding lifecycle: deciding whether to prompt directly or
- * forward to the parent, building and persisting request files, polling for
- * responses, and processing the parent-session inbox.
+ * Holds all forwarding state as private readonly fields and provides the
+ * public `requestApproval` method: deciding whether to prompt directly or
+ * forward to the parent, building and persisting request files, and polling
+ * for responses.
  */
-export class PermissionForwarder implements ApprovalRequester, InboxProcessor {
+export class ApprovalEscalator implements ApprovalRequester {
   private readonly forwardingDir: string;
-  private readonly subagentSessionsDir: string;
-  private readonly platform: NodeJS.Platform;
+  private readonly detection: SubagentDetector;
   private readonly registry: SubagentSessionRegistry | undefined;
-  private readonly events: PermissionEventBus | undefined;
   private readonly logger: DebugReviewLogger;
   private readonly requestPermissionDecisionFromUi: (
     ui: PermissionDecisionUi,
@@ -197,17 +123,13 @@ export class PermissionForwarder implements ApprovalRequester, InboxProcessor {
     message: string,
     options?: RequestPermissionOptions,
   ) => Promise<PermissionPromptDecision>;
-  private readonly config: ConfigReader;
 
-  constructor(deps: PermissionForwarderDeps) {
+  constructor(deps: ApprovalEscalatorDeps) {
     this.forwardingDir = deps.forwardingDir;
-    this.subagentSessionsDir = deps.subagentSessionsDir;
-    this.platform = deps.platform;
+    this.detection = deps.detection;
     this.registry = deps.registry;
-    this.events = deps.events;
     this.logger = deps.logger;
     this.requestPermissionDecisionFromUi = deps.requestPermissionDecisionFromUi;
-    this.config = deps.config;
   }
 
   // ── Public seam methods ────────────────────────────────────────────────
@@ -231,78 +153,13 @@ export class PermissionForwarder implements ApprovalRequester, InboxProcessor {
       );
     }
 
-    if (
-      !isSubagentExecutionContext(
-        ctx,
-        this.subagentSessionsDir,
-        this.platform,
-        this.registry,
-      )
-    ) {
+    if (!this.detection.isSubagent(ctx)) {
       return Promise.resolve({ approved: false, state: "denied" });
     }
 
     return this.waitForForwardedApproval(ctx, message, forwarded);
   }
 
-  /** 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 waitForForwardedApproval(
@@ -313,12 +170,7 @@ export class PermissionForwarder implements ApprovalRequester, InboxProcessor {
     const requesterSessionId = getSessionId(ctx);
     const targetSessionId = resolvePermissionForwardingTargetSessionId({
       hasUI: ctx.hasUI,
-      isSubagent: isSubagentExecutionContext(
-        ctx,
-        this.subagentSessionsDir,
-        this.platform,
-        this.registry,
-      ),
+      isSubagent: this.detection.isSubagent(ctx),
       currentSessionId: requesterSessionId,
       env: process.env,
       sessionId: requesterSessionId,
@@ -472,122 +324,4 @@ export class PermissionForwarder implements ApprovalRequester, InboxProcessor {
     cleanupPermissionForwardingLocationIfEmpty(this.logger, location);
     return { approved: false, state: "denied" };
   }
-
-  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/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/{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,
@@ -49,6 +54,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 +95,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,
@@ -171,7 +182,7 @@ 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],
   );

package/src/permission-prompter.ts

@@ -1,5 +1,5 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import type { ApprovalRequester } from "./forwarded-permissions/permission-forwarder";
+import type { ApprovalRequester } from "./authority/approval-escalator";
 import type { PermissionPromptDecision } from "./permission-dialog";
 import {
   emitUiPromptEvent,

package/src/prompting-gateway.ts

@@ -1,28 +1,22 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-
+import type { SubagentDetector } from "./authority/subagent-detection";
 import type { GatePrompter } from "./gate-prompter";
 import type { PermissionPromptDecision } from "./permission-dialog";
 import type {
   PermissionPrompterApi,
   PromptPermissionDetails,
 } from "./permission-prompter";
-import { isSubagentExecutionContext } from "./subagent-context";
-import type { SubagentSessionRegistry } from "./subagent-registry";
 
 /**
  * Dependencies required by PromptingGateway.
  *
  * All fields are actively consumed:
- * - `subagentSessionsDir` + `registry` drive `canConfirm()`.
+ * - `detection` drives `canConfirm()`.
  * - `prompter` is called by `prompt()`.
  */
 export interface PromptingGatewayDeps {
-  /** Static path used to detect a forwarding subagent context. */
-  subagentSessionsDir: string;
-  /** Host platform, injected from the composition root, for subagent-context path detection. */
-  platform: NodeJS.Platform;
-  /** Process-global registry used to detect a registered child session. */
-  registry?: SubagentSessionRegistry;
+  /** Single owner of subagent detection; drives `canConfirm()`. */
+  detection: SubagentDetector;
   /** Resolves the permission decision: direct UI dialog or forwarded to parent. */
   prompter: PermissionPrompterApi;
 }
@@ -75,15 +69,7 @@ export class PromptingGateway
    */
   canConfirm(): boolean {
     if (this.context === null) return false;
-    return (
-      this.context.hasUI ||
-      isSubagentExecutionContext(
-        this.context,
-        this.deps.subagentSessionsDir,
-        this.deps.platform,
-        this.deps.registry,
-      )
-    );
+    return this.context.hasUI || this.deps.detection.isSubagent(this.context);
   }
 
   /**

package/src/service-lifecycle.ts

@@ -1,13 +1,11 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-
+import type { RegisteredChildDetector } from "./authority/subagent-detection";
 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 {
@@ -28,13 +26,13 @@ export interface ServiceLifecycle {
 export class PermissionServiceLifecycle implements ServiceLifecycle {
   constructor(
     private readonly service: PermissionsService,
-    private readonly registry: SubagentSessionRegistry,
+    private readonly detection: RegisteredChildDetector,
     private readonly events: PermissionEventBus,
     private readonly subscriptions: readonly (() => void)[],
   ) {}
 
   activate(ctx: ExtensionContext): void {
-    if (!isRegisteredSubagentChild(ctx, this.registry)) {
+    if (!this.detection.isRegisteredChild(ctx)) {
       publishPermissionsService(this.service);
     }
     emitReadyEvent(this.events);

package/src/session-logger.ts

@@ -19,7 +19,7 @@ export interface ReviewLogger {
 
 /**
  * Logging seam for consumers that write both debug and review entries.
- * Injected into `ConfigStore` and `PermissionForwarder`.
+ * Injected into `ConfigStore`, `ApprovalEscalator`, and `ForwardedRequestServer`.
  */
 export interface DebugReviewLogger extends ReviewLogger {
   debug(event: string, details?: Record<string, unknown>): void;