@gotgenes/pi-permission-system 14.0.0 → 15.0.0

package/CHANGELOG.md

@@ -5,6 +5,29 @@ 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).
 
+## [15.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v14.0.1...pi-permission-system-v15.0.0) (2026-06-20)
+
+
+### ⚠ BREAKING CHANGES
+
+* the wire system prompt now lists the active tools (narrowed to the permission-allowed set) in the `Available tools:` section. Previously the permission system removed that section entirely, so the model saw no tool listing. Sessions that relied on the empty-listing behavior will now see the narrowed listing.
+
+### Bug Fixes
+
+* narrow the Available tools section to the active set instead of stripping it ([#437](https://github.com/gotgenes/pi-packages/issues/437)) ([dc0b97d](https://github.com/gotgenes/pi-packages/commit/dc0b97d7571d6f3a5cf0b0e15172f0d2d92b050a))
+
+
+### Documentation
+
+* describe Available-tools narrowing and drop the prompt-cache module ([#437](https://github.com/gotgenes/pi-packages/issues/437)) ([4112057](https://github.com/gotgenes/pi-packages/commit/411205711c5574aebb7add9edf9e035d21614946))
+
+## [14.0.1](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v14.0.0...pi-permission-system-v14.0.1) (2026-06-19)
+
+
+### Bug Fixes
+
+* **pi-permission-system:** strip shell comment lines from bash commands before matching ([d045591](https://github.com/gotgenes/pi-packages/commit/d0455915d6d4ce50534884639e516a9e1ef38976))
+
 ## [14.0.0](https://github.com/gotgenes/pi-packages/compare/pi-permission-system-v13.2.0...pi-permission-system-v14.0.0) (2026-06-17)
 
 

package/package.json

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

package/src/bash-arity.ts

@@ -184,3 +184,27 @@ export function prefix(tokens: string[]): string[] {
   // Unknown command — default arity 1.
   return [tokens[0]];
 }
+
+/**
+ * Remove shell comment lines from a bash command string.
+ *
+ * A comment line is one whose first non-whitespace character is `#`. Agents
+ * frequently prepend descriptive comments before the real command
+ * (e.g. `"# Check debug logs\nfind ..."`); such prefixes defeat wildcard
+ * pattern matching and session-approval suggestions, which tokenize the
+ * leading text. Stripping comment lines lets matching operate on the actual
+ * command.
+ *
+ * The original command is never returned: when every line is a comment (or
+ * the input is blank) an empty string is returned, and each caller applies
+ * its own fallback.
+ *
+ * @param command - Raw bash command, possibly multi-line.
+ * @returns The command with comment lines removed and surrounding whitespace
+ *   trimmed, or an empty string when nothing meaningful remains.
+ */
+export function stripBashCommentLines(command: string): string {
+  const lines = command.split("\n");
+  const meaningful = lines.filter((line) => !/^\s*#/.test(line));
+  return meaningful.join("\n").trim();
+}

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

@@ -2,10 +2,6 @@ import type {
   BeforeAgentStartEventResult,
   ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
-import {
-  createActiveToolsCacheKey,
-  createBeforeAgentStartPromptStateKey,
-} from "#src/before-agent-start-cache";
 import type { PermissionResolver } from "#src/permission-resolver";
 import type { PermissionSession } from "#src/permission-session";
 import { resolveSkillPromptEntries } from "#src/skill-prompt-sanitizer";
@@ -35,9 +31,14 @@ 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 byte-stable, rather
+ * than letting Pi reset to its skill-unfiltered base prompt on a cache hit.
+ *
  * Constructor deps:
  * - `session` — encapsulates all mutable session state and lifecycle operations
- * - `resolver` — owns permission-query surface: `getToolPermission`, `getPolicyCacheStamp`, skill check
+ * - `resolver` — owns permission-query surface: `getToolPermission`, skill check
  * - `toolRegistry` — Pi tool API subset (getActive + setActive)
  */
 export class AgentPrepHandler {
@@ -73,40 +74,21 @@ export class AgentPrepHandler {
       }
     }
 
-    const activeToolsCacheKey = createActiveToolsCacheKey(allowedTools);
-    this.session.activeToolsGate.runIfChanged(activeToolsCacheKey, () => {
-      this.toolRegistry.setActive(allowedTools);
-    });
+    this.toolRegistry.setActive(allowedTools);
 
-    const promptStateCacheKey = createBeforeAgentStartPromptStateKey({
+    const toolPromptResult = sanitizeAvailableToolsSection(
+      event.systemPrompt,
+      allowedTools,
+    );
+    const skillPromptResult = resolveSkillPromptEntries(
+      toolPromptResult.prompt,
+      this.resolver,
       agentName,
-      cwd: ctx.cwd,
-      permissionStamp: this.resolver.getPolicyCacheStamp(
-        agentName ?? undefined,
-      ),
-      systemPrompt: event.systemPrompt,
-      allowedToolNames: allowedTools,
-    });
-
-    const promptResult = this.session.promptStateGate.runIfChanged(
-      promptStateCacheKey,
-      () => {
-        const toolPromptResult = sanitizeAvailableToolsSection(
-          event.systemPrompt,
-          allowedTools,
-        );
-        const skillPromptResult = resolveSkillPromptEntries(
-          toolPromptResult.prompt,
-          this.resolver,
-          agentName,
-          ctx.cwd,
-        );
-        this.session.setActiveSkillEntries(skillPromptResult.entries);
-        return skillPromptResult.prompt !== event.systemPrompt
-          ? { systemPrompt: skillPromptResult.prompt }
-          : {};
-      },
+      ctx.cwd,
     );
-    return promptResult ?? {};
+    this.session.setActiveSkillEntries(skillPromptResult.entries);
+    return skillPromptResult.prompt !== event.systemPrompt
+      ? { systemPrompt: skillPromptResult.prompt }
+      : {};
   }
 }

package/src/input-normalizer.ts

@@ -1,3 +1,4 @@
+import { stripBashCommentLines } from "./bash-arity";
 import { getNonEmptyString, toRecord } from "./common";
 import { createMcpPermissionTargets } from "./mcp-targets";
 import { getPathPolicyValues, PATH_BEARING_TOOLS } from "./path-utils";
@@ -92,9 +93,14 @@ export function normalizeInput(
   if (toolName === "bash") {
     const record = toRecord(input);
     const command = typeof record.command === "string" ? record.command : "";
+    // Strip leading shell comment lines so pattern matching operates on the
+    // actual command, not a `# description` prefix agents often prepend.
+    // Fall back to the raw command when stripping leaves nothing, so an
+    // all-comment command still evaluates against its literal text.
+    const matchValue = stripBashCommentLines(command) || command;
     return {
       surface: "bash",
-      values: [command],
+      values: [matchValue],
       resultExtras: { command },
     };
   }

package/src/pattern-suggest.ts

@@ -1,4 +1,4 @@
-import { prefix } from "./bash-arity";
+import { prefix, stripBashCommentLines } from "./bash-arity";
 import { PATH_BEARING_TOOLS } from "./path-utils";
 import { deriveApprovalPattern } from "./session-rules";
 
@@ -26,11 +26,15 @@ export interface SessionApprovalSuggestion {
 export function suggestBashPattern(command: string): string {
   const trimmed = command.trim();
   if (!trimmed) return "";
-  const tokens = trimmed.split(/\s+/);
-  if (tokens.length === 1) return trimmed;
+  // Strip leading shell comment lines so the suggestion is based on the
+  // actual command, not a `# description` prefix agents often prepend.
+  const stripped = stripBashCommentLines(trimmed);
+  if (!stripped) return "";
+  const tokens = stripped.split(/\s+/);
+  if (tokens.length === 1) return stripped;
   const meaningful = prefix(tokens);
   if (meaningful.length >= tokens.length) {
-    return `${trimmed}*`;
+    return `${stripped}*`;
   }
   return `${meaningful.join(" ")} *`;
 }

package/src/permission-manager.ts

@@ -84,7 +84,6 @@ export interface ScopedPermissionManager {
   ): PermissionCheckResult;
   getToolPermission(toolName: string, agentName?: string): PermissionState;
   getConfigIssues(agentName?: string): string[];
-  getPolicyCacheStamp(agentName?: string): string;
 }
 
 export interface PermissionManagerOptions extends PolicyLoaderOptions {
@@ -144,10 +143,6 @@ export class PermissionManager implements ScopedPermissionManager {
     return this.loader.getResolvedPolicyPaths();
   }
 
-  getPolicyCacheStamp(agentName?: string): string {
-    return this.loader.getCacheStamp(agentName);
-  }
-
   private resolvePermissions(agentName?: string): ResolvedPermissions {
     const cacheKey = agentName ?? "__global__";
     const stamp = this.loader.getCacheStamp(agentName);

package/src/permission-resolver.ts

@@ -106,8 +106,4 @@ export class PermissionResolver implements ScopedPermissionResolver {
   getConfigIssues(agentName?: string): string[] {
     return this.permissionManager.getConfigIssues(agentName);
   }
-
-  getPolicyCacheStamp(agentName?: string): string {
-    return this.permissionManager.getPolicyCacheStamp(agentName);
-  }
 }

package/src/permission-session.ts

@@ -1,5 +1,4 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { CacheKeyGate } from "#src/cache-key-gate";
 import {
   getActiveAgentName,
   getActiveAgentNameFromSystemPrompt,
@@ -38,8 +37,6 @@ export class PermissionSession implements ToolCallGateInputs {
   private context: ExtensionContext | null = null;
   private skillEntries: SkillPromptEntry[] = [];
   private knownAgentName: string | null = null;
-  readonly activeToolsGate = new CacheKeyGate();
-  readonly promptStateGate = new CacheKeyGate();
 
   constructor(
     private readonly paths: ExtensionPaths,
@@ -83,38 +80,32 @@ export class PermissionSession implements ToolCallGateInputs {
   /**
    * Reset all mutable state for a new session.
    *
-   * Configures the injected PermissionManager for `ctx.cwd`, clears caches,
-   * skill entries, and activates the new context.
+   * Configures the injected PermissionManager for `ctx.cwd`, clears skill
+   * entries, and activates the new context.
    */
   resetForNewSession(ctx: ExtensionContext): void {
     this.permissionManager.configureForCwd(ctx.cwd);
     this.skillEntries = [];
-    this.activeToolsGate.reset();
-    this.promptStateGate.reset();
     this.activate(ctx);
   }
 
   /**
-   * Shut down the session: clear rules, caches, skill entries, and
-   * deactivate context + forwarding.
+   * Shut down the session: clear rules, skill entries, and deactivate
+   * context + forwarding.
    */
   shutdown(): void {
     this.sessionRules.clear();
     this.skillEntries = [];
-    this.activeToolsGate.reset();
-    this.promptStateGate.reset();
     this.deactivate();
   }
 
   /**
-   * Reload permission manager and clear caches for the current context.
+   * Reload permission manager and clear skill entries for the current context.
    * Used on config reload (e.g. `resources_discover` with reason "reload").
    */
   reload(): void {
     this.permissionManager.configureForCwd(this.context?.cwd);
     this.skillEntries = [];
-    this.activeToolsGate.reset();
-    this.promptStateGate.reset();
   }
 
   // ── Skill entries ──────────────────────────────────────────────────────

package/src/system-prompt-sanitizer.ts

@@ -135,16 +135,59 @@ function findSection(
   return { start, end };
 }
 
-function removeLineSection(
+/**
+ * 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[],
-  section: LineSection | null,
+  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: [...lines.slice(0, section.start), ...lines.slice(section.end)],
+    lines: [...before, header, ...filteredBody, ...after],
     removed: true,
   };
 }
@@ -212,15 +255,15 @@ export function sanitizeAvailableToolsSection(
     allowedToolNames.map((toolName) => toolName.trim()).filter(Boolean),
   );
   const normalizedLines = normalizePrompt(systemPrompt).split("\n");
-  const removedToolsSection = removeLineSection(
+  const narrowedToolsSection = narrowAvailableToolsSection(
     normalizedLines,
-    findSection(normalizedLines, AVAILABLE_TOOLS_SECTION_HEADER),
+    allowedTools,
   );
   const sanitizedGuidelines = sanitizeGuidelinesSection(
-    removedToolsSection.lines,
+    narrowedToolsSection.lines,
     allowedTools,
   );
-  const removed = removedToolsSection.removed || sanitizedGuidelines.removed;
+  const removed = narrowedToolsSection.removed || sanitizedGuidelines.removed;
 
   return {
     prompt: removed

package/test/bash-arity.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { ARITY, prefix } from "#src/bash-arity";
+import { ARITY, prefix, stripBashCommentLines } from "#src/bash-arity";
 
 describe("ARITY dictionary", () => {
   it("is exported as a plain object", () => {
@@ -104,3 +104,41 @@ describe("prefix", () => {
     expect(prefix(["ls", "-la", "/tmp"])).toEqual(["ls"]);
   });
 });
+
+describe("stripBashCommentLines", () => {
+  it("removes a single leading comment line", () => {
+    expect(
+      stripBashCommentLines("# Check debug logs\nfind /home -type f"),
+    ).toBe("find /home -type f");
+  });
+
+  it("removes multiple leading comment lines", () => {
+    expect(
+      stripBashCommentLines("# Step 1\n# Step 2\ngit status --short"),
+    ).toBe("git status --short");
+  });
+
+  it("returns empty string when all lines are comments", () => {
+    expect(stripBashCommentLines("# just a comment")).toBe("");
+  });
+
+  it("returns empty string for blank input", () => {
+    expect(stripBashCommentLines("")).toBe("");
+  });
+
+  it("returns the command unchanged when no comment lines are present", () => {
+    expect(stripBashCommentLines("grep -rn foo src/")).toBe(
+      "grep -rn foo src/",
+    );
+  });
+
+  it("trims surrounding whitespace from the result", () => {
+    expect(stripBashCommentLines("\n\n  ls -la  \n")).toBe("ls -la");
+  });
+
+  it("treats indented comment lines as comments", () => {
+    expect(stripBashCommentLines("    # indented comment\necho hi")).toBe(
+      "echo hi",
+    );
+  });
+});

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

@@ -171,7 +171,7 @@ describe("AgentPrepHandler.handle", () => {
     ]);
   });
 
-  it("calls setActive once across repeated calls with the same allowed tools", async () => {
+  it("calls setActive on every turn (no dedup gate)", async () => {
     const { handler, toolRegistry } = makeSetup({
       toolRegistry: {
         getActive: vi.fn().mockReturnValue(["read"]),
@@ -179,7 +179,40 @@ describe("AgentPrepHandler.handle", () => {
     });
     await handler.handle(makeEvent(), makeCtx());
     await handler.handle(makeEvent(), makeCtx());
-    expect(toolRegistry.setActive).toHaveBeenCalledOnce();
+    expect(toolRegistry.setActive).toHaveBeenCalledTimes(2);
+  });
+
+  it("filters a denied skill from the systemPrompt on every turn, not just the first", async () => {
+    const systemPrompt = [
+      "You are an assistant.",
+      "",
+      "<available_skills>",
+      "  <skill>",
+      "    <name>secret</name>",
+      "    <description>A denied skill</description>",
+      "    <location>/skills/secret/SKILL.md</location>",
+      "  </skill>",
+      "</available_skills>",
+    ].join("\n");
+    const { handler, permissionManager } = makeSetup();
+    vi.mocked(permissionManager.checkPermission).mockImplementation(
+      (surface) =>
+        surface === "skill"
+          ? makeCheckResult({ state: "deny" })
+          : makeCheckResult(),
+    );
+
+    const first = await handler.handle(makeEvent(systemPrompt), makeCtx());
+    const second = await handler.handle(makeEvent(systemPrompt), makeCtx());
+
+    expect(first).toHaveProperty("systemPrompt");
+    expect((first as { systemPrompt: string }).systemPrompt).not.toContain(
+      "secret",
+    );
+    expect(second).toHaveProperty("systemPrompt");
+    expect((second as { systemPrompt: string }).systemPrompt).not.toContain(
+      "secret",
+    );
   });
 
   it("returns empty object on repeated calls with unchanged inputs", async () => {
@@ -209,4 +242,76 @@ describe("AgentPrepHandler.handle", () => {
     const result = await handler.handle(makeEvent(prompt), makeCtx());
     expect(result).toEqual({});
   });
+
+  it("narrows a denied tool out of the Available tools listing without removing the section", async () => {
+    const systemPrompt = [
+      "Available tools:",
+      "- read: Read file contents",
+      "- bash: Run shell commands",
+    ].join("\n");
+    const { handler, permissionManager } = makeSetup({
+      toolRegistry: {
+        getActive: vi.fn().mockReturnValue(["read", "bash"]),
+      },
+    });
+    vi.mocked(permissionManager.getToolPermission).mockImplementation((tool) =>
+      tool === "bash" ? "deny" : "allow",
+    );
+
+    const result = await handler.handle(makeEvent(systemPrompt), makeCtx());
+
+    expect(result.systemPrompt).toBeDefined();
+    const out = result.systemPrompt ?? "";
+    expect(out).toContain("Available tools:");
+    expect(out).toContain("- read: Read file contents");
+    expect(out).not.toContain("- bash");
+  });
+
+  it("keeps the wire system prompt byte-stable across the tool-listing drift between turns", async () => {
+    const fullProse = [
+      "You are an assistant.",
+      "",
+      "Available tools:",
+      "- bash: Run shell commands",
+      "- read: Read file contents",
+      "- edit: Edit a file",
+      "- write: Write a file",
+      "",
+      "Guidelines:",
+      "- use bash for file operations like ls, rg, find",
+      "- use read to examine files instead of cat or sed.",
+      "- Be concise in your responses",
+    ].join("\n");
+    const narrowedProse = [
+      "You are an assistant.",
+      "",
+      "Available tools:",
+      "- read: Read file contents",
+      "- edit: Edit a file",
+      "- write: Write a file",
+      "",
+      "Guidelines:",
+      "- use read to examine files instead of cat or sed.",
+      "- Be concise in your responses",
+    ].join("\n");
+    const { handler, permissionManager } = makeSetup({
+      toolRegistry: {
+        getActive: vi.fn().mockReturnValue(["bash", "read", "edit", "write"]),
+      },
+    });
+    vi.mocked(permissionManager.getToolPermission).mockImplementation((tool) =>
+      tool === "bash" ? "deny" : "allow",
+    );
+
+    // Turn 1: Pi feeds the full default listing.
+    const first = await handler.handle(makeEvent(fullProse), makeCtx());
+    // Turn 2: Pi's setActive rebuild means the event now carries the narrowed
+    // listing, so the override the handler returns must still match turn 1.
+    const second = await handler.handle(makeEvent(narrowedProse), makeCtx());
+
+    const wire1 = first.systemPrompt ?? fullProse;
+    const wire2 = second.systemPrompt ?? narrowedProse;
+    expect(wire1).toBe(narrowedProse);
+    expect(wire2).toBe(narrowedProse);
+  });
 });

package/test/helpers/session-fixtures.ts

@@ -120,7 +120,6 @@ export function makeFakePermissionManager() {
       .fn<(toolName: string, agentName?: string) => PermissionState>()
       .mockReturnValue("allow"),
     getConfigIssues: vi.fn((): string[] => []),
-    getPolicyCacheStamp: vi.fn((): string => "stamp-1"),
   };
 }
 

package/test/input-normalizer.test.ts

@@ -198,6 +198,34 @@ describe("normalizeInput — non-MCP surfaces", () => {
       expect(result.values).toEqual([""]);
       expect(result.resultExtras).toEqual({ command: "" });
     });
+
+    it("strips leading comment lines from values but keeps original in resultExtras", () => {
+      const cmd = "# Check debug logs\nfind /home -path '*debug*' -type f";
+      const result = normalizeInput("bash", { command: cmd }, []);
+      expect(result.values).toEqual(["find /home -path '*debug*' -type f"]);
+      expect(result.resultExtras).toEqual({ command: cmd });
+    });
+
+    it("strips multiple comment lines", () => {
+      const cmd = "# Step 1\n# Step 2\ngit status --short";
+      const result = normalizeInput("bash", { command: cmd }, []);
+      expect(result.values).toEqual(["git status --short"]);
+    });
+
+    it("preserves command when no comment lines present", () => {
+      const result = normalizeInput(
+        "bash",
+        { command: "grep -rn foo src/" },
+        [],
+      );
+      expect(result.values).toEqual(["grep -rn foo src/"]);
+    });
+
+    it("falls back to original when all lines are comments", () => {
+      const cmd = "# just a comment";
+      const result = normalizeInput("bash", { command: cmd }, []);
+      expect(result.values).toEqual(["# just a comment"]);
+    });
   });
 
   describe("path-bearing tools (read, write, edit, grep, find, ls)", () => {

package/test/pattern-suggest.test.ts

@@ -42,6 +42,30 @@ describe("suggestBashPattern", () => {
       "docker compose up *",
     );
   });
+
+  it("strips leading comment lines and suggests based on the actual command", () => {
+    expect(
+      suggestBashPattern(
+        "# Check debug logs\nfind /home -path '*debug*' -type f",
+      ),
+    ).toBe("find *");
+  });
+
+  it("strips multiple leading comment lines", () => {
+    expect(suggestBashPattern("# Step 1\n# Step 2\ngit status --short")).toBe(
+      "git status *",
+    );
+  });
+
+  it("returns empty for comment-only input", () => {
+    expect(suggestBashPattern("# just a comment")).toBe("");
+  });
+
+  it("handles mixed comment and command lines", () => {
+    expect(suggestBashPattern("# description\nrm -rf ./build; echo done")).toBe(
+      "rm *",
+    );
+  });
 });
 
 describe("suggestMcpPattern", () => {

package/test/permission-manager-unified.test.ts

@@ -1586,7 +1586,6 @@ describe("PermissionManager — configureForCwd and agentDir option", () => {
     expect(typeof scoped.checkPermission).toBe("function");
     expect(typeof scoped.getToolPermission).toBe("function");
     expect(typeof scoped.getConfigIssues).toBe("function");
-    expect(typeof scoped.getPolicyCacheStamp).toBe("function");
   });
 
   it("construction with { agentDir } reads global config from getGlobalConfigPath(agentDir)", () => {

package/test/permission-resolver.test.ts

@@ -42,7 +42,6 @@ function makePermissionManager() {
       .fn<(toolName: string, agentName?: string) => PermissionState>()
       .mockReturnValue("allow"),
     getConfigIssues: vi.fn((): string[] => []),
-    getPolicyCacheStamp: vi.fn((): string => "stamp-1"),
   };
 }
 
@@ -263,17 +262,4 @@ describe("PermissionResolver", () => {
       expect(result).toEqual(["issue-1"]);
     });
   });
-
-  describe("getPolicyCacheStamp", () => {
-    it("delegates to permissionManager.getPolicyCacheStamp", () => {
-      const pm = makePermissionManager();
-      vi.mocked(pm.getPolicyCacheStamp).mockReturnValue("stamp-abc");
-      const { resolver } = makeResolver(pm);
-
-      const result = resolver.getPolicyCacheStamp("agent-1");
-
-      expect(pm.getPolicyCacheStamp).toHaveBeenCalledWith("agent-1");
-      expect(result).toBe("stamp-abc");
-    });
-  });
 });

package/test/permission-session.test.ts

@@ -103,23 +103,6 @@ describe("PermissionSession", () => {
       expect(pm.configureForCwd).toHaveBeenCalledWith("/new/project");
     });
 
-    it("clears cache keys", () => {
-      const { session } = createSession();
-      // Prime both gates with a key
-      session.activeToolsGate.runIfChanged("key-1", () => {});
-      session.promptStateGate.runIfChanged("key-2", () => {});
-
-      session.resetForNewSession(makeCtx());
-
-      // After reset, the same keys should run the effect again
-      const toolsEffect = vi.fn();
-      const promptEffect = vi.fn();
-      session.activeToolsGate.runIfChanged("key-1", toolsEffect);
-      session.promptStateGate.runIfChanged("key-2", promptEffect);
-      expect(toolsEffect).toHaveBeenCalledOnce();
-      expect(promptEffect).toHaveBeenCalledOnce();
-    });
-
     it("clears skill entries", () => {
       const { session } = createSession();
       session.setActiveSkillEntries([makeSkillEntry("test")]);
@@ -163,23 +146,6 @@ describe("PermissionSession", () => {
       expect(sessionRules.getRuleset()).toEqual([]);
     });
 
-    it("clears cache keys", () => {
-      const { session } = createSession();
-      // Prime both gates with a key
-      session.activeToolsGate.runIfChanged("k1", () => {});
-      session.promptStateGate.runIfChanged("k2", () => {});
-
-      session.shutdown();
-
-      // After shutdown, the same keys should run the effect again
-      const toolsEffect = vi.fn();
-      const promptEffect = vi.fn();
-      session.activeToolsGate.runIfChanged("k1", toolsEffect);
-      session.promptStateGate.runIfChanged("k2", promptEffect);
-      expect(toolsEffect).toHaveBeenCalledOnce();
-      expect(promptEffect).toHaveBeenCalledOnce();
-    });
-
     it("clears skill entries", () => {
       const { session } = createSession();
       session.setActiveSkillEntries([makeSkillEntry("s")]);
@@ -333,22 +299,12 @@ describe("PermissionSession", () => {
       expect(pm.configureForCwd).toHaveBeenCalledWith("/project");
     });
 
-    it("clears caches and skill entries", () => {
+    it("clears skill entries", () => {
       const { session } = createSession();
-      // Prime both gates with a key
-      session.activeToolsGate.runIfChanged("k1", () => {});
-      session.promptStateGate.runIfChanged("k2", () => {});
       session.setActiveSkillEntries([makeSkillEntry("s")]);
 
       session.reload();
 
-      // After reload, the same keys should run the effect again
-      const toolsEffect = vi.fn();
-      const promptEffect = vi.fn();
-      session.activeToolsGate.runIfChanged("k1", toolsEffect);
-      session.promptStateGate.runIfChanged("k2", promptEffect);
-      expect(toolsEffect).toHaveBeenCalledOnce();
-      expect(promptEffect).toHaveBeenCalledOnce();
       expect(session.getActiveSkillEntries()).toEqual([]);
     });
   });

package/test/system-prompt-sanitizer.test.ts

@@ -20,14 +20,26 @@ function prompt(...sections: string[]): string {
 }
 
 describe("sanitizeAvailableToolsSection — Available tools section", () => {
-  test("sets removed:true and strips the Available tools header", () => {
+  test("keeps allowed tool lines and the header, drops denied ones", () => {
     const input = prompt(
       availableToolsSection(["bash", "read"]),
       "Other content",
     );
-    const result = sanitizeAvailableToolsSection(input, ["bash", "read"]);
+    const result = sanitizeAvailableToolsSection(input, ["read"]);
     expect(result.removed).toBe(true);
-    expect(result.prompt).not.toContain("Available tools:");
+    expect(result.prompt).toContain("Available tools:");
+    expect(result.prompt).toContain("- read");
+    expect(result.prompt).not.toContain("- bash");
+  });
+
+  test("leaves the section untouched when every tool is allowed", () => {
+    const input = prompt(
+      availableToolsSection(["bash", "read"]),
+      "Other content",
+    );
+    const result = sanitizeAvailableToolsSection(input, ["bash", "read"]);
+    expect(result.removed).toBe(false);
+    expect(result.prompt).toBe(input);
   });
 
   // Bug #33: findSection extends to lines.length when no subsequent recognised
@@ -37,7 +49,18 @@ describe("sanitizeAvailableToolsSection — Available tools section", () => {
       availableToolsSection(["bash", "read"]),
       "Other content",
     );
-    const result = sanitizeAvailableToolsSection(input, ["bash", "read"]);
+    const result = sanitizeAvailableToolsSection(input, ["read"]);
+    expect(result.prompt).toContain("Other content");
+  });
+
+  test("removes the whole section when no tool is allowed", () => {
+    const input = prompt(
+      availableToolsSection(["bash", "read"]),
+      "Other content",
+    );
+    const result = sanitizeAvailableToolsSection(input, []);
+    expect(result.removed).toBe(true);
+    expect(result.prompt).not.toContain("Available tools:");
     expect(result.prompt).toContain("Other content");
   });
 
@@ -48,15 +71,18 @@ describe("sanitizeAvailableToolsSection — Available tools section", () => {
     expect(result.prompt).toBe(input);
   });
 
-  test("removes only the tools section and leaves other sections intact", () => {
-    const input = prompt(
-      "Preamble text",
-      availableToolsSection(["bash"]),
-      guidelinesSection(["use bash for file operations like ls, rg, find"]),
-    );
-    const result = sanitizeAvailableToolsSection(input, ["bash"]);
-    expect(result.prompt).not.toContain("Available tools:");
-    expect(result.prompt).toContain("Guidelines:");
+  test("keeps non-tool boilerplate prose near the section", () => {
+    const input = [
+      "Available tools:",
+      "- read: Read file contents",
+      "- bash: Run shell commands",
+      "",
+      "In addition to the tools above, you may have access to other custom tools depending on the project.",
+    ].join("\n");
+    const result = sanitizeAvailableToolsSection(input, ["read"]);
+    expect(result.prompt).toContain("- read: Read file contents");
+    expect(result.prompt).not.toContain("- bash: Run shell commands");
+    expect(result.prompt).toContain("In addition to the tools above");
   });
 
   test("returns original prompt reference unchanged when nothing is removed", () => {
@@ -64,6 +90,47 @@ describe("sanitizeAvailableToolsSection — Available tools section", () => {
     const result = sanitizeAvailableToolsSection(input, []);
     expect(result.prompt).toBe(input);
   });
+
+  test("narrowing the full listing yields the already-narrowed listing (cache byte-stability)", () => {
+    const allowed = ["read", "edit", "write"];
+    const fullProse = [
+      "You are an assistant.",
+      "",
+      "Available tools:",
+      "- bash: Run shell commands",
+      "- read: Read file contents",
+      "- edit: Edit a file",
+      "- write: Write a file",
+      "",
+      "Guidelines:",
+      "- use bash for file operations like ls, rg, find",
+      "- use read to examine files instead of cat or sed.",
+      "- Be concise in your responses",
+    ].join("\n");
+    const narrowedProse = [
+      "You are an assistant.",
+      "",
+      "Available tools:",
+      "- read: Read file contents",
+      "- edit: Edit a file",
+      "- write: Write a file",
+      "",
+      "Guidelines:",
+      "- use read to examine files instead of cat or sed.",
+      "- Be concise in your responses",
+    ].join("\n");
+
+    const fromFull = sanitizeAvailableToolsSection(fullProse, allowed).prompt;
+    const fromNarrowed = sanitizeAvailableToolsSection(
+      narrowedProse,
+      allowed,
+    ).prompt;
+
+    // Idempotent on the already-narrowed input Pi feeds back on later turns.
+    expect(fromNarrowed).toBe(narrowedProse);
+    // Turn 1 (full) and turn 2+ (narrowed) produce identical wire bytes.
+    expect(fromFull).toBe(fromNarrowed);
+  });
 });
 
 describe("sanitizeAvailableToolsSection — Guidelines section", () => {
@@ -208,18 +275,18 @@ describe("sanitizeAvailableToolsSection — findSection boundary edge cases", ()
     expect(result.prompt).toContain("Important user note");
   });
 
-  test("section at EOF with no trailing content still works", () => {
+  test("section at EOF is removed entirely when no tool is allowed", () => {
     const input = availableToolsSection(["bash", "read"]);
-    const result = sanitizeAvailableToolsSection(input, ["bash", "read"]);
+    const result = sanitizeAvailableToolsSection(input, []);
     expect(result.removed).toBe(true);
     expect(result.prompt).toBe("");
   });
 
-  test("section followed by blank lines then prose — prose survives", () => {
+  test("section followed by blank lines then prose — prose survives removal", () => {
     const input = ["Available tools:", "- bash", "", "", "Custom note"].join(
       "\n",
     );
-    const result = sanitizeAvailableToolsSection(input, ["bash"]);
+    const result = sanitizeAvailableToolsSection(input, []);
     expect(result.removed).toBe(true);
     expect(result.prompt).toContain("Custom note");
     expect(result.prompt).not.toContain("Available tools:");
@@ -230,7 +297,7 @@ describe("sanitizeAvailableToolsSection — findSection boundary edge cases", ()
 // Moved from permission-system.test.ts catch-all (#342)
 // ---------------------------------------------------------------------------
 
-test("System prompt sanitizer removes the Available tools section and surrounding boilerplate", () => {
+test("System prompt sanitizer keeps the active tools in the Available tools section", () => {
   const prompt = [
     "Available tools:",
     "- read: Read file contents",
@@ -245,11 +312,31 @@ test("System prompt sanitizer removes the Available tools section and surroundin
 
   const result = sanitizeAvailableToolsSection(prompt, ["read", "mcp"]);
 
-  expect(result.removed).toBe(true);
-  expect(result.prompt).not.toContain("Available tools:");
-  expect(result.prompt).not.toContain("In addition to the tools above");
+  expect(result.removed).toBe(false);
+  expect(result.prompt).toContain("Available tools:");
+  expect(result.prompt).toContain("- read: Read file contents");
+  expect(result.prompt).toContain("- mcp: Discover");
+  expect(result.prompt).toContain("In addition to the tools above");
   expect(result.prompt).toMatch(/Guidelines:/);
-  expect(result.prompt).toMatch(/Use mcp for MCP discovery first/i);
+});
+
+test("System prompt sanitizer drops a denied tool's line but keeps the section", () => {
+  const prompt = [
+    "Available tools:",
+    "- read: Read file contents",
+    "- mcp: Discover, inspect, and call MCP tools across configured servers",
+    "",
+    "Guidelines:",
+    "- Use mcp for MCP discovery first: search by capability, describe one exact tool name, then call it.",
+    "- Be concise in your responses",
+  ].join("\n");
+
+  const result = sanitizeAvailableToolsSection(prompt, ["read"]);
+
+  expect(result.removed).toBe(true);
+  expect(result.prompt).toContain("Available tools:");
+  expect(result.prompt).toContain("- read: Read file contents");
+  expect(result.prompt).not.toContain("- mcp: Discover");
 });
 
 test("System prompt sanitizer removes denied tool guidelines while keeping global guidance", () => {

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

@@ -1,37 +0,0 @@
-export interface BeforeAgentStartPromptStateInput {
-  agentName: string | null;
-  cwd: string;
-  permissionStamp: string;
-  systemPrompt: string;
-  allowedToolNames: readonly string[];
-}
-
-function normalizeAgentName(agentName: string | null): string {
-  return agentName ?? "";
-}
-
-function normalizePrompt(prompt: string): string {
-  return prompt.replace(/\r\n/g, "\n");
-}
-
-function createCacheKey(parts: readonly unknown[]): string {
-  return JSON.stringify(parts);
-}
-
-export function createActiveToolsCacheKey(
-  allowedToolNames: readonly string[],
-): string {
-  return createCacheKey(allowedToolNames);
-}
-
-export function createBeforeAgentStartPromptStateKey(
-  input: BeforeAgentStartPromptStateInput,
-): string {
-  return createCacheKey([
-    normalizeAgentName(input.agentName),
-    input.cwd,
-    input.permissionStamp,
-    createActiveToolsCacheKey(input.allowedToolNames),
-    normalizePrompt(input.systemPrompt),
-  ]);
-}

package/src/cache-key-gate.ts

@@ -1,32 +0,0 @@
-/**
- * Owns a previous cache key and conditionally runs an effect when the key changes.
- *
- * Encapsulates the prev !== next comparison that previously lived in three places:
- * the session's inline `!==`, the handler's ask-then-tell orchestration, and the
- * (test-only-alive) `shouldApplyCachedAgentStartState` free function.
- *
- * Semantics:
- * - On a changed key: runs `effect`, commits `nextKey`, returns the effect's value.
- * - On an unchanged key: skips `effect`, returns `undefined`.
- * - `reset()` re-arms the gate (used by session lifecycle: `resetForNewSession`,
- *   `shutdown`, `reload`).
- *
- * Commit ordering is run-then-commit: the key is saved only after `effect` returns.
- * If `effect` throws, the key stays uncommitted and the next call retries.
- */
-export class CacheKeyGate {
-  private previousKey: string | null = null;
-
-  runIfChanged<T>(nextKey: string, effect: () => T): T | undefined {
-    if (this.previousKey === nextKey) {
-      return undefined;
-    }
-    const result = effect();
-    this.previousKey = nextKey;
-    return result;
-  }
-
-  reset(): void {
-    this.previousKey = null;
-  }
-}

package/test/before-agent-start-cache.test.ts

@@ -1,59 +0,0 @@
-import { writeFileSync } from "node:fs";
-import { expect, test } from "vitest";
-import { createBeforeAgentStartPromptStateKey } from "#src/before-agent-start-cache";
-import { createManager } from "#test/helpers/manager-harness";
-
-test("Before-agent-start prompt cache invalidates on permission changes while runtime enforcement stays authoritative", () => {
-  const { manager, globalConfigPath, cleanup } = createManager({
-    permission: { "*": "allow", write: "deny" },
-  });
-
-  try {
-    const baselineStamp = manager.getPolicyCacheStamp();
-    const baselineKey = createBeforeAgentStartPromptStateKey({
-      agentName: null,
-      cwd: "C:/workspace/project",
-      permissionStamp: baselineStamp,
-      systemPrompt: "Available tools:\n- read\n- write",
-      allowedToolNames: ["read"],
-    });
-
-    expect(manager.checkPermission("write", {}, undefined).state).toBe("deny");
-
-    const updatedConfig = `${JSON.stringify(
-      { permission: { "*": "allow", write: "allow" } },
-      null,
-      2,
-    )}\n`;
-
-    let updatedStamp = baselineStamp;
-    for (
-      let attempt = 0;
-      attempt < 10 && updatedStamp === baselineStamp;
-      attempt += 1
-    ) {
-      const waitUntil = Date.now() + 2;
-      while (Date.now() < waitUntil) {
-        // Wait for the filesystem timestamp granularity to advance.
-      }
-
-      writeFileSync(globalConfigPath, updatedConfig, "utf8");
-      updatedStamp = manager.getPolicyCacheStamp();
-    }
-
-    expect(updatedStamp).not.toBe(baselineStamp);
-
-    const invalidatedKey = createBeforeAgentStartPromptStateKey({
-      agentName: null,
-      cwd: "C:/workspace/project",
-      permissionStamp: updatedStamp,
-      systemPrompt: "Available tools:\n- read\n- write",
-      allowedToolNames: ["read", "write"],
-    });
-
-    expect(invalidatedKey).not.toBe(baselineKey);
-    expect(manager.checkPermission("write", {}, undefined).state).toBe("allow");
-  } finally {
-    cleanup();
-  }
-});

package/test/cache-key-gate.test.ts

@@ -1,85 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-
-import { CacheKeyGate } from "#src/cache-key-gate";
-
-describe("CacheKeyGate", () => {
-  describe("runIfChanged", () => {
-    it("runs the effect and returns its value when the key is new (null previous)", () => {
-      const gate = new CacheKeyGate();
-      const effect = vi.fn(() => "result");
-
-      const result = gate.runIfChanged("key-a", effect);
-
-      expect(effect).toHaveBeenCalledOnce();
-      expect(result).toBe("result");
-    });
-
-    it("commits the key so a second call with the same key skips the effect", () => {
-      const gate = new CacheKeyGate();
-      const effect = vi.fn(() => "result");
-
-      gate.runIfChanged("key-a", effect);
-      const result = gate.runIfChanged("key-a", effect);
-
-      expect(effect).toHaveBeenCalledOnce();
-      expect(result).toBeUndefined();
-    });
-
-    it("runs the effect when the key changes", () => {
-      const gate = new CacheKeyGate();
-      const effect = vi.fn((n: number) => n);
-
-      gate.runIfChanged("key-a", () => effect(1));
-      const result = gate.runIfChanged("key-b", () => effect(2));
-
-      expect(effect).toHaveBeenCalledTimes(2);
-      expect(result).toBe(2);
-    });
-
-    it("returns undefined when the key is unchanged", () => {
-      const gate = new CacheKeyGate();
-      gate.runIfChanged("key-a", vi.fn());
-
-      const result = gate.runIfChanged("key-a", vi.fn());
-
-      expect(result).toBeUndefined();
-    });
-
-    it("does not commit the key if the effect throws", () => {
-      const gate = new CacheKeyGate();
-      const throwing = vi.fn(() => {
-        throw new Error("oops");
-      });
-      const fallback = vi.fn(() => "ok");
-
-      expect(() => gate.runIfChanged("key-a", throwing)).toThrow("oops");
-
-      // Same key should run again since the first call threw
-      gate.runIfChanged("key-a", fallback);
-      expect(fallback).toHaveBeenCalledOnce();
-    });
-  });
-
-  describe("reset", () => {
-    it("re-arms the gate so the same key runs again on the next call", () => {
-      const gate = new CacheKeyGate();
-      const effect = vi.fn(() => "ok");
-
-      gate.runIfChanged("key-a", effect);
-      gate.reset();
-      gate.runIfChanged("key-a", effect);
-
-      expect(effect).toHaveBeenCalledTimes(2);
-    });
-
-    it("is idempotent when called on a fresh gate", () => {
-      const gate = new CacheKeyGate();
-      gate.reset();
-      const effect = vi.fn(() => "ok");
-
-      gate.runIfChanged("key-a", effect);
-
-      expect(effect).toHaveBeenCalledOnce();
-    });
-  });
-});