@gotgenes/pi-permission-system 8.3.2 → 9.0.0

package/CHANGELOG.md

@@ -5,6 +5,27 @@ 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).
 
+## [9.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v8.3.2...pi-permission-system-v9.0.0) (2026-06-01)
+
+
+### ⚠ BREAKING CHANGES
+
+* unpublishPermissionsService() now requires the service to remove as its sole argument. The package's public export is service.ts, so this changes the published API surface.
+
+### Features
+
+* scope service teardown to the publishing instance ([#302](https://github.com/gotgenes/pi-packages/issues/302)) ([72180e9](https://github.com/gotgenes/pi-packages/commit/72180e906f7370c842cd5e31a11726c2971fc988))
+
+
+### Bug Fixes
+
+* keep the parent's service published across child shutdown ([#302](https://github.com/gotgenes/pi-packages/issues/302)) ([300214c](https://github.com/gotgenes/pi-packages/commit/300214ca21d985bfba7231f261c022c394d8bf5a))
+
+
+### Documentation
+
+* document session_start service publication and ready timing ([#302](https://github.com/gotgenes/pi-packages/issues/302)) ([a894fb8](https://github.com/gotgenes/pi-packages/commit/a894fb8d5c2bbc7cd9d33769859d172c5a7dbb73))
+
 ## [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)
 
 

package/package.json

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

package/src/handlers/lifecycle.ts

@@ -18,11 +18,14 @@ interface ResourcesDiscoverPayload {
  *
  * Constructor deps:
  * - `session` — encapsulates all mutable session state
+ * - `activateService` — publishes the process-global service for this session
+ *   (skipped for in-process subagent children) and emits the ready event
  * - `cleanupRpc` — unsubscribes RPC handlers on shutdown
  */
 export class SessionLifecycleHandler {
   constructor(
     private readonly session: PermissionSession,
+    private readonly activateService: (ctx: ExtensionContext) => void,
     private readonly cleanupRpc: () => void,
   ) {}
 
@@ -47,6 +50,12 @@ export class SessionLifecycleHandler {
         cwd: ctx.cwd,
       });
     }
+
+    // Publish the process-global service now that a ctx (and therefore the
+    // session id) is available, so an in-process subagent child can be
+    // identified and excluded. Emitting ready here keeps the
+    // service-resolvable-when-ready ordering contract.
+    this.activateService(ctx);
     return Promise.resolve();
   }
 

package/src/index.ts

@@ -1,4 +1,7 @@
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
 import { registerBuiltinToolInputFormatters } from "./builtin-tool-input-formatters";
 import { registerPermissionSystemCommand } from "./config-modal";
 import { getGlobalConfigPath } from "./config-paths";
@@ -27,7 +30,10 @@ import {
   unpublishPermissionsService,
 } from "./service";
 import { createSessionLogger } from "./session-logger";
-import { isSubagentExecutionContext } from "./subagent-context";
+import {
+  isRegisteredSubagentChild,
+  isSubagentExecutionContext,
+} from "./subagent-context";
 import { subscribeSubagentLifecycle } from "./subagent-lifecycle-events";
 import { getSubagentSessionRegistry } from "./subagent-registry";
 import { ToolInputFormatterRegistry } from "./tool-input-formatter-registry";
@@ -129,7 +135,18 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
       return formatterRegistry.register(toolName, formatter);
     },
   };
-  publishPermissionsService(permissionsService);
+
+  // Publish the service to the process-global slot only when this instance is
+  // not an in-process subagent child, then emit ready. Deferred to
+  // session_start (vs. factory init) because identifying a child requires the
+  // session id from ctx, which the factory body does not have. A registered
+  // child therefore never clobbers the parent's published service. See #302.
+  const activateServiceForSession = (ctx: ExtensionContext): void => {
+    if (!isRegisteredSubagentChild(ctx, subagentRegistry)) {
+      publishPermissionsService(permissionsService);
+    }
+    emitReadyEvent(pi.events);
+  };
 
   // Subscribe to @gotgenes/pi-subagents' child lifecycle events so child
   // sessions register/unregister without the core calling us (ADR 0002).
@@ -138,19 +155,21 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
     subagentRegistry,
   );
 
-  emitReadyEvent(pi.events);
-
   const toolRegistry = {
     getAll: () => pi.getAllTools(),
     setActive: (names: string[]) => pi.setActiveTools(names),
   };
 
-  const lifecycle = new SessionLifecycleHandler(session, () => {
-    rpcHandles.unsubCheck();
-    rpcHandles.unsubPrompt();
-    unsubSubagentLifecycle();
-    unpublishPermissionsService();
-  });
+  const lifecycle = new SessionLifecycleHandler(
+    session,
+    activateServiceForSession,
+    () => {
+      rpcHandles.unsubCheck();
+      rpcHandles.unsubPrompt();
+      unsubSubagentLifecycle();
+      unpublishPermissionsService(permissionsService);
+    },
+  );
   const agentPrep = new AgentPrepHandler(session, toolRegistry);
   const gates = new PermissionGateHandler(
     session,

package/src/permission-events.ts

@@ -24,7 +24,7 @@ export const PERMISSIONS_PROTOCOL_VERSION = 1;
 
 // ── Channel name constants ─────────────────────────────────────────────────
 
-/** Emitted once on extension load. */
+/** Emitted at `session_start`, after the service is published. */
 export const PERMISSIONS_READY_CHANNEL = "permissions:ready";
 
 /** Emitted after every permission gate resolution. */
@@ -160,7 +160,8 @@ export interface PermissionsPromptReplyData {
 
 /**
  * Emit the `permissions:ready` broadcast.
- * Call once after the extension has finished setup.
+ * Call at `session_start`, after the service is published, so a consumer
+ * reacting to ready can immediately resolve `getPermissionsService()`.
  */
 export function emitReadyEvent(events: PermissionEventBus): void {
   const payload: PermissionsReadyEvent = {

package/src/service.ts

@@ -81,7 +81,10 @@ export interface PermissionsService {
  * Store a `PermissionsService` on `globalThis` so other extensions can
  * retrieve it via `getPermissionsService()`.
  *
- * Overwrites any previously published service — safe for `/reload`.
+ * Called at `session_start` by the top-level (parent) instance only — an
+ * in-process subagent child skips publishing so it cannot clobber the parent's
+ * service. Overwrites any previously published service, which keeps `/reload`
+ * working: a reloaded parent re-publishes its fresh service.
  */
 export function publishPermissionsService(service: PermissionsService): void {
   (globalThis as Record<symbol, unknown>)[SERVICE_KEY] = service;
@@ -98,12 +101,22 @@ export function getPermissionsService(): PermissionsService | undefined {
 }
 
 /**
- * Remove the service from `globalThis`.
+ * Remove `service` from `globalThis`, but only when the current slot still
+ * holds it (identity compare-and-delete).
  *
  * Called during `session_shutdown` to avoid stale references after the
- * extension is torn down.
+ * extension is torn down. Scoping the delete to the publishing instance keeps
+ * two cases correct:
+ *
+ * - An in-process subagent child never published the parent's service, so its
+ *   shutdown is a no-op and the parent's slot survives.
+ * - A superseded `/reload` generation no longer owns the slot, so its late
+ *   shutdown cannot wipe the new generation's freshly published service.
  */
-export function unpublishPermissionsService(): void {
+export function unpublishPermissionsService(service: PermissionsService): void {
+  if (getPermissionsService() !== service) {
+    return;
+  }
   // eslint-disable-next-line @typescript-eslint/no-dynamic-delete -- Symbol-keyed global property; Map.delete() is not applicable
   delete (globalThis as Record<symbol, unknown>)[SERVICE_KEY];
 }

package/src/subagent-context.ts

@@ -28,6 +28,32 @@ function isPathWithinDirectoryForSubagent(
   return pathValue.startsWith(prefix);
 }
 
+/**
+ * Return `true` when `ctx` belongs to an in-process subagent child registered
+ * in `registry` by its session id.
+ *
+ * This is the only signal that identifies an **in-process** child (one sharing
+ * the parent's `globalThis`); env-hint and filesystem heuristics identify
+ * **process-based** subagents instead. The composition root uses this to decide
+ * whether the instance owns the process-global service slot — a registered
+ * child must not publish over its parent.
+ */
+export function isRegisteredSubagentChild(
+  ctx: ExtensionContext,
+  registry: SubagentSessionRegistry,
+): boolean {
+  try {
+    const sessionId = ctx.sessionManager.getSessionId();
+    if (!sessionId) {
+      return false;
+    }
+    return registry.has(sessionId);
+  } catch {
+    // getSessionId() unavailable — treat as not-a-registered-child.
+    return false;
+  }
+}
+
 export function isSubagentExecutionContext(
   ctx: ExtensionContext,
   subagentSessionsDir: string,
@@ -37,15 +63,8 @@ export function isSubagentExecutionContext(
   //    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.
-    }
+  if (registry && isRegisteredSubagentChild(ctx, registry)) {
+    return true;
   }
 
   const sessionDir = ctx.sessionManager.getSessionDir();

package/test/composition-root.test.ts

@@ -0,0 +1,398 @@
+/**
+ * Composition-root tests for `piPermissionSystemExtension(pi)`.
+ *
+ * These run the real factory via the `makeFakePi()` harness and assert the
+ * wiring contracts that unit tests cannot see: handler-registration
+ * completeness, shared-instance contracts across factory invocations, teardown,
+ * service↔gate registry sharing, and `ready`-after-publish ordering.
+ *
+ * Every test runs the factory, which mutates two process-global `Symbol.for()`
+ * slots and reads `PI_CODING_AGENT_DIR`. The shared `beforeEach`/`afterEach`
+ * isolate the agent dir to a tmpdir and clear both global slots so factory runs
+ * do not leak across tests.
+ */
+import {
+  mkdirSync,
+  mkdtempSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+
+import {
+  createEventBus,
+  type ExtensionAPI,
+} from "@earendil-works/pi-coding-agent";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { getGlobalConfigPath } from "#src/config-paths";
+import { DEFAULT_EXTENSION_CONFIG } from "#src/extension-config";
+import piPermissionSystemExtension from "#src/index";
+import { PERMISSIONS_READY_CHANNEL } from "#src/permission-events";
+import {
+  createPermissionForwardingLocation,
+  type ForwardedPermissionRequest,
+} from "#src/permission-forwarding";
+import { getPermissionsService } from "#src/service";
+import { SUBAGENT_CHILD_SESSION_CREATED } from "#src/subagent-lifecycle-events";
+import { getSubagentSessionRegistry } from "#src/subagent-registry";
+import { makeFakePi } from "#test/helpers/make-fake-pi";
+
+const SERVICE_KEY = Symbol.for("@gotgenes/pi-permission-system:service");
+const SUBAGENT_REGISTRY_KEY = Symbol.for(
+  "@gotgenes/pi-permission-system:subagent-registry",
+);
+
+/** The six events the factory must register a handler for. */
+const EXPECTED_HANDLERS = [
+  "before_agent_start",
+  "input",
+  "resources_discover",
+  "session_shutdown",
+  "session_start",
+  "tool_call",
+];
+
+let agentDir: string;
+
+beforeEach(() => {
+  agentDir = mkdtempSync(join(tmpdir(), "pi-perm-comp-root-"));
+  vi.stubEnv("PI_CODING_AGENT_DIR", agentDir);
+});
+
+afterEach(() => {
+  // Drop both process-global slots so factory runs do not leak across tests.
+  const store = globalThis as Record<symbol, unknown>;
+  // eslint-disable-next-line @typescript-eslint/no-dynamic-delete -- Symbol-keyed global property
+  delete store[SERVICE_KEY];
+  // eslint-disable-next-line @typescript-eslint/no-dynamic-delete -- Symbol-keyed global property
+  delete store[SUBAGENT_REGISTRY_KEY];
+  vi.unstubAllEnvs();
+  rmSync(agentDir, { recursive: true, force: true });
+});
+
+// ── Shared helpers ──────────────────────────────────────────────────────────
+
+/** Write the global config file under the stubbed agent dir. */
+function writeGlobalConfig(config: Record<string, unknown>): void {
+  const globalConfigPath = getGlobalConfigPath(agentDir);
+  mkdirSync(dirname(globalConfigPath), { recursive: true });
+  writeFileSync(
+    globalConfigPath,
+    `${JSON.stringify({ ...DEFAULT_EXTENSION_CONFIG, ...config }, null, 2)}\n`,
+    "utf8",
+  );
+}
+
+/** Build a minimal subagent `ctx` (no UI) for driving tool-call gates. */
+function makeChildCtx(cwd: string, sessionId: string): unknown {
+  return {
+    cwd,
+    hasUI: false,
+    sessionManager: {
+      getEntries: (): unknown[] => [],
+      getSessionId: (): string => sessionId,
+      getSessionDir: (): string => cwd,
+    },
+    ui: {
+      notify: (): void => {},
+      setStatus: (): void => {},
+      select: async (): Promise<string | undefined> => undefined,
+      input: async (): Promise<string | undefined> => undefined,
+    },
+  };
+}
+
+/**
+ * Build a UI-present `ctx` that records the titles passed to `ui.select`, and
+ * approves every prompt. The ask-prompt message (which embeds the tool-input
+ * preview) is the first line of the select title.
+ */
+function makeUiCtx(cwd: string, capturedTitles: string[]): { ctx: unknown } {
+  const ctx = {
+    cwd,
+    hasUI: true,
+    sessionManager: {
+      getEntries: (): unknown[] => [],
+      getSessionId: (): string => "ui-session",
+      getSessionDir: (): string => cwd,
+    },
+    ui: {
+      notify: (): void => {},
+      setStatus: (): void => {},
+      select: async (title: string): Promise<string | undefined> => {
+        capturedTitles.push(title);
+        return "Yes";
+      },
+      input: async (): Promise<string | undefined> => undefined,
+    },
+  };
+  return { ctx };
+}
+
+const sleep = (ms: number): Promise<void> =>
+  new Promise((resolve) => setTimeout(resolve, ms));
+
+/** Drive the registered `session_start` handler with a ctx. */
+function fireSessionStart(
+  pi: ReturnType<typeof makeFakePi>,
+  ctx: unknown,
+): Promise<unknown> {
+  return pi.fire("session_start", { reason: "start" }, ctx);
+}
+
+/**
+ * Simulate the parent UI session responding to a forwarded permission request.
+ *
+ * Polls the parent's requests directory for the child's request file, then
+ * writes an approval response so the child's forwarding poll resolves quickly
+ * instead of waiting out the 10-minute timeout.
+ */
+async function approveForwardedRequest(
+  forwardingDir: string,
+  parentSessionId: string,
+): Promise<ForwardedPermissionRequest> {
+  const location = createPermissionForwardingLocation(
+    forwardingDir,
+    parentSessionId,
+  );
+  const deadline = Date.now() + 2000;
+  while (Date.now() < deadline) {
+    let files: string[] = [];
+    try {
+      files = readdirSync(location.requestsDir).filter((f) =>
+        f.endsWith(".json"),
+      );
+    } catch {
+      files = [];
+    }
+    const requestFile = files[0];
+    if (requestFile) {
+      const request = JSON.parse(
+        readFileSync(join(location.requestsDir, requestFile), "utf8"),
+      ) as ForwardedPermissionRequest;
+      mkdirSync(location.responsesDir, { recursive: true });
+      writeFileSync(
+        join(location.responsesDir, `${request.id}.json`),
+        JSON.stringify({
+          approved: true,
+          state: "approved",
+          responderSessionId: parentSessionId,
+          respondedAt: Date.now(),
+        }),
+        "utf8",
+      );
+      return request;
+    }
+    await sleep(5);
+  }
+  throw new Error("Timed out waiting for the forwarded permission request");
+}
+
+describe("event-handler registration completeness", () => {
+  it("registers a handler for every required event exactly once", () => {
+    const pi = makeFakePi();
+    piPermissionSystemExtension(pi as unknown as ExtensionAPI);
+
+    expect([...pi.handlers.keys()].sort()).toEqual(EXPECTED_HANDLERS);
+  });
+});
+
+describe("subagent registry sharing across factory instances", () => {
+  // The #296 regression class: two factory invocations on *different* event
+  // buses must still resolve the same process-global SubagentSessionRegistry,
+  // so a child registered via the parent's bus detects itself as a subagent and
+  // forwards (rather than blocking) an external-directory `ask`.
+  it("lets a child instance forward an ask it received via the parent's bus", async () => {
+    writeGlobalConfig({
+      permission: { "*": "allow", external_directory: "ask" },
+    });
+
+    const childCwd = mkdtempSync(join(tmpdir(), "pi-perm-child-cwd-"));
+    const externalDir = mkdtempSync(join(tmpdir(), "pi-perm-external-"));
+    const forwardingDir = join(agentDir, "sessions", "permission-forwarding");
+    const parentSessionId = "parent-session-1";
+    const childSessionId = "child-session-1";
+
+    // Two factory instances, each wired to its own event bus (as in production:
+    // every session's ResourceLoader creates a separate bus).
+    const parentBus = createEventBus();
+    const childBus = createEventBus();
+    piPermissionSystemExtension(
+      makeFakePi({ events: parentBus }) as unknown as ExtensionAPI,
+    );
+    const childPi = makeFakePi({
+      events: childBus,
+      toolNames: ["read"],
+    });
+    piPermissionSystemExtension(childPi as unknown as ExtensionAPI);
+
+    // The child session is announced on the *parent's* bus only; the parent's
+    // lifecycle subscription writes it into the shared global registry.
+    parentBus.emit(SUBAGENT_CHILD_SESSION_CREATED, {
+      sessionId: childSessionId,
+      parentSessionId,
+    });
+
+    // The child fires an external-directory read with no UI. With the shared
+    // registry it detects itself as a subagent and forwards; the simulated
+    // parent approves.
+    const firePromise = childPi.fire(
+      "tool_call",
+      {
+        toolName: "read",
+        toolCallId: "child-external-read",
+        input: { path: join(externalDir, "secret.txt") },
+      },
+      makeChildCtx(childCwd, childSessionId),
+    );
+
+    const request = await approveForwardedRequest(
+      forwardingDir,
+      parentSessionId,
+    );
+    expect(request.targetSessionId).toBe(parentSessionId);
+    expect(request.requesterSessionId).toBe(childSessionId);
+
+    const result = (await firePromise) as { block?: true };
+    expect(result.block).toBeUndefined();
+
+    rmSync(childCwd, { recursive: true, force: true });
+    rmSync(externalDir, { recursive: true, force: true });
+  });
+});
+
+describe("shutdown teardown chain", () => {
+  it("unpublishes the service and unsubscribes the lifecycle on shutdown", async () => {
+    const cwd = mkdtempSync(join(tmpdir(), "pi-perm-teardown-cwd-"));
+    const pi = makeFakePi();
+    piPermissionSystemExtension(pi as unknown as ExtensionAPI);
+
+    // The service is published at session_start, not at factory init.
+    await fireSessionStart(pi, makeChildCtx(cwd, "top-session"));
+    expect(getPermissionsService()).toBeDefined();
+
+    await pi.fire("session_shutdown");
+
+    // Service slot cleared.
+    expect(getPermissionsService()).toBeUndefined();
+
+    // Lifecycle unsubscribed: a post-shutdown session-created must not register.
+    pi.events.emit(SUBAGENT_CHILD_SESSION_CREATED, {
+      sessionId: "late-child",
+      parentSessionId: "p-late",
+    });
+    expect(getSubagentSessionRegistry().has("late-child")).toBe(false);
+
+    rmSync(cwd, { recursive: true, force: true });
+  });
+});
+
+describe("service and gate share one formatter registry", () => {
+  // A formatter registered through the published service must be consulted by
+  // the live gate handler — proving both reference the same
+  // ToolInputFormatterRegistry instance the factory created once.
+  it("surfaces a service-registered formatter in the gate's ask prompt", async () => {
+    writeGlobalConfig({
+      permission: { "*": "allow", demo: "ask" },
+    });
+
+    const cwd = mkdtempSync(join(tmpdir(), "pi-perm-ui-cwd-"));
+    const pi = makeFakePi({ toolNames: ["demo"] });
+    piPermissionSystemExtension(pi as unknown as ExtensionAPI);
+
+    const capturedTitles: string[] = [];
+    const { ctx } = makeUiCtx(cwd, capturedTitles);
+    // The service is published at session_start; publish before resolving it.
+    await fireSessionStart(pi, ctx);
+
+    const previewMarker = "PREVIEW::shared-registry-proof";
+    getPermissionsService()!.registerToolInputFormatter(
+      "demo",
+      () => previewMarker,
+    );
+    const result = (await pi.fire(
+      "tool_call",
+      { toolName: "demo", toolCallId: "demo-ask", input: { foo: "bar" } },
+      ctx,
+    )) as { block?: true };
+
+    // The gate prompted (not blocked) and the prompt embedded the formatter's
+    // preview — so the gate consulted the same registry the service wrote to.
+    expect(result.block).toBeUndefined();
+    expect(capturedTitles.some((t) => t.includes(previewMarker))).toBe(true);
+
+    rmSync(cwd, { recursive: true, force: true });
+  });
+});
+
+describe("ready emitted after service publication", () => {
+  // Ordering contracts exist only at the composition root: a consumer reacting
+  // to permissions:ready must be able to resolve the service immediately. The
+  // service is published and ready fires at session_start (not factory init).
+  it("publishes the service before emitting permissions:ready", async () => {
+    const cwd = mkdtempSync(join(tmpdir(), "pi-perm-ready-cwd-"));
+    const seen: string[] = [];
+    const pi = makeFakePi();
+    pi.events.on(PERMISSIONS_READY_CHANNEL, () => {
+      seen.push(getPermissionsService() ? "present" : "missing");
+    });
+
+    piPermissionSystemExtension(pi as unknown as ExtensionAPI);
+
+    // ready is not emitted at load; only after session_start publishes.
+    expect(seen).toEqual([]);
+
+    await fireSessionStart(pi, makeChildCtx(cwd, "top-session"));
+
+    expect(seen).toEqual(["present"]);
+
+    rmSync(cwd, { recursive: true, force: true });
+  });
+});
+
+describe("multi-instance global service interplay", () => {
+  // The fix (#302) scopes the process-global service slot to the publishing
+  // instance. The parent publishes at its session_start; an in-process child
+  // (registered by session id) skips publishing, and its identity-scoped
+  // teardown is a no-op — so the parent's service is the one that resolves
+  // throughout the child's lifecycle and survives the child's shutdown.
+  it("keeps the parent's service published across the child's lifecycle", async () => {
+    const parentCwd = mkdtempSync(join(tmpdir(), "pi-perm-parent-cwd-"));
+    const childCwd = mkdtempSync(join(tmpdir(), "pi-perm-child-cwd-"));
+    const childSessionId = "child-session-mi";
+
+    const parentPi = makeFakePi({ events: createEventBus() });
+    piPermissionSystemExtension(parentPi as unknown as ExtensionAPI);
+    const childPi = makeFakePi({ events: createEventBus() });
+    piPermissionSystemExtension(childPi as unknown as ExtensionAPI);
+
+    // The parent is not a registered child, so it publishes its service.
+    await fireSessionStart(
+      parentPi,
+      makeChildCtx(parentCwd, "parent-session-mi"),
+    );
+    const parentService = getPermissionsService();
+    expect(parentService).toBeDefined();
+
+    // The child is registered in the shared global registry before its own
+    // session_start, so it detects itself and skips publishing.
+    getSubagentSessionRegistry().register(childSessionId, {
+      parentSessionId: "parent-session-mi",
+    });
+    await fireSessionStart(childPi, makeChildCtx(childCwd, childSessionId));
+
+    // Mid-run: the slot resolves the parent's service, never the child's.
+    expect(getPermissionsService()).toBe(parentService);
+
+    // The child's shutdown is a no-op for the slot it never owned.
+    await childPi.fire("session_shutdown");
+    expect(getPermissionsService()).toBe(parentService);
+
+    rmSync(parentCwd, { recursive: true, force: true });
+    rmSync(childCwd, { recursive: true, force: true });
+  });
+});

package/test/handlers/lifecycle.test.ts

@@ -36,12 +36,18 @@ function makeHandler(
 ): {
   handler: SessionLifecycleHandler;
   session: PermissionSession;
+  activateService: ReturnType<typeof vi.fn>;
   cleanupRpc: ReturnType<typeof vi.fn>;
 } {
   const session = makeSession(overrides);
+  const activateService = vi.fn();
   const cleanupRpc = vi.fn();
-  const handler = new SessionLifecycleHandler(session, cleanupRpc);
-  return { handler, session, cleanupRpc };
+  const handler = new SessionLifecycleHandler(
+    session,
+    activateService,
+    cleanupRpc,
+  );
+  return { handler, session, activateService, cleanupRpc };
 }
 
 // ── handleSessionStart ─────────────────────────────────────────────────────
@@ -106,6 +112,13 @@ describe("handleSessionStart", () => {
     expect(session.logger.debug).not.toHaveBeenCalled();
   });
 
+  it("activates the service for the session with ctx", async () => {
+    const ctx = makeCtx();
+    const { handler, activateService } = makeHandler();
+    await handler.handleSessionStart({ reason: "startup" }, ctx);
+    expect(activateService).toHaveBeenCalledWith(ctx);
+  });
+
   it("calls refreshConfig before resetForNewSession", async () => {
     const callOrder: string[] = [];
     const { handler } = makeHandler({

package/test/helpers/make-fake-pi.ts

@@ -0,0 +1,95 @@
+/**
+ * `makeFakePi()` — a composition-root test harness.
+ *
+ * Lets a test run the real `piPermissionSystemExtension(pi)` factory and then
+ * introspect and drive the result. Unlike the per-handler unit fixtures in
+ * `handler-fixtures.ts` (which inject collaborators), this harness exercises the
+ * factory itself — the wiring layer where registration completeness, shared-
+ * instance contracts, teardown, and event ordering live.
+ *
+ * It provides:
+ * - `events` — a real `createEventBus()` so cross-extension pub/sub and RPC
+ *   behave as in production (tests can inject a shared bus to model parent/child
+ *   instances).
+ * - `handlers` — every `pi.on(event, handler)` registration, keyed by event
+ *   name, so a test can assert completeness and fire handlers.
+ * - `commands` — every `pi.registerCommand(name, …)` registration.
+ * - `fire(event, input, ctx)` — drive a registered handler; resolves to its
+ *   (possibly async) result.
+ *
+ * The harness object is cast to `ExtensionAPI` at the call to the factory; the
+ * `FakePi` interface itself stays narrow (ISP — only what the factory touches).
+ */
+import { createEventBus, type EventBus } from "@earendil-works/pi-coding-agent";
+import { vi } from "vitest";
+
+/** A handler recorded by `pi.on(...)`, kept generic over event/result shapes. */
+export type RecordedHandler = (event: unknown, ctx: unknown) => unknown;
+
+export interface FakePi {
+  /** Real event bus so cross-extension pub/sub and RPC behave as in production. */
+  events: EventBus;
+  /** Every `pi.on(event, handler)` registration, keyed by event name. */
+  handlers: Map<string, RecordedHandler>;
+  /** Every `pi.registerCommand(name, …)` registration, keyed by command name. */
+  commands: Map<string, unknown>;
+  /**
+   * Drive a registered handler; resolves to its (possibly async) result.
+   *
+   * Throws if no handler is registered for `event` so a typo in a test surfaces
+   * loudly instead of silently resolving to `undefined`.
+   */
+  fire(event: string, input?: unknown, ctx?: unknown): Promise<unknown>;
+  /** Minimal tool registry — returns the configured tool names. */
+  getAllTools(): { name: string }[];
+  setActiveTools(names: string[]): void;
+}
+
+export interface MakeFakePiOptions {
+  /** Inject a shared bus to model parent/child instances; defaults to a fresh bus. */
+  events?: EventBus;
+  /** Tool names returned by `getAllTools()`; defaults to a small set. */
+  toolNames?: readonly string[];
+}
+
+const DEFAULT_TOOL_NAMES = ["read", "write", "edit", "bash", "ls", "grep"];
+
+/**
+ * Build a fake `ExtensionAPI` for composition-root tests.
+ *
+ * The returned object is structurally a `FakePi`; pass it to the factory as
+ * `piPermissionSystemExtension(pi as unknown as ExtensionAPI)`.
+ */
+export function makeFakePi(options: MakeFakePiOptions = {}): FakePi {
+  const events = options.events ?? createEventBus();
+  const toolNames = options.toolNames ?? DEFAULT_TOOL_NAMES;
+  const handlers = new Map<string, RecordedHandler>();
+  const commands = new Map<string, unknown>();
+
+  return {
+    events,
+    handlers,
+    commands,
+    fire(event, input, ctx): Promise<unknown> {
+      const handler = handlers.get(event);
+      if (!handler) {
+        throw new Error(`No handler registered for event "${event}"`);
+      }
+      return Promise.resolve(handler(input, ctx));
+    },
+    getAllTools(): { name: string }[] {
+      return toolNames.map((name) => ({ name }));
+    },
+    setActiveTools: vi.fn(),
+    // ── ExtensionAPI methods the factory touches (recorded) ────────────────
+    on(event: string, handler: RecordedHandler): void {
+      handlers.set(event, handler);
+    },
+    registerCommand(name: string, optionsArg: unknown): void {
+      commands.set(name, optionsArg);
+    },
+    // ── ExtensionAPI methods present for the cast but unused by the factory ─
+    registerProvider: vi.fn(),
+    exec: vi.fn(),
+  } as FakePi & Record<string, unknown>;
+}

package/test/permission-events.test.ts

@@ -279,10 +279,18 @@ describe("piPermissionSystemExtension ready event wiring", () => {
     rmSync(baseDir, { recursive: true, force: true });
   });
 
-  it("emits permissions:ready with protocolVersion when extension loads", () => {
+  it("emits permissions:ready with protocolVersion at session_start", async () => {
     const emitSpy = vi.fn();
+    const handlers = new Map<
+      string,
+      (event: unknown, ctx: unknown) => unknown
+    >();
     piPermissionSystemExtension({
-      on: vi.fn(),
+      on: vi.fn(
+        (event: string, handler: (e: unknown, c: unknown) => unknown) => {
+          handlers.set(event, handler);
+        },
+      ),
       registerCommand: vi.fn(),
       getAllTools: vi.fn().mockReturnValue([]),
       setActiveTools: vi.fn(),
@@ -290,6 +298,28 @@ describe("piPermissionSystemExtension ready event wiring", () => {
       events: { emit: emitSpy, on: vi.fn().mockReturnValue(() => undefined) },
     } as never);
 
+    // ready is not emitted at load — only after session_start publishes.
+    expect(
+      emitSpy.mock.calls.filter(([c]) => c === PERMISSIONS_READY_CHANNEL),
+    ).toHaveLength(0);
+
+    const ctx = {
+      cwd: baseDir,
+      hasUI: false,
+      sessionManager: {
+        getEntries: (): unknown[] => [],
+        getSessionId: (): string => "top-session",
+        getSessionDir: (): string => baseDir,
+      },
+      ui: {
+        notify: (): void => {},
+        setStatus: (): void => {},
+        select: async (): Promise<string | undefined> => undefined,
+        input: async (): Promise<string | undefined> => undefined,
+      },
+    };
+    await handlers.get("session_start")?.({ reason: "start" }, ctx);
+
     const readyCalls = emitSpy.mock.calls.filter(
       ([channel]) => channel === PERMISSIONS_READY_CHANNEL,
     );

package/test/permission-system.test.ts

@@ -8,6 +8,7 @@ import {
 } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { dirname, join, resolve } from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { expect, test } from "vitest";
 import {
   createActiveToolsCacheKey,
@@ -46,23 +47,16 @@ import {
   canResolveAskPermissionRequest,
   shouldAutoApprovePermissionState,
 } from "#src/yolo-mode";
+import { type FakePi, makeFakePi } from "#test/helpers/make-fake-pi";
 import {
   type CreateManagerOptions,
   createManager,
 } from "#test/helpers/manager-harness";
 
-type MockHandler = (
-  event: Record<string, unknown>,
-  ctx: Record<string, unknown>,
-) =>
-  | Promise<Record<string, unknown> | undefined>
-  | Record<string, unknown>
-  | undefined;
-
 type ExtensionHarness = {
   baseDir: string;
   cwd: string;
-  handlers: Record<string, MockHandler>;
+  pi: FakePi;
   prompts: string[];
   cleanup: () => Promise<void>;
 };
@@ -112,7 +106,6 @@ function createToolCallHarness(
   const baseDir = mkdtempSync(join(tmpdir(), "pi-permission-system-runtime-"));
   const cwd = options.cwd ?? baseDir;
   const prompts: string[] = [];
-  const handlers: Record<string, MockHandler> = {};
   const originalAgentDir = process.env.PI_CODING_AGENT_DIR;
   const globalConfigPath = getGlobalConfigPath(baseDir);
   mkdirSync(join(baseDir, "agents"), { recursive: true });
@@ -124,22 +117,10 @@ function createToolCallHarness(
     "utf8",
   );
 
+  const pi = makeFakePi({ toolNames });
   process.env.PI_CODING_AGENT_DIR = baseDir;
   try {
-    piPermissionSystemExtension({
-      on: (name: string, handler: MockHandler): void => {
-        handlers[name] = handler;
-      },
-      registerCommand: (): void => {},
-      getAllTools: (): Array<{ name: string }> =>
-        toolNames.map((name) => ({ name })),
-      setActiveTools: (): void => {},
-      registerProvider: (): void => {},
-      events: {
-        emit: (): void => {},
-        on: (): (() => void) => () => undefined,
-      },
-    } as never);
+    piPermissionSystemExtension(pi as unknown as ExtensionAPI);
   } finally {
     if (originalAgentDir === undefined) {
       delete process.env.PI_CODING_AGENT_DIR;
@@ -151,11 +132,13 @@ function createToolCallHarness(
   return {
     baseDir,
     cwd,
-    handlers,
+    pi,
     prompts,
     cleanup: async (): Promise<void> => {
-      await Promise.resolve(
-        handlers.session_shutdown({}, createMockContext(cwd, prompts, options)),
+      await pi.fire(
+        "session_shutdown",
+        {},
+        createMockContext(cwd, prompts, options),
       );
       rmSync(baseDir, { recursive: true, force: true });
     },
@@ -192,15 +175,14 @@ async function runToolCall(
   event: Record<string, unknown>,
   options: ExtensionHarnessOptions = {},
 ): Promise<Record<string, unknown>> {
-  const handler = harness.handlers.tool_call;
-  expect(handler).toBeTypeOf("function");
-
   const result = await withIsolatedSubagentEnv(async () =>
-    Promise.resolve(
-      handler(event, createMockContext(harness.cwd, harness.prompts, options)),
+    harness.pi.fire(
+      "tool_call",
+      event,
+      createMockContext(harness.cwd, harness.prompts, options),
     ),
   );
-  return result ?? {};
+  return (result as Record<string, unknown> | undefined) ?? {};
 }
 
 test("Yolo mode only auto-approves ask-state permissions", () => {
@@ -2335,7 +2317,7 @@ test("session approval: session_shutdown clears session approvals", async () =>
       hasUI: true,
       selectResponse: "Yes",
     });
-    await Promise.resolve(harness.handlers.session_shutdown({}, shutdownCtx));
+    await harness.pi.fire("session_shutdown", {}, shutdownCtx);
 
     // Access same path again — should prompt because cache was cleared
     const result = await runToolCall(

package/test/service.test.ts

@@ -26,7 +26,10 @@ function makeService(
 
 describe("globalThis accessor", () => {
   afterEach(() => {
-    unpublishPermissionsService();
+    const current = getPermissionsService();
+    if (current) {
+      unpublishPermissionsService(current);
+    }
   });
 
   it("returns undefined when nothing has been published", () => {
@@ -47,15 +50,25 @@ describe("globalThis accessor", () => {
     expect(getPermissionsService()).toBe(second);
   });
 
-  it("returns undefined after unpublish", () => {
+  it("removes the slot when it still holds the given service", () => {
     const service = makeService();
     publishPermissionsService(service);
-    unpublishPermissionsService();
+    unpublishPermissionsService(service);
     expect(getPermissionsService()).toBeUndefined();
   });
 
+  it("does not remove the slot when a different service occupies it", () => {
+    const parent = makeService();
+    const child = makeService();
+    publishPermissionsService(parent);
+    // A child instance never published `parent`; unpublishing its own service
+    // must be a no-op that leaves the parent's slot intact.
+    unpublishPermissionsService(child);
+    expect(getPermissionsService()).toBe(parent);
+  });
+
   it("unpublish is safe to call when nothing was published", () => {
-    expect(() => unpublishPermissionsService()).not.toThrow();
+    expect(() => unpublishPermissionsService(makeService())).not.toThrow();
     expect(getPermissionsService()).toBeUndefined();
   });
 });
@@ -64,7 +77,10 @@ describe("globalThis accessor", () => {
 
 describe("service adapter delegation", () => {
   afterEach(() => {
-    unpublishPermissionsService();
+    const current = getPermissionsService();
+    if (current) {
+      unpublishPermissionsService(current);
+    }
   });
 
   const fakeResult: PermissionCheckResult = {
@@ -191,7 +207,10 @@ describe("service adapter delegation", () => {
 
 describe("registerToolInputFormatter delegation", () => {
   afterEach(() => {
-    unpublishPermissionsService();
+    const current = getPermissionsService();
+    if (current) {
+      unpublishPermissionsService(current);
+    }
   });
 
   it("delegates to the registry and returns its disposer", () => {

package/test/subagent-context.test.ts

@@ -2,6 +2,7 @@ import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { afterEach, describe, expect, test, vi } from "vitest";
 import { SUBAGENT_ENV_HINT_KEYS } from "#src/permission-forwarding";
 import {
+  isRegisteredSubagentChild,
   isSubagentExecutionContext,
   normalizeFilesystemPath,
 } from "#src/subagent-context";
@@ -24,6 +25,45 @@ function makeCtx(
   } as unknown as ExtensionContext;
 }
 
+describe("isRegisteredSubagentChild", () => {
+  const childSessionId = "child-session-abc";
+
+  test("returns true when the session id is registered", () => {
+    const registry = new SubagentSessionRegistry();
+    registry.register(childSessionId, {});
+    expect(
+      isRegisteredSubagentChild(makeCtx(null, childSessionId), registry),
+    ).toBe(true);
+  });
+
+  test("returns false when the session id is not registered", () => {
+    const registry = new SubagentSessionRegistry();
+    expect(
+      isRegisteredSubagentChild(makeCtx(null, childSessionId), registry),
+    ).toBe(false);
+  });
+
+  test("returns false when the session id is empty", () => {
+    const registry = new SubagentSessionRegistry();
+    registry.register("", {});
+    expect(isRegisteredSubagentChild(makeCtx(null, ""), registry)).toBe(false);
+  });
+
+  test("returns false when getSessionId throws", () => {
+    const registry = new SubagentSessionRegistry();
+    registry.register(childSessionId, {});
+    const ctx = {
+      sessionManager: {
+        getSessionDir: vi.fn(() => null),
+        getSessionId: vi.fn(() => {
+          throw new Error("session id unavailable");
+        }),
+      },
+    } as unknown as ExtensionContext;
+    expect(isRegisteredSubagentChild(ctx, registry)).toBe(false);
+  });
+});
+
 describe("normalizeFilesystemPath", () => {
   test("normalizes a simple absolute path", () => {
     expect(normalizeFilesystemPath("/projects/my-app")).toBe(