@gotgenes/pi-permission-system 9.2.0 → 10.0.0

package/CHANGELOG.md

@@ -5,6 +5,32 @@ 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).
 
+## [10.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v9.2.0...pi-permission-system-v10.0.0) (2026-06-02)
+
+
+### ⚠ BREAKING CHANGES
+
+* **pi-permission-system:** the permissions:ready event payload no longer includes protocolVersion. Consumers that read it must rely on package semver instead.
+
+### Features
+
+* **pi-permission-manager:** broadcast permission prompts on permissions:prompt channel ([8540f3b](https://github.com/gotgenes/pi-packages/commit/8540f3b462b76a4789c4c17a75fadf254ae39feb))
+* **pi-permission-system:** drop protocolVersion from permissions:ready ([6728a93](https://github.com/gotgenes/pi-packages/commit/6728a93af7edbc6953d20f448f1c3f54f9b7893f))
+* **pi-permission-system:** harden prompt broadcasts ([067bafd](https://github.com/gotgenes/pi-packages/commit/067bafd80ef983fd8b9ab00914cf1cec9b6db915))
+* **pi-permission-system:** make ready and decision broadcasts best-effort ([00a895f](https://github.com/gotgenes/pi-packages/commit/00a895f9377bcb7b598acbc6c95d7bc7cc83c515))
+* **pi-permission-system:** preserve display fields for forwarded prompts ([9970912](https://github.com/gotgenes/pi-packages/commit/997091228736bbd4395d8bd16aeb9f4a4ae7e0b2))
+* **pi-permission-system:** slim ui_prompt payload and centralize construction ([7a1ec56](https://github.com/gotgenes/pi-packages/commit/7a1ec56a827e90fe80a0f7de48e1222b5271700d))
+
+
+### Bug Fixes
+
+* **pi-permission-system:** drop manual CHANGELOG Unreleased section ([f14e4f5](https://github.com/gotgenes/pi-packages/commit/f14e4f5d9b5ae1d6b207a913aefdd71980a46dd6))
+
+
+### Documentation
+
+* **pi-permission-system:** document the lean ui_prompt contract ([0b3c11c](https://github.com/gotgenes/pi-packages/commit/0b3c11c57a7b718d2f73a184802f8c5dcb95fbe7))
+
 ## [9.2.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v9.1.0...pi-permission-system-v9.2.0) (2026-06-02)
 
 

package/README.md

@@ -20,6 +20,7 @@ Permission enforcement extension for the [Pi](https://pi.mariozechner.at/) codin
 - **Protects sensitive file patterns** — cross-cutting `path` rules deny `.env`, `~/.ssh/*`, etc. across all tools and bash at once
 - **Guards external paths** — prompts before file tools or bash commands reach outside `cwd`
 - **Forwards prompts from subagents** — `ask` policies work even in non-UI execution contexts
+- **Broadcasts UI prompt events** — `permissions:ui_prompt` fires only when the permission system is about to invoke the active user-facing permission UI
 - **Native [`@gotgenes/pi-subagents`](https://github.com/gotgenes/pi-subagents) integration** — in-process child sessions register with the permission system automatically, enabling per-agent policy enforcement and `ask`-state forwarding to the parent UI without configuration
 
 ## Install
@@ -89,16 +90,16 @@ For the full reference — all surfaces, runtime knobs, per-agent overrides, mer
 
 ## Documentation
 
-| Document                                                                                                                       | Contents                                                                     |
-| ------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- |
-| [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/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         |
-| [docs/troubleshooting.md](docs/troubleshooting.md)                                                                             | Common issues, diagnostic logging, threat model                              |
-| [docs/migration/legacy-to-flat.md](docs/migration/legacy-to-flat.md)                                                           | Migration from pre-v2 config layout                                          |
+| Document                                                                                                                       | Contents                                                                                |
+| ------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------- |
+| [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/cross-extension-api.md](docs/cross-extension-api.md)                                                                     | Cross-extension service accessor, event bus integration, prompt and 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                    |
+| [docs/troubleshooting.md](docs/troubleshooting.md)                                                                             | Common issues, diagnostic logging, threat model                                         |
+| [docs/migration/legacy-to-flat.md](docs/migration/legacy-to-flat.md)                                                           | Migration from pre-v2 config layout                                                     |
 
 ## Development
 

package/package.json

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

package/src/forwarded-permissions/io.ts

@@ -10,6 +10,7 @@ import {
 } from "node:fs";
 
 import { isPermissionDecisionState } from "#src/permission-dialog";
+import type { PermissionUiPromptSource } from "#src/permission-events";
 import {
   createPermissionForwardingLocation,
   type ForwardedPermissionRequest,
@@ -17,6 +18,29 @@ import {
   type PermissionForwardingLocation,
 } from "#src/permission-forwarding";
 
+/** Valid `permissions:ui_prompt` source values, for tolerant request reads. */
+const UI_PROMPT_SOURCES = [
+  "tool_call",
+  "skill_input",
+  "skill_read",
+  "rpc_prompt",
+] as const satisfies readonly PermissionUiPromptSource[];
+
+/** Narrow an unknown value to a valid prompt source, or `undefined`. */
+function asUiPromptSource(
+  value: unknown,
+): PermissionUiPromptSource | undefined {
+  return UI_PROMPT_SOURCES.find((source) => source === value);
+}
+
+/** Narrow an unknown value to a nullable display string, or `undefined`. */
+function asNullableDisplayString(value: unknown): string | null | undefined {
+  if (value === null || typeof value === "string") {
+    return value;
+  }
+  return undefined;
+}
+
 type LogFn = (event: string, details: Record<string, unknown>) => void;
 
 export interface ForwardedPermissionLogger {
@@ -285,6 +309,11 @@ export function readForwardedPermissionRequest(
       targetSessionId: parsed.targetSessionId,
       requesterAgentName: parsed.requesterAgentName,
       message: parsed.message,
+      // Tolerant read: display fields are optional and may be absent (older
+      // child) or malformed; reconstruct only the well-formed ones.
+      source: asUiPromptSource(parsed.source),
+      surface: asNullableDisplayString(parsed.surface),
+      value: asNullableDisplayString(parsed.value),
     };
   } catch (error) {
     logPermissionForwardingWarning(

package/src/forwarded-permissions/polling.ts

@@ -11,15 +11,21 @@ import type {
   PermissionPromptDecision,
   RequestPermissionOptions,
 } from "#src/permission-dialog";
+import {
+  emitUiPromptEvent,
+  type PermissionEventBus,
+} from "#src/permission-events";
 import {
   type ForwardedPermissionRequest,
   type ForwardedPermissionResponse,
+  type ForwardedPromptDisplay,
   isForwardedPermissionRequestForSession,
   PERMISSION_FORWARDING_POLL_INTERVAL_MS,
   PERMISSION_FORWARDING_TIMEOUT_MS,
   resolvePermissionForwardingTargetSessionId,
   SUBAGENT_PARENT_SESSION_ENV_CANDIDATES,
 } from "#src/permission-forwarding";
+import { buildForwardedUiPrompt } from "#src/permission-ui-prompt";
 import { isSubagentExecutionContext } from "#src/subagent-context";
 import type { SubagentSessionRegistry } from "#src/subagent-registry";
 
@@ -43,6 +49,8 @@ export interface PermissionForwardingDeps {
   subagentSessionsDir: string;
   /** In-process subagent session registry for detection and forwarding target resolution. */
   registry?: SubagentSessionRegistry;
+  /** Event bus used for UI prompt broadcasts. */
+  events?: PermissionEventBus;
   logger: ForwardedPermissionLogger;
   writeReviewLog: (event: string, details: Record<string, unknown>) => void;
   requestPermissionDecisionFromUi: (
@@ -103,6 +111,7 @@ export async function waitForForwardedPermissionApproval(
   ctx: ExtensionContext,
   message: string,
   deps: PermissionForwardingDeps,
+  forwarded?: ForwardedPromptDisplay,
 ): Promise<PermissionPromptDecision> {
   const requesterSessionId = getSessionId(ctx);
   const targetSessionId = resolvePermissionForwardingTargetSessionId({
@@ -155,6 +164,13 @@ export async function waitForForwardedPermissionApproval(
     targetSessionId,
     requesterAgentName,
     message,
+    ...(forwarded
+      ? {
+          source: forwarded.source,
+          surface: forwarded.surface,
+          value: forwarded.value,
+        }
+      : {}),
   };
 
   const requestPath = join(location.requestsDir, `${requestId}.json`);
@@ -296,10 +312,25 @@ export async function processForwardedPermissionRequests(
         forwardedPermissionLogDetails,
       );
       try {
+        const forwardedMessage = formatForwardedPermissionPrompt(request);
+        if (deps.events) {
+          emitUiPromptEvent(
+            deps.events,
+            buildForwardedUiPrompt({
+              requestId: request.id,
+              message: forwardedMessage,
+              requesterAgentName: request.requesterAgentName || null,
+              requesterSessionId: request.requesterSessionId || null,
+              source: request.source ?? null,
+              surface: request.surface ?? null,
+              value: request.value ?? null,
+            }),
+          );
+        }
         decision = await deps.requestPermissionDecisionFromUi(
           ctx.ui,
           "Permission Required (Subagent)",
-          formatForwardedPermissionPrompt(request),
+          forwardedMessage,
         );
       } catch (error) {
         logPermissionForwardingError(
@@ -359,6 +390,7 @@ export async function confirmPermission(
   message: string,
   deps: PermissionForwardingDeps,
   options?: RequestPermissionOptions,
+  forwarded?: ForwardedPromptDisplay,
 ): Promise<PermissionPromptDecision> {
   if (ctx.hasUI) {
     return deps.requestPermissionDecisionFromUi(
@@ -375,5 +407,5 @@ export async function confirmPermission(
     return { approved: false, state: "denied" };
   }
 
-  return waitForForwardedPermissionApproval(ctx, message, deps);
+  return waitForForwardedPermissionApproval(ctx, message, deps, forwarded);
 }

package/src/index.ts

@@ -54,6 +54,7 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
     subagentSessionsDir: runtime.subagentSessionsDir,
     forwardingDir: runtime.forwardingDir,
     registry: subagentRegistry,
+    events: pi.events,
     requestPermissionDecisionFromUi,
   });
 
@@ -61,6 +62,7 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
     forwardingDir: runtime.forwardingDir,
     subagentSessionsDir: runtime.subagentSessionsDir,
     registry: subagentRegistry,
+    events: pi.events,
     logger: {
       writeReviewLog: runtime.writeReviewLog.bind(runtime),
       writeDebugLog: runtime.writeDebugLog.bind(runtime),

package/src/permission-event-rpc.ts

@@ -21,11 +21,13 @@ import type {
   PermissionsRpcReply,
 } from "./permission-events";
 import {
+  emitUiPromptEvent,
   PERMISSIONS_PROTOCOL_VERSION,
   PERMISSIONS_RPC_CHECK_CHANNEL,
   PERMISSIONS_RPC_PROMPT_CHANNEL,
 } from "./permission-events";
 import type { PermissionManager } from "./permission-manager";
+import { buildRpcUiPrompt } from "./permission-ui-prompt";
 import type { Rule } from "./rule";
 
 /** Dependencies injected into the RPC handler registry. */
@@ -155,6 +157,11 @@ async function handlePromptRpc(
       ? `Permission request${agentName ? ` from ${agentName}` : ""}`
       : "Permission request";
 
+    emitUiPromptEvent(
+      events,
+      buildRpcUiPrompt({ requestId, surface, value, agentName, message }),
+    );
+
     const decision = await deps.requestPermissionDecisionFromUi(
       ctx.ui,
       title,

package/src/permission-events.ts

@@ -27,6 +27,9 @@ export const PERMISSIONS_PROTOCOL_VERSION = 1;
 /** Emitted at `session_start`, after the service is published. */
 export const PERMISSIONS_READY_CHANNEL = "permissions:ready";
 
+/** Emitted when a permission request is committed to the active UI prompt path. */
+export const PERMISSIONS_UI_PROMPT_CHANNEL = "permissions:ui_prompt";
+
 /** Emitted after every permission gate resolution. */
 export const PERMISSIONS_DECISION_CHANNEL = "permissions:decision";
 
@@ -61,9 +64,63 @@ export type PermissionsRpcReply<T = void> =
 
 // ── permissions:ready ──────────────────────────────────────────────────────
 
-/** Payload emitted on `permissions:ready`. */
-export interface PermissionsReadyEvent {
-  protocolVersion: number;
+/**
+ * Payload emitted on `permissions:ready`.
+ *
+ * Intentionally empty: the channel is a readiness signal. Version negotiation
+ * lives in the RPC envelope (`PermissionsRpcReply`), not in broadcast payloads —
+ * the published types plus package semver define the broadcast contract.
+ */
+export type PermissionsReadyEvent = Record<string, never>;
+
+// ── permissions:ui_prompt ──────────────────────────────────────────────────
+
+/**
+ * Origin of a UI 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.
+ */
+export type PermissionUiPromptSource =
+  | "tool_call"
+  | "skill_input"
+  | "skill_read"
+  | "rpc_prompt";
+
+/** Forwarding context, present only when a prompt was forwarded from a non-UI subagent. */
+export interface ForwardedPromptContext {
+  /** Requesting subagent's display name, when known. */
+  requesterAgentName: string | null;
+  /** Requesting subagent's session id, when known. */
+  requesterSessionId: string | null;
+}
+
+/**
+ * Payload emitted on `permissions:ui_prompt`, immediately before the active
+ * user-facing permission UI is shown.
+ *
+ * Lean by design: `surface`/`value` are the normalized display projection a
+ * notification consumer reads; `source` is the origin; `forwarding` is non-null
+ * only for forwarded subagent prompts. There is no `protocolVersion` — the
+ * published types plus package semver define the broadcast contract, and
+ * consumers should read defensively.
+ */
+export interface PermissionUiPromptEvent {
+  /** Unique ID for the permission request being prompted. */
+  requestId: string;
+  /** Prompt origin. */
+  source: PermissionUiPromptSource;
+  /** Normalized display surface (e.g. "bash", "skill"), when known. */
+  surface: string | null;
+  /** Normalized display value (command, path, skill name, etc.), when known. */
+  value: string | null;
+  /** Agent name (when known). */
+  agentName: string | null;
+  /** Message displayed to the user. */
+  message: string;
+  /** Forwarding context, or null for a direct prompt. */
+  forwarding: ForwardedPromptContext | null;
 }
 
 // ── permissions:decision ───────────────────────────────────────────────────
@@ -164,10 +221,29 @@ export interface PermissionsPromptReplyData {
  * reacting to ready can immediately resolve `getPermissionsService()`.
  */
 export function emitReadyEvent(events: PermissionEventBus): void {
-  const payload: PermissionsReadyEvent = {
-    protocolVersion: PERMISSIONS_PROTOCOL_VERSION,
-  };
-  events.emit(PERMISSIONS_READY_CHANNEL, payload);
+  const payload: PermissionsReadyEvent = {};
+  try {
+    events.emit(PERMISSIONS_READY_CHANNEL, payload);
+  } catch {
+    // Broadcasts are best-effort. A throwing listener must not block the
+    // permission system from completing session startup.
+  }
+}
+
+/**
+ * Emit a `permissions:ui_prompt` broadcast.
+ * Call immediately before invoking the active user-facing permission UI.
+ */
+export function emitUiPromptEvent(
+  events: PermissionEventBus,
+  event: PermissionUiPromptEvent,
+): void {
+  try {
+    events.emit(PERMISSIONS_UI_PROMPT_CHANNEL, event);
+  } catch {
+    // UI-prompt broadcasts are observational. A consumer failure must not block
+    // the permission dialog itself.
+  }
 }
 
 /**
@@ -178,5 +254,10 @@ export function emitDecisionEvent(
   events: PermissionEventBus,
   event: PermissionDecisionEvent,
 ): void {
-  events.emit(PERMISSIONS_DECISION_CHANNEL, event);
+  try {
+    events.emit(PERMISSIONS_DECISION_CHANNEL, event);
+  } catch {
+    // Broadcasts are best-effort. A throwing listener must not block the
+    // permission gate from resolving.
+  }
 }

package/src/permission-forwarding.ts

@@ -1,6 +1,7 @@
 import { join } from "node:path";
 
 import type { PermissionDecisionState } from "./permission-dialog";
+import type { PermissionUiPromptSource } from "./permission-events";
 import type { SubagentSessionRegistry } from "./subagent-registry";
 
 export const PERMISSION_FORWARDING_POLL_INTERVAL_MS = 250;
@@ -38,6 +39,19 @@ const SESSION_FORWARDING_ROOT_DIRECTORY_NAME = "sessions";
 const SESSION_FORWARDING_REQUESTS_DIRECTORY_NAME = "requests";
 const SESSION_FORWARDING_RESPONSES_DIRECTORY_NAME = "responses";
 
+/**
+ * Display fields relayed from a forwarding child to the parent UI so the parent
+ * can emit a non-degraded `permissions:ui_prompt` event.
+ *
+ * Carried separately from the prompt message because the parent reconstructs
+ * the original event through `buildForwardedUiPrompt`, not from the message text.
+ */
+export interface ForwardedPromptDisplay {
+  source: PermissionUiPromptSource;
+  surface: string | null;
+  value: string | null;
+}
+
 export type ForwardedPermissionRequest = {
   id: string;
   createdAt: number;
@@ -45,6 +59,15 @@ export type ForwardedPermissionRequest = {
   targetSessionId: string;
   requesterAgentName: string;
   message: string;
+  /**
+   * Original prompt display fields, persisted so the parent emits a
+   * non-degraded event. Optional for version-skew tolerance: a parent on a
+   * newer version may read a request written by an older child during an
+   * upgrade, in which case the reader defaults `source` to `"tool_call"`.
+   */
+  source?: PermissionUiPromptSource;
+  surface?: string | null;
+  value?: string | null;
 };
 
 export type ForwardedPermissionResponse = {

package/src/permission-prompter.ts

@@ -9,6 +9,11 @@ import type {
   PermissionPromptDecision,
   RequestPermissionOptions,
 } from "./permission-dialog";
+import {
+  emitUiPromptEvent,
+  type PermissionEventBus,
+} from "./permission-events";
+import { buildDirectUiPrompt } from "./permission-ui-prompt";
 import type { SubagentSessionRegistry } from "./subagent-registry";
 import { shouldAutoApprovePermissionState } from "./yolo-mode";
 
@@ -57,6 +62,8 @@ export interface PermissionPrompterDeps {
   forwardingDir: string;
   /** In-process subagent session registry for detection and forwarding target resolution. */
   registry?: SubagentSessionRegistry;
+  /** Event bus used for UI prompt broadcasts. */
+  events: PermissionEventBus;
   /** Show the interactive permission dialog in the UI. */
   requestPermissionDecisionFromUi(
     ui: ExtensionContext["ui"],
@@ -91,11 +98,25 @@ export class PermissionPrompter implements PermissionPrompterApi {
 
     this.writeReviewEntry("permission_request.waiting", details);
 
+    // Build the event once. When this session has UI it broadcasts directly;
+    // when it does not (a forwarding subagent), the display fields ride along
+    // to the parent so the parent emits a non-degraded event from the
+    // forwarded path instead of here.
+    const uiPrompt = buildDirectUiPrompt(details);
+    if (ctx.hasUI) {
+      emitUiPromptEvent(this.deps.events, uiPrompt);
+    }
+
     const decision = await confirmPermission(
       ctx,
       details.message,
       this.buildForwardingDeps(),
       details.sessionLabel ? { sessionLabel: details.sessionLabel } : undefined,
+      {
+        source: uiPrompt.source,
+        surface: uiPrompt.surface,
+        value: uiPrompt.value,
+      },
     );
 
     this.writeReviewEntry(
@@ -159,6 +180,7 @@ export class PermissionPrompter implements PermissionPrompterApi {
       forwardingDir: deps.forwardingDir,
       subagentSessionsDir: deps.subagentSessionsDir,
       registry: deps.registry,
+      events: deps.events,
       logger,
       // eslint-disable-next-line @typescript-eslint/unbound-method -- logger methods are plain function closures; no this-binding issue
       writeReviewLog: deps.writeReviewLog,

package/src/permission-ui-prompt.ts

@@ -0,0 +1,127 @@
+/**
+ * Centralized construction for `permissions:ui_prompt` payloads.
+ *
+ * Every emit site builds its event through one of these functions, so the
+ * public contract's shape — including the normalized `surface`/`value`
+ * projection — lives in exactly one place and cannot drift by source.
+ *
+ * This module is a leaf: it owns narrow input types that each call site's
+ * domain object satisfies structurally, so it imports nothing from the
+ * prompter, RPC, or forwarding modules (no import cycles, correct layering).
+ */
+
+import type {
+  PermissionUiPromptEvent,
+  PermissionUiPromptSource,
+} from "./permission-events";
+
+/** Input for a direct (non-forwarded) tool or skill prompt. */
+export interface DirectPromptInput {
+  requestId: string;
+  source: "tool_call" | "skill_input" | "skill_read";
+  agentName: string | null;
+  message: string;
+  toolName?: string;
+  skillName?: string;
+  path?: string;
+  command?: string;
+  target?: string;
+}
+
+/** Input for a `permissions:rpc:prompt` forwarded UI prompt. */
+export interface RpcPromptInput {
+  requestId: string;
+  surface?: string | null;
+  value?: string | null;
+  agentName?: string | null;
+  message: string;
+}
+
+/** Input for a file-forwarded subagent prompt shown by the parent UI. */
+export interface ForwardedPromptInput {
+  requestId: string;
+  message: string;
+  requesterAgentName: string | null;
+  requesterSessionId: string | null;
+  /** Original prompt origin, when the forwarded request carries it. */
+  source?: PermissionUiPromptSource | null;
+  /** Original normalized surface, when the forwarded request carries it. */
+  surface?: string | null;
+  /** Original normalized value, when the forwarded request carries it. */
+  value?: string | null;
+}
+
+/** Normalized display surface for a direct prompt. */
+function directSurface(input: DirectPromptInput): string | null {
+  if (input.source === "skill_input" || input.source === "skill_read") {
+    return "skill";
+  }
+  return input.toolName ?? null;
+}
+
+/** Normalized display value for a direct prompt. */
+function directValue(input: DirectPromptInput): string | null {
+  return (
+    input.command ??
+    input.path ??
+    input.target ??
+    input.skillName ??
+    input.toolName ??
+    null
+  );
+}
+
+/** Build the UI prompt event for a direct tool/skill prompt. */
+export function buildDirectUiPrompt(
+  input: DirectPromptInput,
+): PermissionUiPromptEvent {
+  return {
+    requestId: input.requestId,
+    source: input.source,
+    surface: directSurface(input),
+    value: directValue(input),
+    agentName: input.agentName,
+    message: input.message,
+    forwarding: null,
+  };
+}
+
+/** Build the UI prompt event for an RPC-forwarded prompt. */
+export function buildRpcUiPrompt(
+  input: RpcPromptInput,
+): PermissionUiPromptEvent {
+  return {
+    requestId: input.requestId,
+    source: "rpc_prompt",
+    surface: input.surface ?? null,
+    value: input.value ?? null,
+    agentName: input.agentName ?? null,
+    message: input.message,
+    forwarding: null,
+  };
+}
+
+/**
+ * Build the UI prompt event for a file-forwarded subagent prompt.
+ *
+ * `source` defaults to `"tool_call"` (the dominant forwarded origin) when the
+ * persisted request predates carrying it — a parent on a newer version may read
+ * a request written by an older child during an upgrade. The consumer still
+ * receives the notify-now signal, message, and forwarding context.
+ */
+export function buildForwardedUiPrompt(
+  input: ForwardedPromptInput,
+): PermissionUiPromptEvent {
+  return {
+    requestId: input.requestId,
+    source: input.source ?? "tool_call",
+    surface: input.surface ?? null,
+    value: input.value ?? null,
+    agentName: input.requesterAgentName,
+    message: input.message,
+    forwarding: {
+      requesterAgentName: input.requesterAgentName,
+      requesterSessionId: input.requesterSessionId,
+    },
+  };
+}

package/src/service.ts

@@ -14,6 +14,23 @@
 import type { ToolInputFormatter } from "./tool-input-formatter-registry";
 import type { PermissionCheckResult, PermissionState } from "./types";
 
+export type {
+  ForwardedPromptContext,
+  PermissionDecisionEvent,
+  PermissionsPromptReplyData,
+  PermissionsPromptRequest,
+  PermissionsReadyEvent,
+  PermissionsRpcReply,
+  PermissionUiPromptEvent,
+  PermissionUiPromptSource,
+} from "./permission-events";
+export {
+  PERMISSIONS_DECISION_CHANNEL,
+  PERMISSIONS_PROTOCOL_VERSION,
+  PERMISSIONS_READY_CHANNEL,
+  PERMISSIONS_RPC_PROMPT_CHANNEL,
+  PERMISSIONS_UI_PROMPT_CHANNEL,
+} from "./permission-events";
 export type { PermissionCheckResult, PermissionState, ToolInputFormatter };
 
 /** Process-global key for the service slot. */

package/test/composition-root.test.ts

@@ -256,6 +256,11 @@ describe("subagent registry sharing across factory instances", () => {
     );
     expect(request.targetSessionId).toBe(parentSessionId);
     expect(request.requesterSessionId).toBe(childSessionId);
+    // The child persists the original display fields so the parent emits a
+    // non-degraded `permissions:ui_prompt` event (forwarded non-degradation).
+    expect(request.source).toBe("tool_call");
+    expect(request.surface).toBe("read");
+    expect(request.value).toBe(join(externalDir, "secret.txt"));
 
     const result = (await firePromise) as { block?: true };
     expect(result.block).toBeUndefined();