@gotgenes/pi-permission-system 31.1.1 → 31.1.3

package/CHANGELOG.md

@@ -5,6 +5,25 @@ 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.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)
+
+
+### Miscellaneous Chores
+
+* **pi-permission-system:** add path false-positive measurement script ([464c6a1](https://github.com/gotgenes/pi-packages/commit/464c6a10a2795cbae5fac4e518d0b60ed90c7eaf)), closes [#863](https://github.com/gotgenes/pi-packages/issues/863)
+
 ## [31.1.1](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v31.1.0...pi-permission-system-v31.1.1) (2026-09-05)
 
 

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-permission-system",
-  "version": "31.1.1",
+  "version": "31.1.3",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
   "exports": {
@@ -90,6 +90,7 @@
     "test:watch": "vitest",
     "verify:public-types": "bash scripts/verify-public-types.sh",
     "measure:core-coverage": "node scripts/measure-core-coverage.mjs",
+    "measure:path-false-positives": "node scripts/measure-path-false-positives.mjs",
     "measure:statement-descent": "node scripts/measure-statement-descent.mjs",
     "measure:statement-operands": "node scripts/measure-statement-operands.mjs",
     "measure:unresolved-redirects": "node scripts/measure-unresolved-redirects.mjs",

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/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,
-  };
-}