@gotgenes/pi-permission-system 19.0.0 → 20.0.0

package/CHANGELOG.md

@@ -5,6 +5,29 @@ 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).
 
+## [20.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v19.0.1...pi-permission-system-v20.0.0) (2026-07-07)
+
+
+### ⚠ BREAKING CHANGES
+
+* **pi-permission-system:** The permissions:rpc:check and permissions:rpc:prompt event-bus channels are removed, along with their request/reply types (PermissionsCheckRequest, PermissionsCheckReplyData, PermissionsPromptRequest, PermissionsPromptReplyData), the PermissionsRpcReply envelope, PERMISSIONS_PROTOCOL_VERSION, and the rpc_prompt member of PermissionUiPromptSource. permissions:rpc:check consumers migrate to getPermissionsService().checkPermission(surface, value?, agentName?). permissions:rpc:prompt is removed with no public replacement; prompt forwarding is an internal subagent-to-parent mechanism.
+
+### Features
+
+* **pi-permission-system:** remove deprecated event-bus RPC channel ([557ea91](https://github.com/gotgenes/pi-packages/commit/557ea913c54f21ef64b0812169bbc7d5224072e2))
+
+
+### Documentation
+
+* **pi-permission-system:** repoint cross-extension docs off the removed RPC channel ([b3d06f7](https://github.com/gotgenes/pi-packages/commit/b3d06f77aea43758a4e820e66d1111608b86879b)), closes [#531](https://github.com/gotgenes/pi-packages/issues/531)
+
+## [19.0.1](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v19.0.0...pi-permission-system-v19.0.1) (2026-07-07)
+
+
+### Documentation
+
+* **pi-permission-system:** mark Phase 8 Step 6 complete; retarget forwarder docs ([c11d8a2](https://github.com/gotgenes/pi-packages/commit/c11d8a2653edbac3637e45c1e5c5867f0a882afe))
+
 ## [19.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v18.2.0...pi-permission-system-v19.0.0) (2026-07-06)
 
 

package/docs/cross-extension-api.md

@@ -3,14 +3,14 @@
 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.
+2. **Event bus** — broadcasts on `pi.events` for observation.
 
 ---
 
 ## 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.
+It provides direct, synchronous, type-safe function calls.
 
 ### Quick Start
 
@@ -286,22 +286,17 @@ The extension also emits events on Pi's `pi.events` bus so other extensions can
 
 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>` |
+| 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` |
 
 ---
 
@@ -333,15 +328,15 @@ pi.events.on("permissions:ui_prompt", (raw) => {
 
 ### 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                                |
+| Field        | Type                             | Description                                                            |
+| ------------ | -------------------------------- | ---------------------------------------------------------------------- |
+| `requestId`  | `string`                         | Unique ID for the permission request being prompted                    |
+| `source`     | `PermissionUiPromptSource`       | Prompt origin: `"tool_call"`, `"skill_input"`, or `"skill_read"`       |
+| `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.
 
@@ -400,117 +395,13 @@ pi.events.on("permissions:decision", (raw) => {
 
 ---
 
-## 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.
+It carries no `protocolVersion` — the broadcast contract is defined by the published types plus package semver.
 
 ```typescript
 pi.events.on("permissions:ready", () => {

package/docs/guides/permission-frontmatter-for-subagent-extensions.md

@@ -127,61 +127,29 @@ The permission system handles all evaluation, prompt dialogs, and policy enforce
 
 ## Runtime Integration (Optional)
 
-If your extension runs subagents in-process (e.g. via `createAgentSession()`), you can optionally query the permission system's policy at runtime via the event bus API — no package import needed.
+If your extension runs subagents in-process (e.g. via `createAgentSession()`), you can optionally query the permission system's policy at runtime via the `Symbol.for()`-backed service accessor — no required peer dependency, just a dynamic `import()`.
 
 ### Querying policy
 
 ```typescript
-const requestId = crypto.randomUUID();
-
-pi.events.on(
-  `permissions:rpc:check:reply:${requestId}`,
-  (raw) => {
-    const reply = raw as { success: boolean; data?: { result: string } };
-    if (reply.success) {
-      console.log(reply.data?.result); // "allow" | "deny" | "ask"
-    }
-  },
-);
-
-pi.events.emit("permissions:rpc:check", {
-  requestId,
-  surface: "bash",
-  value: "git push",
-  agentName: "Worker",
-});
+try {
+  const { getPermissionsService } = await import(
+    "@gotgenes/pi-permission-system"
+  );
+  const permissions = getPermissionsService();
+  if (permissions) {
+    const result = permissions.checkPermission("bash", "git push", "Worker");
+    console.log(result.state); // "allow" | "deny" | "ask"
+  }
+} catch {
+  // Not installed — graceful degradation
+}
 ```
 
-### Forwarding permission prompts
+If `pi-permission-system` is not installed, `import()` throws; if it has not published a service yet (or has been unloaded), `getPermissionsService()` returns `undefined`.
+Guard both cases as shown above.
 
-When a child agent encounters an `ask` permission and has no UI, the prompt can be forwarded to the parent session:
-
-```typescript
-const requestId = crypto.randomUUID();
-
-pi.events.on(
-  `permissions:rpc:prompt:reply:${requestId}`,
-  (raw) => {
-    const reply = raw as { success: boolean; data?: { approved: boolean } };
-    if (reply.success && reply.data?.approved) {
-      // proceed
-    } else {
-      // deny
-    }
-  },
-);
-
-pi.events.emit("permissions:rpc:prompt", {
-  requestId,
-  surface: "bash",
-  value: "rm -rf /tmp/build",
-  message: "Allow rm -rf /tmp/build?",
-  agentName: "Worker",
-});
-```
-
-If `pi-permission-system` is not installed, no reply arrives.
-Implement a timeout and treat no-reply as `deny` for graceful degradation.
+Prompt forwarding for headless child agents is an internal subagent-to-parent mechanism, not a public cross-extension operation — there is no service-accessor equivalent to call directly.
 
 For full API documentation, see [Cross-extension API](../cross-extension-api.md).
 
@@ -191,11 +159,11 @@ For full API documentation, see [Cross-extension API](../cross-extension-api.md)
 2. **Unified config** — one `permission:` block per agent instead of separate restriction keys in multiple extensions.
 3. **Surface coverage** — policy covers bash patterns, MCP tools, skills, external directories, and special operations, not just tool names.
 4. **Forwarding** — permission prompts from headless child agents surface in the parent session's UI.
-5. **Programmatic access** — the event bus API lets your extension query policy at runtime without importing the package.
+5. **Programmatic access** — the `Symbol.for()` service accessor lets your extension query policy at runtime with only a dynamic `import()`, no required peer dependency.
 
 ## Further Reading
 
 - [Subagent Integration](../subagent-integration.md) — full coexistence documentation and interaction rules
-- [Cross-extension API](../cross-extension-api.md) — service accessor, event bus reference (decision broadcasts, RPC check, RPC prompt)
+- [Cross-extension API](../cross-extension-api.md) — service accessor, event bus reference (decision and UI-prompt broadcasts)
 - [Configuration](../configuration.md) — full policy reference including merge precedence
 - [Schema](../../schemas/permissions.schema.json) — canonical JSON Schema for the flat permission format

package/docs/guides/upstream-issue-template.md

@@ -31,7 +31,7 @@ This is purely a documentation change — no code dependency on pi-permission-sy
 - **Three-state policy**: `allow`, `ask` (prompt the user), or `deny` — richer than binary allow/deny
 - **Multiple surfaces**: tools, bash commands (glob patterns), MCP operations, skills, external directories
 - **Prompt forwarding**: `ask` decisions in headless child agents surface in the parent session's UI
-- **Event bus API**: other extensions can query policy at runtime without importing the package
+- **Service accessor API**: other extensions can query policy at runtime via a `Symbol.for()`-backed accessor, with only a dynamic `import()` and no required peer dependency
 
 ### Example
 
@@ -99,7 +99,7 @@ No code changes, no new dependency, no schema enforcement.
 | `{{your-key}}`       | `disallowed_tools` |
 | `{{example-value}}`  | `write_file,bash`  |
 
-Additional note for tintinweb: since this extension runs subagents in-process via `createAgentSession()`, mention the [Event Bus RPC](https://github.com/gotgenes/pi-permission-system/blob/main/docs/cross-extension-api.md#policy-query-rpc-deprecated) as an optional runtime integration path for querying or forwarding permission prompts without spawning a subprocess.
+Additional note for tintinweb: since this extension runs subagents in-process via `createAgentSession()`, mention the [service accessor](https://github.com/gotgenes/pi-permission-system/blob/main/docs/cross-extension-api.md#service-accessor) as an optional runtime integration path for querying policy without spawning a subprocess.
 
 ### HazAT/pi-interactive-subagents
 

package/docs/subagent-integration.md

@@ -29,7 +29,6 @@ The main interactive session polls for forwarded requests, shows the confirmatio
 This keeps `ask` policies usable even when the original permission check happens inside a non-UI execution context.
 
 For in-process child sessions, detection and forwarding use the event-driven registration described above.
-The [Prompt Forwarding RPC](cross-extension-api.md#prompt-forwarding-rpc) remains available as an alternative for extensions that cannot use the service accessor.
 
 ---
 

package/package.json

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