pi-tool-discipline 0.1.16 → 0.2.0

package/README.md

@@ -1,11 +1,9 @@
 # pi-tool-discipline
 
-<p align="center">
-  <img src="assets/banner.png" alt="pi-tool-discipline" width="600">
-</p>
-
 pi extension that enforces a **search-tools-first discipline** and removes the
 conflicting "use bash for file operations" guidance pi injects by default.
+**Prompt-level only: it activates the right tools and edits the system prompt;
+it does not intercept or parse bash commands.**
 
 ## Why
 
@@ -19,18 +17,14 @@ tool, not bash").
 
 ## How it works
 
-Three mechanisms, applied automatically in every session:
+Two mechanisms, applied automatically in every session:
 
-1. **Activate search tools (root fix).** pi 0.84+ ships real `grep` / `find` /
+1. **Activate search tools (root fix).** pi >= 0.84 ships real `grep` / `find` /
    `ls` built-in tool definitions but only activates `read`/`bash`/`edit`/
    `write` by default. This extension activates the built-ins, so pi's
    `hasGrep`/`hasFind`/`hasLs` check passes and the conflicting
    `Use bash for file operations like ls, rg, find` guideline is **never
-   generated** — the model is never told to use bash for searching. On older
-   pi versions without these built-ins, fs-based fallbacks
-   (`extensions/search.ts`) are registered instead, with their text snippet
-   suppressed while `ffgrep`/`fffind` from pi-fff are active (the registered
-   tool schema remains present either way).
+   generated** — the model is never told to use bash for searching.
 2. **System-prompt injection (rules).** On every agent start, appends an
    idempotent "Tool Discipline" section to the system prompt: content search
    with `ffgrep`, path search with `fffind`, file reads with `read`
@@ -38,13 +32,22 @@ Three mechanisms, applied automatically in every session:
    `which` for searching or reading, bash reserved for pipelines/git/npm/network, `rg`
    (never `grep`) as the last resort in pipelines. Also strips the bash guideline text as
    a belt-and-suspenders fallback.
-3. **Runtime Guardrail (interception).** Intercepts `tool_call` events for
-   `bash` and `powershell`. If the model attempts to invoke prohibited file
-   operations (`ls`, `cat`, `grep`, `find`, `sed`, `which`, or unpiped
-   `head`/`tail` directly on files), execution is blocked at runtime with
-   actionable feedback guiding the model to use the proper tool (`read`,
-   `ffgrep`, `fffind`, `ls`, etc.), while safely preserving legitimate builds,
-   tests, git operations, and pipelines.
+
+## Why no bash interception?
+
+Earlier versions (<= 0.1.x) added a runtime guard: a hand-written
+bash/PowerShell command parser that blocked prohibited file operations at
+`tool_call` time. Maintaining a parser that precisely recognizes nested
+subshells, here-docs, wrappers and redirects — without misjudging legitimate
+pipelines — grew to ~1000 lines and became a hang/freeze risk (a stray `)` in
+a command could spin the event loop at 100% CPU, freezing the whole session).
+
+Behavior guidance at the prompt level is probabilistic but safe; code-level
+enforcement would require near-complete shell parsing — impractical and
+hazardous. The activation + injection mechanisms above already remove the
+root cause (pi no longer tells the model to use bash), so interception added
+little value. This version drops it entirely: no command parsing, no
+interception, no hang surface.
 
 ## Install
 
@@ -54,14 +57,14 @@ pi install npm:pi-tool-discipline
 pi -e npm:pi-tool-discipline
 ```
 
-Requires nothing extra. With `@ff-labs/pi-fff` installed, the model prefers
-`ffgrep`/`fffind`; without it, Pi's built-in `grep`/`find`/`ls` tools (activated
-by this extension, or fs-based fallbacks on older pi versions) are used.
+Requires **pi >= 0.84** (built-in `grep`/`find`/`ls` definitions). With
+`@ff-labs/pi-fff` installed, the model prefers `ffgrep`/`fffind`; without it,
+Pi's built-in `grep`/`find`/`ls` tools (activated by this extension) are used.
 
 ## Verify
 
-Run `/tool-discipline` in a pi session — it reports whether the placeholder
-tools are registered and whether the discipline section is injected.
+Run `/tool-discipline` in a pi session — it reports whether the search tools
+are registered/active and whether the discipline section is injected.
 
 You can also inspect the system prompt: the string
 `Use bash for file operations like ls, rg, find` should no longer appear, and
@@ -72,18 +75,8 @@ You can also inspect the system prompt: the string
 This extension runs with full system access like any pi extension. What it does:
 - Activates pi's built-in `grep`/`find`/`ls` tools (read-only file search).
 - Injects text into the system prompt (discipline rules).
-- On pi versions without built-in search tools, registers read-only fs-based
-  fallback implementations that read file contents under the searched path.
-
-**Disclosure:** pi's built-in `grep`/`find` tools execute the `rg`/`fd`
-binaries, and pi may auto-download those binaries from GitHub on first use
-(`ensureTool`). This extension itself does not execute commands, write files,
-or touch the network — that claim covers only its own fs-based fallback
-implementations, not the pi built-ins it activates.
-
-The fallback search tools only read. Note that any installed tool, including
-this one, can be invoked by the model. Review the source in `extensions/`
-before installing.
+
+It executes no commands, writes no files, and touches no network.
 
 ## License
 

package/extensions/index.ts

@@ -1,5 +1,5 @@
 /**
- * pi-tool-discipline
+ * pi-tool-discipline (slim)
  *
  * Enforces a "search tools first" file-search discipline in pi sessions and
  * neutralizes the built-in "Use bash for file operations like ls, rg, find"
@@ -12,29 +12,27 @@
  *   search tool exists and tells the model to use bash — fighting AGENTS.md
  *   rules that say to use the grep tool instead.
  *
- * How it works:
- *   A. Ensures `grep` / `find` / `ls` tools are ACTIVE in the session. pi 0.84+
- *      ships real built-in definitions (createAllToolDefinitions) but only
- *      activates read/bash/edit/write by default — this extension activates
- *      the built-ins, so pi's hasGrep/hasFind/hasLs check passes and the
- *      conflicting bash guideline is never generated, and the model always has
- *      search tools. On older pi versions without the built-ins, fs-based
- *      fallbacks (search.ts) are registered instead (visible only when the
- *      FFF counterpart ffgrep/fffind is absent).
+ * How it works (prompt-level only — no bash interception):
+ *   A. Ensures pi's built-in `grep` / `find` / `ls` tools are ACTIVE in the
+ *      session (pi 0.84+ ships real definitions via createAllToolDefinitions
+ *      but only activates read/bash/edit/write by default). Activating them
+ *      flips pi's hasGrep/hasFind/hasLs check, so the conflicting bash
+ *      guideline is never generated and the model always has search tools.
  *   B. On before_agent_start, appends the tool-discipline rules to the system
  *      prompt (idempotent) and strips the bash guideline text as a fallback.
+ *
+ * No runtime tool_call interception: behavior is guided at the prompt level,
+ * which means no shell-command parsing and no risk of parser hangs. Requires
+ * pi >= 0.84 for the built-in grep/find/ls definitions.
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { Type } from "typebox";
-import { grepFiles, findFiles, listDir, grepSchema, findSchema, lsSchema } from "./search.js";
 import { stripBashGuidelines } from "./strip.js";
-import { checkDisciplineViolation } from "./guard.js";
 
 const MARK = "<!-- pi-tool-discipline:v1 -->";
 
 /** Tool names that flip pi's hasGrep/hasFind/hasLs checks. */
-const PLACEHOLDER_NAMES = ["grep", "find", "ls"] as const;
+const SEARCH_TOOLS = ["grep", "find", "ls"] as const;
 
 /** FFF search tools that indicate pi-fff (or equivalent) is installed. */
 const FFF_TOOLS = ["ffgrep", "fffind"];
@@ -45,103 +43,25 @@ const DISCIPLINE = `
 Search tool priority:
 
 1. ffgrep / fffind (from @ff-labs/pi-fff) — always preferred. They work with absolute paths outside the workspace and support regex / path / exclude filters.
-2. Without pi-fff, use the grep / find / ls TOOLS (Pi built-ins on pi 0.84+, fs fallbacks on older versions). Fill their parameters according to each tool's declared schema — built-in grep uses ignoreCase/limit, built-in find uses a glob pattern. Never fall back to bash's grep or find.
+2. Without pi-fff, use the grep / find / ls TOOLS (Pi built-ins on pi 0.84+). Fill their parameters according to each tool's declared schema — built-in grep uses ignoreCase/limit, built-in find uses a glob pattern. Never fall back to bash's grep or find.
 3. Never run bash \`grep\` or \`find\`. Never use bash \`ls\`/\`cat\`/\`head\`/\`tail\`/\`sed\`/\`which\` directly for searching or reading — use ffgrep / fffind / read (or the grep/find/ls tools) instead.
 4. Read files with \`read\` (offset/limit for large files).
 5. Bash stays allowed only when dedicated tools cannot do the job: pipelines, git, npm, running programs, network requests, file mutations.
 6. If bash searching is truly unavoidable, use \`rg\` (never \`grep\`).`;
 
-interface FallbackTool {
-	label: string;
-	description: string;
-	snippet: string;
-	parameters: ReturnType<typeof Type.Object>;
-	execute: (params: any, cwd: string, signal?: AbortSignal) => Promise<string>;
-}
-
-const FALLBACK_TOOLS: Record<string, FallbackTool> = {
-	grep: {
-		label: "grep (fallback)",
-		description:
-			"Search file contents for a text pattern. Fallback for environments without ffgrep; prefer ffgrep when available.",
-		snippet: "Search file contents (fallback when ffgrep is unavailable)",
-		parameters: grepSchema,
-		execute: async (params, cwd, signal) => grepFiles({ ...params, cwd, signal }),
-	},
-	find: {
-		label: "find (fallback)",
-		description:
-			"Find files by path/name substring. Fallback for environments without fffind; prefer fffind when available.",
-		snippet: "Find files by path/name (fallback when fffind is unavailable)",
-		parameters: findSchema,
-		execute: async (params, cwd, signal) => findFiles({ ...params, cwd, signal }),
-	},
-	ls: {
-		label: "ls (fallback)",
-		description:
-			"List directory entries. Fallback for environments without fffind; prefer fffind when available.",
-		snippet: "List directory entries (fallback when fffind is unavailable)",
-		parameters: lsSchema,
-		execute: async (params, cwd, signal) => listDir({ ...params, cwd, signal }),
-	},
-};
-
 export default function toolDiscipline(pi: ExtensionAPI) {
-	// A. Register search-tool names so pi stops generating the bash guideline.
-	// Done in session_start: action methods (getAllTools/registerTool) are not
-	// available during extension loading, and tools registered here are
+	// A. Activate pi's built-in search tools so pi stops generating the bash
+	// guideline. Done in session_start: action methods (setActiveTools) are
+	// not available during extension loading, and tools activated here are
 	// refreshed into the session (and system prompt) immediately.
 	pi.on("session_start", () => {
 		const all = new Set(pi.getAllTools().map((t) => t.name));
 		const active = new Set(pi.getActiveTools());
-		const hasFfgrep = active.has("ffgrep");
-		const hasFffind = active.has("fffind");
-
-		// 1) Activate built-in grep/find/ls when they exist (pi 0.84+ ships real
-		//    definitions via createAllToolDefinitions but only activates
-		//    read/bash/edit/write by default). Activating them flips
-		//    hasGrep/hasFind/hasLs so the bash guideline is never generated, and
-		//    gives the model real built-in search tools.
-		const toActivate = PLACEHOLDER_NAMES.filter((name) => all.has(name) && !active.has(name));
+		const toActivate = SEARCH_TOOLS.filter((name) => all.has(name) && !active.has(name));
 		if (toActivate.length > 0) {
 			// setActiveTools rebuilds the system prompt immediately.
 			pi.setActiveTools([...active, ...toActivate]);
 		}
-
-		// 2) Older pi without built-in grep/find/ls: register working fs-based
-		//    fallbacks (search.ts). Visibility is per-capability: hidden while
-		//    the FFF counterpart is active, visible when it is not.
-		let registeredAny = false;
-		const registerSearchTool = (name: string, fffActive: boolean) => {
-			if (all.has(name)) return; // built-in exists — handled above
-			const fallback = FALLBACK_TOOLS[name];
-			pi.registerTool({
-				name,
-				label: fallback.label,
-				description: fallback.description,
-				promptSnippet: fffActive ? undefined : fallback.snippet,
-				promptGuidelines: [
-					"Use ffgrep/fffind when they are available; grep/find/ls are fallbacks only for environments without pi-fff.",
-				],
-				parameters: fallback.parameters,
-				async execute(_toolCallId, params, signal, _onUpdate, execCtx) {
-					const text = await fallback.execute(params ?? {}, execCtx.cwd, signal);
-					return {
-						content: [{ type: "text", text }],
-						details: { fallback: true },
-					};
-				},
-			});
-			registeredAny = true;
-		};
-		registerSearchTool("grep", hasFfgrep);
-		registerSearchTool("find", hasFffind);
-		registerSearchTool("ls", hasFffind);
-		// Tools registered in session_start do not enter selectedTools until the
-		// registry is refreshed. refreshTools exists at runtime (ExtensionActions)
-		// but is not declared on ExtensionAPI's type. Known limitation: with peer
-		// version "*", other pi versions may differ.
-		if (registeredAny) (pi as unknown as { refreshTools: () => void }).refreshTools();
 	});
 
 	// B. Inject the discipline into the system prompt (idempotent per turn).
@@ -152,24 +72,6 @@ export default function toolDiscipline(pi: ExtensionAPI) {
 		return { systemPrompt: `${prompt}\n${MARK}\n${DISCIPLINE}` };
 	});
 
-	// C. Runtime Guardrail: intercept and block prohibited bash file operations.
-	pi.on("tool_call", async (event) => {
-		if (event.toolName === "bash" || event.toolName === "powershell") {
-			const command = (event.input as { command?: string })?.command;
-			if (typeof command === "string") {
-				const dialect = event.toolName === "powershell" ? "powershell" : "bash";
-				const check = checkDisciplineViolation(command, dialect);
-				if (check.block) {
-					return {
-						block: true,
-						reason: check.reason,
-					};
-				}
-			}
-		}
-		return undefined;
-	});
-
 	// Status command: /tool-discipline — verify tool activation and injection.
 	pi.registerCommand("tool-discipline", {
 		description: "Show pi-tool-discipline status (tools + injected guideline)",
@@ -177,8 +79,8 @@ export default function toolDiscipline(pi: ExtensionAPI) {
 			const all = new Set(pi.getAllTools().map((t) => t.name));
 			const active = new Set(pi.getActiveTools());
 			const fff = FFF_TOOLS.filter((name) => active.has(name));
-			const registered = PLACEHOLDER_NAMES.filter((n) => all.has(n));
-			const activeTools = PLACEHOLDER_NAMES.filter((n) => active.has(n));
+			const registered = SEARCH_TOOLS.filter((n) => all.has(n));
+			const activeTools = SEARCH_TOOLS.filter((n) => active.has(n));
 			const injected = ctx.getSystemPrompt().includes(MARK);
 			ctx.ui.notify(
 				`pi-tool-discipline\n` +

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-tool-discipline",
-  "version": "0.1.16",
-  "description": "pi extension: enforce ffgrep/fffind-first search discipline and neutralize the default bash file-operation guideline",
+  "version": "0.2.0",
+  "description": "pi extension (prompt-level): enforce ffgrep/fffind-first search discipline and neutralize the default bash file-operation guideline",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -38,16 +38,14 @@
   },
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "test": "node --experimental-strip-types test/fallback.test.mjs && node --experimental-strip-types test/guard.test.mjs"
+    "test": "node --experimental-strip-types test/strip.test.mjs"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "*",
-    "typebox": "*"
+    "@earendil-works/pi-coding-agent": ">=0.84"
   },
   "devDependencies": {
     "@earendil-works/pi-coding-agent": "*",
     "@types/node": "^22.0.0",
-    "typebox": "*",
     "typescript": "^5.0.0"
   }
 }