@gotgenes/pi-permission-system 34.0.1 → 35.0.0

package/CHANGELOG.md

@@ -5,6 +5,17 @@ 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).
 
+## [35.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v34.0.1...pi-permission-system-v35.0.0) (2026-09-26)
+
+
+### Features
+
+* **pi-permission-system:** **breaking:** stop appending a tool list and rules to an operator's custom system prompt ([672a64c](https://github.com/gotgenes/pi-packages/commit/672a64c0844ec2fff8e113130109919623158107)), closes [#980](https://github.com/gotgenes/pi-packages/issues/980)
+
+### Documentation
+
+* **pi-permission-system:** record that a custom system prompt gets no appended tool surface ([7e0816d](https://github.com/gotgenes/pi-packages/commit/7e0816d28ab5377de011b5558b034c5b2bdaca4d))
+
 ## [34.0.1](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v34.0.0...pi-permission-system-v34.0.1) (2026-09-26)
 
 

package/docs/configuration.md

@@ -1246,11 +1246,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, 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 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                                                                                                                                                 |
 
 Additional behaviors:
 
@@ -1262,8 +1262,10 @@ Additional behaviors:
 - 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, whether or not anything is denied.
-  Only the copies pi wrote are removed: a custom system prompt (`.pi/SYSTEM.md`, `~/.pi/agent/SYSTEM.md`, `--system-prompt`) keeps its own text untouched, sections and all, because pi writes no tool surface of its own under one — so a prompt that lists tools itself is shown alongside this session's block rather than replaced by it.
+  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.
+  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 policy change is an intentional cache transition, as a mid-session agent switch already is.

package/package.json

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

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

@@ -2,6 +2,7 @@ import type {
   BeforeAgentStartEventResult,
   ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
+import type { SubagentDetector } from "#src/authority/subagent-detection";
 import { resolveSkillPromptEntries } from "#src/exposure/skill-prompt-sanitizer";
 import {
   type RegisteredTools,
@@ -23,7 +24,8 @@ interface BeforeAgentStartPayload {
    * 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.
+   * 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.
    */
@@ -60,6 +62,9 @@ export function shouldExposeTool(
  *
  * 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.
  *
  * Constructor deps:
  * - `turnPrep` — brings the node up to date for the turn before anything reads
@@ -68,6 +73,8 @@ export function shouldExposeTool(
  * - `resolver` — owns permission-query surface: `isToolFullyDenied`, skill check
  * - `toolRegistry` — Pi tool API subset (getAll + getActive + setActive)
  * - `logger` — records each change to the effective tool surface
+ * - `detector` — tells a subagent child from a root, which decides whether a
+ *   custom prompt gets this node's tool surface
  *
  * The active set is recomputed from the session's pre-filter tool surface
  * every turn, so relaxing a rule restores the tool it had withheld (#873).
@@ -79,6 +86,7 @@ export class AgentPrepHandler {
     private readonly resolver: PermissionResolver,
     private readonly toolRegistry: ToolRegistry,
     private readonly logger: DebugLogger,
+    private readonly detector: SubagentDetector,
   ) {}
 
   // eslint-disable-next-line @typescript-eslint/require-await
@@ -108,15 +116,15 @@ export class AgentPrepHandler {
       });
     }
 
-    const toolSurfacePrompt = renderToolSurface(event.systemPrompt, {
-      allowedTools,
-      toolSnippets: event.systemPromptOptions?.toolSnippets ?? {},
-      guidelinesByTool: registered.guidelinesByTool,
-      promptGuidelines: event.systemPromptOptions?.promptGuidelines ?? [],
-      // Pi's own `if (customPrompt)` test, so an empty string reads here the
-      // way it reads there: as no custom prompt at all.
-      piAuthoredPreamble: !event.systemPromptOptions?.customPrompt,
-    });
+    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,
       this.resolver,
@@ -129,6 +137,21 @@ export class AgentPrepHandler {
       : {};
   }
 
+  /**
+   * Whether this node renders its own tool surface into the prompt.
+   *
+   * 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.
+   */
+  private statesOwnToolSurface(
+    event: BeforeAgentStartPayload,
+    ctx: ExtensionContext,
+  ): boolean {
+    return !hasCustomPrompt(event) || this.detector.isSubagent(ctx);
+  }
+
   private observeToolSurface(
     registered: RegisteredTools,
   ): ToolSurfaceObservation {
@@ -138,3 +161,11 @@ export class AgentPrepHandler {
     };
   }
 }
+
+/**
+ * Whether Pi built the prompt from a custom one, by Pi's own `if (customPrompt)`
+ * test, so an empty string reads here the way it reads there: as none.
+ */
+function hasCustomPrompt(event: BeforeAgentStartPayload): boolean {
+  return Boolean(event.systemPromptOptions?.customPrompt);
+}

package/src/index.ts

@@ -344,6 +344,7 @@ export default function piPermissionSystemExtension(pi: ExtensionAPI): void {
     resolver,
     toolRegistry,
     logger,
+    subagentDetection,
   );
 
   const gateRunner = new GateRunner(