From bfa9a508956f9858ccaf680f6ef3f2c52638601e Mon Sep 17 00:00:00 2001
From: Spencer Gilbert <me@spencergilbert.dev>
Date: Fri, 25 Sep 2026 09:07:32 -0400
Subject: [PATCH] [extensions/tool-guidance] Add grep/find/ls prompt guidance

Adds "prefer the dedicated tool over bash" guidelines for grep, find, and
ls, mirroring the built-in read/write lines. All three ship with
guidelines: [], so nothing steers the model away from bash grep/rg,
find/fd, and ls.

Patches the Guidelines section through the mutable systemPromptOptions of
before_agent_start rather than re-registering the tools: re-registering a
tool with a built-in name replaces its definition wholesale and would
clobber another extension's execute (e.g. ssh's remote-routed grep/find/ls).

Experimental local stopgap ahead of proposing the equivalent one-line
additions upstream for the built-in tool definitions.
---
 README.md                   |  8 +++++++
 TODO.md                     |  6 ++++++
 extensions/tool-guidance.ts | 42 +++++++++++++++++++++++++++++++++++++
 3 files changed, 56 insertions(+)
 create mode 100644 extensions/tool-guidance.ts

diff --git a/README.md b/README.md
index 1dfd922..ba0d8b5 100644
--- a/README.md
+++ b/README.md
@@ -135,6 +135,14 @@ While pair watch is active the session is teach-only: the `write` and `edit` too
 
 Manual `/pair <focus>` invocation works as before.
 
+### tool-guidance (experimental)
+
+Adds "prefer the dedicated tool over bash" guidelines for the `grep`, `find`, and `ls` tools, the same way `read` already says "Use read to examine files instead of cat or sed". Those three built-ins ship with no guidelines, so nothing steers the model away from bash `grep`/`rg`, `find`/`fd`, and `ls` — the dedicated tools respect `.gitignore` and `grep` returns line numbers.
+
+Always on; no usage or flags. It patches the system prompt's Guidelines section via `before_agent_start` rather than re-registering the tools, so it composes with execution-overriding extensions such as `ssh`.
+
+Still experimental — a local stopgap while the equivalent one-line additions are proposed upstream for the built-in tool definitions.
+
 ## Skills
 
 ### kagi
diff --git a/TODO.md b/TODO.md
index 0bfeb50..524d823 100644
--- a/TODO.md
+++ b/TODO.md
@@ -227,6 +227,12 @@ Maintainers reopen worthwhile ones daily. Verified against `main` where noted.
   `node_modules` blowups) and `grep` returns line numbers.
 - Upstream PR to add the same one-liners to the built-in tool definitions.
 
+### Status
+- **Experimental local stopgap shipped**: `extensions/tool-guidance.ts` adds
+  the three guidelines via the mutable `systemPromptOptions.toolGuidelines` of
+  `before_agent_start` (not by re-registering tools, which would clobber
+  `ssh`'s remote-routed `execute`). Being tested ahead of the upstream PR.
+
 ---
 
 ## Done / already handled
diff --git a/extensions/tool-guidance.ts b/extensions/tool-guidance.ts
new file mode 100644
index 0000000..307c321
--- /dev/null
+++ b/extensions/tool-guidance.ts
@@ -0,0 +1,42 @@
+/**
+ * Tool Guidance extension - experimental
+ *
+ * Adds "prefer the dedicated tool over bash" guidelines for the grep, find,
+ * and ls tools, mirroring the built-in read/write lines ("Use read to examine
+ * files instead of cat or sed"). Those three ship with `guidelines: []`, so
+ * without this nothing steers the model away from bash `grep`/`rg`,
+ * `find`/`fd`, and `ls` - which is exactly the underuse surfaced by the
+ * session review (grep 3.7x, ls 5.9x, find 7.5x more often via bash).
+ *
+ * This is an experimental local stopgap while the one-line additions are
+ * proposed upstream for the built-in tool definitions.
+ *
+ * Implementation note: this patches the Guidelines section through the
+ * mutable `systemPromptOptions` of `before_agent_start` instead of
+ * re-registering the tools. Re-registering a tool with a built-in name
+ * replaces its definition wholesale, which would clobber another extension's
+ * `execute` (e.g. ssh's remote-routed grep/find/ls). Mutating prompt
+ * metadata composes with those extensions.
+ *
+ * Guidelines are keyed by tool name and only rendered when the tool is in
+ * the active selectedTools, so adding all three unconditionally is safe.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+const GUIDELINES: Record<string, string[]> = {
+	grep: [
+		"Use grep instead of bash grep or rg — it respects .gitignore and returns line numbers.",
+	],
+	find: ["Use find instead of bash find or fd — it respects .gitignore."],
+	ls: ["Use ls instead of bash ls."],
+};
+
+export default function toolGuidanceExtension(pi: ExtensionAPI) {
+	pi.on("before_agent_start", (event) => {
+		const { toolGuidelines } = event.systemPromptOptions;
+		for (const [name, lines] of Object.entries(GUIDELINES)) {
+			toolGuidelines[name] = [...(toolGuidelines[name] ?? []), ...lines];
+		}
+	});
+}
-- 
2.51.2