@gotgenes/pi-permission-system 18.1.0 → 18.1.2

package/docs/cross-extension-api.md

@@ -0,0 +1,525 @@
+# Event API
+
+The extension provides two cross-extension integration surfaces:
+
+1. **Service accessor** (preferred) — a `Symbol.for()`-backed synchronous API on `globalThis` for direct policy queries.
+2. **Event bus** — broadcasts and RPC on `pi.events` for observation and prompt forwarding.
+
+---
+
+## Service Accessor
+
+The preferred way for other extensions to query the permission policy is the `Symbol.for()`-backed service accessor.
+It provides direct, synchronous, type-safe function calls — no async RPC envelope needed.
+
+### Quick Start
+
+```typescript
+try {
+  const { getPermissionsService } = await import(
+    "@gotgenes/pi-permission-system"
+  );
+  const permissions = getPermissionsService();
+  if (permissions) {
+    const result = permissions.checkPermission("bash", "git push");
+    console.log(result.state); // "allow" | "deny" | "ask"
+  }
+} catch {
+  // Not installed — graceful degradation
+}
+```
+
+### How It Works
+
+Pi's extension loader creates a fresh [jiti](https://github.com/nicolo-ribaudo/jiti) instance per extension with `moduleCache: false`, which isolates module-level state.
+`Symbol.for()` and `globalThis` are process-global by spec, so they survive this isolation.
+
+The permission-system extension publishes a service object on `globalThis` via `Symbol.for("@gotgenes/pi-permission-system:service")` at `session_start`.
+Consumers call `getPermissionsService()` to retrieve it — even though their `import()` loads a fresh module copy, the accessor reads from the shared `globalThis` slot.
+An in-process subagent child does not publish its own service; inside a child, `getPermissionsService()` resolves the parent's service.
+A consumer reacting to the `permissions:ready` broadcast (also emitted at `session_start`, after the publish) can resolve the service immediately.
+
+### API
+
+The `PermissionsService` interface:
+
+```typescript
+interface PermissionsService {
+  /** Query the permission policy for a surface and value. */
+  checkPermission(
+    surface: string,
+    value?: string,
+    agentName?: string,
+  ): PermissionCheckResult;
+
+  /** Query tool-level permission state for pre-filtering before session creation. */
+  getToolPermission(toolName: string, agentName?: string): PermissionState;
+
+  /**
+   * Register a custom preview formatter for a specific tool name.
+   * Returns a disposer that unregisters the formatter.
+   * Throws if a formatter is already registered for that tool name.
+   */
+  registerToolInputFormatter(
+    toolName: string,
+    formatter: (input: Record<string, unknown>) => string | undefined,
+  ): () => void;
+
+  /**
+   * Register a custom access-intent extractor for a specific tool name.
+   * Declares the filesystem path a tool accesses so the `path` and
+   * `external_directory` gates can see it. Returns a disposer; throws if an
+   * extractor is already registered for that tool name.
+   */
+  registerToolAccessExtractor(
+    toolName: string,
+    extractor: (input: Record<string, unknown>) => string | undefined,
+  ): () => void;
+}
+```
+
+#### `checkPermission`
+
+| Parameter   | Required | Description                                                                              |
+| ----------- | -------- | ---------------------------------------------------------------------------------------- |
+| `surface`   | Yes      | Permission surface: `"bash"`, `"read"`, `"mcp"`, `"skill"`, `"external_directory"`, etc. |
+| `value`     | No       | Value to evaluate (command, name, path); defaults to `""`                                |
+| `agentName` | No       | Agent name for per-agent policy resolution                                               |
+
+Returns `PermissionCheckResult` with fields `state`, `matchedPattern`, `source`, `origin`, etc.
+
+For a path-shaped surface (`path`, `external_directory`, or a path-bearing tool — `read`/`write`/`edit`/`grep`/`find`/`ls`), the supplied `value` is matched against both the path as given and its canonical (symlink-resolved) form, at parity with the gates — so a query for a symlinked path matches a rule on its real target.
+
+#### `getToolPermission`
+
+Returns `"allow"` | `"deny"` | `"ask"` for a tool name without considering command-level rules.
+Use this to pre-filter a tool list before creating a child session — it avoids calling `checkPermission` per tool and interpreting the full result.
+
+```typescript
+const denied = tools.filter(
+  (t) => permissions.getToolPermission(t, agentName) === "deny",
+);
+```
+
+#### `registerToolInputFormatter`
+
+Register a custom preview formatter for a specific tool name.
+Permission ask-prompts call your formatter while building the prompt text, so you can show a human-readable summary of a tool call instead of the default truncated JSON.
+
+```typescript
+registerToolInputFormatter(
+  toolName: string,
+  formatter: (input: Record<string, unknown>) => string | undefined,
+): () => void; // returns a disposer
+```
+
+Registration rules:
+
+- One formatter per tool name.
+  A second `register` for the same name throws — there is no silent override.
+- The returned disposer unregisters the formatter.
+  It is identity-guarded, so a stale disposer cannot evict a later registration of the same name.
+
+##### Which tool name to key on
+
+The `toolName` you register is matched against the **registered Pi tool name** the agent invoked — not against MCP server/tool pairs.
+
+- For a tool your extension registers directly with Pi, use that tool's exact name (the same string Pi shows in `pi.getAllTools()`).
+- For **MCP** calls, every server tool arrives as the single umbrella `"mcp"` tool, with the real target in `input.tool` (e.g. `"exa:search"`).
+  You therefore cannot register a formatter per `server:tool`.
+  The `"mcp"` name is already claimed by the built-in summarizer (below), and because duplicate registration throws, you cannot replace it.
+  If you need richer per-server MCP previews, open an issue — that requires a chained-formatter model this seam does not yet provide.
+- `"bash"` never reaches your formatter: bash prompts take a dedicated branch that shows the command directly.
+
+##### What your formatter receives
+
+The `input` argument is the raw tool-call input object exactly as the agent supplied it (the tool's arguments).
+It is always a plain record; shapes by tool:
+
+| Tool                   | `input` shape                                                                           |
+| ---------------------- | --------------------------------------------------------------------------------------- |
+| `mcp` (umbrella)       | `{ tool: "server:tool", server?, arguments?: object, … }` — summarize `input.arguments` |
+| `read`                 | `{ path, offset?, limit? }`                                                             |
+| `write`                | `{ path, content }`                                                                     |
+| `edit`                 | `{ path, edits?: […] }` or `{ path, oldText, newText }`                                 |
+| `grep` / `find` / `ls` | `{ pattern?, glob?, path? }`                                                            |
+| your own tool          | whatever input schema your tool registered                                              |
+
+Treat every field as untrusted: the agent can emit malformed or partial input, so read defensively (type-check before use) rather than assuming a shape.
+
+##### What your return value does
+
+The returned string is spliced into the middle of the prompt sentence:
+
+```text
+Agent 'Explore' requested tool 'deploy' <your fragment>. Allow this call?
+```
+
+Return a short grammatical fragment that reads naturally in that slot — e.g. `"with target staging (3 services)"` or `"runs 2 commands"`, not a full sentence and not raw JSON.
+
+Return semantics:
+
+- Return a **string** to use it verbatim as the preview (this also overrides the built-in preview for built-in tools like `read`/`edit`).
+- Return **`undefined`** to decline — the prompt falls through to the built-in formatter for that tool, and finally to the truncated-JSON default.
+  Prefer `undefined` over `""` when you have nothing useful to add: an empty string short-circuits the fallthrough and suppresses the default preview entirely.
+
+##### Your formatter must not throw
+
+The core does **not** wrap your formatter in a `try/catch`.
+A thrown error propagates into prompt construction and can break the permission prompt — a denial-of-service on the gate.
+Guard your own parsing and return `undefined` on anything unexpected.
+
+##### End-to-end wiring
+
+Register during your extension's initialization and store the disposer for teardown:
+
+```typescript
+export default function myExtension(pi: ExtensionAPI): void {
+  let disposeFormatter: (() => void) | undefined;
+
+  void (async () => {
+    try {
+      const { getPermissionsService } = await import(
+        "@gotgenes/pi-permission-system"
+      );
+      const permissions = getPermissionsService();
+      disposeFormatter = permissions?.registerToolInputFormatter(
+        "deploy", // a tool THIS extension registers with Pi
+        (input) => {
+          const target =
+            typeof input.target === "string" ? input.target : undefined;
+          const services = Array.isArray(input.services)
+            ? input.services.length
+            : undefined;
+          if (!target) return undefined; // decline → default preview
+          return services !== undefined
+            ? `with target ${target} (${services} services)`
+            : `with target ${target}`;
+        },
+      );
+    } catch {
+      // permission-system not installed — nothing to register
+    }
+  })();
+
+  pi.on("session_shutdown", () => {
+    disposeFormatter?.();
+    disposeFormatter = undefined;
+  });
+}
+```
+
+Reload note: on `/reload`, the permission-system publishes a fresh service backed by a new registry, so previous registrations are dropped.
+Re-register on every initialization (as above) rather than once globally; the disposer is for explicit teardown within a single load.
+
+##### Recommended practices
+
+- Keep previews short — they appear inline in a yes/no prompt, and the result is truncated by the configured preview length anyway.
+- Never surface secrets (tokens, keys, full request bodies) in a preview; summarize counts and identifiers instead.
+- Parse defensively and return `undefined` on malformed input — never throw.
+- Return a grammatical fragment, not raw JSON or a full sentence.
+- Register idempotently on each extension load; dispose on `session_shutdown`.
+
+##### Built-in MCP summarizer
+
+A built-in formatter is registered for the `"mcp"` tool at startup (through this same public API).
+It renders a compact `with key: value, …` summary of the call's `arguments` and returns `undefined` when there are no arguments, leaving the MCP target prompt unchanged.
+This is the reference implementation for the seam — see `src/builtin-tool-input-formatters.ts`.
+
+#### `registerToolAccessExtractor`
+
+Declare the filesystem path a tool will access so the cross-cutting `path` and `external_directory` gates can evaluate it.
+
+```typescript
+registerToolAccessExtractor(
+  toolName: string,
+  extractor: (input: Record<string, unknown>) => string | undefined,
+): () => void; // returns a disposer
+```
+
+You usually do **not** need this.
+Path gating is on by default for every tool whose input follows the convention:
+
+- Built-in file tools (`read`, `write`, `edit`, `find`, `grep`, `ls`) and any tool exposing `input.path` are extracted automatically.
+- MCP calls are extracted from `input.arguments.path`.
+- `bash` is never extracted here — it has its own token-based path gates.
+
+Register an extractor only when a tool carries its path under a **non-standard key** (e.g. `input.target` or `input.file`).
+Return the path string, or `undefined` to decline.
+
+```typescript
+const dispose = permissions.registerToolAccessExtractor("ffgrep", (input) =>
+  typeof input.target === "string" ? input.target : undefined,
+);
+```
+
+Registration rules mirror `registerToolInputFormatter`: one extractor per tool name (a second `register` for the same name throws), and the returned disposer is identity-guarded.
+The extractor must not throw — guard your parsing and return `undefined` on anything unexpected.
+
+#### Subagent session registration
+
+In-process subagent registration is event-driven.
+`@gotgenes/pi-subagents` emits `subagents:child:session-created` before `bindExtensions()` and `subagents:child:disposed` in the run's `finally`; the permission system subscribes automatically — no service call from the spawner is required.
+See [Subagent Integration](subagent-integration.md) for details.
+
+### Reload Safety
+
+During `/reload`, all extensions re-initialize.
+The permission-system re-publishes a fresh service at `session_start`; teardown is identity-scoped, so a superseded generation's shutdown only clears the slot when it still owns it and cannot wipe the new service.
+Consumers that re-initialize during reload naturally get the new instance.
+
+Best practice: call `getPermissionsService()` per use rather than caching the reference.
+
+### Graceful Degradation
+
+`getPermissionsService()` returns `undefined` when the permission-system extension has not loaded (or has been unloaded).
+The `import()` throws if the package is not installed.
+Wrap both in `try/catch` + `if` guard as shown in the Quick Start example.
+
+---
+
+## Event Bus
+
+The extension also emits events on Pi's `pi.events` bus so other extensions can observe permission decisions and integrate with the policy system without importing this package.
+
+## Stability Guarantee
+
+Fields may be added to any payload, but existing fields will not be removed or renamed without a semver-major version bump.
+The broadcast contract is defined by the published TypeScript types plus package semver — broadcast payloads (`permissions:ready`, `permissions:ui_prompt`, `permissions:decision`) carry no `protocolVersion`.
+The `PERMISSIONS_PROTOCOL_VERSION` constant is exported from `src/permission-events.ts` and embedded only in the RPC reply envelope, where per-call request/reply negotiation is load-bearing.
+Consumers should read broadcast payloads defensively (field-presence checks) rather than version-gating — that is robust to any shape skew between independently-versioned sibling extensions.
+
+All three broadcasts are best-effort: a throwing listener cannot block permission handling, session startup, or gate resolution.
+
+## Channel Reference
+
+| Channel                                    | Direction | When                              | Payload type                                      |
+| ------------------------------------------ | --------- | --------------------------------- | ------------------------------------------------- |
+| `permissions:ready`                        | Broadcast | At `session_start`, after publish | `PermissionsReadyEvent`                           |
+| `permissions:ui_prompt`                    | Broadcast | Before active UI prompt           | `PermissionUiPromptEvent`                         |
+| `permissions:decision`                     | Broadcast | After every gate resolution       | `PermissionDecisionEvent`                         |
+| `permissions:rpc:check`                    | Request   | On-demand                         | `PermissionsCheckRequest`                         |
+| `permissions:rpc:check:reply:<requestId>`  | Reply     | After each check request          | `PermissionsRpcReply<PermissionsCheckReplyData>`  |
+| `permissions:rpc:prompt`                   | Request   | On-demand                         | `PermissionsPromptRequest`                        |
+| `permissions:rpc:prompt:reply:<requestId>` | Reply     | After prompt is resolved          | `PermissionsRpcReply<PermissionsPromptReplyData>` |
+
+---
+
+## UI Prompt Broadcasts
+
+The permission system emits `permissions:ui_prompt` immediately before it invokes the active user-facing permission UI.
+This event is for integrations such as notification extensions that should alert only when the user needs to respond to a permission prompt.
+It is not a generic "permission request entered waiting state" event, and it does not imply the prompt will be approved.
+Policy decisions that resolve without an active UI prompt, such as `policy_allow`, `policy_deny`, `session_approved`, `infrastructure_auto_allowed`, or `auto_approved`, do not emit this event.
+Non-UI child sessions also do not emit this event when they create a forwarded permission request; the parent UI session emits it immediately before showing the forwarded permission dialog.
+Forwarded prompts are not degraded: the parent emits the child's original `source` and the same `surface`/`value` display projection, plus a populated `forwarding` context identifying the requesting subagent.
+
+The payload is lean by design — `surface`/`value` are the normalized display projection a notification consumer reads, not a mirror of the internal review log.
+Read defensively rather than version-gating: broadcast payloads carry no `protocolVersion`.
+
+```typescript
+import type { PermissionUiPromptEvent } from "@gotgenes/pi-permission-system";
+
+pi.events.on("permissions:ui_prompt", (raw) => {
+  const event = raw as PermissionUiPromptEvent;
+  // Defensive read: tolerate any shape skew between sibling extensions.
+  if (typeof event.value !== "string" && typeof event.message !== "string") {
+    return;
+  }
+  notify(event.surface, event.value, event.message);
+  // e.g. "bash" "git push" "Allow git push?"
+});
+```
+
+### Payload Fields
+
+| Field        | Type                             | Description                                                                      |
+| ------------ | -------------------------------- | -------------------------------------------------------------------------------- |
+| `requestId`  | `string`                         | Unique ID for the permission request being prompted                              |
+| `source`     | `PermissionUiPromptSource`       | Prompt origin: `"tool_call"`, `"skill_input"`, `"skill_read"`, or `"rpc_prompt"` |
+| `surface`    | `string \| null`                 | Normalized display surface (e.g. `"bash"`, `"skill"`), when known                |
+| `value`      | `string \| null`                 | Normalized display value (command, path, skill name, etc.), when known           |
+| `agentName`  | `string \| null`                 | Active/requesting agent name, when known                                         |
+| `message`    | `string`                         | Message displayed in the permission prompt                                       |
+| `forwarding` | `ForwardedPromptContext \| null` | Forwarding context, or `null` for a direct 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.
+
+#### `ForwardedPromptContext`
+
+Present only when the prompt was forwarded from a non-UI subagent.
+
+| Field                | Type             | Description                                    |
+| -------------------- | ---------------- | ---------------------------------------------- |
+| `requesterAgentName` | `string \| null` | Requesting subagent's display name, when known |
+| `requesterSessionId` | `string \| null` | Requesting subagent's session id, when known   |
+
+The `surface`/`value` pair is a deliberate display projection that replaces the redundant per-source fields (`command`/`path`/`target`/`skillName`/`toolName`/`toolCallId`/`toolInputPreview`/`sessionLabel`) from earlier drafts — none of which the notification use case reads.
+The stability guarantee is additive, so any can be reintroduced in a later minor when a concrete consumer needs them.
+
+---
+
+## Decision Broadcasts
+
+Every permission gate resolution emits a `permissions:decision` event, regardless of outcome.
+This is useful for dashboards, telemetry, or audit overlays.
+
+```typescript
+pi.events.on("permissions:decision", (raw) => {
+  const event = raw as import("@gotgenes/pi-permission-system").PermissionDecisionEvent;
+  console.log(event.surface, event.result, event.resolution);
+  // e.g. "bash" "allow" "user_approved_for_session"
+});
+```
+
+### Payload Fields
+
+| Field            | Type                | Description                                                                               |
+| ---------------- | ------------------- | ----------------------------------------------------------------------------------------- |
+| `surface`        | `string`            | Permission surface (`"bash"`, `"read"`, `"mcp"`, `"skill"`, `"external_directory"`, etc.) |
+| `value`          | `string`            | Value evaluated (command, tool name, skill name, path)                                    |
+| `result`         | `"allow" \| "deny"` | Final outcome                                                                             |
+| `resolution`     | `string`            | How the outcome was reached (see table below)                                             |
+| `origin`         | `string \| null`    | Config scope that contributed the winning rule                                            |
+| `agentName`      | `string \| null`    | Active agent name when known                                                              |
+| `matchedPattern` | `string \| null`    | Pattern from the winning rule                                                             |
+
+### Resolution Values
+
+| Value                         | Meaning                                                              |
+| ----------------------------- | -------------------------------------------------------------------- |
+| `policy_allow`                | Config rule said allow — no prompt shown                             |
+| `policy_deny`                 | Config rule said deny — blocked immediately                          |
+| `session_approved`            | Covered by a session-level approval from earlier in the same session |
+| `infrastructure_auto_allowed` | Read of a Pi infrastructure path — auto-allowed                      |
+| `user_approved`               | User approved once via dialog                                        |
+| `user_approved_for_session`   | User approved for the rest of the session                            |
+| `user_denied`                 | User denied via dialog                                               |
+| `auto_approved`               | Yolo mode — approved automatically without dialog                    |
+| `confirmation_unavailable`    | State was `ask` but no UI was available — blocked                    |
+
+---
+
+## Policy Query RPC (deprecated)
+
+> **Deprecated**: prefer the [Service Accessor](#service-accessor) above.
+> The event-bus RPC remains available as a zero-dependency fallback.
+
+Other extensions can evaluate the current permission policy without importing this package.
+The call is synchronous-style: emit a request, listen on a scoped reply channel.
+
+```typescript
+const requestId = crypto.randomUUID();
+
+// Listen for the reply first
+const unsub = pi.events.on(
+  `permissions:rpc:check:reply:${requestId}`,
+  (raw) => {
+    unsub();
+    const reply = raw as import("@gotgenes/pi-permission-system").PermissionsRpcReply<
+      import("@gotgenes/pi-permission-system").PermissionsCheckReplyData
+    >;
+    if (reply.success) {
+      console.log(reply.data?.result); // "allow" | "deny" | "ask"
+    }
+  },
+);
+
+// Then emit the request
+pi.events.emit("permissions:rpc:check", {
+  requestId,
+  surface: "bash",
+  value: "git push",
+  agentName: "Worker", // optional
+});
+```
+
+If the extension is not loaded, no reply arrives.
+Callers should implement a timeout and treat no-reply as `deny` (graceful degradation).
+
+### Request Fields
+
+| Field       | Required | Description                                                |
+| ----------- | -------- | ---------------------------------------------------------- |
+| `requestId` | Yes      | Unique string; scopes the reply channel                    |
+| `surface`   | Yes      | Permission surface to evaluate                             |
+| `value`     | No       | Value to evaluate (command, name, path); defaults to `"*"` |
+| `agentName` | No       | Agent name for per-agent policy resolution                 |
+
+As with the `checkPermission` service method, a path-shaped surface (`path`, `external_directory`, or a path-bearing tool) matches the `value` against both the path as given and its canonical (symlink-resolved) form.
+
+### Reply Data Fields (`PermissionsCheckReplyData`)
+
+| Field            | Type                         | Description                                      |
+| ---------------- | ---------------------------- | ------------------------------------------------ |
+| `result`         | `"allow" \| "deny" \| "ask"` | Policy decision (including active session rules) |
+| `matchedPattern` | `string \| null`             | Matched rule pattern                             |
+| `origin`         | `string \| null`             | Config scope of the winning rule                 |
+
+---
+
+## Prompt Forwarding RPC
+
+In-process child sessions (e.g. tintinweb/pi-subagents running via `createAgentSession()`) cannot use file-based permission forwarding because no child process is spawned.
+They can instead forward permission prompts to the parent session's UI via this RPC.
+
+```typescript
+const requestId = crypto.randomUUID();
+
+const unsub = pi.events.on(
+  `permissions:rpc:prompt:reply:${requestId}`,
+  (raw) => {
+    unsub();
+    const reply = raw as import("@gotgenes/pi-permission-system").PermissionsRpcReply<
+      import("@gotgenes/pi-permission-system").PermissionsPromptReplyData
+    >;
+    if (reply.success && reply.data?.approved) {
+      // proceed
+    } else {
+      // deny — either user denied or no UI was available (error: "no_ui")
+    }
+  },
+);
+
+pi.events.emit("permissions:rpc:prompt", {
+  requestId,
+  surface: "bash",
+  value: "rm -rf /tmp/build",
+  message: "Allow rm -rf /tmp/build?",
+  agentName: "Explore",      // optional
+  sessionLabel: "Allow rm *", // optional — label for the "for this session" option
+});
+```
+
+The handler replies with `{ success: false, error: "no_ui" }` when no interactive session is available.
+
+### Successful Reply Fields
+
+| Field          | Type                | Description                                                                   |
+| -------------- | ------------------- | ----------------------------------------------------------------------------- |
+| `approved`     | `boolean`           | Whether the user approved                                                     |
+| `state`        | `string`            | `"approved"`, `"approved_for_session"`, `"denied"`, or `"denied_with_reason"` |
+| `denialReason` | `string` (optional) | User-provided denial reason                                                   |
+
+---
+
+## Ready Event
+
+The extension emits `permissions:ready` at `session_start`, right after the service is published — so a consumer reacting to it can immediately resolve `getPermissionsService()`.
+It fires once per `session_start` (including `/reload`).
+Consumers that start after the extension can check via a ping-style RPC check — the `permissions:rpc:check` handler is active as long as the extension is loaded.
+
+The payload is intentionally empty (`Record<string, never>`): the channel is a pure readiness signal.
+It carries no `protocolVersion` — version negotiation lives in the RPC reply envelope, and the broadcast contract is defined by the published types plus package semver.
+
+```typescript
+pi.events.on("permissions:ready", () => {
+  void (async () => {
+    const { getPermissionsService } = await import(
+      "@gotgenes/pi-permission-system"
+    );
+    const permissions = getPermissionsService();
+    // The service is published just before this fires — resolve it now.
+  })();
+});
+```