---
slug: "pi-tool-repair"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/monotykamary/pi-tool-repair@main/README.md"
repo: "https://github.com/monotykamary/pi-tool-repair"
source_file: "README.md"
branch: "main"
---
# π§ pi-tool-repair
**Validate-then-repair for [pi](https://github.com/earendil-works/pi-coding-agent)**
_Fixes the finite set of tool-call mistakes open models make β before tools execute._
[](https://github.com/earendil-works/pi-coding-agent)
[](./LICENSE)
---
> **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](https://commandcode.ai/)'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):
```bash
pi install npm:pi-tool-repair
```
Or install from GitHub:
```bash
pi install https://github.com/monotykamary/pi-tool-repair
```
**With npm**:
```bash
npm install npm:pi-tool-repair
```
**Manual** β add to `~/.pi/agent/settings.json`:
```json
{
"packages": ["git:github.com/monotykamary/pi-tool-repair"]
}
```
**Local development** β add the extension path directly:
```json
{
"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`:
```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 not recovered as tool calls. For DSML, dangling or truncated marker tokens (e.g. a stream that died at `<ο½DSMLο½tool_calls` with no closing `>`) are still stripped from visible text so the raw marker doesn't persist in the transcript.
- 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 ``, Qwen/Hermes ``, Kimi sentinels, Mistral `[TOOL_CALLS]`, Llama `<|python_tag|>`, GLM `arg_key`/`arg_value`, Granite JSON ``, MiniMax-Text-01 TypeScript calls, and OLMo3 `` pythonic calls. See [`docs/tool-call-grammar-leakage-survey.md`](https://github.com/monotykamary/pi-tool-repair/blob/HEAD/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`](https://github.com/monotykamary/pi-tool-repair/blob/HEAD/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`.
Full alias table
| 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
```bash
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](https://github.com/monotykamary/pi-retry) | Automatic retry for 400/413/connection errors |
| [pi-fast-resume](https://github.com/monotykamary/pi-fast-resume) | Instant session picker (6ms vs 5.6s) |
| [pi-hide-providers](https://github.com/monotykamary/pi-hide-providers) | Hide providers and models from the selector |
| [pi-double-esc](https://github.com/monotykamary/pi-double-esc) | Prevent accidental Escape aborts |
| [pi-loop](https://github.com/monotykamary/pi-loop) | Close the verification loop on task completion |
| [pi-fireworks-provider](https://github.com/monotykamary/pi-fireworks-provider) | Fireworks AI provider (origin of the Kimi anchor-bleed fix) |
## License
[MIT](https://github.com/monotykamary/pi-tool-repair/tree/HEAD/LICENSE)