Problem Description

FileTools today has no targeted-edit primitive. Agents that want to change a function signature, rename a symbol, or tweak a config value have two choices and both are bad:

• save_file — requires the model to reproduce the entire file on every change. Expensive in tokens and each retyped line is a chance for regression.
• replace_file_chunk — works on line ranges (start_line, end_line). LLMs miscount lines reliably; one off-by-one and the wrong region is rewritten.

The modern pattern, popularized by Claude Code's Edit tool and mirrored by Cursor and Aider, is literal string replacement with safety guards: the agent picks an old_text with enough surrounding context to be unique, supplies the new_text, and the tool either applies the change or refuses for a clear reason.

Proposed Solution

Add edit_file(file_name, old_text, new_text, replace_all=False, encoding="utf-8") to FileTools, with the following invariants:

1. Read-before-edit. The file must have been fully read (via read_file or written via save_file) before it can be edited. Partial reads via read_file_chunk are rejected because the chosen old_text might only exist in unseen lines.
2. Staleness detection. If the file's mtime has changed since the last observation, the edit is refused and the agent is told to re-read.
3. Unique match. old_text must appear exactly once unless replace_all=True, otherwise the edit is refused with the match count so the agent can add more context.
4. Creation on empty old_text. old_text="" on a missing file creates it with new_text as contents (matches Claude Code's Edit semantics).
5. Identical strings rejected. old_text == new_text returns a no-op error instead of a silent write.

Parameter names (old_text, new_text, file_name) are aligned with the existing CodingTools.edit_file so users moving between toolkits carry consistent vocabulary.

Alternatives Considered

• Keep replace_file_chunk as the only partial-write API. Rejected: LLMs are demonstrably bad at line math.
• Always use save_file for edits. Rejected: quadratic token cost, high regression risk on large files.
• Build this into a new standalone toolkit. Rejected: FileTools already has read_file/save_file/search_content; this is a missing method, not a new paradigm.

Additional Context

Implementation and test coverage in #7640.

Would you like to work on this?

• Yes, I'd love to work on it! (PR open)