@gotgenes/pi-permission-system 31.1.4 → 32.0.0

package/CHANGELOG.md

@@ -5,6 +5,18 @@ 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).
 
+## [32.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v31.1.4...pi-permission-system-v32.0.0) (2026-09-11)
+
+
+### Features
+
+* **pi-permission-system:** **breaking:** prompt in the parent session for a subagent that has its own UI ([24b56a2](https://github.com/gotgenes/pi-packages/commit/24b56a2181df3db8b17e45b1acefd5a53fe2eddf)), closes [#907](https://github.com/gotgenes/pi-packages/issues/907), closes [#909](https://github.com/gotgenes/pi-packages/issues/909)
+* **pi-permission-system:** record when a session starts or stops relaying its asks ([7d1e2bb](https://github.com/gotgenes/pi-packages/commit/7d1e2bbe69d59360a66a27d3277d41aedecbefb5)), closes [#909](https://github.com/gotgenes/pi-packages/issues/909)
+
+### Documentation
+
+* **pi-permission-system:** document relaying from a session that has its own UI ([0250d68](https://github.com/gotgenes/pi-packages/commit/0250d68bb3a89e32782836ed1b6a17d4e52d25e8)), closes [#909](https://github.com/gotgenes/pi-packages/issues/909)
+
 ## [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)
 
 

package/docs/subagent-integration.md

@@ -63,6 +63,19 @@ A value naming the reading session itself is ignored as a forwarding target, sin
 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.
 
+#### Children that keep a UI of their own
+
+An implementation may spawn each child as a full interactive session — a visible pane per agent, for observability and direct inspection — while keeping permission authority with the human at the lead session.
+A child like that forwards its asks to the session the variable names, rather than opening its own dialog, for as long as that session is draining its forwarded-permission inbox.
+It is the declared target that decides this, so an implementation opts in by naming a parent, and opts out by not naming one; nothing else is required of it.
+
+The liveness condition is what keeps a visible child usable.
+A child whose named parent has exited, been killed, or stopped polling opens its own dialog instead of refusing the tool call, and the decision is remade on every turn: a pane whose lead exits mid-run returns to prompting locally at its next turn, and one whose lead comes back starts forwarding again.
+Only an ask already in flight when the parent disappears is refused, with the usual approval-unavailable reason.
+
+A session that relays still serves its own inbox, so a `lead → agent → agent` tree relays through the middle hop.
+What it does not do is run its own authorizer chain: live authority converges at the node that decides, which is the serving one ([ADR 0007] §7).
+
 ### What an implementation does not owe
 
 None of the following is an implementation's responsibility, on either process shape:
@@ -132,7 +145,7 @@ When `@gotgenes/pi-permission-system` is not installed, an implementation emits
 
 ## Permission Forwarding
 
-When a delegated or routed subagent runs without direct UI access, `ask` permissions can still be enforced by forwarding the confirmation request through Pi session directories.
+When a delegated or routed subagent cannot decide an `ask` where it runs — because it has no UI of its own, or because it names a parent session that is answering for it — the confirmation request is forwarded through Pi session directories instead.
 The main interactive session polls for forwarded requests, shows the confirmation prompt, writes the response, and the subagent resumes once that decision is available.
 A parent `allow`/`deny` rule governs a child's escalation directly (the serving node resolves it as recorded authority before prompting), and a "whole session" grant recorded on the parent auto-approves later forwards of the same pattern.
 

package/package.json

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

package/src/authority/approval-escalator.ts

@@ -173,10 +173,11 @@ function forwardableRequestId(requesterRequestId: string): string {
  * Owns the escalation-up role of the forwarded-permission behavior: builds
  * and persists a request file, then polls for the parent session's
  * response. `ctx` is bound once at construction — `selectAuthorizer` only
- * constructs a `ParentAuthorizer` for a context it has already confirmed has
- * no UI and is a subagent, so `authorize` never re-derives that dispatch
- * (formerly `ApprovalEscalator.requestApproval`'s `hasUI` / `!isSubagent`
- * arms, both dead once every caller routes through `selectAuthorizer`).
+ * constructs a `ParentAuthorizer` for a context it has already established is a
+ * child, whether that child has a UI of its own (#909) or not, so `authorize`
+ * never re-derives that dispatch (formerly `ApprovalEscalator.requestApproval`'s
+ * `hasUI` / `!isSubagent` arms, both dead once every caller routes through
+ * `selectAuthorizer`).
  */
 export class ParentAuthorizer implements TerminalAuthorizer {
   private readonly forwardingDir: string;
@@ -221,10 +222,9 @@ export class ParentAuthorizer implements TerminalAuthorizer {
   ): Promise<PermissionPromptDecision> {
     const requesterSessionId = getSessionId(ctx);
     const target = resolvePermissionForwardingTarget({
-      hasUI: ctx.hasUI,
-      // Invariant: selectAuthorizer only selects ParentAuthorizer for a
-      // no-UI subagent context, so this is always true — no detection dep
-      // needed to re-derive it here.
+      // Invariant: selectAuthorizer only selects ParentAuthorizer for a context
+      // it has already established is a child — no detection dep needed to
+      // re-derive it here.
       isSubagent: true,
       currentSessionId: requesterSessionId,
       env: process.env,

package/src/authority/authorizer-selection.ts

@@ -10,6 +10,7 @@ import { composeAuthorizerChain } from "./authorizer-chain";
 import type { AuthorizerLookup } from "./authorizer-registry";
 import { encloseInDelegationEnvelope } from "./delegation-envelope";
 import type { PermissionPromptDecision } from "./permission-dialog";
+import type { PermissionForwardingTarget } from "./permission-forwarding";
 import type {
   PermissionPrompterApi,
   PromptPermissionDetails,
@@ -48,9 +49,13 @@ export interface AskEscalator {
  * so a sibling extension learns it without knowing what a subagent is) and by
  * the registration observer (which records a link registered where no chain
  * runs). Both depend on this single-method view rather than the selection
- * itself, and neither may re-derive the role from `detection.isSubagent(ctx)`:
- * `selectAuthorizer` tests `hasUI` first, so a subagent with its own UI
- * adjudicates locally.
+ * itself, and neither may re-derive the role from `ctx.hasUI` or
+ * `detection.isSubagent(ctx)`: a node with a UI relays when it names another
+ * session that is draining its inbox, and decides locally otherwise (#909).
+ *
+ * Because the selection is remade on every activation, the answer can change
+ * within one session — a node stops relaying as soon as its declared parent
+ * stops serving.
  */
 export interface AdjudicationRole {
   adjudicatesLocally(): boolean;
@@ -72,6 +77,7 @@ export class AuthorizerSelection
   implements AskEscalator, AuthorizerSelectionLifecycle, AdjudicationRole
 {
   private authority: SelectedAuthority | null = null;
+  private relayTarget: PermissionForwardingTarget | null = null;
 
   constructor(
     private readonly deps: AuthorizerSelectionDeps & {
@@ -92,7 +98,39 @@ export class AuthorizerSelection
    * activation, so link resolution is deferred to the session's first ask.
    */
   activate(ctx: ExtensionContext): void {
-    this.authority = selectAuthorizer(ctx, this.deps);
+    const authority = selectAuthorizer(ctx, this.deps);
+    this.recordRelayTransition(authority.relayTarget ?? null);
+    this.authority = authority;
+  }
+
+  /**
+   * Record that this node started, stopped, or redirected its relaying.
+   *
+   * `activate` runs on every turn event, so only a change is worth a line: the
+   * pair reads beside the serving node's own
+   * `forwarded_permission.serving_started`/`serving_stopped`, which is what
+   * makes a misdirected relay a one-line diff across the two sessions. A node
+   * that never relays writes nothing at all.
+   */
+  private recordRelayTransition(
+    target: PermissionForwardingTarget | null,
+  ): void {
+    const previous = this.relayTarget;
+    if (previous?.sessionId === target?.sessionId) {
+      return;
+    }
+    this.relayTarget = target;
+    if (previous !== null) {
+      this.deps.logger.review("forwarded_permission.relay_stopped", {
+        targetSessionId: previous.sessionId,
+      });
+    }
+    if (target !== null) {
+      this.deps.logger.review("forwarded_permission.relay_started", {
+        targetSessionId: target.sessionId,
+        channel: target.source,
+      });
+    }
   }
 
   /**
@@ -181,6 +219,7 @@ export class AuthorizerSelection
 
   /** Clear the stored selection. */
   deactivate(): void {
+    this.recordRelayTransition(null);
     this.authority = null;
   }
 

package/src/authority/authorizer.ts

@@ -4,9 +4,12 @@ import type { AuthorizerLog, PermissionQuery } from "#src/service";
 import type { PermissionEventBus } from "#src/service/permission-events";
 import { ParentAuthorizer } from "./approval-escalator";
 import { DenyingAuthorizer } from "./denying-authorizer";
+import { getSessionId } from "./forwarder-context";
 import type { TargetServingLookup } from "./forwarding-liveness";
 import { LocalUserAuthorizer } from "./local-user-authorizer";
 import type { PermissionPromptDecision } from "./permission-dialog";
+import type { PermissionForwardingTarget } from "./permission-forwarding";
+import { resolvePermissionForwardingTarget } from "./permission-forwarding";
 import type {
   PromptPreferences,
   requestPermissionDecision,
@@ -77,9 +80,10 @@ export interface TerminalAuthorizer {
  * whether this node adjudicates them with its own chain.
  *
  * The chain role is the selection's product, not a discriminator a consumer
- * re-derives: `selectAuthorizer` tests `hasUI` before `isSubagent`, so a
- * subagent that has its own UI decides locally, and re-deriving the role from
- * `detection.isSubagent(ctx)` alone would get that case wrong.
+ * re-derives: a node with a UI decides locally unless it names another session
+ * that is draining its forwarded-permission inbox (#909), so re-deriving the
+ * role from `ctx.hasUI` or `detection.isSubagent(ctx)` alone would get that
+ * case wrong in opposite directions.
  */
 export interface SelectedAuthority {
   /** The terminal that decides this node's asks, or relays them upward. */
@@ -92,6 +96,12 @@ export interface SelectedAuthority {
    * twice.
    */
   readonly adjudicatesLocally: boolean;
+  /**
+   * The target this selection itself verified as live, for the relay-transition
+   * record. Absent on the headless relay arm, where the target is resolved per
+   * ask by `ParentAuthorizer` rather than at selection.
+   */
+  readonly relayTarget?: PermissionForwardingTarget;
 }
 
 /** Construction inputs for {@link selectAuthorizer}. */
@@ -117,40 +127,84 @@ export interface AuthorizerSelectionDeps {
 
 /**
  * Select the live authority for the current context: the single owner of the
- * three-way `hasUI` / `isSubagent` / deny dispatch, and of the chain role that
- * dispatch implies.
+ * three-way local / relay / deny dispatch, and of the chain role that dispatch
+ * implies.
  *
- * Evaluated once per session activation (`AuthorizerSelection.activate`),
- * replacing the re-derivation of the same predicates across
- * `PromptingGateway`, `PermissionPrompter`, and `ApprovalEscalator`.
+ * Evaluated on every session activation (`AuthorizerSelection.activate`), which
+ * is what lets a node with a UI follow its declared parent's liveness: the
+ * moment that parent stops serving, the next activation selects the local
+ * dialog again.
  */
 export function selectAuthorizer(
   ctx: ExtensionContext,
   deps: AuthorizerSelectionDeps,
 ): SelectedAuthority {
   if (ctx.hasUI) {
+    const relayTarget = resolveLiveRelayTarget(ctx, deps);
+    if (relayTarget === null) {
+      return {
+        terminal: new LocalUserAuthorizer({
+          ui: ctx.ui,
+          mode: ctx.mode,
+          events: deps.events,
+          getPromptPreferences: deps.getPromptPreferences,
+          requestPermissionDecision: deps.requestPermissionDecision,
+        }),
+        adjudicatesLocally: true,
+      };
+    }
     return {
-      terminal: new LocalUserAuthorizer({
-        ui: ctx.ui,
-        mode: ctx.mode,
-        events: deps.events,
-        getPromptPreferences: deps.getPromptPreferences,
-        requestPermissionDecision: deps.requestPermissionDecision,
-      }),
-      adjudicatesLocally: true,
+      terminal: buildParentAuthorizer(ctx, deps),
+      adjudicatesLocally: false,
+      relayTarget,
     };
   }
   if (deps.detection.isSubagent(ctx)) {
     return {
-      terminal: new ParentAuthorizer(ctx, {
-        forwardingDir: deps.forwardingDir,
-        registry: deps.registry,
-        serving: deps.serving,
-        getTimeoutMs: deps.getForwardingTimeoutMs,
-        logger: deps.logger,
-      }),
+      terminal: buildParentAuthorizer(ctx, deps),
       adjudicatesLocally: false,
     };
   }
   return { terminal: new DenyingAuthorizer(), adjudicatesLocally: true };
 }
+
+/**
+ * The session a node with a UI should relay to, or `null` when it should decide
+ * for itself.
+ *
+ * A human is present here, so only a definite "yes" relays: a target nobody can
+ * confirm is draining its inbox leaves the ask with the human who is already
+ * watching. That is the opposite burden of proof from
+ * `ParentAuthorizer.checkServingLiveness`, where an unjudgeable target waits
+ * out the timeout because a headless child has no alternative.
+ */
+function resolveLiveRelayTarget(
+  ctx: ExtensionContext,
+  deps: AuthorizerSelectionDeps,
+): PermissionForwardingTarget | null {
+  const sessionId = getSessionId(ctx);
+  const target = resolvePermissionForwardingTarget({
+    isSubagent: deps.detection.isSubagent(ctx),
+    currentSessionId: sessionId,
+    sessionId,
+    registry: deps.registry,
+  });
+  if (target === null || deps.serving.isServing(target) !== true) {
+    return null;
+  }
+  return target;
+}
+
+/** The relaying terminal for `ctx`, built from the selection's own deps. */
+function buildParentAuthorizer(
+  ctx: ExtensionContext,
+  deps: AuthorizerSelectionDeps,
+): ParentAuthorizer {
+  return new ParentAuthorizer(ctx, {
+    forwardingDir: deps.forwardingDir,
+    registry: deps.registry,
+    serving: deps.serving,
+    getTimeoutMs: deps.getForwardingTimeoutMs,
+    logger: deps.logger,
+  });
+}

package/src/authority/forwarding-liveness.ts

@@ -92,8 +92,7 @@ export interface HeartbeatReader {
  * Keyed on the target rather than a session id because the answer depends on
  * how the target was resolved. An in-process child and its parent share a
  * `globalThis`, so the registry answers for them; an out-of-process pair shares
- * only the filesystem; and a session that owns the inbox it is forwarding to is
- * not a case either channel describes.
+ * only the filesystem.
  *
  * Consolidating that into one collaborator is what keeps `ParentAuthorizer`
  * from holding two lookups and re-deciding which one applies — the decision has
@@ -108,6 +107,10 @@ export interface TargetServingLookup {
 
 /** What answered a liveness question, and what it saw. */
 export interface ServingObservation {
+  /**
+   * Which channel answered. `"none"` belongs to a lookup that consulted none —
+   * the real judge never gives it, since every target it sees names a channel.
+   */
   channel: "registry" | "heartbeat" | "none";
   /** The heartbeat state behind a `"heartbeat"` answer; `null` on the other channels. */
   state: HeartbeatState | null;
@@ -138,8 +141,6 @@ export class ForwardingLivenessJudge implements TargetServingLookup {
         return this.deps.registry.isServing(target.sessionId);
       case "env":
         return this.deps.heartbeats.read(target.sessionId) === "alive";
-      case "self":
-        return null;
     }
   }
 
@@ -157,8 +158,6 @@ export class ForwardingLivenessJudge implements TargetServingLookup {
           state: this.deps.heartbeats.read(target.sessionId),
           servingIds: this.deps.heartbeats.servingIds(),
         };
-      case "self":
-        return { channel: "none", state: null, servingIds: [] };
     }
   }
 }

package/src/authority/permission-forwarding.ts

@@ -287,10 +287,9 @@ export function createPermissionForwardingLocation(
  * **in-process** child of `sessionId`, so the two share a `globalThis` and the
  * requester may consult the serving-session registry to decide whether anyone
  * is draining its inbox. `"env"` means the target lives in another process,
- * where that signal is unavailable; `"self"` is the UI host owning its own
- * forwarding location.
+ * where that signal is unavailable.
  */
-export type PermissionForwardingTargetSource = "self" | "registry" | "env";
+export type PermissionForwardingTargetSource = "registry" | "env";
 
 /** The resolved forwarding target together with how it was found. */
 export interface PermissionForwardingTarget {
@@ -298,8 +297,14 @@ export interface PermissionForwardingTarget {
   source: PermissionForwardingTargetSource;
 }
 
+/**
+ * The session this node relays its asks to, or `null` when it has none.
+ *
+ * Answers only "which *other* session", never "myself": a node that owns its
+ * forwarding location has nothing to resolve, and a request filed into one's
+ * own inbox is drained by no watcher.
+ */
 export function resolvePermissionForwardingTarget(options: {
-  hasUI: boolean;
   isSubagent: boolean;
   currentSessionId?: string | null;
   env?: NodeJS.ProcessEnv;
@@ -308,13 +313,6 @@ export function resolvePermissionForwardingTarget(options: {
   /** In-process subagent session registry (checked before env vars). */
   registry?: SubagentSessionRegistry;
 }): PermissionForwardingTarget | null {
-  if (options.hasUI) {
-    const own = normalizePermissionForwardingSessionId(
-      options.currentSessionId,
-    );
-    return own === null ? null : { sessionId: own, source: "self" };
-  }
-
   if (!options.isSubagent) {
     return null;
   }

package/src/authority/subagent-detection.ts

@@ -15,9 +15,10 @@ import type { SubagentSessionRegistry } from "./subagent-registry";
  * 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).
+ * the children it launches inherit it. No consumer may read it as a relay
+ * decision: `selectAuthorizer` relays a node with a UI only when a forwarding
+ * target resolves *and* that target is serving (#909), and serving eligibility
+ * does not consult this predicate at all (#907).
  */
 export interface SubagentDetector {
   isSubagent(ctx: SubagentDetectionContext): boolean;