@gotgenes/pi-permission-system 26.3.0 → 27.0.0

package/docs/migration/0794-keyed-service-locator.md

@@ -0,0 +1,91 @@
+# Migration guide: the keyed service locator and the ready cadence
+
+Starting with the release that closes #794, two things change for an extension that talks to pi-permission-system:
+
+1. `getPermissionsService()` requires the session id of the node whose service you want.
+2. `permissions:ready` fires at least once per session and may repeat, so a registration handler must be idempotent.
+
+Both are **breaking changes**.
+If your extension neither imports `@gotgenes/pi-permission-system` nor listens on `permissions:ready`, nothing here affects you.
+
+## Why the accessor changed
+
+One Pi process can host several **nodes** — a root session and each of its in-process subagent children are separate session runtimes, each with its own gates, registries, and authorizer chain.
+A registration is read by the node it was made in, so "the permission service" was never a single thing to ask for.
+The old zero-arg accessor answered with the **process root's** service, which is the wrong node in every node but the root: inside a subagent child it handed back the parent's service, so a chain link landed where the child's gates never read it, and a policy query answered against the parent's config.
+
+That is the defect behind the duplicate-registration errors reported in #699, and the contract that replaces it is [ADR 0012](https://github.com/gotgenes/pi-packages/blob/main/packages/pi-permission-system/docs/decisions/0012-cross-node-extension-contract.md).
+Each node now publishes its own service under its own session id, and you resolve the one you mean.
+
+## What to change
+
+| Before                                 | After                                                              |
+| -------------------------------------- | ------------------------------------------------------------------ |
+| `getPermissionsService()`              | `getPermissionsService(sessionId)`                                 |
+| — (no equivalent)                      | `getRootPermissionsService()` — the old behavior, still deprecated |
+| `publishPermissionsService(service)`   | `publishRootPermissionsService(service)`                           |
+| `unpublishPermissionsService(service)` | `unpublishRootPermissionsService(service)`                         |
+
+The session id arrives as a field on the `permissions:ready` payload.
+Inside your own session handler, `ctx.sessionManager.getSessionId()` is the same value.
+
+```typescript
+let dispose: (() => void) | undefined;
+
+pi.events.on(PERMISSIONS_READY_CHANNEL, (event) => {
+  const { sessionId } = event as PermissionsReadyEvent;
+  // Idempotent: ready may repeat, so a second emission must be a no-op.
+  if (dispose || !sessionId) return;
+  void (async () => {
+    const { getPermissionsService } = await import(
+      "@gotgenes/pi-permission-system"
+    );
+    dispose = getPermissionsService(sessionId)?.registerAuthorizer(
+      "my-link",
+      authorize,
+    );
+  })();
+});
+
+pi.on("session_shutdown", () => {
+  dispose?.();
+  dispose = undefined;
+});
+```
+
+That handler is the whole registration.
+A second attempt from your own `session_start` — the dual-path workaround that load-order ambiguity used to require — is no longer needed and should be deleted.
+
+## The session id is required, not optional
+
+`getPermissionsService` takes `sessionId` as a required argument rather than an optional one, and there is no zero-arg overload.
+`PermissionsReadyEvent.sessionId` is `string | null`, and any shape where a `null` could reach the locator and fall through to the process root's slot would restore exactly the wrong-node bug the contract removes.
+
+A TypeScript consumer gets a compile error.
+A JavaScript consumer, or one compiled against an earlier major, still reaches the function with no argument: that call returns `undefined` — never another node's service — and emits a once-guarded Node warning:
+
+```text
+(node:12345) [PI_PERMISSION_SYSTEM_WARN0001] Warning: getPermissionsService() was called without a session id and answered undefined. …
+```
+
+Watch for it after upgrading.
+A consumer that guards with `if (!service) return;` treats the `undefined` as "the permission system is not loaded" and silently registers nothing, so the warning is the only evidence that a link stopped being consulted.
+It is deliberately not a `DeprecationWarning`, so `--no-deprecation` does not silence it.
+
+## The ready cadence
+
+`permissions:ready` used to be described as firing once, at each node's `session_start`.
+It now fires **at least once per session, and may repeat**: each node emits it at `session_start` after publishing, and again at its first `before_agent_start` — which runs after every extension's `session_start` and before any tool call, hence before any ask.
+
+The second emission is what makes the ready handler a sufficient registration site regardless of extension load order.
+The cost is that a handler which registers unconditionally now hits `registerAuthorizer`'s duplicate-name throw on every session rather than only on a user-initiated `/reload`.
+Guard it with a stored dispose handle, as shown above, and release the handle on `session_shutdown`.
+
+`registerToolInputFormatter` and `registerToolAccessExtractor` throw on a duplicate name for the same reason and want the same guard.
+
+## What has not changed
+
+- The `PermissionsService` interface — the five methods and their signatures are untouched.
+- The `permissions:ready`, `permissions:ui_prompt`, and `permissions:decision` payload shapes.
+- The process-root slot itself: a node that is not an in-process subagent child still publishes to it, so `getRootPermissionsService()` answers exactly as the old zero-arg accessor did.
+  It remains deprecated (`PI_PERMISSION_SYSTEM_DEP0001`), and its removal is deferred to a later major.

package/docs/subagent-integration.md

@@ -1,26 +1,94 @@
 # Subagent Integration
 
-## Native integration with `@gotgenes/pi-subagents`
+## The subagent adapter convention
 
-[`@gotgenes/pi-subagents`](https://github.com/gotgenes/pi-subagents) is the only subagent extension with native permission-system integration.
-It publishes a child-execution lifecycle on `pi.events`; this package subscribes (see `src/authority/subagent-lifecycle-events.ts`) and registers every in-process child session with the `SubagentSessionRegistry` on the `subagents:child:session-created` event — emitted before `bindExtensions()` fires — and unregisters it on `subagents:child:disposed`.
-Because the event bus dispatches synchronously, the synchronous registration completes before binding proceeds.
-This inverts the former dependency direction: the core no longer looks up this package's service ([ADR-0002] / pi-subagents [#261]).
+This is the one supported API between a subagent implementation and this package, and this section is its canonical specification ([ADR 0012] decision 5).
+
+An implementation's entire obligation is the **announcement**.
+Everything that follows from it is this package's job, on both ends.
+
+### In-process implementations
+
+An implementation that creates child sessions inside its own process (via `createAgentSession()`) emits two one-way broadcasts on `pi.events`:
+
+| Channel                           | Payload                           | When                                                                      |
+| --------------------------------- | --------------------------------- | ------------------------------------------------------------------------- |
+| `subagents:child:session-created` | `{ sessionId, parentSessionId? }` | After the child session is created, immediately before `bindExtensions()` |
+| `subagents:child:disposed`        | `{ sessionId }`                   | In the run's `finally`, on success and on error alike                     |
+
+The pre-bind ordering of `session-created` is **contract, not an implementation detail**.
+Emit it synchronously, on the same call stack, before `bindExtensions()`: this package's subscriber registers the child synchronously, and the registration must land before binding proceeds so the child's own instance can detect itself the moment it loads.
+An implementation that awaits between creating the session and emitting, or that emits after binding, breaks detection for every child it spawns.
+
+Both are fire-and-forget broadcasts.
+Nothing is returned, nothing is awaited, and no reply travels back over the bus.
+
+### Out-of-process implementations
+
+An implementation that spawns a child as its own `pi` process sets one environment variable at spawn:
+
+```bash
+PI_SUBAGENT_PARENT_SESSION=<parent-session-id>
+```
+
+That is the whole obligation.
+The variable identifies the session the child forwards its asks to, and naming a parent session is itself sufficient to mark the process as a child — a separate "I am a subagent" marker is neither required nor expected.
+
+Earlier per-extension variables are grandfathered for compatibility: the markers `PI_IS_SUBAGENT`, `PI_SUBAGENT_CHILD`, `PI_SUBAGENT_NAME` and their siblings still register as child hints, and `PI_AGENT_ROUTER_PARENT_SESSION_ID` is still honored as a parent-session source, checked ahead of the convention name.
+New implementations use `PI_SUBAGENT_PARENT_SESSION` only.
+
+### What an implementation does not owe
+
+None of the following is an implementation's responsibility, on either process shape:
+
+- Detecting that a session is a child.
+- Selecting the authority that answers an ask, or deciding whether a node adjudicates locally or relays.
+- Forwarding an ask, fixing its facts, or transporting the answer back.
+- Publishing or reading the serving heartbeat, or fast-failing a request whose target is not draining its inbox.
+- Resolving per-agent `permission:` frontmatter, or choosing a session-approval grant scope.
+
+An implementation never imports this package, never resolves its service, and never manages permissions.
+The dependency arrow points one way: this package subscribes to the announcement, and the implementation does not know this package exists ([ADR-0002]).
+
+## Loading asymmetry
+
+Subagent implementations may load arbitrary extension sets into children — `@gotgenes/pi-subagents` offers `excludedExtensionPackages`, and others differ — so this package assumes no symmetry between a parent's extensions and its children's ([ADR 0012] decision 6).
+
+Three statements hold:
+
+1. **A permission extension riding into a child is harmless by construction.**
+   Access extractors and preview formatters land in the child's own registries, where the child's own gates read them, which is where they are needed.
+   A chain link registered on a relaying node is accepted, returns a working disposer, and is recorded as `authorizer_link_vacant` rather than refused.
+   Nothing throws and nothing warns per child start.
+2. **Excluding an extension from children is an optimization, never a correctness requirement.**
+   Excluding a link-only extension saves load time; the adjudicating node's own instance still judges every descendant ask.
+3. **Excluding a provider of access extractors can weaken a child's own gates.**
+   This is the one real hazard, and it is narrower than it sounds: excluding a package also keeps that package's tools out of children, so a package that supplies both a tool and that tool's extractor takes both away and leaves no gap.
+   A gap needs the tool and its extractor to come from *different* packages, with only the extractor's package excluded.
+
+The full condition, with a worked example, is documented where the setting lives: [Excluding package extensions from children](https://github.com/gotgenes/pi-packages/blob/main/packages/pi-subagents/docs/configuration.md#excluding-package-extensions-from-children).
+
+## What this package does on both ends
+
+The announcement is all an implementation provides; this section is what it buys.
+
+On the announcing side, this package subscribes to the child lifecycle (`src/authority/subagent-lifecycle-events.ts`) and registers every in-process child session in the `SubagentSessionRegistry` on `subagents:child:session-created`, unregistering it on `subagents:child:disposed`.
+Because the event bus dispatches synchronously, that registration completes before `bindExtensions()` proceeds.
 
 The `SubagentSessionRegistry` is backed by a process-global singleton (`globalThis` + `Symbol.for()`), accessed via `getSubagentSessionRegistry()` in `src/authority/subagent-registry.ts`.
 This is necessary because each session's `ResourceLoader` creates its own `pi.events` bus: the parent emits `subagents:child:session-created` on the parent's bus, and only the parent's permission-system instance receives it.
 The child's jiti instance runs on a separate bus and never receives the event — but because both instances call `getSubagentSessionRegistry()`, they share the same store, so the parent's registration is visible to the child.
 
-The integration enables:
+What the announcement enables:
 
-1. **Deterministic child detection** — `isSubagentExecutionContext()` hits the process-global registry on the first check, no env-var or filesystem heuristics needed.
+1. **Deterministic child detection** — `isSubagentExecutionContext()` hits the process-global registry on the first check for an in-process child, and reads the environment for one spawned as its own process, with a session-directory heuristic behind both.
 2. **Per-agent policy enforcement** - the permission system's `before_agent_start` handler resolves the agent name from the `<active_agent>` system-prompt tag and applies per-agent `permission:` frontmatter overrides.
 3. **`ask`-state forwarding** - when a child triggers an `ask` permission, the request forwards to the parent session's UI through the existing polling mechanism.
    The parent approves or denies, and the child resumes.
    When the parent approves "for this session," it chooses a scope: **this subagent only** (the least-privilege default) records the grant on the requesting child, while **the whole session** records it on the serving parent so the parent and all its subagents resolve it without re-prompting.
 
 No configuration is required - the integration is automatic when both extensions are installed.
-When `@gotgenes/pi-permission-system` is not installed, `@gotgenes/pi-subagents` emits its lifecycle events with no subscriber - a harmless no-op.
+When `@gotgenes/pi-permission-system` is not installed, an implementation emits its lifecycle events with no subscriber - a harmless no-op.
 
 ## Permission Forwarding
 
@@ -92,6 +160,27 @@ Nothing needs to be edited, and in-process children are unaffected: parent and c
 
 ---
 
+## Conformance of known implementations
+
+Conformance is a property of the announcement alone — whether an implementation emits the in-process events, or sets the out-of-process variable — not of the frontmatter vocabulary it offers for tool visibility.
+
+| Extension                                                                           | Shape      | Adopts the convention             | Visibility key                     |
+| ----------------------------------------------------------------------------------- | ---------- | --------------------------------- | ---------------------------------- |
+| [@gotgenes/pi-subagents](https://github.com/gotgenes/pi-subagents)                  | in-process | ✓ Emits both lifecycle events     | `tools:` (allowlist)               |
+| [tintinweb/pi-subagents](https://github.com/tintinweb/pi-subagents)                 | in-process | ✗ Publishes no lifecycle event    | `disallowed_tools:` (CSV denylist) |
+| [nicobailon/pi-subagents](https://github.com/nicobailon/pi-subagents)               | subprocess | ✗ Sets no parent-session variable | `tools:` (CSV allowlist)           |
+| [HazAT/pi-interactive-subagents](https://github.com/HazAT/pi-interactive-subagents) | subprocess | ✗ Sets no parent-session variable | `deny-tools:` (CSV denylist)       |
+
+The two subprocess implementations set their own child-marker variables, so their children are detected, but neither names the parent session.
+Without it there is nowhere to forward to, and an `ask` in one of those children is reported as approval being unavailable.
+Adopting the convention is a one-line change at their spawn site.
+
+The upstream `tintinweb/pi-subagents` (which `@gotgenes/pi-subagents` forks) publishes no `subagents:child:session-created` event, so its in-process children have neither deterministic detection nor `ask`-state forwarding.
+
+See [guides/permission-frontmatter-for-subagent-extensions.md](guides/permission-frontmatter-for-subagent-extensions.md) for the companion convention on `permission:` frontmatter, which implementations document rather than implement.
+
+---
+
 ## Coexistence with Other Subagent Extensions
 
 Subagent extensions implement their own tool restriction mechanisms.
@@ -111,21 +200,6 @@ These compose correctly with the permission system because the two operate at di
 └─────────────────────────────────────────────────────┘
 ```
 
-### Known Subagent Extensions
-
-| Extension                                                                           | Type       | Permission integration           | Frontmatter key                    |
-| ----------------------------------------------------------------------------------- | ---------- | -------------------------------- | ---------------------------------- |
-| [@gotgenes/pi-subagents](https://github.com/gotgenes/pi-subagents)                  | in-process | ✓ Native (registry + forwarding) | `disallowed_tools:` (CSV denylist) |
-| [tintinweb/pi-subagents](https://github.com/tintinweb/pi-subagents)                 | in-process | ✗ No registration                | `disallowed_tools:` (CSV denylist) |
-| [nicobailon/pi-subagents](https://github.com/nicobailon/pi-subagents)               | subprocess | ✗ Missing env vars               | `tools:` (CSV allowlist)           |
-| [HazAT/pi-interactive-subagents](https://github.com/HazAT/pi-interactive-subagents) | subprocess | ✗ Missing env vars               | `deny-tools:` (CSV denylist)       |
-
-Process-based subagent extensions (nicobailon, HazAT) spawn child processes but do not set the `PI_SUBAGENT_PARENT_SESSION` env var that the permission system needs for `ask`-state forwarding.
-Without that env var, `ask` permissions in child processes are auto-denied.
-See [guides/permission-frontmatter-for-subagent-extensions.md](guides/permission-frontmatter-for-subagent-extensions.md) for the convention that subagent extension authors should follow.
-
-The upstream `tintinweb/pi-subagents` (which `@gotgenes/pi-subagents` forks) does not publish the `subagents:child:session-created` lifecycle event, so it lacks deterministic child detection and `ask`-state forwarding.
-
 ### Interaction Rules
 
 1. **Hidden tool → permission system never sees it.**
@@ -158,4 +232,5 @@ permission:
 
 In this example the subagent extension restricts visibility to `bash` and `read`, and the permission system then gates every `bash` call with an `ask` prompt - both rules apply independently.
 
+[ADR 0012]: https://github.com/gotgenes/pi-packages/blob/main/packages/pi-permission-system/docs/decisions/0012-cross-node-extension-contract.md
 [ADR-0002]: https://github.com/gotgenes/pi-packages/blob/main/packages/pi-subagents/docs/decisions/0002-extensions-on-a-minimal-core.md

package/package.json

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

package/src/authority/authorizer-registry.ts

@@ -10,9 +10,16 @@
  * operator names it in the `authorizerChain` config (the opt-in activation
  * model). `AuthorizerSelection` owns that config-order resolution; this registry
  * is storage only.
+ *
+ * A node that relays its asks runs no chain at all (ADR 0007 §7), so a link
+ * registered there is accepted and never consulted — the vacant link cell.
+ * {@link ObservedAuthorizerRegistrar} records that fact rather than refusing
+ * the registration (ADR 0012 decision 4).
  */
 
+import type { ReviewLogger } from "#src/session-logger";
 import type { Authorizer } from "./authorizer";
+import type { AdjudicationRole } from "./authorizer-selection";
 
 /**
  * Read-only lookup used by chain composition (ISP — exposes only the read side,
@@ -67,3 +74,46 @@ export class AuthorizerRegistry
     return this.links.get(name);
   }
 }
+
+/**
+ * The registrar a sibling extension reaches through `registerAuthorizer`:
+ * accepts every registration, and records the ones this node will never
+ * consult (ADR 0012 decision 4 — accept and observe).
+ *
+ * Registering everywhere is the correct default for a link author: the
+ * architecture consults a link where adjudication happens, so a link needs no
+ * placement ceremony and cannot be registered "in the wrong node". On a
+ * relaying node that makes the registration vacant by the system's own routing
+ * decision, not by author error — so it is honored (a working disposer comes
+ * back) and written to the review log beside the per-ask
+ * `authorizer_chain_delegated`, where an operator already looks to find out
+ * where adjudication went.
+ *
+ * A decorator rather than a branch inside {@link AuthorizerRegistry}: storage
+ * stays storage, and the chain's own lookup keeps reading the undecorated
+ * registry.
+ */
+export class ObservedAuthorizerRegistrar implements AuthorizerRegistrar {
+  constructor(
+    private readonly registrar: AuthorizerRegistrar,
+    private readonly role: AdjudicationRole,
+    private readonly logger: ReviewLogger,
+  ) {}
+
+  /**
+   * Register `name` into the underlying registry and return its disposer.
+   *
+   * The role is read per registration, not captured at construction: this
+   * registrar outlives a session (the composition root owns it) while the
+   * node's selected authority is per-activation. A duplicate registration
+   * still throws, and records nothing — under the cross-node contract that is
+   * a genuine author bug, not a vacancy.
+   */
+  register(name: string, authorize: Authorizer["authorize"]): () => void {
+    const dispose = this.registrar.register(name, authorize);
+    if (!this.role.adjudicatesLocally()) {
+      this.logger.review("authorizer_link_vacant", { name });
+    }
+    return dispose;
+  }
+}

package/src/authority/authorizer-selection.ts

@@ -39,6 +39,23 @@ export interface AskEscalator {
   escalate(details: PromptPermissionDetails): Promise<PermissionPromptDecision>;
 }
 
+/**
+ * The node's chain role, as a fact a collaborator can read: does this node's
+ * authorizer chain run, or does it relay its asks to a serving node
+ * (ADR 0007 §7)?
+ *
+ * Consumed by the service lifecycle (which broadcasts it on `permissions:ready`
+ * so a sibling extension learns it without knowing what a subagent is) and by
+ * the registration observer (which records a link registered where no chain
+ * runs). Both depend on this single-method view rather than the selection
+ * itself, and neither may re-derive the role from `detection.isSubagent(ctx)`:
+ * `selectAuthorizer` tests `hasUI` first, so a subagent with its own UI
+ * adjudicates locally.
+ */
+export interface AdjudicationRole {
+  adjudicatesLocally(): boolean;
+}
+
 /**
  * Context-owning selection root for the Authorizer spine.
  *
@@ -52,7 +69,7 @@ export interface AskEscalator {
  * predicate survives (#556 dissolved `canConfirm()`).
  */
 export class AuthorizerSelection
-  implements AskEscalator, AuthorizerSelectionLifecycle
+  implements AskEscalator, AuthorizerSelectionLifecycle, AdjudicationRole
 {
   private authority: SelectedAuthority | null = null;
 
@@ -147,6 +164,21 @@ export class AuthorizerSelection
     return links;
   }
 
+  /**
+   * Whether this node adjudicates its own asks. Implements
+   * {@link AdjudicationRole}.
+   *
+   * Reports `true` with no selection stored — before activation, or after
+   * deactivation. Production never reads it there (`activate` runs inside
+   * `PermissionSession.resetForNewSession`, ahead of every consumer), and
+   * "this node adjudicates" is the fail-soft answer: it tells a sibling to
+   * register, which a relaying node accepts and records rather than refusing
+   * (ADR 0012 decision 4).
+   */
+  adjudicatesLocally(): boolean {
+    return this.authority?.adjudicatesLocally ?? true;
+  }
+
   /** Clear the stored selection. */
   deactivate(): void {
     this.authority = null;

package/src/authority/permission-forwarding.ts

@@ -18,7 +18,17 @@ export const PERMISSION_FORWARDING_TIMEOUT_MS = 10 * 60 * 1000;
  */
 export const PERMISSION_FORWARDING_SERVING_GRACE_MS =
   8 * PERMISSION_FORWARDING_POLL_INTERVAL_MS;
-export const SUBAGENT_ENV_HINT_KEYS = [
+/** Ordered list of env var names to check for the parent session ID. First match wins. */
+export const SUBAGENT_PARENT_SESSION_ENV_CANDIDATES: readonly string[] = [
+  // pi-agent-router (original)
+  "PI_AGENT_ROUTER_PARENT_SESSION_ID",
+  // Shared convention for CLI-based subagent extensions
+  // (nicobailon/pi-subagents, HazAT/pi-interactive-subagents, etc.)
+  "PI_SUBAGENT_PARENT_SESSION",
+] as const;
+
+/** Per-extension markers set by known process-based subagent extensions. */
+const THIRD_PARTY_SUBAGENT_ENV_HINTS = [
   // pi-agent-router (original)
   "PI_IS_SUBAGENT",
   "PI_SUBAGENT_SESSION_ID",
@@ -34,14 +44,20 @@ export const SUBAGENT_ENV_HINT_KEYS = [
   "PI_SUBAGENT_SESSION",
   "PI_SUBAGENT_ACTIVITY_FILE",
 ] as const;
-/** Ordered list of env var names to check for the parent session ID. First match wins. */
-export const SUBAGENT_PARENT_SESSION_ENV_CANDIDATES: readonly string[] = [
-  // pi-agent-router (original)
-  "PI_AGENT_ROUTER_PARENT_SESSION_ID",
-  // Shared convention for CLI-based subagent extensions
-  // (nicobailon/pi-subagents, HazAT/pi-interactive-subagents, etc.)
-  "PI_SUBAGENT_PARENT_SESSION",
-] as const;
+
+/**
+ * Env vars whose presence marks the current process as a subagent child.
+ *
+ * A process that names a parent session is a child by definition, so every
+ * parent-session candidate is a detection hint too. That is what makes the
+ * subagent adapter convention's single out-of-process obligation — set
+ * `PI_SUBAGENT_PARENT_SESSION` — sufficient on its own: an implementation owes
+ * the announcement and nothing else, and detection is this package's job.
+ */
+export const SUBAGENT_ENV_HINT_KEYS: readonly string[] = [
+  ...THIRD_PARTY_SUBAGENT_ENV_HINTS,
+  ...SUBAGENT_PARENT_SESSION_ENV_CANDIDATES,
+];
 
 /** @deprecated Use SUBAGENT_PARENT_SESSION_ENV_CANDIDATES */
 export const SUBAGENT_PARENT_SESSION_ENV_KEY =

package/src/authority/subagent-context.ts

@@ -1,6 +1,7 @@
 import { SUBAGENT_ENV_HINT_KEYS } from "#src/authority/permission-forwarding";
 import type { SubagentSessionRegistry } from "#src/authority/subagent-registry";
 import type { PathFlavor } from "#src/path/path-flavor";
+import { readSessionId } from "#src/session-identity";
 
 /**
  * Narrow context for subagent detection — the only session-manager readers
@@ -35,16 +36,9 @@ export function isRegisteredSubagentChild(
   ctx: SubagentDetectionContext,
   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;
-  }
+  const sessionId = readSessionId(ctx);
+  // An unreachable session id names no registration — treat as not-a-child.
+  return sessionId !== null && registry.has(sessionId);
 }
 
 export function isSubagentExecutionContext(

package/src/handlers/before-agent-start.ts

@@ -2,6 +2,7 @@ import type {
   BeforeAgentStartEventResult,
   ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
+import type { TurnPreparation } from "#src/handlers/session-turn-prep";
 import type { PermissionResolver } from "#src/permission-resolver";
 import type { PermissionSession } from "#src/permission-session";
 import { resolveSkillPromptEntries } from "#src/skill-prompt-sanitizer";
@@ -37,19 +38,18 @@ export function shouldExposeTool(
  * than letting Pi reset to its skill-unfiltered base prompt on a cache hit.
  *
  * Constructor deps:
+ * - `turnPrep` — brings the node up to date for the turn before anything reads
+ *   session state
  * - `session` — encapsulates all mutable session state and lifecycle operations
  * - `resolver` — owns permission-query surface: `getToolPermission`, skill check
  * - `toolRegistry` — Pi tool API subset (getActive + setActive)
- * - `warmParser` — warms the tree-sitter parser so the synchronous advisory
- *   bash path can decompose at gate parity; `before_agent_start` precedes any
- *   tool call, so triggering it here closes the pre-warm window (#309)
  */
 export class AgentPrepHandler {
   constructor(
+    private readonly turnPrep: TurnPreparation,
     private readonly session: PermissionSession,
     private readonly resolver: PermissionResolver,
     private readonly toolRegistry: ToolRegistry,
-    private readonly warmParser: () => void,
   ) {}
 
   // eslint-disable-next-line @typescript-eslint/require-await
@@ -57,16 +57,7 @@ export class AgentPrepHandler {
     event: BeforeAgentStartPayload,
     ctx: ExtensionContext,
   ): Promise<BeforeAgentStartEventResult> {
-    // Fire-and-forget: warming is idempotent and best-effort, so it never
-    // delays agent start. A bash advisory query before it completes falls back
-    // to whole-string matching.
-    this.warmParser();
-    this.session.activate(ctx);
-    // Gate the mid-session runtime-config refresh on project trust too, so an
-    // untrusted project cannot slip its runtime config (e.g. `yoloMode`) in
-    // right before agent start after session_start withheld it (#644). The
-    // session_start handler already warned; do not re-warn on every start.
-    this.session.refreshConfig(ctx, ctx.isProjectTrusted());
+    this.turnPrep.prepare(ctx);
 
     const agentName = this.session.resolveAgentName(ctx, event.systemPrompt);
     const activeTools = this.toolRegistry.getActive();

package/src/handlers/index.ts

@@ -1,3 +1,4 @@
 export { AgentPrepHandler } from "./before-agent-start";
 export { SessionLifecycleHandler } from "./lifecycle";
 export { PermissionGateHandler } from "./permission-gate-handler";
+export { SessionTurnPrep } from "./session-turn-prep";

package/src/handlers/session-turn-prep.ts

@@ -0,0 +1,58 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ReadyAnnouncer } from "#src/service-lifecycle";
+
+/** The session surface the turn-prep routine drives. */
+export interface TurnPrepSession {
+  activate(ctx: ExtensionContext): void;
+  refreshConfig(
+    ctx: ExtensionContext | undefined,
+    projectTrusted: boolean,
+  ): void;
+}
+
+/** What a `before_agent_start` handler asks for; `SessionTurnPrep` provides it. */
+export interface TurnPreparation {
+  prepare(ctx: ExtensionContext): void;
+}
+
+/**
+ * Brings this node up to date for the turn about to start.
+ *
+ * Everything that must be true before the node answers a permission question
+ * this turn lives here, so the `before_agent_start` handler is left with the
+ * one job its name describes: filtering tools and sanitizing the prompt.
+ *
+ * Constructor deps:
+ * - `session` — activated with the turn's context, then refreshed from disk
+ * - `warmParser` — warms the tree-sitter parser so the synchronous advisory
+ *   bash path can decompose at gate parity; `before_agent_start` precedes any
+ *   tool call, so triggering it here closes the pre-warm window (#309)
+ * - `readyAnnouncer` — re-announces `permissions:ready` once per session
+ *   (ADR 0012 decision 3); `before_agent_start` runs after every extension's
+ *   `session_start` and before any ask, so a consumer that registers from the
+ *   ready handler alone is heard in time
+ */
+export class SessionTurnPrep implements TurnPreparation {
+  constructor(
+    private readonly session: TurnPrepSession,
+    private readonly warmParser: () => void,
+    private readonly readyAnnouncer: ReadyAnnouncer,
+  ) {}
+
+  prepare(ctx: ExtensionContext): void {
+    // Fire-and-forget: warming is idempotent and best-effort, so it never
+    // delays agent start. A bash advisory query before it completes falls back
+    // to whole-string matching.
+    this.warmParser();
+    this.session.activate(ctx);
+    // Gate the mid-session runtime-config refresh on project trust too, so an
+    // untrusted project cannot slip its runtime config (e.g. `yoloMode`) in
+    // right before agent start after session_start withheld it (#644). The
+    // session_start handler already warned; do not re-warn on every start.
+    this.session.refreshConfig(ctx, ctx.isProjectTrusted());
+    // Announce last: the node is up to date for the turn, so a consumer that
+    // resolves the service in its ready handler queries current policy. The
+    // once-per-session guard lives in the announcer, not here.
+    this.readyAnnouncer.announceReady(ctx);
+  }
+}