@gotgenes/pi-permission-system 9.2.0 → 10.1.0

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/permissions-service.ts

@@ -0,0 +1,53 @@
+import { buildInputForSurface } from "./input-normalizer";
+import type { PermissionManager } from "./permission-manager";
+import type { PermissionsService } from "./service";
+import type { SessionRules } from "./session-rules";
+import type {
+  ToolInputFormatter,
+  ToolInputFormatterRegistry,
+} from "./tool-input-formatter-registry";
+
+/**
+ * In-process implementation of the cross-extension {@link PermissionsService}.
+ *
+ * Constructed once in the composition root and backed by the runtime's
+ * permission manager and session rules. Both injected instances are stable
+ * for the lifetime of the factory — `runtime.permissionManager` is never
+ * reassigned on the runtime object (only `PermissionSession` reassigns its
+ * own internal copy), and `runtime.sessionRules` is `readonly`.
+ */
+export class LocalPermissionsService implements PermissionsService {
+  constructor(
+    private readonly permissionManager: PermissionManager,
+    private readonly sessionRules: SessionRules,
+    private readonly formatterRegistry: ToolInputFormatterRegistry,
+  ) {}
+
+  checkPermission(
+    surface: string,
+    value?: string,
+    agentName?: string,
+  ): ReturnType<PermissionsService["checkPermission"]> {
+    const input = buildInputForSurface(surface, value);
+    return this.permissionManager.checkPermission(
+      surface,
+      input,
+      agentName,
+      this.sessionRules.getRuleset(),
+    );
+  }
+
+  getToolPermission(
+    toolName: string,
+    agentName?: string,
+  ): ReturnType<PermissionsService["getToolPermission"]> {
+    return this.permissionManager.getToolPermission(toolName, agentName);
+  }
+
+  registerToolInputFormatter(
+    toolName: string,
+    formatter: ToolInputFormatter,
+  ): ReturnType<PermissionsService["registerToolInputFormatter"]> {
+    return this.formatterRegistry.register(toolName, formatter);
+  }
+}

package/src/service-lifecycle.ts

@@ -0,0 +1,49 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import { emitReadyEvent, type PermissionEventBus } from "./permission-events";
+import {
+  type PermissionsService,
+  publishPermissionsService,
+  unpublishPermissionsService,
+} from "./service";
+import { isRegisteredSubagentChild } from "./subagent-context";
+import type { SubagentSessionRegistry } from "./subagent-registry";
+
+/** The session-scoped service lifecycle that the lifecycle handler drives. */
+export interface ServiceLifecycle {
+  activate(ctx: ExtensionContext): void;
+  teardown(): void;
+}
+
+/**
+ * Owns the process-global service publication lifecycle for one extension
+ * instance.
+ *
+ * - `activate` publishes the service (skipped for registered subagent children
+ *   so they never clobber the parent's slot — see #302), then emits the ready
+ *   event.
+ * - `teardown` runs all session-scoped subscription cleanups in order, then
+ *   unpublishes the service.
+ */
+export class PermissionServiceLifecycle implements ServiceLifecycle {
+  constructor(
+    private readonly service: PermissionsService,
+    private readonly registry: SubagentSessionRegistry,
+    private readonly events: PermissionEventBus,
+    private readonly subscriptions: readonly (() => void)[],
+  ) {}
+
+  activate(ctx: ExtensionContext): void {
+    if (!isRegisteredSubagentChild(ctx, this.registry)) {
+      publishPermissionsService(this.service);
+    }
+    emitReadyEvent(this.events);
+  }
+
+  teardown(): void {
+    for (const unsubscribe of this.subscriptions) {
+      unsubscribe();
+    }
+    unpublishPermissionsService(this.service);
+  }
+}

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/src/session-approval-recorder.ts

@@ -0,0 +1,6 @@
+import type { SessionApproval } from "./session-approval";
+
+/** Records a granted session-scoped approval into the session ruleset. */
+export interface SessionApprovalRecorder {
+  recordSessionApproval(approval: SessionApproval): void;
+}

package/src/session-lifecycle-session.ts

@@ -0,0 +1,24 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+import type { SessionLogger } from "./session-logger";
+
+/**
+ * The session surface `SessionLifecycleHandler` invokes across
+ * `session_start`, `resources_discover`, and `session_shutdown`: refresh and
+ * report config, reset / reload / shut down session state, resolve the agent
+ * name, surface config issues, read the runtime context, and log.
+ *
+ * `activate` is intentionally absent — the lifecycle handler never calls it
+ * directly (ISP: do not depend on methods you do not use).
+ */
+export interface SessionLifecycleSession {
+  refreshConfig(ctx?: ExtensionContext): void;
+  resetForNewSession(ctx: ExtensionContext): void;
+  logResolvedConfigPaths(): void;
+  resolveAgentName(ctx: ExtensionContext, systemPrompt?: string): string | null;
+  getConfigIssues(agentName?: string): string[];
+  reload(): void;
+  getRuntimeContext(): ExtensionContext | null;
+  shutdown(): void;
+  readonly logger: SessionLogger;
+}

package/src/tool-input-preview.ts

@@ -1,4 +1,3 @@
-import { getNonEmptyString, toRecord } from "./common";
 import { safeJsonStringify } from "./logging";
 
 export const TOOL_INPUT_PREVIEW_MAX_LENGTH = 200;
@@ -25,67 +24,6 @@ export function formatCount(
   return `${value} ${value === 1 ? singular : plural}`;
 }
 
-export function getPromptPath(input: Record<string, unknown>): string | null {
-  return getNonEmptyString(input.path) ?? getNonEmptyString(input.file_path);
-}
-
-export function formatEditInputForPrompt(
-  input: Record<string, unknown>,
-): string {
-  const path = getPromptPath(input);
-  const rawEdits = Array.isArray(input.edits)
-    ? input.edits
-    : typeof input.oldText === "string" && typeof input.newText === "string"
-      ? [{ oldText: input.oldText, newText: input.newText }]
-      : [];
-
-  const edits = rawEdits
-    .map((edit) => toRecord(edit))
-    .filter(
-      (edit) =>
-        typeof edit.oldText === "string" && typeof edit.newText === "string",
-    );
-
-  const pathPart = path ? `for '${path}'` : "";
-  if (edits.length === 0) {
-    return pathPart ? `${pathPart} with edit input` : "with edit input";
-  }
-
-  const firstEdit = edits[0];
-  const oldText = String(firstEdit.oldText);
-  const newText = String(firstEdit.newText);
-  const firstEditSummary = `edit #1 replaces ${formatCount(countTextLines(oldText), "line", "lines")} with ${formatCount(countTextLines(newText), "line", "lines")}`;
-  const extraEdits =
-    edits.length > 1
-      ? `, plus ${formatCount(edits.length - 1, "additional edit", "additional edits")}`
-      : "";
-  const summary = `(${formatCount(edits.length, "replacement", "replacements")}: ${firstEditSummary}${extraEdits})`;
-  return pathPart ? `${pathPart} ${summary}` : summary;
-}
-
-export function formatWriteInputForPrompt(
-  input: Record<string, unknown>,
-): string {
-  const path = getPromptPath(input);
-  const content = typeof input.content === "string" ? input.content : "";
-  const summary = `(${formatCount(countTextLines(content), "line", "lines")}, ${formatCount(content.length, "character", "characters")})`;
-  return path ? `for '${path}' ${summary}` : summary;
-}
-
-export function formatReadInputForPrompt(
-  input: Record<string, unknown>,
-): string {
-  const path = getPromptPath(input);
-  const parts = path ? [`path '${path}'`] : [];
-  if (typeof input.offset === "number") {
-    parts.push(`offset ${input.offset}`);
-  }
-  if (typeof input.limit === "number") {
-    parts.push(`limit ${input.limit}`);
-  }
-  return parts.length > 0 ? `for ${parts.join(", ")}` : "";
-}
-
 export function serializeToolInputPreview(input: unknown): string {
   const serialized = safeJsonStringify(input);
   if (!serialized || serialized === "{}" || serialized === "null") {

package/src/tool-input-prompt-formatters.ts

@@ -0,0 +1,63 @@
+import { getNonEmptyString, toRecord } from "./common";
+import { countTextLines, formatCount } from "./tool-input-preview";
+
+export function getPromptPath(input: Record<string, unknown>): string | null {
+  return getNonEmptyString(input.path) ?? getNonEmptyString(input.file_path);
+}
+
+export function formatEditInputForPrompt(
+  input: Record<string, unknown>,
+): string {
+  const path = getPromptPath(input);
+  const rawEdits = Array.isArray(input.edits)
+    ? input.edits
+    : typeof input.oldText === "string" && typeof input.newText === "string"
+      ? [{ oldText: input.oldText, newText: input.newText }]
+      : [];
+
+  const edits = rawEdits
+    .map((edit) => toRecord(edit))
+    .filter(
+      (edit) =>
+        typeof edit.oldText === "string" && typeof edit.newText === "string",
+    );
+
+  const pathPart = path ? `for '${path}'` : "";
+  if (edits.length === 0) {
+    return pathPart ? `${pathPart} with edit input` : "with edit input";
+  }
+
+  const firstEdit = edits[0];
+  const oldText = String(firstEdit.oldText);
+  const newText = String(firstEdit.newText);
+  const firstEditSummary = `edit #1 replaces ${formatCount(countTextLines(oldText), "line", "lines")} with ${formatCount(countTextLines(newText), "line", "lines")}`;
+  const extraEdits =
+    edits.length > 1
+      ? `, plus ${formatCount(edits.length - 1, "additional edit", "additional edits")}`
+      : "";
+  const summary = `(${formatCount(edits.length, "replacement", "replacements")}: ${firstEditSummary}${extraEdits})`;
+  return pathPart ? `${pathPart} ${summary}` : summary;
+}
+
+export function formatWriteInputForPrompt(
+  input: Record<string, unknown>,
+): string {
+  const path = getPromptPath(input);
+  const content = typeof input.content === "string" ? input.content : "";
+  const summary = `(${formatCount(countTextLines(content), "line", "lines")}, ${formatCount(content.length, "character", "characters")})`;
+  return path ? `for '${path}' ${summary}` : summary;
+}
+
+export function formatReadInputForPrompt(
+  input: Record<string, unknown>,
+): string {
+  const path = getPromptPath(input);
+  const parts = path ? [`path '${path}'`] : [];
+  if (typeof input.offset === "number") {
+    parts.push(`offset ${input.offset}`);
+  }
+  if (typeof input.limit === "number") {
+    parts.push(`limit ${input.limit}`);
+  }
+  return parts.length > 0 ? `for ${parts.join(", ")}` : "";
+}

package/src/tool-preview-formatter.ts

@@ -2,16 +2,18 @@ import { getNonEmptyString, toRecord } from "./common";
 import type { PermissionSystemExtensionConfig } from "./extension-config";
 import type { ToolInputFormatterLookup } from "./tool-input-formatter-registry";
 import {
-  formatEditInputForPrompt,
-  formatReadInputForPrompt,
-  formatWriteInputForPrompt,
-  getPromptPath,
   serializeToolInputPreview,
   TOOL_INPUT_LOG_PREVIEW_MAX_LENGTH,
   TOOL_INPUT_PREVIEW_MAX_LENGTH,
   TOOL_TEXT_SUMMARY_MAX_LENGTH,
   truncateInlineText,
 } from "./tool-input-preview";
+import {
+  formatEditInputForPrompt,
+  formatReadInputForPrompt,
+  formatWriteInputForPrompt,
+  getPromptPath,
+} from "./tool-input-prompt-formatters";
 import type { PermissionCheckResult } from "./types";
 
 export interface ToolPreviewFormatterOptions {

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();

package/test/decision-reporter.test.ts

@@ -0,0 +1,112 @@
+import { describe, expect, it, vi } from "vitest";
+
+import {
+  type DecisionReporter,
+  GateDecisionReporter,
+} from "#src/decision-reporter";
+import {
+  PERMISSIONS_DECISION_CHANNEL,
+  type PermissionDecisionEvent,
+} from "#src/permission-events";
+import type { SessionLogger } from "#src/session-logger";
+
+// ── fixtures ───────────────────────────────────────────────────────────────
+
+function makeLogger(): SessionLogger {
+  return {
+    debug: vi.fn(),
+    review: vi.fn(),
+    warn: vi.fn(),
+  };
+}
+
+function makeEvents() {
+  return {
+    emit: vi.fn(),
+    on: vi.fn().mockReturnValue(() => undefined),
+  };
+}
+
+function makeDecisionEvent(
+  overrides: Partial<PermissionDecisionEvent> = {},
+): PermissionDecisionEvent {
+  return {
+    surface: "read",
+    value: "read",
+    result: "allow",
+    resolution: "policy_allow",
+    origin: "global",
+    agentName: null,
+    matchedPattern: null,
+    ...overrides,
+  };
+}
+
+// ── tests ──────────────────────────────────────────────────────────────────
+
+describe("GateDecisionReporter", () => {
+  it("satisfies the DecisionReporter interface", () => {
+    const reporter: DecisionReporter = new GateDecisionReporter(
+      makeLogger(),
+      makeEvents(),
+    );
+    expect(reporter).toBeDefined();
+  });
+
+  describe("writeReviewLog", () => {
+    it("delegates to logger.review with event and details", () => {
+      const logger = makeLogger();
+      const reporter = new GateDecisionReporter(logger, makeEvents());
+      reporter.writeReviewLog("permission_request.blocked", { tool: "bash" });
+      expect(logger.review).toHaveBeenCalledWith("permission_request.blocked", {
+        tool: "bash",
+      });
+    });
+
+    it("delegates with an empty details object", () => {
+      const logger = makeLogger();
+      const reporter = new GateDecisionReporter(logger, makeEvents());
+      reporter.writeReviewLog("permission_request.session_approved", {});
+      expect(logger.review).toHaveBeenCalledWith(
+        "permission_request.session_approved",
+        {},
+      );
+    });
+
+    it("does not call emitDecision", () => {
+      const events = makeEvents();
+      const reporter = new GateDecisionReporter(makeLogger(), events);
+      reporter.writeReviewLog("some.event", { key: "val" });
+      expect(events.emit).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("emitDecision", () => {
+    it("emits on the PERMISSIONS_DECISION_CHANNEL with the event", () => {
+      const events = makeEvents();
+      const reporter = new GateDecisionReporter(makeLogger(), events);
+      const event = makeDecisionEvent();
+      reporter.emitDecision(event);
+      expect(events.emit).toHaveBeenCalledWith(
+        PERMISSIONS_DECISION_CHANNEL,
+        event,
+      );
+    });
+
+    it("does not call writeReviewLog", () => {
+      const logger = makeLogger();
+      const reporter = new GateDecisionReporter(logger, makeEvents());
+      reporter.emitDecision(makeDecisionEvent());
+      expect(logger.review).not.toHaveBeenCalled();
+    });
+
+    it("does not propagate a throwing listener", () => {
+      const events = makeEvents();
+      events.emit.mockImplementation(() => {
+        throw new Error("listener boom");
+      });
+      const reporter = new GateDecisionReporter(makeLogger(), events);
+      expect(() => reporter.emitDecision(makeDecisionEvent())).not.toThrow();
+    });
+  });
+});

package/test/denial-messages.test.ts

@@ -265,6 +265,31 @@ describe("formatDenyReason", () => {
       );
     });
   });
+
+  describe("skill_input context", () => {
+    test("without agent", () => {
+      expect(
+        formatDenyReason({
+          kind: "skill_input",
+          skillName: "librarian",
+        }),
+      ).toBe(
+        "[pi-permission-system] Current agent is not permitted to access skill 'librarian'.",
+      );
+    });
+
+    test("with agent", () => {
+      expect(
+        formatDenyReason({
+          kind: "skill_input",
+          skillName: "librarian",
+          agentName: "my-agent",
+        }),
+      ).toBe(
+        "[pi-permission-system] Agent 'my-agent' is not permitted to access skill 'librarian'.",
+      );
+    });
+  });
 });
 
 // ── formatUnavailableReason ────────────────────────────────────────────────
@@ -353,6 +378,17 @@ describe("formatUnavailableReason", () => {
       "[pi-permission-system] Accessing skill 'librarian' requires approval, but no interactive UI is available.",
     );
   });
+
+  test("skill_input", () => {
+    expect(
+      formatUnavailableReason({
+        kind: "skill_input",
+        skillName: "librarian",
+      }),
+    ).toBe(
+      "[pi-permission-system] Accessing skill 'librarian' requires approval, but no interactive UI is available.",
+    );
+  });
 });
 
 // ── formatUserDeniedReason ─────────────────────────────────────────────────
@@ -530,4 +566,30 @@ describe("formatUserDeniedReason", () => {
       );
     });
   });
+
+  describe("skill_input context", () => {
+    test("without agent and without reason", () => {
+      expect(
+        formatUserDeniedReason({
+          kind: "skill_input",
+          skillName: "librarian",
+        }),
+      ).toBe("[pi-permission-system] User denied access to skill 'librarian'.");
+    });
+
+    test("with agent and with reason", () => {
+      expect(
+        formatUserDeniedReason(
+          {
+            kind: "skill_input",
+            skillName: "librarian",
+            agentName: "code-agent",
+          },
+          "not permitted",
+        ),
+      ).toBe(
+        "[pi-permission-system] User denied access to skill 'librarian'. Reason: not permitted.",
+      );
+    });
+  });
 });