@gotgenes/pi-permission-system 19.0.0 → 20.0.0

package/src/permission-events.ts

@@ -1,27 +1,19 @@
 /**
  * Permission event channel — public contract.
  *
- * Exports channel name constants, protocol version, TypeScript types for all
- * emitted events and RPC envelopes, and thin emit helpers.
+ * Exports channel name constants, TypeScript types for all emitted events,
+ * and thin emit helpers.
  *
  * Stability guarantee: fields may be added, but existing fields will not be
  * removed or renamed without a semver-major version bump.
  */
 
-/** Minimal event bus interface required by the emit helpers and RPC handlers. */
+/** Minimal event bus interface required by the emit helpers. */
 export interface PermissionEventBus {
   emit(channel: string, data: unknown): void;
   on(channel: string, handler: (data: unknown) => void): () => void;
 }
 
-// ── Protocol version ───────────────────────────────────────────────────────
-
-/**
- * RPC protocol version.
- * Bumped when the envelope shape or method contracts change in a breaking way.
- */
-export const PERMISSIONS_PROTOCOL_VERSION = 1;
-
 // ── Channel name constants ─────────────────────────────────────────────────
 
 /** Emitted at `session_start`, after the service is published. */
@@ -33,43 +25,14 @@ export const PERMISSIONS_UI_PROMPT_CHANNEL = "permissions:ui_prompt";
 /** Emitted after every permission gate resolution. */
 export const PERMISSIONS_DECISION_CHANNEL = "permissions:decision";
 
-/**
- * RPC request channel — query the permission policy (no prompting).
- *
- * @deprecated Use the `Symbol.for()`-backed service accessor instead:
- * ```typescript
- * const { getPermissionsService } = await import("@gotgenes/pi-permission-system");
- * const service = getPermissionsService();
- * if (service) {
- *   const result = service.checkPermission("bash", "git push");
- * }
- * ```
- * The event-bus RPC remains available as a zero-dependency fallback.
- */
-export const PERMISSIONS_RPC_CHECK_CHANNEL = "permissions:rpc:check";
-
-/** RPC request channel — forward a permission prompt to the parent UI. */
-export const PERMISSIONS_RPC_PROMPT_CHANNEL = "permissions:rpc:prompt";
-
-// ── Shared RPC envelope ────────────────────────────────────────────────────
-
-/**
- * Standard RPC reply envelope.
- * Success: `{ success: true, protocolVersion, data? }`.
- * Error:   `{ success: false, protocolVersion, error }`.
- */
-export type PermissionsRpcReply<T = void> =
-  | { success: true; protocolVersion: number; data?: T }
-  | { success: false; protocolVersion: number; error: string };
-
 // ── permissions:ready ──────────────────────────────────────────────────────
 
 /**
  * Payload emitted on `permissions:ready`.
  *
- * Intentionally empty: the channel is a readiness signal. Version negotiation
- * lives in the RPC envelope (`PermissionsRpcReply`), not in broadcast payloads —
- * the published types plus package semver define the broadcast contract.
+ * Intentionally empty: the channel is a readiness signal. There is no
+ * `protocolVersion` — the published types plus package semver define the
+ * broadcast contract.
  */
 export type PermissionsReadyEvent = Record<string, never>;
 
@@ -85,8 +48,7 @@ export type PermissionsReadyEvent = Record<string, never>;
 export type PermissionUiPromptSource =
   | "tool_call"
   | "skill_input"
-  | "skill_read"
-  | "rpc_prompt";
+  | "skill_read";
 
 /** Forwarding context, present only when a prompt was forwarded from a non-UI subagent. */
 export interface ForwardedPromptContext {
@@ -155,64 +117,6 @@ export interface PermissionDecisionEvent {
   matchedPattern: string | null;
 }
 
-// ── permissions:rpc:check ──────────────────────────────────────────────────
-
-/**
- * Request payload for `permissions:rpc:check`.
- *
- * @deprecated Prefer `getPermissionsService().checkPermission()` from the
- * service accessor module. See `PERMISSIONS_RPC_CHECK_CHANNEL` for details.
- */
-export interface PermissionsCheckRequest {
-  requestId: string;
-  /** Permission surface to evaluate. */
-  surface: string;
-  /** The value to evaluate: command string, tool name, skill name, or path. */
-  value?: string;
-  /** Optional agent name for per-agent policy resolution. */
-  agentName?: string;
-}
-
-/**
- * Data field in a successful `permissions:rpc:check` reply.
- *
- * @deprecated Prefer `getPermissionsService().checkPermission()` from the
- * service accessor module. See `PERMISSIONS_RPC_CHECK_CHANNEL` for details.
- */
-export interface PermissionsCheckReplyData {
-  result: "allow" | "deny" | "ask";
-  matchedPattern: string | null;
-  origin: string | null;
-}
-
-// ── permissions:rpc:prompt ─────────────────────────────────────────────────
-
-/** Request payload for `permissions:rpc:prompt`. */
-export interface PermissionsPromptRequest {
-  requestId: string;
-  /** Permission surface being evaluated. */
-  surface: string;
-  /** Value being evaluated (shown in the dialog). */
-  value: string;
-  /** Optional agent name for display. */
-  agentName?: string;
-  /** Message to display in the permission dialog. */
-  message: string;
-  /** Optional label for the "for this session" option. */
-  sessionLabel?: string;
-}
-
-/** Data field in a successful `permissions:rpc:prompt` reply. */
-export interface PermissionsPromptReplyData {
-  approved: boolean;
-  /**
-   * Detailed state: "approved", "approved_for_session",
-   * "denied", or "denied_with_reason".
-   */
-  state: string;
-  denialReason?: string;
-}
-
 // ── Emit helpers ───────────────────────────────────────────────────────────
 
 /**

package/src/permission-prompter.ts

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

package/src/permission-ui-prompt.ts

@@ -7,7 +7,7 @@
  *
  * 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
- * prompter, RPC, or forwarding modules (no import cycles, correct layering).
+ * prompter or forwarding modules (no import cycles, correct layering).
  */
 
 import type {
@@ -28,15 +28,6 @@ export interface DirectPromptInput {
   target?: string;
 }
 
-/** Input for a `permissions:rpc:prompt` forwarded UI prompt. */
-export interface RpcPromptInput {
-  requestId: string;
-  surface?: string | null;
-  value?: string | null;
-  agentName?: string | null;
-  message: string;
-}
-
 /** Input for a file-forwarded subagent prompt shown by the parent UI. */
 export interface ForwardedPromptInput {
   requestId: string;
@@ -86,21 +77,6 @@ export function buildDirectUiPrompt(
   };
 }
 
-/** Build the UI prompt event for an RPC-forwarded prompt. */
-export function buildRpcUiPrompt(
-  input: RpcPromptInput,
-): PermissionUiPromptEvent {
-  return {
-    requestId: input.requestId,
-    source: "rpc_prompt",
-    surface: input.surface ?? null,
-    value: input.value ?? null,
-    agentName: input.agentName ?? null,
-    message: input.message,
-    forwarding: null,
-  };
-}
-
 /**
  * Build the UI prompt event for a file-forwarded subagent prompt.
  *

package/src/prompting-gateway.ts

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

package/src/service-lifecycle.ts

@@ -1,13 +1,11 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-
+import type { RegisteredChildDetector } from "./authority/subagent-detection";
 import { emitReadyEvent, type PermissionEventBus } from "./permission-events";
 import {
   type PermissionsService,
   publishPermissionsService,
   unpublishPermissionsService,
 } from "./service";
-import { isRegisteredSubagentChild } from "./subagent-context";
-import type { SubagentSessionRegistry } from "./subagent-registry";
 
 /** The session-scoped service lifecycle that the lifecycle handler drives. */
 export interface ServiceLifecycle {
@@ -28,13 +26,13 @@ export interface ServiceLifecycle {
 export class PermissionServiceLifecycle implements ServiceLifecycle {
   constructor(
     private readonly service: PermissionsService,
-    private readonly registry: SubagentSessionRegistry,
+    private readonly detection: RegisteredChildDetector,
     private readonly events: PermissionEventBus,
     private readonly subscriptions: readonly (() => void)[],
   ) {}
 
   activate(ctx: ExtensionContext): void {
-    if (!isRegisteredSubagentChild(ctx, this.registry)) {
+    if (!this.detection.isRegisteredChild(ctx)) {
       publishPermissionsService(this.service);
     }
     emitReadyEvent(this.events);

package/src/service.ts

@@ -18,18 +18,13 @@ import type { PermissionCheckResult, PermissionState } from "./types";
 export type {
   ForwardedPromptContext,
   PermissionDecisionEvent,
-  PermissionsPromptReplyData,
-  PermissionsPromptRequest,
   PermissionsReadyEvent,
-  PermissionsRpcReply,
   PermissionUiPromptEvent,
   PermissionUiPromptSource,
 } from "./permission-events";
 export {
   PERMISSIONS_DECISION_CHANNEL,
-  PERMISSIONS_PROTOCOL_VERSION,
   PERMISSIONS_READY_CHANNEL,
-  PERMISSIONS_RPC_PROMPT_CHANNEL,
   PERMISSIONS_UI_PROMPT_CHANNEL,
 } from "./permission-events";
 export type { PermissionCheckResult, PermissionState, ToolInputFormatter };
@@ -40,9 +35,9 @@ const SERVICE_KEY = Symbol.for("@gotgenes/pi-permission-system:service");
 /**
  * Public interface exposed to other extensions via `getPermissionsService()`.
  *
- * Mirrors the simplified RPC signature — surface + optional value + optional
- * agent name — and delegates to `PermissionManager.checkPermission()` with
- * current session rules internally.
+ * `checkPermission` takes a surface + optional value + optional agent name,
+ * and delegates to `PermissionManager.checkPermission()` with current session
+ * rules internally.
  */
 export interface PermissionsService {
   /**

package/src/session-logger.ts

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

package/src/permission-event-rpc.ts

@@ -1,227 +0,0 @@
-/* eslint-disable @typescript-eslint/no-deprecated -- this module implements the deprecated event-bus RPC channel; references to its own deprecated symbols are intentional */
-/**
- * Permission event bus RPC handlers.
- *
- * Registers `permissions:rpc:check` and `permissions:rpc:prompt` handlers on
- * the Pi event bus so other extensions can query our policy and forward
- * permission prompts without importing this package.
- */
-import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { buildAccessIntentForSurface } from "./input-normalizer";
-import type { PathNormalizer } from "./path-normalizer";
-import type {
-  PermissionPromptDecision,
-  RequestPermissionOptions,
-} from "./permission-dialog";
-import type {
-  PermissionEventBus,
-  PermissionsCheckReplyData,
-  PermissionsCheckRequest,
-  PermissionsPromptReplyData,
-  PermissionsPromptRequest,
-  PermissionsRpcReply,
-} from "./permission-events";
-import {
-  emitUiPromptEvent,
-  PERMISSIONS_PROTOCOL_VERSION,
-  PERMISSIONS_RPC_CHECK_CHANNEL,
-  PERMISSIONS_RPC_PROMPT_CHANNEL,
-} from "./permission-events";
-import type { ScopedPermissionResolver } from "./permission-resolver";
-import { buildRpcUiPrompt } from "./permission-ui-prompt";
-import type { ReviewLogger } from "./session-logger";
-
-/** Dependencies injected into the RPC handler registry. */
-export interface PermissionRpcDeps {
-  /**
-   * The shared resolver: answers an access intent, composing the session
-   * ruleset and unwrapping `access-path` → `path-values` internally so the
-   * RPC check matches the same lexical ∪ canonical set the gates do (#503).
-   */
-  resolver: Pick<ScopedPermissionResolver, "resolve">;
-  /**
-   * Narrow session view: runtime context for the prompt handler (hasUI / UI
-   * dialog) and the cwd-bound path normalizer for path-surface check queries.
-   */
-  session: {
-    getRuntimeContext(): ExtensionContext | null;
-    getPathNormalizer(): PathNormalizer;
-  };
-  /** Show the interactive permission dialog in the parent session UI. */
-  requestPermissionDecisionFromUi(
-    ui: ExtensionContext["ui"],
-    title: string,
-    message: string,
-    options?: RequestPermissionOptions,
-  ): Promise<PermissionPromptDecision>;
-  /** Write review-log entries for prompted decisions. */
-  logger: ReviewLogger;
-}
-
-/** Unsubscribe handles returned from registerPermissionRpcHandlers. */
-export interface PermissionRpcHandles {
-  /** Stop the permissions:rpc:check handler. */
-  unsubCheck: () => void;
-  /** Stop the permissions:rpc:prompt handler. */
-  unsubPrompt: () => void;
-}
-
-// ── Internal helpers ───────────────────────────────────────────────────────
-
-/** Build a success reply envelope. */
-function successReply<T>(data?: T): PermissionsRpcReply<T> {
-  if (data !== undefined) {
-    return {
-      success: true,
-      protocolVersion: PERMISSIONS_PROTOCOL_VERSION,
-      data,
-    };
-  }
-  return { success: true, protocolVersion: PERMISSIONS_PROTOCOL_VERSION };
-}
-
-/** Build an error reply envelope. */
-function errorReply(error: string): PermissionsRpcReply {
-  return {
-    success: false,
-    protocolVersion: PERMISSIONS_PROTOCOL_VERSION,
-    error,
-  };
-}
-
-// ── RPC handler: permissions:rpc:check ────────────────────────────────────
-
-function handleCheckRpc(
-  raw: unknown,
-  events: PermissionEventBus,
-  deps: PermissionRpcDeps,
-): void {
-  const req = raw as Partial<PermissionsCheckRequest>;
-  const { requestId, surface, value, agentName } = req;
-
-  if (typeof requestId !== "string" || !requestId) {
-    // Cannot reply without a requestId — silently discard.
-    return;
-  }
-
-  const replyChannel = `${PERMISSIONS_RPC_CHECK_CHANNEL}:reply:${requestId}`;
-
-  try {
-    if (typeof surface !== "string" || !surface) {
-      events.emit(replyChannel, errorReply("surface is required"));
-      return;
-    }
-
-    const intent = buildAccessIntentForSurface(
-      surface,
-      value,
-      deps.session.getPathNormalizer(),
-      agentName ?? undefined,
-    );
-    const result = deps.resolver.resolve(intent);
-
-    const data: PermissionsCheckReplyData = {
-      result: result.state,
-      matchedPattern: result.matchedPattern ?? null,
-      // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- ?? null normalises undefined to null for the reply record
-      origin: result.origin ?? null,
-    };
-    events.emit(replyChannel, successReply(data));
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    events.emit(replyChannel, errorReply(message));
-  }
-}
-
-// ── RPC handler: permissions:rpc:prompt ───────────────────────────────────
-
-async function handlePromptRpc(
-  raw: unknown,
-  events: PermissionEventBus,
-  deps: PermissionRpcDeps,
-): Promise<void> {
-  const req = raw as Partial<PermissionsPromptRequest>;
-  const { requestId, surface, value, agentName, message, sessionLabel } = req;
-
-  if (typeof requestId !== "string" || !requestId) {
-    return;
-  }
-
-  const replyChannel = `${PERMISSIONS_RPC_PROMPT_CHANNEL}:reply:${requestId}`;
-
-  const ctx = deps.session.getRuntimeContext();
-  if (!ctx?.hasUI) {
-    events.emit(replyChannel, errorReply("no_ui"));
-    return;
-  }
-
-  if (typeof message !== "string" || !message) {
-    events.emit(replyChannel, errorReply("message is required"));
-    return;
-  }
-
-  try {
-    const title = surface
-      ? `Permission request${agentName ? ` from ${agentName}` : ""}`
-      : "Permission request";
-
-    emitUiPromptEvent(
-      events,
-      buildRpcUiPrompt({ requestId, surface, value, agentName, message }),
-    );
-
-    const decision = await deps.requestPermissionDecisionFromUi(
-      ctx.ui,
-      title,
-      message,
-      sessionLabel ? { sessionLabel } : undefined,
-    );
-
-    deps.logger.review("permission_request.rpc_prompt", {
-      requestId,
-      surface: surface ?? null,
-      value: value ?? null,
-      agentName: agentName ?? null,
-      message,
-      approved: decision.approved,
-      resolution: decision.state,
-      denialReason: decision.denialReason ?? null,
-    });
-
-    const data: PermissionsPromptReplyData = {
-      approved: decision.approved,
-      state: decision.state,
-      ...(decision.denialReason !== undefined
-        ? { denialReason: decision.denialReason }
-        : {}),
-    };
-    events.emit(replyChannel, successReply(data));
-  } catch (err) {
-    const message_ = err instanceof Error ? err.message : String(err);
-    events.emit(replyChannel, errorReply(message_));
-  }
-}
-
-// ── Public API ─────────────────────────────────────────────────────────────
-
-/**
- * Register `permissions:rpc:check` and `permissions:rpc:prompt` handlers on
- * the event bus.
- *
- * Returns unsubscribe handles — call them in session_shutdown to stop the
- * handlers and prevent memory leaks.
- */
-export function registerPermissionRpcHandlers(
-  events: PermissionEventBus,
-  deps: PermissionRpcDeps,
-): PermissionRpcHandles {
-  const unsubCheck = events.on(PERMISSIONS_RPC_CHECK_CHANNEL, (raw) => {
-    handleCheckRpc(raw, events, deps);
-  });
-
-  const unsubPrompt = events.on(PERMISSIONS_RPC_PROMPT_CHANNEL, (raw) => {
-    void handlePromptRpc(raw, events, deps);
-  });
-
-  return { unsubCheck, unsubPrompt };
-}