@gotgenes/pi-permission-system 31.1.3 → 31.1.4

package/CHANGELOG.md

@@ -5,6 +5,19 @@ 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).
 
+## [31.1.4](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v31.1.3...pi-permission-system-v31.1.4) (2026-09-11)
+
+
+### Bug Fixes
+
+* keep serving forwarded permissions when a parent-session marker is inherited ([0e1188b](https://github.com/gotgenes/pi-packages/commit/0e1188bb88b8d5b3ee14db3027baf4038644678b)), closes [#907](https://github.com/gotgenes/pi-packages/issues/907)
+* republish the serving heartbeat when the session id changes mid-session ([3fcb1a1](https://github.com/gotgenes/pi-packages/commit/3fcb1a1b040709510b774d873e08548da519b09a)), closes [#907](https://github.com/gotgenes/pi-packages/issues/907)
+* refuse a forwarding target that names the requesting session ([30ab5cc](https://github.com/gotgenes/pi-packages/commit/30ab5cc1f1418b38cc572d53b4d166d4097ce3e1)), closes [#907](https://github.com/gotgenes/pi-packages/issues/907)
+
+### Documentation
+
+* record that a UI host always serves forwarded permissions ([f62ca0b](https://github.com/gotgenes/pi-packages/commit/f62ca0b5ed920c0912691a8878375d7ce98d7770)), closes [#907](https://github.com/gotgenes/pi-packages/issues/907)
+
 ## [31.1.3](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v31.1.2...pi-permission-system-v31.1.3) (2026-09-08)
 
 

package/docs/subagent-integration.md

@@ -56,6 +56,13 @@ The variable identifies the session the child forwards its asks to, and naming a
 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.
 
+Setting the variable in the implementation's **own** root process, so that children inherit it rather than receiving it per spawn, is supported.
+A session with a UI serves its forwarded-permission inbox whatever its environment names, so a root carrying the marker keeps answering its children's asks.
+
+A value naming the reading session itself is ignored as a forwarding target, since a request filed into one's own inbox can never be answered.
+That matters when an implementation rewrites an inherited marker with the current session's id: doing so in a child destroys the only record of its real parent, and the child's asks then fail closed with an unresolved-target error.
+Guard such a rewrite on the process being a root — for example, skip it when a child marker such as `PI_SUBAGENT_CHILD` is present.
+
 ### What an implementation does not owe
 
 None of the following is an implementation's responsibility, on either process shape:

package/package.json

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

package/src/authority/forwarding-manager.ts

@@ -2,9 +2,11 @@ import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { DebugReviewLogger } from "#src/logging/session-logger";
 import type { InboxProcessor } from "./forwarded-request-server";
 import { getSessionId } from "./forwarder-context";
-import { PERMISSION_FORWARDING_POLL_INTERVAL_MS } from "./permission-forwarding";
+import {
+  normalizePermissionForwardingSessionId,
+  PERMISSION_FORWARDING_POLL_INTERVAL_MS,
+} from "./permission-forwarding";
 import type { ServingAnnouncer } from "./serving-registry";
-import type { SubagentDetector } from "./subagent-detection";
 
 /**
  * Narrow interface for the forwarding lifecycle used by `PermissionSession`.
@@ -17,8 +19,6 @@ export interface ForwardingController {
 
 /** Constructor config for {@link ForwardingManager}. */
 export interface ForwardingManagerDeps {
-  /** Single owner of subagent detection; gates whether this session may serve. */
-  detection: SubagentDetector;
   /** Drains this session's forwarded-permission inbox on each tick. */
   forwarder: InboxProcessor;
   /** Publishes that this session is draining its inbox, for forwarding children. */
@@ -39,6 +39,13 @@ export interface ForwardingManagerDeps {
  * into — and the review log records that id, so a child forwarding to a
  * *different* id is visible as a one-line diff against its
  * `forwarded_permission.request_created` entry (#719).
+ *
+ * Serving eligibility is `hasUI` and nothing else: a node with a UI has a human
+ * who can answer, so it drains its own inbox. It deliberately does **not** ask
+ * whether this process looks like a subagent — a spawner may export a
+ * parent-session marker from its own root process so the children it later
+ * launches inherit it, which made the root withdraw serving and fail every
+ * forwarded ask closed (#907).
  */
 export class ForwardingManager {
   private timer: NodeJS.Timeout | null = null;
@@ -49,13 +56,13 @@ export class ForwardingManager {
   constructor(private readonly deps: ForwardingManagerDeps) {}
 
   /**
-   * Start polling if `ctx` has UI and is not a subagent execution context.
+   * Start polling if `ctx` has UI.
    * No-op (timer stays running) if already polling — updates the stored
    * context so the next tick uses the latest session.
    * Stops any existing poll when the context does not qualify for forwarding.
    */
   start(ctx: ExtensionContext): void {
-    if (!ctx.hasUI || this.deps.detection.isSubagent(ctx)) {
+    if (!ctx.hasUI) {
       this.stop();
       return;
     }
@@ -99,30 +106,44 @@ export class ForwardingManager {
    *
    * A no-op when the id is unchanged, since `start` runs on every
    * `before_agent_start`, `input`, and `tool_call` — the announcement must not
-   * cost a log line per turn.
+   * cost a log line per turn. Also a no-op for an unreachable id: a record
+   * under the `"unknown"` sentinel names a session no child can target.
    */
   private announceServing(sessionId: string): void {
-    if (this.servingSessionId === sessionId) {
+    const served = normalizePermissionForwardingSessionId(sessionId);
+    if (served === null || this.servingSessionId === served) {
       return;
     }
     this.withdrawServing();
-    this.servingSessionId = sessionId;
-    this.deps.serving.markServing(sessionId);
+    this.servingSessionId = served;
+    this.deps.serving.markServing(served);
     this.deps.logger.review("forwarded_permission.serving_started", {
-      sessionId,
+      sessionId: served,
     });
   }
 
   /**
    * Re-announce the served session, keeping a decayable channel current.
    *
-   * Separate from {@link announceServing} because that one detects a change to
-   * write its log line, and this one deliberately writes none — four review
-   * entries a second would drown the log the announcement exists to make
-   * readable.
+   * The id is re-resolved from the live context rather than trusted from
+   * `start`, because a session id can change in place without a turn event and
+   * `ForwardedRequestServer.processInbox` reads the live one on every tick. An
+   * announcement pinned to the id captured at `start` therefore drifts away
+   * from the inbox actually being drained, stranding children on both sides of
+   * the change (#907). A change is rare and diagnosis-worthy, so it is
+   * delegated to {@link announceServing} and logged; the unchanged case never
+   * reaches it and stays silent, since four review entries a second would drown
+   * the log the announcement exists to make readable.
    */
   private refreshServing(): void {
-    if (this.servingSessionId === null) {
+    if (this.servingSessionId === null || this.context === null) {
+      return;
+    }
+    const liveSessionId = normalizePermissionForwardingSessionId(
+      getSessionId(this.context),
+    );
+    if (liveSessionId !== null && liveSessionId !== this.servingSessionId) {
+      this.announceServing(liveSessionId);
       return;
     }
     this.deps.serving.markServing(this.servingSessionId);

package/src/authority/permission-forwarding.ts

@@ -319,20 +319,32 @@ export function resolvePermissionForwardingTarget(options: {
     return null;
   }
 
+  // A candidate naming the requester itself is not a usable target: the
+  // request would land in an inbox this node is not draining, and no other node
+  // would ever answer it. A child's own copy of a subagent extension can
+  // overwrite the spawner's marker with the child's own session id, which is
+  // how such a candidate arises (#907).
+  const own = normalizePermissionForwardingSessionId(options.currentSessionId);
+  const namesAnotherSession = (candidate: string): boolean => candidate !== own;
+
   // 1. Registry — in-process subagents register parentSessionId explicitly.
   if (options.registry && options.sessionId) {
     const entry = options.registry.get(options.sessionId);
     const resolved = normalizePermissionForwardingSessionId(
       entry?.parentSessionId,
     );
-    if (resolved) return { sessionId: resolved, source: "registry" };
+    if (resolved && namesAnotherSession(resolved)) {
+      return { sessionId: resolved, source: "registry" };
+    }
   }
 
   // 2. Env vars — process-based subagent extensions.
   const env = options.env ?? process.env;
   for (const key of SUBAGENT_PARENT_SESSION_ENV_CANDIDATES) {
     const resolved = normalizePermissionForwardingSessionId(env[key]);
-    if (resolved) return { sessionId: resolved, source: "env" };
+    if (resolved && namesAnotherSession(resolved)) {
+      return { sessionId: resolved, source: "env" };
+    }
   }
   return null;
 }

package/src/authority/subagent-detection.ts

@@ -8,9 +8,16 @@ import type { SubagentSessionRegistry } from "./subagent-registry";
 /**
  * Narrow seam for the ask-path consumers: "is the current session a subagent?"
  *
- * `selectAuthorizer`/`AuthorizerSelection` and `ForwardingManager` depend on
- * this single-method view so their unit tests inject a one-field fake without
- * casts. It is the Authorizer-selection predicate the Phase 9 spine consumes.
+ * `selectAuthorizer`/`AuthorizerSelection` depends on this single-method view so
+ * its unit tests inject a one-field fake without casts. It is the
+ * Authorizer-selection predicate the Phase 9 spine consumes.
+ *
+ * It answers "is this process a child", which is **not** "should this node relay
+ * rather than decide". A UI host answers `true` here whenever its process
+ * carries a parent-session marker — a spawner may export one from the root so
+ * the children it launches inherit it. Every consumer therefore tests `hasUI`
+ * first: `selectAuthorizer` returns before reaching this predicate, and serving
+ * eligibility does not consult it at all (#907).
  */
 export interface SubagentDetector {
   isSubagent(ctx: SubagentDetectionContext): boolean;

package/src/index.ts

@@ -215,7 +215,6 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
   session = new PermissionSession(
     paths,
     new ForwardingManager({
-      detection: subagentDetection,
       forwarder: requestServer,
       serving: composeServingAnnouncers(servingRegistry, servingHeartbeats),
       logger,