@gotgenes/pi-permission-system 5.2.1 → 5.3.1

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" }),