pi-tool-repair 0.1.0

package/README.md

@@ -0,0 +1,237 @@
+<div align="center">
+
+# 🔧 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._
+
+[![pi extension](https://img.shields.io/badge/pi-extension-blueviolet)](https://github.com/earendil-works/pi-coding-agent)
+[![license](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)
+
+</div>
+
+---
+
+> **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 https://github.com/monotykamary/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 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`](./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`](./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`.
+
+<details>
+<summary><strong>Full alias table</strong></summary>
+
+| 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`                                                                                                   |
+
+</details>
+
+## 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](./LICENSE)

package/docs/tool-call-grammar-leakage-survey.md

@@ -0,0 +1,289 @@
+# Tool-Call Grammar Leakage Survey (June 2026)
+
+Survey of LLMs that use XML-like / sentinel-token tool-call grammars and are
+observed to *leak* the raw markup into the user-visible `content` (or
+`reasoning_content`) field instead of emitting structured `tool_calls`.
+
+This is the input for an opt-in `pi-tool-repair` feature: a configurable,
+**disabled-by-default** flag (set in `~/.pi/agent/extensions/pi-tool-repair.json`)
+that recovers leaked grammar back into structured tool calls — or at minimum
+strips it from visible output.
+
+## Why leakage happens (root causes, consistent across families)
+
+The same handful of mechanisms produce leakage regardless of vendor:
+
+1. **Reasoning/tool-parser ordering.** When both a reasoning parser and a
+   tool-call parser are enabled, the tool parser only runs on `content` after
+   the reasoning parser yields. If the model emits the tool grammar *inside* an
+   unclosed `<think>`/reasoning block, the tags land in `reasoning_content` and
+   the tool parser never sees them. (DeepSeek, Qwen3.5/3.6, Kimi K2.)
+2. **Split start-marker across stream chunks.** Long sentinel start tokens
+   (`<｜｜DSML｜｜tool_calls>`, `<|tool_calls_section_begin|>`) get split across
+   SSE chunks; the parser emits the partial prefix as plain text before it can
+   recognize the marker. (DeepSeek DSML, Kimi K2, MiniMax.)
+3. **`tool_choice=auto` + `stream=true`** is the high-risk path. `required` and
+   `stream=false` are markedly more stable because they take a different
+   (constrained) decode/parse branch.
+4. **Tokenizer `skip_special_tokens=True` in batched decode.** When a tool-call
+   request shares a batch with a non-tool request, the sentinel/special tokens
+   get stripped, so the marker (`｜DSML｜`, `[TOOL_CALLS]`) is simply *missing*
+   and downstream parsers fail. (DeepSeek V3.2, Mistral.)
+5. **Provider/engine parser absent or mismatched.** Self-hosted vLLM/SGLang/MLX
+   or aggregators (OpenRouter, Novita, Fireworks, NVIDIA, OpenCode Zen,
+   Tensorix, Foundry) ship the model before a correct `--tool-call-parser`
+   exists or with the wrong one, so raw markup passes straight through.
+6. **Higher temperature** increases format drift away from the strict grammar.
+
+Prompt-level mitigations ("do not output DSML tags") are unreliable: emission is
+a tokenizer/training-level pattern, not instruction-following.
+
+## The grammar families to handle
+
+These are the concrete shapes that show up in leaked `content`. Group them by
+parser, not by vendor — multiple vendors share a shape.
+
+### A. DeepSeek "DSML" XML (`｜DSML｜`, U+FF5C fullwidth bars)
+
+DeepSeek V3.2 / V4 (V4-Pro, V4-Flash). The `｜` is U+FF5C fullwidth vertical bar.
+Three observed bar variants plus an ASCII-pipe variant from some proxies:
+
+```
+# Double-bar (most common in live V4 SSE)
+<｜｜DSML｜｜tool_calls>
+<｜｜DSML｜｜invoke name="code_exec">
+<｜｜DSML｜｜parameter name="language" string="true">python</｜｜DSML｜｜parameter>
+</｜｜DSML｜｜invoke>
+</｜｜DSML｜｜tool_calls>
+
+# Single-bar
+<｜DSML｜tool_calls>
+<｜DSML｜invoke name="fetch">
+<｜DSML｜parameter name="url" string="false">["x"]</｜DSML｜parameter>
+</｜DSML｜invoke>
+</｜DSML｜tool_calls>
+
+# No-leading-bar
+<DSML｜tool_calls>
+<DSML｜invoke name="bash">
+</DSML｜invoke>
+
+# ASCII-pipe variant (proxies/aggregators that transcode the fullwidth bars)
+< | DSML | tool_calls>
+< | DSML | invoke name="builtin_web_search">
+< | DSML | parameter name="additionalContext" string="true">...</ | DSML | parameter>
+</ | DSML | invoke>
+</ | DSML | tool_calls>
+```
+
+Key details:
+- `function_calls` vs `tool_calls` both appear as the outer wrapper (V3.2 used
+  `function_calls`; V4 uses `tool_calls`). Handle both, singular and plural.
+- `string="true"` → value passed as-is; `string="false"` → value is JSON
+  (number/bool/array/object). The repair must respect this when building args.
+- Inner body can be XML `<parameter>` tags **or** a direct JSON object.
+- Newlines inside `<parameter>` values are common (multi-line bash) and break
+  naive non-DOTALL matching — a real failure mode reported against pi itself
+  (earendil-works/pi#3712).
+- Providers with reported leakage: official DeepSeek API, **NVIDIA**,
+  **Novita**, **Fireworks**, **OpenCode Zen**, **Tensorix**, Microsoft Foundry,
+  CherryIN, self-hosted vLLM/SGLang/antirez-ds4.
+
+### B. Anthropic-style `<invoke>` / `<parameter>` XML (no DSML bars)
+
+This is the canonical Anthropic tool-use shape, widely copied. Leaked by:
+
+- **MiniMax** M1, M2.1, M2.5, M2.7, M3 — wrapped in `<minimax:tool_call>`:
+  ```xml
+  <minimax:tool_call>
+  <invoke name="search_web">
+  <parameter name="query_list">["..."]</parameter>
+  </invoke>
+  </minimax:tool_call>
+  ```
+  MiniMax M2 also has a *malformed* variant that drops the `<`/`</` angle
+  brackets entirely (`invoke name="x">` … `parameter name="y">val parameter>`),
+  needing bracket-repair before XML parsing.
+- **Anthropic Claude via OpenRouter** occasionally emits raw `<tool_call>` /
+  `<tool_result>` tags as text.
+- Generic `<tool_call>...</tool_call>` and `<tool_result>...</tool_result>`
+  blocks leaked across many OpenAI-compat providers.
+
+### C. Qwen / Hermes XML (`<tool_call>` + `<function=…>` + `<parameter=…>`)
+
+Two sub-shapes — note the `=` (Qwen3-Coder/qwen3_xml) vs `name="…"` (Hermes):
+
+```xml
+# Qwen3-Coder / qwen3_xml shape (attribute via '=')
+<tool_call>
+<function=get_weather>
+<parameter=location>Paris</parameter>
+</function>
+</tool_call>
+
+# Hermes shape (JSON inside <tool_call>)
+<tool_call>
+{"name": "get_weather", "arguments": {"location": "Paris"}}
+</tool_call>
+
+# Qwen2.5-Coder oddball: wraps in <tools> with a JSON body
+<tools>
+{"name": "get_weather", "arguments": {"location": "San Francisco, CA"}}
+</tools>
+```
+
+Affected: Qwen2.5 / Qwen2.5-Coder / Qwen2.5-VL, QwQ-32B, Qwen3 / Qwen3-Coder
+(30B, 480B, Next), **Qwen3.5** (9B/35B-A3B most unstable), **Qwen3.6**
+(27B / 35B-A3B). Common failure: XML lands in `reasoning_content` when emitted
+inside an unclosed `<think>`. Also malformed variants (merged tags
+`<function=edit>` missing `<`, bare `<function>` without `<tool_call>`,
+mismatched/missing closers) — see the community `qwen-toolcall-fixer` proxy.
+
+### D. Kimi K2 sentinel tokens (`<|tool_calls_section_begin|>` …)
+
+Moonshot Kimi K2 / K2-Thinking / K2.6:
+
+```
+<|tool_calls_section_begin|>
+<|tool_call_begin|>functions.web_search:0<|tool_call_argument_begin|>{"query": "..."}<|tool_call_end|>
+<|tool_calls_section_end|>
+```
+
+Details:
+- Singular variants also exist: `<|tool_call_section_begin|>` / `_end`.
+- Tool-call ID format is load-bearing: `functions.{name}:{idx}`. Bare
+  `call00003` / `search:2` / `call_0001` (OpenAI-style) confuse the model and
+  the parser, causing leakage or empty `tool_calls`. Hosted Moonshot API
+  normalizes IDs; OSS deployments must normalize client-side.
+- Leaks into `reasoning_delta`/`reasoning_content` in thinking mode.
+- Sparse toolsets (1–2 tools) increase the inline-token leakage rate
+  (observed via OpenRouter for `moonshotai/kimi-k2.6`).
+
+### E. Mistral sentinel tokens (`[TOOL_CALLS]`, `[ARGS]`, `[CALL_ID]`)
+
+Mistral 7B v0.3, Nemo, Ministral-8B, Mistral-Large-2407, plus V7/V11 tokenizers:
+
+```
+[TOOL_CALLS] [{"name": "calculator", "arguments": {"operation": "2+2"}, "id": "VvvODy9mT"}]
+# V11: [TOOL_CALLS]name[CALL_ID]id[ARGS]{...}
+```
+
+Failure modes: tool call emitted as plain JSON text (no `[TOOL_CALLS]` token),
+`skip_special_tokens` dropping the sentinel, brittle behavior above temperature
+0, IDs must be 9-char alphanumeric.
+
+### F. Llama `<|python_tag|>` + JSON / pythonic
+
+Llama 3.1 / 3.2 / 3.3 / 4. Tool call prefixed with `<|python_tag|>`, body is
+JSON (`llama3_json` / `llama4_json`) or pythonic (`pythonic` / `llama4_pythonic`).
+Leaks when the `<|python_tag|>` token is dropped or the model wraps JSON in
+markdown / adds preamble text. Llama 3.2 emits *no* start token at all, which is
+its own leakage class.
+
+### G. GLM `<tool_call>` + `<arg_key>` / `<arg_value>` XML
+
+Zhipu/Z.ai GLM-4.5 / GLM-4.6 / GLM-4.7 (`glm4_moe` / `glm47` parser), and
+GLM-5:
+
+```xml
+<tool_call>get_weather
+<arg_key>city</arg_key>
+<arg_value>Beijing</arg_value>
+</tool_call>
+```
+
+Reasoning wrapped in `<think>`/`</think>`. Zero-arg calls
+(`<tool_call>get_current_date</tool_call>`) and same-line name+args are valid
+variants. GLM-5 observed leaking raw `<tool_call>` shadow text to chat channels.
+
+### H. IBM Granite `<tool_call>` + JSON (Hermes-derived)
+
+Granite 4.0 / 4.1 (and Nano). Uses Hermes convention:
+`<tool_call>{"name": …, "arguments": …}</tool_call>`. Known quirk: emits
+arguments as an escaped *string* instead of JSON object. Granite 3.3 / 4.0
+H-Small emit *pythonic* calls (`func(kw=val)`) instead — a separate shape.
+
+### I. MiniMax-Text-01 typescript-style
+
+Older MiniMax text model emits:
+```
+<function_call>```typescript
+functions.get_current_weather({"location": "Shanghai"})
+```
+```
+
+### J. OLMo 3 `<function_calls>` + pythonic
+
+AllenAI OLMo 3 Instruct: newline-delimited pythonic calls wrapped in
+`<function_calls>...</function_calls>` (allows JSON `true`/`false`/`null`).
+(OLMo 3 *Think* models are not trained for tools — leakage there is the model
+narrating, not a grammar.)
+
+## Quick reference table
+
+| Family | Models | Marker shape | Inner body | Leaks into |
+|---|---|---|---|---|
+| A. DSML | DeepSeek V3.2, V4-Pro, V4-Flash | `<｜DSML｜tool_calls>` / `function_calls` (+ double-bar, no-bar, ASCII `< | DSML |`) | `<parameter name= string=>` or JSON | content + reasoning |
+| B. invoke/parameter | MiniMax M1–M3, Claude (via OpenRouter) | `<minimax:tool_call>` / `<invoke name=>` `<parameter name=>` | text / JSON | content |
+| C. Qwen/Hermes | Qwen2.5/3/3.5/3.6, Coder, VL, QwQ | `<tool_call>` + `<function=>` `<parameter=>` or JSON | text / JSON | reasoning_content |
+| D. Kimi sentinels | Kimi K2 / K2-Thinking / K2.6 | `<\|tool_calls_section_begin\|>` … | `functions.name:idx` + JSON | content + reasoning_delta |
+| E. Mistral sentinels | 7B v0.3, Nemo, Ministral, Large-2407 | `[TOOL_CALLS]` `[ARGS]` `[CALL_ID]` | JSON array | content |
+| F. Llama python_tag | Llama 3.1/3.2/3.3/4 | `<\|python_tag\|>` (or none) | JSON / pythonic | content |
+| G. GLM arg_key | GLM-4.5/4.6/4.7, GLM-5 | `<tool_call>name` + `<arg_key>` `<arg_value>` | XML kv | content + think |
+| H. Granite | Granite 4.0/4.1 (+ Nano) | `<tool_call>` | JSON (sometimes escaped string) | content |
+| I. MiniMax-Text-01 | MiniMax-Text-01 | `<function_call>` ```typescript | `functions.x({...})` | content |
+| J. OLMo3 | OLMo 3 Instruct | `<function_calls>` | newline pythonic | content |
+
+## Provider hot-spots (where leakage is reported in the wild)
+
+Aggregators/engines that have shipped models ahead of (or without) a correct
+parser, producing the leakage the colleague observed:
+
+- **Novita, Fireworks, OpenCode Zen, Tensorix** — reported by colleague for
+  DeepSeek V4-Flash.
+- **NVIDIA** integrate endpoint — DSML leaked as assistant text (DeepSeek V4).
+- **OpenRouter** — Kimi K2.6 inline tokens (sparse toolsets), Claude raw tags.
+- **Microsoft Foundry / CherryIN** — DeepSeek V4 DSML.
+- Self-hosted **vLLM / SGLang / MLX / llama.cpp / Ollama** across all families
+  (parser version mismatches, batched-decode special-token stripping).
+
+## Design implications for the opt-in flag
+
+1. **Disabled by default**, configured at
+   `~/.pi/agent/extensions/pi-tool-repair.json`. Likely shape:
+   ```json
+   {
+     "grammarRepair": {
+       "enabled": true,
+       "grammars": ["dsml", "minimax", "qwen", "kimi", "mistral", "llama", "glm", "granite", "olmo"],
+       "mode": "recover"  // "recover" = promote to tool_calls; "strip" = remove from visible text only
+     }
+   }
+   ```
+   Default to all-known grammars when `enabled` and `grammars` omitted; allow
+   per-grammar opt-in/out.
+
+2. **Recover, don't just strip.** Stripping alone leaves the agent loop with
+   `finish_reason: stop` and no tool dispatched (silent no-op). The valuable
+   behavior is parsing the leaked grammar into structured tool calls and
+   rewriting `finish_reason` → `tool_calls` (the path Cherry Studio, OpenClaw,
+   and Hermes all converged on). Fall back to strip when the block is malformed.
+
+3. **Only recover complete, well-formed blocks with a known tool name and
+   parseable args.** Leave incomplete/malformed markup as text (or surface a
+   parse error) — do not promote arbitrary prose into execution.
+
+4. **Stream-aware buffering.** Markers split across chunks; buffer a bounded
+   prefix (marker-length window) before emitting visible text, with a cap
+   (Kimi parser uses ~1KB buffer / 8KB section cap) and a final flush.
+
+5. **Respect DSML `string="true|false"`** when building arguments; unwrap nested
+   `{"arguments": "{...}"}` wrappers; normalize Kimi tool-call IDs to
+   `functions.{name}:{idx}`.
+
+6. **Code-fence / prose guard.** Don't strip grammar that appears inside fenced
+   code blocks or when the user/assistant is legitimately discussing the syntax
+   (the bug OpenClaw hit with `stripToolCallXmlTags`).
+
+7. **Match the colleague's exact three DSML variants first** (double-bar,
+   single-bar, no-lead-bar), then generalize to the table above.

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "pi-tool-repair",
+  "version": "0.1.0",
+  "description": "Validate-then-repair extension for pi — fixes common LLM tool-call mistakes (null fields, stringified arrays, wrong field names, anchor bleed) before tools execute",
+  "type": "module",
+  "author": "Tom X Nguyen",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/monotykamary/pi-tool-repair.git"
+  },
+  "homepage": "https://github.com/monotykamary/pi-tool-repair#readme",
+  "bugs": {
+    "url": "https://github.com/monotykamary/pi-tool-repair/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-coding-agent",
+    "extension",
+    "tool-repair",
+    "open-models",
+    "kimi",
+    "deepseek",
+    "validate-then-repair",
+    "anchor-bleed",
+    "grammar-repair",
+    "dsml"
+  ],
+  "files": [
+    "*.ts",
+    "src/",
+    "docs/",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "lint:dead": "knip --no-gitignore"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "0.75.4",
+    "@types/node": "25.9.1",
+    "@vitest/coverage-v8": "4.1.7",
+    "knip": "6.14.1",
+    "typescript": "6.0.3",
+    "vitest": "4.1.7"
+  },
+  "pi": {
+    "extensions": [
+      "./tool-repair.ts"
+    ]
+  }
+}