@komarspn/pi-permission-system 16.0.2

package/src/permission-event-rpc.ts

@@ -0,0 +1,223 @@
+/* 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 { buildInputForSurface } from "./input-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 { PermissionManager } from "./permission-manager";
+import { buildRpcUiPrompt } from "./permission-ui-prompt";
+import type { ReviewLogger } from "./session-logger";
+import type { SessionRules } from "./session-rules";
+
+/** Dependencies injected into the RPC handler registry. */
+export interface PermissionRpcDeps {
+  /** The shared PermissionManager instance. */
+  permissionManager: Pick<PermissionManager, "checkPermission">;
+  /** The shared SessionRules instance. */
+  sessionRules: Pick<SessionRules, "getRuleset">;
+  /**
+   * Narrow session view: provides runtime context.
+   * Used by the prompt handler to check hasUI and access the UI dialog.
+   */
+  session: { getRuntimeContext(): ExtensionContext | null };
+  /** 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 input = buildInputForSurface(surface, value);
+    const sessionRules = deps.sessionRules.getRuleset();
+    const result = deps.permissionManager.checkPermission(
+      surface,
+      input,
+      agentName ?? undefined,
+      sessionRules,
+    );
+
+    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 };
+}

package/src/permission-events.ts

@@ -0,0 +1,266 @@
+/**
+ * Permission event channel — public contract.
+ *
+ * Exports channel name constants, protocol version, TypeScript types for all
+ * emitted events and RPC envelopes, 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. */
+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. */
+export const PERMISSIONS_READY_CHANNEL = "permissions:ready";
+
+/** Emitted when a permission request is committed to the active UI prompt path. */
+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.
+ */
+export type PermissionsReadyEvent = Record<string, never>;
+
+// ── permissions:ui_prompt ──────────────────────────────────────────────────
+
+/**
+ * Origin of a UI 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.
+ */
+export type PermissionUiPromptSource =
+  | "tool_call"
+  | "skill_input"
+  | "skill_read"
+  | "rpc_prompt";
+
+/** Forwarding context, present only when a prompt was forwarded from a non-UI subagent. */
+export interface ForwardedPromptContext {
+  /** Requesting subagent's display name, when known. */
+  requesterAgentName: string | null;
+  /** Requesting subagent's session id, when known. */
+  requesterSessionId: string | null;
+}
+
+/**
+ * Payload emitted on `permissions:ui_prompt`, immediately before the active
+ * user-facing permission UI is shown.
+ *
+ * Lean by design: `surface`/`value` are the normalized display projection a
+ * notification consumer reads; `source` is the origin; `forwarding` is non-null
+ * only for forwarded subagent prompts. There is no `protocolVersion` — the
+ * published types plus package semver define the broadcast contract, and
+ * consumers should read defensively.
+ */
+export interface PermissionUiPromptEvent {
+  /** Unique ID for the permission request being prompted. */
+  requestId: string;
+  /** Prompt origin. */
+  source: PermissionUiPromptSource;
+  /** Normalized display surface (e.g. "bash", "skill"), when known. */
+  surface: string | null;
+  /** Normalized display value (command, path, skill name, etc.), when known. */
+  value: string | null;
+  /** Agent name (when known). */
+  agentName: string | null;
+  /** Message displayed to the user. */
+  message: string;
+  /** Forwarding context, or null for a direct prompt. */
+  forwarding: ForwardedPromptContext | null;
+}
+
+// ── permissions:decision ───────────────────────────────────────────────────
+
+/** How a permission decision was reached. */
+export type PermissionDecisionResolution =
+  | "policy_allow"
+  | "policy_deny"
+  | "session_approved"
+  | "infrastructure_auto_allowed"
+  | "user_approved"
+  | "user_approved_for_session"
+  | "user_approved_for_project"
+  | "user_approved_globally"
+  | "user_denied"
+  | "auto_approved"
+  | "confirmation_unavailable";
+
+/** Payload emitted on `permissions:decision`. */
+export interface PermissionDecisionEvent {
+  /** Permission surface: "bash", "read", "mcp", "skill", "external_directory", etc. */
+  surface: string;
+  /** The value that was evaluated (command, tool name, skill name, path). */
+  value: string;
+  /** Final decision. */
+  result: "allow" | "deny";
+  /** How the decision was reached. */
+  resolution: PermissionDecisionResolution;
+  /** Which config scope contributed the winning rule (when available). */
+  origin: string | null;
+  /** Agent name (when known). */
+  agentName: string | null;
+  /** Matched pattern from the winning rule (when available). */
+  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",
+   * "approved_for_project", "approved_globally", "denied",
+   * or "denied_with_reason".
+   */
+  state: string;
+  denialReason?: string;
+}
+
+// ── Emit helpers ───────────────────────────────────────────────────────────
+
+/**
+ * Emit the `permissions:ready` broadcast.
+ * Call at `session_start`, after the service is published, so a consumer
+ * reacting to ready can immediately resolve `getPermissionsService()`.
+ */
+export function emitReadyEvent(events: PermissionEventBus): void {
+  const payload: PermissionsReadyEvent = {};
+  try {
+    events.emit(PERMISSIONS_READY_CHANNEL, payload);
+  } catch {
+    // Broadcasts are best-effort. A throwing listener must not block the
+    // permission system from completing session startup.
+  }
+}
+
+/**
+ * Emit a `permissions:ui_prompt` broadcast.
+ * Call immediately before invoking the active user-facing permission UI.
+ */
+export function emitUiPromptEvent(
+  events: PermissionEventBus,
+  event: PermissionUiPromptEvent,
+): void {
+  try {
+    events.emit(PERMISSIONS_UI_PROMPT_CHANNEL, event);
+  } catch {
+    // UI-prompt broadcasts are observational. A consumer failure must not block
+    // the permission dialog itself.
+  }
+}
+
+/**
+ * Emit a `permissions:decision` broadcast.
+ * Call after every permission gate resolution.
+ */
+export function emitDecisionEvent(
+  events: PermissionEventBus,
+  event: PermissionDecisionEvent,
+): void {
+  try {
+    events.emit(PERMISSIONS_DECISION_CHANNEL, event);
+  } catch {
+    // Broadcasts are best-effort. A throwing listener must not block the
+    // permission gate from resolving.
+  }
+}

package/src/permission-forwarding.ts

@@ -0,0 +1,188 @@
+import { join } from "node:path";
+
+import type { PermissionDecisionState } from "./permission-dialog";
+import type { PermissionUiPromptSource } from "./permission-events";
+import type { SubagentSessionRegistry } from "./subagent-registry";
+
+export const PERMISSION_FORWARDING_POLL_INTERVAL_MS = 250;
+export const PERMISSION_FORWARDING_TIMEOUT_MS = 10 * 60 * 1000;
+export const SUBAGENT_ENV_HINT_KEYS = [
+  // pi-agent-router (original)
+  "PI_IS_SUBAGENT",
+  "PI_SUBAGENT_SESSION_ID",
+  "PI_AGENT_ROUTER_SUBAGENT",
+  // nicobailon/pi-subagents
+  "PI_SUBAGENT_CHILD",
+  "PI_SUBAGENT_RUN_ID",
+  "PI_SUBAGENT_CHILD_AGENT",
+  "PI_SUBAGENT_DEPTH",
+  // HazAT/pi-interactive-subagents
+  "PI_SUBAGENT_NAME",
+  "PI_SUBAGENT_ID",
+  "PI_SUBAGENT_SESSION",
+  "PI_SUBAGENT_ACTIVITY_FILE",
+] as const;
+/** Ordered list of env var names to check for the parent session ID. First match wins. */
+export const SUBAGENT_PARENT_SESSION_ENV_CANDIDATES: readonly string[] = [
+  // pi-agent-router (original)
+  "PI_AGENT_ROUTER_PARENT_SESSION_ID",
+  // Shared convention for CLI-based subagent extensions
+  // (nicobailon/pi-subagents, HazAT/pi-interactive-subagents, etc.)
+  "PI_SUBAGENT_PARENT_SESSION",
+] as const;
+
+/** @deprecated Use SUBAGENT_PARENT_SESSION_ENV_CANDIDATES */
+export const SUBAGENT_PARENT_SESSION_ENV_KEY =
+  SUBAGENT_PARENT_SESSION_ENV_CANDIDATES[0];
+
+const SESSION_FORWARDING_ROOT_DIRECTORY_NAME = "sessions";
+const SESSION_FORWARDING_REQUESTS_DIRECTORY_NAME = "requests";
+const SESSION_FORWARDING_RESPONSES_DIRECTORY_NAME = "responses";
+
+/**
+ * Display fields relayed from a forwarding child to the parent UI so the parent
+ * 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.
+ */
+export interface ForwardedPromptDisplay {
+  source: PermissionUiPromptSource;
+  surface: string | null;
+  value: string | null;
+}
+
+export type ForwardedPermissionRequest = {
+  id: string;
+  createdAt: number;
+  requesterSessionId: string;
+  targetSessionId: string;
+  requesterAgentName: string;
+  message: string;
+  /**
+   * Original prompt display fields, persisted so the parent emits a
+   * non-degraded event. Optional for version-skew tolerance: a parent on a
+   * newer version may read a request written by an older child during an
+   * upgrade, in which case the reader defaults `source` to `"tool_call"`.
+   */
+  source?: PermissionUiPromptSource;
+  surface?: string | null;
+  value?: string | null;
+};
+
+export type ForwardedPermissionResponse = {
+  approved: boolean;
+  state: PermissionDecisionState;
+  denialReason?: string;
+  responderSessionId: string;
+  respondedAt: number;
+};
+
+export type PermissionForwardingLocation = {
+  sessionId: string;
+  sessionRootDir: string;
+  requestsDir: string;
+  responsesDir: string;
+  label: "primary";
+};
+
+export function normalizePermissionForwardingSessionId(
+  value: unknown,
+): string | null {
+  if (typeof value !== "string") {
+    return null;
+  }
+
+  const trimmed = value.trim();
+  if (!trimmed || trimmed.toLowerCase() === "unknown") {
+    return null;
+  }
+
+  return trimmed;
+}
+
+function encodeSessionIdForPath(sessionId: string): string {
+  return encodeURIComponent(sessionId);
+}
+
+export function createPermissionForwardingLocation(
+  forwardingRootDir: string,
+  sessionId: string,
+): PermissionForwardingLocation {
+  const normalizedSessionId = normalizePermissionForwardingSessionId(sessionId);
+  if (!normalizedSessionId) {
+    throw new Error(
+      "Permission forwarding session id must be a non-empty string.",
+    );
+  }
+
+  const sessionRootDir = join(
+    forwardingRootDir,
+    SESSION_FORWARDING_ROOT_DIRECTORY_NAME,
+    encodeSessionIdForPath(normalizedSessionId),
+  );
+
+  return {
+    sessionId: normalizedSessionId,
+    sessionRootDir,
+    requestsDir: join(
+      sessionRootDir,
+      SESSION_FORWARDING_REQUESTS_DIRECTORY_NAME,
+    ),
+    responsesDir: join(
+      sessionRootDir,
+      SESSION_FORWARDING_RESPONSES_DIRECTORY_NAME,
+    ),
+    label: "primary",
+  };
+}
+
+export function resolvePermissionForwardingTargetSessionId(options: {
+  hasUI: boolean;
+  isSubagent: boolean;
+  currentSessionId?: string | null;
+  env?: NodeJS.ProcessEnv;
+  /** Child session id for registry lookup. */
+  sessionId?: string;
+  /** In-process subagent session registry (checked before env vars). */
+  registry?: SubagentSessionRegistry;
+}): string | null {
+  if (options.hasUI) {
+    return normalizePermissionForwardingSessionId(options.currentSessionId);
+  }
+
+  if (!options.isSubagent) {
+    return null;
+  }
+
+  // 1. Registry — in-process subagents register parentSessionId explicitly.
+  if (options.registry && options.sessionId) {
+    const entry = options.registry.get(options.sessionId);
+    const resolved = normalizePermissionForwardingSessionId(
+      entry?.parentSessionId,
+    );
+    if (resolved) return resolved;
+  }
+
+  // 2. Env vars — process-based subagent extensions.
+  const env = options.env ?? process.env;
+  for (const key of SUBAGENT_PARENT_SESSION_ENV_CANDIDATES) {
+    const resolved = normalizePermissionForwardingSessionId(env[key]);
+    if (resolved) return resolved;
+  }
+  return null;
+}
+
+export function isForwardedPermissionRequestForSession(
+  request: Pick<ForwardedPermissionRequest, "targetSessionId">,
+  sessionId: string | null | undefined,
+): boolean {
+  const normalizedRequestSessionId = normalizePermissionForwardingSessionId(
+    request.targetSessionId,
+  );
+  const normalizedSessionId = normalizePermissionForwardingSessionId(sessionId);
+  return (
+    normalizedRequestSessionId !== null &&
+    normalizedRequestSessionId === normalizedSessionId
+  );
+}