@gotgenes/pi-permission-system 5.2.0 → 5.3.0

package/src/permission-event-rpc.ts

@@ -0,0 +1,229 @@
+/**
+ * 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 "@mariozechner/pi-coding-agent";
+import type {
+  PermissionPromptDecision,
+  RequestPermissionOptions,
+} from "./permission-dialog";
+import type {
+  PermissionEventBus,
+  PermissionsCheckReplyData,
+  PermissionsCheckRequest,
+  PermissionsPromptReplyData,
+  PermissionsPromptRequest,
+  PermissionsRpcReply,
+} from "./permission-events";
+import {
+  PERMISSIONS_PROTOCOL_VERSION,
+  PERMISSIONS_RPC_CHECK_CHANNEL,
+  PERMISSIONS_RPC_PROMPT_CHANNEL,
+} from "./permission-events";
+import type { PermissionManager } from "./permission-manager";
+import type { Rule } from "./rule";
+
+/** Dependencies injected into the RPC handler registry. */
+export interface PermissionRpcDeps {
+  /** Returns the current PermissionManager (refreshed on session start). */
+  getPermissionManager(): Pick<PermissionManager, "checkPermission">;
+  /** Returns the current session rules (highest-priority approvals). */
+  getSessionRules(): Rule[];
+  /**
+   * Returns the current ExtensionContext, or null if no session is active.
+   * Used by the prompt handler to check hasUI and access the UI dialog.
+   */
+  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 structured entries to the permission review log. */
+  writeReviewLog(event: string, details: Record<string, unknown>): void;
+}
+
+/** 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,
+  };
+}
+
+/**
+ * Construct a surface-appropriate input object from a raw value string.
+ *
+ * Note: MCP inputs are complex (server name + tool name derivation). Callers
+ * providing an MCP surface receive a best-effort policy evaluation using the
+ * value as a pre-qualified target string. Pass the fully-qualified target
+ * (e.g. "exa:search" or "exa") directly.
+ */
+function buildInputForSurface(
+  surface: string,
+  value: string | undefined,
+): unknown {
+  const v = value ?? "";
+  if (surface === "bash") return { command: v };
+  if (surface === "skill") return { name: v };
+  if (surface === "external_directory") return { path: v };
+  // MCP and tool surfaces: normalizeInput handles them from the surface alone.
+  return {};
+}
+
+// ── 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.getSessionRules();
+    const result = deps
+      .getPermissionManager()
+      .checkPermission(surface, input, agentName ?? undefined, sessionRules);
+
+    const data: PermissionsCheckReplyData = {
+      result: result.state,
+      matchedPattern: result.matchedPattern ?? null,
+      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.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";
+
+    const decision = await deps.requestPermissionDecisionFromUi(
+      ctx.ui,
+      title,
+      message,
+      sessionLabel ? { sessionLabel } : undefined,
+    );
+
+    deps.writeReviewLog("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,159 @@
+/**
+ * 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 once on extension load. */
+export const PERMISSIONS_READY_CHANNEL = "permissions:ready";
+
+/** Emitted after every permission gate resolution. */
+export const PERMISSIONS_DECISION_CHANNEL = "permissions:decision";
+
+/** RPC request channel — query the permission policy (no prompting). */
+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`. */
+export interface PermissionsReadyEvent {
+  protocolVersion: number;
+}
+
+// ── 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_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`. */
+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. */
+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 ───────────────────────────────────────────────────────────
+
+/**
+ * Emit the `permissions:ready` broadcast.
+ * Call once after the extension has finished setup.
+ */
+export function emitReadyEvent(events: PermissionEventBus): void {
+  const payload: PermissionsReadyEvent = {
+    protocolVersion: PERMISSIONS_PROTOCOL_VERSION,
+  };
+  events.emit(PERMISSIONS_READY_CHANNEL, payload);
+}
+
+/**
+ * Emit a `permissions:decision` broadcast.
+ * Call after every permission gate resolution.
+ */
+export function emitDecisionEvent(
+  events: PermissionEventBus,
+  event: PermissionDecisionEvent,
+): void {
+  events.emit(PERMISSIONS_DECISION_CHANNEL, event);
+}

package/src/permission-prompter.ts

@@ -66,7 +66,7 @@ export class PermissionPrompter implements PermissionPrompterApi {
   ): Promise<PermissionPromptDecision> {
     if (shouldAutoApprovePermissionState("ask", this.deps.getConfig())) {
       this.writeReviewEntry("permission_request.auto_approved", details);
-      return { approved: true, state: "approved" };
+      return { approved: true, state: "approved", autoApproved: true };
     }
 
     this.writeReviewEntry("permission_request.waiting", details);

package/tests/handlers/before-agent-start.test.ts

@@ -101,8 +101,10 @@ function makeDeps(overrides: Partial<HandlerDeps> = {}): HandlerDeps {
       .fn()
       .mockResolvedValue({ approved: true, state: "approved" }),
     createPermissionRequestId: vi.fn().mockReturnValue("test-id"),
+    events: { emit: vi.fn(), on: vi.fn().mockReturnValue(() => undefined) },
     startForwardedPermissionPolling: vi.fn(),
     stopForwardedPermissionPolling: vi.fn(),
+    stopPermissionRpcHandlers: vi.fn(),
     getAllTools: vi.fn().mockReturnValue([]),
     setActiveTools: vi.fn(),
     ...overrides,

package/tests/handlers/input-events.test.ts

@@ -0,0 +1,226 @@
+/**
+ * Tests that handleInput emits permissions:decision events for skill input gates.
+ */
+import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
+import { describe, expect, it, vi } from "vitest";
+
+import { handleInput } from "../../src/handlers/input";
+import type { HandlerDeps } from "../../src/handlers/types";
+import type { PermissionDecisionEvent } from "../../src/permission-events";
+import { PERMISSIONS_DECISION_CHANNEL } from "../../src/permission-events";
+import type { ExtensionRuntime } from "../../src/runtime";
+
+// ── helpers ────────────────────────────────────────────────────────────────
+
+function makeEvents() {
+  return {
+    emit: vi.fn(),
+    on: vi.fn().mockReturnValue(() => undefined),
+  };
+}
+
+function makeCtx(overrides: Partial<ExtensionContext> = {}): ExtensionContext {
+  return {
+    cwd: "/test/project",
+    hasUI: true,
+    ui: {
+      setStatus: vi.fn(),
+      notify: vi.fn(),
+      select: vi.fn(),
+      input: vi.fn(),
+    },
+    sessionManager: {
+      getEntries: vi.fn().mockReturnValue([]),
+      getSessionDir: vi.fn().mockReturnValue("/sessions/test"),
+      addEntry: vi.fn(),
+    },
+    ...overrides,
+  } as unknown as ExtensionContext;
+}
+
+function makeRuntime(
+  state: "allow" | "deny" | "ask" = "allow",
+): ExtensionRuntime {
+  return {
+    agentDir: "/test/agent",
+    sessionsDir: "/test/agent/sessions",
+    subagentSessionsDir: "/test/agent/subagent-sessions",
+    forwardingDir: "/test/agent/sessions/permission-forwarding",
+    globalLogsDir: "/test/agent/extensions/pi-permission-system/logs",
+    piInfrastructureDirs: ["/test/agent"],
+    config: { debugLog: false, permissionReviewLog: true, yoloMode: false },
+    runtimeContext: null,
+    permissionManager: {
+      checkPermission: vi.fn().mockReturnValue({
+        state,
+        toolName: "skill",
+        source: "skill",
+        origin: "global",
+        matchedPattern: "*",
+      }),
+    } as unknown as ExtensionRuntime["permissionManager"],
+    activeSkillEntries: [],
+    lastKnownActiveAgentName: null,
+    lastActiveToolsCacheKey: null,
+    lastPromptStateCacheKey: null,
+    lastConfigWarning: null,
+    sessionRules: {
+      approve: vi.fn(),
+      getRuleset: vi.fn().mockReturnValue([]),
+      clear: vi.fn(),
+    } as unknown as ExtensionRuntime["sessionRules"],
+    permissionForwardingContext: null,
+    permissionForwardingTimer: null,
+    isProcessingForwardedRequests: false,
+    writeDebugLog: vi.fn(),
+    writeReviewLog: vi.fn(),
+  } as ExtensionRuntime;
+}
+
+function makeDeps(
+  state: "allow" | "deny" | "ask" = "allow",
+  overrides: Partial<HandlerDeps> = {},
+): HandlerDeps {
+  return {
+    runtime: makeRuntime(state),
+    events: makeEvents(),
+    createPermissionManagerForCwd: vi.fn(),
+    refreshExtensionConfig: vi.fn(),
+    notifyWarning: vi.fn(),
+    logResolvedConfigPaths: vi.fn(),
+    resolveAgentName: vi.fn().mockReturnValue(null),
+    canRequestPermissionConfirmation: vi.fn().mockReturnValue(true),
+    promptPermission: vi
+      .fn()
+      .mockResolvedValue({ approved: true, state: "approved" }),
+    createPermissionRequestId: vi.fn().mockReturnValue("req-id"),
+    startForwardedPermissionPolling: vi.fn(),
+    stopForwardedPermissionPolling: vi.fn(),
+    stopPermissionRpcHandlers: vi.fn(),
+    getAllTools: vi.fn().mockReturnValue([]),
+    setActiveTools: vi.fn(),
+    ...overrides,
+  };
+}
+
+function getDecisionEvents(deps: HandlerDeps): PermissionDecisionEvent[] {
+  const emitMock = (deps.events as ReturnType<typeof makeEvents>).emit;
+  return emitMock.mock.calls
+    .filter(([channel]) => channel === PERMISSIONS_DECISION_CHANNEL)
+    .map(([, payload]) => payload as PermissionDecisionEvent);
+}
+
+// ── tests ──────────────────────────────────────────────────────────────────
+
+describe("handleInput decision events — skill gate", () => {
+  it("does not emit when input is not a skill invocation", async () => {
+    const deps = makeDeps();
+    await handleInput(deps, { text: "hello world" }, makeCtx());
+    expect(getDecisionEvents(deps)).toHaveLength(0);
+  });
+
+  it("emits allow with policy_allow for an allowed skill", async () => {
+    const deps = makeDeps("allow");
+    await handleInput(deps, { text: "/skill:librarian" }, makeCtx());
+
+    const events = getDecisionEvents(deps);
+    expect(events).toHaveLength(1);
+    expect(events[0]).toMatchObject({
+      surface: "skill",
+      value: "librarian",
+      result: "allow",
+      resolution: "policy_allow",
+    });
+  });
+
+  it("emits deny with policy_deny for a denied skill", async () => {
+    const deps = makeDeps("deny");
+    await handleInput(deps, { text: "/skill:restricted" }, makeCtx());
+
+    const events = getDecisionEvents(deps);
+    expect(events).toHaveLength(1);
+    expect(events[0]).toMatchObject({
+      surface: "skill",
+      value: "restricted",
+      result: "deny",
+      resolution: "policy_deny",
+    });
+  });
+
+  it("emits allow with user_approved when state=ask and user approves", async () => {
+    const deps = makeDeps("ask", {
+      promptPermission: vi
+        .fn()
+        .mockResolvedValue({ approved: true, state: "approved" }),
+    });
+    await handleInput(deps, { text: "/skill:explorer" }, makeCtx());
+
+    const events = getDecisionEvents(deps);
+    expect(events).toHaveLength(1);
+    expect(events[0]).toMatchObject({
+      surface: "skill",
+      value: "explorer",
+      result: "allow",
+      resolution: "user_approved",
+    });
+  });
+
+  it("emits deny with user_denied when state=ask and user denies", async () => {
+    const deps = makeDeps("ask", {
+      promptPermission: vi
+        .fn()
+        .mockResolvedValue({ approved: false, state: "denied" }),
+    });
+    await handleInput(deps, { text: "/skill:explorer" }, makeCtx());
+
+    const events = getDecisionEvents(deps);
+    expect(events).toHaveLength(1);
+    expect(events[0]).toMatchObject({
+      surface: "skill",
+      value: "explorer",
+      result: "deny",
+      resolution: "user_denied",
+    });
+  });
+
+  it("emits deny with confirmation_unavailable when state=ask but no UI", async () => {
+    const deps = makeDeps("ask", {
+      canRequestPermissionConfirmation: vi.fn().mockReturnValue(false),
+    });
+    await handleInput(
+      deps,
+      { text: "/skill:explorer" },
+      makeCtx({ hasUI: false }),
+    );
+
+    const events = getDecisionEvents(deps);
+    expect(events).toHaveLength(1);
+    expect(events[0]).toMatchObject({
+      surface: "skill",
+      value: "explorer",
+      result: "deny",
+      resolution: "confirmation_unavailable",
+    });
+  });
+
+  it("emits allow with auto_approved when promptPermission returns autoApproved:true", async () => {
+    const deps = makeDeps("ask", {
+      // Simulate what PermissionPrompter returns in yolo mode
+      promptPermission: vi.fn().mockResolvedValue({
+        approved: true,
+        state: "approved",
+        autoApproved: true,
+      }),
+    });
+    await handleInput(deps, { text: "/skill:explorer" }, makeCtx());
+
+    const events = getDecisionEvents(deps);
+    expect(events).toHaveLength(1);
+    expect(events[0]).toMatchObject({
+      surface: "skill",
+      value: "explorer",
+      result: "allow",
+      resolution: "auto_approved",
+    });
+  });
+});

package/tests/handlers/input.test.ts

@@ -80,8 +80,10 @@ function makeDeps(overrides: Partial<HandlerDeps> = {}): HandlerDeps {
       .fn()
       .mockResolvedValue({ approved: true, state: "approved" }),
     createPermissionRequestId: vi.fn().mockReturnValue("req-id"),
+    events: { emit: vi.fn(), on: vi.fn().mockReturnValue(() => undefined) },
     startForwardedPermissionPolling: vi.fn(),
     stopForwardedPermissionPolling: vi.fn(),
+    stopPermissionRpcHandlers: vi.fn(),
     getAllTools: vi.fn().mockReturnValue([]),
     setActiveTools: vi.fn(),
     ...overrides,

package/tests/handlers/lifecycle.test.ts

@@ -109,8 +109,10 @@ function makeDeps(overrides: Partial<HandlerDeps> = {}): HandlerDeps {
       .fn()
       .mockResolvedValue({ approved: true, state: "approved" }),
     createPermissionRequestId: vi.fn().mockReturnValue("test-id"),
+    events: { emit: vi.fn(), on: vi.fn().mockReturnValue(() => undefined) },
     startForwardedPermissionPolling: vi.fn(),
     stopForwardedPermissionPolling: vi.fn(),
+    stopPermissionRpcHandlers: vi.fn(),
     getAllTools: vi.fn().mockReturnValue([]),
     setActiveTools: vi.fn(),
     ...overrides,
@@ -341,6 +343,12 @@ describe("handleSessionShutdown", () => {
     expect(deps.stopForwardedPermissionPolling).toHaveBeenCalledOnce();
   });
 
+  it("calls stopPermissionRpcHandlers on shutdown", async () => {
+    const deps = makeDeps();
+    await handleSessionShutdown(deps);
+    expect(deps.stopPermissionRpcHandlers).toHaveBeenCalledOnce();
+  });
+
   it("does not reset lastKnownActiveAgentName", async () => {
     const deps = makeDeps({
       runtime: makeRuntime({ lastKnownActiveAgentName: "remembered" }),