pi-tool-discipline 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jiangkoumo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,62 @@
+# pi-tool-discipline
+
+pi extension that enforces a **search-tools-first discipline** and removes the
+conflicting "use bash for file operations" guidance pi injects by default.
+
+## Why
+
+Pi's system-prompt builder only injects
+`Use bash for file operations like ls, rg, find` when **no tool named
+`grep` / `find` / `ls` is active** ([dist/core/system-prompt.js]). FFF-style
+search tools are named `ffgrep` / `fffind`, so pi mistakes them for "no search
+tool available" and tells the model to use bash for everything — directly
+fighting project instructions (like an `AGENTS.md` that says "use the grep
+tool, not bash").
+
+## How it works
+
+Two mechanisms, applied automatically in every session:
+
+1. **Placeholder tools (root fix).** Registers placeholder tools named
+   `grep`, `find`, and `ls` (skipped if already registered). They carry no
+   prompt snippet, so they never appear in the model's tool list and are never
+   callable in practice. Their mere presence flips pi's `hasGrep`/`hasFind`/
+   `hasLs` check, so the conflicting bash guideline is **never generated**.
+2. **System-prompt injection (fallback + 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` (offset/limit), no bash `grep`/`rg`/`find`/`ls`/`cat`/`sed`/`head`/
+   `tail`/`which` for searching, bash reserved for pipelines/git/npm/network.
+   Also strips the default bash guideline text in environments where the
+   placeholder registration is disabled.
+
+## Install
+
+```bash
+pi install npm:pi-tool-discipline
+# or try without installing:
+pi -e npm:pi-tool-discipline
+```
+
+Requires `@ff-labs/pi-fff` (or any other extension providing `ffgrep`/`fffind`)
+for the discipline to point at real search tools.
+
+## Verify
+
+Run `/tool-discipline` in a pi session — it reports whether the placeholder
+tools are registered 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
+`## Tool Discipline (pi-tool-discipline)` should be present.
+
+## Security
+
+This extension runs with full system access like any pi extension. It only
+registers inert placeholder tools and appends text to the system prompt; it
+does not execute commands, read files, or touch network. Review the source in
+`extensions/index.ts` before installing.
+
+## License
+
+MIT

package/extensions/index.ts

@@ -0,0 +1,118 @@
+/**
+ * pi-tool-discipline
+ *
+ * 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"
+ * guideline that conflicts with project instructions (e.g. AGENTS.md).
+ *
+ * Why it exists:
+ *   pi only injects the bash file-operation guideline when NO tool named
+ *   `grep` / `find` / `ls` is active (dist/core/system-prompt.js). FFF-style
+ *   search tools are named `ffgrep` / `fffind`, so pi mistakenly thinks no
+ *   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. Registers placeholder tools named `grep` / `find` / `ls` (skipped when
+ *      already registered). They carry no promptSnippet, so they never appear
+ *      in the model's tool list and are never actually callable in practice.
+ *      Their presence flips pi's hasGrep/hasFind/hasLs check, so the
+ *      conflicting bash guideline is never generated.
+ *   B. On before_agent_start, appends the tool-discipline rules to the system
+ *      prompt (idempotent) and strips the bash guideline text as a fallback
+ *      for environments where the placeholder registration is disabled.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+const MARK = "<!-- pi-tool-discipline:v1 -->";
+
+/** Placeholder tool names that flip pi's hasGrep/hasFind/hasLs checks. */
+const PLACEHOLDER_NAMES = ["grep", "find", "ls"] as const;
+
+/**
+ * The exact guidelines pi's builder injects when no search tool is active.
+ * Stripped from the system prompt as a fallback (plan B).
+ */
+const BASH_GUIDELINES = [
+	"Use bash for file operations like ls, rg, find",
+	"Use bash or PowerShell for file operations like listing, searching, and finding files",
+	"Use PowerShell for file operations like listing, searching, and finding files",
+];
+
+const DISCIPLINE = `
+## Tool Discipline (pi-tool-discipline)
+
+Search and read files with dedicated tools, not bash:
+
+- Content search: use \`ffgrep\`. Path search: use \`fffind\`.
+- Read files with \`read\` (use \`offset\`/\`limit\` for large files).
+- Do NOT use the bash tool for \`grep\`/\`rg\`/\`find\`/\`ls\`/\`cat\`/\`sed\`/\`head\`/\`tail\`/\`which\` searches or file reads.
+- Bash stays allowed only when dedicated tools cannot do the job: pipelines, git, npm, running programs, network requests, file mutations.
+- If bash searching is truly unavoidable, prefer \`rg\` over \`grep\`.`;
+
+function stripBashGuidelines(prompt: string): string {
+	let out = prompt;
+	for (const guideline of BASH_GUIDELINES) {
+		out = out.replaceAll(guideline, "Use ffgrep/fffind for file operations like ls, rg, find");
+	}
+	return out;
+}
+
+export default function toolDiscipline(pi: ExtensionAPI) {
+	// A. Register placeholder search tools 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
+	// refreshed into the session (and system prompt) immediately.
+	pi.on("session_start", () => {
+		const existing = new Set(pi.getAllTools().map((t) => t.name));
+		for (const name of PLACEHOLDER_NAMES) {
+			if (existing.has(name)) continue; // already present — the check already passes
+			pi.registerTool({
+			name,
+			label: `${name} (placeholder)`,
+			description:
+				`Placeholder tool registered by pi-tool-discipline so pi knows a ${name} tool exists ` +
+				`and does not inject its default "use bash for file operations" guideline. ` +
+				`Do not call this tool — use ffgrep for content search and fffind for path search instead.`,
+			parameters: Type.Object({}),
+			async execute() {
+				return {
+					content: [
+						{
+							type: "text",
+							text: "This placeholder tool has no implementation. Use ffgrep for content search and fffind for path search instead.",
+						},
+					],
+					details: { placeholder: true },
+				};
+			},
+		});
+	}
+	});
+
+	// B. Inject the discipline into the system prompt (idempotent per turn).
+	pi.on("before_agent_start", async (event) => {
+		const { systemPrompt } = event;
+		if (systemPrompt.includes(MARK)) return; // already injected
+		const prompt = stripBashGuidelines(systemPrompt);
+		return { systemPrompt: `${prompt}\n${MARK}\n${DISCIPLINE}` };
+	});
+
+	// Status command: /tool-discipline — verify placeholder tools and injection.
+	pi.registerCommand("tool-discipline", {
+		description: "Show pi-tool-discipline status (placeholder tools + injected guideline)",
+		handler: async (_args, ctx) => {
+			const tools = pi.getAllTools().map((t) => t.name);
+			const placeholders = PLACEHOLDER_NAMES.filter((n) => tools.includes(n));
+			const injected = ctx.getSystemPrompt().includes(MARK);
+			ctx.ui.notify(
+				`pi-tool-discipline\n` +
+					`placeholder tools: ${placeholders.length > 0 ? placeholders.join(", ") : "(none)"}\n` +
+					`discipline injected: ${injected ? "yes" : "no"}`,
+				"info",
+			);
+		},
+	});
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "pi-tool-discipline",
+  "version": "0.1.0",
+  "description": "pi extension: enforce ffgrep/fffind-first search discipline and neutralize the default bash file-operation guideline",
+  "type": "module",
+  "license": "MIT",
+  "keywords": [
+    "pi",
+    "pi-package",
+    "pi-extension",
+    "ffgrep",
+    "fffind",
+    "grep",
+    "search",
+    "discipline"
+  ],
+  "pi": {
+    "extensions": ["./extensions/index.ts"]
+  },
+  "files": [
+    "extensions",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@sinclair/typebox": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@sinclair/typebox": "*",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.0.0"
+  }
+}