@gotgenes/pi-permission-system 5.2.1 → 5.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-permission-system",
-  "version": "5.2.1",
+  "version": "5.3.1",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
   "files": [

package/src/handlers/input.ts

@@ -8,6 +8,7 @@ interface InputPayload {
   text: string;
 }
 
+import { emitDecisionEvent } from "../permission-events";
 import { applyPermissionGate } from "../permission-gate";
 import { formatSkillAskPrompt } from "../permission-prompts";
 import type { HandlerDeps } from "./types";
@@ -65,17 +66,22 @@ export async function handleInput(
     skillName,
     agentName ?? undefined,
   );
+  const skillInputCanConfirm = deps.canRequestPermissionConfirmation(ctx);
+  let skillInputAutoApproved = false;
   const skillInputGate = await applyPermissionGate({
     state: check.state,
-    canConfirm: deps.canRequestPermissionConfirmation(ctx),
-    promptForApproval: () =>
-      deps.promptPermission(ctx, {
+    canConfirm: skillInputCanConfirm,
+    promptForApproval: async () => {
+      const decision = await deps.promptPermission(ctx, {
         requestId: deps.createPermissionRequestId("skill-input"),
         source: "skill_input",
         agentName,
         message: skillInputMessage,
         skillName,
-      }),
+      });
+      skillInputAutoApproved = decision.autoApproved === true;
+      return decision;
+    },
     writeLog: deps.runtime.writeReviewLog,
     logContext: {
       source: "skill_input",
@@ -91,6 +97,27 @@ export async function handleInput(
     },
   });
 
+  emitDecisionEvent(deps.events, {
+    surface: "skill",
+    value: skillName,
+    result: skillInputGate.action === "allow" ? "allow" : "deny",
+    resolution:
+      check.state === "allow"
+        ? "policy_allow"
+        : check.state === "deny"
+          ? "policy_deny"
+          : skillInputGate.action === "allow"
+            ? skillInputAutoApproved
+              ? "auto_approved"
+              : "user_approved"
+            : skillInputCanConfirm
+              ? "user_denied"
+              : "confirmation_unavailable",
+    origin: check.origin ?? null,
+    agentName: agentName ?? null,
+    matchedPattern: check.matchedPattern ?? null,
+  });
+
   if (skillInputGate.action === "block") {
     return { action: "handled" };
   }

package/src/handlers/lifecycle.ts

@@ -78,4 +78,5 @@ export async function handleSessionShutdown(deps: HandlerDeps): Promise<void> {
   deps.runtime.lastPromptStateCacheKey = null;
   deps.runtime.sessionRules.clear();
   deps.stopForwardedPermissionPolling();
+  deps.stopPermissionRpcHandlers();
 }

package/src/handlers/tool-call.ts

@@ -21,6 +21,10 @@ import {
 } from "../external-directory";
 import { suggestSessionPattern } from "../pattern-suggest";
 import type { PermissionPromptDecision } from "../permission-dialog";
+import {
+  emitDecisionEvent,
+  type PermissionDecisionResolution,
+} from "../permission-events";
 import { applyPermissionGate } from "../permission-gate";
 import {
   formatAskPrompt,
@@ -38,8 +42,50 @@ import {
   checkRequestedToolRegistration,
   getToolNameFromValue,
 } from "../tool-registry";
+import type { PermissionCheckResult } from "../types";
 import type { HandlerDeps } from "./types";
 
+// ── Emission helper ────────────────────────────────────────────────────────
+
+/**
+ * Derive the human-readable value for a decision event from a check result.
+ * Bash → extracted command; MCP → qualified target; others → tool name.
+ */
+function deriveDecisionValue(
+  toolName: string,
+  check: Pick<PermissionCheckResult, "command" | "target">,
+): string {
+  if (toolName === "bash") return check.command ?? toolName;
+  if (toolName === "mcp") return check.target ?? toolName;
+  return toolName;
+}
+
+/**
+ * Map the gate outcome back to a PermissionDecisionResolution.
+ *
+ * @param state     - The permission state passed to the gate.
+ * @param action    - The gate's resulting action ("allow" | "block").
+ * @param hasSession - True when the gate result carries a sessionApproval
+ *                    (indicates the user chose "for this session").
+ * @param canConfirm - Whether an interactive prompt was available.
+ */
+function deriveResolution(
+  state: "allow" | "deny" | "ask",
+  action: "allow" | "block",
+  hasSession: boolean,
+  canConfirm: boolean,
+  autoApproved = false,
+): PermissionDecisionResolution {
+  if (state === "allow") return "policy_allow";
+  if (state === "deny") return "policy_deny";
+  // state === "ask"
+  if (action === "allow") {
+    if (autoApproved) return "auto_approved";
+    return hasSession ? "user_approved_for_session" : "user_approved";
+  }
+  return canConfirm ? "user_denied" : "confirmation_unavailable";
+}
+
 /**
  * Extract the tool input from an event, checking both `input` and `arguments`
  * fields (different Pi SDK versions use different names).
@@ -112,9 +158,10 @@ export async function handleToolCall(
         readEvent.input.path,
         agentName ?? undefined,
       );
+      const skillReadCanConfirm = deps.canRequestPermissionConfirmation(ctx);
       const skillReadGate = await applyPermissionGate({
         state: matchedSkill.state,
-        canConfirm: deps.canRequestPermissionConfirmation(ctx),
+        canConfirm: skillReadCanConfirm,
         promptForApproval: () =>
           deps.promptPermission(ctx, {
             requestId: (readEvent as { toolCallId: string }).toolCallId,
@@ -149,6 +196,20 @@ export async function handleToolCall(
           },
         },
       });
+      emitDecisionEvent(deps.events, {
+        surface: "skill",
+        value: matchedSkill.name,
+        result: skillReadGate.action === "allow" ? "allow" : "deny",
+        resolution: deriveResolution(
+          matchedSkill.state,
+          skillReadGate.action,
+          false,
+          skillReadCanConfirm,
+        ),
+        origin: null,
+        agentName: agentName ?? null,
+        matchedPattern: null,
+      });
       if (skillReadGate.action === "block") {
         return { block: true, reason: skillReadGate.reason };
       }
@@ -193,6 +254,15 @@ export async function handleToolCall(
           path: externalDirectoryPath,
         },
       );
+      emitDecisionEvent(deps.events, {
+        surface: toolName,
+        value: externalDirectoryPath,
+        result: "allow",
+        resolution: "infrastructure_auto_allowed",
+        origin: null,
+        agentName: agentName ?? null,
+        matchedPattern: null,
+      });
       // Fall through to normal tool-permission check.
     } else {
       const extCheck = deps.runtime.permissionManager.checkPermission(
@@ -212,6 +282,15 @@ export async function handleToolCall(
           resolution: "session_approved",
           sessionApprovalPattern: extCheck.matchedPattern,
         });
+        emitDecisionEvent(deps.events, {
+          surface: "external_directory",
+          value: externalDirectoryPath,
+          result: "allow",
+          resolution: "session_approved",
+          origin: extCheck.origin ?? null,
+          agentName: agentName ?? null,
+          matchedPattern: extCheck.matchedPattern ?? null,
+        });
         // Fall through to normal permission check
       } else {
         let extDirDecision: PermissionPromptDecision | null = null;
@@ -221,9 +300,10 @@ export async function handleToolCall(
           ctx.cwd,
           agentName ?? undefined,
         );
-        const extDirGate = await applyPermissionGate({
+        const extDirCanConfirm = deps.canRequestPermissionConfirmation(ctx);
+        const extDirGateResult = await applyPermissionGate({
           state: extCheck.state,
-          canConfirm: deps.canRequestPermissionConfirmation(ctx),
+          canConfirm: extDirCanConfirm,
           promptForApproval: async () => {
             const decision = await deps.promptPermission(ctx, {
               requestId: (event as { toolCallId: string }).toolCallId,
@@ -262,8 +342,22 @@ export async function handleToolCall(
               ),
           },
         });
-        if (extDirGate.action === "block") {
-          return { block: true, reason: extDirGate.reason };
+        emitDecisionEvent(deps.events, {
+          surface: "external_directory",
+          value: externalDirectoryPath,
+          result: extDirGateResult.action === "allow" ? "allow" : "deny",
+          resolution: deriveResolution(
+            extCheck.state,
+            extDirGateResult.action,
+            extDirDecision?.state === "approved_for_session",
+            extDirCanConfirm,
+          ),
+          origin: extCheck.origin ?? null,
+          agentName: agentName ?? null,
+          matchedPattern: extCheck.matchedPattern ?? null,
+        });
+        if (extDirGateResult.action === "block") {
+          return { block: true, reason: extDirGateResult.reason };
         }
 
         if (extDirDecision?.state === "approved_for_session") {
@@ -397,6 +491,15 @@ export async function handleToolCall(
       resolution: "session_approved",
       sessionApprovalPattern: check.matchedPattern,
     });
+    emitDecisionEvent(deps.events, {
+      surface: toolName,
+      value: deriveDecisionValue(toolName, check),
+      result: "allow",
+      resolution: "session_approved",
+      origin: check.origin ?? null,
+      agentName: agentName ?? null,
+      matchedPattern: check.matchedPattern ?? null,
+    });
     return {};
   }
 
@@ -423,15 +526,17 @@ export async function handleToolCall(
         : `Using tool '${toolName}' requires approval, but no interactive UI is available.`;
 
   const toolAskMessage = formatAskPrompt(check, agentName ?? undefined, input);
+  const toolCanConfirm = deps.canRequestPermissionConfirmation(ctx);
+  let toolDecisionAutoApproved = false;
   const toolGate = await applyPermissionGate({
     state: check.state,
-    canConfirm: deps.canRequestPermissionConfirmation(ctx),
+    canConfirm: toolCanConfirm,
     sessionApproval: {
       surface: suggestion.surface,
       pattern: suggestion.pattern,
     },
-    promptForApproval: () =>
-      deps.promptPermission(ctx, {
+    promptForApproval: async () => {
+      const decision = await deps.promptPermission(ctx, {
         requestId: (event as { toolCallId: string }).toolCallId,
         source: "tool_call",
         agentName,
@@ -440,7 +545,10 @@ export async function handleToolCall(
         toolName,
         sessionLabel: suggestion.label,
         ...permissionLogContext,
-      }),
+      });
+      toolDecisionAutoApproved = decision.autoApproved === true;
+      return decision;
+    },
     writeLog: deps.runtime.writeReviewLog,
     logContext: {
       source: "tool_call",
@@ -458,6 +566,24 @@ export async function handleToolCall(
     },
   });
 
+  const toolGateHasSession =
+    toolGate.action === "allow" && toolGate.sessionApproval !== undefined;
+  emitDecisionEvent(deps.events, {
+    surface: toolName,
+    value: deriveDecisionValue(toolName, check),
+    result: toolGate.action === "allow" ? "allow" : "deny",
+    resolution: deriveResolution(
+      check.state,
+      toolGate.action,
+      toolGateHasSession,
+      toolCanConfirm,
+      toolDecisionAutoApproved,
+    ),
+    origin: check.origin ?? null,
+    agentName: agentName ?? null,
+    matchedPattern: check.matchedPattern ?? null,
+  });
+
   if (toolGate.action === "block") {
     return { block: true, reason: toolGate.reason };
   }

package/src/handlers/types.ts

@@ -1,6 +1,7 @@
 import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
 
 import type { PermissionPromptDecision } from "../permission-dialog";
+import type { PermissionEventBus } from "../permission-events";
 import type { PermissionManager } from "../permission-manager";
 import type { ExtensionRuntime } from "../runtime";
 
@@ -33,6 +34,8 @@ export interface HandlerDeps {
   // ── Runtime context ────────────────────────────────────────────────────
   /** All mutable extension state and log-writing methods. */
   readonly runtime: ExtensionRuntime;
+  /** Event bus for emitting permissions:decision broadcast events. */
+  readonly events: PermissionEventBus;
 
   // ── Factories ──────────────────────────────────────────────────────────
   /** Create a new PermissionManager scoped to cwd's config hierarchy. */
@@ -67,6 +70,8 @@ export interface HandlerDeps {
   // ── Forwarding ─────────────────────────────────────────────────────────
   startForwardedPermissionPolling(ctx: ExtensionContext): void;
   stopForwardedPermissionPolling(): void;
+  /** Unsubscribe the permissions:rpc:check and permissions:rpc:prompt handlers. */
+  stopPermissionRpcHandlers(): void;
 
   // ── Pi API subset ──────────────────────────────────────────────────────
   getAllTools(): unknown[];

package/src/index.ts

@@ -12,6 +12,8 @@ import {
   handleToolCall,
 } from "./handlers";
 import { requestPermissionDecisionFromUi } from "./permission-dialog";
+import { registerPermissionRpcHandlers } from "./permission-event-rpc";
+import { emitReadyEvent } from "./permission-events";
 import { PermissionPrompter } from "./permission-prompter";
 import {
   createExtensionRuntime,
@@ -67,8 +69,17 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
   const createPermissionRequestId = (prefix: string): string =>
     `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 10)}-${process.pid}`;
 
+  const rpcHandles = registerPermissionRpcHandlers(pi.events, {
+    getPermissionManager: () => runtime.permissionManager,
+    getSessionRules: () => runtime.sessionRules.getRuleset(),
+    getRuntimeContext: () => runtime.runtimeContext,
+    requestPermissionDecisionFromUi,
+    writeReviewLog: runtime.writeReviewLog.bind(runtime),
+  });
+
   const deps: HandlerDeps = {
     runtime,
+    events: pi.events,
     createPermissionManagerForCwd: (cwd) =>
       createPermissionManagerForCwd(runtime.agentDir, cwd),
     refreshExtensionConfig: (ctx) => refreshExtensionConfig(runtime, ctx),
@@ -92,10 +103,16 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
       startForwardedPermissionPolling(runtime, forwardingDeps, ctx),
     stopForwardedPermissionPolling: () =>
       stopForwardedPermissionPolling(runtime),
+    stopPermissionRpcHandlers: () => {
+      rpcHandles.unsubCheck();
+      rpcHandles.unsubPrompt();
+    },
     getAllTools: () => pi.getAllTools(),
     setActiveTools: (names) => pi.setActiveTools(names),
   };
 
+  emitReadyEvent(pi.events);
+
   pi.on("session_start", (event, ctx) => handleSessionStart(deps, event, ctx));
   pi.on("resources_discover", (event) => handleResourcesDiscover(deps, event));
   pi.on("session_shutdown", () => handleSessionShutdown(deps));

package/src/permission-dialog.ts

@@ -8,6 +8,12 @@ export type PermissionPromptDecision = {
   approved: boolean;
   state: PermissionDecisionState;
   denialReason?: string;
+  /**
+   * True when the decision was made automatically by yolo mode rather than
+   * by an interactive user prompt. Used by handlers to emit "auto_approved"
+   * rather than "user_approved" in the permissions:decision broadcast.
+   */
+  autoApproved?: true;
 };
 
 export interface PermissionDecisionUi {

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