@gotgenes/pi-permission-system 7.3.2 → 7.4.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).
 
+## [7.4.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v7.3.3...pi-permission-system-v7.4.0) (2026-05-29)
+
+
+### Features
+
+* register subagent child sessions via lifecycle events ([cd324dc](https://github.com/gotgenes/pi-packages/commit/cd324dc5f8b18fe69ba8802eda0b17a6a36ccc58))
+
+
+### Documentation
+
+* document event-based subagent child lifecycle ([62621fa](https://github.com/gotgenes/pi-packages/commit/62621fa9abd093b5deadb3c15139179ae85ad519))
+
+## [7.3.3](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v7.3.2...pi-permission-system-v7.3.3) (2026-05-28)
+
+
+### Bug Fixes
+
+* respect config-level allow/deny in bash external-directory gate ([#249](https://github.com/gotgenes/pi-packages/issues/249)) ([1437ff3](https://github.com/gotgenes/pi-packages/commit/1437ff3e3c0bdde93927ba9fdf9e3cf5b52e7c0c))
+
+
+### Documentation
+
+* plan fix for bash external-directory config-level allow bypass ([#249](https://github.com/gotgenes/pi-packages/issues/249)) ([9e09f35](https://github.com/gotgenes/pi-packages/commit/9e09f35e6cfad09b53a1b55b54fcd44af4ed6a7b))
+* **retro:** add planning stage notes for issue [#249](https://github.com/gotgenes/pi-packages/issues/249) ([fe13214](https://github.com/gotgenes/pi-packages/commit/fe132144869db93bfc83c4e940abb7d3ce813d46))
+* **retro:** add TDD stage notes for issue [#249](https://github.com/gotgenes/pi-packages/issues/249) ([b5d22f6](https://github.com/gotgenes/pi-packages/commit/b5d22f6d67f7d2c28ed406c99bc0458df9024713))
+
 ## [7.3.2](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v7.3.1...pi-permission-system-v7.3.2) (2026-05-27)
 
 

package/package.json

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

package/src/handlers/gates/bash-external-directory.ts

@@ -21,7 +21,7 @@ type CheckPermissionFn = (
  * Extracts paths from a bash command and checks whether any reference
  * directories outside the working directory. Returns `null` when the gate
  * does not apply (tool is not bash, no CWD, or no external paths found).
- * Returns a `GateBypass` when all paths are session-covered.
+ * Returns a `GateBypass` when all paths are allowed (by config or session rule).
  * Returns a `GateDescriptor` with multi-pattern sessionApproval for uncovered paths.
  */
 export async function describeBashExternalDirectoryGate(
@@ -41,15 +41,26 @@ export async function describeBashExternalDirectoryGate(
   if (externalPaths.length === 0) return null;
 
   const bashSessionRules = getSessionRuleset();
-  const uncoveredPaths = externalPaths.filter(
-    (p) =>
-      checkPermission(
-        "external_directory",
-        { path: p },
-        tcc.agentName ?? undefined,
-        bashSessionRules,
-      ).source !== "session",
-  );
+
+  // Collect paths whose resolved state is not already "allow".
+  // Checking state (not source) ensures config-level allow rules (source: "special")
+  // suppress the prompt just as session-level allow rules (source: "session") do.
+  const uncoveredEntries: Array<{
+    path: string;
+    check: PermissionCheckResult;
+  }> = [];
+  for (const p of externalPaths) {
+    const check = checkPermission(
+      "external_directory",
+      { path: p },
+      tcc.agentName ?? undefined,
+      bashSessionRules,
+    );
+    if (check.state !== "allow") {
+      uncoveredEntries.push({ path: p, check });
+    }
+  }
+  const uncoveredPaths = uncoveredEntries.map(({ path }) => path);
 
   if (uncoveredPaths.length === 0) {
     return {
@@ -69,12 +80,12 @@ export async function describeBashExternalDirectoryGate(
     };
   }
 
-  // Get the config-level policy (no path → no session check).
-  const extCheck = checkPermission(
-    "external_directory",
-    {},
-    tcc.agentName ?? undefined,
-  );
+  // Use the most restrictive check among uncovered paths as the pre-check result.
+  // This ensures a config-level "deny" rule is not downgraded to "ask" by the
+  // generic "*" catch-all that the old path-less checkPermission call returned.
+  const worstCheck =
+    uncoveredEntries.find(({ check }) => check.state === "deny")?.check ??
+    uncoveredEntries[0].check;
 
   const bashExtMessage = formatBashExternalDirectoryAskPrompt(
     command,
@@ -120,6 +131,6 @@ export async function describeBashExternalDirectoryGate(
       surface: "external_directory",
       value: command,
     },
-    preCheck: extCheck,
+    preCheck: worstCheck,
   };
 }

package/src/index.ts

@@ -27,6 +27,7 @@ import {
 } from "./service";
 import { createSessionLogger } from "./session-logger";
 import { isSubagentExecutionContext } from "./subagent-context";
+import { subscribeSubagentLifecycle } from "./subagent-lifecycle-events";
 import { SubagentSessionRegistry } from "./subagent-registry";
 import {
   canResolveAskPermissionRequest,
@@ -129,6 +130,13 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
   };
   publishPermissionsService(permissionsService);
 
+  // Subscribe to @gotgenes/pi-subagents' child lifecycle events so child
+  // sessions register/unregister without the core calling us (ADR 0002).
+  const unsubSubagentLifecycle = subscribeSubagentLifecycle(
+    pi.events,
+    subagentRegistry,
+  );
+
   emitReadyEvent(pi.events);
 
   const toolRegistry = {
@@ -139,6 +147,7 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
   const lifecycle = new SessionLifecycleHandler(session, () => {
     rpcHandles.unsubCheck();
     rpcHandles.unsubPrompt();
+    unsubSubagentLifecycle();
     unpublishPermissionsService();
   });
   const agentPrep = new AgentPrepHandler(session, toolRegistry);

package/src/subagent-lifecycle-events.ts

@@ -0,0 +1,72 @@
+/**
+ * subagent-lifecycle-events.ts — Subscribe to @gotgenes/pi-subagents' child
+ * lifecycle events and keep the SubagentSessionRegistry in sync.
+ *
+ * @gotgenes/pi-subagents publishes its child-execution lifecycle on the Pi
+ * event bus (ADR 0002): it no longer calls this package's service directly.
+ * We register the child on `session-created` and unregister it on `disposed`.
+ *
+ * The channel names and payload shapes are declared independently here (the two
+ * packages must not depend on each other under jiti) and MUST match the
+ * publisher in `@gotgenes/pi-subagents` (`src/lifecycle/child-lifecycle.ts`).
+ *
+ * The `session-created` handler MUST stay synchronous: the core emits it on the
+ * same synchronous call stack immediately before `bindExtensions()`, and the
+ * event bus dispatches listeners synchronously, so a synchronous handler lands
+ * the registry entry before binding proceeds. Introducing an `await` before
+ * `registry.register(...)` would break the pre-bind ordering.
+ */
+
+import type { SubagentSessionRegistry } from "./subagent-registry";
+
+/** Emitted by the core after session creation, before `bindExtensions()`. */
+export const SUBAGENT_CHILD_SESSION_CREATED = "subagents:child:session-created";
+
+/** Emitted by the core in the run's `finally` (success and error). */
+export const SUBAGENT_CHILD_DISPOSED = "subagents:child:disposed";
+
+/** Minimal event-bus surface this module needs (subscribe only). */
+interface LifecycleEventBus {
+  on(channel: string, handler: (data: unknown) => void): () => void;
+}
+
+/** Fields read from the `session-created` payload (ISP). */
+interface ChildSessionCreatedEvent {
+  sessionDir: string;
+  agentName: string;
+  parentSessionId?: string;
+}
+
+/** Fields read from the `disposed` payload (ISP). */
+interface ChildDisposedEvent {
+  sessionDir: string;
+}
+
+/**
+ * Subscribe to the subagent child lifecycle.
+ *
+ * @returns an unsubscribe that detaches both handlers (call during
+ *          `session_shutdown`).
+ */
+export function subscribeSubagentLifecycle(
+  events: LifecycleEventBus,
+  registry: SubagentSessionRegistry,
+): () => void {
+  const unsubCreated = events.on(SUBAGENT_CHILD_SESSION_CREATED, (data) => {
+    const event = data as ChildSessionCreatedEvent;
+    registry.register(event.sessionDir, {
+      agentName: event.agentName,
+      parentSessionId: event.parentSessionId,
+    });
+  });
+
+  const unsubDisposed = events.on(SUBAGENT_CHILD_DISPOSED, (data) => {
+    const event = data as ChildDisposedEvent;
+    registry.unregister(event.sessionDir);
+  });
+
+  return () => {
+    unsubCreated();
+    unsubDisposed();
+  };
+}

package/test/handlers/gates/bash-external-directory.test.ts

@@ -98,16 +98,39 @@ describe("describeBashExternalDirectoryGate", () => {
     expect(patterns.length).toBeGreaterThan(0);
   });
 
-  it("uses config-level checkPermission for the policy state", async () => {
+  it("returns GateBypass when all external paths are config-level allowed", async () => {
+    // Config-level allow (source: "special") should suppress the prompt,
+    // not just session-level allow. This was the bug: source !== "session"
+    // kept config-allowed paths in the uncovered set.
     const checkPermission = vi
       .fn()
       .mockImplementation(
         (_surface: string, input: Record<string, unknown>) => {
-          // Path-specific check returns session for coverage filtering
           if (input.path)
             return makeCheckResult("allow", { source: "special" });
-          // Config-level check (no path) returns deny
-          return makeCheckResult("deny");
+          return makeCheckResult("ask");
+        },
+      );
+    const result = await describeBashExternalDirectoryGate(
+      makeTcc(),
+      checkPermission,
+      vi.fn().mockReturnValue([]),
+    );
+    expect(result).not.toBeNull();
+    expect(isGateBypass(result)).toBe(true);
+  });
+
+  it("uses worst-check state from uncovered paths for preCheck (config deny > catch-all ask)", async () => {
+    // The path-less extCheck used to always return the "*" catch-all (ask),
+    // silently downgrading a config-level deny to ask. After the fix, the
+    // descriptor's preCheck is derived from the actual path check result.
+    const checkPermission = vi
+      .fn()
+      .mockImplementation(
+        (_surface: string, input: Record<string, unknown>) => {
+          if (input.path) return makeCheckResult("deny", { source: "special" });
+          // Path-less catch-all returns ask — should NOT be used as preCheck.
+          return makeCheckResult("ask");
         },
       );
     const result = await describeBashExternalDirectoryGate(
@@ -116,8 +139,6 @@ describe("describeBashExternalDirectoryGate", () => {
       vi.fn().mockReturnValue([]),
     );
     expect(isGateDescriptor(result)).toBe(true);
-    // The descriptor should carry the deny state from the config-level check
-    // (it will be checked as preCheck by the runner)
     const desc = result as GateDescriptor;
     expect(desc.preCheck?.state).toBe("deny");
   });
@@ -172,6 +193,53 @@ describe("describeBashExternalDirectoryGate", () => {
     });
   });
 
+  it("config-allowed path is excluded; remaining ask path produces a descriptor", async () => {
+    // One path config-allowed, one config-ask → descriptor with only the ask path.
+    const checkPermission = vi
+      .fn()
+      .mockImplementation(
+        (_surface: string, input: Record<string, unknown>) => {
+          if (input.path === "/outside/a.ts")
+            return makeCheckResult("allow", { source: "special" });
+          return makeCheckResult("ask");
+        },
+      );
+    const result = await describeBashExternalDirectoryGate(
+      makeTcc({ input: { command: "diff /outside/a.ts /outside/b.ts" } }),
+      checkPermission,
+      vi.fn().mockReturnValue([]),
+    );
+    expect(isGateDescriptor(result)).toBe(true);
+    const desc = result as GateDescriptor;
+    const patterns = (desc.sessionApproval as { patterns: string[] }).patterns;
+    expect(patterns.length).toBe(1);
+    expect(desc.preCheck?.state).toBe("ask");
+  });
+
+  it("config-denied path makes worstCheck deny even when another path is ask", async () => {
+    // One path config-denied, one config-ask → descriptor with preCheck.state === "deny".
+    const checkPermission = vi
+      .fn()
+      .mockImplementation(
+        (_surface: string, input: Record<string, unknown>) => {
+          if (input.path === "/outside/a.ts")
+            return makeCheckResult("deny", { source: "special" });
+          return makeCheckResult("ask");
+        },
+      );
+    const result = await describeBashExternalDirectoryGate(
+      makeTcc({ input: { command: "diff /outside/a.ts /outside/b.ts" } }),
+      checkPermission,
+      vi.fn().mockReturnValue([]),
+    );
+    expect(isGateDescriptor(result)).toBe(true);
+    const desc = result as GateDescriptor;
+    expect(desc.preCheck?.state).toBe("deny");
+    // Both paths are uncovered (neither is allow), so both patterns are included.
+    const patterns = (desc.sessionApproval as { patterns: string[] }).patterns;
+    expect(patterns.length).toBe(2);
+  });
+
   it("only includes uncovered paths when some are session-covered", async () => {
     const checkPermission = vi
       .fn()

package/test/subagent-lifecycle-events.test.ts

@@ -0,0 +1,113 @@
+import { createEventBus } from "@earendil-works/pi-coding-agent";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import {
+  SUBAGENT_CHILD_DISPOSED,
+  SUBAGENT_CHILD_SESSION_CREATED,
+  subscribeSubagentLifecycle,
+} from "#src/subagent-lifecycle-events";
+import { SubagentSessionRegistry } from "#src/subagent-registry";
+
+describe("subscribeSubagentLifecycle", () => {
+  let registry: SubagentSessionRegistry;
+
+  beforeEach(() => {
+    registry = new SubagentSessionRegistry();
+  });
+
+  it("registers a child session on session-created", () => {
+    const bus = createEventBus();
+    subscribeSubagentLifecycle(bus, registry);
+
+    bus.emit(SUBAGENT_CHILD_SESSION_CREATED, {
+      sessionDir: "/sessions/child-abc",
+      agentName: "Explore",
+      parentSessionId: "parent-42",
+    });
+
+    expect(registry.get("/sessions/child-abc")).toEqual({
+      agentName: "Explore",
+      parentSessionId: "parent-42",
+    });
+  });
+
+  it("populates the registry synchronously — before emit() returns", () => {
+    // Guards the pre-bindExtensions ordering: the core emits session-created
+    // on the same synchronous call stack right before bindExtensions(), so the
+    // handler must complete before emit() returns. A real EventEmitter-backed
+    // bus dispatches synchronously; this fails loudly if the handler ever
+    // becomes async (awaiting before registry.register).
+    const bus = createEventBus();
+    subscribeSubagentLifecycle(bus, registry);
+
+    bus.emit(SUBAGENT_CHILD_SESSION_CREATED, {
+      sessionDir: "/sessions/child-sync",
+      agentName: "Explore",
+    });
+
+    // No await between emit and this assertion.
+    expect(registry.has("/sessions/child-sync")).toBe(true);
+  });
+
+  it("omits parentSessionId when the event does not carry one", () => {
+    const bus = createEventBus();
+    subscribeSubagentLifecycle(bus, registry);
+
+    bus.emit(SUBAGENT_CHILD_SESSION_CREATED, {
+      sessionDir: "/sessions/child-xyz",
+      agentName: "general-purpose",
+    });
+
+    expect(registry.get("/sessions/child-xyz")).toEqual({
+      agentName: "general-purpose",
+      parentSessionId: undefined,
+    });
+  });
+
+  it("unregisters a child session on disposed", () => {
+    const bus = createEventBus();
+    subscribeSubagentLifecycle(bus, registry);
+    registry.register("/sessions/child-abc", { agentName: "Explore" });
+
+    bus.emit(SUBAGENT_CHILD_DISPOSED, { sessionDir: "/sessions/child-abc" });
+
+    expect(registry.has("/sessions/child-abc")).toBe(false);
+  });
+
+  it("detaches both handlers when the returned unsubscribe is called", () => {
+    const bus = createEventBus();
+    const unsubscribe = subscribeSubagentLifecycle(bus, registry);
+
+    unsubscribe();
+
+    bus.emit(SUBAGENT_CHILD_SESSION_CREATED, {
+      sessionDir: "/sessions/child-abc",
+      agentName: "Explore",
+    });
+    bus.emit(SUBAGENT_CHILD_DISPOSED, { sessionDir: "/sessions/child-abc" });
+
+    expect(registry.has("/sessions/child-abc")).toBe(false);
+  });
+
+  it("subscribes to a fake bus on the exact channel names", () => {
+    const handlers = new Map<string, (data: unknown) => void>();
+    const bus = {
+      on: vi.fn((channel: string, handler: (data: unknown) => void) => {
+        handlers.set(channel, handler);
+        return () => handlers.delete(channel);
+      }),
+    };
+
+    subscribeSubagentLifecycle(bus, registry);
+
+    expect(bus.on).toHaveBeenCalledTimes(2);
+    expect(handlers.has("subagents:child:session-created")).toBe(true);
+    expect(handlers.has("subagents:child:disposed")).toBe(true);
+  });
+
+  it("exposes the canonical channel-name strings", () => {
+    expect(SUBAGENT_CHILD_SESSION_CREATED).toBe(
+      "subagents:child:session-created",
+    );
+    expect(SUBAGENT_CHILD_DISPOSED).toBe("subagents:child:disposed");
+  });
+});