[Tool] Add FileEditTool - search-and-replace editing for files

[omatheusmesmo]

Motivation

The agent currently only has writeFile which overwrites entire files. For any small edit (fixing a typo, changing a config value, adding an import), the agent must rewrite the entire file content. This wastes tokens, risks accidental deletions, and makes precise edits error-prone.

All three reference projects have a dedicated edit tool.

What the tool should do

Perform exact text search-and-replace within a file. The agent specifies the exact text to find (oldText) and the replacement (newText).

Reference implementations

opencode (TypeScript) - Most sophisticated

• 9-tier fuzzy matching strategy: exact match, line-trimmed, block anchor (Levenshtein 0.65), whitespace normalized, indentation flexible, escape normalized, trimmed boundary, context aware (50% similarity), multi-occurrence
• Disproportionate match protection (refuses if found span >> search string)
• Per-file semaphore locks to prevent race conditions
• CRLF/LF line ending normalization
• UTF-8 BOM handling
• Diff generation for permission prompts
• LSP diagnostics after edit
• Auto-formatter integration

hermes-agent (Python)

• Fuzzy matching for old_string (handles minor whitespace differences)
• replace_all flag for replacing all occurrences
• V4A patch format support (Codex, Cline compatible)
• Diff output returned to the model
• Consecutive failure escalation (hints after repeated failures)

openclaw (TypeScript)

• Multiple disjoint edits in one call (edits[] array of {oldText, newText})
• TUI diff previews before execution
• BOM handling, line ending normalization (CRLF/LF)
• Edit verification by re-reading file after write

Requirements

1. Exact string match - Find oldText and replace with newText
2. replaceAll mode - Optional flag to replace all occurrences
3. Multiple edits per call - Support array of {oldText, newText} pairs
4. Line ending preservation - Detect and preserve CRLF/LF
5. BOM handling - Preserve UTF-8 BOM
6. Error on multiple matches - Warn if oldText matches more than once (when replaceAll is false)
7. Error on no match - Clear error message when oldText not found
8. Diff preview - Return a unified diff showing what changed
9. Workspace confinement - Must respect workspace root

Suggested location

client/runtime/src/main/java/dev/omatheusmesmo/qlawkus/tool/shell/FileEditTool.java

Config properties

• qlawkus.file.edit.enabled (boolean, default true)