@gotgenes/pi-permission-system 29.0.0 → 29.1.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).
 
+## [29.1.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v29.0.0...pi-permission-system-v29.1.0) (2026-08-31)
+
+
+### Features
+
+* **pi-permission-system:** warn when a subagent child runs with no permission node ([223710f](https://github.com/gotgenes/pi-packages/commit/223710ff2ed81977161ba2a367deb81fe6c7f207)), closes [#792](https://github.com/gotgenes/pi-packages/issues/792)
+
+
+### Documentation
+
+* **pi-permission-system:** document the optional bound channel and the unguarded-child alarm ([9a16e1b](https://github.com/gotgenes/pi-packages/commit/9a16e1b09934ecdb529875b59f7649c50ccfd5b9)), closes [#792](https://github.com/gotgenes/pi-packages/issues/792)
+
 ## [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)
 
 

package/docs/subagent-integration.md

@@ -16,13 +16,32 @@ An implementation that creates child sessions inside its own process (via `creat
 | `subagents:child:session-created` | `{ sessionId, parentSessionId? }` | After the child session is created, immediately before `bindExtensions()` |
 | `subagents:child:disposed`        | `{ sessionId }`                   | In the run's `finally`, on success and on error alike                     |
 
+A third channel is **optional**, and buys one diagnostic:
+
+| Channel                  | Payload                           | When                                                                |
+| ------------------------ | --------------------------------- | ------------------------------------------------------------------- |
+| `subagents:child:bound`  | `{ sessionId, parentSessionId? }` | After `bindExtensions()` resolves, and not at all when it throws    |
+
 The pre-bind ordering of `session-created` is **contract, not an implementation detail**.
 Emit it synchronously, on the same call stack, before `bindExtensions()`: this package's subscriber registers the child synchronously, and the registration must land before binding proceeds so the child's own instance can detect itself the moment it loads.
 An implementation that awaits between creating the session and emitting, or that emits after binding, breaks detection for every child it spawns.
 
-Both are fire-and-forget broadcasts.
+All are fire-and-forget broadcasts.
 Nothing is returned, nothing is awaited, and no reply travels back over the bus.
 
+#### The optional `bound` channel
+
+Emitting `subagents:child:bound` is not part of the obligation, and an implementation that never emits it is fully conformant.
+What it buys is the unguarded-child alarm described under [What this package does on both ends](#what-this-package-does-on-both-ends): without it, a child that loads no instance of this package runs every tool in its `tools:` allowlist ungated and nothing says so.
+
+The timing is the whole point, and it is the one moment that answers the question.
+`bindExtensions()` awaits the child's `session_start` emit, so when it resolves every child extension has initialized and this package's child instance — if it loaded at all — has published its service.
+Emit it there: after the `await`, on the success path only.
+A child whose binding threw never ran, so reporting it would be a false alarm about a session that does not exist.
+
+No other moment works.
+`session-created` fires before the child's extensions have loaded, and by `disposed` the child's `session_shutdown` has already withdrawn its service — so a healthy child looks identical to an unguarded one at both.
+
 ### Out-of-process implementations
 
 An implementation that spawns a child as its own `pi` process sets one environment variable at spawn:
@@ -72,7 +91,7 @@ The full condition, with a worked example, is documented where the setting lives
 
 The announcement is all an implementation provides; this section is what it buys.
 
-On the announcing side, this package subscribes to the child lifecycle (`src/authority/subagent-lifecycle-events.ts`) and registers every in-process child session in the `SubagentSessionRegistry` on `subagents:child:session-created`, unregistering it on `subagents:child:disposed`.
+On the announcing side, this package subscribes to the child lifecycle (`src/authority/subagent-lifecycle-events.ts`) and registers every in-process child session in the `SubagentSessionRegistry` on `subagents:child:session-created`, unregistering it on `subagents:child:disposed`, and auditing it on `subagents:child:bound`.
 Because the event bus dispatches synchronously, that registration completes before `bindExtensions()` proceeds.
 
 The `SubagentSessionRegistry` is backed by a process-global singleton (`globalThis` + `Symbol.for()`), accessed via `getSubagentSessionRegistry()` in `src/authority/subagent-registry.ts`.
@@ -83,7 +102,10 @@ What the announcement enables:
 
 1. **Deterministic child detection** — `isSubagentExecutionContext()` hits the process-global registry on the first check for an in-process child, and reads the environment for one spawned as its own process, with a session-directory heuristic behind both.
 2. **Per-agent policy enforcement** - the permission system's `before_agent_start` handler resolves the agent name from the `<active_agent>` system-prompt tag and applies per-agent `permission:` frontmatter overrides.
-3. **`ask`-state forwarding** - when a child triggers an `ask` permission, the request forwards to the parent session's UI through the existing polling mechanism.
+3. **An unguarded child is announced** — when a child finishes binding without publishing a service of its own, it has no permission node: no `tool_call` gate, no tool filtering, no `permission:` frontmatter resolution, and no ask-forwarding.
+   The parent records a `child_node_absent` review entry for every such child and warns once per session.
+   The likeliest cause is the child's own configuration — `@gotgenes/pi-subagents` excluding this package under `excludedExtensionPackages` — and a failure to load this extension in the child leaves the identical absence, which the parent cannot tell apart, so the warning names both.
+4. **`ask`-state forwarding** - when a child triggers an `ask` permission, the request forwards to the parent session's UI through the existing polling mechanism.
    The parent approves or denies, and the child resumes.
    When the parent approves "for this session," it chooses a scope: **this subagent only** (the least-privilege default) records the grant on the requesting child, while **the whole session** records it on the serving parent so the parent and all its subagents resolve it without re-prompting.
 
@@ -162,7 +184,7 @@ Nothing needs to be edited, and in-process children are unaffected: parent and c
 
 ## Conformance of known implementations
 
-Conformance is a property of the announcement alone — whether an implementation emits the in-process events, or sets the out-of-process variable — not of the frontmatter vocabulary it offers for tool visibility.
+Conformance is a property of the announcement alone — whether an implementation emits the two in-process events, or sets the out-of-process variable — not of the frontmatter vocabulary it offers for tool visibility, and not of the optional `bound` channel.
 
 | Extension                                                                           | Shape      | Adopts the convention             | Visibility key                     |
 | ----------------------------------------------------------------------------------- | ---------- | --------------------------------- | ---------------------------------- |
@@ -177,6 +199,9 @@ Adopting the convention is a one-line change at their spawn site.
 
 The upstream `tintinweb/pi-subagents` (which `@gotgenes/pi-subagents` forks) publishes no `subagents:child:session-created` event, so its in-process children have neither deterministic detection nor `ask`-state forwarding.
 
+`@gotgenes/pi-subagents` is also the only implementation that emits the optional `subagents:child:bound` channel, so it is the only one whose unguarded children are announced.
+The others forfeit that alarm without forfeiting conformance.
+
 See [guides/permission-frontmatter-for-subagent-extensions.md](guides/permission-frontmatter-for-subagent-extensions.md) for the companion convention on `permission:` frontmatter, which implementations document rather than implement.
 
 ---

package/package.json

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

package/src/authority/child-node-audit.ts

@@ -0,0 +1,94 @@
+/**
+ * child-node-audit.ts — Report an in-process subagent child that runs with no
+ * permission node.
+ *
+ * Gating is node-local (ADR 0012 decision 1): each node loads its own instance
+ * of this extension and gates its own `tool_call`s. A child that loads none has
+ * no gate, no tool filtering, no `permission:` frontmatter resolution, and no
+ * ask-forwarding — every tool in its `tools:` allowlist runs ungated. The
+ * parent's own gating is unaffected, so without this audit the operator watches
+ * the permission system work and never learns the child is unguarded.
+ *
+ * The signal is publication: since #699 every node publishes its service under
+ * its own session id, and a subagent implementation announces the moment a
+ * child finished binding its extensions. A child that has published nothing by
+ * then has no node.
+ *
+ * The two halves of the alarm fire at different rates on purpose. The review
+ * entry is the durable record and must be complete, so it is written for every
+ * affected child. The visible warning is capped at one per parent session: the
+ * cause is a single line of configuration, and a parent that fans out ten
+ * children would otherwise emit ten identical warnings.
+ */
+
+/** Answers whether the node whose session is `sessionId` published a service. */
+export type NodePresenceLookup = (sessionId: string) => boolean;
+
+/** The narrow log seam this audit needs (ISP): a durable record and a warning. */
+export interface ChildNodeAuditLog {
+  review(event: string, details?: Record<string, unknown>): void;
+  warn(message: string): void;
+}
+
+/** Fields read from the child-bound announcement (ISP). */
+export interface BoundChild {
+  /** Child session id — the key its node would have published under. */
+  sessionId: string;
+  parentSessionId?: string;
+}
+
+/**
+ * The agent-facing text for an unguarded child.
+ *
+ * The parent cannot tell a deliberate exclusion from a load failure — both
+ * leave the identical absence — so the message names the likelier cause and
+ * admits the other in the same sentence.
+ */
+export function childNodeAbsentMessage(childSessionId: string): string {
+  return (
+    `pi-permission-system: subagent child session ${childSessionId} is ` +
+    "running with no permission node — this extension is not loaded in it, so " +
+    "its tool calls are not gated there. Most often the package is listed in " +
+    "pi-subagents' excludedExtensionPackages; a failure to load this extension " +
+    "in the child does the same. Further affected children are recorded in the " +
+    "permission review log as child_node_absent."
+  );
+}
+
+/** The audit seam the child-lifecycle subscription drives (ISP). */
+export interface BoundChildAuditor {
+  auditBoundChild(child: BoundChild): void;
+}
+
+/**
+ * Audits each child that finishes binding, and alarms on one with no node.
+ *
+ * The warn-once latch is a plain field with no re-arm hook, because the
+ * extension factory is re-invoked per session generation — a `/new`, `/resume`,
+ * `/fork`, or `/import` switch builds a fresh audit. A `session_start` with
+ * `reason: "reload"` reuses this instance and deliberately does not re-warn:
+ * the operator has already been told.
+ */
+export class ChildNodeAudit implements BoundChildAuditor {
+  private warned = false;
+
+  constructor(
+    private readonly hasNode: NodePresenceLookup,
+    private readonly log: ChildNodeAuditLog,
+  ) {}
+
+  auditBoundChild(child: BoundChild): void {
+    if (this.hasNode(child.sessionId)) {
+      return;
+    }
+    this.log.review("child_node_absent", {
+      childSessionId: child.sessionId,
+      parentSessionId: child.parentSessionId ?? null,
+    });
+    if (this.warned) {
+      return;
+    }
+    this.warned = true;
+    this.log.warn(childNodeAbsentMessage(child.sessionId));
+  }
+}

package/src/authority/subagent-lifecycle-events.ts

@@ -1,10 +1,16 @@
 /**
  * subagent-lifecycle-events.ts — Subscribe to @gotgenes/pi-subagents' child
- * lifecycle events and keep the SubagentSessionRegistry in sync.
+ * lifecycle events and dispatch each fact to its owner.
  *
  * @gotgenes/pi-subagents publishes its child-execution lifecycle on the Pi
  * event bus (ADR 0002): it no longer calls this package's service directly.
- * We register the child on `session-created` and unregister it on `disposed`.
+ * We register the child on `session-created`, audit it for a permission node on
+ * `bound`, and unregister it on `disposed`.
+ *
+ * The module subscribes to the announcement and hands each fact to its owner —
+ * the registry for the two registration events, the audit for `bound` — so the
+ * channel names and payload shapes of the whole contract stay declared in one
+ * place.
  *
  * The channel names and payload shapes are declared independently here (the two
  * packages must not depend on each other under jiti) and MUST match the
@@ -15,13 +21,25 @@
  * event bus dispatches listeners synchronously, so a synchronous handler lands
  * the registry entry before binding proceeds. Introducing an `await` before
  * `registry.register(...)` would break the pre-bind ordering.
+ *
+ * The `bound` handler carries no such requirement — nothing waits on it — but it
+ * must not make the other two async either, since they share this module.
  */
 
+import type { BoundChildAuditor } from "./child-node-audit";
 import type { SubagentSessionRegistry } from "./subagent-registry";
 
 /** Emitted by the core after session creation, before `bindExtensions()`. */
 export const SUBAGENT_CHILD_SESSION_CREATED = "subagents:child:session-created";
 
+/**
+ * Emitted by the core once the child's extensions have bound, after every child
+ * `session_start` handler has run — the one moment a parent can observe what
+ * those extensions installed. Optional: an implementation that never emits it
+ * is still conformant, and simply forfeits the unguarded-child alarm.
+ */
+export const SUBAGENT_CHILD_BOUND = "subagents:child:bound";
+
 /** Emitted by the core in the run's `finally` (success and error). */
 export const SUBAGENT_CHILD_DISPOSED = "subagents:child:disposed";
 
@@ -37,6 +55,13 @@ interface ChildSessionCreatedEvent {
   parentSessionId?: string;
 }
 
+/** Fields read from the `bound` payload (ISP). */
+interface ChildBoundEvent {
+  /** Child session id — the key its node would have published under. */
+  sessionId: string;
+  parentSessionId?: string;
+}
+
 /** Fields read from the `disposed` payload (ISP). */
 interface ChildDisposedEvent {
   /** Child session id — the registry key. Must match the publisher. */
@@ -46,12 +71,13 @@ interface ChildDisposedEvent {
 /**
  * Subscribe to the subagent child lifecycle.
  *
- * @returns an unsubscribe that detaches both handlers (call during
+ * @returns an unsubscribe that detaches every handler (call during
  *          `session_shutdown`).
  */
 export function subscribeSubagentLifecycle(
   events: LifecycleEventBus,
   registry: SubagentSessionRegistry,
+  audit: BoundChildAuditor,
 ): () => void {
   const unsubCreated = events.on(SUBAGENT_CHILD_SESSION_CREATED, (data) => {
     const event = data as ChildSessionCreatedEvent;
@@ -60,6 +86,14 @@ export function subscribeSubagentLifecycle(
     });
   });
 
+  const unsubBound = events.on(SUBAGENT_CHILD_BOUND, (data) => {
+    const event = data as ChildBoundEvent;
+    audit.auditBoundChild({
+      sessionId: event.sessionId,
+      parentSessionId: event.parentSessionId,
+    });
+  });
+
   const unsubDisposed = events.on(SUBAGENT_CHILD_DISPOSED, (data) => {
     const event = data as ChildDisposedEvent;
     registry.unregister(event.sessionId);
@@ -67,6 +101,7 @@ export function subscribeSubagentLifecycle(
 
   return () => {
     unsubCreated();
+    unsubBound();
     unsubDisposed();
   };
 }

package/src/index.ts

@@ -7,6 +7,7 @@ import {
   ObservedAuthorizerRegistrar,
 } from "./authority/authorizer-registry";
 import { AuthorizerSelection } from "./authority/authorizer-selection";
+import { ChildNodeAudit } from "./authority/child-node-audit";
 import {
   ForwardedRequestServer,
   type ServingPolicy,
@@ -50,7 +51,7 @@ import { PermissionResolver } from "./permission-resolver";
 import { PermissionSession } from "./permission-session";
 import { LocalPermissionsService } from "./permissions-service";
 import { resolveRenderBudget } from "./presentation/dialog-renderer";
-import type { PermissionsService } from "./service";
+import { getPermissionsService, type PermissionsService } from "./service";
 import { PermissionServiceLifecycle } from "./service-lifecycle";
 import { PermissionSessionLogger } from "./session-logger";
 import { SessionRules } from "./session-rules";
@@ -259,10 +260,18 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
   );
 
   // Subscribe to @gotgenes/pi-subagents' child lifecycle events so child
-  // sessions register/unregister without the core calling us (ADR 0002).
+  // sessions register/unregister without the core calling us (ADR 0002), and
+  // so a child that bound its extensions without loading one of ours is
+  // reported rather than silently ungated (#792). The lookup is a thunk over
+  // the locator, never a cached reference, per the guidance in service.ts.
+  const childNodeAudit = new ChildNodeAudit(
+    (sessionId) => getPermissionsService(sessionId) !== undefined,
+    logger,
+  );
   const unsubSubagentLifecycle = subscribeSubagentLifecycle(
     pi.events,
     subagentRegistry,
+    childNodeAudit,
   );
 
   // PermissionServiceLifecycle owns the process-global service publication: