@gotgenes/pi-permission-system 20.0.0 → 20.2.0

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,
+  type ServingPolicy,
 } 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";
@@ -27,13 +25,12 @@ import { GateRunner } from "./handlers/gates/runner";
 import { SkillInputGatePipeline } from "./handlers/gates/skill-input-gate-pipeline";
 import { ToolCallGatePipeline } from "./handlers/gates/tool-call-gate-pipeline";
 import { createFailClosedToolCall } from "./handlers/tool-call-boundary";
+import { buildAccessIntentForSurface } from "./input-normalizer";
 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,33 +91,48 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
     logger,
   });
 
-  const escalatorDeps: ApprovalEscalatorDeps = {
-    forwardingDir: paths.forwardingDir,
+  const prompter = new PermissionPrompter({ logger });
+
+  const authorizerSelection = new AuthorizerSelection({
     detection: subagentDetection,
-    registry: subagentRegistry,
-    logger,
+    events: pi.events,
     requestPermissionDecisionFromUi,
-  };
-  const escalator = new ApprovalEscalator(escalatorDeps);
-
-  const requestServerDeps: ForwardedRequestServerDeps = {
     forwardingDir: paths.forwardingDir,
+    registry: subagentRegistry,
     logger,
-    events: pi.events,
-    requestPermissionDecisionFromUi,
-    config: configStore,
+    prompter,
+  });
+
+  // Resolver composes the manager + session ruleset and owns the
+  // access-path → path-values unwrap. Constructed here (before `session`) so
+  // the forwarded-request server's ServingPolicy can resolve against it; the
+  // service and gates below share this one instance.
+  const resolver = new PermissionResolver(permissionManager, sessionRules);
+
+  // Serving a forwarded request is resolution: evaluate (surface, value)
+  // against the serving node's composed base ruleset (agentName undefined —
+  // the child already applied its own per-agent overrides before forwarding).
+  // The session.getPathNormalizer() read is deferred behind the closure: inbox
+  // polling starts at session_start, after `session` is assigned — the same
+  // deferred-binding precedent as the logger notify sink below.
+  const servingPolicy: ServingPolicy = {
+    check: (surface, value) =>
+      resolver.resolve(
+        buildAccessIntentForSurface(
+          surface,
+          value ?? undefined,
+          session.getPathNormalizer(),
+          undefined,
+        ),
+      ),
   };
-  const requestServer = new ForwardedRequestServer(requestServerDeps);
 
-  const prompter = new PermissionPrompter({
+  const requestServer = new ForwardedRequestServer({
+    forwardingDir: paths.forwardingDir,
     logger,
-    events: pi.events,
-    forwarder: escalator,
-  });
-
-  const gateway = new PromptingGateway({
-    detection: subagentDetection,
-    prompter,
+    policy: servingPolicy,
+    escalator: authorizerSelection,
+    registry: subagentRegistry,
   });
 
   session = new PermissionSession(
@@ -129,7 +141,7 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
     permissionManager,
     sessionRules,
     configStore,
-    gateway,
+    authorizerSelection,
     hostPlatform,
   );
 
@@ -148,11 +160,6 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
       ),
   });
 
-  // Resolver composes the manager + session ruleset and owns the
-  // access-path → path-values unwrap; the service routes its policy
-  // queries through it, so it is constructed before it.
-  const resolver = new PermissionResolver(permissionManager, sessionRules);
-
   const permissionsService = new LocalPermissionsService(
     resolver,
     session,
@@ -196,7 +203,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-dialog.ts

@@ -14,6 +14,14 @@ export type PermissionPromptDecision = {
    * rather than "user_approved" in the permissions:decision broadcast.
    */
   autoApproved?: true;
+  /**
+   * True when no live authority was reachable and the DenyingAuthorizer denied
+   * this ask (a no-UI, non-subagent session). Consumed by deriveResolution (the
+   * decision-event resolution), the gate (block reason), and PermissionPrompter
+   * (review-entry resolution) to emit "confirmation_unavailable" rather than a
+   * plain user denial.
+   */
+  confirmationUnavailable?: true;
 };
 
 export interface PermissionDecisionUi {

package/src/permission-forwarding.ts

@@ -44,7 +44,8 @@ const SESSION_FORWARDING_RESPONSES_DIRECTORY_NAME = "responses";
  * can emit a non-degraded `permissions:ui_prompt` event.
  *
  * Carried separately from the prompt message because the parent reconstructs
- * the original event through `buildForwardedUiPrompt`, not from the message text.
+ * the original event from the escalated ask's details (`buildUiPrompt`), not
+ * from the message text.
  */
 export interface ForwardedPromptDisplay {
   source: PermissionUiPromptSource;

package/src/permission-gate.ts

@@ -10,10 +10,11 @@ export interface PermissionGateParams {
   /** The resolved permission state from checkPermission(). */
   state: "allow" | "deny" | "ask";
 
-  /** Whether the current context supports interactive prompts. */
-  canConfirm: boolean;
-
-  /** Prompt the user for approval. Only called when state === "ask" and canConfirm is true. */
+  /**
+   * Escalate the ask to the session's Authorizer for a decision. Called for
+   * every `ask`; the DenyingAuthorizer answers by denying with the
+   * `confirmationUnavailable` marker when no live authority is reachable.
+   */
   promptForApproval: () => Promise<PermissionPromptDecision>;
 
   /**
@@ -45,14 +46,7 @@ export interface PermissionGateParams {
 export async function applyPermissionGate(
   params: PermissionGateParams,
 ): Promise<PermissionGateResult> {
-  const {
-    state,
-    canConfirm,
-    promptForApproval,
-    writeLog,
-    logContext,
-    messages,
-  } = params;
+  const { state, promptForApproval, writeLog, logContext, messages } = params;
 
   if (state === "deny") {
     writeLog("permission_request.blocked", {
@@ -63,17 +57,17 @@ export async function applyPermissionGate(
   }
 
   if (state === "ask") {
-    if (!canConfirm) {
-      writeLog("permission_request.blocked", {
-        ...logContext,
-        resolution: "confirmation_unavailable",
-      });
-      return { action: "block", reason: messages.unavailableReason };
-    }
-
     const decision = await promptForApproval();
     if (!decision.approved) {
-      return { action: "block", reason: messages.userDeniedReason(decision) };
+      // The gate writes no review entry for an ask denial — the prompter
+      // brackets it (waiting/denied). The block reason distinguishes an
+      // absent-authority denial (confirmationUnavailable) from a user denial.
+      return {
+        action: "block",
+        reason: decision.confirmationUnavailable
+          ? messages.unavailableReason
+          : messages.userDeniedReason(decision),
+      };
     }
     if (decision.state === "approved_for_session" && params.sessionApproval) {
       return { action: "allow", sessionApproval: params.sessionApproval };

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/permission-ui-prompt.ts

@@ -1,9 +1,10 @@
 /**
  * Centralized construction for `permissions:ui_prompt` payloads.
  *
- * Every emit site builds its event through one of these functions, so the
- * public contract's shape — including the normalized `surface`/`value`
- * projection — lives in exactly one place and cannot drift by source.
+ * The single builder `buildUiPrompt` handles both direct and forwarded asks, so
+ * the public contract's shape — including the normalized `surface`/`value`
+ * projection and the `forwarding` context — lives in exactly one place and
+ * cannot drift by source.
  *
  * This module is a leaf: it owns narrow input types that each call site's
  * domain object satisfies structurally, so it imports nothing from the
@@ -11,8 +12,8 @@
  */
 
 import type {
+  ForwardedPromptContext,
   PermissionUiPromptEvent,
-  PermissionUiPromptSource,
 } from "./permission-events";
 
 /** Input for a direct (non-forwarded) tool or skill prompt. */
@@ -28,18 +29,42 @@ export interface DirectPromptInput {
   target?: string;
 }
 
-/** Input for a file-forwarded subagent prompt shown by the parent UI. */
-export interface ForwardedPromptInput {
-  requestId: string;
-  message: string;
-  requesterAgentName: string | null;
-  requesterSessionId: string | null;
-  /** Original prompt origin, when the forwarded request carries it. */
-  source?: PermissionUiPromptSource | null;
-  /** Original normalized surface, when the forwarded request carries it. */
+/**
+ * Input for any UI prompt — direct or forwarded.
+ *
+ * A direct prompt supplies only the `DirectPromptInput` fields and lets
+ * `surface`/`value` derive and `forwarding` default to `null`; a forwarded ask
+ * supplies the child's original `surface`/`value` projection explicitly and a
+ * populated `forwarding` context, so the parent's broadcast stays non-degraded
+ * (the #292 contract hardening).
+ */
+export interface UiPromptInput extends DirectPromptInput {
+  /** Explicit display surface; falls back to the derived projection when omitted. */
   surface?: string | null;
-  /** Original normalized value, when the forwarded request carries it. */
+  /** Explicit display value; falls back to the derived projection when omitted. */
   value?: string | null;
+  /** Forwarding context for a forwarded subagent ask; `null`/omitted for a direct prompt. */
+  forwarding?: ForwardedPromptContext | null;
+}
+
+/**
+ * Build a `permissions:ui_prompt` event from either a direct or a forwarded ask.
+ *
+ * `surface`/`value` use the explicit override when the caller sets them (an
+ * explicit `null` is honored, not treated as "derive"); otherwise they fall
+ * back to the direct-prompt projection. `forwarding` passes through, defaulting
+ * to `null`.
+ */
+export function buildUiPrompt(input: UiPromptInput): PermissionUiPromptEvent {
+  return {
+    requestId: input.requestId,
+    source: input.source,
+    surface: input.surface !== undefined ? input.surface : directSurface(input),
+    value: input.value !== undefined ? input.value : directValue(input),
+    agentName: input.agentName,
+    message: input.message,
+    forwarding: input.forwarding ?? null,
+  };
 }
 
 /** Normalized display surface for a direct prompt. */
@@ -61,43 +86,3 @@ function directValue(input: DirectPromptInput): string | null {
     null
   );
 }
-
-/** Build the UI prompt event for a direct tool/skill prompt. */
-export function buildDirectUiPrompt(
-  input: DirectPromptInput,
-): PermissionUiPromptEvent {
-  return {
-    requestId: input.requestId,
-    source: input.source,
-    surface: directSurface(input),
-    value: directValue(input),
-    agentName: input.agentName,
-    message: input.message,
-    forwarding: null,
-  };
-}
-
-/**
- * Build the UI prompt event for a file-forwarded subagent prompt.
- *
- * `source` defaults to `"tool_call"` (the dominant forwarded origin) when the
- * persisted request predates carrying it — a parent on a newer version may read
- * a request written by an older child during an upgrade. The consumer still
- * receives the notify-now signal, message, and forwarding context.
- */
-export function buildForwardedUiPrompt(
-  input: ForwardedPromptInput,
-): PermissionUiPromptEvent {
-  return {
-    requestId: input.requestId,
-    source: input.source ?? "tool_call",
-    surface: input.surface ?? null,
-    value: input.value ?? null,
-    agentName: input.requesterAgentName,
-    message: input.message,
-    forwarding: {
-      requesterAgentName: input.requesterAgentName,
-      requesterSessionId: input.requesterSessionId,
-    },
-  };
-}

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/gate-prompter.ts

@@ -1,12 +0,0 @@
-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
- * interactive confirmation is possible, and the prompt itself. The context
- * is bound by the implementor, not threaded per call.
- */
-export interface GatePrompter {
-  canConfirm(): boolean;
-  prompt(details: PromptPermissionDetails): Promise<PermissionPromptDecision>;
-}

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);
-  }
-}