@gotgenes/pi-permission-system 5.17.0 → 5.18.0

package/CHANGELOG.md

@@ -5,6 +5,23 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [5.18.0](https://github.com/gotgenes/pi-permission-system/compare/v5.17.0...v5.18.0) (2026-05-14)
+
+
+### Features
+
+* add package.json exports field for cross-extension import ([#145](https://github.com/gotgenes/pi-permission-system/issues/145)) ([1091de5](https://github.com/gotgenes/pi-permission-system/commit/1091de5eb673050c3b83448ee69cffb876c407d9))
+* add Symbol.for()-backed service accessor module ([#145](https://github.com/gotgenes/pi-permission-system/issues/145)) ([6a7ddab](https://github.com/gotgenes/pi-permission-system/commit/6a7ddab6e3e58ca0f93807255e9e48716d96ca24))
+* publish permissions service on startup, clear on shutdown ([#145](https://github.com/gotgenes/pi-permission-system/issues/145)) ([97bea7b](https://github.com/gotgenes/pi-permission-system/commit/97bea7bec043de4f6abb823846cef5c04a069517))
+
+
+### Documentation
+
+* deprecate permissions:rpc:check types in favor of service accessor ([#145](https://github.com/gotgenes/pi-permission-system/issues/145)) ([a64b1b9](https://github.com/gotgenes/pi-permission-system/commit/a64b1b91f141e1a98b576433280ad09d95ec3011))
+* document service accessor and deprecate RPC check ([#145](https://github.com/gotgenes/pi-permission-system/issues/145)) ([931a14e](https://github.com/gotgenes/pi-permission-system/commit/931a14efec1ef9bc53075f8974bfd1eeff7e0749))
+* plan Symbol.for()-backed service accessor ([#145](https://github.com/gotgenes/pi-permission-system/issues/145)) ([d9448bc](https://github.com/gotgenes/pi-permission-system/commit/d9448bc8c9ee71714599a18f03cf516a5ffca2cb))
+* **retro:** add retro notes for issue [#148](https://github.com/gotgenes/pi-permission-system/issues/148) ([84e0262](https://github.com/gotgenes/pi-permission-system/commit/84e026264e292357c18c0333b1d1bd561f70149b))
+
 ## [5.17.0](https://github.com/gotgenes/pi-permission-system/compare/v5.16.0...v5.17.0) (2026-05-14)
 
 

package/README.md

@@ -91,7 +91,7 @@ For the full reference — all surfaces, runtime knobs, per-agent overrides, mer
 |---|---|
 |[docs/configuration.md](docs/configuration.md)|Full policy reference, runtime knobs, per-agent overrides, recipes|
 |[docs/session-approvals.md](docs/session-approvals.md)|Session-scoped rules, pattern suggestions, bash arity table|
-|[docs/event-api.md](docs/event-api.md)|Event bus integration, decision broadcasts, RPC check/prompt|
+|[docs/cross-extension-api.md](docs/cross-extension-api.md)|Cross-extension service accessor, event bus integration, decision broadcasts|
 |[docs/subagent-integration.md](docs/subagent-integration.md)|Permission forwarding, coexistence with subagent extensions|
 |[docs/guides/permission-frontmatter-for-subagent-extensions.md](docs/guides/permission-frontmatter-for-subagent-extensions.md)|Convention guide for subagent extension authors|
 |[docs/opencode-compatibility.md](docs/opencode-compatibility.md)|OpenCode compatibility — shared concepts, divergences, porting guide|

package/package.json

@@ -1,8 +1,11 @@
 {
   "name": "@gotgenes/pi-permission-system",
-  "version": "5.17.0",
+  "version": "5.18.0",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
+  "exports": {
+    ".": "./src/service.ts"
+  },
   "files": [
     "src",
     "tests",

package/src/index.ts

@@ -8,6 +8,7 @@ import {
   PermissionGateHandler,
   SessionLifecycleHandler,
 } from "./handlers";
+import { buildInputForSurface } from "./input-normalizer";
 import { requestPermissionDecisionFromUi } from "./permission-dialog";
 import { registerPermissionRpcHandlers } from "./permission-event-rpc";
 import { emitReadyEvent } from "./permission-events";
@@ -19,6 +20,11 @@ import {
   refreshExtensionConfig,
   saveExtensionConfig,
 } from "./runtime";
+import type { PermissionsService } from "./service";
+import {
+  publishPermissionsService,
+  unpublishPermissionsService,
+} from "./service";
 import { createSessionLogger } from "./session-logger";
 import { isSubagentExecutionContext } from "./subagent-context";
 import {
@@ -91,6 +97,20 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
     writeReviewLog: runtime.writeReviewLog.bind(runtime),
   });
 
+  const permissionsService: PermissionsService = {
+    checkPermission(surface, value, agentName) {
+      const input = buildInputForSurface(surface, value);
+      const sessionRules = runtime.sessionRules.getRuleset();
+      return runtime.permissionManager.checkPermission(
+        surface,
+        input,
+        agentName,
+        sessionRules,
+      );
+    },
+  };
+  publishPermissionsService(permissionsService);
+
   emitReadyEvent(pi.events);
 
   const toolRegistry = {
@@ -101,6 +121,7 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
   const lifecycle = new SessionLifecycleHandler(session, () => {
     rpcHandles.unsubCheck();
     rpcHandles.unsubPrompt();
+    unpublishPermissionsService();
   });
   const agentPrep = new AgentPrepHandler(session, toolRegistry);
   const gates = new PermissionGateHandler(session, pi.events, toolRegistry);

package/src/input-normalizer.ts

@@ -2,6 +2,34 @@ import { toRecord } from "./common";
 import { createMcpPermissionTargets } from "./mcp-targets";
 import { getPathBearingToolPath, PATH_BEARING_TOOLS } from "./path-utils";
 
+/**
+ * Construct a surface-appropriate input object from a raw value string.
+ *
+ * This is the inverse of `normalizeInput()` — it builds the minimal input
+ * object that `PermissionManager.checkPermission()` expects for a given
+ * surface, from a single string value.
+ *
+ * Used by the event-bus RPC handler and the `Symbol.for()` service accessor
+ * so external callers can query policy with `(surface, value)` instead of
+ * constructing a full tool-call input payload.
+ *
+ * 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.
+ */
+export 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 {};
+}
+
 /**
  * Surface-normalized representation of a tool invocation used by
  * `checkPermission()` to feed a single `evaluateFirst()` call.

package/src/permission-event-rpc.ts

@@ -6,6 +6,7 @@
  * permission prompts without importing this package.
  */
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { buildInputForSurface } from "./input-normalizer";
 import type {
   PermissionPromptDecision,
   RequestPermissionOptions,
@@ -79,26 +80,6 @@ function errorReply(error: string): PermissionsRpcReply {
   };
 }
 
-/**
- * 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(

package/src/permission-events.ts

@@ -30,7 +30,19 @@ 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). */
+/**
+ * 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. */
@@ -88,7 +100,12 @@ export interface PermissionDecisionEvent {
 
 // ── permissions:rpc:check ──────────────────────────────────────────────────
 
-/** Request payload for `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. */
@@ -99,7 +116,12 @@ export interface PermissionsCheckRequest {
   agentName?: string;
 }
 
-/** Data field in a successful `permissions:rpc:check` reply. */
+/**
+ * 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;

package/src/service.ts

@@ -0,0 +1,75 @@
+/**
+ * Cross-extension service accessor backed by `Symbol.for()` on `globalThis`.
+ *
+ * `Symbol.for()` is process-global by spec, so it survives jiti's per-extension
+ * module isolation (`moduleCache: false`). A consumer doing
+ * `import("@gotgenes/pi-permission-system")` gets a fresh module copy, but
+ * `getPermissionsService()` reads from the same `globalThis` slot the provider
+ * wrote to — enabling direct, synchronous, type-safe function calls.
+ *
+ * Best practice: call `getPermissionsService()` per use rather than caching the
+ * reference — this ensures resilience across `/reload` and load-order edge cases.
+ */
+
+import type { PermissionCheckResult, PermissionState } from "./types";
+
+export type { PermissionCheckResult, PermissionState };
+
+/** Process-global key for the service slot. */
+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.
+ */
+export interface PermissionsService {
+  /**
+   * Query the permission policy for a surface and value.
+   *
+   * @param surface   - Permission surface: "bash", "read", "mcp", "skill",
+   *                    "external_directory", etc.
+   * @param value     - The value to evaluate: command string, tool name, skill
+   *                    name, or path. Omit or pass `undefined` for a
+   *                    surface-level query.
+   * @param agentName - Optional agent name for per-agent policy resolution.
+   * @returns Full check result including state, matched pattern, and origin.
+   */
+  checkPermission(
+    surface: string,
+    value?: string,
+    agentName?: string,
+  ): PermissionCheckResult;
+}
+
+/**
+ * Store a `PermissionsService` on `globalThis` so other extensions can
+ * retrieve it via `getPermissionsService()`.
+ *
+ * Overwrites any previously published service — safe for `/reload`.
+ */
+export function publishPermissionsService(service: PermissionsService): void {
+  (globalThis as Record<symbol, unknown>)[SERVICE_KEY] = service;
+}
+
+/**
+ * Retrieve the published `PermissionsService`, or `undefined` if the
+ * permission-system extension has not loaded (or has been unloaded).
+ */
+export function getPermissionsService(): PermissionsService | undefined {
+  return (globalThis as Record<symbol, unknown>)[SERVICE_KEY] as
+    | PermissionsService
+    | undefined;
+}
+
+/**
+ * Remove the service from `globalThis`.
+ *
+ * Called during `session_shutdown` to avoid stale references after the
+ * extension is torn down.
+ */
+export function unpublishPermissionsService(): void {
+  delete (globalThis as Record<symbol, unknown>)[SERVICE_KEY];
+}

package/tests/service.test.ts

@@ -0,0 +1,144 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { buildInputForSurface } from "../src/input-normalizer";
+import type { PermissionsService } from "../src/service";
+import {
+  getPermissionsService,
+  publishPermissionsService,
+  unpublishPermissionsService,
+} from "../src/service";
+import type { PermissionCheckResult } from "../src/types";
+
+// ── helpers ────────────────────────────────────────────────────────────────
+
+function makeService(
+  overrides: Partial<PermissionsService> = {},
+): PermissionsService {
+  return {
+    checkPermission: vi.fn(),
+    ...overrides,
+  };
+}
+
+// ── globalThis accessor ────────────────────────────────────────────────────
+
+describe("globalThis accessor", () => {
+  afterEach(() => {
+    unpublishPermissionsService();
+  });
+
+  it("returns undefined when nothing has been published", () => {
+    expect(getPermissionsService()).toBeUndefined();
+  });
+
+  it("returns the published service", () => {
+    const service = makeService();
+    publishPermissionsService(service);
+    expect(getPermissionsService()).toBe(service);
+  });
+
+  it("overwrites a previously published service", () => {
+    const first = makeService();
+    const second = makeService();
+    publishPermissionsService(first);
+    publishPermissionsService(second);
+    expect(getPermissionsService()).toBe(second);
+  });
+
+  it("returns undefined after unpublish", () => {
+    const service = makeService();
+    publishPermissionsService(service);
+    unpublishPermissionsService();
+    expect(getPermissionsService()).toBeUndefined();
+  });
+
+  it("unpublish is safe to call when nothing was published", () => {
+    expect(() => unpublishPermissionsService()).not.toThrow();
+    expect(getPermissionsService()).toBeUndefined();
+  });
+});
+
+// ── service adapter delegation ─────────────────────────────────────────────
+
+describe("service adapter delegation", () => {
+  afterEach(() => {
+    unpublishPermissionsService();
+  });
+
+  const fakeResult: PermissionCheckResult = {
+    toolName: "bash",
+    state: "allow",
+    matchedPattern: "git *",
+    source: "bash",
+    origin: "global",
+  };
+
+  it("checkPermission delegates surface and value through buildInputForSurface", () => {
+    const checkPermission = vi.fn().mockReturnValue(fakeResult);
+    const sessionRules = [
+      {
+        surface: "bash",
+        pattern: "*",
+        action: "allow" as const,
+        layer: "session" as const,
+        origin: "session" as const,
+      },
+    ];
+
+    // Build the adapter the same way index.ts will
+    const service: PermissionsService = {
+      checkPermission(surface, value, agentName) {
+        const input = buildInputForSurface(surface, value);
+        return checkPermission(surface, input, agentName, sessionRules);
+      },
+    };
+
+    publishPermissionsService(service);
+    const retrieved = getPermissionsService()!;
+    const result = retrieved.checkPermission("bash", "git push");
+
+    expect(result).toBe(fakeResult);
+    expect(checkPermission).toHaveBeenCalledWith(
+      "bash",
+      { command: "git push" },
+      undefined,
+      sessionRules,
+    );
+  });
+
+  it("checkPermission passes agentName through", () => {
+    const checkPermission = vi.fn().mockReturnValue(fakeResult);
+
+    const service: PermissionsService = {
+      checkPermission(surface, value, agentName) {
+        const input = buildInputForSurface(surface, value);
+        return checkPermission(surface, input, agentName, []);
+      },
+    };
+
+    publishPermissionsService(service);
+    getPermissionsService()!.checkPermission("skill", "my-skill", "Explore");
+
+    expect(checkPermission).toHaveBeenCalledWith(
+      "skill",
+      { name: "my-skill" },
+      "Explore",
+      [],
+    );
+  });
+
+  it("checkPermission uses empty object for unknown surfaces", () => {
+    const checkPermission = vi.fn().mockReturnValue(fakeResult);
+
+    const service: PermissionsService = {
+      checkPermission(surface, value, agentName) {
+        const input = buildInputForSurface(surface, value);
+        return checkPermission(surface, input, agentName, []);
+      },
+    };
+
+    publishPermissionsService(service);
+    getPermissionsService()!.checkPermission("read", "/tmp/file");
+
+    expect(checkPermission).toHaveBeenCalledWith("read", {}, undefined, []);
+  });
+});