🔧 pi-tool-repair

Validate-then-repair for pi

Fixes the finite set of tool-call mistakes open models make — before tools execute.

---

Open models aren't bad at tool calling — the harness is.

By adding a thin repair layer, DeepSeek V4 Pro beat Opus 4.7 in 6/10 internal evals — without changing the model. The same four mistakes repeat across DeepSeek, GLM, Qwen, and others. Each fix is 30–100 lines. Order matters.

Reverse-engineered from Command Code's tool parsing pipeline.

What it fixes

Problem	Model sends	After repair
null for optional fields	{"path": "/foo", "offset": null}	{"path": "/foo"}
Arrays as JSON strings	"[\"a\",\"b\"]"	["a","b"]
{} where array expected	{"include": {}}	(dropped)
Bare string → array	"foo"	["foo"]
Wrong field names	{"file_path": "/foo"}	{"path": "/foo"}
Bare string as root input	"/path/to/file"	{"path": "/path/to/file"}
Schema anchor bleed (Kimi K2)	"^pattern$" in values	"pattern"
Leaked tool grammar (opt-in)	<｜DSML｜tool_calls>...	pi toolCall block

Install

With pi install (recommended):

pi install https://github.com/monotykamary/pi-tool-repair

With npm:

npm install pi-tool-repair

Manual — add to ~/.pi/agent/settings.json:

{
  "packages": ["git:github.com/monotykamary/pi-tool-repair"]
}

Local development — add the extension path directly:

{
  "extensions": ["./path/to/pi-tool-repair/tool-repair.ts"]
}

Reload with /reload after any install method.

How it works

┌────────────────────────────────────────────────────────────┐
│ Phase 0: Schema poisoning (before_provider_request)        │
│                                                            │
│ Strip regex anchors from JSON Schema patterns for models   │
│ where they leak into generated values (Kimi K2, MiniMax)   │
│                                                            │
│ Fixes what YOU send the model — not what the model sends   │
└──────────────────────────┬─────────────────────────────────┘
                           │
                           ▼
               Model generates tool call
                           │
                           ▼
┌────────────────────────────────────────────────────────────┐
│ Phase 1: Grammar leak repair (message_end, opt-in)         │
│                                                            │
│ Detect raw XML/sentinel tool grammars emitted as text or   │
│ thinking, strip them from visible output, and recover them │
│ as pi toolCall blocks when complete and safe.              │
└──────────────────────────┬─────────────────────────────────┘
                           │
                           ▼
┌────────────────────────────────────────────────────────────┐
│ Phase 2: Validate-then-repair (tool_call)                  │
│                                                            │
│  1. Validate input against schema (if known tool)          │
│   ↳ Valid? Ship it untouched.                              │
│  2. Walk the validator's issue list                        │
│   ↳ Apply targeted repairs only at the exact failed paths  │
│  3. Re-validate the repaired input                         │
│   ↳ Still invalid? Let the tool handle it.                 │
│  4. Log outcome (debug mode)                               │
└────────────────────────────────────────────────────────────┘

Repair rules (in order)

Order matters — parseJsonStringifiedArray must run before wrapBareStringAsArray or you get double-wrapping.

#	Rule	What it catches
1	renameAliasedField	file_path → path, query → pattern, etc.
2	dropNullOrUndefined	null/undefined for optional fields
3	dropEmptyObjectPlaceholder	{} where array expected
4	parseJsonStringifiedArray	"[\"a\",\"b\"]" → ["a","b"]
5	wrapBareStringAsArray	"foo" → ["foo"]
6	wrapRootStringAsObject	"/path" → {"path": "/path"}

Why validate-then-repair (not preprocess-then-validate)

Preprocessing inputs before validation silently corrupts valid data — rewriting file content that happened to look like JSON, for example. The better design:

1. Parse the input as-is. If valid, ship it untouched.
2. On failure, walk the validator's issue list and apply repairs only at the exact paths that failed.
3. Re-validate. The schema localizes the bug for you — you only spend repair effort where it's actually needed.

Configuration

Grammar leak repair (disabled by default)

Raw XML/sentinel tool-call grammar recovery is opt-in because it can turn assistant text into tool execution. Enable it in ~/.pi/agent/extensions/pi-tool-repair.json:

{
  "grammarRepair": {
    "enabled": true,
    "mode": "recover",
    "requireKnownTool": true,
    "grammars": [
      "dsml",
      "invoke",
      "qwen",
      "kimi",
      "mistral",
      "llama",
      "glm",
      "granite",
      "minimax-text",
      "olmo"
    ]
  }
}

Modes:

Mode	Behavior
recover	Strip leaked markup and append recovered pi toolCall blocks.
strip	Strip leaked markup only; do not execute recovered calls.

Safety gates:

• requireKnownTool: true only recovers calls whose name is in pi's active tool registry.
• Markup inside fenced code blocks is ignored so syntax discussions and examples are preserved.
• Incomplete or unparseable blocks are left alone.
• If the provider already emitted native toolCall blocks, leaked shadow text is stripped but duplicate calls are not added.

Covered grammar families: DeepSeek DSML, MiniMax/Anthropic <invoke>, Qwen/Hermes <tool_call>, Kimi sentinels, Mistral [TOOL_CALLS], Llama <|python_tag|>, GLM arg_key/arg_value, Granite JSON <tool_call>, MiniMax-Text-01 TypeScript calls, and OLMo3 <function_calls> pythonic calls. See docs/tool-call-grammar-leakage-survey.md for the survey.

Debug logging

Set PI_TOOL_REPAIR_DEBUG=1 or grammarRepair.debug: true to log repair diagnostics to stderr:

[pi-tool-repair] tool=read outcome=recovered rules=dropNullOrUndefined hints=1
  input: {"path":"/foo","offset":null}
  repaired: {"path":"/foo"}
  hint[0]: Dropped null `offset` from tool "read"...

Covered tools

Repair rules apply to pi's built-in tools: read, write, edit, bash, grep, find, ls.

Anchor bleed models

Phase 0 schema sanitization activates for models matching these patterns:

Pattern	Models
/kimi-k2/i	Kimi K2 variants
/minimax/i	MiniMax variants
/glm/i	GLM variants

To add more models, edit anchorBleedModels in src/index.ts.

Field aliases

The extension maps common model mistakes (wrong field names) to the canonical field name. For example, when calling read, the model can send file_path, absolutePath, filepath, target_file, etc. — all map to path.

Tool	Canonical	Aliases
read	path	absolutePath, file_path, filePath, filepath, pathname, target_file, targetFile, file, absolute_path, fileAbsolutePath
grep	pattern	query, regex, search, q, expression, text
write	path	absolutePath, file_path, filePath, filepath, pathname, target_file, targetFile
write	content	text, body, data, contents, fileContent
edit	path	absolutePath, file_path, filePath, filepath, pathname, target_file, targetFile
edit	oldText	old_string, oldString, old, old_str, oldStr, from, old_value, oldText, old_text, oldContent, old_content
edit	newText	new_string, newString, new, new_str, newStr, to, new_value, newText, new_text, newContent, new_content
ls	path	absolutePath, directory, dir, folder, directoryPath
find	pattern	query, glob, expression, search, include
bash	command	cmd, shell, script, commandLine

Development

npm install
npm test              # run tests
npm run test:watch    # watch mode
npm run test:coverage # coverage report
npm run typecheck     # type checking
npm run lint:dead     # dead code detection

Related projects

Project	Description
pi-retry	Automatic retry for 400/413/connection errors
pi-fast-resume	Instant session picker (6ms vs 5.6s)
pi-hide-providers	Hide providers and models from the selector
pi-double-esc	Prevent accidental Escape aborts
pi-loop	Close the verification loop on task completion
pi-fireworks-provider	Fireworks AI provider (origin of the Kimi anchor-bleed fix)

License

MIT