@gotgenes/pi-permission-system 28.0.0 → 29.0.0

package/CHANGELOG.md

@@ -5,6 +5,31 @@ 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).
 
+## [29.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v28.0.1...pi-permission-system-v29.0.0) (2026-08-30)
+
+
+### ⚠ BREAKING CHANGES
+
+* **pi-permission-system:** `getRootPermissionsService()`, `publishRootPermissionsService()`, and `unpublishRootPermissionsService()` are removed. Resolve a node's service with `getPermissionsService(sessionId)`, taking `sessionId` from the `permissions:ready` payload (or from `ctx.sessionManager.getSessionId()` inside your own session handler). See docs/migration/0796-remove-process-root-slot.md.
+
+### Features
+
+* **pi-permission-system:** remove the deprecated process-root service accessor ([65cbbee](https://github.com/gotgenes/pi-packages/commit/65cbbee5b4d98a8f34e34b831ad4a33250735f7e)), closes [#796](https://github.com/gotgenes/pi-packages/issues/796)
+
+
+### Documentation
+
+* **pi-permission-system:** retire the process-root service slot from the docs ([649b1f0](https://github.com/gotgenes/pi-packages/commit/649b1f063a840e9a7c1f259ed03620a71624e55f)), closes [#796](https://github.com/gotgenes/pi-packages/issues/796)
+
+## [28.0.1](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v28.0.0...pi-permission-system-v28.0.1) (2026-08-30)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** carry a serving session's deny reason to the requesting agent ([b2010d7](https://github.com/gotgenes/pi-packages/commit/b2010d7bfbf766592b4ae0b98f16a612f96ff706)), closes [#844](https://github.com/gotgenes/pi-packages/issues/844)
+* **pi-permission-system:** name the rule that refused a forwarded call instead of blaming the user ([3d83641](https://github.com/gotgenes/pi-packages/commit/3d83641ad9bf6b045a86a4fb2879a7761c0aefc3)), closes [#844](https://github.com/gotgenes/pi-packages/issues/844)
+* **pi-permission-system:** tell the agent when the permission authority failed to answer ([8f70380](https://github.com/gotgenes/pi-packages/commit/8f70380005733546fa2df1d8694c50985332de19)), closes [#844](https://github.com/gotgenes/pi-packages/issues/844)
+
 ## [28.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v27.1.3...pi-permission-system-v28.0.0) (2026-08-30)
 
 

package/README.md

@@ -209,6 +209,7 @@ Approve-and-steer, edit diffs, and risk explanations → a downstream package ov
 | [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                 |
+| [docs/migration/0796-remove-process-root-slot.md](docs/migration/0796-remove-process-root-slot.md)                             | Process-root slot removed (breaking) — `getRootPermissionsService()` and its publish/unpublish pair are gone         |
 
 ## Development
 

package/dist/public.d.ts

@@ -465,15 +465,12 @@ type ToolInputFormatter = (input: Record<string, unknown>) => string | undefined
  * 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()`.
+ * The slot is a session-keyed map, 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). Every node
+ * writes under its own session id, and `getPermissionsService(sessionId)`
+ * resolves the service whose registries that node's own gates and chain read
+ * (ADR 0012 decision 2).
  *
  * Best practice: resolve per use rather than caching the reference — this
  * ensures resilience across `/reload` and load-order edge cases.
@@ -529,8 +526,7 @@ interface PermissionQuery {
 }
 /**
  * Public interface exposed to other extensions via
- * {@link getPermissionsService} (or the deprecated
- * {@link getRootPermissionsService}).
+ * {@link getPermissionsService}.
  *
  * 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
@@ -600,26 +596,6 @@ interface PermissionsService extends PermissionQuery {
      */
     registerAuthorizer(name: string, authorize: Authorizer["authorize"]): () => void;
 }
-/**
- * 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 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).
@@ -647,27 +623,14 @@ declare function publishPermissionsService(sessionId: string, service: Permissio
 declare function getPermissionsService(sessionId: string): PermissionsService | undefined;
 /**
  * Remove the `sessionId` entry, but only when it still holds `service`
- * (identity compare-and-delete, like {@link unpublishRootPermissionsService}).
+ * (identity compare-and-delete).
  *
- * Scoping the delete to the publishing instance keeps a superseded `/reload`
- * generation's late shutdown from wiping the new generation's freshly
+ * Called during `session_shutdown` to avoid stale references after the node is
+ * torn down. 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 unpublishPermissionsService(sessionId: string, service: PermissionsService): void;
-/**
- * Remove `service` from `globalThis`, but only when the current slot still
- * holds it (identity compare-and-delete).
- *
- * Called during `session_shutdown` to avoid stale references after the
- * extension is torn down. Scoping the delete to the publishing instance keeps
- * two cases correct:
- *
- * - An in-process subagent child never published the parent's service, so its
- *   shutdown is a no-op and the parent's slot survives.
- * - A superseded `/reload` generation no longer owns the slot, so its late
- *   shutdown cannot wipe the new generation's freshly published service.
- */
-declare function unpublishRootPermissionsService(service: PermissionsService): void;
 
-export { PERMISSIONS_DECISION_CHANNEL, PERMISSIONS_READY_CHANNEL, PERMISSIONS_UI_PROMPT_CHANNEL, getPermissionsService, getRootPermissionsService, publishPermissionsService, publishRootPermissionsService, unpublishPermissionsService, unpublishRootPermissionsService };
+export { PERMISSIONS_DECISION_CHANNEL, PERMISSIONS_READY_CHANNEL, PERMISSIONS_UI_PROMPT_CHANNEL, getPermissionsService, publishPermissionsService, unpublishPermissionsService };
 export type { Authorizer, AuthorizerLog, AuthorizerVerdict, ForwardedPromptContext, PermissionCheckResult, PermissionDecisionEvent, PermissionQuery, PermissionState, PermissionUiPromptEvent, PermissionUiPromptSource, PermissionsReadyEvent, PermissionsService, PromptAnnotation, PromptEvidence, PromptPayload, PromptPayloadKind, PromptPermissionDetails, PromptRequestFacts, PromptRequester, ToolInputFormatter };

package/docs/cross-extension-api.md

@@ -49,11 +49,9 @@ Each node therefore publishes its own service at `session_start`, into a `global
 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).
+That keyed map is the only service slot.
+A separate legacy slot once held the process root's service, read by a deprecated `getRootPermissionsService()`; both were removed, because in any node but the root that accessor answered the wrong question — handing an in-process child the parent's service.
+If you are upgrading from a release that had it, see [migration/0796-remove-process-root-slot.md](migration/0796-remove-process-root-slot.md); if you are upgrading from one whose `getPermissionsService()` took no argument, start with [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.
@@ -301,7 +299,7 @@ Best practice: resolve the service per use rather than caching the reference.
 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.
+It also returns `undefined` when called with no session id at all — a shape TypeScript rejects but JavaScript reaches — rather than guessing a node, 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.
 

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

@@ -149,7 +149,7 @@ try {
 
 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.
+That is why the session id is required: an accessor answering "the process root's service" would hand a child the parent's, and the one that did was removed.
 
 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.

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

@@ -22,7 +22,7 @@ Each node now publishes its own service under its own session id, and you resolv
 | Before                                 | After                                                              |
 | -------------------------------------- | ------------------------------------------------------------------ |
 | `getPermissionsService()`              | `getPermissionsService(sessionId)`                                 |
-| — (no equivalent)                      | `getRootPermissionsService()` — the old behavior, still deprecated |
+| — (no equivalent)                      | `getRootPermissionsService()` — the old behavior, deprecated       |
 | `publishPermissionsService(service)`   | `publishRootPermissionsService(service)`                           |
 | `unpublishPermissionsService(service)` | `unpublishRootPermissionsService(service)`                         |
 
@@ -89,3 +89,8 @@ Guard it with a stored dispose handle, as shown above, and release the handle on
 - 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.
+
+> [!NOTE]
+> That last bullet held only for this release.
+> The process-root slot, its accessor, and its publish/unpublish pair were removed in a later major — see [0796-remove-process-root-slot.md](0796-remove-process-root-slot.md).
+> If you are migrating from a pre-27.0.0 release, work through this guide first and that one second.

package/docs/migration/0796-remove-process-root-slot.md

@@ -0,0 +1,68 @@
+# Migration guide: the process-root service slot is removed
+
+Starting with the release that closes #796, the deprecated process-root service accessor and the `globalThis` slot behind it no longer exist.
+
+This is a **breaking change**.
+If your extension does not import `getRootPermissionsService`, `publishRootPermissionsService`, or `unpublishRootPermissionsService` from `@gotgenes/pi-permission-system`, nothing here affects you.
+
+## What was removed
+
+| Removed                                            | Replacement                                      |
+| -------------------------------------------------- | ------------------------------------------------ |
+| `getRootPermissionsService()`                      | `getPermissionsService(sessionId)`               |
+| `publishRootPermissionsService(service)`           | — (internal; a node publishes its own service)   |
+| `unpublishRootPermissionsService(service)`         | — (internal; a node unpublishes its own service) |
+| `PI_PERMISSION_SYSTEM_DEP0001` deprecation warning | — (the deprecated path is gone)                  |
+
+The `Symbol.for("@gotgenes/pi-permission-system:service")` slot is no longer written by any node.
+`Symbol.for("@gotgenes/pi-permission-system:session-services")` — the session-keyed map — is the only service slot.
+
+## What to change
+
+Resolve the service of the node whose behavior you mean to affect, keyed by its session id.
+The id arrives as a field on the `permissions:ready` payload; inside your own session handler, `ctx.sessionManager.getSessionId()` is the same value.
+
+```typescript
+import {
+  getPermissionsService,
+  PERMISSIONS_READY_CHANNEL,
+  type PermissionsReadyEvent,
+} from "@gotgenes/pi-permission-system";
+
+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;
+  dispose = getPermissionsService(sessionId)?.registerAuthorizer(
+    "my-link",
+    authorize,
+  );
+});
+```
+
+If you are still on a zero-argument `getPermissionsService()` from a release before 27.0.0, migrate through [0794-keyed-service-locator.md](0794-keyed-service-locator.md) first — that release is where the accessor's signature changed.
+
+## Why the deprecation window closed
+
+[ADR 0012](https://github.com/gotgenes/pi-packages/blob/main/packages/pi-permission-system/docs/decisions/0012-cross-node-extension-contract.md) decision 7 deferred the removal until downstream consumers had migrated.
+`pi-permission-model-judge` 2.0.0 — the named migration case — registers through the keyed locator and floors its peer range at `>=27.0.0`, and no other known consumer reads the root slot.
+
+The removal is also narrower than a deprecation window's usual population suggests.
+`getRootPermissionsService` did not exist before 27.0.0: it is the name that release gave the old behavior when it reclaimed `getPermissionsService` for the keyed locator.
+So no consumer predating the deprecation can be calling it — every caller adopted the name after it was already marked deprecated, in preference to the keyed locator this guide's predecessor recommends.
+
+## What you will see if you miss a call site
+
+The export is gone, so TypeScript reports `TS2724` at your import and plain JavaScript throws `TypeError: getRootPermissionsService is not a function`.
+
+Calling `getPermissionsService()` with **no** argument still answers `undefined` and emits a once-guarded Node warning under code `PI_PERMISSION_SYSTEM_WARN0001`, naming the keyed call and the ready payload.
+That warning is deliberately not a `DeprecationWarning`, so `--no-deprecation` does not silence it: a registration that never landed is not something to hide.
+
+## What has not changed
+
+- The `PermissionsService` interface — the five methods and their signatures are untouched.
+- The keyed accessors `getPermissionsService` / `publishPermissionsService` / `unpublishPermissionsService`.
+- The `permissions:ready`, `permissions:ui_prompt`, and `permissions:decision` payload shapes and cadence.
+- Node-locality: a registration is still read only by the node it was made in, and an in-process subagent child still gets its own service.

package/package.json

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

package/src/authority/forwarded-request-server.ts

@@ -5,7 +5,10 @@ import {
   type ForwarderContext,
   getSessionId,
 } from "#src/authority/forwarder-context";
-import type { PermissionPromptDecision } from "#src/authority/permission-dialog";
+import {
+  createDeniedPermissionDecision,
+  type PermissionPromptDecision,
+} from "#src/authority/permission-dialog";
 import {
   type ForwardedAccessFacts,
   type ForwardedAccessIntent,
@@ -456,9 +459,12 @@ export class ForwardedRequestServer implements InboxProcessor {
           : "forwarded_permission.auto_denied",
         { ...logDetails, decidedBy },
       );
+      // A deny-with-reason rule's text is the operator's own explanation, and
+      // the requesting session relays it to its agent — so it travels with the
+      // verdict rather than stopping at the node that holds the config (#844).
       return approved
         ? { approved: true, state: "approved", decidedBy }
-        : { approved: false, state: "denied", decidedBy };
+        : { ...createDeniedPermissionDecision(check.reason), decidedBy };
     }
 
     this.logger.review("forwarded_permission.prompted", logDetails);

package/src/authority/subagent-detection.ts

@@ -1,5 +1,4 @@
 import {
-  isRegisteredSubagentChild,
   isSubagentExecutionContext,
   type SubagentDetectionContext,
 } from "#src/authority/subagent-context";
@@ -17,17 +16,6 @@ export interface SubagentDetector {
   isSubagent(ctx: SubagentDetectionContext): boolean;
 }
 
-/**
- * Narrow seam for the service-publication guard (#302): "is the current
- * session a registered in-process child?"
- *
- * `PermissionServiceLifecycle` depends on this single-method view so a
- * registered child never publishes over its parent's process-global slot.
- */
-export interface RegisteredChildDetector {
-  isRegisteredChild(ctx: SubagentDetectionContext): boolean;
-}
-
 /** Composition-root inputs for {@link SubagentDetection}. */
 export interface SubagentDetectionDeps {
   subagentSessionsDir: string;
@@ -44,9 +32,7 @@ export interface SubagentDetectionDeps {
  * individually. Delegates to the pure detection functions in
  * {@link ./subagent-context}, holding only the deps.
  */
-export class SubagentDetection
-  implements SubagentDetector, RegisteredChildDetector
-{
+export class SubagentDetection implements SubagentDetector {
   constructor(private readonly deps: SubagentDetectionDeps) {}
 
   isSubagent(ctx: SubagentDetectionContext): boolean {
@@ -57,10 +43,4 @@ export class SubagentDetection
       this.deps.registry,
     );
   }
-
-  isRegisteredChild(ctx: SubagentDetectionContext): boolean {
-    return this.deps.registry
-      ? isRegisteredSubagentChild(ctx, this.deps.registry)
-      : false;
-  }
 }

package/src/index.ts

@@ -266,15 +266,13 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
   );
 
   // PermissionServiceLifecycle owns the process-global service publication:
-  // activate() publishes this node's service under its own session id (and to
-  // the legacy root slot unless this is a registered subagent child — see
-  // #302), then announces the node's session id and chain role on the ready
-  // channel; teardown() unsubscribes all session listeners and unpublishes.
+  // activate() publishes this node's service under its own session id, then
+  // announces the node's session id and chain role on the ready channel;
+  // teardown() unsubscribes all session listeners and unpublishes.
   // Deferred to session_start because both facts come from ctx, unavailable at
   // factory-init time.
   const serviceLifecycle = new PermissionServiceLifecycle(
     permissionsService,
-    subagentDetection,
     authorizerSelection,
     pi.events,
     [unsubSubagentLifecycle],

package/src/presentation/agent-renderer.ts

@@ -14,6 +14,7 @@ import {
   findEvidence,
   type PromptPayload,
 } from "#src/presentation/prompt-payload";
+import type { BashCommandContext } from "#src/types";
 
 /**
  * The agent-facing render of a refused permission ask (ADR 0011 §7).
@@ -68,6 +69,9 @@ export function renderRefusal(
   budget: AgentRenderBudget = DEFAULT_RENDER_BUDGET,
 ): string {
   const decider = effectiveDecider(decidedBy);
+  // The hop the unwrap discarded: *where* the decision was made. Kept as a
+  // bare fact rather than the responder's identity, which stays undisclosed.
+  const decidedElsewhere = decidedBy.kind === "forwarded";
   switch (decider.kind) {
     case "authorizer":
       return renderAuthorizerDenial(
@@ -78,14 +82,26 @@ export function renderRefusal(
       );
     case "unavailable":
       return renderUnavailableDenial(payload, denialReason, budget);
-    // A `rule` here is a rule in the *serving* session, whose pattern and
-    // origin are not on this payload — `matchedPattern` is the pattern that
-    // raised this session's own ask, so naming a rule would name the wrong
-    // one. That render, and the `gate_error` one beside it, are #844. The
-    // remaining kinds never refuse: they only ever allow.
-    case "user":
     case "rule":
+      return renderEscalatedPolicyDenial(
+        payload,
+        { pattern: decider.pattern, decidedElsewhere },
+        denialReason,
+        budget,
+      );
     case "gate_error":
+      return renderGateErrorDenial(payload, {
+        reason: decider.reason,
+        decidedElsewhere,
+      });
+    // Three different reasons share this arm. `user` is the render's true
+    // subject: a human refused, and the sentence says so. The three below it
+    // never refuse at all — a session grant, an infrastructure read, and yolo
+    // only ever allow — so they are unreachable here and listed only to keep
+    // the switch exhaustive. A `forwarded` reaching this far named no inner
+    // decider (an older responder), so the hop is all that is known, and the
+    // user render is the fail-soft answer rather than the accurate one.
+    case "user":
     case "session_approval":
     case "infrastructure_read":
     case "yolo":
@@ -101,7 +117,7 @@ export function renderPolicyDenial(
   budget: AgentRenderBudget = DEFAULT_RENDER_BUDGET,
 ): string {
   return tagged(
-    `Denied by policy: ${identification(payload, budget, "")}${boundaryClause(payload)}${provenanceClause(payload)}.`,
+    `Denied by policy: ${identification(payload, budget, "", askRuleClause(payload))}${boundaryClause(payload)}${provenanceClause(payload)}.`,
     ruleReason,
   );
 }
@@ -113,7 +129,7 @@ export function renderUserDenial(
   budget: AgentRenderBudget = DEFAULT_RENDER_BUDGET,
 ): string {
   return tagged(
-    `The user denied this ${identification(payload, budget, "call")}${boundaryClause(payload)}${provenanceClause(payload)}.`,
+    `The user denied this ${identification(payload, budget, "call", askRuleClause(payload))}${boundaryClause(payload)}${provenanceClause(payload)}.`,
     denialReason,
   );
 }
@@ -133,11 +149,76 @@ export function renderAuthorizerDenial(
   budget: AgentRenderBudget = DEFAULT_RENDER_BUDGET,
 ): string {
   return tagged(
-    `The '${linkName}' authorizer denied this ${identification(payload, budget, "call")}${boundaryClause(payload)}${provenanceClause(payload)}.`,
+    `The '${linkName}' authorizer denied this ${identification(payload, budget, "call", askRuleClause(payload))}${boundaryClause(payload)}${provenanceClause(payload)}.`,
+    denialReason,
+  );
+}
+
+/** The rule that refused an escalated ask, and where it sat. */
+export interface EscalatedRule {
+  /** The pattern the deciding node's rule matched; `null` when none was recorded. */
+  readonly pattern: string | null;
+  /** Whether that node was reached through a forwarding hop. */
+  readonly decidedElsewhere: boolean;
+}
+
+/**
+ * The agent-facing render of a policy denial an escalation came back with.
+ *
+ * Distinct from {@link renderPolicyDenial} in which rule it names. That one
+ * renders the rule on this session's payload, which is the rule that decided
+ * when recorded authority answered locally. Here the ask was escalated, so the
+ * payload's rule is the one that raised the *ask* and the rule that *denied*
+ * lives on the decision — naming the payload's would name the wrong rule while
+ * looking correct (ADR 0011 §10, #844).
+ */
+export function renderEscalatedPolicyDenial(
+  payload: PromptPayload,
+  rule: EscalatedRule,
+  denialReason: string | null,
+  budget: AgentRenderBudget = DEFAULT_RENDER_BUDGET,
+): string {
+  const decidedRule = ruleClause(rule.pattern, payload.request.commandContext);
+  return tagged(
+    `A policy rule${servingClause(rule.decidedElsewhere)} denied this ${identification(payload, budget, "call", decidedRule)}${boundaryClause(payload)}${provenanceClause(payload)}.`,
     denialReason,
   );
 }
 
+/** The escalation failure that blocked an ask fail-closed, and where it happened. */
+export interface GateFailure {
+  /** The error text stamped on the decision, which carries the detail here. */
+  readonly reason: string;
+  /** Whether the failing authority was reached through a forwarding hop. */
+  readonly decidedElsewhere: boolean;
+}
+
+/**
+ * The agent-facing render of an escalation that threw rather than ruling.
+ *
+ * Nobody denied this call — the authority that would have answered broke, and
+ * the boundary blocked rather than allowed. Saying so is what distinguishes it
+ * from a verdict the agent should respect: a failure is worth surfacing to the
+ * operator, where a denial is worth working around (#844).
+ *
+ * The reason comes from the decision's own stamp rather than a denial reason,
+ * because that is the field the failing site writes and the field the review
+ * log records — a second source would be a second story about one failure.
+ *
+ * Like {@link renderUnavailableDenial}, it omits the escaped boundary: the
+ * ask never reached a rule, so no retry shape would change the outcome.
+ */
+export function renderGateErrorDenial(
+  payload: PromptPayload,
+  failure: GateFailure,
+  budget: AgentRenderBudget = DEFAULT_RENDER_BUDGET,
+): string {
+  return tagged(
+    `The permission authority${servingClause(failure.decidedElsewhere)} failed to answer this ${identification(payload, budget, "call", askRuleClause(payload))}, so it was blocked (fail-closed).`,
+    failure.reason,
+  );
+}
+
 /** The agent-facing render when no live authority could answer the ask. */
 export function renderUnavailableDenial(
   payload: PromptPayload,
@@ -145,13 +226,24 @@ export function renderUnavailableDenial(
   budget: AgentRenderBudget = DEFAULT_RENDER_BUDGET,
 ): string {
   return tagged(
-    `This ${identification(payload, budget, "call")} requires approval, but no interactive UI is available.`,
+    `This ${identification(payload, budget, "call", askRuleClause(payload))} requires approval, but no interactive UI is available.`,
     denialReason,
   );
 }
 
 // ── Sentence assembly ──────────────────────────────────────────────────────
 
+/**
+ * Where the deciding authority sat, when it was not this session.
+ *
+ * Says that another session decided and never which one: the responder's
+ * identity answers a question the requesting agent cannot act on, and §6 keeps
+ * it off the render (ADR 0011 §10).
+ */
+function servingClause(decidedElsewhere: boolean): string {
+  return decidedElsewhere ? " in the session serving this request" : "";
+}
+
 function tagged(sentence: string, reason: string | null): string {
   return `${EXTENSION_TAG} ${sentence}${reasonClause(reason)}`;
 }
@@ -164,11 +256,16 @@ function tagged(sentence: string, reason: string | null): string {
  * `callWord` is the noun the verdict needs after the surface — a user or
  * unavailable verdict refuses a *call*, while a policy deny refuses the
  * surface itself.
+ *
+ * `ruleText` is supplied rather than read off the payload, because an escalated
+ * refusal names the rule that *decided* it, which is not always this session's
+ * own (#844).
  */
 function identification(
   payload: PromptPayload,
   budget: AgentRenderBudget,
   callWord: string,
+  ruleText: string,
 ): string {
   return [
     `'${payload.request.surface}'`,
@@ -177,7 +274,7 @@ function identification(
     toolClause(payload),
     agentClause(payload),
     flaggedClause(payload, budget),
-    ruleClause(payload),
+    ruleText,
   ]
     .filter((clause) => clause !== "")
     .join(" ");
@@ -244,12 +341,29 @@ function resolvedAlias(payload: PromptPayload, element: string): string {
   return resolved ? ` (resolves to '${resolved}')` : "";
 }
 
-/** The rule that fired, with the nested context that makes it intelligible. */
-function ruleClause(payload: PromptPayload): string {
-  const { matchedPattern, commandContext } = payload.request;
+/** The rule that raised this session's own ask. */
+function askRuleClause(payload: PromptPayload): string {
+  return ruleClause(
+    payload.request.matchedPattern,
+    payload.request.commandContext,
+  );
+}
+
+/**
+ * The rule that fired, with the nested context that makes it intelligible.
+ *
+ * The pattern is a parameter rather than a payload read: an escalated refusal
+ * renders the rule that decided it, which for a forwarded ask lives on the
+ * response's decider and never on this session's payload. The command context
+ * is a fact about the call either way, so it always comes from the payload.
+ */
+function ruleClause(
+  pattern: string | null,
+  commandContext: BashCommandContext | null,
+): string {
   const parts: string[] = [];
-  if (matchedPattern !== null) {
-    parts.push(`rule '${matchedPattern}'`);
+  if (pattern !== null) {
+    parts.push(`rule '${pattern}'`);
   }
   const context = describeBashCommandContext(commandContext);
   if (context !== undefined) {

package/src/service-lifecycle.ts

@@ -1,13 +1,10 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { AdjudicationRole } from "./authority/authorizer-selection";
-import type { RegisteredChildDetector } from "./authority/subagent-detection";
 import { emitReadyEvent, type PermissionEventBus } from "./permission-events";
 import {
   type PermissionsService,
   publishPermissionsService,
-  publishRootPermissionsService,
   unpublishPermissionsService,
-  unpublishRootPermissionsService,
 } from "./service";
 import { readSessionId } from "./session-identity";
 
@@ -35,18 +32,16 @@ export interface ReadyAnnouncer {
  *
  * - `activate` publishes the service under this node's own session id, so a
  *   sibling extension loaded into this node registers into the registries this
- *   node's gates and chain read. It additionally publishes to the legacy
- *   process-root slot unless this is a registered subagent child, which must
- *   not clobber its parent's slot (#302). Then it announces both facts a
- *   consumer needs — the session id and the chain role — on the ready channel,
- *   and re-arms the latch so the turn about to start announces once more.
+ *   node's gates and chain read. Then it announces both facts a consumer needs
+ *   — the session id and the chain role — on the ready channel, and re-arms the
+ *   latch so the turn about to start announces once more.
  * - `announceReady` is that second announcement: it fires at most once per
  *   activation cycle, so `permissions:ready` reaches a consumer whose own
  *   `session_start` ran after this node's (ADR 0012 decision 3). The channel's
  *   contract is therefore "at least once per session, and may repeat" —
  *   handlers must be idempotent.
  * - `teardown` runs all session-scoped subscription cleanups in order, then
- *   unpublishes from both slots. Each unpublish is identity-scoped, so a
+ *   unpublishes this node's entry. The unpublish is identity-scoped, so a
  *   superseded `/reload` generation cannot evict the fresh one.
  */
 export class PermissionServiceLifecycle
@@ -60,7 +55,6 @@ export class PermissionServiceLifecycle
 
   constructor(
     private readonly service: PermissionsService,
-    private readonly detection: RegisteredChildDetector,
     private readonly role: AdjudicationRole,
     private readonly events: PermissionEventBus,
     private readonly subscriptions: readonly (() => void)[],
@@ -75,9 +69,6 @@ export class PermissionServiceLifecycle
       publishPermissionsService(sessionId, this.service);
       this.publishedSessionId = sessionId;
     }
-    if (!this.detection.isRegisteredChild(ctx)) {
-      publishRootPermissionsService(this.service);
-    }
     this.emitReady(ctx);
   }
 
@@ -97,7 +88,6 @@ export class PermissionServiceLifecycle
       unpublishPermissionsService(this.publishedSessionId, this.service);
       this.publishedSessionId = null;
     }
-    unpublishRootPermissionsService(this.service);
   }
 
   /**

package/src/service.ts

@@ -7,15 +7,12 @@
  * 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()`.
+ * The slot is a session-keyed map, 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). Every node
+ * writes under its own session id, and `getPermissionsService(sessionId)`
+ * resolves the service whose registries that node's own gates and chain read
+ * (ADR 0012 decision 2).
  *
  * Best practice: resolve per use rather than caching the reference — this
  * ensures resilience across `/reload` and load-order edge cases.
@@ -72,9 +69,6 @@ export type {
 } from "./presentation/prompt-payload";
 export type { PermissionCheckResult, PermissionState, ToolInputFormatter };
 
-/** Process-global key for the legacy (process-root) service slot. */
-const SERVICE_KEY = Symbol.for("@gotgenes/pi-permission-system:service");
-
 /** Process-global key for the session-keyed service map (ADR 0012 decision 2). */
 const SESSION_SERVICES_KEY = Symbol.for(
   "@gotgenes/pi-permission-system:session-services",
@@ -120,8 +114,7 @@ export interface PermissionQuery {
 
 /**
  * Public interface exposed to other extensions via
- * {@link getPermissionsService} (or the deprecated
- * {@link getRootPermissionsService}).
+ * {@link getPermissionsService}.
  *
  * 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
@@ -203,77 +196,13 @@ export interface PermissionsService extends PermissionQuery {
   ): () => void;
 }
 
-/**
- * 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.
- */
-export function publishRootPermissionsService(
-  service: PermissionsService,
-): void {
-  (globalThis as Record<symbol, unknown>)[SERVICE_KEY] = service;
-}
-
-/**
- * Warned at most once per module copy, so a consumer hears it on its first
- * deprecated call and never again. Under jiti isolation each consumer
- * extension holds its own copy, so each hears it for its own call site.
- */
-let warnedDeprecatedAccessor = false;
-
-const DEPRECATED_ACCESSOR_WARNING =
-  "getRootPermissionsService() is deprecated: it answers with the process root's " +
-  "service, which is the wrong node in every node but the root — inside an " +
-  "in-process subagent child it hands back the parent's service, so a " +
-  "registration lands where the child's gates never read it and a policy " +
-  "query answers against the parent's config. Use " +
-  "getPermissionsService(sessionId) with the sessionId from the " +
-  "permissions:ready payload. See " +
-  "https://github.com/gotgenes/pi-packages/blob/main/packages/pi-permission-system/docs/cross-extension-api.md";
-
-/**
- * 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).
- */
-export function getRootPermissionsService(): PermissionsService | undefined {
-  if (!warnedDeprecatedAccessor) {
-    warnedDeprecatedAccessor = true;
-    process.emitWarning(DEPRECATED_ACCESSOR_WARNING, {
-      type: "DeprecationWarning",
-      code: "PI_PERMISSION_SYSTEM_DEP0001",
-    });
-  }
-  return readRootService();
-}
-
-/**
- * The undeprecated read of the root slot, for this package's own lifecycle.
- *
- * `unpublishRootPermissionsService` must compare identities without warning the
- * host about a call the host did not make.
- */
-function readRootService(): PermissionsService | undefined {
-  return (globalThis as Record<symbol, unknown>)[SERVICE_KEY] as
-    | PermissionsService
-    | undefined;
-}
-
 /**
  * The process-global map of session id → that node's service, created on first
  * use.
  *
- * Backed by `globalThis` + `Symbol.for()` for the same reason the single slot
- * above is: each session's `ResourceLoader` builds its own jiti instance, so a
- * parent and its in-process child share no module state — only process globals.
+ * Backed by `globalThis` + `Symbol.for()` because each session's
+ * `ResourceLoader` builds its own jiti instance, so a parent and its in-process
+ * child share no module state — only process globals.
  */
 function sessionServices(): Map<string, PermissionsService> {
   const store = globalThis as Record<symbol, unknown>;
@@ -331,9 +260,7 @@ export function getPermissionsService(
 const MISSING_SESSION_ID_WARNING =
   "getPermissionsService() was called without a session id and answered " +
   "undefined. It resolves the service of one node, so it needs the sessionId " +
-  "from the permissions:ready payload: getPermissionsService(sessionId). To " +
-  "read the process root's service — what the zero-arg call used to do — use " +
-  "the deprecated getRootPermissionsService(). See " +
+  "from the permissions:ready payload: getPermissionsService(sessionId). See " +
   "https://github.com/gotgenes/pi-packages/blob/main/packages/pi-permission-system/docs/cross-extension-api.md";
 
 /**
@@ -358,10 +285,11 @@ function warnMissingSessionId(): void {
 
 /**
  * Remove the `sessionId` entry, but only when it still holds `service`
- * (identity compare-and-delete, like {@link unpublishRootPermissionsService}).
+ * (identity compare-and-delete).
  *
- * Scoping the delete to the publishing instance keeps a superseded `/reload`
- * generation's late shutdown from wiping the new generation's freshly
+ * Called during `session_shutdown` to avoid stale references after the node is
+ * torn down. Scoping the delete to the publishing instance keeps a superseded
+ * `/reload` generation's late shutdown from wiping the new generation's freshly
  * published service.
  */
 export function unpublishPermissionsService(
@@ -373,26 +301,3 @@ export function unpublishPermissionsService(
     services.delete(sessionId);
   }
 }
-
-/**
- * Remove `service` from `globalThis`, but only when the current slot still
- * holds it (identity compare-and-delete).
- *
- * Called during `session_shutdown` to avoid stale references after the
- * extension is torn down. Scoping the delete to the publishing instance keeps
- * two cases correct:
- *
- * - An in-process subagent child never published the parent's service, so its
- *   shutdown is a no-op and the parent's slot survives.
- * - A superseded `/reload` generation no longer owns the slot, so its late
- *   shutdown cannot wipe the new generation's freshly published service.
- */
-export function unpublishRootPermissionsService(
-  service: PermissionsService,
-): void {
-  if (readRootService() !== service) {
-    return;
-  }
-  // eslint-disable-next-line @typescript-eslint/no-dynamic-delete -- Symbol-keyed global property; Map.delete() is not applicable
-  delete (globalThis as Record<symbol, unknown>)[SERVICE_KEY];
-}