@gotgenes/pi-permission-system 31.1.2 → 31.1.4

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).
 
+## [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)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** state each session's own tool list instead of editing the inherited one ([190e4c7](https://github.com/gotgenes/pi-packages/commit/190e4c7dc7e1a34e2e3c3ce4b413cd1e3ecd74c7)), closes [#890](https://github.com/gotgenes/pi-packages/issues/890)
+
+### Documentation
+
+* record that the inherited region is shared parts, not shared bytes ([#890](https://github.com/gotgenes/pi-packages/issues/890)) ([5755a9a](https://github.com/gotgenes/pi-packages/commit/5755a9a8ea34bf5c7e08a4cb8abc988c12eb3a59))
+* correct the sub-agent bridge description and the header-match residual ([#890](https://github.com/gotgenes/pi-packages/issues/890)) ([b0db764](https://github.com/gotgenes/pi-packages/commit/b0db764e0ffa484eb18bad2883710e77d93ec99b)), closes [#890](https://github.com/gotgenes/pi-packages/issues/890)
+
 ## [31.1.2](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v31.1.1...pi-permission-system-v31.1.2) (2026-09-07)
 
 

package/docs/configuration.md

@@ -1155,11 +1155,11 @@ permission:
 
 The extension integrates via Pi's lifecycle hooks:
 
-| Hook                 | Behavior                                                                                                                            |
-| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
-| `before_agent_start` | Filters the active tool set (restrict-only), narrows the `Available tools:` system-prompt listing to match, and hides denied skills |
-| `tool_call`          | Enforces permissions for every tool invocation                                                                                      |
-| `input`              | Intercepts `/skill:<name>` requests and enforces skill policy                                                                       |
+| Hook                 | Behavior                                                                                                                                                                  |
+| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `before_agent_start` | Filters the active tool set (restrict-only), restates the `Available tools:` and `Guidelines:` sections at the end of the system prompt to match, and hides denied skills |
+| `tool_call`          | Enforces permissions for every tool invocation                                                                                                                            |
+| `input`              | Intercepts `/skill:<name>` requests and enforces skill policy                                                                                                             |
 
 Additional behaviors:
 
@@ -1167,10 +1167,12 @@ Additional behaviors:
 - Tool filtering is restrict-only: the active set starts from pi's already-active tools (`pi.getActiveTools()`) and only ever has denied tools removed — the permission system never activates a tool pi left off by default (e.g. `find`, `grep`, `ls`)
 - Policy is applied to the tool surface pi has activated over the session, not to the previous turn's filtered result, so removing a `deny` rule restores the tool it had hidden without restarting pi.
   A tool that stops being active for any other reason (another extension deactivating it, pi unregistering it) is not restored.
-- On the turn a tool is restored, it is callable immediately but its `Available tools:` line reappears one turn later: pi builds the prompt an extension receives before the extension runs, so the line is only regenerated once the restored tool is already active
+- On the turn a tool is restored, it is callable immediately but its `Available tools:` line reappears one turn later: pi builds the prompt parts an extension receives before the extension runs, so the restored tool has no one-line description to render until it is already active
 - A tool is removed only when every value under its surface resolves to `deny`; a surface with any reachable `allow` or `ask` pattern stays available (see [Tool Surfaces](#tool-surfaces))
-- The `Available tools:` system prompt section is narrowed to match the filtered active tool set: denied tools' lines are dropped, the rest are kept, and the section is removed entirely only when no tool is allowed
-- The narrowed prompt is recomputed and returned on every turn but is byte-stable for a stable policy/agent, so the provider's prompt cache (tools + system prefix) is preserved rather than rewritten each turn.
+- The `Available tools:` and `Guidelines:` sections are **relocated** rather than edited in place: the copies pi wrote are removed, and this session's own are rendered at the end of the system prompt, after pi's `Current working directory:` footer.
+  Each session states its own tool surface, which is what keeps a subagent child's inherited prompt byte-identical to its parent's (see [ADR 0014](decisions/0014-tool-surface-is-node-local-prose.md)); the tool list moves to the end of the prompt for every session, whether or not anything is denied
+- The rendered sections follow pi's own rules: a tool is listed only when pi supplied a one-line description for it, and the guideline bullets are the allowed tools' own contributions around pi's built-in ones
+- The prompt is recomputed and returned on every turn but is stable across turns for a stable policy/agent, so the provider's prompt cache (tools + system prefix) is preserved rather than rewritten each turn.
   A policy change is an intentional cache transition, as a mid-session agent switch already is.
 - Extension-provided tools like `task`, `mcp`, and third-party tools are handled by exact registered name
 - Generic extension-tool approval prompts include a bounded input preview; built-in file tools use concise human-readable summaries

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.2",
+  "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/exposure/tool-registry.ts

@@ -9,6 +9,44 @@ export interface ToolRegistry {
   setActive(names: string[]): void;
 }
 
+/** Tool names and their guideline bullets, read from one pass over a registry. */
+export interface RegisteredTools {
+  /** Resolvable tool names, in registry order. */
+  readonly names: string[];
+  /** Guideline bullets per tool; a tool declaring none has no entry. */
+  readonly guidelinesByTool: ReadonlyMap<string, readonly string[]>;
+}
+
+/**
+ * Read a registry listing once, yielding both the answers this package needs.
+ *
+ * `getActive()` returns bare names and `getAll()` returns `ToolInfo` records,
+ * so both are accepted: a listing carrying no guidelines simply produces an
+ * empty map.
+ */
+export function readRegisteredTools(
+  tools: readonly unknown[],
+): RegisteredTools {
+  const names: string[] = [];
+  const guidelinesByTool = new Map<string, readonly string[]>();
+
+  for (const tool of tools) {
+    const name = getToolNameFromValue(tool);
+    if (!name) {
+      continue;
+    }
+
+    names.push(name);
+
+    const guidelines = getToolPromptGuidelinesFromValue(tool);
+    if (guidelines.length > 0) {
+      guidelinesByTool.set(name, guidelines);
+    }
+  }
+
+  return { names, guidelinesByTool };
+}
+
 export type ToolRegistrationCheckResult =
   | {
       status: "missing-tool-name";
@@ -98,6 +136,35 @@ export function getToolNameFromValue(value: unknown): string | null {
   return null;
 }
 
+/**
+ * The guideline bullets a registered tool contributes to the system prompt.
+ *
+ * Pi carries them per tool on `ToolInfo.promptGuidelines` and flattens them
+ * into one `Guidelines:` block when it builds the prompt. Reading them per tool
+ * is what lets this package rebuild that block for the allowed set alone,
+ * rather than matching Pi's rendered sentences by literal text.
+ *
+ * Kept defensively wide, like {@link getToolNameFromValue}: anything that is
+ * not a non-empty string is dropped, and a value that is not an array of them
+ * yields no guidelines rather than throwing.
+ */
+export function getToolPromptGuidelinesFromValue(value: unknown): string[] {
+  const guidelines = toRecord(value).promptGuidelines;
+  if (!Array.isArray(guidelines)) {
+    return [];
+  }
+
+  const bullets: string[] = [];
+  for (const entry of guidelines) {
+    const bullet = getNonEmptyString(entry);
+    if (bullet) {
+      bullets.push(bullet);
+    }
+  }
+
+  return bullets;
+}
+
 export function checkRequestedToolRegistration(
   requestedToolName: string | null,
   registeredTools: readonly unknown[],

package/src/exposure/tool-surface-prompt.ts

@@ -0,0 +1,258 @@
+/**
+ * The tool-surface region of a system prompt: which tools this session may
+ * call, and the guidance those tools contribute.
+ *
+ * Pi writes that region near the top of its preamble, a few hundred characters
+ * in. `@gotgenes/pi-subagents` copies everything ahead of the skills catalogue
+ * into a child's prompt verbatim, so the child's leading bytes match its
+ * parent's for prefix-reusing inference engines — which means editing the
+ * region in place ends that shared prefix for every child whose allowed set
+ * differs from its parent's (#890).
+ *
+ * So the region is *relocated* rather than narrowed: the sections Pi wrote are
+ * removed wherever they sit, and this node's own are rendered at the end of
+ * the prompt, past everything a child inherits. Each session then states its
+ * own tool surface and no session edits another's bytes.
+ *
+ * Rendering follows `buildSystemPrompt`'s own rules — a tool is listed only
+ * when it has a snippet, and the guideline bullets are the allowed tools' own
+ * `promptGuidelines` around Pi's built-in ones — so the block reads as the one
+ * Pi would have written for this session's real surface.
+ */
+
+/** What a session's tool surface renders from. */
+export interface ToolSurfaceInputs {
+  /** Tools this session may call, in the order they should be listed. */
+  readonly allowedTools: readonly string[];
+  /** Pi's one-line tool descriptions, keyed by tool name. */
+  readonly toolSnippets: Readonly<Record<string, string>>;
+  /** Guideline bullets each tool contributes, keyed by tool name. */
+  readonly guidelinesByTool: ReadonlyMap<string, readonly string[]>;
+}
+
+type LineSection = {
+  start: number;
+  end: number;
+};
+
+const AVAILABLE_TOOLS_SECTION_HEADER = "Available tools:";
+const GUIDELINES_SECTION_HEADER = "Guidelines:";
+
+/**
+ * Pi's filler sentence between the tool list and the guidelines.
+ *
+ * It refers to "the tools above", so it belongs with the list rather than with
+ * the text the list is being moved out of.
+ */
+const CUSTOM_TOOLS_FILLER_PREFIX = "In addition to the tools above";
+
+/** Pi's two unconditional guideline bullets, in the order it writes them. */
+const UNIVERSAL_GUIDELINES: readonly string[] = [
+  "Be concise in your responses",
+  "Show file paths clearly when working with files",
+];
+
+/**
+ * Relocate the tool surface: drop the sections Pi wrote, append this session's.
+ *
+ * The result always carries a tool-surface block, so a child whose inherited
+ * identity has none — its parent's node having already relocated it — still
+ * describes its own tools.
+ */
+export function renderToolSurface(
+  systemPrompt: string,
+  inputs: ToolSurfaceInputs,
+): string {
+  const lines = removeToolSurfaceSections(
+    normalizePrompt(systemPrompt).split("\n"),
+  );
+  const body = collapseExtraBlankLines(lines.join("\n"));
+  const block = renderToolSurfaceBlock(inputs);
+
+  return body.length > 0 ? `${body}\n\n${block}` : block;
+}
+
+/**
+ * Remove the `Available tools:` and `Guidelines:` sections, and the filler
+ * sentence between them.
+ *
+ * Each section is located by its own header, so the two are removed whether
+ * they sit adjacent in Pi's preamble or alone in a prompt something downstream
+ * rewrote — including a prompt this function already produced, which is what
+ * makes it safe to apply to its own output.
+ */
+function removeToolSurfaceSections(lines: readonly string[]): string[] {
+  let remaining = [...lines];
+  for (const header of [
+    AVAILABLE_TOOLS_SECTION_HEADER,
+    GUIDELINES_SECTION_HEADER,
+  ]) {
+    const section = findSection(remaining, header);
+    if (section) {
+      remaining = [
+        ...remaining.slice(0, section.start),
+        ...remaining.slice(section.end),
+      ];
+    }
+  }
+
+  return remaining.filter(
+    (line) => !line.trimStart().startsWith(CUSTOM_TOOLS_FILLER_PREFIX),
+  );
+}
+
+/** This session's tool surface, as Pi would have rendered it. */
+function renderToolSurfaceBlock(inputs: ToolSurfaceInputs): string {
+  const sections: string[] = [];
+
+  const toolList = renderAvailableTools(inputs);
+  if (toolList) {
+    sections.push(toolList);
+  }
+  sections.push(renderGuidelines(inputs));
+
+  return sections.join("\n\n");
+}
+
+/**
+ * The `Available tools:` section for the allowed set, or `null` when none of
+ * those tools has a snippet.
+ *
+ * Pi lists a tool only when the caller supplied a one-line snippet for it, so
+ * a tool without one is left unlisted here too rather than rendered bare.
+ */
+function renderAvailableTools(inputs: ToolSurfaceInputs): string | null {
+  const bullets = inputs.allowedTools
+    .map((toolName) => ({ toolName, snippet: inputs.toolSnippets[toolName] }))
+    .filter((tool) => Boolean(tool.snippet))
+    .map((tool) => `- ${tool.toolName}: ${tool.snippet}`);
+
+  return bullets.length > 0
+    ? [AVAILABLE_TOOLS_SECTION_HEADER, ...bullets].join("\n")
+    : null;
+}
+
+/**
+ * The `Guidelines:` section for the allowed set.
+ *
+ * Mirrors `buildSystemPrompt`'s assembly: its conditional file-exploration
+ * bullet first, then each allowed tool's own contributions, then its two
+ * unconditional bullets — de-duplicated in first-seen order, as Pi does.
+ */
+function renderGuidelines(inputs: ToolSurfaceInputs): string {
+  const bullets: string[] = [];
+  const seen = new Set<string>();
+  const addGuideline = (guideline: string): void => {
+    const normalized = guideline.trim();
+    if (normalized.length === 0 || seen.has(normalized)) {
+      return;
+    }
+    seen.add(normalized);
+    bullets.push(normalized);
+  };
+
+  const fileOperations = fileExplorationGuideline(new Set(inputs.allowedTools));
+  if (fileOperations) {
+    addGuideline(fileOperations);
+  }
+
+  for (const toolName of inputs.allowedTools) {
+    for (const guideline of inputs.guidelinesByTool.get(toolName) ?? []) {
+      addGuideline(guideline);
+    }
+  }
+
+  for (const guideline of UNIVERSAL_GUIDELINES) {
+    addGuideline(guideline);
+  }
+
+  return [
+    GUIDELINES_SECTION_HEADER,
+    ...bullets.map((bullet) => `- ${bullet}`),
+  ].join("\n");
+}
+
+/**
+ * Pi's shell-only file-exploration bullet, or `null` when it does not apply.
+ *
+ * Pi writes it only when a shell is available and none of the dedicated
+ * exploration tools is, so a session holding `grep`/`find`/`ls` is not told to
+ * reach for the shell instead.
+ */
+function fileExplorationGuideline(
+  allowedTools: ReadonlySet<string>,
+): string | null {
+  const hasBash = allowedTools.has("bash");
+  const hasPowerShell = allowedTools.has("powershell");
+  const hasExplorationTool =
+    allowedTools.has("grep") ||
+    allowedTools.has("find") ||
+    allowedTools.has("ls");
+
+  if ((!hasBash && !hasPowerShell) || hasExplorationTool) {
+    return null;
+  }
+  if (hasBash && hasPowerShell) {
+    return "Use bash or PowerShell for file operations like listing, searching, and finding files";
+  }
+  if (hasPowerShell) {
+    return "Use PowerShell for file operations like listing, searching, and finding files";
+  }
+  return "Use bash for file operations like ls, rg, find";
+}
+
+function normalizePrompt(prompt: string): string {
+  return (prompt || "").replace(/\r\n/g, "\n");
+}
+
+function collapseExtraBlankLines(text: string): string {
+  return text.replace(/\n{3,}/g, "\n\n").trimEnd();
+}
+
+function isTopLevelSectionHeader(line: string): boolean {
+  const trimmed = line.trim();
+  return (
+    trimmed.length > 0 && trimmed.endsWith(":") && !trimmed.startsWith("-")
+  );
+}
+
+function isSectionBodyLine(line: string): boolean {
+  const trimmed = line.trim();
+  if (trimmed.length === 0) return true; // blank line
+  if (trimmed.startsWith("- ")) return true; // bullet
+  if (line !== line.trimStart()) return true; // indented
+  return false;
+}
+
+function findSection(
+  lines: readonly string[],
+  header: string,
+): LineSection | null {
+  const start = lines.findIndex((line) => line.trim() === header);
+  if (start === -1) {
+    return null;
+  }
+
+  // If a subsequent recognised section header exists, use it as the boundary.
+  // This preserves the original behaviour for the common case where sections
+  // are adjacent (e.g. "Available tools:" followed by "Guidelines:") and
+  // ensures any prose continuation between the two headers is also removed.
+  for (let index = start + 1; index < lines.length; index += 1) {
+    if (isTopLevelSectionHeader(lines[index])) {
+      return { start, end: index };
+    }
+  }
+
+  // No subsequent section header — stop at the first non-body line so that
+  // content after the section (e.g. custom user notes) is not silently deleted.
+  let end = start + 1;
+  for (let index = start + 1; index < lines.length; index += 1) {
+    if (!isSectionBodyLine(lines[index])) {
+      end = index;
+      break;
+    }
+    end = index + 1;
+  }
+
+  return { start, end };
+}

package/src/handlers/before-agent-start.ts

@@ -3,12 +3,13 @@ import type {
   ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
 import { resolveSkillPromptEntries } from "#src/exposure/skill-prompt-sanitizer";
-import { sanitizeAvailableToolsSection } from "#src/exposure/system-prompt-sanitizer";
 import {
-  getToolNameFromValue,
+  type RegisteredTools,
+  readRegisteredTools,
   type ToolRegistry,
 } from "#src/exposure/tool-registry";
 import type { ToolSurfaceObservation } from "#src/exposure/tool-surface-baseline";
+import { renderToolSurface } from "#src/exposure/tool-surface-prompt";
 import type { DebugLogger } from "#src/logging/session-logger";
 import type { PermissionResolver } from "#src/policy/permission-resolver";
 import type { PermissionSession } from "#src/session/permission-session";
@@ -17,6 +18,14 @@ import type { TurnPreparation } from "./session-turn-prep";
 /** Minimal subset of BeforeAgentStartEvent used by this handler. */
 interface BeforeAgentStartPayload {
   systemPrompt: string;
+  /**
+   * The parts Pi assembled the prompt from. `toolSnippets` is what lets this
+   * handler render the session's own tool list instead of editing the one Pi
+   * wrote — including in a child, whose inherited identity carries none.
+   */
+  systemPromptOptions?: {
+    toolSnippets?: Record<string, string>;
+  };
 }
 
 /**
@@ -39,8 +48,12 @@ export function shouldExposeTool(
  *
  * Recomputes the active tool set and the returned system-prompt override on
  * every fire (no memoization): the override must be returned each turn so that
- * skill filtering is reapplied and the wire prompt stays byte-stable, rather
- * than letting Pi reset to its skill-unfiltered base prompt on a cache hit.
+ * skill filtering is reapplied and the wire prompt stays stable across turns,
+ * rather than letting Pi reset to its skill-unfiltered base prompt on a cache
+ * hit.
+ *
+ * The tool surface is relocated rather than edited in place, so a subagent
+ * child's inherited identity stays byte-identical to its parent's (#890).
  *
  * Constructor deps:
  * - `turnPrep` — brings the node up to date for the turn before anything reads
@@ -70,8 +83,9 @@ export class AgentPrepHandler {
     this.turnPrep.prepare(ctx);
 
     const agentName = this.session.resolveAgentName(ctx, event.systemPrompt);
+    const registered = readRegisteredTools(this.toolRegistry.getAll());
     const surface = this.session.resolveExposedTools(
-      this.observeToolSurface(),
+      this.observeToolSurface(registered),
       (toolName) =>
         shouldExposeTool(toolName, agentName, (t, a) =>
           this.resolver.isToolFullyDenied(t, a),
@@ -88,12 +102,13 @@ export class AgentPrepHandler {
       });
     }
 
-    const toolPromptResult = sanitizeAvailableToolsSection(
-      event.systemPrompt,
+    const toolSurfacePrompt = renderToolSurface(event.systemPrompt, {
       allowedTools,
-    );
+      toolSnippets: event.systemPromptOptions?.toolSnippets ?? {},
+      guidelinesByTool: registered.guidelinesByTool,
+    });
     const skillPromptResult = resolveSkillPromptEntries(
-      toolPromptResult.prompt,
+      toolSurfacePrompt,
       this.resolver,
       agentName,
       this.session.getPathNormalizer(),
@@ -104,21 +119,12 @@ export class AgentPrepHandler {
       : {};
   }
 
-  private observeToolSurface(): ToolSurfaceObservation {
+  private observeToolSurface(
+    registered: RegisteredTools,
+  ): ToolSurfaceObservation {
     return {
-      active: toolNamesOf(this.toolRegistry.getActive()),
-      registered: new Set(toolNamesOf(this.toolRegistry.getAll())),
+      active: readRegisteredTools(this.toolRegistry.getActive()).names,
+      registered: new Set(registered.names),
     };
   }
 }
-
-function toolNamesOf(tools: readonly unknown[]): string[] {
-  const names: string[] = [];
-  for (const tool of tools) {
-    const toolName = getToolNameFromValue(tool);
-    if (toolName) {
-      names.push(toolName);
-    }
-  }
-  return names;
-}

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,

package/src/exposure/system-prompt-sanitizer.ts

@@ -1,274 +0,0 @@
-export interface SanitizeSystemPromptResult {
-  prompt: string;
-  removed: boolean;
-}
-
-type LineSection = {
-  start: number;
-  end: number;
-};
-
-type GuidelineRule = {
-  matches: (guideline: string) => boolean;
-  shouldKeep: (allowedTools: ReadonlySet<string>) => boolean;
-};
-
-const AVAILABLE_TOOLS_SECTION_HEADER = "Available tools:";
-const GUIDELINES_SECTION_HEADER = "Guidelines:";
-
-const TOOL_GUIDELINE_RULES: readonly GuidelineRule[] = [
-  {
-    matches: (guideline) =>
-      guideline === "use bash for file operations like ls, rg, find",
-    shouldKeep: (allowedTools) => allowedTools.has("bash"),
-  },
-  {
-    matches: (guideline) =>
-      guideline ===
-      "prefer grep/find/ls tools over bash for file exploration (faster, respects .gitignore)",
-    shouldKeep: (allowedTools) =>
-      allowedTools.has("bash") &&
-      (allowedTools.has("grep") ||
-        allowedTools.has("find") ||
-        allowedTools.has("ls")),
-  },
-  {
-    matches: (guideline) =>
-      guideline ===
-        "use read to examine files before editing. you must use this tool instead of cat or sed." ||
-      guideline === "use read to examine files instead of cat or sed.",
-    shouldKeep: (allowedTools) => allowedTools.has("read"),
-  },
-  {
-    matches: (guideline) =>
-      guideline ===
-      "use edit for precise changes (old text must match exactly)",
-    shouldKeep: (allowedTools) => allowedTools.has("edit"),
-  },
-  {
-    matches: (guideline) =>
-      guideline === "use write only for new files or complete rewrites",
-    shouldKeep: (allowedTools) => allowedTools.has("write"),
-  },
-  {
-    matches: (guideline) =>
-      guideline ===
-      "when summarizing your actions, output plain text directly - do not use cat or bash to display what you did",
-    shouldKeep: (allowedTools) =>
-      allowedTools.has("edit") || allowedTools.has("write"),
-  },
-  {
-    matches: (guideline) =>
-      guideline ===
-      "use task when work should be delegated to one or more specialized agents instead of handled entirely in the current session.",
-    shouldKeep: (allowedTools) => allowedTools.has("task"),
-  },
-  {
-    matches: (guideline) =>
-      guideline ===
-      "use mcp for mcp discovery first: search by capability, describe one exact tool name, then call it.",
-    shouldKeep: (allowedTools) => allowedTools.has("mcp"),
-  },
-];
-
-function normalizePrompt(prompt: string): string {
-  return (prompt || "").replace(/\r\n/g, "\n");
-}
-
-function collapseExtraBlankLines(text: string): string {
-  return text.replace(/\n{3,}/g, "\n\n").trimEnd();
-}
-
-function normalizeGuidelineText(line: string): string {
-  return line
-    .trim()
-    .replace(/^[-*]\s+/, "")
-    .replace(/\s+/g, " ")
-    .toLowerCase();
-}
-
-function isTopLevelSectionHeader(line: string): boolean {
-  const trimmed = line.trim();
-  return (
-    trimmed.length > 0 && trimmed.endsWith(":") && !trimmed.startsWith("-")
-  );
-}
-
-function isSectionBodyLine(line: string): boolean {
-  const trimmed = line.trim();
-  if (trimmed.length === 0) return true; // blank line
-  if (trimmed.startsWith("- ")) return true; // bullet
-  if (line !== line.trimStart()) return true; // indented
-  return false;
-}
-
-function findSection(
-  lines: readonly string[],
-  header: string,
-): LineSection | null {
-  const start = lines.findIndex((line) => line.trim() === header);
-  if (start === -1) {
-    return null;
-  }
-
-  // If a subsequent recognised section header exists, use it as the boundary.
-  // This preserves the original behaviour for the common case where sections
-  // are adjacent (e.g. "Available tools:" followed by "Guidelines:") and
-  // ensures any prose continuation between the two headers is also removed.
-  for (let index = start + 1; index < lines.length; index += 1) {
-    if (isTopLevelSectionHeader(lines[index])) {
-      return { start, end: index };
-    }
-  }
-
-  // No subsequent section header — stop at the first non-body line so that
-  // content after the section (e.g. custom user notes) is not silently deleted.
-  let end = start + 1;
-  for (let index = start + 1; index < lines.length; index += 1) {
-    if (!isSectionBodyLine(lines[index])) {
-      end = index;
-      break;
-    }
-    end = index + 1;
-  }
-
-  return { start, end };
-}
-
-/**
- * Tool name from an `Available tools:` bullet (`- read: …` -> `read`), or
- * `null` for non-tool lines (blank lines, boilerplate prose). Matches the
- * first token after the bullet marker, with or without a trailing colon.
- */
-function extractToolBulletName(line: string): string | null {
-  const match = /^\s*-\s+([A-Za-z0-9_-]+)/.exec(line);
-  return match ? match[1] : null;
-}
-
-/**
- * Narrow the `Available tools:` section to the allowed tools: keep allowed-tool
- * bullet lines and any non-tool prose, drop denied/inactive bullet lines. When
- * no tool bullet survives, remove the section header too. This mirrors what Pi
- * itself renders for the active tool set, so the result is byte-stable across
- * turns regardless of whether the input still carries the full default listing.
- */
-function narrowAvailableToolsSection(
-  lines: readonly string[],
-  allowedTools: ReadonlySet<string>,
-): { lines: string[]; removed: boolean } {
-  const section = findSection(lines, AVAILABLE_TOOLS_SECTION_HEADER);
-  if (!section) {
-    return { lines: [...lines], removed: false };
-  }
-
-  const before = lines.slice(0, section.start);
-  const header = lines[section.start];
-  const body = lines.slice(section.start + 1, section.end);
-  const after = lines.slice(section.end);
-
-  const filteredBody = body.filter((line) => {
-    const toolName = extractToolBulletName(line);
-    if (toolName === null) {
-      return true; // keep blank lines and non-tool boilerplate
-    }
-    return allowedTools.has(toolName);
-  });
-
-  const removed = filteredBody.length !== body.length;
-  if (!removed) {
-    return { lines: [...lines], removed: false };
-  }
-
-  const hasToolBullet = filteredBody.some(
-    (line) => extractToolBulletName(line) !== null,
-  );
-  if (!hasToolBullet) {
-    return { lines: [...before, ...after], removed: true };
-  }
-
-  return {
-    lines: [...before, header, ...filteredBody, ...after],
-    removed: true,
-  };
-}
-
-function shouldKeepGuideline(
-  line: string,
-  allowedTools: ReadonlySet<string>,
-): boolean {
-  const normalized = normalizeGuidelineText(line);
-
-  for (const rule of TOOL_GUIDELINE_RULES) {
-    if (rule.matches(normalized)) {
-      return rule.shouldKeep(allowedTools);
-    }
-  }
-
-  return true;
-}
-
-function sanitizeGuidelinesSection(
-  lines: readonly string[],
-  allowedTools: ReadonlySet<string>,
-): { lines: string[]; removed: boolean } {
-  const section = findSection(lines, GUIDELINES_SECTION_HEADER);
-  if (!section) {
-    return { lines: [...lines], removed: false };
-  }
-
-  const before = lines.slice(0, section.start + 1);
-  const after = lines.slice(section.end);
-  const body = lines.slice(section.start + 1, section.end);
-  const filteredBody = body.filter((line) => {
-    const trimmed = line.trim();
-    if (!trimmed.startsWith("- ")) {
-      return true;
-    }
-
-    return shouldKeepGuideline(line, allowedTools);
-  });
-
-  const removed = filteredBody.length !== body.length;
-  if (!removed) {
-    return { lines: [...lines], removed: false };
-  }
-
-  const hasBullet = filteredBody.some((line) => line.trim().startsWith("- "));
-  if (!hasBullet) {
-    return {
-      lines: [...lines.slice(0, section.start), ...after],
-      removed: true,
-    };
-  }
-
-  return {
-    lines: [...before, ...filteredBody, ...after],
-    removed: true,
-  };
-}
-
-export function sanitizeAvailableToolsSection(
-  systemPrompt: string,
-  allowedToolNames: readonly string[],
-): SanitizeSystemPromptResult {
-  const allowedTools = new Set(
-    allowedToolNames.map((toolName) => toolName.trim()).filter(Boolean),
-  );
-  const normalizedLines = normalizePrompt(systemPrompt).split("\n");
-  const narrowedToolsSection = narrowAvailableToolsSection(
-    normalizedLines,
-    allowedTools,
-  );
-  const sanitizedGuidelines = sanitizeGuidelinesSection(
-    narrowedToolsSection.lines,
-    allowedTools,
-  );
-  const removed = narrowedToolsSection.removed || sanitizedGuidelines.removed;
-
-  return {
-    prompt: removed
-      ? collapseExtraBlankLines(sanitizedGuidelines.lines.join("\n"))
-      : systemPrompt,
-    removed,
-  };
-}