@gotgenes/pi-permission-system 9.1.0 → 10.0.0

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/bash-external-directory.test.ts

@@ -852,15 +852,16 @@ describe("extractExternalPathsFromBashCommand", () => {
       expect(result).toHaveLength(0);
     });
 
-    test("cd to external dir: paths after cd are still checked against cwd", async () => {
-      // When cd target is outside cwd, we fall back to cwd as the resolve base.
-      // The cd target itself should be flagged, and paths after cd are resolved
-      // against cwd.
+    test("cd to external dir: subsequent paths resolve against the (external) effective directory", async () => {
+      // The effective directory is tracked faithfully: `cd /tmp` makes /tmp the
+      // base, so the cd target itself is flagged AND ../etc/hosts resolves to
+      // /etc/hosts (both outside cwd).
       const result = await extractExternalPathsFromBashCommand(
         "cd /tmp && cat ../etc/hosts",
         cwd,
       );
-      expect(result.length).toBeGreaterThan(0);
+      expect(result).toContain("/tmp");
+      expect(result).toContain("/etc/hosts");
     });
 
     test("cd with relative target: resolves inside cwd", async () => {
@@ -880,14 +881,14 @@ describe("extractExternalPathsFromBashCommand", () => {
       expect(result.length).toBeGreaterThan(0);
     });
 
-    test("cd is not first command: cd is ignored", async () => {
-      // cd after another command should not affect path resolution.
+    test("sequential fold: a cd that is not the first command still updates the base", async () => {
+      // The current-shell `cd` folds even though it is not the first command;
+      // ../../outside.txt resolves against /projects/my-app/src → /projects/outside.txt.
       const result = await extractExternalPathsFromBashCommand(
         "echo hello && cd /projects/my-app/src && cat ../../outside.txt",
         cwd,
       );
-      // ../../outside.txt resolves against cwd, not the cd target
-      expect(result.length).toBeGreaterThan(0);
+      expect(result).toContain("/projects/outside.txt");
     });
 
     test("cd with semicolon separator", async () => {

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/handlers/gates/bash-program.test.ts

@@ -33,6 +33,115 @@ describe("BashProgram", () => {
       const program = await BashProgram.parse("cat src/index.ts");
       expect(program.externalPaths(cwd)).toHaveLength(0);
     });
+
+    describe("effective working directory projection", () => {
+      it("folds a sequence of current-shell cd commands", async () => {
+        // cd a → cwd/a, cd b → cwd/a/b; ../c resolves to cwd/a/c (inside).
+        const program = await BashProgram.parse("cd a && cd b && cat ../c");
+        expect(program.externalPaths(cwd)).toHaveLength(0);
+      });
+
+      it("catches an escape masked by a later cd that the single-base model missed", async () => {
+        // Effective dir after `cd nested/deep && cd ..` is cwd/nested, so
+        // ../../etc/passwd escapes to /projects/etc/passwd.
+        const program = await BashProgram.parse(
+          "cd nested/deep && cd .. && cat ../../etc/passwd",
+        );
+        expect(program.externalPaths(cwd)).toContain("/projects/etc/passwd");
+      });
+
+      it("folds a cd that is not the first command", async () => {
+        // The single-base model ignored a cd that was not first; now `cd a`
+        // folds, so ../b resolves to cwd/b (inside) and is not flagged.
+        const program = await BashProgram.parse("mkdir d && cd a && cat ../b");
+        expect(program.externalPaths(cwd)).toHaveLength(0);
+      });
+
+      it("does not fold a backgrounded cd", async () => {
+        // `cd a &` runs in a subshell, so it must not update the running
+        // directory; ../b resolves against cwd and escapes.
+        const program = await BashProgram.parse("cd a & cat ../b");
+        expect(program.externalPaths(cwd)).toContain("/projects/b");
+      });
+
+      it("does not fold a cd inside a pipeline", async () => {
+        // Pipeline members run in subshells; the cd must not leak.
+        const program = await BashProgram.parse("cd nested | cat ../b");
+        expect(program.externalPaths(cwd)).toContain("/projects/b");
+      });
+
+      it("folds a cd inside a subshell for paths within that subshell", async () => {
+        // Inside the subshell the effective dir is cwd/sub, so ../x → cwd/x.
+        const program = await BashProgram.parse("( cd sub && cat ../x )");
+        expect(program.externalPaths(cwd)).toHaveLength(0);
+      });
+
+      it("does not leak a subshell cd to following commands", async () => {
+        // The subshell cd resets on exit, so ../y resolves against cwd.
+        const program = await BashProgram.parse("( cd sub ) && cat ../y");
+        expect(program.externalPaths(cwd)).toContain("/projects/y");
+      });
+
+      it("persists a cd inside a brace group to later commands in the group", async () => {
+        // Brace groups run in the current shell, so cd sub persists to cat ../x.
+        const program = await BashProgram.parse("{ cd sub; cat ../x; }");
+        expect(program.externalPaths(cwd)).toHaveLength(0);
+      });
+
+      it("persists a brace-group cd to following sibling commands", async () => {
+        const program = await BashProgram.parse("{ cd sub; } && cat ../x");
+        expect(program.externalPaths(cwd)).toHaveLength(0);
+      });
+
+      it("conservatively flags a relative path inside a command substitution", async () => {
+        // Interior cd folding inside substitutions is deferred: the interior
+        // inherits the enclosing base (cwd), so ../r is flagged rather than
+        // resolved against cwd/q. Conservative — never misses an escape.
+        const program = await BashProgram.parse("echo $(cd q && cat ../r)");
+        expect(program.externalPaths(cwd)).toContain("/projects/r");
+      });
+
+      it("flags relative paths conservatively after a non-literal cd", async () => {
+        // cd "$DIR" makes the effective dir unknowable; ../x could be anywhere,
+        // so it is flagged (least-privilege).
+        const program = await BashProgram.parse('cd "$DIR" && cat ../x');
+        expect(program.externalPaths(cwd)).toContain("/projects/x");
+      });
+
+      it("flags even a within-cwd relative path after a non-literal cd", async () => {
+        // Conservative cost: src/../within.txt resolves inside cwd but is still
+        // flagged because the effective dir is unknown.
+        const program = await BashProgram.parse(
+          'cd "$DIR" && cat src/../within.txt',
+        );
+        expect(program.externalPaths(cwd)).toContain(
+          "/projects/my-app/within.txt",
+        );
+      });
+
+      it("still resolves an absolute path normally after a non-literal cd", async () => {
+        // Absolute paths are base-independent; one inside cwd is not flagged
+        // even when the effective dir is unknown.
+        const program = await BashProgram.parse(
+          'cd "$DIR" && cat /projects/my-app/x.txt',
+        );
+        expect(program.externalPaths(cwd)).toHaveLength(0);
+      });
+
+      it("treats `cd -` as an unknown effective directory", async () => {
+        const program = await BashProgram.parse("cd - && cat ../x");
+        expect(program.externalPaths(cwd)).toContain("/projects/x");
+      });
+
+      it("recovers a known base when a later cd is absolute", async () => {
+        // cd "$DIR" → unknown, then cd /projects/my-app/src → known again, so
+        // ../x resolves to cwd and is not flagged.
+        const program = await BashProgram.parse(
+          'cd "$DIR" && cd /projects/my-app/src && cat ../x',
+        );
+        expect(program.externalPaths(cwd)).toHaveLength(0);
+      });
+    });
   });
 
   describe("commands", () => {

package/test/permission-event-rpc.test.ts

@@ -13,6 +13,7 @@ import {
   PERMISSIONS_PROTOCOL_VERSION,
   PERMISSIONS_RPC_CHECK_CHANNEL,
   PERMISSIONS_RPC_PROMPT_CHANNEL,
+  PERMISSIONS_UI_PROMPT_CHANNEL,
 } from "#src/permission-events";
 
 // ── Helpers ────────────────────────────────────────────────────────────────
@@ -317,6 +318,44 @@ describe("registerPermissionRpcHandlers — permissions:rpc:prompt", () => {
     }
   });
 
+  it("emits a UI prompt broadcast before awaiting the UI decision", async () => {
+    const bus = createEventBus();
+    const ctx = makeCtxWithUi();
+    const requestUi = vi
+      .fn()
+      .mockResolvedValue({ approved: true, state: "approved" as const });
+    const deps = makeDeps({
+      getRuntimeContext: vi.fn().mockReturnValue(ctx),
+      requestPermissionDecisionFromUi: requestUi,
+    });
+    registerPermissionRpcHandlers(bus, deps);
+
+    const promptPromise = waitForReply(bus, PERMISSIONS_UI_PROMPT_CHANNEL);
+    const replyPromise = waitForReply(
+      bus,
+      `${PERMISSIONS_RPC_PROMPT_CHANNEL}:reply:req-prompt-broadcast`,
+    );
+    bus.emit(PERMISSIONS_RPC_PROMPT_CHANNEL, {
+      requestId: "req-prompt-broadcast",
+      surface: "bash",
+      value: "git push",
+      message: "Allow git push?",
+      agentName: "Worker",
+      sessionLabel: "Allow git *",
+    });
+
+    await expect(promptPromise).resolves.toEqual({
+      requestId: "req-prompt-broadcast",
+      source: "rpc_prompt",
+      surface: "bash",
+      value: "git push",
+      agentName: "Worker",
+      message: "Allow git push?",
+      forwarding: null,
+    });
+    await replyPromise;
+  });
+
   it("passes the message to requestPermissionDecisionFromUi", async () => {
     const bus = createEventBus();
     const ctx = makeCtxWithUi();