Edit file
edit_fileReplace exact text in a single file with verified, targeted substitutions, optionally applying multiple edits and checking a SHA-256 hash to prevent stale-content changes.
Instructions
Replace exact text: old_text to new_text, or edits[] for several replacements in one file (edits[] wins). Use when: you make a targeted change. old_text must match exactly once unless replace_all=true. Pass expected_sha256 (read_file's sha256 or your last sha256_after) to refuse stale content and get a verified re-read. Avoid when: you rewrite the whole file (write_file) or change several files at once (edit_batch). Output: replacements, sha256_before, sha256_after, verified (when expected_sha256 is given). Failures leave the file unchanged: old_text_not_found (data.mismatch locates the first difference, data.context shows the nearby lines) and old_text_ambiguous (lists each match with context).
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"relative_path": "<relative_path>"
},
"name": "edit_file"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| edits | No | Multiple section replacements in this file; takes precedence over old_text/new_text. | |
| reason | No | Optional why (max 400 chars), audit-logged. | |
| new_text | No | Replacement text (paired with old_text; ignored when edits[] is given). | |
| old_text | No | Exact text to replace. Must match exactly once unless replace_all=true. Ignored when edits[] is given. | |
| replace_all | No | true replaces every match; false (default) requires exactly one match. | |
| relative_path | Yes | Workspace-relative ('.' = root); absolute/.. outside it rejected. | |
| expected_sha256 | No | Hex SHA-256 of the file's current full content. The edit is refused if the file on disk differs. Use sha256_after from your last write/edit of this file; read_file's sha256 only matches when the whole file was returned. When given, the result is re-read after the write and reports verified. |