@gotgenes/pi-permission-system 26.3.0 → 27.0.0

package/CHANGELOG.md

@@ -5,6 +5,46 @@ 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).
 
+## [27.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v26.3.1...pi-permission-system-v27.0.0) (2026-08-21)
+
+
+### ⚠ BREAKING CHANGES
+
+* **pi-permission-system:** `permissions:ready` now fires at least once per session and may repeat. The latch added in #787 re-emits it at each node's first `before_agent_start`, so a consumer that registers unconditionally on every emission hits a duplicate-registration throw on every session instead of the rare user-initiated `/reload` it previously hit. Guard the ready handler with a stored dispose handle so it registers once per session, and release it on `session_shutdown`.
+
+### Features
+
+* **pi-permission-system:** deprecate the zero-arg service accessor ([#699](https://github.com/gotgenes/pi-packages/issues/699)) ([511c87f](https://github.com/gotgenes/pi-packages/commit/511c87f46e1ec85137145442050d53ae41eb8cd1))
+* **pi-permission-system:** publish each node's service under its own session id ([#699](https://github.com/gotgenes/pi-packages/issues/699)) ([d8ce4a8](https://github.com/gotgenes/pi-packages/commit/d8ce4a85ac381b6123b4d1f461d59073953a22b6))
+* **pi-permission-system:** re-emit permissions:ready at the first before_agent_start ([#787](https://github.com/gotgenes/pi-packages/issues/787)) ([405e904](https://github.com/gotgenes/pi-packages/commit/405e904e527645776cab8162293682a71fa5ec65))
+* **pi-permission-system:** reclaim getPermissionsService for the keyed locator ([214b30a](https://github.com/gotgenes/pi-packages/commit/214b30abf3a2ba3dc2f8f9bc3c56932a868c32dd))
+* **pi-permission-system:** record a vacant link cell on a relaying node ([#699](https://github.com/gotgenes/pi-packages/issues/699)) ([f5f08d2](https://github.com/gotgenes/pi-packages/commit/f5f08d2c159504f508b88f9e163be2f9049d558d))
+* **pi-permission-system:** warn when the keyed locator gets no session id ([29824aa](https://github.com/gotgenes/pi-packages/commit/29824aae61b1a4f565b5c456d9f3440d77304be5)), closes [#794](https://github.com/gotgenes/pi-packages/issues/794)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** detect a subagent from its parent-session env var ([bd698da](https://github.com/gotgenes/pi-packages/commit/bd698da14a7d44dfa8dc06be2342a47b8337324e)), closes [#789](https://github.com/gotgenes/pi-packages/issues/789)
+
+
+### Documentation
+
+* **pi-permission-system:** cite the adapter convention instead of restating it ([d9ba637](https://github.com/gotgenes/pi-packages/commit/d9ba6375b29e3e25e53d9324676e7c5220c2bad7)), closes [#789](https://github.com/gotgenes/pi-packages/issues/789)
+* **pi-permission-system:** document session-keyed service publication ([#699](https://github.com/gotgenes/pi-packages/issues/699)) ([8ed137c](https://github.com/gotgenes/pi-packages/commit/8ed137c662a22087edc3623151938c7ae0ea9a86))
+* **pi-permission-system:** document the ready latch and its idempotency requirement ([#787](https://github.com/gotgenes/pi-packages/issues/787)) ([bc31193](https://github.com/gotgenes/pi-packages/commit/bc31193aafa8c6ef1356cc2e096e643f6357c912))
+* **pi-permission-system:** document the reclaimed locator and the ready cadence ([ca585b4](https://github.com/gotgenes/pi-packages/commit/ca585b4fba48a95ddd4dbe51106c02486997a400)), closes [#794](https://github.com/gotgenes/pi-packages/issues/794)
+* **pi-permission-system:** make subagent-integration the adapter convention's canonical spec ([07f9d2b](https://github.com/gotgenes/pi-packages/commit/07f9d2beffb66207aa3b01985b1a28312d431da3)), closes [#789](https://github.com/gotgenes/pi-packages/issues/789)
+
+## [26.3.1](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v26.3.0...pi-permission-system-v26.3.1) (2026-08-19)
+
+
+### Documentation
+
+* condense scope sections and move them below the usage material ([#775](https://github.com/gotgenes/pi-packages/issues/775)) ([99f5829](https://github.com/gotgenes/pi-packages/commit/99f58298962baac5bdfe5d3cc02dca0ca9b32395))
+* **pi-permission-system:** document scope and non-goals ([#775](https://github.com/gotgenes/pi-packages/issues/775)) ([5fa3960](https://github.com/gotgenes/pi-packages/commit/5fa39609953ad8bf370a0e304a73fdf67df6dae5))
+* **retro:** add retro notes for issue [#610](https://github.com/gotgenes/pi-packages/issues/610) ([2333e6a](https://github.com/gotgenes/pi-packages/commit/2333e6ae57fe77c64e322e520918404995ef1dda))
+* route model-assisted judging to the seam, not to one link ([#775](https://github.com/gotgenes/pi-packages/issues/775)) ([3f30984](https://github.com/gotgenes/pi-packages/commit/3f30984b53eb0a14217cf70ecb05ac1daab48abb))
+
 ## [26.3.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v26.2.2...pi-permission-system-v26.3.0) (2026-08-18)
 
 

package/README.md

@@ -115,7 +115,7 @@ Within a surface map like `bash` or `mcp`, **last matching rule wins** — put b
 The optional `shellTools` field records which non-`bash` tools carry shell semantics (e.g. an `exec_command` tool that replaces native `bash`), so they are gated at full parity with native `bash` — see [docs/configuration.md](docs/configuration.md#shelltools--gating-aliased-shell-tools).
 
 The optional `authorizerChain` field names registered case-by-case decision links (e.g. a light model judge) to consult when a request lands on `ask`, ahead of the interactive prompt.
-A downstream extension registers a link via `getPermissionsService().registerAuthorizer(name, authorize)`; it decides nothing until you name it here (opt-in), config order fixes the chain order, and the chain owner caps any link's `allow` on `external_directory`/`path` to keep it within your policy — see [docs/configuration.md](docs/configuration.md#authorizer-chain--case-by-case-decision-links).
+A downstream extension registers a link via `getPermissionsService(sessionId).registerAuthorizer(name, authorize)`; it decides nothing until you name it here (opt-in), config order fixes the chain order, and the chain owner caps any link's `allow` on `external_directory`/`path` to keep it within your policy — see [docs/configuration.md](docs/configuration.md#authorizer-chain--case-by-case-decision-links).
 A subagent's ask is reviewed by the chain of the session serving it, one hop up, rather than inside the subagent — see the same section.
 [`@gotgenes/pi-permission-model-judge`](https://github.com/gotgenes/pi-packages/tree/main/packages/pi-permission-model-judge) is a first-party reference implementation of such a link — a deny-first reviewer that auto-denies mistyped out-of-directory paths.
 
@@ -137,6 +137,41 @@ Commands that previously slipped through silently on the error or empty-parse pa
 
 If you relied on the old permissive behavior for bash, set an explicit permissive bash policy — `"bash": { "*": "allow" }` — which also suppresses the new startup warning emitted when a top-level `"*": "allow"` leaves bash ungated.
 
+## Scope and non-goals
+
+**Purpose.**
+An agent takes many actions, most of them benign, but some of which need a human to confirm they are safe or correct.
+This package routes your attention to those, and turns each ruling into deterministic, reusable policy — enforced at the host level rather than by asking the model to police itself.
+
+**In scope.**
+Hardening the gates against bypass, fail-closed corrections (breaking ones included), named opt-in extension seams for downstream packages, and structural work backed by a written decision record.
+
+**Non-goals.**
+
+- _Sandboxing._
+  This is a decision layer, not a sandbox — it decides and records, it does not isolate.
+  If a dangerous action is reachable through an allowed tool, policy has to restrict it explicitly.
+- _Deciding project trust._
+  A policy enforcer, not a trust oracle: whether a project is trusted is Pi's decision and yours, and this package observes it.
+- _Permissive defaults, trust profiles, or workflow presets._
+  Your risk profile is not knowable from here, so defaults are least-privilege and common policies ship as documented recipes rather than preset keywords.
+- _Guessing what is sensitive._
+  No built-in secret denylist, and log redaction is key-name-structural rather than predictive — a redactor that silently misses a key invites treating the log as safe to share.
+- _Model judgment in the core._
+  This package makes no LLM call and holds no model config; model-assisted judging attaches as a chain link over the authorizer seam instead.
+  A link decides nothing until you name it in `authorizerChain`, and its `allow` on an excluded surface is downgraded to `defer`.
+
+The [architecture doc](https://github.com/gotgenes/pi-packages/blob/main/packages/pi-permission-system/docs/architecture/architecture.md#scope-and-non-goals) carries the full inventory, with the decision record behind each entry.
+
+**One decision is still open.**
+How policy may _enter_ the system — which channels are admissible, and with what precedence — is being worked out in [issue #639](https://github.com/gotgenes/pi-packages/issues/639), along with whether a capability model replaces the current surface list.
+Several requested widenings are parked on it rather than declined, durable persistence of an approval among them.
+
+**Where adjacent requests belong.**
+True isolation of a permitted action → an agent sandbox.
+Model-assisted judging of an `ask` → a chain link over the authorizer seam; [@gotgenes/pi-permission-model-judge](https://www.npmjs.com/package/@gotgenes/pi-permission-model-judge) is the first-party one, and judges mistyped paths.
+Approve-and-steer, edit diffs, and risk explanations → a downstream package over the `permissions:decision` event and the presentation seams.
+
 ## Documentation
 
 | Document                                                                                                                       | Contents                                                                                                             |
@@ -144,7 +179,7 @@ If you relied on the old permissive behavior for bash, set an explicit permissiv
 | [docs/configuration.md](docs/configuration.md)                                                                                 | Full policy reference, runtime knobs, per-agent overrides, recipes                                                   |
 | [docs/session-approvals.md](docs/session-approvals.md)                                                                         | Session-scoped rules, pattern suggestions, bash arity table                                                          |
 | [docs/cross-extension-api.md](docs/cross-extension-api.md)                                                                     | Cross-extension service accessor, event bus integration, prompt and decision broadcasts                              |
-| [docs/subagent-integration.md](docs/subagent-integration.md)                                                                   | Permission forwarding, coexistence with subagent extensions                                                          |
+| [docs/subagent-integration.md](docs/subagent-integration.md)                                                                   | The subagent adapter convention, permission forwarding, coexistence with subagent extensions                         |
 | [docs/guides/permission-frontmatter-for-subagent-extensions.md](docs/guides/permission-frontmatter-for-subagent-extensions.md) | Convention guide for subagent extension authors                                                                      |
 | [docs/opencode-compatibility.md](docs/opencode-compatibility.md)                                                               | OpenCode compatibility — shared concepts, divergences, porting guide                                                 |
 | [docs/troubleshooting.md](docs/troubleshooting.md)                                                                             | Common issues, diagnostic logging, threat model                                                                      |
@@ -153,6 +188,7 @@ If you relied on the old permissive behavior for bash, set an explicit permissiv
 | [docs/migration/0644-project-trust-gating.md](docs/migration/0644-project-trust-gating.md)                                     | Project-trust gating (breaking) — project config loads only after project trust                                      |
 | [docs/migration/0745-prompt-payload-contracts.md](docs/migration/0745-prompt-payload-contracts.md)                             | Prompt payload contracts (breaking) — the forwarded wire, the `ui_prompt` broadcast, and the deprecated preview caps |
 | [docs/migration/0746-review-log-fields.md](docs/migration/0746-review-log-fields.md)                                           | Review-log fields (breaking) — `message` replaced by request facts, and the `reviewLogFieldMaxWidth` bound           |
+| [docs/migration/0794-keyed-service-locator.md](docs/migration/0794-keyed-service-locator.md)                                   | Keyed service locator (breaking) — `getPermissionsService(sessionId)`, and the repeating ready event                 |
 
 ## Development
 

package/dist/public.d.ts

@@ -158,20 +158,48 @@ interface PromptAnnotation {
  * removed or renamed without a semver-major version bump.
  */
 
-/** Emitted at `session_start`, after the service is published. */
+/**
+ * Emitted at `session_start` after the emitting node published its service, and
+ * again at that node's first `before_agent_start` (ADR 0012 decision 3).
+ *
+ * Fires at least once per session and may repeat, so a handler must be
+ * idempotent — registering on every emission hits the duplicate-registration
+ * throw.
+ */
 declare const PERMISSIONS_READY_CHANNEL = "permissions:ready";
 /** Emitted when a permission request is committed to the active UI prompt path. */
 declare const PERMISSIONS_UI_PROMPT_CHANNEL = "permissions:ui_prompt";
 /** Emitted after every permission gate resolution. */
 declare const PERMISSIONS_DECISION_CHANNEL = "permissions:decision";
 /**
- * Payload emitted on `permissions:ready`.
+ * Payload emitted on `permissions:ready`: plain facts about the node that
+ * emitted it (ADR 0012 decision 2).
  *
- * Intentionally empty: the channel is a readiness signal. There is no
- * `protocolVersion` — the published types plus package semver define the
- * broadcast contract.
+ * The bus announces; the locator provides. The payload carries data a consumer
+ * can log, serialize, and replay — never a live capability — so the service
+ * itself is fetched with `getPermissionsService(sessionId)`.
+ *
+ * There is no `protocolVersion` — the published types plus package semver
+ * define the broadcast contract.
  */
-type PermissionsReadyEvent = Record<string, never>;
+interface PermissionsReadyEvent {
+    /**
+     * The emitting node's session id: the key for
+     * `getPermissionsService`. `null` when the host exposed no session
+     * id, in which case this node published no keyed service.
+     */
+    sessionId: string | null;
+    /**
+     * Whether this node adjudicates its own asks (its authorizer chain runs) or
+     * relays them to a serving node, which runs *its* chain over the same facts
+     * (ADR 0007 §7).
+     *
+     * A registration needs no branch on this: extractors and formatters are read
+     * by every node's own gates, and a chain link registered where no chain runs
+     * is accepted and recorded rather than refused (ADR 0012 decision 4).
+     */
+    adjudicatesLocally: boolean;
+}
 /**
  * Origin of a UI prompt.
  *
@@ -405,16 +433,26 @@ type ToolAccessExtractor = (input: Record<string, unknown>) => string | undefine
 type ToolInputFormatter = (input: Record<string, unknown>) => string | undefined;
 
 /**
- * Cross-extension service accessor backed by `Symbol.for()` on `globalThis`.
+ * Cross-extension service accessors backed by `Symbol.for()` on `globalThis`.
  *
  * `Symbol.for()` is process-global by spec, so it survives jiti's per-extension
  * module isolation (`moduleCache: false`). A consumer doing
- * `import("@gotgenes/pi-permission-system")` gets a fresh module copy, but
- * `getPermissionsService()` reads from the same `globalThis` slot the provider
- * wrote to — enabling direct, synchronous, type-safe function calls.
+ * `import("@gotgenes/pi-permission-system")` gets a fresh module copy, but the
+ * accessors here read from the same `globalThis` slots the provider wrote to —
+ * enabling direct, synchronous, type-safe function calls.
+ *
+ * There are two slots, because one process can host several **nodes** (one Pi
+ * session runtime each — a root session and its in-process subagent children
+ * all load their own instance of this extension):
+ *
+ * - A session-keyed map, written by every node under its own session id.
+ *   `getPermissionsService(sessionId)` resolves the service whose
+ *   registries that node's own gates and chain read (ADR 0012 decision 2).
+ * - A single legacy slot holding the process root's service, read by the
+ *   deprecated `getRootPermissionsService()`.
  *
- * Best practice: call `getPermissionsService()` per use rather than caching the
- * reference — this ensures resilience across `/reload` and load-order edge cases.
+ * Best practice: resolve per use rather than caching the reference — this
+ * ensures resilience across `/reload` and load-order edge cases.
  */
 
 /**
@@ -466,7 +504,14 @@ interface PermissionQuery {
     getToolPermission(toolName: string, agentName?: string): PermissionState;
 }
 /**
- * Public interface exposed to other extensions via `getPermissionsService()`.
+ * Public interface exposed to other extensions via
+ * {@link getPermissionsService} (or the deprecated
+ * {@link getRootPermissionsService}).
+ *
+ * Each instance belongs to one node, and its three registration surfaces are
+ * read by that node alone: extractors and formatters by its own gates, chain
+ * links by its own chain. Resolve the service of the node whose behavior you
+ * mean to affect.
  *
  * `checkPermission` takes a surface + optional value + optional agent name,
  * and delegates to `PermissionManager.checkPermission()` with current session
@@ -532,20 +577,59 @@ interface PermissionsService extends PermissionQuery {
     registerAuthorizer(name: string, authorize: Authorizer["authorize"]): () => void;
 }
 /**
- * Store a `PermissionsService` on `globalThis` so other extensions can
- * retrieve it via `getPermissionsService()`.
+ * Store a `PermissionsService` in the legacy process-root slot, read by
+ * `getRootPermissionsService()`.
  *
  * 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.
  */
-declare function publishPermissionsService(service: PermissionsService): void;
+declare function publishRootPermissionsService(service: PermissionsService): void;
+/**
+ * Retrieve the process root's published `PermissionsService`, or `undefined`
+ * if the permission-system extension has not loaded (or has been unloaded).
+ *
+ * @deprecated Use {@link getPermissionsService} with the `sessionId`
+ * from the `permissions:ready` payload. This accessor answers "the process
+ * root's service", which is the wrong question in every node but the root.
+ * Removal is deferred to a future major (ADR 0012 decision 7).
+ */
+declare function getRootPermissionsService(): PermissionsService | undefined;
+/**
+ * Publish `service` as the service of the node whose session is `sessionId`
+ * (ADR 0012 decision 2 — node-locality).
+ *
+ * Every node publishes under its own key, including an in-process subagent
+ * child, so there is nothing to clobber: a child's sibling extension registers
+ * an extractor, formatter, or chain link into the registry the child's own
+ * gates and chain read.
+ */
+declare function publishPermissionsService(sessionId: string, service: PermissionsService): void;
+/**
+ * Retrieve the service belonging to the node whose session is `sessionId`, or
+ * `undefined` when that node has published none.
+ *
+ * This is the supported way to obtain a node's service, for registration and
+ * for policy queries alike. Take `sessionId` from the `permissions:ready`
+ * payload (or from `ctx.sessionManager.getSessionId()` inside your own session
+ * handler), and resolve per use rather than caching the reference.
+ *
+ * A caller the type checker cannot reach — JavaScript, or a consumer compiled
+ * against an earlier major — may still call this with no argument. That answers
+ * `undefined` rather than another node's service, and warns once so the missing
+ * registration is not silent.
+ */
+declare function getPermissionsService(sessionId: string): PermissionsService | undefined;
 /**
- * Retrieve the published `PermissionsService`, or `undefined` if the
- * permission-system extension has not loaded (or has been unloaded).
+ * Remove the `sessionId` entry, but only when it still holds `service`
+ * (identity compare-and-delete, like {@link unpublishRootPermissionsService}).
+ *
+ * Scoping the delete to the publishing instance keeps a superseded `/reload`
+ * generation's late shutdown from wiping the new generation's freshly
+ * published service.
  */
-declare function getPermissionsService(): PermissionsService | undefined;
+declare function unpublishPermissionsService(sessionId: string, service: PermissionsService): void;
 /**
  * Remove `service` from `globalThis`, but only when the current slot still
  * holds it (identity compare-and-delete).
@@ -559,7 +643,7 @@ declare function getPermissionsService(): PermissionsService | undefined;
  * - A superseded `/reload` generation no longer owns the slot, so its late
  *   shutdown cannot wipe the new generation's freshly published service.
  */
-declare function unpublishPermissionsService(service: PermissionsService): void;
+declare function unpublishRootPermissionsService(service: PermissionsService): void;
 
-export { PERMISSIONS_DECISION_CHANNEL, PERMISSIONS_READY_CHANNEL, PERMISSIONS_UI_PROMPT_CHANNEL, getPermissionsService, publishPermissionsService, unpublishPermissionsService };
+export { PERMISSIONS_DECISION_CHANNEL, PERMISSIONS_READY_CHANNEL, PERMISSIONS_UI_PROMPT_CHANNEL, getPermissionsService, getRootPermissionsService, publishPermissionsService, publishRootPermissionsService, unpublishPermissionsService, unpublishRootPermissionsService };
 export type { Authorizer, AuthorizerLog, AuthorizerVerdict, ForwardedPromptContext, PermissionCheckResult, PermissionDecisionEvent, PermissionQuery, PermissionState, PermissionUiPromptEvent, PermissionUiPromptSource, PermissionsReadyEvent, PermissionsService, PromptAnnotation, PromptEvidence, PromptPayload, PromptPayloadKind, PromptPermissionDetails, PromptRequestFacts, PromptRequester, ToolInputFormatter };

package/docs/configuration.md

@@ -244,9 +244,11 @@ Three review-log records make the chain observable, all keyed by the ask's `requ
 | `authorizer_chain_resolved`          | the links consulted on this ask, recorded before they run — a link that defers otherwise leaves no trace |
 | `authorizer_chain_delegated`         | the ask came from a relaying subagent node; the named links were deliberately not run here               |
 | `authorizer_chain_unregistered_link` | a configured name had no registered link — a real misconfiguration; the ask still reaches the terminal   |
+| `authorizer_link_vacant`             | a link was registered on a relaying node, which runs no chain — accepted and recorded, never consulted   |
 
-Extension authors: register a link from a `permissions:ready` handler via `getPermissionsService().registerAuthorizer(name, authorize)`; the callback receives the ask details and a narrow, session-scoped `PermissionQuery` (`checkPermission` / `getToolPermission`) so it can consult the deterministic engine at gate parity.
+Extension authors: register a link from a `permissions:ready` handler via `getPermissionsService(sessionId).registerAuthorizer(name, authorize)`, taking `sessionId` from that event's payload; the callback receives the ask details and a narrow, session-scoped `PermissionQuery` (`checkPermission` / `getToolPermission`) so it can consult the deterministic engine at gate parity.
 Registration returns a disposer, and only one link may hold a given name.
+Register in every session without branching: a session that relays its asks accepts the link and records `authorizer_link_vacant` rather than refusing it.
 For a complete working example, see [`@gotgenes/pi-permission-model-judge`](https://github.com/gotgenes/pi-packages/tree/main/packages/pi-permission-model-judge): it registers a `model-judge` link on `permissions:ready` that reviews `external_directory` asks and auto-denies mistyped paths with a corrective reason.
 
 ---

package/docs/cross-extension-api.md

@@ -15,29 +15,45 @@ It provides direct, synchronous, type-safe function calls.
 ### Quick Start
 
 ```typescript
-try {
-  const { getPermissionsService } = await import(
-    "@gotgenes/pi-permission-system"
-  );
-  const permissions = getPermissionsService();
-  if (permissions) {
-    const result = permissions.checkPermission("bash", "git push");
-    console.log(result.state); // "allow" | "deny" | "ask"
-  }
-} catch {
-  // Not installed — graceful degradation
-}
+pi.events.on("permissions:ready", (data) => {
+  const { sessionId } = data as PermissionsReadyEvent;
+  if (!sessionId) return;
+  void (async () => {
+    try {
+      const { getPermissionsService } =
+        await import("@gotgenes/pi-permission-system");
+      const permissions = getPermissionsService(sessionId);
+      if (permissions) {
+        const result = permissions.checkPermission("bash", "git push");
+        console.log(result.state); // "allow" | "deny" | "ask"
+      }
+    } catch {
+      // Not installed — graceful degradation
+    }
+  })();
+});
 ```
 
+Inside your own `session_start` handler, `ctx.sessionManager.getSessionId()` is the same key.
+
 ### How It Works
 
 Pi's extension loader creates a fresh [jiti](https://github.com/nicolo-ribaudo/jiti) instance per extension with `moduleCache: false`, which isolates module-level state.
 `Symbol.for()` and `globalThis` are process-global by spec, so they survive this isolation.
 
-The permission-system extension publishes a service object on `globalThis` via `Symbol.for("@gotgenes/pi-permission-system:service")` at `session_start`.
-Consumers call `getPermissionsService()` to retrieve it — even though their `import()` loads a fresh module copy, the accessor reads from the shared `globalThis` slot.
-An in-process subagent child does not publish its own service; inside a child, `getPermissionsService()` resolves the parent's service.
-A consumer reacting to the `permissions:ready` broadcast (also emitted at `session_start`, after the publish) can resolve the service immediately.
+One process can host several **nodes** — one Pi session runtime each, with its own gates and its own registries.
+A root session and each of its in-process subagent children are separate nodes, and each loads its own instance of this extension.
+Registrations never cross a node boundary: a formatter, an access extractor, or an authorizer link is read by the node it was registered in.
+
+Each node therefore publishes its own service at `session_start`, into a `globalThis` map keyed by that node's session id (`Symbol.for("@gotgenes/pi-permission-system:session-services")`).
+Consumers call `getPermissionsService(sessionId)` to retrieve it — even though their `import()` loads a fresh module copy, the accessor reads from the shared `globalThis` slot.
+The session id arrives as a field on the `permissions:ready` broadcast, which each node emits at its own `session_start`, right after publishing — and again at that node's first `before_agent_start`, so a consumer whose own `session_start` ran later still hears it.
+
+`getRootPermissionsService()` remains, reading a separate legacy slot that holds the **process root's** service, but it is deprecated: in any node but the root it answers the wrong question, handing an in-process child the parent's service.
+Calling it emits a once-guarded Node `DeprecationWarning` (code `PI_PERMISSION_SYSTEM_DEP0001`); run with `--trace-deprecation` to locate your call site, or `--no-deprecation` to silence it.
+Removal is deferred to a future major release.
+
+Both accessors were renamed in the major that reclaimed `getPermissionsService` for the keyed locator; if you are upgrading from a release whose `getPermissionsService()` took no argument, see [migration/0794-keyed-service-locator.md](migration/0794-keyed-service-locator.md).
 
 All types below are directly importable and type-check with `tsc` out of the box.
 `@gotgenes/pi-permission-system`'s published `exports` resolve `import type { … }` to a self-contained, bundled declaration file with no internal module references, so a downstream `tsconfig.json` needs no special path configuration.
@@ -184,30 +200,33 @@ Register during your extension's initialization and store the disposer for teard
 export default function myExtension(pi: ExtensionAPI): void {
   let disposeFormatter: (() => void) | undefined;
 
-  void (async () => {
-    try {
-      const { getPermissionsService } = await import(
-        "@gotgenes/pi-permission-system"
-      );
-      const permissions = getPermissionsService();
-      disposeFormatter = permissions?.registerToolInputFormatter(
-        "deploy", // a tool THIS extension registers with Pi
-        (input) => {
-          const target =
-            typeof input.target === "string" ? input.target : undefined;
-          const services = Array.isArray(input.services)
-            ? input.services.length
-            : undefined;
-          if (!target) return undefined; // decline → default preview
-          return services !== undefined
-            ? `with target ${target} (${services} services)`
-            : `with target ${target}`;
-        },
-      );
-    } catch {
-      // permission-system not installed — nothing to register
-    }
-  })();
+  pi.events.on("permissions:ready", (data) => {
+    const { sessionId } = data as PermissionsReadyEvent;
+    if (disposeFormatter || !sessionId) return;
+    void (async () => {
+      try {
+        const { getPermissionsService } =
+          await import("@gotgenes/pi-permission-system");
+        const permissions = getPermissionsService(sessionId);
+        disposeFormatter = permissions?.registerToolInputFormatter(
+          "deploy", // a tool THIS extension registers with Pi
+          (input) => {
+            const target =
+              typeof input.target === "string" ? input.target : undefined;
+            const services = Array.isArray(input.services)
+              ? input.services.length
+              : undefined;
+            if (!target) return undefined; // decline → default preview
+            return services !== undefined
+              ? `with target ${target} (${services} services)`
+              : `with target ${target}`;
+          },
+        );
+      } catch {
+        // permission-system not installed — nothing to register
+      }
+    })();
+  });
 
   pi.on("session_shutdown", () => {
     disposeFormatter?.();
@@ -265,24 +284,27 @@ The extractor must not throw — guard your parsing and return `undefined` on an
 
 #### Subagent session registration
 
-In-process subagent registration is event-driven.
-`@gotgenes/pi-subagents` emits `subagents:child:session-created` before `bindExtensions()` and `subagents:child:disposed` in the run's `finally`; the permission system subscribes automatically — no service call from the spawner is required.
-See [Subagent Integration](subagent-integration.md) for details.
+Subagent registration is announcement-driven, and the spawner makes no service call.
+The channel names, payload shapes, pre-bind ordering, and the out-of-process environment variable are specified by the subagent adapter convention in [Subagent Integration](subagent-integration.md#the-subagent-adapter-convention).
 
 ### Reload Safety
 
 During `/reload`, all extensions re-initialize.
-The permission-system re-publishes a fresh service at `session_start`; teardown is identity-scoped, so a superseded generation's shutdown only clears the slot when it still owns it and cannot wipe the new service.
+The permission-system re-publishes a fresh service at `session_start`; teardown is identity-scoped for both slots, so a superseded generation's shutdown only removes an entry it still owns and cannot wipe the new service.
 Consumers that re-initialize during reload naturally get the new instance.
 
-Best practice: call `getPermissionsService()` per use rather than caching the reference.
+Best practice: resolve the service per use rather than caching the reference.
 
 ### Graceful Degradation
 
-`getPermissionsService()` returns `undefined` when the permission-system extension has not loaded (or has been unloaded).
+`getPermissionsService(sessionId)` returns `undefined` when the permission-system extension has not loaded into that node (or has been unloaded).
 The `import()` throws if the package is not installed.
 Wrap both in `try/catch` + `if` guard as shown in the Quick Start example.
 
+It also returns `undefined` when called with no session id at all — a shape TypeScript rejects but JavaScript reaches — rather than falling back to the process root's service, since answering with another node's service is the defect the keyed locator exists to prevent.
+That call emits a once-guarded Node warning (code `PI_PERMISSION_SYSTEM_WARN0001`), because the guard above turns the missing service into a registration that silently never happens.
+It is deliberately not a `DeprecationWarning`: `--no-deprecation` does not silence it.
+
 ---
 
 ## Event Bus
@@ -299,11 +321,11 @@ All three broadcasts are best-effort: a throwing listener cannot block permissio
 
 ## Channel Reference
 
-| Channel                 | Direction | When                              | Payload type              |
-| ----------------------- | --------- | --------------------------------- | ------------------------- |
-| `permissions:ready`     | Broadcast | At `session_start`, after publish | `PermissionsReadyEvent`   |
-| `permissions:ui_prompt` | Broadcast | Before active UI prompt           | `PermissionUiPromptEvent` |
-| `permissions:decision`  | Broadcast | After every gate resolution       | `PermissionDecisionEvent` |
+| Channel                 | Direction | When                                                                                                  | Payload type              |
+| ----------------------- | --------- | ----------------------------------------------------------------------------------------------------- | ------------------------- |
+| `permissions:ready`     | Broadcast | At each node's `session_start` after that node publishes, and again at its first `before_agent_start` | `PermissionsReadyEvent`   |
+| `permissions:ui_prompt` | Broadcast | Before active UI prompt                                                                               | `PermissionUiPromptEvent` |
+| `permissions:decision`  | Broadcast | After every gate resolution                                                                           | `PermissionDecisionEvent` |
 
 ---
 
@@ -401,12 +423,13 @@ A served decision carries a non-null `forwarding` context; the requesting sessio
 
 The `requestId` is the same id the request's review-log entries carry, and the same one `permissions:ui_prompt` carried if the request reached a prompt — so a prompt and its outcome are joinable, as are two concurrent prompts for the same command.
 A request that reaches a prompt is answered by exactly one terminal event on that prompt's own bus, including when the dialog itself fails.
-It identifies a permission *request*, not a tool call: one tool call runs several gates and so raises several requests, each with its own id.
+It identifies a permission _request_, not a tool call: one tool call runs several gates and so raises several requests, each with its own id.
 Use the review log's `toolCallId` to join back to the Pi transcript.
 
 ```typescript
 pi.events.on("permissions:decision", (raw) => {
-  const event = raw as import("@gotgenes/pi-permission-system").PermissionDecisionEvent;
+  const event =
+    raw as import("@gotgenes/pi-permission-system").PermissionDecisionEvent;
   console.log(event.surface, event.result, event.resolution);
   // e.g. "bash" "allow" "user_approved_for_session"
 });
@@ -445,20 +468,47 @@ pi.events.on("permissions:decision", (raw) => {
 
 ## Ready Event
 
-The extension emits `permissions:ready` at `session_start`, right after the service is published — so a consumer reacting to it can immediately resolve `getPermissionsService()`.
-It fires once per `session_start` (including `/reload`).
+Each node emits `permissions:ready` at its own `session_start`, right after publishing its service — so a consumer reacting to it can immediately resolve that node's service.
+It emits again at that node's first `before_agent_start`, which runs after every extension's `session_start` and before any tool call, hence before any permission prompt.
+
+So the channel's contract is: **fires at least once per session, and may repeat.**
+A handler must be idempotent.
+That guarantee is what makes the ready event alone a sufficient registration site: a consumer that needs its own config before it can register no longer has to attempt registration from `session_start` as well, hoping one of the two orderings completes the pair.
+A new session generation (`/reload`, `/new`, `/resume`) starts the cycle over: one emission at `session_start`, one at the first turn that follows.
 
-The payload is intentionally empty (`Record<string, never>`): the channel is a pure readiness signal.
+Guard your registration on the disposer you stored, as the example below does.
+An unguarded handler that calls `registerAuthorizer`, `registerToolInputFormatter`, or `registerToolAccessExtractor` on every emission hits the duplicate-registration throw on the second one.
+That throw is caught by Pi's event bus and reported on stderr — your first registration stays live — but the noise is avoidable, and it was already reachable before the latch existed, since `/reload` re-runs `session_start`.
+
+The payload carries plain facts about the node that emitted it, never a live capability: the bus announces, the locator provides.
 It carries no `protocolVersion` — the broadcast contract is defined by the published types plus package semver.
 
+| Field                | Type             | Meaning                                                                                                                                                               |
+| -------------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `sessionId`          | `string \| null` | The emitting node's session id — the key for `getPermissionsService`. `null` when the host exposed no session id, in which case that node published no keyed service. |
+| `adjudicatesLocally` | `boolean`        | Whether this node's authorizer chain runs, or the node relays its asks to a serving node that runs _its_ chain over the same facts.                                   |
+
 ```typescript
-pi.events.on("permissions:ready", () => {
+let dispose: (() => void) | undefined;
+
+pi.events.on("permissions:ready", (data) => {
+  const { sessionId } = data 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"
-    );
-    const permissions = getPermissionsService();
-    // The service is published just before this fires — resolve it now.
+    const { getPermissionsService } =
+      await import("@gotgenes/pi-permission-system");
+    const permissions = getPermissionsService(sessionId);
+    // This node published before the event fired — resolve and register now.
+    dispose = permissions?.registerAuthorizer("my-link", authorize);
   })();
 });
+
+pi.on("session_shutdown", () => {
+  dispose?.();
+  dispose = undefined;
+});
 ```
+
+A registration needs no branch on `adjudicatesLocally`.
+Formatters and access extractors are read by every node's own gates, and a chain link registered on a relaying node is accepted (its disposer works) and recorded in the review log as `authorizer_link_vacant` rather than refused — so registering everywhere is the correct default.

package/docs/guides/permission-frontmatter-for-subagent-extensions.md

@@ -136,7 +136,8 @@ try {
   const { getPermissionsService } = await import(
     "@gotgenes/pi-permission-system"
   );
-  const permissions = getPermissionsService();
+  // Your own session's id; inside a handler, ctx.sessionManager.getSessionId().
+  const permissions = getPermissionsService(sessionId);
   if (permissions) {
     const result = permissions.checkPermission("bash", "git push", "Worker");
     console.log(result.state); // "allow" | "deny" | "ask"
@@ -146,7 +147,11 @@ try {
 }
 ```
 
-If `pi-permission-system` is not installed, `import()` throws; if it has not published a service yet (or has been unloaded), `getPermissionsService()` returns `undefined`.
+Query the service belonging to the session whose policy you mean.
+Each session that loads the permission system publishes its own — a subagent child's config (and cwd) may differ from its parent's, so the parent's service is not a stand-in for the child's.
+The deprecated `getRootPermissionsService()` always answers with the process root's service, which is why it is the wrong call inside a child.
+
+If `pi-permission-system` is not installed, `import()` throws; if that session has published no service yet (or has been unloaded), `getPermissionsService(sessionId)` returns `undefined`.
 Guard both cases as shown above.
 
 Prompt forwarding for headless child agents is an internal subagent-to-parent mechanism, not a public cross-extension operation — there is no service-accessor equivalent to call directly.