pi-edit-safe

A drop-in replacement for the pi coding agent's built-in edit tool, with a stricter matcher that refuses to silently edit the wrong place — and a call shape that weaker models can actually use.

Exposes one call shape — {path, edits: [...]}, always an array, even for a single replacement — so the model has nothing to choose per call. Multi-edit applies in order (sequential), the contract models assume from multi-edit tools elsewhere, instead of pi's all-against-the-original-file semantic.

The looser shapes models emit anyway are still folded onto that form before validation, so off-contract calls are normalized rather than rejected — they are just not advertised.

Install: npm:@tian.zuo/pi-edit-safe · npm package @tian.zuo/pi-edit-safe · workspace packages/pi-edit-safe

Call shape

One shape, always an array:

{ "path": "src/a.ts", "edits": [
	{ "oldText": "...", "newText": "..." },
	{ "oldText": "...", "newText": "..." }
] }

Use a one-element edits array for a single replacement. path and edits are both required and edits has minItems: 1. Nothing else is advertised to the model.

Tolerated but not advertised

prepareArguments runs before schema validation (per pi's extension contract) and folds these onto the canonical form: file_path/filePath/filename for path; old_string/new_string, oldString/newString, old_str/new_str for the pair (per entry or top-level); top-level oldText/newText shorthand; edits as a JSON string; and edits as a single object.

This keeps off-contract calls working without widening the public schema. Exact duplicate entries are rejected loudly. When a later edit fails because an earlier edit in the same call rewrote its target, the error says exactly that.

Design stance

| Decision | typical fuzzy edit tools | pi-edit-safe | |---|---|---| | Partial-signal strategies (first/last-line anchor) | yes | none | | On ambiguity | fall through to next candidate | throw immediately | | Fuzzy candidate validation | per-candidate similarity threshold | full-span structural equality + exactly-one + occurs-once | | Overlapping exact matches | often missed | caught (overlap-aware counting) | | Unicode punctuation drift (smart quotes, em dash, NBSP) | varies | strict unicode strategy, span-only | | Untouched bytes | may be normalized whole-file | never touched (slice + verbatim splice) | | Line endings | whole-file normalize/restore | span-boundary only; mixed-ending files never flattened | | newText write | String.replace ($& hazard) | slice-join (literal) | | Multi-edit semantics | all edits vs the original file | sequential, in order | | Call shapes offered to the model | varies | exactly one (edits[]) |

Fuzzy matching only ever locates a span. The replacement is spliced in verbatim — it is never re-indented or rewritten.

Matching order

1. Exact, never gated, counted overlap-aware (aa in aaa is ambiguous, not unique).
2. If exact fails, hard gates: ≥5 non-space chars, no NUL byte, ≤1M chars, ≤50k lines.
3. Increasingly tolerant full-span strategies: line-trimmed → unicode punctuation → collapsed whitespace → escape-normalized.
4. More than one candidate for a strategy → throw. Never falls through from ambiguity to a looser matcher.
5. Splice verbatim. Uniform LF/CRLF files adapt the replacement's newlines; mixed-ending files take it as-is.
6. Apply all entries in memory, in order, then write once — a later failure leaves the file unchanged.

Result details

Returns pi's built-in EditToolDetails shape (diff, patch, firstChangedLine) alongside a edits[] array of per-edit provenance (matchedVia, startLine, endLine).

Because pi resolves renderer inheritance per slot (toolDefinition.renderCall ?? builtInToolDefinition.renderCall), this override deliberately defines neither renderCall nor renderResult, and so inherits pi's streaming diff preview and final diff rendering for free.

The diff is computed against the real bytes on both sides. pi's built-in diffs its LF-normalized view instead, which is why the two disagree on mixed-line-ending files (see bench case 11).

Disable

PI_EDIT_SAFE_DISABLE=1 pi   # falls back to the built-in edit

Tests and A/B bench

pnpm --filter @tian.zuo/pi-edit-safe test    # 45 unit tests (Node's built-in runner)
pnpm --filter @tian.zuo/pi-edit-safe run bench

The bench imports pi's actual shipped edit-diff.js functions and composes them exactly as dist/core/tools/edit.js does, then runs the same 12 (file, edits) cases through both pipelines and reports every divergence, including "canary" lines that must stay byte-identical.

These are deterministic corruption regressions. They are not a model-level eval — no cross-model pass@1 / token / retry benchmark exists for this tool yet.

Attribution

Fuzzy-strategy concepts adapted from opencode (MIT, via cline MIT and gemini-cli Apache-2.0); the unicode normalization table mirrors pi's own normalizer (MIT), applied span-only. Design philosophy reproduced independently. See NOTICES.md.