@gotgenes/pi-permission-system 8.3.1 → 9.0.0

package/CHANGELOG.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-permission-system",
-  "version": "8.3.1",
+  "version": "9.0.0",
   "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/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/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/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,19 +28,47 @@ 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,
   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)) {
+  // 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 && isRegisteredSubagentChild(ctx, registry)) {
     return true;
   }
 
+  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,15 +7,22 @@
  * 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. */
@@ -53,19 +60,20 @@ export function getSubagentSessionRegistry(): SubagentSessionRegistry {
 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>();
@@ -73,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);
   }
 }