@gotgenes/pi-permission-system 20.0.0 → 20.2.0

package/CHANGELOG.md

@@ -5,6 +5,31 @@ 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.2.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v20.1.0...pi-permission-system-v20.2.0) (2026-07-09)
+
+
+### Features
+
+* **pi-permission-system:** serve forwarded permissions by resolution and Authorizer escalation ([#557](https://github.com/gotgenes/pi-packages/issues/557)) ([c5d3bcb](https://github.com/gotgenes/pi-packages/commit/c5d3bcbf4e69a568f750d6a7c0619d4b88d5b377))
+
+
+### Documentation
+
+* **pi-permission-system:** mark Phase 9 Step 3 complete ([a5a348f](https://github.com/gotgenes/pi-packages/commit/a5a348f3d3dc1835e64ecd7b6b0c1b6164085a97))
+
+## [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/docs/cross-extension-api.md

@@ -307,7 +307,8 @@ This event is for integrations such as notification extensions that should alert
 It is not a generic "permission request entered waiting state" event, and it does not imply the prompt will be approved.
 Policy decisions that resolve without an active UI prompt, such as `policy_allow`, `policy_deny`, `session_approved`, `infrastructure_auto_allowed`, or `auto_approved`, do not emit this event.
 Non-UI child sessions also do not emit this event when they create a forwarded permission request; the parent UI session emits it immediately before showing the forwarded permission dialog.
-Forwarded prompts are not degraded: the parent emits the child's original `source` and the same `surface`/`value` display projection, plus a populated `forwarding` context identifying the requesting subagent.
+A forwarded request the parent's own recorded policy decides (a matching `allow` or `deny`) is answered without a prompt and emits no event; the event fires only when the parent is actually about to ask the human.
+Forwarded prompts that do reach the human are not degraded: the parent emits the child's original `source` and the same `surface`/`value` display projection, plus a populated `forwarding` context identifying the requesting subagent.
 
 The payload is lean by design — `surface`/`value` are the normalized display projection a notification consumer reads, not a mirror of the internal review log.
 Read defensively rather than version-gating: broadcast payloads carry no `protocolVersion`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-permission-system",
-  "version": "20.0.0",
+  "version": "20.2.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 { buildUiPrompt } 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 = buildUiPrompt(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,86 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+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;
+}
+
+/**
+ * The ask-escalation seam `GateRunner` depends on: escalate a single ask to
+ * the session's selected `Authorizer` and return its decision.
+ *
+ * Replaces the two-method `GatePrompter` role (#556). There is no
+ * "can anyone answer" pre-check: absent authority is the `DenyingAuthorizer`,
+ * which answers by denying with a `confirmationUnavailable` marker.
+ */
+export interface AskEscalator {
+  escalate(details: PromptPermissionDetails): Promise<PermissionPromptDecision>;
+}
+
+/**
+ * Context-owning selection root for the Authorizer spine.
+ *
+ * The rewrite of `PromptingGateway`: owns the stored `ExtensionContext`, runs
+ * `selectAuthorizer` once per activation, and implements `AskEscalator` by
+ * delegating to the selected `Authorizer` via `PermissionPrompter`.
+ *
+ * `selectAuthorizer` encodes the liveness decision in *which* `Authorizer` it
+ * returns (`LocalUserAuthorizer` / `ParentAuthorizer` when authority is
+ * reachable, `DenyingAuthorizer` otherwise), so no separate confirmability
+ * predicate survives (#556 dissolved `canConfirm()`).
+ */
+export class AuthorizerSelection
+  implements AskEscalator, AuthorizerSelectionLifecycle
+{
+  private selected: Authorizer | null = null;
+
+  constructor(
+    private readonly deps: AuthorizerSelectionDeps & {
+      prompter: PermissionPrompterApi;
+    },
+  ) {}
+
+  /** Select the Authorizer for `ctx` and store it. */
+  activate(ctx: ExtensionContext): void {
+    this.selected = selectAuthorizer(ctx, this.deps);
+  }
+
+  /** Clear the stored selection. */
+  deactivate(): void {
+    this.selected = null;
+  }
+
+  /**
+   * Escalate an ask to the selected authorizer and return its decision.
+   *
+   * Rejects if no authorizer has been selected — i.e. before the session was
+   * activated. Implements {@link AskEscalator}.
+   */
+  escalate(
+    details: PromptPermissionDetails,
+  ): Promise<PermissionPromptDecision> {
+    if (this.selected === null) {
+      return Promise.reject(
+        new Error("escalate 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,20 @@
+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.
+ *
+ * The denial carries the `confirmationUnavailable` marker so the ask path can
+ * distinguish "nobody could answer" from an interactive user denial when it
+ * derives the review-entry and decision-event resolution.
+ */
+export class DenyingAuthorizer implements Authorizer {
+  authorize(): Promise<PermissionPromptDecision> {
+    return Promise.resolve({
+      approved: false,
+      state: "denied",
+      confirmationUnavailable: true,
+    });
+  }
+}