docs: survey how five code agents design their edit tool

[minixalpha]

What this adds

docs/research/edit_tool.md — a survey of the model-callable editing tools in
the five reference agents (Grok Build, Pi, Claude Code, OpenCode, Codex), written
before building the equivalent here. Same shape as the existing read_tool.md
and write_tool.md notes: read the checked-out sources, record what each project
actually does, then derive a contract for this project.

What it found

All five ship structured localized editing, but they have not converged on one
Edit:

Project	Main protocol
Grok Build	search_replace by default; presets swap in hashline_edit, OpenCode edit or apply_patch
Pi	one file, edits[] of oldText/newText
Claude Code	single old_string/new_string with replace_all, plus NotebookEdit
OpenCode	V1 and V2 both have edit; GPT models get apply_patch instead
Codex	no string edit at all — freeform apply_patch only

The shared trait is therefore not the name or the schema but the shape: the model
states a change and its precondition, and the runtime reads the current file,
verifies the precondition, and leaves everything else alone. The note draws the
line the other way too — an Edit tool is not automatically a security boundary or
a transaction, since bash can still write anywhere and the checks are not one
storage transaction with the write.

Each project section records the limits, not just the design: Grok's empty
old_string still overwrites a non-empty file under the default config, Claude
Code's delete path can leave an occurrence behind while reporting that all were
replaced, OpenCode V1's prompt still promises a read-before-edit check that was
removed from the implementation, and Codex re-parses and re-applies the patch
after approval, so the committed result can differ from the previewed one.

What it recommends here

A fourth built-in tool: a thin, exact, single-replacement
Edit(path, old_text, new_text, replace_all=false) with a deliberately honest
contract — existing UTF-8 regular files only, non-empty old_text, unique match
or explicit replace_all, no regex/trim/similarity fuzz, strict UTF-8 with the
BOM stripped before matching and restored on write, and one documented LF→CRLF
retry so text copied out of read (which drops \r) can still match a CRLF
file. It explicitly leaves out prior-Read enforcement, edits[], apply_patch,
formatter/LSP/history and a per-file queue in the first version, and says why for
each.

Also

docs/research/README.md now indexes edit_tool.md, plus the write_tool.md
entry that had been missing since that note landed.

Notes

• The note is written in Chinese, per the docs/research/ convention.
• Documentation only, no shipped behavior changes — no changelog entry.