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. Prompt-level only: it activates the right tools and edits the system prompt; it does not intercept or parse bash commands.

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. 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.
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 (offset/limit), no bash grep/find/ls/cat/sed/head/tail/ 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.

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

pi install npm:pi-tool-discipline
# or try without installing:
pi -e npm:pi-tool-discipline

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 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 ## Tool Discipline (pi-tool-discipline) should be present.

Security

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).

It executes no commands, writes no files, and touches no network.

License

MIT