feat(core): steer model to prefer replace over write_file for existing files

[genneth]

What happened?

The model frequently uses write_file to rewrite entire files when a targeted replace call would be more appropriate. This leads to unnecessary full-file rewrites that are:

• Harder to review — the user sees a full file write instead of a focused diff
• More error-prone — rewriting a whole file risks dropping content, especially in large files (related: Data Loss: replace Tool Causes Silent Truncation of Large Files #17562, Agent falls back to write_file after str_replace failure, causing code corruption #20799)
• More expensive — full file content in the tool call consumes significantly more output tokens

The root cause appears to be in the tool descriptions rather than the tool implementations. The write_file tool description contains no guidance about when it should or shouldn't be used. Meanwhile, the replace tool description is ~300 words of strict requirements (3+ lines of context, exact literal matching, mandatory instruction parameter), which may discourage the model from choosing it.

What did you expect to happen?

The model should strongly prefer replace for modifying existing files and only use write_file for creating new files or complete rewrites where the majority of the file content is changing.

Suggested fix

Add steering text to the write_file tool description, something like:

"Prefer the replace tool for modifying existing files. Only use write_file to create new files or for complete rewrites where most of the content is changing."

This is a low-risk, prompt-only change that doesn't require any code modifications to tool implementations. It could also be reinforced in the system prompt snippets (snippets.ts).

Additionally, consider simplifying the replace tool description to reduce friction — the current description's strict tone may push the model toward the "safer" write_file path.

Related issues

• Agent falls back to write_file after str_replace failure, causing code corruption #20799 — Agent falls back to write_file after str_replace failure
• Data Loss: replace Tool Causes Silent Truncation of Large Files #17562 — replace tool causes silent truncation of large files
• The EDIT/REPLACE tool is a disgrace; it deletes code and creates bad replacements. #18098 — replace tool quality issues

Environment

N/A — this is a prompt/tool description change, not environment-specific.