pi-tool-guard

A pi extension that corrects common LLM tool call mistakes: normalizes argument aliases for edit/write/read and strips trailing pipeline extractors from bash commands.

Install

pi install npm:pi-tool-guard

---

Features

1. Argument alias normalization (edit / write / read)

When the LLM calls a tool with wrong field names, the extension normalizes them before schema validation. No error, no re-execution.

Tool	Canonical	Accepted aliases
edit	path	file, filePath, file_path, target, filename, file_name
edit	edits[].oldText	old_str, old_string, oldContent, old, original, search
edit	edits[].newText	new_str, new_string, newContent, new, replacement, replace
write	path	file, filePath, file_path, target, filename, file_name
write	content	text, body, code, data, fileContent, contents
read	path	file, filePath, file_path, target, filename, file_name
read	offset	start, startLine, start_line, from, line
read	limit	lines, maxLines, max_lines, count, numLines, num_lines

Edit tool shorthand: top-level oldText/newText (or aliases) are automatically wrapped into an edits array.

Read tool type coercion: string values for offset and limit are coerced to numbers.

2. Bash pipeline extractor stripping

When the LLM appends truncation commands (tail, head, grep, etc.) to bash commands, the extension strips them and applies the extractor intelligently.

Three-case strategy:

Scenario	UI Notification	LLM Response
Fast command (< 10s), truncated	Filtered via \head``	Filtered result only
Fast command (< 10s), not truncated	Filtered via \head``	Filtered result only
Slow command (truncated or not)	The full output is above...	Result + This is a slow command. Avoid re-running...

Example: vitest run | tail -n 10

• If vitest finishes in < 10s → run tail on result (or full output file if truncated), notify UI
• If vitest is slow → return result as-is, notify UI, append slow-command hint to LLM

Detected extractors: head, tail, grep, egrep, fgrep, rg, sed, awk, cut, sort, uniq, wc, less, more, column, jq, yq, tr

All trailing extractors are stripped: npm test | grep FAIL | head -5 → strips grep FAIL | head -5

---

Architecture

Both features use prepareArguments on overridden built-in tools — the cleanest pi extension pattern for argument correction:

• edit/write/read: createXxxToolDefinition(cwd) + prepareArguments normalizes aliases before schema validation
• bash: createBashToolDefinition(cwd) + custom execute override:
  1. prepareArguments parses the command with unbash, strips trailing extractors
  2. execute runs the stripped command via the original built-in execute
  3. If fast (< 10s) + truncated → runs extractor on the full output file via pi.exec
  4. If fast (< 10s) + not truncated → pipes result through extractor via pi.exec
  5. If slow (truncated or not) → returns result as-is with notice

No error recovery, no session scanning.

Development

pnpm install
pnpm test        # Run all tests
pnpm typecheck   # Type check

License

MIT