@gotgenes/pi-permission-system 20.0.0 → 20.1.0

package/CHANGELOG.md

@@ -5,6 +5,19 @@ 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).
 
+## [20.1.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v20.0.0...pi-permission-system-v20.1.0) (2026-07-08)
+
+
+### Features
+
+* **pi-permission-system:** gate win32 backslash-relative bash args via path rules ([#520](https://github.com/gotgenes/pi-packages/issues/520)) ([ad90fe5](https://github.com/gotgenes/pi-packages/commit/ad90fe568403a292afec52eaf75e9cb42e4db62c))
+* **pi-permission-system:** recognize win32 backslash-relative path tokens ([#520](https://github.com/gotgenes/pi-packages/issues/520)) ([343f331](https://github.com/gotgenes/pi-packages/commit/343f3318257df5358f6db7e447fd1de8f16a81b8))
+
+
+### Documentation
+
+* **pi-permission-system:** document win32 backslash-relative path recognition ([#520](https://github.com/gotgenes/pi-packages/issues/520)) ([b71d0b8](https://github.com/gotgenes/pi-packages/commit/b71d0b88fa8ee28eddfb4fc9796b7e15172d670a))
+
 ## [20.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v19.0.1...pi-permission-system-v20.0.0) (2026-07-07)
 
 

package/docs/configuration.md

@@ -363,6 +363,9 @@ When the current working directory is known, relative bash tokens are matched wi
 A bare filename with no path shape at all (e.g. `id_rsa` in `cat id_rsa`) is also gated when it matches an active, specific (non-`*`) `path` deny/ask rule — so `"id_rsa": "deny"` or `"*.pem": "deny"` blocks the file whether it is referenced by a bare name, a relative path, or the `read` tool.
 A bare token that matches no specific `path` rule (e.g. `status` in `git status`) is left alone, and this promotion never fires against a `"*"` catch-all — only a config that already declares a specific `path` rule is affected.
 
+On Windows, where a backslash is a path separator, a backslash-relative bash argument (e.g. `dir\file` in `cat dir\file`) is gated by a `path` rule the same as its forward-slash equivalent (`dir/file`) and the same as the file accessed through the `read` tool.
+On other platforms a backslash is a legal filename character, so such a token is not treated as a path.
+
 Four orthogonal layers compose with most-restrictive-wins:
 
 | Layer                   | Question                                | Applies to       |

package/package.json

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

package/src/access-intent/bash/bash-path-resolver.ts

@@ -426,6 +426,10 @@ export class BashPathResolver {
    * classifier (`classifyPromotedRuleCandidate`, #509) for a bare token the
    * broad classifier rejects for shape — promoted only when the injected
    * `isPromotablePathToken` predicate matches an active, specific `path` rule.
+   * On win32 the broad classifier is told to treat a backslash as a path
+   * separator, so a backslash-relative token (`dir\file`) is recognized as a
+   * rule candidate the same as its forward-slash equivalent (#520); on POSIX
+   * `\` is a legal filename character, so the token stays bare there.
    * Pairs each qualifying token with its set of policy values (absolute +
    * project-relative + raw).
    * A token after a non-literal `cd` keeps only its literal value so no
@@ -436,10 +440,11 @@ export class BashPathResolver {
   ): BashPathRuleCandidate[] {
     const seen = new Set<string>();
     const result: BashPathRuleCandidate[] = [];
+    const windowsSeparators = this.normalizer.usesWindowsSeparators();
 
     for (const { token, base } of candidates) {
       const candidate =
-        classifyTokenAsRuleCandidate(token) ??
+        classifyTokenAsRuleCandidate(token, { windowsSeparators }) ??
         classifyPromotedRuleCandidate(token, this.isPromotablePathToken);
       if (!candidate) continue;
 

package/src/access-intent/bash/token-classification.ts

@@ -18,6 +18,14 @@
  * gated by the `path` surface; on Windows the `PathNormalizer` routes it through
  * the absolute-path branch. Shape recognition is platform-independent string
  * matching; the platform-sensitive absoluteness decision belongs to `PathNormalizer`.
+ *
+ * `classifyTokenAsRuleCandidate` also accepts a `RuleCandidateOptions.windowsSeparators`
+ * flag: when `true`, a backslash-relative token (`dir\file`, no leading `.`, no
+ * `/`, no `..`, not a drive-letter absolute) is accepted as path-shaped (#520).
+ * This is the one genuinely platform-sensitive shape rule the classifier owns —
+ * on POSIX `\` is a legal filename character, so the caller (`BashPathResolver`)
+ * derives the flag from `PathNormalizer.usesWindowsSeparators()` rather than the
+ * classifier reading `process.platform` itself.
  */
 import type { PathRuleTokenMatcher } from "#src/types";
 
@@ -45,6 +53,19 @@ export function classifyTokenAsPathCandidate(token: string): string | null {
   return null;
 }
 
+/**
+ * Platform-sensitive options for {@link classifyTokenAsRuleCandidate}.
+ */
+export interface RuleCandidateOptions {
+  /**
+   * True when the host platform treats `\` as a path separator (win32), so a
+   * backslash-relative token (`dir\file`) is accepted as path-shaped (#520).
+   * On POSIX `\` is a legal filename character, so omit this (or pass
+   * `false`) to keep such a token bare.
+   */
+  readonly windowsSeparators?: boolean;
+}
+
 /**
  * Broader token classifier for cross-cutting `path` permission rules.
  *
@@ -52,6 +73,10 @@ export function classifyTokenAsPathCandidate(token: string): string | null {
  * - Dot-files and `./`-relative paths (starting with `.`)
  * - Any relative path containing `/` (e.g. `src/foo.ts`)
  * - Windows drive-letter absolute paths (`C:/…` or `C:\…`)
+ * - A backslash-relative token (`dir\file`) when `options.windowsSeparators`
+ *   is `true` (#520) — the caller (`BashPathResolver`) derives this from
+ *   `PathNormalizer.usesWindowsSeparators()` so the platform bit has a single
+ *   home; this classifier never reads `process.platform`.
  *
  * The `~/foo` case is covered by `includes("/")` — no separate `~/` branch needed.
  * The forward-slash drive form (`C:/…`) is also caught by `includes("/")`, but the
@@ -64,13 +89,17 @@ export function classifyTokenAsPathCandidate(token: string): string | null {
  *
  * Returns the raw token string if it qualifies, or `null` to skip.
  */
-export function classifyTokenAsRuleCandidate(token: string): string | null {
+export function classifyTokenAsRuleCandidate(
+  token: string,
+  options?: RuleCandidateOptions,
+): string | null {
   if (rejectNonPathToken(token)) return null;
 
   if (token.startsWith(".")) return token;
   if (token.includes("/")) return token; // covers ~/ paths and all relative paths with /
   if (token.includes("..")) return token; // bare ".." (no slash)
   if (WINDOWS_DRIVE_PATH_PATTERN.test(token)) return token; // backslash-only drive form
+  if (options?.windowsSeparators && token.includes("\\")) return token;
 
   return null;
 }

package/src/authority/approval-escalator.ts

@@ -18,12 +18,7 @@ import {
   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 type { PermissionPromptDecision } from "#src/permission-dialog";
 import {
   type ForwardedPermissionRequest,
   type ForwardedPromptDisplay,
@@ -33,31 +28,12 @@ import {
   resolvePermissionForwardingTargetSessionId,
   SUBAGENT_PARENT_SESSION_ENV_CANDIDATES,
 } from "#src/permission-forwarding";
+import { buildDirectUiPrompt } from "#src/permission-ui-prompt";
 import type { DebugReviewLogger } from "#src/session-logger";
 import type { SubagentSessionRegistry } from "#src/subagent-registry";
 import { toRecord } from "#src/value-guards";
-
-/**
- * Constructor config for `ApprovalEscalator`.
- *
- * Replaces the `PermissionForwardingDeps` interface that was previously
- * 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 ApprovalEscalatorDeps {
-  forwardingDir: string;
-  /** Single owner of subagent detection; gates the forward-vs-deny decision. */
-  detection: SubagentDetector;
-  /** In-process subagent session registry for forwarding target resolution. */
-  registry?: SubagentSessionRegistry;
-  logger: DebugReviewLogger;
-  requestPermissionDecisionFromUi: (
-    ui: PermissionDecisionUi,
-    title: string,
-    message: string,
-    options?: RequestPermissionOptions,
-  ) => Promise<PermissionPromptDecision>;
-}
+import type { Authorizer } from "./authorizer";
+import type { PromptPermissionDetails } from "./permission-prompter";
 
 // ── Module-private helpers ────────────────────────────────────────────────
 
@@ -82,82 +58,51 @@ function getContextSystemPrompt(ctx: ForwarderContext): string | undefined {
   }
 }
 
-// ── Public seam interfaces ────────────────────────────────────────────────
+// ── ParentAuthorizer ────────────────────────────────────────────────────
 
-/**
- * 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 `ApprovalEscalator`) keeps
- * the prompter's unit tests free of casts — they inject a plain
- * `{ requestApproval: vi.fn() }` mock.
- */
-export interface ApprovalRequester {
-  requestApproval(
-    ctx: ForwarderContext,
-    message: string,
-    options?: RequestPermissionOptions,
-    forwarded?: ForwardedPromptDisplay,
-  ): Promise<PermissionPromptDecision>;
+/** Constructor config for {@link ParentAuthorizer}. */
+export interface ParentAuthorizerDeps {
+  forwardingDir: string;
+  /** In-process subagent session registry for forwarding target resolution. */
+  registry?: SubagentSessionRegistry;
+  logger: DebugReviewLogger;
 }
 
-// ── ApprovalEscalator ────────────────────────────────────────────────
-
 /**
- * Owner of the escalation-up role of the forwarded-permission behavior.
+ * Authorizer for a subagent session: escalate the ask up the tree to the
+ * parent's authority.
  *
- * 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.
+ * Owns the escalation-up role of the forwarded-permission behavior: builds
+ * and persists a request file, then polls for the parent session's
+ * response. `ctx` is bound once at construction — `selectAuthorizer` only
+ * constructs a `ParentAuthorizer` for a context it has already confirmed has
+ * no UI and is a subagent, so `authorize` never re-derives that dispatch
+ * (formerly `ApprovalEscalator.requestApproval`'s `hasUI` / `!isSubagent`
+ * arms, both dead once every caller routes through `selectAuthorizer`).
  */
-export class ApprovalEscalator implements ApprovalRequester {
+export class ParentAuthorizer implements Authorizer {
   private readonly forwardingDir: string;
-  private readonly detection: SubagentDetector;
   private readonly registry: SubagentSessionRegistry | undefined;
   private readonly logger: DebugReviewLogger;
-  private readonly requestPermissionDecisionFromUi: (
-    ui: PermissionDecisionUi,
-    title: string,
-    message: string,
-    options?: RequestPermissionOptions,
-  ) => Promise<PermissionPromptDecision>;
 
-  constructor(deps: ApprovalEscalatorDeps) {
+  constructor(
+    private readonly ctx: ForwarderContext,
+    deps: ParentAuthorizerDeps,
+  ) {
     this.forwardingDir = deps.forwardingDir;
-    this.detection = deps.detection;
     this.registry = deps.registry;
     this.logger = deps.logger;
-    this.requestPermissionDecisionFromUi = deps.requestPermissionDecisionFromUi;
   }
 
-  // ── Public seam methods ────────────────────────────────────────────────
-
-  /**
-   * Resolve a permission decision for the current context: prompt directly
-   * when this session has UI, otherwise forward to the parent session.
-   */
-  requestApproval(
-    ctx: ForwarderContext,
-    message: string,
-    options?: RequestPermissionOptions,
-    forwarded?: ForwardedPromptDisplay,
+  authorize(
+    details: PromptPermissionDetails,
   ): Promise<PermissionPromptDecision> {
-    if (ctx.hasUI) {
-      return this.requestPermissionDecisionFromUi(
-        ctx.ui,
-        "Permission Required",
-        message,
-        options,
-      );
-    }
-
-    if (!this.detection.isSubagent(ctx)) {
-      return Promise.resolve({ approved: false, state: "denied" });
-    }
-
-    return this.waitForForwardedApproval(ctx, message, forwarded);
+    const uiPrompt = buildDirectUiPrompt(details);
+    return this.waitForForwardedApproval(this.ctx, details.message, {
+      source: uiPrompt.source,
+      surface: uiPrompt.surface,
+      value: uiPrompt.value,
+    });
   }
 
   // ── Private methods ────────────────────────────────────────────────────
@@ -170,7 +115,10 @@ export class ApprovalEscalator implements ApprovalRequester {
     const requesterSessionId = getSessionId(ctx);
     const targetSessionId = resolvePermissionForwardingTargetSessionId({
       hasUI: ctx.hasUI,
-      isSubagent: this.detection.isSubagent(ctx),
+      // Invariant: selectAuthorizer only selects ParentAuthorizer for a
+      // no-UI subagent context, so this is always true — no detection dep
+      // needed to re-derive it here.
+      isSubagent: true,
       currentSessionId: requesterSessionId,
       env: process.env,
       sessionId: requesterSessionId,

package/src/authority/authorizer-selection.ts

@@ -0,0 +1,87 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { GatePrompter } from "#src/gate-prompter";
+import type { PermissionPromptDecision } from "#src/permission-dialog";
+import {
+  type Authorizer,
+  type AuthorizerSelectionDeps,
+  selectAuthorizer,
+} from "./authorizer";
+import type {
+  PermissionPrompterApi,
+  PromptPermissionDetails,
+} from "./permission-prompter";
+
+/**
+ * The lifecycle slice of the selection owner that PermissionSession drives.
+ *
+ * PermissionSession calls activate/deactivate to keep the selection's stored
+ * context in sync with its own — the same pattern the former
+ * PromptingGatewayLifecycle used.
+ */
+export interface AuthorizerSelectionLifecycle {
+  activate(ctx: ExtensionContext): void;
+  deactivate(): void;
+}
+
+/**
+ * Context-owning selection root for the Authorizer spine.
+ *
+ * The rewrite of `PromptingGateway`: owns the stored `ExtensionContext`, runs
+ * `selectAuthorizer` once per activation, and implements `GatePrompter` by
+ * delegating to the selected `Authorizer` via `PermissionPrompter`.
+ *
+ * `canConfirm()` survives this step (dissolved in #556): it is recomputed
+ * transitionally alongside `selectAuthorizer`'s own branch, rather than
+ * derived from the selected authorizer, to keep the ask path byte-identical
+ * until #556 derives confirmability from a `DenyingAuthorizer` marker.
+ */
+export class AuthorizerSelection
+  implements GatePrompter, AuthorizerSelectionLifecycle
+{
+  private selected: Authorizer | null = null;
+  private confirmable = false;
+
+  constructor(
+    private readonly deps: AuthorizerSelectionDeps & {
+      prompter: PermissionPrompterApi;
+    },
+  ) {}
+
+  /** Select the Authorizer for `ctx` and store both it and the confirmable predicate. */
+  activate(ctx: ExtensionContext): void {
+    this.selected = selectAuthorizer(ctx, this.deps);
+    this.confirmable = ctx.hasUI || this.deps.detection.isSubagent(ctx);
+  }
+
+  /** Clear the stored selection. */
+  deactivate(): void {
+    this.selected = null;
+    this.confirmable = false;
+  }
+
+  /**
+   * Whether an interactive permission prompt can be shown.
+   *
+   * Returns false when no authorizer has been selected. Otherwise true when
+   * the context had UI or was a forwarding subagent at selection time — the
+   * two Authorizer-selection predicates, evaluated once at `activate`.
+   */
+  canConfirm(): boolean {
+    return this.selected !== null && this.confirmable;
+  }
+
+  /**
+   * Prompt for a permission decision using the selected authorizer.
+   *
+   * Rejects if no authorizer has been selected — `canConfirm()` guards this
+   * in normal use. Implements {@link GatePrompter}.
+   */
+  prompt(details: PromptPermissionDetails): Promise<PermissionPromptDecision> {
+    if (this.selected === null) {
+      return Promise.reject(
+        new Error("prompt called before the session was activated"),
+      );
+    }
+    return this.deps.prompter.prompt(this.selected, details);
+  }
+}

package/src/authority/authorizer.ts

@@ -0,0 +1,72 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type {
+  PermissionPromptDecision,
+  requestPermissionDecisionFromUi,
+} from "#src/permission-dialog";
+import type { PermissionEventBus } from "#src/permission-events";
+import type { DebugReviewLogger } from "#src/session-logger";
+import type { SubagentSessionRegistry } from "#src/subagent-registry";
+import { ParentAuthorizer } from "./approval-escalator";
+import { DenyingAuthorizer } from "./denying-authorizer";
+import { LocalUserAuthorizer } from "./local-user-authorizer";
+import type { PromptPermissionDetails } from "./permission-prompter";
+import type { SubagentDetector } from "./subagent-detection";
+
+/**
+ * The live-authority role: on `ask`, an `Authorizer` rules on a single
+ * request and is told the decision.
+ *
+ * One method, one responsibility. `DenyingAuthorizer` ignores `details`;
+ * `LocalUserAuthorizer` reads `message`/`sessionLabel` and derives the UI
+ * event from it; `ParentAuthorizer` reads `message` and derives the
+ * forwarded display from it.
+ */
+export interface Authorizer {
+  authorize(
+    details: PromptPermissionDetails,
+  ): Promise<PermissionPromptDecision>;
+}
+
+/** Construction inputs for {@link selectAuthorizer}. */
+export interface AuthorizerSelectionDeps {
+  /** Single owner of subagent detection; the ParentAuthorizer-selection predicate. */
+  detection: SubagentDetector;
+  /** Event bus used by `LocalUserAuthorizer` for the `permissions:ui_prompt` broadcast. */
+  events: PermissionEventBus;
+  /** Injected for testability; production callers pass the real function. */
+  requestPermissionDecisionFromUi: typeof requestPermissionDecisionFromUi;
+  /** Forwarding directory `ParentAuthorizer` reads/writes request and response files under. */
+  forwardingDir: string;
+  /** In-process subagent session registry for forwarding target resolution. */
+  registry?: SubagentSessionRegistry;
+  logger: DebugReviewLogger;
+}
+
+/**
+ * Select the `Authorizer` for the current context: the single owner of the
+ * three-way `hasUI` / `isSubagent` / deny dispatch.
+ *
+ * Evaluated once per session activation (`AuthorizerSelection.activate`),
+ * replacing the re-derivation of the same predicates across
+ * `PromptingGateway`, `PermissionPrompter`, and `ApprovalEscalator`.
+ */
+export function selectAuthorizer(
+  ctx: ExtensionContext,
+  deps: AuthorizerSelectionDeps,
+): Authorizer {
+  if (ctx.hasUI) {
+    return new LocalUserAuthorizer({
+      ui: ctx.ui,
+      events: deps.events,
+      requestPermissionDecisionFromUi: deps.requestPermissionDecisionFromUi,
+    });
+  }
+  if (deps.detection.isSubagent(ctx)) {
+    return new ParentAuthorizer(ctx, {
+      forwardingDir: deps.forwardingDir,
+      registry: deps.registry,
+      logger: deps.logger,
+    });
+  }
+  return new DenyingAuthorizer();
+}

package/src/authority/denying-authorizer.ts

@@ -0,0 +1,12 @@
+import type { PermissionPromptDecision } from "#src/permission-dialog";
+import type { Authorizer } from "./authorizer";
+
+/**
+ * Least-privilege Authorizer: no authority is reachable for this session
+ * (no UI, not a subagent), so every ask is denied.
+ */
+export class DenyingAuthorizer implements Authorizer {
+  authorize(): Promise<PermissionPromptDecision> {
+    return Promise.resolve({ approved: false, state: "denied" });
+  }
+}

package/src/authority/local-user-authorizer.ts

@@ -0,0 +1,46 @@
+import type {
+  PermissionDecisionUi,
+  PermissionPromptDecision,
+  requestPermissionDecisionFromUi,
+} from "#src/permission-dialog";
+import {
+  emitUiPromptEvent,
+  type PermissionEventBus,
+} from "#src/permission-events";
+import { buildDirectUiPrompt } from "#src/permission-ui-prompt";
+import type { Authorizer } from "./authorizer";
+import type { PromptPermissionDetails } from "./permission-prompter";
+
+/** Dependencies required by {@link LocalUserAuthorizer}. */
+export interface LocalUserAuthorizerDeps {
+  /** The active session's UI surface. */
+  ui: PermissionDecisionUi;
+  /** Event bus used for the `permissions:ui_prompt` broadcast. */
+  events: PermissionEventBus;
+  /** Injected for testability; production callers pass the real function. */
+  requestPermissionDecisionFromUi: typeof requestPermissionDecisionFromUi;
+}
+
+/**
+ * Authorizer for a session with an active UI: prompt the human here.
+ *
+ * Emits the `permissions:ui_prompt` broadcast (moved here from
+ * `PermissionPrompter`'s `ctx.hasUI` arm) before showing the dialog, so
+ * observers know a decision is imminent.
+ */
+export class LocalUserAuthorizer implements Authorizer {
+  constructor(private readonly deps: LocalUserAuthorizerDeps) {}
+
+  authorize(
+    details: PromptPermissionDetails,
+  ): Promise<PermissionPromptDecision> {
+    const uiPrompt = buildDirectUiPrompt(details);
+    emitUiPromptEvent(this.deps.events, uiPrompt);
+    return this.deps.requestPermissionDecisionFromUi(
+      this.deps.ui,
+      "Permission Required",
+      details.message,
+      details.sessionLabel ? { sessionLabel: details.sessionLabel } : undefined,
+    );
+  }
+}

package/src/{permission-prompter.ts → authority/permission-prompter.ts}

@@ -1,12 +1,6 @@
-import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import type { ApprovalRequester } from "./authority/approval-escalator";
-import type { PermissionPromptDecision } from "./permission-dialog";
-import {
-  emitUiPromptEvent,
-  type PermissionEventBus,
-} from "./permission-events";
-import { buildDirectUiPrompt } from "./permission-ui-prompt";
-import type { ReviewLogger } from "./session-logger";
+import type { PermissionPromptDecision } from "#src/permission-dialog";
+import type { ReviewLogger } from "#src/session-logger";
+import type { Authorizer } from "./authorizer";
 
 export type PermissionReviewSource = "tool_call" | "skill_input" | "skill_read";
 
@@ -27,72 +21,53 @@ export interface PromptPermissionDetails {
   sessionLabel?: string;
 }
 
-/** Mockable contract for permission prompting. */
+/**
+ * Narrow seam onto {@link PermissionPrompter}.
+ *
+ * Kept separate from the concrete class so consumers (e.g. `AuthorizerSelection`)
+ * can inject a plain `{ prompt: vi.fn() }` mock in tests — a private field on
+ * the concrete class would create a nominal brand that a structural mock
+ * cannot satisfy without a cast.
+ */
 export interface PermissionPrompterApi {
   prompt(
-    ctx: ExtensionContext,
+    authorizer: Authorizer,
     details: PromptPermissionDetails,
   ): Promise<PermissionPromptDecision>;
 }
 
-/**
- * Dependencies required by PermissionPrompter.
- *
- * Keeps the prompter's external surface narrow: callers provide a review
- * logger, the UI-prompt event bus, and the forwarder that owns the
- * UI/subagent-forwarding branching logic.
- */
+/** Dependencies required by {@link PermissionPrompter}. */
 export interface PermissionPrompterDeps {
   /** Write structured entries to the permission review log. */
   logger: ReviewLogger;
-  /** Event bus used for UI prompt broadcasts. */
-  events: PermissionEventBus;
-  /** Resolves the permission decision: direct UI dialog or forwarded to parent. */
-  forwarder: ApprovalRequester;
 }
 
 /**
- * Encapsulates the full permission-prompt flow:
+ * Brackets the ask-path flow with review-log entries and delegates the
+ * live decision to the selected {@link Authorizer}:
  *   1. Review-log "waiting" entry.
- *   2. UI-present vs. subagent-forwarding branching (via confirmPermission).
+ *   2. `authorizer.authorize(details)`.
  *   3. Review-log "approved" / "denied" entry.
  *
+ * The UI/forwarding branching this class previously owned now lives on the
+ * individual `Authorizer` implementations (`LocalUserAuthorizer`,
+ * `ParentAuthorizer`, `DenyingAuthorizer`) — this class no longer threads
+ * `ExtensionContext` per call.
+ *
  * Yolo-mode auto-approval happens upstream, at the composition stage
  * (`PermissionManager.check`'s `rewriteAsksToYolo`) — an `ask` never reaches
  * this class under yolo, so this class has no yolo-mode knowledge.
- *
- * Injecting a single PermissionPrompter instance means adding a new prompt
- * parameter (e.g. a future sessionLabel variant) only requires changing
- * PromptPermissionDetails and this class — not the full threading chain.
  */
 export class PermissionPrompter implements PermissionPrompterApi {
   constructor(private readonly deps: PermissionPrompterDeps) {}
 
   async prompt(
-    ctx: ExtensionContext,
+    authorizer: Authorizer,
     details: PromptPermissionDetails,
   ): Promise<PermissionPromptDecision> {
     this.writeReviewEntry("permission_request.waiting", details);
 
-    // 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,
-      details.sessionLabel ? { sessionLabel: details.sessionLabel } : undefined,
-      {
-        source: uiPrompt.source,
-        surface: uiPrompt.surface,
-        value: uiPrompt.value,
-      },
-    );
+    const decision = await authorizer.authorize(details);
 
     this.writeReviewEntry(
       decision.approved

package/src/authority/subagent-detection.ts

@@ -8,7 +8,7 @@ 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
+ * `selectAuthorizer`/`AuthorizerSelection` and `ForwardingManager` 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.
  */

package/src/config-loader.ts

@@ -14,7 +14,7 @@ import {
 } from "./config-schema";
 import { mergeFlatPermissions } from "./permission-merge";
 import type { FlatPermissionConfig, PatternValue } from "./types";
-import { isDenyWithReason, isPermissionState } from "./value-guards";
+import { isDenyWithReason, isPermissionState } from "./types";
 
 // The unified config shape is derived from the zod schema (config-schema.ts,
 // the single source of truth) and re-exported so existing importers keep their

package/src/gate-prompter.ts

@@ -1,5 +1,5 @@
+import type { PromptPermissionDetails } from "./authority/permission-prompter";
 import type { PermissionPromptDecision } from "./permission-dialog";
-import type { PromptPermissionDetails } from "./permission-prompter";
 
 /**
  * The prompting role the gate runner needs: a yes/no on whether an

package/src/handlers/gates/descriptor.ts

@@ -1,6 +1,6 @@
+import type { PromptPermissionDetails } from "#src/authority/permission-prompter";
 import type { DenialContext } from "#src/denial-messages";
 import type { PermissionDecisionEvent } from "#src/permission-events";
-import type { PromptPermissionDetails } from "#src/permission-prompter";
 import type { SessionApproval } from "#src/session-approval";
 import type { PermissionCheckResult, PermissionState } from "#src/types";
 

package/src/index.ts

@@ -1,13 +1,11 @@
 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 { AuthorizerSelection } from "./authority/authorizer-selection";
 import {
   ForwardedRequestServer,
   type ForwardedRequestServerDeps,
 } from "./authority/forwarded-request-server";
+import { PermissionPrompter } from "./authority/permission-prompter";
 import { SubagentDetection } from "./authority/subagent-detection";
 import { registerBuiltinToolInputFormatters } from "./builtin-tool-input-formatters";
 import { registerPermissionSystemCommand } from "./config-modal";
@@ -29,11 +27,9 @@ import { ToolCallGatePipeline } from "./handlers/gates/tool-call-gate-pipeline";
 import { createFailClosedToolCall } from "./handlers/tool-call-boundary";
 import { requestPermissionDecisionFromUi } from "./permission-dialog";
 import { PermissionManager } from "./permission-manager";
-import { PermissionPrompter } from "./permission-prompter";
 import { PermissionResolver } from "./permission-resolver";
 import { PermissionSession } from "./permission-session";
 import { LocalPermissionsService } from "./permissions-service";
-import { PromptingGateway } from "./prompting-gateway";
 import { PermissionServiceLifecycle } from "./service-lifecycle";
 import { PermissionSessionLogger } from "./session-logger";
 import { SessionRules } from "./session-rules";
@@ -94,15 +90,6 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
     logger,
   });
 
-  const escalatorDeps: ApprovalEscalatorDeps = {
-    forwardingDir: paths.forwardingDir,
-    detection: subagentDetection,
-    registry: subagentRegistry,
-    logger,
-    requestPermissionDecisionFromUi,
-  };
-  const escalator = new ApprovalEscalator(escalatorDeps);
-
   const requestServerDeps: ForwardedRequestServerDeps = {
     forwardingDir: paths.forwardingDir,
     logger,
@@ -112,14 +99,15 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
   };
   const requestServer = new ForwardedRequestServer(requestServerDeps);
 
-  const prompter = new PermissionPrompter({
-    logger,
-    events: pi.events,
-    forwarder: escalator,
-  });
+  const prompter = new PermissionPrompter({ logger });
 
-  const gateway = new PromptingGateway({
+  const authorizerSelection = new AuthorizerSelection({
     detection: subagentDetection,
+    events: pi.events,
+    requestPermissionDecisionFromUi,
+    forwardingDir: paths.forwardingDir,
+    registry: subagentRegistry,
+    logger,
     prompter,
   });
 
@@ -129,7 +117,7 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
     permissionManager,
     sessionRules,
     configStore,
-    gateway,
+    authorizerSelection,
     hostPlatform,
   );
 
@@ -196,7 +184,12 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
   const agentPrep = new AgentPrepHandler(session, resolver, toolRegistry);
 
   const reporter = new GateDecisionReporter(logger, pi.events);
-  const gateRunner = new GateRunner(resolver, sessionRules, gateway, reporter);
+  const gateRunner = new GateRunner(
+    resolver,
+    sessionRules,
+    authorizerSelection,
+    reporter,
+  );
   const toolCallGatePipeline = new ToolCallGatePipeline(
     resolver,
     session,

package/src/normalize.ts

@@ -1,6 +1,6 @@
 import type { Rule, Ruleset } from "./rule";
 import type { FlatPermissionConfig } from "./types";
-import { isDenyWithReason, isPermissionState } from "./value-guards";
+import { isDenyWithReason, isPermissionState } from "./types";
 
 /**
  * Convert a flat permission config into a Ruleset.

package/src/path-normalizer.ts

@@ -112,6 +112,18 @@ export class PathNormalizer {
     return this.impl.isAbsolute(pathValue);
   }
 
+  /**
+   * True when the host platform treats a backslash as a path separator (win32).
+   *
+   * The bash rule-candidate classifier reads this to decide whether a
+   * backslash-relative token (`dir\file`) is path-shaped: on win32 `\` is a
+   * separator, but on POSIX it is a legal filename character (#520). Keeping the
+   * decision here means no bash-layer module re-reads `process.platform`.
+   */
+  usesWindowsSeparators(): boolean {
+    return this.platform === "win32";
+  }
+
   /**
    * Interpret a literal `cd` target's effect on the effective base.
    *

package/src/permission-manager.ts

@@ -34,7 +34,7 @@ import type {
   PermissionCheckResult,
   PermissionState,
 } from "./types";
-import { isPermissionState } from "./value-guards";
+import { isPermissionState } from "./types";
 import { wildcardMatch } from "./wildcard-matcher";
 
 const BUILT_IN_TOOL_PERMISSION_NAMES = new Set([

package/src/permission-session.ts

@@ -3,7 +3,7 @@ import {
   getActiveAgentName,
   getActiveAgentNameFromSystemPrompt,
 } from "./active-agent";
-
+import type { AuthorizerSelectionLifecycle } from "./authority/authorizer-selection";
 import type { SessionConfigStore } from "./config-store";
 import type { PermissionSystemExtensionConfig } from "./extension-config";
 import type { ExtensionPaths } from "./extension-paths";
@@ -11,7 +11,6 @@ import type { ForwardingController } from "./forwarding-manager";
 import type { ToolCallGateInputs } from "./handlers/gates/tool-call-gate-pipeline";
 import { PathNormalizer } from "./path-normalizer";
 import type { ScopedPermissionManager } from "./permission-manager";
-import type { PromptingGatewayLifecycle } from "./prompting-gateway";
 
 import type { SessionRules } from "./session-rules";
 import type { SkillPromptEntry } from "./skill-prompt-sanitizer";
@@ -33,7 +32,7 @@ import type { PathRuleTokenMatcher } from "./types";
  * - `ExtensionPaths` — immutable path constants
  * - `ForwardingController` — polling lifecycle
  * - `SessionConfigStore` — owns extension config; provides refresh, log, read
- * - `PromptingGatewayLifecycle` — prompting lifecycle forwarded via activate/deactivate
+ * - `AuthorizerSelectionLifecycle` — authorizer-selection lifecycle forwarded via activate/deactivate
  */
 export class PermissionSession implements ToolCallGateInputs {
   private context: ExtensionContext | null = null;
@@ -47,7 +46,7 @@ export class PermissionSession implements ToolCallGateInputs {
     private readonly permissionManager: ScopedPermissionManager,
     private readonly sessionRules: SessionRules,
     private readonly configStore: SessionConfigStore,
-    private readonly gateway: PromptingGatewayLifecycle,
+    private readonly authorizerSelection: AuthorizerSelectionLifecycle,
     private readonly platform: NodeJS.Platform,
   ) {
     // Placeholder until the first activate(ctx) binds the real cwd; every gate
@@ -71,14 +70,14 @@ export class PermissionSession implements ToolCallGateInputs {
     this.context = ctx;
     this.pathNormalizer = new PathNormalizer(this.platform, ctx.cwd);
     this.forwarding.start(ctx);
-    this.gateway.activate(ctx);
+    this.authorizerSelection.activate(ctx);
   }
 
-  /** Clear the context, stop forwarding, and deactivate the gateway. */
+  /** Clear the context, stop forwarding, and deactivate the authorizer selection. */
   deactivate(): void {
     this.context = null;
     this.forwarding.stop();
-    this.gateway.deactivate();
+    this.authorizerSelection.deactivate();
   }
 
   /** Return the current runtime context, or null if not activated. */

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`, `ApprovalEscalator`, and `ForwardedRequestServer`.
+ * Injected into `ConfigStore`, `ParentAuthorizer`, and `ForwardedRequestServer`.
  */
 export interface DebugReviewLogger extends ReviewLogger {
   debug(event: string, details?: Record<string, unknown>): void;

package/src/types.ts

@@ -63,3 +63,23 @@ export interface PermissionCheckResult {
    */
   commandContext?: BashCommandContext;
 }
+
+export function isPermissionState(value: unknown): value is PermissionState {
+  return value === "allow" || value === "deny" || value === "ask";
+}
+
+/**
+ * Narrow type guard: a raw value representing a DenyWithReason object.
+ * Accepts `{ action: "deny" }` and `{ action: "deny", reason: "…" }`.
+ * Rejects a non-string `reason` to keep malformed config out of the rule set.
+ */
+export function isDenyWithReason(value: unknown): value is DenyWithReason {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return false;
+  }
+  const record = value as Record<string, unknown>;
+  return (
+    record.action === "deny" &&
+    (record.reason === undefined || typeof record.reason === "string")
+  );
+}

package/src/value-guards.ts

@@ -1,5 +1,3 @@
-import type { DenyWithReason, PermissionState } from "./types";
-
 export function toRecord(value: unknown): Record<string, unknown> {
   if (!value || typeof value !== "object" || Array.isArray(value)) {
     return {};
@@ -16,23 +14,3 @@ export function getNonEmptyString(value: unknown): string | null {
   const trimmed = value.trim();
   return trimmed.length > 0 ? trimmed : null;
 }
-
-export function isPermissionState(value: unknown): value is PermissionState {
-  return value === "allow" || value === "deny" || value === "ask";
-}
-
-/**
- * Narrow type guard: a raw value representing a DenyWithReason object.
- * Accepts `{ action: "deny" }` and `{ action: "deny", reason: "…" }`.
- * Rejects a non-string `reason` to keep malformed config out of the rule set.
- */
-export function isDenyWithReason(value: unknown): value is DenyWithReason {
-  if (typeof value !== "object" || value === null || Array.isArray(value)) {
-    return false;
-  }
-  const record = value as Record<string, unknown>;
-  return (
-    record.action === "deny" &&
-    (record.reason === undefined || typeof record.reason === "string")
-  );
-}

package/src/prompting-gateway.ts

@@ -1,89 +0,0 @@
-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";
-
-/**
- * Dependencies required by PromptingGateway.
- *
- * All fields are actively consumed:
- * - `detection` drives `canConfirm()`.
- * - `prompter` is called by `prompt()`.
- */
-export interface PromptingGatewayDeps {
-  /** Single owner of subagent detection; drives `canConfirm()`. */
-  detection: SubagentDetector;
-  /** Resolves the permission decision: direct UI dialog or forwarded to parent. */
-  prompter: PermissionPrompterApi;
-}
-
-/**
- * The lifecycle slice of the gateway that PermissionSession drives.
- *
- * PermissionSession calls activate/deactivate to keep the gateway's stored
- * context in sync with its own — the same pattern used for ForwardingController.
- */
-export interface PromptingGatewayLifecycle {
-  activate(ctx: ExtensionContext): void;
-  deactivate(): void;
-}
-
-/**
- * Context-owning implementation of the GatePrompter role.
- *
- * Owns the stored ExtensionContext and the "can we prompt?" policy
- * (UI / subagent), replacing the four twin methods that previously
- * lived on PermissionSession.
- *
- * Lifecycle: PermissionSession drives activate/deactivate so the stored
- * context mirrors the session context without independent call-site changes.
- */
-export class PromptingGateway
-  implements GatePrompter, PromptingGatewayLifecycle
-{
-  private context: ExtensionContext | null = null;
-
-  constructor(private readonly deps: PromptingGatewayDeps) {}
-
-  /** Store the current extension context. */
-  activate(ctx: ExtensionContext): void {
-    this.context = ctx;
-  }
-
-  /** Clear the stored context. */
-  deactivate(): void {
-    this.context = null;
-  }
-
-  /**
-   * Whether an interactive permission prompt can be shown.
-   *
-   * Returns false when no context is active. Otherwise true when the
-   * context has UI or is a forwarding subagent — the two Authorizer-
-   * selection predicates the Phase 9 spine will consume. Yolo-mode never
-   * reaches this policy: it is resolved upstream at the composition stage.
-   */
-  canConfirm(): boolean {
-    if (this.context === null) return false;
-    return this.context.hasUI || this.deps.detection.isSubagent(this.context);
-  }
-
-  /**
-   * Prompt the user for a permission decision using the stored context.
-   *
-   * Rejects if no context is active — canConfirm() guards this in normal use.
-   * Implements {@link GatePrompter}.
-   */
-  prompt(details: PromptPermissionDetails): Promise<PermissionPromptDecision> {
-    if (this.context === null) {
-      return Promise.reject(
-        new Error("prompt called before the session was activated"),
-      );
-    }
-    return this.deps.prompter.prompt(this.context, details);
-  }
-}