@gotgenes/pi-permission-system 7.3.3 → 7.4.0

package/CHANGELOG.md

@@ -5,6 +5,18 @@ 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)
 
 

package/package.json

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

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/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");
+  });
+});