@gotgenes/pi-permission-system 36.2.1 → 37.0.0

package/CHANGELOG.md

@@ -5,6 +5,23 @@ 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).
 
+## [37.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v36.2.1...pi-permission-system-v37.0.0) (2026-10-02)
+
+
+### Features
+
+* **pi-permission-system:** **breaking:** require Pi 1.0.0 or later ([9c76ae3](https://github.com/gotgenes/pi-packages/commit/9c76ae30dd58b0a94524f753f7c72ff356231294)), closes [#970](https://github.com/gotgenes/pi-packages/issues/970)
+
+### Bug Fixes
+
+* **pi-permission-system:** keep prompt sections other extensions add, such as <mcp_servers> ([1abdfe4](https://github.com/gotgenes/pi-packages/commit/1abdfe4901a27cb8ff3d85a965fc07b3be874624)), closes [#999](https://github.com/gotgenes/pi-packages/issues/999)
+* **pi-permission-system:** keep later prompt sections when a skill is denied ([dafd83b](https://github.com/gotgenes/pi-packages/commit/dafd83b075b01ef39335822f8b5122c56ee00b97)), closes [#999](https://github.com/gotgenes/pi-packages/issues/999)
+
+### Documentation
+
+* **pi-permission-system:** note the Pi 1.0.0 requirement under Upgrading ([5bc932c](https://github.com/gotgenes/pi-packages/commit/5bc932cf9936728c0e3c551fdbea6a7009108958)), closes [#970](https://github.com/gotgenes/pi-packages/issues/970)
+* **pi-permission-system:** record prompt changes through systemPromptOptions ([b11051f](https://github.com/gotgenes/pi-packages/commit/b11051f1365a635b67e70dea126c8a49ff9ef31b)), closes [#999](https://github.com/gotgenes/pi-packages/issues/999)
+
 ## [36.2.1](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v36.2.0...pi-permission-system-v36.2.1) (2026-10-01)
 
 

package/README.md

@@ -155,6 +155,12 @@ Third-party packages are maintained by their authors; review one before granting
 
 ## Upgrading
 
+### The major after 36.x — requires Pi 1.0.0
+
+The extension now requires `@earendil-works/pi-coding-agent` and `@earendil-works/pi-tui` 1.0.0 or later.
+Upgrade Pi to 1.0.0 before upgrading this package; on an older Pi, stay on the 36.x line.
+No configuration change is needed.
+
 ### 22.0.0 — project config requires project trust
 
 Project-scoped configuration (the project `config.json` and project-agent frontmatter — both permission policy and runtime knobs such as `yoloMode`) is now loaded only when Pi reports the project as trusted.

package/docs/configuration.md

@@ -1314,11 +1314,11 @@ permission:
 
 The extension integrates via Pi's lifecycle hooks:
 
-| Hook                 | Behavior                                                                                                                                                                                                      |
-| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `before_agent_start` | Filters the active tool set (restrict-only), restates the tool list and guidelines at the end of the system prompt to match (except under a custom system prompt outside a subagent), 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), states a subagent child's own tool list and rules, and hides denied skills, all through pi's prompt options rather than a rewritten prompt |
+| `tool_call`          | Enforces permissions for every tool invocation                                                                                                                                          |
+| `input`              | Intercepts `/skill:<name>` requests and enforces skill policy                                                                                                                           |
 
 Additional behaviors:
 
@@ -1326,16 +1326,18 @@ 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 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 tool list and guidelines 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 the working directory pi states last.
-  They take the shape pi writes them in: `Available tools:` and `Guidelines:` sections after a `Current working directory:` footer through pi 0.85, and `<tools>` and `<rules>` sections after a `<cwd>` section from pi 0.86.
-  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 on pi's default prompt, whether or not anything is denied.
-  A custom system prompt (`.pi/SYSTEM.md`, `~/.pi/agent/SYSTEM.md`, `--system-prompt`) is left exactly as pi built it: pi writes no tool list or rules under one, and this extension adds none either, so the prompt describes tools only if you wrote that yourself.
+- Every change this extension makes to the system prompt goes through pi's `systemPromptOptions`; it never returns a rewritten prompt.
+  A returned prompt is sent as the whole prompt, which would drop the sections other extensions add after this one runs, such as pi's `<mcp_servers>` list of `codemode` and `deferred` MCP servers (see [ADR 0015](decisions/0015-prompt-changes-through-system-prompt-options.md)).
+- On pi's default prompt, the tool list and guidelines stay where pi writes them, as its `<tools>` and `<rules>` sections, and pi renders them from the filtered active set, so a denied tool and its guidelines are absent and a restored tool is listed on the turn it returns.
+- A custom system prompt (`.pi/SYSTEM.md`, `~/.pi/agent/SYSTEM.md`, `--system-prompt`) is left exactly as pi built it: pi writes no tool list or rules under one, and this extension adds none either, so the prompt describes tools only if you wrote that yourself.
   Tool filtering and enforcement still apply, and the model still receives only the allowed tools in the request's tool list.
-  A subagent child is the exception: its prompt is always a custom one assembled by the subagent extension, so it still gets its own tool list and rules at the end, while any custom text it inherited stays untouched.
-- 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, then any rules another extension added to `systemPromptOptions.promptGuidelines`, 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 subagent child is the exception: its prompt is always a custom one assembled by the subagent extension, so it gets its own `<tools>` and `<rules>` sections, placed after the working directory, while any custom text it inherited stays untouched.
+  The child's 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, then any rules another extension added to `systemPromptOptions.promptGuidelines`, around pi's built-in ones.
+- A subagent child running with `@gotgenes/pi-subagents` needs a release that drops the parent's `<tools>` and `<rules>` from the prompt the child inherits; with an older one, the child shows the parent's tool list as well as its own.
+- A denied skill is removed from the skills catalogue pi renders.
+  A skill listed in text pi did not render, such as your own `SYSTEM.md`, is not edited out; using it is still gated.
+- The prompt options are recomputed on every turn but are stable across turns for a stable policy/agent, so the provider's prompt cache 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": "36.2.1",
+  "version": "37.0.0",
   "description": "Permission enforcement extension for the Pi coding agent.",
   "type": "module",
   "exports": {
@@ -63,13 +63,13 @@
     ]
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": ">=0.79.0",
-    "@earendil-works/pi-tui": ">=0.79.0"
+    "@earendil-works/pi-coding-agent": ">=1.0.0",
+    "@earendil-works/pi-tui": ">=1.0.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.5.11",
-    "@earendil-works/pi-coding-agent": "0.79.1",
-    "@earendil-works/pi-tui": "0.79.1",
+    "@earendil-works/pi-coding-agent": "1.0.0",
+    "@earendil-works/pi-tui": "1.0.0",
     "@types/node": "^22.15.3",
     "rollup": "^4.63.1",
     "rollup-plugin-dts": "^6.5.1",

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

@@ -38,8 +38,6 @@ export type SkillPromptEntry = {
 };
 
 export type SkillPromptSection = {
-  start: number;
-  end: number;
   entries: ParsedSkillPromptEntry[];
 };
 
@@ -52,15 +50,6 @@ function decodeXml(value: string): string {
     .replace(/&/g, "&");
 }
 
-function encodeXml(value: string): string {
-  return value
-    .replace(/&/g, "&")
-    .replace(/</g, "&lt;")
-    .replace(/>/g, "&gt;")
-    .replace(/"/g, "&quot;")
-    .replace(/'/g, "&apos;");
-}
-
 function parseSkillEntries(sectionBody: string): ParsedSkillPromptEntry[] {
   const entries: ParsedSkillPromptEntry[] = [];
   const skillBlockRegex = new RegExp(SKILL_BLOCK_PATTERN, "g");
@@ -115,8 +104,6 @@ export function parseAllSkillPromptSections(
       closeStart,
     );
     sections.push({
-      start,
-      end,
       entries: parseSkillEntries(sectionBody),
     });
     searchStart = end;
@@ -160,95 +147,56 @@ function createResolvedSkillEntry(
   };
 }
 
-function renderAvailableSkillsSection(
-  entries: readonly SkillPromptEntry[],
-): string {
-  return [
-    AVAILABLE_SKILLS_OPEN_TAG,
-    ...entries.flatMap((entry) => [
-      "  <skill>",
-      `    <name>${encodeXml(entry.name)}</name>`,
-      `    <description>${encodeXml(entry.description)}</description>`,
-      `    <location>${encodeXml(entry.location)}</location>`,
-      "  </skill>",
-    ]),
-    AVAILABLE_SKILLS_CLOSE_TAG,
-  ].join("\n");
-}
-
-function removePromptRange(prompt: string, start: number, end: number): string {
-  const beforeSection = prompt.slice(0, start).replace(/\n+$/, "");
-  const afterSection = prompt.slice(end);
-  return `${beforeSection}${afterSection}`;
-}
-
-export function resolveSkillPromptEntries(
+/**
+ * The skills listed in the prompt's `<available_skills>` catalogues that
+ * policy does not deny, in catalogue order: what skill path matching may
+ * treat as a skill's files. Edits no prompt text.
+ */
+export function visibleSkillPromptEntries(
   prompt: string,
   permissionManager: SkillPermissionChecker,
   agentName: string | null,
   normalizer: PathNormalizer,
-): { prompt: string; entries: SkillPromptEntry[] } {
-  const sections = parseAllSkillPromptSections(prompt);
-  if (sections.length === 0) {
-    return { prompt, entries: [] };
-  }
-
+): SkillPromptEntry[] {
   const permissionCache = new Map<string, PermissionState>();
-  const visibleEntries: SkillPromptEntry[] = [];
-  const replacements: Array<{ start: number; end: number; content: string }> =
-    [];
+  return parseAllSkillPromptSections(prompt)
+    .flatMap((section) => section.entries)
+    .map((entry) =>
+      createResolvedSkillEntry(
+        entry,
+        resolvePermissionState(
+          entry.name,
+          permissionManager,
+          agentName,
+          permissionCache,
+        ),
+        normalizer,
+      ),
+    )
+    .filter((entry) => entry.state !== "deny");
+}
 
-  for (const section of sections) {
-    const resolvedEntries = section.entries.map((entry) => {
-      const state = resolvePermissionState(
-        entry.name,
+/**
+ * The skills policy does not deny, judged by name, in their original order.
+ *
+ * Judging the skill list itself, rather than a catalogue rendered from it,
+ * keeps the answer independent of whether that catalogue has been rendered yet.
+ */
+export function withoutDeniedSkills<T extends { readonly name: string }>(
+  skills: readonly T[],
+  permissionManager: SkillPermissionChecker,
+  agentName: string | null,
+): T[] {
+  const permissionCache = new Map<string, PermissionState>();
+  return skills.filter(
+    (skill) =>
+      resolvePermissionState(
+        skill.name,
         permissionManager,
         agentName,
         permissionCache,
-      );
-      return createResolvedSkillEntry(entry, state, normalizer);
-    });
-
-    const visibleSectionEntries = resolvedEntries.filter(
-      (entry) => entry.state !== "deny",
-    );
-    visibleEntries.push(...visibleSectionEntries);
-
-    if (visibleSectionEntries.length === resolvedEntries.length) {
-      continue;
-    }
-
-    replacements.push({
-      start: section.start,
-      end: section.end,
-      content:
-        visibleSectionEntries.length > 0
-          ? renderAvailableSkillsSection(visibleSectionEntries)
-          : "",
-    });
-  }
-
-  if (replacements.length === 0) {
-    return { prompt, entries: visibleEntries };
-  }
-
-  let sanitizedPrompt = prompt;
-  for (let i = replacements.length - 1; i >= 0; i--) {
-    const replacement = replacements[i];
-    sanitizedPrompt =
-      replacement.content.length > 0
-        ? `${sanitizedPrompt.slice(0, replacement.start)}${replacement.content}${sanitizedPrompt.slice(replacement.end)}`
-        : removePromptRange(
-            sanitizedPrompt,
-            replacement.start,
-            replacement.end,
-          );
-  }
-
-  return {
-    prompt: sanitizedPrompt,
-    entries: visibleEntries,
-  };
+      ) !== "deny",
+  );
 }
 
 export function findSkillPathMatch(

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

@@ -2,36 +2,18 @@
  * 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).
+ * Pi renders that region itself, as its `<tools>` and `<rules>` sections, from
+ * the active tool set this extension narrows — but only when it writes the
+ * preamble. A subagent child's prompt is always a `customPrompt`, under which
+ * Pi writes neither section, so a child states its own through
+ * `systemPromptOptions.sections`, which Pi places after its `<cwd>` section.
+ * This module renders those section contents.
  *
- * So the region is *relocated* rather than narrowed: the sections Pi wrote are
- * removed, 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.
- *
- * Removal is bounded to the text this package or Pi wrote. The prompt is split
- * at the cwd layer Pi writes last and unconditionally: a
- * `Current working directory:` footer through Pi 0.85, a `<cwd>` section from
- * 0.86. Everything after it was appended by an extension, and everything
- * before it is Pi's own only when Pi did not build the prompt from a
- * `customPrompt`. Under a custom prompt Pi writes no tool surface at all, so a
- * section matched above the cwd layer is a user's or another extension's, and
- * removing it destroyed their text (#919, #932). On the 0.86 shape even a
- * Pi-authored head is searched only for Pi's own `<tools>` and `<rules>`,
- * bounded to where Pi writes them, since the plain headers it no longer
- * writes would match only a context file's text.
- *
- * Rendering follows `buildSystemPrompt`'s own rules (a tool is listed only
- * when it has a snippet; the guideline bullets are the allowed tools' own
- * `promptGuidelines`, then other extensions' rules, around Pi's built-in
- * ones) and its shape (plain headers or tagged sections, matching the
- * prompt), so the block reads as the one Pi would have written for this
- * session's real surface.
+ * 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`, then other extensions' rules, around Pi's built-in ones,
+ * so the sections read as the ones Pi would have written for this session's
+ * real surface.
  */
 
 /** What a session's tool surface renders from. */
@@ -43,78 +25,25 @@ export interface ToolSurfaceInputs {
   /** Guideline bullets each tool contributes, keyed by tool name. */
   readonly guidelinesByTool: ReadonlyMap<string, readonly string[]>;
   /**
-   * `systemPromptOptions.promptGuidelines`: bullets Pi writes into its rules
-   * after the tools' own.
+   * `systemPromptOptions.promptGuidelines`: the bullets other extensions add
+   * to Pi's rules after the tools' own.
    *
-   * Only a bullet no registered tool contributes is carried. From Pi 0.86 the
-   * field holds what other extensions added; through 0.85 it *is* the tools'
-   * guidelines, flattened, and a denied tool's bullet must not return by this
-   * route.
+   * Only a bullet no registered tool contributes is carried, so a denied
+   * tool's bullet cannot return by this route.
    */
   readonly promptGuidelines: readonly string[];
-  /**
-   * Whether Pi wrote the prompt's preamble itself.
-   *
-   * False when Pi assembled the prompt from `customPrompt` — a user's
-   * SYSTEM.md, or a subagent child's assembled prompt — in which case Pi wrote
-   * no tool-surface sections and every line above its footer belongs to
-   * somebody else.
-   */
-  readonly piAuthoredPreamble: boolean;
 }
 
-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";
-
-/** What Pi writes under `Available tools:` when no selected tool has a snippet. */
-const EMPTY_LIST_PLACEHOLDER = "(none)";
-
-/**
- * The first line of the footer Pi writes last, in both of its branches.
- *
- * It is the boundary between what Pi assembled and what extensions appended
- * after it — the same anchor `@gotgenes/pi-subagents` uses to find Pi's
- * session-resolved tail.
- */
-const PROMPT_FOOTER_PREFIX = "Current working directory: ";
-
-/**
- * The tags of the section Pi renders the working directory into from 0.86,
- * last among its own sections and in both of its branches.
- */
-const CWD_SECTION_OPEN = "<cwd>";
-const CWD_SECTION_CLOSE = "</cwd>";
-
-/** The sections Pi 0.86+ writes its tool surface into, in the order it writes them. */
-const TOOL_SURFACE_SECTION_NAMES = ["tools", "rules"] as const;
-
 /**
- * Opening tags of the sections Pi writes after its tool surface.
- *
- * Pi writes `<tools>` and `<rules>` directly under its preamble and ahead of
- * every one of these, so a match that opens or closes past the first of them
- * is text somebody quoted, not Pi's.
+ * This session's tool surface as the contents of Pi's `tools` and `rules`
+ * prompt sections, untagged: Pi wraps each `sections` entry in its own tags.
  */
-const LATER_PI_SECTION_OPENS: ReadonlySet<string> = new Set([
-  "<docs>",
-  "<addendum>",
-  "<project_context>",
-  "<skills>",
-  CWD_SECTION_OPEN,
-]);
+export interface ToolSurfaceSections {
+  /** `- name: snippet` lines; absent when no allowed tool has a snippet. */
+  readonly tools?: string;
+  /** `- rule` lines, in `buildSystemPrompt`'s order. */
+  readonly rules: string;
+}
 
 /** Pi's two unconditional guideline bullets, in the order it writes them. */
 const UNIVERSAL_GUIDELINES: readonly string[] = [
@@ -123,299 +52,18 @@ const UNIVERSAL_GUIDELINES: readonly string[] = [
 ];
 
 /**
- * Relocate the tool surface: drop the sections Pi wrote, append this session's.
+ * Render this session's tool surface as section contents, for a node that
+ * states it through `systemPromptOptions.sections`.
  *
- * 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.
+ * The `tools` section is omitted when no allowed tool has a snippet, as Pi
+ * lists a tool only when it has one.
  */
-export function renderToolSurface(
-  systemPrompt: string,
+export function renderToolSurfaceSections(
   inputs: ToolSurfaceInputs,
-): string {
-  const lines = normalizePrompt(systemPrompt).split("\n");
-  const { layout, tailStart } = detectPromptLayout(lines);
-  const body = [
-    settleRegion(
-      lines.slice(0, tailStart),
-      inputs.piAuthoredPreamble ? layout.removePiSurface : null,
-    ),
-    settleRegion(lines.slice(tailStart), layout.removeRelocatedSurface),
-  ]
-    .filter((region) => region.length > 0)
-    .join("\n")
-    .trimEnd();
-  const block = layout.renderBlock(toolSurfaceBullets(inputs));
-
-  return body.length > 0 ? `${body}\n\n${block}` : block;
-}
-
-/** Lines removed from one region of the prompt; the rest are returned in order. */
-type RegionRemoval = (lines: readonly string[]) => string[];
-
-/**
- * How one prompt shape bounds and writes the tool surface.
- *
- * Pi has written its prompt in more than one shape, and each shape answers the
- * same three questions differently, so the shape is decided once per prompt
- * and every answer is read off the layout it selected.
- */
-interface PromptLayout {
-  /** Pi's own tool surface, removed from the head when Pi wrote the preamble. */
-  readonly removePiSurface: RegionRemoval;
-  /** A relocated block (this package's or a peer's), removed from the tail. */
-  readonly removeRelocatedSurface: RegionRemoval;
-  /** This session's block, in this layout's shape. */
-  readonly renderBlock: (bullets: ToolSurfaceBullets) => string;
-}
-
-/** A prompt's layout, and the line at which the text extensions appended begins. */
-interface DetectedLayout {
-  readonly layout: PromptLayout;
-  readonly tailStart: number;
-}
-
-/**
- * The shape Pi wrote through 0.85: `Available tools:` and `Guidelines:`
- * sections in its preamble, and a `Current working directory:` footer last.
- */
-const HEADER_LAYOUT: PromptLayout = {
-  removePiSurface: removeToolSurfaceSections,
-  removeRelocatedSurface: removeToolSurfaceSections,
-  renderBlock: renderHeaderBlock,
-};
-
-/**
- * The shape Pi writes from 0.86: an untagged preamble, then `<name>` sections
- * joined by a blank line (`<tools>` and `<rules>` among them), and a `<cwd>`
- * section last among its own.
- */
-const SECTION_LAYOUT: PromptLayout = {
-  removePiSurface: removePiToolSurfaceSections,
-  removeRelocatedSurface: removeRelocatedToolSurface,
-  renderBlock: renderSectionBlock,
-};
-
-/**
- * The prompt's layout, read off the cwd layer Pi wrote, and where the text
- * extensions appended after that layer begins.
- *
- * Pi writes its cwd layer last among its own, in both of its branches: a
- * `Current working directory:` footer through 0.85, a `<cwd>` section from
- * 0.86. So whichever of the two sits later is Pi's, and a line of either shape
- * quoted in a context file or a custom prompt is always above it. The shape is
- * told apart by which layer is present, never by version sniffing.
- *
- * A prompt carrying neither is read as the header layout and treated as all
- * head, so a block appended to *that* prompt cannot be found and replaced, and
- * a custom preamble would collect a second one. Pi writes a cwd layer in both
- * branches of both renderers, so reaching this needs a downstream rewrite of
- * Pi's whole output.
- */
-function detectPromptLayout(lines: readonly string[]): DetectedLayout {
-  const footerAt = lines.findLastIndex((line) =>
-    line.startsWith(PROMPT_FOOTER_PREFIX),
-  );
-  const cwdCloseAt = lastCwdSectionClose(lines);
-  if (cwdCloseAt > footerAt) {
-    return { layout: SECTION_LAYOUT, tailStart: cwdCloseAt + 1 };
-  }
-  return {
-    layout: HEADER_LAYOUT,
-    tailStart: footerAt === -1 ? lines.length : footerAt + 1,
-  };
-}
-
-/**
- * Line index of the closing tag of the last `<cwd>` section, or -1 when there
- * is none.
- *
- * Pi renders the section as exactly three lines (the opening tag, the
- * directory, the closing tag), so that is the shape matched, the way the
- * footer is matched by its prefix.
- */
-function lastCwdSectionClose(lines: readonly string[]): number {
-  return lines.findLastIndex(
-    (line, index) =>
-      line === CWD_SECTION_CLOSE && lines[index - 2] === CWD_SECTION_OPEN,
-  );
-}
-
-/**
- * One region's surviving text: its sections removed, when they are ours to
- * remove, or returned as it arrived when `removal` is `null`.
- *
- * Blank runs are collapsed only where a removal opened one, so a region this
- * pass took nothing out of is returned exactly as it arrived rather than
- * reflowed by a pass that had nothing to do with it.
- */
-function settleRegion(
-  lines: readonly string[],
-  removal: RegionRemoval | null,
-): string {
-  if (!removal) {
-    return lines.join("\n");
-  }
-  const kept = removal(lines);
-  const text = kept.join("\n");
-  return kept.length === lines.length ? text : collapseExtraBlankLines(text);
-}
-
-/**
- * Remove the `Available tools:` and `Guidelines:` sections, and the filler
- * sentence between them, from one region.
- *
- * Each section is located by its own header, so the two are removed whether
- * they sit adjacent in Pi's preamble or alone in the tail — including a block
- * this function already produced, which is what makes it safe to apply to its
- * own output, and what keeps it order-independent with a second writer.
- */
-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),
-  );
-}
-
-/**
- * Remove Pi 0.86+'s own `<tools>` and `<rules>` sections, tags included.
- *
- * A section is Pi's only when it opens and closes before the first section Pi
- * writes after it; the plain headers `removeToolSurfaceSections` matches are
- * never searched here, because Pi writes none on this shape and every match
- * would be a user's or another extension's text.
- */
-function removePiToolSurfaceSections(head: readonly string[]): string[] {
-  return removeTaggedToolSurface(head, laterPiSectionStart);
-}
-
-/**
- * Remove a relocated block from the extension tail, in either shape.
- *
- * This package writes the tagged shape here, and a peer writer may write
- * either, so both are removed: the pass stays safe to apply to its own output
- * and order-independent with a second writer.
- */
-function removeRelocatedToolSurface(tail: readonly string[]): string[] {
-  return removeToolSurfaceSections(
-    removeTaggedToolSurface(tail, (lines) => lines.length),
-  );
-}
-
-/**
- * Remove the first `<tools>` and the first `<rules>` section, each only when
- * it closes before the line `limitOf` names.
- */
-function removeTaggedToolSurface(
-  lines: readonly string[],
-  limitOf: (lines: readonly string[]) => number,
-): string[] {
-  let remaining = [...lines];
-  for (const name of TOOL_SURFACE_SECTION_NAMES) {
-    const section = findTaggedSection(remaining, name, limitOf(remaining));
-    if (section) {
-      remaining = [
-        ...remaining.slice(0, section.start),
-        ...remaining.slice(section.end),
-      ];
-    }
-  }
-  return remaining;
-}
-
-/** Line index of the first section Pi writes after its tool surface. */
-function laterPiSectionStart(lines: readonly string[]): number {
-  const at = lines.findIndex((line) => LATER_PI_SECTION_OPENS.has(line));
-  return at === -1 ? lines.length : at;
-}
-
-/**
- * The first `<name>` section, opening tag through closing tag, that ends
- * before `limit`; `null` when there is none.
- */
-function findTaggedSection(
-  lines: readonly string[],
-  name: string,
-  limit: number,
-): LineSection | null {
-  const start = lines.indexOf(`<${name}>`);
-  if (start === -1 || start >= limit) {
-    return null;
-  }
-  const closeAt = lines.indexOf(`</${name}>`, start + 1);
-  if (closeAt === -1 || closeAt >= limit) {
-    return null;
-  }
-  return { start, end: closeAt + 1 };
-}
-
-/**
- * This session's tool surface, as Pi 0.86+ would have rendered it: a `<tools>`
- * section, when any allowed tool has a snippet, then a `<rules>` section.
- */
-function renderSectionBlock(bullets: ToolSurfaceBullets): string {
-  const sections: string[] = [];
-  if (bullets.tools.length > 0) {
-    sections.push(taggedSection("tools", bullets.tools));
-  }
-  sections.push(taggedSection("rules", bullets.rules));
-
-  return sections.join("\n\n");
-}
-
-/** A section in the form Pi 0.86+ renders: its tags on their own lines. */
-function taggedSection(name: string, lines: readonly string[]): string {
-  return [`<${name}>`, ...lines, `</${name}>`].join("\n");
-}
-
-/** This session's tool surface, as Pi through 0.85 would have rendered it. */
-function renderHeaderBlock(bullets: ToolSurfaceBullets): string {
-  const sections: string[] = [];
-
-  const toolList = renderAvailableTools(bullets.tools);
-  if (toolList) {
-    sections.push(toolList);
-  }
-  sections.push(renderGuidelines(bullets.rules));
-
-  return sections.join("\n\n");
-}
-
-/** The `Available tools:` section, or `null` when it lists no tool. */
-function renderAvailableTools(bullets: readonly string[]): string | null {
-  return bullets.length > 0
-    ? [AVAILABLE_TOOLS_SECTION_HEADER, ...bullets].join("\n")
-    : null;
-}
-
-/** The `Guidelines:` section. */
-function renderGuidelines(bullets: readonly string[]): string {
-  return [GUIDELINES_SECTION_HEADER, ...bullets].join("\n");
-}
-
-/** The bullets a tool-surface block wraps, whatever shape wraps them. */
-interface ToolSurfaceBullets {
-  /** `- name: snippet` lines; empty when no allowed tool has a snippet. */
-  readonly tools: readonly string[];
-  /** `- rule` lines, in `buildSystemPrompt`'s order. */
-  readonly rules: readonly string[];
-}
-
-function toolSurfaceBullets(inputs: ToolSurfaceInputs): ToolSurfaceBullets {
-  return { tools: toolBullets(inputs), rules: ruleBullets(inputs) };
+): ToolSurfaceSections {
+  const tools = toolBullets(inputs);
+  const rules = ruleBullets(inputs).join("\n");
+  return tools.length > 0 ? { tools: tools.join("\n"), rules } : { rules };
 }
 
 /**
@@ -436,7 +84,8 @@ function toolBullets(inputs: ToolSurfaceInputs): string[] {
  *
  * Mirrors `buildSystemPrompt`'s assembly: its conditional file-exploration
  * bullet first, then each allowed tool's own contributions, then the bullets
- * other extensions added, then its two unconditional bullets — de-duplicated in first-seen order, as Pi does.
+ * other extensions added, then its two unconditional bullets — de-duplicated
+ * in first-seen order, as Pi does.
  */
 function ruleBullets(inputs: ToolSurfaceInputs): string[] {
   const bullets: string[] = [];
@@ -512,48 +161,3 @@ function fileExplorationGuideline(
   }
   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();
-}
-
-/**
- * Whether the line belongs to the body of the section above it.
- *
- * Pi writes a section as its header, then bullets — or the `(none)` placeholder
- * when the list is empty — and separates it from what follows with a blank
- * line. Anything else is already outside the section, however it is punctuated:
- * a section that ran on to "the next line ending in a colon" swallowed the
- * prose in between, which is somebody else's text whenever the match was not
- * Pi's own (#919, #932).
- */
-function isSectionBodyLine(line: string): boolean {
-  const trimmed = line.trim();
-  if (trimmed.length === 0) return true; // blank line
-  if (trimmed.startsWith("- ")) return true; // bullet
-  if (trimmed === EMPTY_LIST_PLACEHOLDER) return true; // Pi's empty list
-  if (line !== line.trimStart()) return true; // indented
-  return false;
-}
-
-/** The header line plus its own body, or `null` when the header is absent. */
-function findSection(
-  lines: readonly string[],
-  header: string,
-): LineSection | null {
-  const start = lines.findIndex((line) => line.trim() === header);
-  if (start === -1) {
-    return null;
-  }
-
-  let end = start + 1;
-  while (end < lines.length && isSectionBodyLine(lines[end])) {
-    end += 1;
-  }
-
-  return { start, end };
-}

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

@@ -1,16 +1,20 @@
 import type {
   BeforeAgentStartEventResult,
   ExtensionContext,
+  NormalizedBuildSystemPromptOptions,
 } from "@earendil-works/pi-coding-agent";
 import type { SubagentDetector } from "#src/authority/subagent-detection";
-import { resolveSkillPromptEntries } from "#src/exposure/skill-prompt-sanitizer";
+import {
+  visibleSkillPromptEntries,
+  withoutDeniedSkills,
+} from "#src/exposure/skill-prompt-sanitizer";
 import {
   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 { renderToolSurfaceSections } 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";
@@ -18,22 +22,20 @@ import type { TurnPreparation } from "./session-turn-prep";
 
 /** Minimal subset of BeforeAgentStartEvent used by this handler. */
 interface BeforeAgentStartPayload {
-  systemPrompt: string;
+  /** The prompt rendered from `systemPromptOptions` as it stands right now. */
+  readonly 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.
-   * `customPrompt` says whether Pi wrote a preamble at all: under one, it
-   * writes no tool surface, so there is nothing of Pi's to remove, and a root
-   * node adds none either.
-   * `promptGuidelines` carries rules other extensions added, which removing
-   * Pi's own rules section would otherwise drop.
+   * The mutable parts Pi renders the prompt from; later handlers, and Pi
+   * itself, see what this handler writes here. `customPrompt` says whether Pi
+   * wrote a preamble at all: under one, it writes no tool surface.
+   * `toolSnippets` and `promptGuidelines` are what a child's own tool surface
+   * renders from, and `sections` is where it is stated. `skills` is the
+   * catalogue Pi renders, which policy narrows.
    */
-  systemPromptOptions?: {
-    customPrompt?: string;
-    toolSnippets?: Record<string, string>;
-    promptGuidelines?: readonly string[];
-  };
+  systemPromptOptions: Pick<
+    NormalizedBuildSystemPromptOptions,
+    "customPrompt" | "toolSnippets" | "promptGuidelines" | "sections" | "skills"
+  >;
 }
 
 /**
@@ -54,17 +56,16 @@ export function shouldExposeTool(
 /**
  * Handles the `before_agent_start` event: tool filtering + prompt sanitization.
  *
- * 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 stable across turns,
- * rather than letting Pi reset to its skill-unfiltered base prompt on a cache
- * hit.
+ * Every change to the prompt is stated through `event.systemPromptOptions`,
+ * never as a returned `systemPrompt`: a returned prompt is frozen for the run,
+ * so the sections an extension later in the chain adds (Pi's own
+ * `<mcp_servers>` among them) would never reach the provider (#999).
  *
- * 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).
- * A root node whose prompt Pi built from a custom one states no tool surface,
- * matching Pi, which writes none there; a subagent child's prompt is always a
- * custom one, and it still states its own tools.
+ * Narrowing the active set is enough for a prompt Pi wrote: Pi renders its
+ * `<tools>` and `<rules>` from the reconciled active set. A subagent child's
+ * prompt is always a custom one, under which Pi writes neither, so a child
+ * states its own as `sections`, which Pi places after its `<cwd>` section. A
+ * root under a custom prompt states none, matching Pi.
  *
  * Constructor deps:
  * - `turnPrep` — brings the node up to date for the turn before anything reads
@@ -116,40 +117,53 @@ export class AgentPrepHandler {
       });
     }
 
-    const toolSurfacePrompt = this.statesOwnToolSurface(event, ctx)
-      ? renderToolSurface(event.systemPrompt, {
-          allowedTools,
-          toolSnippets: event.systemPromptOptions?.toolSnippets ?? {},
-          guidelinesByTool: registered.guidelinesByTool,
-          promptGuidelines: event.systemPromptOptions?.promptGuidelines ?? [],
-          piAuthoredPreamble: !hasCustomPrompt(event),
-        })
-      : event.systemPrompt;
-    const skillPromptResult = resolveSkillPromptEntries(
-      toolSurfacePrompt,
+    const options = event.systemPromptOptions;
+    if (this.isSubagentUnderCustomPrompt(event, ctx)) {
+      const sections = renderToolSurfaceSections({
+        allowedTools,
+        toolSnippets: options.toolSnippets,
+        guidelinesByTool: registered.guidelinesByTool,
+        promptGuidelines: options.promptGuidelines,
+      });
+      // An empty section is one Pi leaves out, so this also clears a stale peer list.
+      options.sections.tools = sections.tools ?? "";
+      options.sections.rules = sections.rules;
+    }
+
+    // Path-match entries come from every catalogue the rendered prompt lists,
+    // read before the skill list is narrowed.
+    this.session.setActiveSkillEntries(
+      visibleSkillPromptEntries(
+        event.systemPrompt,
+        this.resolver,
+        agentName,
+        this.session.getPathNormalizer(),
+      ),
+    );
+    // Denials are judged on the list Pi renders `<skills>` from, not on the
+    // rendered prompt: that prompt predates this turn's tool changes, and on
+    // the turn `read`/`bash` return from a full denial it lists no catalogue.
+    options.skills = withoutDeniedSkills(
+      options.skills,
       this.resolver,
       agentName,
-      this.session.getPathNormalizer(),
     );
-    this.session.setActiveSkillEntries(skillPromptResult.entries);
-    return skillPromptResult.prompt !== event.systemPrompt
-      ? { systemPrompt: skillPromptResult.prompt }
-      : {};
+    return {};
   }
 
   /**
-   * Whether this node renders its own tool surface into the prompt.
+   * Whether this node states its own tool surface through `sections`.
    *
-   * Every node does except a root whose prompt Pi built from a custom one:
-   * there Pi writes no tool list or rules, and the operator's prompt is left
-   * as Pi built it. A subagent child's prompt is always a custom one, and its
-   * inherited identity carries no tool list, so it still states its own.
+   * Only a subagent child does: its prompt is always a custom one, under which
+   * Pi writes no tool list or rules, and its inherited identity carries none
+   * either. A root needs none — Pi renders its own from the narrowed active
+   * set, or, under an operator's custom prompt, deliberately writes none.
    */
-  private statesOwnToolSurface(
+  private isSubagentUnderCustomPrompt(
     event: BeforeAgentStartPayload,
     ctx: ExtensionContext,
   ): boolean {
-    return !hasCustomPrompt(event) || this.detector.isSubagent(ctx);
+    return hasCustomPrompt(event) && this.detector.isSubagent(ctx);
   }
 
   private observeToolSurface(
@@ -167,5 +181,5 @@ export class AgentPrepHandler {
  * test, so an empty string reads here the way it reads there: as none.
  */
 function hasCustomPrompt(event: BeforeAgentStartPayload): boolean {
-  return Boolean(event.systemPromptOptions?.customPrompt);
+  return Boolean(event.systemPromptOptions.customPrompt);
 }