@gotgenes/pi-permission-system 9.2.0 → 10.1.0

package/CHANGELOG.md

@@ -5,6 +5,58 @@ 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.1.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v10.0.0...pi-permission-system-v10.1.0) (2026-06-03)
+
+
+### Features
+
+* add DecisionReporter and GateDecisionReporter ([530211d](https://github.com/gotgenes/pi-packages/commit/530211da9158a012e86f37311e326f4e2b571c55))
+* add GatePrompter and SessionApprovalRecorder session roles ([2f761e4](https://github.com/gotgenes/pi-packages/commit/2f761e44fd07c98fe98147275f75fc170163b06d))
+* add GateRunner class consolidating gate dispatch ([a390558](https://github.com/gotgenes/pi-packages/commit/a390558f19723fa911924b2d1878d4d874d6966d))
+* add getToolPreviewLimits and getInfrastructureReadDirs to PermissionSession ([#327](https://github.com/gotgenes/pi-packages/issues/327)) ([a0bf166](https://github.com/gotgenes/pi-packages/commit/a0bf1662119eeeb4b390c668c6993c7ff87194bf))
+* add PermissionResolver.resolve to PermissionSession ([c922bbd](https://github.com/gotgenes/pi-packages/commit/c922bbddcfb47a2ec88d349f3a797b633bd58f45))
+* add skill_input denial context ([#326](https://github.com/gotgenes/pi-packages/issues/326)) ([71e9d28](https://github.com/gotgenes/pi-packages/commit/71e9d28c5f6c8a09d2bfa9fe21cca6c55948898b))
+* introduce SkillInputGatePipeline collaborator ([#329](https://github.com/gotgenes/pi-packages/issues/329)) ([4ddd5af](https://github.com/gotgenes/pi-packages/commit/4ddd5af1c476ab3c3eb29ce456a33b273c386ca0))
+* introduce ToolCallGatePipeline collaborator ([#327](https://github.com/gotgenes/pi-packages/issues/327)) ([3a87727](https://github.com/gotgenes/pi-packages/commit/3a877274091bfc2db3998ca915f76ecbdd2ac1e7))
+
+
+### Bug Fixes
+
+* drop vestigial events field; document makeReporter in package skill ([9e0a8a7](https://github.com/gotgenes/pi-packages/commit/9e0a8a7d89b4c081d21465e02b7aa77c18ddd1b0))
+
+
+### Documentation
+
+* document SkillInputGatePipeline in architecture and package skill ([#329](https://github.com/gotgenes/pi-packages/issues/329)) ([9193c86](https://github.com/gotgenes/pi-packages/commit/9193c86ecc2fa6b18da6a7c7e4a9f9efbbc807ed))
+* record the composition-root collaborator extraction ([#320](https://github.com/gotgenes/pi-packages/issues/320)) ([dab8890](https://github.com/gotgenes/pi-packages/commit/dab8890df05e003bb9136924ab2d344c7fe69319))
+* standardize and correct package READMEs ([4c270ad](https://github.com/gotgenes/pi-packages/commit/4c270adac97ca816fa1889a879d1d4fe19cdd464))
+
+## [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

@@ -4,7 +4,7 @@
 
 # @gotgenes/pi-permission-system
 
-[![npm version](https://img.shields.io/npm/v/@gotgenes/pi-permission-system?style=flat&logo=npm&logoColor=white)](https://www.npmjs.com/package/@gotgenes/pi-permission-system) [![CI](https://img.shields.io/github/actions/workflow/status/gotgenes/pi-permission-system/ci.yml?style=flat&logo=github&label=CI)](https://github.com/gotgenes/pi-permission-system/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat)](https://opensource.org/licenses/MIT) [![TypeScript](https://img.shields.io/badge/TypeScript-6.x-3178C6?style=flat&logo=typescript&logoColor=white)](https://www.typescriptlang.org/) [![Pi Package](https://img.shields.io/badge/Pi-Package-6366F1?style=flat)](https://pi.mariozechner.at/)
+[![npm version](https://img.shields.io/npm/v/@gotgenes/pi-permission-system?style=flat&logo=npm&logoColor=white)](https://www.npmjs.com/package/@gotgenes/pi-permission-system) [![CI](https://img.shields.io/github/actions/workflow/status/gotgenes/pi-packages/ci.yml?style=flat&logo=github&label=CI)](https://github.com/gotgenes/pi-packages/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat)](https://opensource.org/licenses/MIT) [![TypeScript](https://img.shields.io/badge/TypeScript-6.x-3178C6?style=flat&logo=typescript&logoColor=white)](https://www.typescriptlang.org/) [![pnpm](https://img.shields.io/badge/pnpm-%3E%3D11-F69220?style=flat&logo=pnpm&logoColor=white)](https://pnpm.io/) [![Pi Package](https://img.shields.io/badge/Pi-Package-6366F1?style=flat)](https://pi.mariozechner.at/)
 
 Permission enforcement extension for the [Pi](https://pi.mariozechner.at/) coding agent that provides centralized, deterministic permission gates over tool, bash, MCP, skill, and special operations.
 
@@ -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.1.0",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
   "exports": {

package/src/agent-prep-session.ts

@@ -0,0 +1,28 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import type { GateHandlerSession } from "./gate-handler-session";
+import type {
+  SkillPermissionChecker,
+  SkillPromptEntry,
+} from "./skill-prompt-sanitizer";
+import type { PermissionState } from "./types";
+
+/**
+ * The session surface `AgentPrepHandler` invokes during `before_agent_start`:
+ * bind context + identify the agent (via {@link GateHandlerSession}), check
+ * skill permissions for prompt sanitization (via {@link SkillPermissionChecker}),
+ * refresh config, decide tool exposure, manage the active-tools / prompt-state
+ * cache keys, and store the resolved skill entries.
+ */
+export interface AgentPrepSession
+  extends GateHandlerSession,
+    SkillPermissionChecker {
+  refreshConfig(ctx?: ExtensionContext): void;
+  getToolPermission(toolName: string, agentName?: string): PermissionState;
+  shouldUpdateActiveTools(cacheKey: string): boolean;
+  commitActiveToolsCacheKey(cacheKey: string): void;
+  getPolicyCacheStamp(agentName?: string): string;
+  shouldUpdatePromptState(cacheKey: string): boolean;
+  commitPromptStateCacheKey(cacheKey: string): void;
+  setActiveSkillEntries(entries: SkillPromptEntry[]): void;
+}

package/src/decision-reporter.ts

@@ -0,0 +1,41 @@
+import {
+  emitDecisionEvent,
+  type PermissionDecisionEvent,
+  type PermissionEventBus,
+} from "./permission-events";
+import type { SessionLogger } from "./session-logger";
+
+/**
+ * Reports a permission gate's outcome to the review log and the decision
+ * channel. Groups the two side effects that always travel together:
+ * writing a structured review-log entry and broadcasting a decision event.
+ */
+export interface DecisionReporter {
+  writeReviewLog(event: string, details: Record<string, unknown>): void;
+  emitDecision(event: PermissionDecisionEvent): void;
+}
+
+/**
+ * Owns the `SessionLogger` and the event bus so neither the handler nor
+ * the runner has to reach through the session to its logger or close over
+ * the event bus directly.
+ *
+ * Built once in `PermissionGateHandler`'s constructor; shared between
+ * `handleToolCall` (gate runner + bypass branch) and `handleInput`.
+ *
+ * Answers "who owns the event bus" — the reporter does, not the session.
+ */
+export class GateDecisionReporter implements DecisionReporter {
+  constructor(
+    private readonly logger: SessionLogger,
+    private readonly events: PermissionEventBus,
+  ) {}
+
+  writeReviewLog(event: string, details: Record<string, unknown>): void {
+    this.logger.review(event, details);
+  }
+
+  emitDecision(event: PermissionDecisionEvent): void {
+    emitDecisionEvent(this.events, event);
+  }
+}

package/src/denial-messages.ts

@@ -45,6 +45,11 @@ export type DenialContext =
       skillName: string;
       readPath: string;
       agentName?: string;
+    }
+  | {
+      kind: "skill_input";
+      skillName: string;
+      agentName?: string;
     };
 
 // ── Public formatter API ───────────────────────────────────────────────────
@@ -91,6 +96,8 @@ function buildDenyBody(ctx: DenialContext): string {
       return `${subject(ctx.agentName)} is not permitted to access path '${ctx.pathValue}' via tool 'bash'.`;
     case "skill_read":
       return `${subject(ctx.agentName)} is not permitted to access skill '${ctx.skillName}' via '${ctx.readPath}'.`;
+    case "skill_input":
+      return `${subject(ctx.agentName)} is not permitted to access skill '${ctx.skillName}'.`;
   }
 }
 
@@ -184,6 +191,8 @@ function buildUnavailableBody(ctx: DenialContext): string {
       return `Bash command '${ctx.command}' accesses path '${ctx.pathValue}' which requires approval, but no interactive UI is available.`;
     case "skill_read":
       return `Accessing skill '${ctx.skillName}' requires approval, but no interactive UI is available.`;
+    case "skill_input":
+      return `Accessing skill '${ctx.skillName}' requires approval, but no interactive UI is available.`;
   }
 }
 
@@ -212,6 +221,8 @@ function buildUserDeniedBody(
       return `User denied path access for bash command '${ctx.command}' (path '${ctx.pathValue}').${reasonSuffix(denialReason)}`;
     case "skill_read":
       return `User denied access to skill '${ctx.skillName}'.${reasonSuffix(denialReason)}`;
+    case "skill_input":
+      return `User denied access to skill '${ctx.skillName}'.${reasonSuffix(denialReason)}`;
   }
 }
 

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(