pi-permission-system 0.3.1 → 0.4.1

package/CHANGELOG.md

@@ -5,6 +5,31 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.1] - 2026-04-01
+
+### Changed
+- Updated npm keywords for improved discoverability (`pi-coding-agent`, `coding-agent`, `access-control`, `authorization`, `security`)
+- Updated README permission prompt example image
+- Added Related Pi Extensions cross-linking section to README
+
+## [0.4.0] - 2026-04-01
+
+### Added
+- System prompt sanitizer now removes inactive tool guidelines from the `Guidelines:` section
+- Guideline filtering based on allowed tools (e.g., removes task/mcp/bash/write guidance when tools are denied)
+- New `TOOL_GUIDELINE_RULES` configuration for extensible guideline filtering
+- Helper functions: `findSection()`, `removeLineSection()`, `sanitizeGuidelinesSection()`
+
+### Changed
+- Updated `@mariozechner/pi-coding-agent` and `@mariozechner/pi-tui` peer dependencies to ^0.64.0
+- Updated `@sinclair/typebox` peer dependency to ^0.34.49
+- Refactored system prompt sanitizer to handle both `Available tools:` and `Guidelines:` sections
+
+### Tests
+- Added tests for system prompt sanitizer removing Available tools section
+- Added tests for guideline filtering based on allowed tools
+- Added tests for inactive built-in write/edit/task/mcp guidance removal
+
 ## [0.3.1] - 2026-03-24
 
 ### Added

package/README.md

@@ -1,11 +1,12 @@
 # 🔐 pi-permission-system
 
-[![Version](https://img.shields.io/badge/version-0.3.1-blue.svg)](package.json)
+[![Version](https://img.shields.io/badge/version-0.4.1-blue.svg)](package.json)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
 Permission enforcement extension for the Pi coding agent that provides centralized, deterministic permission gates for tool, bash, MCP, skill, and special operations.
 
-![Permission Prompt Example](https://raw.githubusercontent.com/MasuRii/pi-permission-system/main/asset/pi-permission-system.png)
+<img width="1360" height="752" alt="image" src="https://github.com/user-attachments/assets/3e85190a-17fa-4d94-ac8e-efa54337df5d" />
+
 
 ## Features
 
@@ -473,6 +474,13 @@ npm run check    # Run lint + test
 
 ---
 
+## Related Pi Extensions
+
+- [pi-multi-auth](https://github.com/MasuRii/pi-multi-auth) — Multi-provider credential management and quota-aware rotation
+- [pi-tool-display](https://github.com/MasuRii/pi-tool-display) — Compact tool rendering and diff visualization
+- [pi-rtk-optimizer](https://github.com/MasuRii/pi-rtk-optimizer) — RTK command rewriting and output compaction
+- [pi-MUST-have-extension](https://github.com/MasuRii/pi-MUST-have-extension) — RFC 2119 keyword normalization for prompts
+
 ## License
 
 [MIT](LICENSE)

package/package.json

@@ -1,61 +1,65 @@
-{
-  "name": "pi-permission-system",
-  "version": "0.3.1",
-  "description": "Permission enforcement extension for the Pi coding agent.",
-  "type": "module",
-  "main": "./index.ts",
-  "exports": {
-    ".": "./index.ts"
-  },
-  "files": [
-    "index.ts",
-    "src",
-    "config.json",
-    "config/config.example.json",
-    "schemas/permissions.schema.json",
-    "asset",
-    "README.md",
-    "CHANGELOG.md",
-    "LICENSE"
-  ],
-  "scripts": {
-    "build": "npx --yes -p typescript@5.7.3 tsc -p tsconfig.json --noCheck",
-    "lint": "npm run build",
-    "test": "bun ./src/test.ts && bun ./src/config-modal-test.ts",
-    "check": "npm run lint && npm run test"
-  },
-  "keywords": [
-    "pi-package",
-    "pi",
-    "pi-extension",
-    "permissions",
-    "policy",
-    "coding-agent"
-  ],
-  "author": "MasuRii",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/MasuRii/pi-permission-system.git"
-  },
-  "homepage": "https://github.com/MasuRii/pi-permission-system#readme",
-  "bugs": {
-    "url": "https://github.com/MasuRii/pi-permission-system/issues"
-  },
-  "engines": {
-    "node": ">=20"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "pi": {
-    "extensions": [
-      "./index.ts"
-    ]
-  },
-  "peerDependencies": {
-    "@mariozechner/pi-coding-agent": "^0.62.0",
-    "@mariozechner/pi-tui": "^0.62.0",
-    "@sinclair/typebox": "^0.34.48"
-  }
-}
+{
+  "name": "pi-permission-system",
+  "version": "0.4.1",
+  "description": "Permission enforcement extension for the Pi coding agent.",
+  "type": "module",
+  "main": "./index.ts",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "files": [
+    "index.ts",
+    "src",
+    "config.json",
+    "config/config.example.json",
+    "schemas/permissions.schema.json",
+    "asset",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "npx --yes -p typescript@5.7.3 tsc -p tsconfig.json --noCheck",
+    "lint": "npm run build",
+    "test": "bun ./src/test.ts && bun ./src/config-modal-test.ts",
+    "check": "npm run lint && npm run test"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "pi-coding-agent",
+    "coding-agent",
+    "permissions",
+    "policy",
+    "access-control",
+    "authorization",
+    "security"
+  ],
+  "author": "MasuRii",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MasuRii/pi-permission-system.git"
+  },
+  "homepage": "https://github.com/MasuRii/pi-permission-system#readme",
+  "bugs": {
+    "url": "https://github.com/MasuRii/pi-permission-system/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "^0.64.0",
+    "@mariozechner/pi-tui": "^0.64.0",
+    "@sinclair/typebox": "^0.34.49"
+  }
+}

package/src/system-prompt-sanitizer.ts

@@ -3,18 +3,59 @@ export interface SanitizeSystemPromptResult {
   removed: boolean;
 }
 
-type ToolPromptEntry = {
-  name: string;
-  lines: string[];
-};
-
-type ToolPromptSection = {
+type LineSection = {
   start: number;
   end: number;
-  entries: ToolPromptEntry[];
+};
+
+type GuidelineRule = {
+  matches: (guideline: string) => boolean;
+  shouldKeep: (allowedTools: ReadonlySet<string>) => boolean;
 };
 
 const AVAILABLE_TOOLS_SECTION_HEADER = "Available tools:";
+const GUIDELINES_SECTION_HEADER = "Guidelines:";
+
+const TOOL_GUIDELINE_RULES: readonly GuidelineRule[] = [
+  {
+    matches: (guideline) => guideline === "use bash for file operations like ls, rg, find",
+    shouldKeep: (allowedTools) => allowedTools.has("bash"),
+  },
+  {
+    matches: (guideline) => guideline === "prefer grep/find/ls tools over bash for file exploration (faster, respects .gitignore)",
+    shouldKeep: (allowedTools) =>
+      allowedTools.has("bash") && (allowedTools.has("grep") || allowedTools.has("find") || allowedTools.has("ls")),
+  },
+  {
+    matches: (guideline) =>
+      guideline === "use read to examine files before editing. you must use this tool instead of cat or sed."
+        || guideline === "use read to examine files instead of cat or sed.",
+    shouldKeep: (allowedTools) => allowedTools.has("read"),
+  },
+  {
+    matches: (guideline) => guideline === "use edit for precise changes (old text must match exactly)",
+    shouldKeep: (allowedTools) => allowedTools.has("edit"),
+  },
+  {
+    matches: (guideline) => guideline === "use write only for new files or complete rewrites",
+    shouldKeep: (allowedTools) => allowedTools.has("write"),
+  },
+  {
+    matches: (guideline) =>
+      guideline === "when summarizing your actions, output plain text directly - do not use cat or bash to display what you did",
+    shouldKeep: (allowedTools) => allowedTools.has("edit") || allowedTools.has("write"),
+  },
+  {
+    matches: (guideline) =>
+      guideline === "use task when work should be delegated to one or more specialized agents instead of handled entirely in the current session.",
+    shouldKeep: (allowedTools) => allowedTools.has("task"),
+  },
+  {
+    matches: (guideline) =>
+      guideline === "use mcp for mcp discovery first: search by capability, describe one exact tool name, then call it.",
+    shouldKeep: (allowedTools) => allowedTools.has("mcp"),
+  },
+];
 
 function normalizePrompt(prompt: string): string {
   return (prompt || "").replace(/\r\n/g, "\n");
@@ -24,77 +65,89 @@ function collapseExtraBlankLines(text: string): string {
   return text.replace(/\n{3,}/g, "\n\n").trimEnd();
 }
 
-function parseAvailableToolsSection(systemPrompt: string): ToolPromptSection | null {
-  const lines = normalizePrompt(systemPrompt).split("\n");
-  const start = lines.findIndex((line) => line.trim() === AVAILABLE_TOOLS_SECTION_HEADER);
+function normalizeGuidelineText(line: string): string {
+  return line.trim().replace(/^[-*]\s+/, "").replace(/\s+/g, " ").toLowerCase();
+}
+
+function isTopLevelSectionHeader(line: string): boolean {
+  const trimmed = line.trim();
+  return trimmed.length > 0 && trimmed.endsWith(":") && !trimmed.startsWith("-");
+}
+
+function findSection(lines: readonly string[], header: string): LineSection | null {
+  const start = lines.findIndex((line) => line.trim() === header);
   if (start === -1) {
     return null;
   }
 
-  const entries: ToolPromptEntry[] = [];
-  let index = start + 1;
-
-  while (index < lines.length) {
-    const line = lines[index];
-    const trimmed = line.trim();
-
-    if (!trimmed) {
-      index += 1;
-      continue;
-    }
-
-    if (!trimmed.startsWith("- ")) {
+  let end = lines.length;
+  for (let index = start + 1; index < lines.length; index += 1) {
+    if (isTopLevelSectionHeader(lines[index])) {
+      end = index;
       break;
     }
+  }
 
-    const match = trimmed.match(/^\-\s+([^:]+):/);
-    if (!match) {
-      break;
-    }
+  return { start, end };
+}
+
+function removeLineSection(lines: readonly string[], section: LineSection | null): { lines: string[]; removed: boolean } {
+  if (!section) {
+    return { lines: [...lines], removed: false };
+  }
 
-    const entryLines = [line];
-    index += 1;
+  return {
+    lines: [...lines.slice(0, section.start), ...lines.slice(section.end)],
+    removed: true,
+  };
+}
 
-    while (index < lines.length) {
-      const nextLine = lines[index];
-      const nextTrimmed = nextLine.trim();
+function shouldKeepGuideline(line: string, allowedTools: ReadonlySet<string>): boolean {
+  const normalized = normalizeGuidelineText(line);
 
-      if (!nextTrimmed) {
-        entryLines.push(nextLine);
-        index += 1;
-        continue;
-      }
+  for (const rule of TOOL_GUIDELINE_RULES) {
+    if (rule.matches(normalized)) {
+      return rule.shouldKeep(allowedTools);
+    }
+  }
 
-      if (nextTrimmed.startsWith("- ")) {
-        break;
-      }
+  return true;
+}
 
-      if (!/^\s/.test(nextLine)) {
-        break;
-      }
+function sanitizeGuidelinesSection(lines: readonly string[], allowedTools: ReadonlySet<string>): { lines: string[]; removed: boolean } {
+  const section = findSection(lines, GUIDELINES_SECTION_HEADER);
+  if (!section) {
+    return { lines: [...lines], removed: false };
+  }
 
-      entryLines.push(nextLine);
-      index += 1;
+  const before = lines.slice(0, section.start + 1);
+  const after = lines.slice(section.end);
+  const body = lines.slice(section.start + 1, section.end);
+  const filteredBody = body.filter((line) => {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith("- ")) {
+      return true;
     }
 
-    while (entryLines.length > 0 && entryLines[entryLines.length - 1].trim().length === 0) {
-      entryLines.pop();
-    }
+    return shouldKeepGuideline(line, allowedTools);
+  });
 
-    entries.push({
-      name: match[1].trim(),
-      lines: entryLines,
-    });
+  const removed = filteredBody.length !== body.length;
+  if (!removed) {
+    return { lines: [...lines], removed: false };
   }
 
-  if (entries.length === 0) {
-    return null;
+  const hasBullet = filteredBody.some((line) => line.trim().startsWith("- "));
+  if (!hasBullet) {
+    return {
+      lines: [...lines.slice(0, section.start), ...after],
+      removed: true,
+    };
   }
 
   return {
-    start,
-    end: index,
-    entries,
+    lines: [...before, ...filteredBody, ...after],
+    removed: true,
   };
 }
 
@@ -102,29 +155,14 @@ export function sanitizeAvailableToolsSection(
   systemPrompt: string,
   allowedToolNames: readonly string[],
 ): SanitizeSystemPromptResult {
-  const section = parseAvailableToolsSection(systemPrompt);
-  if (!section) {
-    return { prompt: systemPrompt, removed: false };
-  }
-
   const allowedTools = new Set(allowedToolNames.map((toolName) => toolName.trim()).filter(Boolean));
-  const visibleEntries = section.entries.filter((entry) => allowedTools.has(entry.name));
-
-  if (visibleEntries.length === section.entries.length) {
-    return { prompt: systemPrompt, removed: false };
-  }
-
-  const lines = normalizePrompt(systemPrompt).split("\n");
-  const replacement = visibleEntries.length > 0
-    ? [lines[section.start], ...visibleEntries.flatMap((entry) => entry.lines)]
-    : [];
+  const normalizedLines = normalizePrompt(systemPrompt).split("\n");
+  const removedToolsSection = removeLineSection(normalizedLines, findSection(normalizedLines, AVAILABLE_TOOLS_SECTION_HEADER));
+  const sanitizedGuidelines = sanitizeGuidelinesSection(removedToolsSection.lines, allowedTools);
+  const removed = removedToolsSection.removed || sanitizedGuidelines.removed;
 
   return {
-    prompt: collapseExtraBlankLines([
-      ...lines.slice(0, section.start),
-      ...replacement,
-      ...lines.slice(section.end),
-    ].join("\n")),
-    removed: true,
+    prompt: removed ? collapseExtraBlankLines(sanitizedGuidelines.lines.join("\n")) : systemPrompt,
+    removed,
   };
 }

package/src/test.ts

@@ -14,6 +14,7 @@ import {
 import { PermissionManager } from "./permission-manager.js";
 import { checkRequestedToolRegistration, getToolNameFromValue } from "./tool-registry.js";
 import { getPermissionSystemStatus } from "./status.js";
+import { sanitizeAvailableToolsSection } from "./system-prompt-sanitizer.js";
 import type { GlobalPermissionConfig } from "./types.js";
 import { canResolveAskPermissionRequest, shouldAutoApprovePermissionState } from "./yolo-mode.js";
 
@@ -207,6 +208,64 @@ runTest("Permission-system status is only exposed when yolo mode is enabled", ()
   );
 });
 
+runTest("System prompt sanitizer removes the Available tools section and surrounding boilerplate", () => {
+  const prompt = [
+    "Available tools:",
+    "- read: Read file contents",
+    "- mcp: Discover, inspect, and call MCP tools across configured servers",
+    "",
+    "In addition to the tools above, you may have access to other custom tools depending on the project.",
+    "",
+    "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", "mcp"]);
+
+  assert.equal(result.removed, true);
+  assert.equal(result.prompt.includes("Available tools:"), false);
+  assert.equal(result.prompt.includes("In addition to the tools above"), false);
+  assert.match(result.prompt, /Guidelines:/);
+  assert.match(result.prompt, /Use mcp for MCP discovery first/i);
+});
+
+runTest("System prompt sanitizer removes denied tool guidelines while keeping global guidance", () => {
+  const prompt = [
+    "Guidelines:",
+    "- Use task when work SHOULD be delegated to one or more specialized agents instead of handled entirely in the current session.",
+    "- Use mcp for MCP discovery first: search by capability, describe one exact tool name, then call it.",
+    "- Prefer grep/find/ls tools over bash for file exploration (faster, respects .gitignore)",
+    "- Be concise in your responses",
+    "- Show file paths clearly when working with files",
+  ].join("\n");
+
+  const result = sanitizeAvailableToolsSection(prompt, ["bash", "grep", "mcp"]);
+
+  assert.equal(result.removed, true);
+  assert.equal(result.prompt.includes("Use task when work SHOULD"), false);
+  assert.match(result.prompt, /Use mcp for MCP discovery first/i);
+  assert.match(result.prompt, /Prefer grep\/find\/ls tools over bash/i);
+  assert.match(result.prompt, /Be concise in your responses/);
+  assert.match(result.prompt, /Show file paths clearly when working with files/);
+});
+
+runTest("System prompt sanitizer removes inactive built-in write guidance", () => {
+  const prompt = [
+    "Guidelines:",
+    "- Use write only for new files or complete rewrites",
+    "- When summarizing your actions, output plain text directly - do NOT use cat or bash to display what you did",
+    "- Be concise in your responses",
+  ].join("\n");
+
+  const result = sanitizeAvailableToolsSection(prompt, ["read"]);
+
+  assert.equal(result.removed, true);
+  assert.equal(result.prompt.includes("Use write only for new files or complete rewrites"), false);
+  assert.equal(result.prompt.includes("do NOT use cat or bash to display what you did"), false);
+  assert.match(result.prompt, /Be concise in your responses/);
+});
+
 runTest("Permission-system logger respects debug toggle and keeps review log enabled by default", () => {
   const baseDir = mkdtempSync(join(tmpdir(), "pi-permission-system-logs-"));
   const logsDir = join(baseDir, "logs");