@gotgenes/pi-permission-system 8.3.0 → 8.3.2

package/CHANGELOG.md

@@ -5,6 +5,33 @@ 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).
 
+## [8.3.2](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v8.3.1...pi-permission-system-v8.3.2) (2026-06-01)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** key subagent registry by session id and drop vestigial agentName ([d299c54](https://github.com/gotgenes/pi-packages/commit/d299c5421f41ab0829fb83fcf4e030d1c7af6d56))
+* **pi-permission-system:** resolve subagent detection and forwarding target by session id ([0f7e079](https://github.com/gotgenes/pi-packages/commit/0f7e0795b911797e645f4d44c42bb314bf0cb103))
+
+
+### Documentation
+
+* **retro:** add retro notes for issue [#296](https://github.com/gotgenes/pi-packages/issues/296) ([75743ab](https://github.com/gotgenes/pi-packages/commit/75743abe92604de142ff6e77c9c0fbc44266e12a))
+
+## [8.3.1](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v8.3.0...pi-permission-system-v8.3.1) (2026-06-01)
+
+
+### Bug Fixes
+
+* add process-global SubagentSessionRegistry accessor ([#296](https://github.com/gotgenes/pi-packages/issues/296)) ([d3fd3b0](https://github.com/gotgenes/pi-packages/commit/d3fd3b04223b2d276873094ad8c14f239654b8c8))
+* share SubagentSessionRegistry across parent and child sessions ([#296](https://github.com/gotgenes/pi-packages/issues/296)) ([fed676a](https://github.com/gotgenes/pi-packages/commit/fed676aaa485abe8db158e522ba898705f3dff94))
+
+
+### Documentation
+
+* explain process-global subagent registry across session buses ([#296](https://github.com/gotgenes/pi-packages/issues/296)) ([1804dbb](https://github.com/gotgenes/pi-packages/commit/1804dbbb766d7b7fbc0e49da877f3238f5c3e8dc))
+* use ADR-NNNN with links docs-wide ([c6b6431](https://github.com/gotgenes/pi-packages/commit/c6b6431c004f324931f23be46cf2e47e8fdac919))
+
 ## [8.3.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v8.2.1...pi-permission-system-v8.3.0) (2026-06-01)
 
 

package/package.json

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

package/src/forwarded-permissions/polling.ts

@@ -105,7 +105,6 @@ export async function waitForForwardedPermissionApproval(
   deps: PermissionForwardingDeps,
 ): Promise<PermissionPromptDecision> {
   const requesterSessionId = getSessionId(ctx);
-  const sessionDir = ctx.sessionManager.getSessionDir();
   const targetSessionId = resolvePermissionForwardingTargetSessionId({
     hasUI: ctx.hasUI,
     isSubagent: isSubagentExecutionContext(
@@ -115,7 +114,7 @@ export async function waitForForwardedPermissionApproval(
     ),
     currentSessionId: requesterSessionId,
     env: process.env,
-    sessionDir,
+    sessionId: requesterSessionId,
     registry: deps.registry,
   });
 

package/src/index.ts

@@ -29,7 +29,7 @@ import {
 import { createSessionLogger } from "./session-logger";
 import { isSubagentExecutionContext } from "./subagent-context";
 import { subscribeSubagentLifecycle } from "./subagent-lifecycle-events";
-import { SubagentSessionRegistry } from "./subagent-registry";
+import { getSubagentSessionRegistry } from "./subagent-registry";
 import { ToolInputFormatterRegistry } from "./tool-input-formatter-registry";
 import {
   canResolveAskPermissionRequest,
@@ -38,7 +38,7 @@ import {
 
 export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
   const runtime = createExtensionRuntime();
-  const subagentRegistry = new SubagentSessionRegistry();
+  const subagentRegistry = getSubagentSessionRegistry();
   const formatterRegistry = new ToolInputFormatterRegistry();
   registerBuiltinToolInputFormatters(formatterRegistry);
 

package/src/permission-forwarding.ts

@@ -119,8 +119,8 @@ export function resolvePermissionForwardingTargetSessionId(options: {
   isSubagent: boolean;
   currentSessionId?: string | null;
   env?: NodeJS.ProcessEnv;
-  /** Session directory key for registry lookup. */
-  sessionDir?: string;
+  /** Child session id for registry lookup. */
+  sessionId?: string;
   /** In-process subagent session registry (checked before env vars). */
   registry?: SubagentSessionRegistry;
 }): string | null {
@@ -133,8 +133,8 @@ export function resolvePermissionForwardingTargetSessionId(options: {
   }
 
   // 1. Registry — in-process subagents register parentSessionId explicitly.
-  if (options.registry && options.sessionDir) {
-    const entry = options.registry.get(options.sessionDir);
+  if (options.registry && options.sessionId) {
+    const entry = options.registry.get(options.sessionId);
     const resolved = normalizePermissionForwardingSessionId(
       entry?.parentSessionId,
     );

package/src/subagent-context.ts

@@ -33,14 +33,23 @@ export function isSubagentExecutionContext(
   subagentSessionsDir: string,
   registry?: SubagentSessionRegistry,
 ): boolean {
-  const sessionDir = ctx.sessionManager.getSessionDir();
-
-  // 1. Explicit registry — in-process subagent extensions register before
-  //    bindExtensions(); checked first so it takes priority over heuristics.
-  if (registry && sessionDir && registry.has(sessionDir)) {
-    return true;
+  // 1. Explicit registry — in-process subagent extensions register by child
+  //    session id before bindExtensions(); checked first so it takes priority
+  //    over heuristics. Each concurrent sibling has a unique session id, so
+  //    one sibling's disposed event cannot affect another's registration.
+  if (registry) {
+    try {
+      const sessionId = ctx.sessionManager.getSessionId();
+      if (sessionId && registry.has(sessionId)) {
+        return true;
+      }
+    } catch {
+      // getSessionId() unavailable — fall through to env/filesystem detection.
+    }
   }
 
+  const sessionDir = ctx.sessionManager.getSessionDir();
+
   // 2. Env vars — process-based subagent extensions (nicobailon/pi-subagents,
   //    HazAT/pi-interactive-subagents, pi-agent-router, etc.).
   for (const key of SUBAGENT_ENV_HINT_KEYS) {

package/src/subagent-lifecycle-events.ts

@@ -32,14 +32,15 @@ interface LifecycleEventBus {
 
 /** Fields read from the `session-created` payload (ISP). */
 interface ChildSessionCreatedEvent {
-  sessionDir: string;
-  agentName: string;
+  /** Child session id — the registry key. Must match the publisher. */
+  sessionId: string;
   parentSessionId?: string;
 }
 
 /** Fields read from the `disposed` payload (ISP). */
 interface ChildDisposedEvent {
-  sessionDir: string;
+  /** Child session id — the registry key. Must match the publisher. */
+  sessionId: string;
 }
 
 /**
@@ -54,15 +55,14 @@ export function subscribeSubagentLifecycle(
 ): () => void {
   const unsubCreated = events.on(SUBAGENT_CHILD_SESSION_CREATED, (data) => {
     const event = data as ChildSessionCreatedEvent;
-    registry.register(event.sessionDir, {
-      agentName: event.agentName,
+    registry.register(event.sessionId, {
       parentSessionId: event.parentSessionId,
     });
   });
 
   const unsubDisposed = events.on(SUBAGENT_CHILD_DISPOSED, (data) => {
     const event = data as ChildDisposedEvent;
-    registry.unregister(event.sessionDir);
+    registry.unregister(event.sessionId);
   });
 
   return () => {

package/src/subagent-registry.ts

@@ -7,28 +7,73 @@
  * can detect them without relying on environment variables or filesystem
  * heuristics.
  *
- * The registry is keyed by session directory path, which is unique per
- * session and available to both producer and consumer via
- * `ctx.sessionManager.getSessionDir()`.
+ * The registry is keyed by the child's **session id**, which is unique per
+ * child and available to both producer (via `sessionManager.getSessionId()`
+ * after `newSession()` in `create-subagent-session.ts`) and consumer (via
+ * `ctx.sessionManager.getSessionId()`). Two concurrent siblings of the same
+ * parent therefore occupy distinct keys, so one sibling's `disposed` event
+ * cannot evict the entry the others depend on.
+ *
+ * The single registry instance is stored on `globalThis` (via `Symbol.for()`)
+ * so that the parent's permission-system instance (which registers children
+ * on the parent's event bus) and each child's separate jiti instance (which
+ * reads the registry to detect itself and resolve its forwarding target) share
+ * one store across per-session event buses. See `getSubagentSessionRegistry()`.
+ *
+ * When a future code path needs the child's agent name, read it from
+ * `tcc.agentName` (resolved from the `<active_agent>` system-prompt tag) —
+ * not from this registry.
+ */
+
+/** Process-global key for the shared registry slot. */
+const SUBAGENT_SESSION_REGISTRY_KEY = Symbol.for(
+  "@gotgenes/pi-permission-system:subagent-registry",
+);
+
+/**
+ * Return the process-global SubagentSessionRegistry, creating it on first call.
+ *
+ * Backed by `globalThis` + `Symbol.for()` so the parent's permission-system
+ * instance (which registers children on the parent event bus) and each child's
+ * separate jiti instance (which reads the registry to detect itself and resolve
+ * its forwarding target) share one store across per-session event buses.
+ *
+ * Intentionally has no shutdown/unpublish hook — a child's `session_shutdown`
+ * must not be able to wipe the parent's registrations. Entries are added and
+ * removed exclusively by the parent's `subagents:child:session-created` /
+ * `subagents:child:disposed` subscription.
  */
+export function getSubagentSessionRegistry(): SubagentSessionRegistry {
+  const store = globalThis as Record<symbol, unknown>;
+  const existing = store[SUBAGENT_SESSION_REGISTRY_KEY] as
+    | SubagentSessionRegistry
+    | undefined;
+  if (existing) {
+    return existing;
+  }
+  const registry = new SubagentSessionRegistry();
+  store[SUBAGENT_SESSION_REGISTRY_KEY] = registry;
+  return registry;
+}
 
 /** Signal stored per registered in-process subagent session. */
 export interface SubagentSessionInfo {
   /** Parent session ID for permission forwarding. Omit when unknown. */
   parentSessionId?: string;
-  /** Agent name for per-agent policy resolution. */
-  agentName: string;
 }
 
 /**
  * Registry of active in-process subagent sessions.
  *
- * Owned by `ExtensionRuntime`; written exclusively by `subscribeSubagentLifecycle`
- * via the `subagents:child:session-created` / `subagents:child:disposed` event
- * subscription (ADR 0002 — the core publishes, consumers observe).
+ * A process-global singleton — obtain it via `getSubagentSessionRegistry()`,
+ * never `new` (see that accessor for why). Written exclusively by
+ * `subscribeSubagentLifecycle` via the `subagents:child:session-created` /
+ * `subagents:child:disposed` event subscription (ADR 0002 — the core
+ * publishes, consumers observe).
  *
- * Concurrent background agents are safe because each session has a unique
- * directory path as its key — no scalar global flag is needed.
+ * Keyed by child session id. Each concurrent child of the same parent receives
+ * a unique session id from `sessionManager.newSession()`, so siblings occupy
+ * distinct keys and one sibling's `disposed` cannot evict another's entry.
  */
 export class SubagentSessionRegistry {
   private readonly sessions = new Map<string, SubagentSessionInfo>();
@@ -36,25 +81,25 @@ export class SubagentSessionRegistry {
   /**
    * Register an in-process subagent session.
    *
-   * If a previous entry exists for `sessionKey`, it is overwritten
+   * If a previous entry exists for `sessionId`, it is overwritten
    * (last-write-wins; single-writer expected per key).
    */
-  register(sessionKey: string, info: SubagentSessionInfo): void {
-    this.sessions.set(sessionKey, info);
+  register(sessionId: string, info: SubagentSessionInfo): void {
+    this.sessions.set(sessionId, info);
   }
 
   /** Remove a previously registered session. No-op if the key is absent. */
-  unregister(sessionKey: string): void {
-    this.sessions.delete(sessionKey);
+  unregister(sessionId: string): void {
+    this.sessions.delete(sessionId);
   }
 
-  /** Return the registered info for `sessionKey`, or `undefined` if absent. */
-  get(sessionKey: string): SubagentSessionInfo | undefined {
-    return this.sessions.get(sessionKey);
+  /** Return the registered info for `sessionId`, or `undefined` if absent. */
+  get(sessionId: string): SubagentSessionInfo | undefined {
+    return this.sessions.get(sessionId);
   }
 
-  /** Return `true` when `sessionKey` has a registered entry. */
-  has(sessionKey: string): boolean {
-    return this.sessions.has(sessionKey);
+  /** Return `true` when `sessionId` has a registered entry. */
+  has(sessionId: string): boolean {
+    return this.sessions.has(sessionId);
   }
 }

package/test/permission-forwarding.test.ts

@@ -149,13 +149,11 @@ describe("resolvePermissionForwardingTargetSessionId", () => {
 });
 
 describe("resolvePermissionForwardingTargetSessionId — registry resolution", () => {
-  const sessionDir =
-    "/home/user/projects/.pi/sessions/parent/tasks/session-abc";
+  const childSessionId = "child-session-abc";
 
   test("returns parentSessionId from registry when env vars are absent", () => {
     const registry = new SubagentSessionRegistry();
-    registry.register(sessionDir, {
-      agentName: "Explore",
+    registry.register(childSessionId, {
       parentSessionId: "parent-from-registry",
     });
 
@@ -163,7 +161,7 @@ describe("resolvePermissionForwardingTargetSessionId — registry resolution", (
       resolvePermissionForwardingTargetSessionId({
         hasUI: false,
         isSubagent: true,
-        sessionDir,
+        sessionId: childSessionId,
         registry,
         env: {},
       }),
@@ -172,8 +170,7 @@ describe("resolvePermissionForwardingTargetSessionId — registry resolution", (
 
   test("registry takes priority over env vars", () => {
     const registry = new SubagentSessionRegistry();
-    registry.register(sessionDir, {
-      agentName: "Explore",
+    registry.register(childSessionId, {
       parentSessionId: "parent-from-registry",
     });
 
@@ -181,7 +178,7 @@ describe("resolvePermissionForwardingTargetSessionId — registry resolution", (
       resolvePermissionForwardingTargetSessionId({
         hasUI: false,
         isSubagent: true,
-        sessionDir,
+        sessionId: childSessionId,
         registry,
         env: { PI_AGENT_ROUTER_PARENT_SESSION_ID: "parent-from-env" },
       }),
@@ -190,27 +187,27 @@ describe("resolvePermissionForwardingTargetSessionId — registry resolution", (
 
   test("falls through to env vars when registry entry has no parentSessionId", () => {
     const registry = new SubagentSessionRegistry();
-    registry.register(sessionDir, { agentName: "Explore" }); // no parentSessionId
+    registry.register(childSessionId, {}); // no parentSessionId
 
     expect(
       resolvePermissionForwardingTargetSessionId({
         hasUI: false,
         isSubagent: true,
-        sessionDir,
+        sessionId: childSessionId,
         registry,
         env: { PI_AGENT_ROUTER_PARENT_SESSION_ID: "parent-from-env" },
       }),
     ).toBe("parent-from-env");
   });
 
-  test("falls through to env vars when sessionDir is not in registry", () => {
+  test("falls through to env vars when sessionId is not in registry", () => {
     const registry = new SubagentSessionRegistry(); // empty
 
     expect(
       resolvePermissionForwardingTargetSessionId({
         hasUI: false,
         isSubagent: true,
-        sessionDir,
+        sessionId: childSessionId,
         registry,
         env: { PI_AGENT_ROUTER_PARENT_SESSION_ID: "parent-from-env" },
       }),
@@ -219,13 +216,13 @@ describe("resolvePermissionForwardingTargetSessionId — registry resolution", (
 
   test("returns null when registry entry has no parentSessionId and no env vars set", () => {
     const registry = new SubagentSessionRegistry();
-    registry.register(sessionDir, { agentName: "Explore" }); // no parentSessionId
+    registry.register(childSessionId, {}); // no parentSessionId
 
     expect(
       resolvePermissionForwardingTargetSessionId({
         hasUI: false,
         isSubagent: true,
-        sessionDir,
+        sessionId: childSessionId,
         registry,
         env: {},
       }),
@@ -237,7 +234,7 @@ describe("resolvePermissionForwardingTargetSessionId — registry resolution", (
       resolvePermissionForwardingTargetSessionId({
         hasUI: false,
         isSubagent: true,
-        sessionDir,
+        sessionId: childSessionId,
         env: { PI_AGENT_ROUTER_PARENT_SESSION_ID: "parent-from-env" },
       }),
     ).toBe("parent-from-env");

package/test/subagent-context.test.ts

@@ -12,10 +12,14 @@ afterEach(() => {
   vi.restoreAllMocks();
 });
 
-function makeCtx(sessionDir: string | null): ExtensionContext {
+function makeCtx(
+  sessionDir: string | null,
+  sessionId: string = "",
+): ExtensionContext {
   return {
     sessionManager: {
       getSessionDir: vi.fn(() => sessionDir),
+      getSessionId: vi.fn(() => sessionId),
     },
   } as unknown as ExtensionContext;
 }
@@ -203,57 +207,75 @@ describe("isSubagentExecutionContext — registry detection", () => {
   const subagentRoot = "/home/user/.pi/agent/sessions/subagents";
   const outsideDir =
     "/home/user/projects/my-app/.pi/agent/sessions/parent/tasks";
+  const childSessionId = "child-session-abc";
 
-  test("returns true when session dir is registered (no env vars, outside filesystem root)", () => {
+  test("returns true when session id is registered (no env vars, dir outside filesystem root)", () => {
     const registry = new SubagentSessionRegistry();
-    registry.register(outsideDir, { agentName: "Explore" });
+    registry.register(childSessionId, {});
     expect(
-      isSubagentExecutionContext(makeCtx(outsideDir), subagentRoot, registry),
+      isSubagentExecutionContext(
+        makeCtx(outsideDir, childSessionId),
+        subagentRoot,
+        registry,
+      ),
     ).toBe(true);
   });
 
   test("returns true when registered session has a parentSessionId", () => {
     const registry = new SubagentSessionRegistry();
-    registry.register(outsideDir, {
-      agentName: "Plan",
-      parentSessionId: "parent-123",
-    });
+    registry.register(childSessionId, { parentSessionId: "parent-123" });
     expect(
-      isSubagentExecutionContext(makeCtx(outsideDir), subagentRoot, registry),
+      isSubagentExecutionContext(
+        makeCtx(outsideDir, childSessionId),
+        subagentRoot,
+        registry,
+      ),
     ).toBe(true);
   });
 
-  test("returns false when registry is provided but session dir is not registered", () => {
+  test("returns false when registry is provided but session id is not registered", () => {
     const registry = new SubagentSessionRegistry();
     expect(
-      isSubagentExecutionContext(makeCtx(outsideDir), subagentRoot, registry),
+      isSubagentExecutionContext(
+        makeCtx(outsideDir, childSessionId),
+        subagentRoot,
+        registry,
+      ),
     ).toBe(false);
   });
 
-  test("returns false when session dir is null and registry has no matching entry", () => {
+  test("returns false when session id is empty and registry has no matching entry", () => {
     const registry = new SubagentSessionRegistry();
     expect(
-      isSubagentExecutionContext(makeCtx(null), subagentRoot, registry),
+      isSubagentExecutionContext(makeCtx(null, ""), subagentRoot, registry),
     ).toBe(false);
   });
 
   test("registry check takes priority over env var detection", () => {
     // Registry says registered; env var not set — should still return true.
     const registry = new SubagentSessionRegistry();
-    registry.register(outsideDir, { agentName: "Explore" });
+    registry.register(childSessionId, {});
     // Confirm no env var is set
     expect(process.env.PI_IS_SUBAGENT).toBeUndefined();
     expect(
-      isSubagentExecutionContext(makeCtx(outsideDir), subagentRoot, registry),
+      isSubagentExecutionContext(
+        makeCtx(outsideDir, childSessionId),
+        subagentRoot,
+        registry,
+      ),
     ).toBe(true);
   });
 
   test("unregistered session falls through to env var detection", () => {
     vi.stubEnv("PI_IS_SUBAGENT", "true");
-    const registry = new SubagentSessionRegistry(); // empty — outsideDir not registered
+    const registry = new SubagentSessionRegistry(); // empty — childSessionId not registered
     // Env var present → still true even without registry entry
     expect(
-      isSubagentExecutionContext(makeCtx(outsideDir), subagentRoot, registry),
+      isSubagentExecutionContext(
+        makeCtx(outsideDir, childSessionId),
+        subagentRoot,
+        registry,
+      ),
     ).toBe(true);
   });
 

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

@@ -19,13 +19,11 @@ describe("subscribeSubagentLifecycle", () => {
     subscribeSubagentLifecycle(bus, registry);
 
     bus.emit(SUBAGENT_CHILD_SESSION_CREATED, {
-      sessionDir: "/sessions/child-abc",
-      agentName: "Explore",
+      sessionId: "child-session-abc",
       parentSessionId: "parent-42",
     });
 
-    expect(registry.get("/sessions/child-abc")).toEqual({
-      agentName: "Explore",
+    expect(registry.get("child-session-abc")).toEqual({
       parentSessionId: "parent-42",
     });
   });
@@ -40,12 +38,11 @@ describe("subscribeSubagentLifecycle", () => {
     subscribeSubagentLifecycle(bus, registry);
 
     bus.emit(SUBAGENT_CHILD_SESSION_CREATED, {
-      sessionDir: "/sessions/child-sync",
-      agentName: "Explore",
+      sessionId: "child-session-sync",
     });
 
     // No await between emit and this assertion.
-    expect(registry.has("/sessions/child-sync")).toBe(true);
+    expect(registry.has("child-session-sync")).toBe(true);
   });
 
   it("omits parentSessionId when the event does not carry one", () => {
@@ -53,12 +50,10 @@ describe("subscribeSubagentLifecycle", () => {
     subscribeSubagentLifecycle(bus, registry);
 
     bus.emit(SUBAGENT_CHILD_SESSION_CREATED, {
-      sessionDir: "/sessions/child-xyz",
-      agentName: "general-purpose",
+      sessionId: "child-session-xyz",
     });
 
-    expect(registry.get("/sessions/child-xyz")).toEqual({
-      agentName: "general-purpose",
+    expect(registry.get("child-session-xyz")).toEqual({
       parentSessionId: undefined,
     });
   });
@@ -66,11 +61,11 @@ describe("subscribeSubagentLifecycle", () => {
   it("unregisters a child session on disposed", () => {
     const bus = createEventBus();
     subscribeSubagentLifecycle(bus, registry);
-    registry.register("/sessions/child-abc", { agentName: "Explore" });
+    registry.register("child-session-abc", { parentSessionId: "parent-42" });
 
-    bus.emit(SUBAGENT_CHILD_DISPOSED, { sessionDir: "/sessions/child-abc" });
+    bus.emit(SUBAGENT_CHILD_DISPOSED, { sessionId: "child-session-abc" });
 
-    expect(registry.has("/sessions/child-abc")).toBe(false);
+    expect(registry.has("child-session-abc")).toBe(false);
   });
 
   it("detaches both handlers when the returned unsubscribe is called", () => {
@@ -80,12 +75,11 @@ describe("subscribeSubagentLifecycle", () => {
     unsubscribe();
 
     bus.emit(SUBAGENT_CHILD_SESSION_CREATED, {
-      sessionDir: "/sessions/child-abc",
-      agentName: "Explore",
+      sessionId: "child-session-abc",
     });
-    bus.emit(SUBAGENT_CHILD_DISPOSED, { sessionDir: "/sessions/child-abc" });
+    bus.emit(SUBAGENT_CHILD_DISPOSED, { sessionId: "child-session-abc" });
 
-    expect(registry.has("/sessions/child-abc")).toBe(false);
+    expect(registry.has("child-session-abc")).toBe(false);
   });
 
   it("subscribes to a fake bus on the exact channel names", () => {
@@ -110,4 +104,29 @@ describe("subscribeSubagentLifecycle", () => {
     );
     expect(SUBAGENT_CHILD_DISPOSED).toBe("subagents:child:disposed");
   });
+
+  // ── #298 regression: concurrent siblings must be independent ──────────────
+
+  it("disposing one sibling does not evict the other (collision regression)", () => {
+    const bus = createEventBus();
+    subscribeSubagentLifecycle(bus, registry);
+
+    // Two concurrent children of the same parent register under distinct ids.
+    bus.emit(SUBAGENT_CHILD_SESSION_CREATED, {
+      sessionId: "child-A",
+      parentSessionId: "parent-P",
+    });
+    bus.emit(SUBAGENT_CHILD_SESSION_CREATED, {
+      sessionId: "child-B",
+      parentSessionId: "parent-P",
+    });
+
+    // Sibling A finishes first.
+    bus.emit(SUBAGENT_CHILD_DISPOSED, { sessionId: "child-A" });
+
+    // B must still be detected as a registered subagent.
+    expect(registry.has("child-A")).toBe(false);
+    expect(registry.has("child-B")).toBe(true);
+    expect(registry.get("child-B")?.parentSessionId).toBe("parent-P");
+  });
 });

package/test/subagent-registry.test.ts

@@ -1,94 +1,145 @@
-import { describe, expect, test } from "vitest";
+import { afterEach, describe, expect, test } from "vitest";
 import {
+  getSubagentSessionRegistry,
   type SubagentSessionInfo,
   SubagentSessionRegistry,
 } from "#src/subagent-registry";
 
+const REGISTRY_KEY = Symbol.for(
+  "@gotgenes/pi-permission-system:subagent-registry",
+);
+
 function makeInfo(
   overrides: Partial<SubagentSessionInfo> = {},
 ): SubagentSessionInfo {
-  return {
-    agentName: "Explore",
-    ...overrides,
-  };
+  return { ...overrides };
 }
 
 describe("SubagentSessionRegistry", () => {
   test("has() returns false for an unregistered key", () => {
     const registry = new SubagentSessionRegistry();
-    expect(registry.has("/sessions/task-abc")).toBe(false);
+    expect(registry.has("session-abc")).toBe(false);
   });
 
   test("get() returns undefined for an unregistered key", () => {
     const registry = new SubagentSessionRegistry();
-    expect(registry.get("/sessions/task-abc")).toBeUndefined();
+    expect(registry.get("session-abc")).toBeUndefined();
   });
 
   test("has() returns true after register()", () => {
     const registry = new SubagentSessionRegistry();
-    registry.register("/sessions/task-abc", makeInfo());
-    expect(registry.has("/sessions/task-abc")).toBe(true);
+    registry.register("session-abc", makeInfo());
+    expect(registry.has("session-abc")).toBe(true);
   });
 
   test("get() returns the registered info after register()", () => {
     const registry = new SubagentSessionRegistry();
     const info = makeInfo({ parentSessionId: "parent-123" });
-    registry.register("/sessions/task-abc", info);
-    expect(registry.get("/sessions/task-abc")).toEqual(info);
+    registry.register("session-abc", info);
+    expect(registry.get("session-abc")).toEqual(info);
   });
 
-  test("register() stores agentName without parentSessionId", () => {
+  test("register() stores entry without parentSessionId", () => {
     const registry = new SubagentSessionRegistry();
-    registry.register("/sessions/task-abc", makeInfo());
-    expect(registry.get("/sessions/task-abc")).toEqual({
-      agentName: "Explore",
-    });
+    registry.register("session-abc", makeInfo());
+    expect(registry.get("session-abc")).toEqual({});
   });
 
   test("has() returns false after unregister()", () => {
     const registry = new SubagentSessionRegistry();
-    registry.register("/sessions/task-abc", makeInfo());
-    registry.unregister("/sessions/task-abc");
-    expect(registry.has("/sessions/task-abc")).toBe(false);
+    registry.register("session-abc", makeInfo());
+    registry.unregister("session-abc");
+    expect(registry.has("session-abc")).toBe(false);
   });
 
   test("get() returns undefined after unregister()", () => {
     const registry = new SubagentSessionRegistry();
-    registry.register("/sessions/task-abc", makeInfo());
-    registry.unregister("/sessions/task-abc");
-    expect(registry.get("/sessions/task-abc")).toBeUndefined();
+    registry.register("session-abc", makeInfo());
+    registry.unregister("session-abc");
+    expect(registry.get("session-abc")).toBeUndefined();
   });
 
   test("unregister() is a no-op for an unknown key", () => {
     const registry = new SubagentSessionRegistry();
-    expect(() => registry.unregister("/sessions/nonexistent")).not.toThrow();
+    expect(() => registry.unregister("session-nonexistent")).not.toThrow();
   });
 
   test("register() overwrites a previous entry for the same key", () => {
+    const registry = new SubagentSessionRegistry();
+    registry.register("session-abc", makeInfo({ parentSessionId: "parent-1" }));
+    registry.register("session-abc", makeInfo({ parentSessionId: "parent-2" }));
+    expect(registry.get("session-abc")?.parentSessionId).toBe("parent-2");
+  });
+
+  // ── #298 regression: concurrent siblings must be independent ──────────────
+
+  test("two sibling session ids are registered independently", () => {
     const registry = new SubagentSessionRegistry();
     registry.register(
-      "/sessions/task-abc",
-      makeInfo({ parentSessionId: "parent-1" }),
+      "child-session-A",
+      makeInfo({ parentSessionId: "parent-P" }),
     );
     registry.register(
-      "/sessions/task-abc",
-      makeInfo({ parentSessionId: "parent-2" }),
-    );
-    expect(registry.get("/sessions/task-abc")?.parentSessionId).toBe(
-      "parent-2",
+      "child-session-B",
+      makeInfo({ parentSessionId: "parent-P" }),
     );
+
+    expect(registry.has("child-session-A")).toBe(true);
+    expect(registry.has("child-session-B")).toBe(true);
   });
 
-  test("multiple keys are independent", () => {
+  test("disposing one sibling does not evict the other (collision regression)", () => {
     const registry = new SubagentSessionRegistry();
-    registry.register("/sessions/task-1", makeInfo({ agentName: "Explore" }));
-    registry.register("/sessions/task-2", makeInfo({ agentName: "Plan" }));
+    registry.register(
+      "child-session-A",
+      makeInfo({ parentSessionId: "parent-P" }),
+    );
+    registry.register(
+      "child-session-B",
+      makeInfo({ parentSessionId: "parent-P" }),
+    );
+
+    // Sibling A finishes — should not affect B.
+    registry.unregister("child-session-A");
 
-    expect(registry.get("/sessions/task-1")?.agentName).toBe("Explore");
-    expect(registry.get("/sessions/task-2")?.agentName).toBe("Plan");
+    expect(registry.has("child-session-A")).toBe(false);
+    expect(registry.has("child-session-B")).toBe(true);
+    expect(registry.get("child-session-B")?.parentSessionId).toBe("parent-P");
+  });
+});
+
+// ── process-global accessor ────────────────────────────────────────────────
+
+describe("getSubagentSessionRegistry (process-global accessor)", () => {
+  afterEach(() => {
+    // eslint-disable-next-line @typescript-eslint/no-dynamic-delete -- Symbol-keyed global property; Map.delete() is not applicable
+    delete (globalThis as Record<symbol, unknown>)[REGISTRY_KEY];
+  });
+
+  test("returns a SubagentSessionRegistry instance", () => {
+    const registry = getSubagentSessionRegistry();
+    expect(registry).toBeInstanceOf(SubagentSessionRegistry);
+  });
+
+  test("returns the same instance on repeated calls", () => {
+    const first = getSubagentSessionRegistry();
+    const second = getSubagentSessionRegistry();
+    expect(first).toBe(second);
+  });
+
+  test("state registered through one call is visible through another call", () => {
+    const writer = getSubagentSessionRegistry();
+    writer.register("child-session-xyz", {
+      parentSessionId: "parent-abc",
+    });
+
+    const reader = getSubagentSessionRegistry();
+    expect(reader.has("child-session-xyz")).toBe(true);
+    expect(reader.get("child-session-xyz")?.parentSessionId).toBe("parent-abc");
+  });
 
-    registry.unregister("/sessions/task-1");
-    expect(registry.has("/sessions/task-1")).toBe(false);
-    expect(registry.has("/sessions/task-2")).toBe(true);
+  test("starts empty on first call", () => {
+    const registry = getSubagentSessionRegistry();
+    expect(registry.has("any-session-id")).toBe(false);
   });
 });