@gotgenes/pi-permission-system 19.0.1 → 20.1.0

package/CHANGELOG.md

@@ -5,6 +5,35 @@ 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)
+
+
+### ⚠ BREAKING CHANGES
+
+* **pi-permission-system:** The permissions:rpc:check and permissions:rpc:prompt event-bus channels are removed, along with their request/reply types (PermissionsCheckRequest, PermissionsCheckReplyData, PermissionsPromptRequest, PermissionsPromptReplyData), the PermissionsRpcReply envelope, PERMISSIONS_PROTOCOL_VERSION, and the rpc_prompt member of PermissionUiPromptSource. permissions:rpc:check consumers migrate to getPermissionsService().checkPermission(surface, value?, agentName?). permissions:rpc:prompt is removed with no public replacement; prompt forwarding is an internal subagent-to-parent mechanism.
+
+### Features
+
+* **pi-permission-system:** remove deprecated event-bus RPC channel ([557ea91](https://github.com/gotgenes/pi-packages/commit/557ea913c54f21ef64b0812169bbc7d5224072e2))
+
+
+### Documentation
+
+* **pi-permission-system:** repoint cross-extension docs off the removed RPC channel ([b3d06f7](https://github.com/gotgenes/pi-packages/commit/b3d06f77aea43758a4e820e66d1111608b86879b)), closes [#531](https://github.com/gotgenes/pi-packages/issues/531)
+
 ## [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)
 
 

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/docs/cross-extension-api.md

@@ -3,14 +3,14 @@
 The extension provides two cross-extension integration surfaces:
 
 1. **Service accessor** (preferred) — a `Symbol.for()`-backed synchronous API on `globalThis` for direct policy queries.
-2. **Event bus** — broadcasts and RPC on `pi.events` for observation and prompt forwarding.
+2. **Event bus** — broadcasts on `pi.events` for observation.
 
 ---
 
 ## Service Accessor
 
 The preferred way for other extensions to query the permission policy is the `Symbol.for()`-backed service accessor.
-It provides direct, synchronous, type-safe function calls — no async RPC envelope needed.
+It provides direct, synchronous, type-safe function calls.
 
 ### Quick Start
 
@@ -286,22 +286,17 @@ The extension also emits events on Pi's `pi.events` bus so other extensions can
 
 Fields may be added to any payload, but existing fields will not be removed or renamed without a semver-major version bump.
 The broadcast contract is defined by the published TypeScript types plus package semver — broadcast payloads (`permissions:ready`, `permissions:ui_prompt`, `permissions:decision`) carry no `protocolVersion`.
-The `PERMISSIONS_PROTOCOL_VERSION` constant is exported from `src/permission-events.ts` and embedded only in the RPC reply envelope, where per-call request/reply negotiation is load-bearing.
 Consumers should read broadcast payloads defensively (field-presence checks) rather than version-gating — that is robust to any shape skew between independently-versioned sibling extensions.
 
 All three broadcasts are best-effort: a throwing listener cannot block permission handling, session startup, or gate resolution.
 
 ## Channel Reference
 
-| Channel                                    | Direction | When                              | Payload type                                      |
-| ------------------------------------------ | --------- | --------------------------------- | ------------------------------------------------- |
-| `permissions:ready`                        | Broadcast | At `session_start`, after publish | `PermissionsReadyEvent`                           |
-| `permissions:ui_prompt`                    | Broadcast | Before active UI prompt           | `PermissionUiPromptEvent`                         |
-| `permissions:decision`                     | Broadcast | After every gate resolution       | `PermissionDecisionEvent`                         |
-| `permissions:rpc:check`                    | Request   | On-demand                         | `PermissionsCheckRequest`                         |
-| `permissions:rpc:check:reply:<requestId>`  | Reply     | After each check request          | `PermissionsRpcReply<PermissionsCheckReplyData>`  |
-| `permissions:rpc:prompt`                   | Request   | On-demand                         | `PermissionsPromptRequest`                        |
-| `permissions:rpc:prompt:reply:<requestId>` | Reply     | After prompt is resolved          | `PermissionsRpcReply<PermissionsPromptReplyData>` |
+| Channel                 | Direction | When                              | Payload type              |
+| ----------------------- | --------- | --------------------------------- | ------------------------- |
+| `permissions:ready`     | Broadcast | At `session_start`, after publish | `PermissionsReadyEvent`   |
+| `permissions:ui_prompt` | Broadcast | Before active UI prompt           | `PermissionUiPromptEvent` |
+| `permissions:decision`  | Broadcast | After every gate resolution       | `PermissionDecisionEvent` |
 
 ---
 
@@ -333,15 +328,15 @@ pi.events.on("permissions:ui_prompt", (raw) => {
 
 ### Payload Fields
 
-| Field        | Type                             | Description                                                                      |
-| ------------ | -------------------------------- | -------------------------------------------------------------------------------- |
-| `requestId`  | `string`                         | Unique ID for the permission request being prompted                              |
-| `source`     | `PermissionUiPromptSource`       | Prompt origin: `"tool_call"`, `"skill_input"`, `"skill_read"`, or `"rpc_prompt"` |
-| `surface`    | `string \| null`                 | Normalized display surface (e.g. `"bash"`, `"skill"`), when known                |
-| `value`      | `string \| null`                 | Normalized display value (command, path, skill name, etc.), when known           |
-| `agentName`  | `string \| null`                 | Active/requesting agent name, when known                                         |
-| `message`    | `string`                         | Message displayed in the permission prompt                                       |
-| `forwarding` | `ForwardedPromptContext \| null` | Forwarding context, or `null` for a direct prompt                                |
+| Field        | Type                             | Description                                                            |
+| ------------ | -------------------------------- | ---------------------------------------------------------------------- |
+| `requestId`  | `string`                         | Unique ID for the permission request being prompted                    |
+| `source`     | `PermissionUiPromptSource`       | Prompt origin: `"tool_call"`, `"skill_input"`, or `"skill_read"`       |
+| `surface`    | `string \| null`                 | Normalized display surface (e.g. `"bash"`, `"skill"`), when known      |
+| `value`      | `string \| null`                 | Normalized display value (command, path, skill name, etc.), when known |
+| `agentName`  | `string \| null`                 | Active/requesting agent name, when known                               |
+| `message`    | `string`                         | Message displayed in the permission prompt                             |
+| `forwarding` | `ForwardedPromptContext \| null` | Forwarding context, or `null` for a direct prompt                      |
 
 Forwarding is orthogonal to origin: a forwarded subagent prompt keeps its original `source` and is identified by a non-null `forwarding` field, not by a dedicated source value.
 
@@ -400,117 +395,13 @@ pi.events.on("permissions:decision", (raw) => {
 
 ---
 
-## Policy Query RPC (deprecated)
-
-> **Deprecated**: prefer the [Service Accessor](#service-accessor) above.
-> The event-bus RPC remains available as a zero-dependency fallback.
-
-Other extensions can evaluate the current permission policy without importing this package.
-The call is synchronous-style: emit a request, listen on a scoped reply channel.
-
-```typescript
-const requestId = crypto.randomUUID();
-
-// Listen for the reply first
-const unsub = pi.events.on(
-  `permissions:rpc:check:reply:${requestId}`,
-  (raw) => {
-    unsub();
-    const reply = raw as import("@gotgenes/pi-permission-system").PermissionsRpcReply<
-      import("@gotgenes/pi-permission-system").PermissionsCheckReplyData
-    >;
-    if (reply.success) {
-      console.log(reply.data?.result); // "allow" | "deny" | "ask"
-    }
-  },
-);
-
-// Then emit the request
-pi.events.emit("permissions:rpc:check", {
-  requestId,
-  surface: "bash",
-  value: "git push",
-  agentName: "Worker", // optional
-});
-```
-
-If the extension is not loaded, no reply arrives.
-Callers should implement a timeout and treat no-reply as `deny` (graceful degradation).
-
-### Request Fields
-
-| Field       | Required | Description                                                |
-| ----------- | -------- | ---------------------------------------------------------- |
-| `requestId` | Yes      | Unique string; scopes the reply channel                    |
-| `surface`   | Yes      | Permission surface to evaluate                             |
-| `value`     | No       | Value to evaluate (command, name, path); defaults to `"*"` |
-| `agentName` | No       | Agent name for per-agent policy resolution                 |
-
-As with the `checkPermission` service method, a path-shaped surface (`path`, `external_directory`, or a path-bearing tool) matches the `value` against both the path as given and its canonical (symlink-resolved) form.
-
-### Reply Data Fields (`PermissionsCheckReplyData`)
-
-| Field            | Type                         | Description                                      |
-| ---------------- | ---------------------------- | ------------------------------------------------ |
-| `result`         | `"allow" \| "deny" \| "ask"` | Policy decision (including active session rules) |
-| `matchedPattern` | `string \| null`             | Matched rule pattern                             |
-| `origin`         | `string \| null`             | Config scope of the winning rule                 |
-
----
-
-## Prompt Forwarding RPC
-
-In-process child sessions (e.g. tintinweb/pi-subagents running via `createAgentSession()`) cannot use file-based permission forwarding because no child process is spawned.
-They can instead forward permission prompts to the parent session's UI via this RPC.
-
-```typescript
-const requestId = crypto.randomUUID();
-
-const unsub = pi.events.on(
-  `permissions:rpc:prompt:reply:${requestId}`,
-  (raw) => {
-    unsub();
-    const reply = raw as import("@gotgenes/pi-permission-system").PermissionsRpcReply<
-      import("@gotgenes/pi-permission-system").PermissionsPromptReplyData
-    >;
-    if (reply.success && reply.data?.approved) {
-      // proceed
-    } else {
-      // deny — either user denied or no UI was available (error: "no_ui")
-    }
-  },
-);
-
-pi.events.emit("permissions:rpc:prompt", {
-  requestId,
-  surface: "bash",
-  value: "rm -rf /tmp/build",
-  message: "Allow rm -rf /tmp/build?",
-  agentName: "Explore",      // optional
-  sessionLabel: "Allow rm *", // optional — label for the "for this session" option
-});
-```
-
-The handler replies with `{ success: false, error: "no_ui" }` when no interactive session is available.
-
-### Successful Reply Fields
-
-| Field          | Type                | Description                                                                   |
-| -------------- | ------------------- | ----------------------------------------------------------------------------- |
-| `approved`     | `boolean`           | Whether the user approved                                                     |
-| `state`        | `string`            | `"approved"`, `"approved_for_session"`, `"denied"`, or `"denied_with_reason"` |
-| `denialReason` | `string` (optional) | User-provided denial reason                                                   |
-
----
-
 ## Ready Event
 
 The extension emits `permissions:ready` at `session_start`, right after the service is published — so a consumer reacting to it can immediately resolve `getPermissionsService()`.
 It fires once per `session_start` (including `/reload`).
-Consumers that start after the extension can check via a ping-style RPC check — the `permissions:rpc:check` handler is active as long as the extension is loaded.
 
 The payload is intentionally empty (`Record<string, never>`): the channel is a pure readiness signal.
-It carries no `protocolVersion` — version negotiation lives in the RPC reply envelope, and the broadcast contract is defined by the published types plus package semver.
+It carries no `protocolVersion` — the broadcast contract is defined by the published types plus package semver.
 
 ```typescript
 pi.events.on("permissions:ready", () => {

package/docs/guides/permission-frontmatter-for-subagent-extensions.md

@@ -127,61 +127,29 @@ The permission system handles all evaluation, prompt dialogs, and policy enforce
 
 ## Runtime Integration (Optional)
 
-If your extension runs subagents in-process (e.g. via `createAgentSession()`), you can optionally query the permission system's policy at runtime via the event bus API — no package import needed.
+If your extension runs subagents in-process (e.g. via `createAgentSession()`), you can optionally query the permission system's policy at runtime via the `Symbol.for()`-backed service accessor — no required peer dependency, just a dynamic `import()`.
 
 ### Querying policy
 
 ```typescript
-const requestId = crypto.randomUUID();
-
-pi.events.on(
-  `permissions:rpc:check:reply:${requestId}`,
-  (raw) => {
-    const reply = raw as { success: boolean; data?: { result: string } };
-    if (reply.success) {
-      console.log(reply.data?.result); // "allow" | "deny" | "ask"
-    }
-  },
-);
-
-pi.events.emit("permissions:rpc:check", {
-  requestId,
-  surface: "bash",
-  value: "git push",
-  agentName: "Worker",
-});
+try {
+  const { getPermissionsService } = await import(
+    "@gotgenes/pi-permission-system"
+  );
+  const permissions = getPermissionsService();
+  if (permissions) {
+    const result = permissions.checkPermission("bash", "git push", "Worker");
+    console.log(result.state); // "allow" | "deny" | "ask"
+  }
+} catch {
+  // Not installed — graceful degradation
+}
 ```
 
-### Forwarding permission prompts
+If `pi-permission-system` is not installed, `import()` throws; if it has not published a service yet (or has been unloaded), `getPermissionsService()` returns `undefined`.
+Guard both cases as shown above.
 
-When a child agent encounters an `ask` permission and has no UI, the prompt can be forwarded to the parent session:
-
-```typescript
-const requestId = crypto.randomUUID();
-
-pi.events.on(
-  `permissions:rpc:prompt:reply:${requestId}`,
-  (raw) => {
-    const reply = raw as { success: boolean; data?: { approved: boolean } };
-    if (reply.success && reply.data?.approved) {
-      // proceed
-    } else {
-      // deny
-    }
-  },
-);
-
-pi.events.emit("permissions:rpc:prompt", {
-  requestId,
-  surface: "bash",
-  value: "rm -rf /tmp/build",
-  message: "Allow rm -rf /tmp/build?",
-  agentName: "Worker",
-});
-```
-
-If `pi-permission-system` is not installed, no reply arrives.
-Implement a timeout and treat no-reply as `deny` for graceful degradation.
+Prompt forwarding for headless child agents is an internal subagent-to-parent mechanism, not a public cross-extension operation — there is no service-accessor equivalent to call directly.
 
 For full API documentation, see [Cross-extension API](../cross-extension-api.md).
 
@@ -191,11 +159,11 @@ For full API documentation, see [Cross-extension API](../cross-extension-api.md)
 2. **Unified config** — one `permission:` block per agent instead of separate restriction keys in multiple extensions.
 3. **Surface coverage** — policy covers bash patterns, MCP tools, skills, external directories, and special operations, not just tool names.
 4. **Forwarding** — permission prompts from headless child agents surface in the parent session's UI.
-5. **Programmatic access** — the event bus API lets your extension query policy at runtime without importing the package.
+5. **Programmatic access** — the `Symbol.for()` service accessor lets your extension query policy at runtime with only a dynamic `import()`, no required peer dependency.
 
 ## Further Reading
 
 - [Subagent Integration](../subagent-integration.md) — full coexistence documentation and interaction rules
-- [Cross-extension API](../cross-extension-api.md) — service accessor, event bus reference (decision broadcasts, RPC check, RPC prompt)
+- [Cross-extension API](../cross-extension-api.md) — service accessor, event bus reference (decision and UI-prompt broadcasts)
 - [Configuration](../configuration.md) — full policy reference including merge precedence
 - [Schema](../../schemas/permissions.schema.json) — canonical JSON Schema for the flat permission format

package/docs/guides/upstream-issue-template.md

@@ -31,7 +31,7 @@ This is purely a documentation change — no code dependency on pi-permission-sy
 - **Three-state policy**: `allow`, `ask` (prompt the user), or `deny` — richer than binary allow/deny
 - **Multiple surfaces**: tools, bash commands (glob patterns), MCP operations, skills, external directories
 - **Prompt forwarding**: `ask` decisions in headless child agents surface in the parent session's UI
-- **Event bus API**: other extensions can query policy at runtime without importing the package
+- **Service accessor API**: other extensions can query policy at runtime via a `Symbol.for()`-backed accessor, with only a dynamic `import()` and no required peer dependency
 
 ### Example
 
@@ -99,7 +99,7 @@ No code changes, no new dependency, no schema enforcement.
 | `{{your-key}}`       | `disallowed_tools` |
 | `{{example-value}}`  | `write_file,bash`  |
 
-Additional note for tintinweb: since this extension runs subagents in-process via `createAgentSession()`, mention the [Event Bus RPC](https://github.com/gotgenes/pi-permission-system/blob/main/docs/cross-extension-api.md#policy-query-rpc-deprecated) as an optional runtime integration path for querying or forwarding permission prompts without spawning a subprocess.
+Additional note for tintinweb: since this extension runs subagents in-process via `createAgentSession()`, mention the [service accessor](https://github.com/gotgenes/pi-permission-system/blob/main/docs/cross-extension-api.md#service-accessor) as an optional runtime integration path for querying policy without spawning a subprocess.
 
 ### HazAT/pi-interactive-subagents
 

package/docs/subagent-integration.md

@@ -29,7 +29,6 @@ The main interactive session polls for forwarded requests, shows the confirmatio
 This keeps `ask` policies usable even when the original permission check happens inside a non-UI execution context.
 
 For in-process child sessions, detection and forwarding use the event-driven registration described above.
-The [Prompt Forwarding RPC](cross-extension-api.md#prompt-forwarding-rpc) remains available as an alternative for extensions that cannot use the service accessor.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-permission-system",
-  "version": "19.0.1",
+  "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,