my-pi/pi-permission-system/docs/plans/0296-process-global-subagent-registry.md

issue, issue_title

issue	issue_title
296	Permission forwarding broken for in-process @gotgenes/pi-subagents children — `ask` silently blocked (regression: pi-subagents v11.4.0 / pi-permission-system v8.0.0)

Back SubagentSessionRegistry with a process-global instance

Problem Statement

Permission forwarding no longer works for in-process @gotgenes/pi-subagents children. When a subagent triggers an ask decision (for example an external-directory ls), the request is blocked deterministically instead of being forwarded to the parent session's UI, and no forwarded_permission.* entry is written — the child never enters the forwarding path.

The root cause is a per-session event-bus split. Each session's ResourceLoader creates its own EventBus, and @gotgenes/pi-subagents builds the child session's loader without passing the parent's bus. The child lifecycle is published on the parent's bus (createChildLifecyclePublisher((c, d) => pi.events.emit(c, d))), so the parent's permission-system instance registers the child in its SubagentSessionRegistry and can poll/surface requests. But the child's permission-system instance is a separate jiti module instance with its own empty new SubagentSessionRegistry(), subscribed to the child's separate bus, so it never receives the registration. In the child, isSubagentExecutionContext() then misses the registry, finds no env hints (@gotgenes/pi-subagents sets none), and fails the filesystem heuristic (child sessions live at <parent-session-dir>/<basename>/tasks, not ~/.pi/agent/subagent-sessions). canResolveAskPermissionRequest = hasUI || isSubagent || yolo is then false on all three counts, so the ask is blocked.

This is a regression. The retired permission-bridge.ts (pi-subagents #101) registered through globalThis[Symbol.for("@gotgenes/pi-permission-system:service")] — a process-global channel that survives jiti/session isolation. The #261 event-based inversion replaced that with a per-session bus, and #267 then removed the globalThis fallback entirely.

Goals

• Restore forwarding for in-process @gotgenes/pi-subagents children: a child's ask decision reaches the parent's UI as a Permission Required (Subagent) prompt.
• Make the single SubagentSessionRegistry instance process-global so the parent's instance writes and the child's instance reads the same store, regardless of which per-session event bus each instance is wired to.
• Reuse the package's established Symbol.for() convention (the same mechanism src/service.ts uses for PermissionsService).
• Keep the existing event-driven registration (ADR-0002) intact — only the registry's storage location changes; the publish/subscribe flow and the synchronous session-created ordering guarantee are unchanged.

Non-Goals

• No changes to @gotgenes/pi-subagents. The publisher already emits subagents:child:session-created / subagents:child:disposed on the parent bus correctly, and the parent-side subscription is correct. This is a single-package fix even though the issue carries both pkg:* labels.
• Not fixing the sibling-key collision for concurrent children of the same parent (all share the <parent>/<basename>/tasks getSessionDir() key). This pre-dates the regression and is independent of the event-bus split — see Open Questions.
• Not broadening env-hint or filesystem detection for CLI/process-based subagent extensions (that is the separate, still-open #22).
• No change to the PermissionsService public surface or the prompt-forwarding RPC.

Background

Relevant modules in packages/pi-permission-system/src/:

• subagent-registry.ts — the SubagentSessionRegistry class (a Map<string, SubagentSessionInfo> keyed by child session directory). Today it is instantiated once with new SubagentSessionRegistry() in index.ts.
• index.ts — the composition root. Line 41 constructs the registry and threads the instance into PermissionPrompter, forwardingDeps, ForwardingManager, the two isSubagentExecutionContext(...) closures, and subscribeSubagentLifecycle(pi.events, subagentRegistry).
• subagent-context.ts — isSubagentExecutionContext(ctx, subagentSessionsDir, registry) checks registry.has(sessionDir) first.
• permission-forwarding.ts — resolvePermissionForwardingTargetSessionId(...) reads registry.get(sessionDir)?.parentSessionId to find the forwarding target.
• subagent-lifecycle-events.ts — subscribeSubagentLifecycle(events, registry) registers on session-created and unregisters on disposed.
• service.ts — the existing Symbol.for("@gotgenes/pi-permission-system:service") pattern to mirror: a process-global slot accessor that survives jiti's moduleCache: false isolation.

Constraint from AGENTS.md / the package-pi-permission-system skill: under jiti, module-scoped state is isolated per extension instance; globalThis + Symbol.for() is the prescribed mechanism for process-global state. The session-created handler must stay synchronous (the core emits it on the same call stack right before bindExtensions()); this fix does not touch that handler.

The registration key matches the runtime lookup key: the event payload's sessionDir is the output of deriveSubagentSessionDir, and the SDK's SessionManager.getSessionDir() returns exactly the directory passed to SessionManager.create(cwd, dir) (verified — newSession() does not mutate sessionDir). So once the parent's registration lands in a shared store, the child's lookup hits it.

Design Overview

Introduce a lazily-initialized, process-global accessor for the registry and have the composition root use it instead of new.

New accessor in subagent-registry.ts (the class is unchanged):

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.
 */
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;
}

Consumer call site in index.ts (one line):

const subagentRegistry = getSubagentSessionRegistry();

All downstream wiring (prompter, forwardingDeps, ForwardingManager, subscribeSubagentLifecycle, the isSubagentExecutionContext closures) is unchanged — it already receives the instance by reference and the type is identical.

Lifecycle and ordering, after the change:

1. The parent's permission-system runs getSubagentSessionRegistry() at process startup — first call creates the global registry — and subscribes to the parent bus.
2. A child spawns; the core emits session-created on the parent bus before bindExtensions(); the parent's synchronous subscriber calls registry.register(childSessionDir, { agentName, parentSessionId }) on the global registry.
3. bindExtensions() instantiates the child's permission-system; its getSubagentSessionRegistry() returns the same global instance (already populated).
4. On the child's first tool_call, isSubagentExecutionContext() hits registry.has(childSessionDir) → true; the ask resolves via waitForForwardedPermissionApproval, which reads parentSessionId from the same registry and writes a request the parent already polls for.
5. On child completion, the core emits disposed on the parent bus; the parent's subscriber calls registry.unregister(childSessionDir).

Why this is the right shape:

• Tell-Don't-Ask / Law of Demeter: callers ask once for the shared registry, then tell it to register / unregister / has / get. No reach-through, no new collaborator surface.
• SRP: the accessor owns the "where the single instance lives" concern; the class keeps owning the data.
• It deliberately does not add a shutdown/unpublish hook for the registry. A child's session_shutdown must not be able to wipe the parent's registrations. Entries are created and removed only by the parent's session-created / disposed subscription, so no teardown hook is needed and child shutdown leaves the store intact.

Why not share the event bus instead?

The deeper cause of the regression is that a cross-session signal (subagents:child:session-created) was routed over a per-session transport. Each session's ResourceLoader mints its own pi.events bus (resource-loader.ts: this.eventBus = options.eventBus ?? createEventBus()), and the child's loader is built without the parent's bus, so the child subscribes to a different bus than the one the parent publishes on.

Crucially, lifecycle events do not travel on pi.events. pi.on(...) registers into a per-extension handler map, and the per-session ExtensionRunner dispatches lifecycle by iterating those maps — it never routes tool_call / turn_end / etc. through the bus. Session isolation (the parent not seeing the child's tool calls) is therefore guaranteed by the per-session ExtensionRunner, not by the bus being per-session. The per-session scope of pi.events is incidental to lifecycle correctness.

A per-session pi.events is still the right default: intra-session cross-extension coordination must stay scoped, and this package itself depends on it (registerPermissionRpcHandlers(pi.events, ...), emitReadyEvent(pi.events)). The mismatch is using that bus as a cross-session channel, not the bus being per-session.

Rejected alternatives:

• Pass the parent's bus into the child's loader (share one pi.events). Highest blast radius: it would cross every extension's intra-session channels between parent and child (this package's RPC and ready events, plus any other extension's pub/sub), breaking the isolation other extensions rely on.
• Introduce a process-global event bus for cross-session signals. More general, but no such bus exists today; inventing one is broader scope and largely re-creates what globalThis + Symbol.for() already provides.

The chosen approach keeps per-session buses and moves only the cross-session state to a process-global store. The child never needs to receive the event — it only needs to answer "am I a subagent, and who is my parent?", which is a state lookup, not an event. The parent writes the global registry; the child reads it. The lifecycle events remain useful for the parent-side registration and telemetry, and the child simply stops depending on receiving them.

Edge cases:

• /reload: the parent re-runs getSubagentSessionRegistry() and reuses the existing global registry. This differs from the previous (broken) per-instance registry, which started empty after every reload; reuse is correct because entries are keyed per child and cleaned on disposed, and a reload with no in-flight children leaves an empty store.
• Concurrency: distinct children with distinct session directories register under distinct keys safely. Concurrent siblings of one parent share a key (see Open Questions) — pre-existing, unchanged by this fix.

Module-Level Changes

• packages/pi-permission-system/src/subagent-registry.ts — add the SUBAGENT_SESSION_REGISTRY_KEY symbol (module-private) and the exported getSubagentSessionRegistry() accessor. The SubagentSessionRegistry class and SubagentSessionInfo interface are unchanged.
• packages/pi-permission-system/src/index.ts — change the import from { SubagentSessionRegistry } to { getSubagentSessionRegistry } and replace const subagentRegistry = new SubagentSessionRegistry(); with const subagentRegistry = getSubagentSessionRegistry();. No other lines change (SubagentSessionRegistry is referenced only at the import and that one construction site).
• packages/pi-permission-system/test/subagent-registry.test.ts — add a describe("getSubagentSessionRegistry (process-global accessor)") block (mirrors the globalThis accessor block in test/service.test.ts), with an afterEach that clears the global slot.
• packages/pi-permission-system/docs/subagent-integration.md — the "Deterministic child detection" bullet currently implies in-process detection works via the registry; add that the registry is process-global (globalThis + Symbol.for()) because parent and child run on separate per-session event buses, which is what makes the child's lookup see the parent's registration.
• packages/pi-permission-system/docs/architecture/architecture.md — in the detection-model section (around the SubagentSessionRegistry references near lines 417 and 438) add a sentence noting the registry is a process-global singleton shared across per-session buses, and add getSubagentSessionRegistry to the subagent-registry.ts description in the module listing (around line 538).
• .pi/skills/package-pi-permission-system/SKILL.md — extend the "Event-based subagent integration" section: the registry must be process-global because the publisher emits on the parent's bus while the child's instance listens on a separate bus; record this as the durable lesson behind this regression.

No changes to service.ts, subagent-context.ts, permission-forwarding.ts, forwarding-manager.ts, or subagent-lifecycle-events.ts — they already operate on the injected registry instance.

Test Impact Analysis

1. New tests enabled: the process-global accessor is new behavior that could not be tested before (the registry was only ever new'd directly). New cases: returns a SubagentSessionRegistry; returns the same instance on repeated calls; an entry registered through one returned reference is visible through another (the parent-writes/child-reads property); state is observable across calls within the process.
2. Redundant tests: none. The existing subagent-registry.test.ts cases construct new SubagentSessionRegistry() and exercise register/unregister/has/get mechanics — those remain valid and are not duplicated by the accessor tests.
3. Tests that must stay as-is: subagent-context.test.ts, permission-forwarding.test.ts, and subagent-lifecycle-events.test.ts inject a registry instance directly and exercise detection, target resolution, and the subscribe/register/unregister wiring. They genuinely cover that layer and are unaffected by where the production instance is stored.

TDD Order

1. fix: — add the process-global accessor. Test surface: test/subagent-registry.test.ts, new describe("getSubagentSessionRegistry (process-global accessor)") block with afterEach clearing the global slot via Symbol.for("@gotgenes/pi-permission-system:subagent-registry"). Red: import getSubagentSessionRegistry (does not exist yet) and assert same-instance-on-repeat plus cross-reference state sharing. Green: implement getSubagentSessionRegistry() and the module-private symbol in src/subagent-registry.ts. Commit: fix: add process-global SubagentSessionRegistry accessor (#296).
2. fix: — wire the composition root to the shared registry. Change src/index.ts to import and call getSubagentSessionRegistry() instead of new SubagentSessionRegistry(). This is the regression fix; the accessor from step 1 gains its production consumer here (so no dead-export window remains at review time). Run pnpm run check immediately (composition-root/wiring change) and the full package suite. Commit: fix: share SubagentSessionRegistry across parent and child sessions (#296).
3. docs: — update docs/subagent-integration.md, docs/architecture/architecture.md, and .pi/skills/package-pi-permission-system/SKILL.md to document the process-global registry and the per-session-bus rationale. Commit: docs: explain process-global subagent registry across session buses (#296).

Risks and Mitigations

• Global state leaking across unit tests. Mitigation: the accessor test clears the Symbol.for(...) slot in afterEach, mirroring test/service.test.ts. No other test uses the accessor (all others construct the class directly), so cross-file pollution is not possible.
• A child's shutdown wiping the parent's registrations. Mitigation by design: no shutdown/unpublish hook is added for the registry; entries are mutated only by the parent's session-created / disposed subscription.
• Stale entries across /reload. Mitigation: entries are keyed per child and removed on disposed; a reload with no in-flight children leaves an empty store, and the parent reuses the same registry deliberately.
• Release semantics. Both code commits use fix: so release-please cuts a patch — appropriate for restoring previously-working behavior; the accessor is internal (not part of the published PermissionsService surface), so it is not a feat.

Open Questions

• Concurrent sibling children of the same parent share the <parent-session-dir>/<basename>/tasks getSessionDir() key, so they collide on one registry entry; when one sibling is disposed, unregister removes the shared entry and detection breaks for still-running siblings. This pre-dates the regression (the old bridge keyed on the same path) and is independent of the event-bus split, so it is out of scope here. It is latent today (forwarding is broken end-to-end) but becomes live the moment this fix lands, and is tracked in #298 (leaning toward keying the registry by the child's session id).
• This regression is an instance of a broader gap: the composition root (index.ts) has no test coverage, so wiring faults (a collaborator instantiated instead of shared, a dropped handler, a leaked teardown) slip past the unit suite. The practical coverage for this fix is the accessor unit test (TDD step 1) plus the existing injected-registry tests; a makeFakePi() composition-root harness and the backfill tests that would have caught this class of fault are tracked separately in #297 and intentionally out of scope here.