edit_file_range
Replace a contiguous range in a file using anchor text or line numbers. Optionally require a content hash to avoid overwriting conflicting changes.
Instructions
Replace a contiguous span of a file with new content, addressed by anchors (primary) or line numbers (fallback). Optional expected_content_hash guards against stale edits; writes atomically. IMPORTANT: the from_anchor line and the to_anchor line are BOTH included in the replaced span — they are consumed, not preserved. If you want to keep the boundary lines, you must include them verbatim in new_content. Common mistake: anchoring on the last line of content you want to keep and then omitting it from new_content — that line will be silently dropped.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Absolute or workspace-relative path to the file. | |
| to_line | No | 1-based end line, inclusive. Supports negative indexing. Mutually exclusive with to_anchor. | |
| encoding | No | File encoding. Default: utf-8. Pass utf-8-sig to strip a BOM. | utf-8 |
| from_line | No | 1-based start line. Supports negative indexing (-1 = last line). Mutually exclusive with from_anchor. | |
| to_anchor | No | Stop at the matching line after the start (inclusive). Mutually exclusive with to_line. | |
| from_anchor | No | Start at the matching line (inclusive, substring, case-sensitive). Mutually exclusive with from_line. | |
| new_content | Yes | Replacement text, written byte-for-byte after encoding. The caller is responsible for correct line endings and trailing newline. | |
| project_root | No | Sets (and remembers) the project root for resolving relative paths for this and subsequent calls in the session. | |
| to_anchor_total | No | Expected total occurrences of to_anchor after the start. Optional: if omitted, the ambiguity guard is skipped and the to_anchor_occurrence-th match after the start is selected. Supply a value to re-enable the guard (ANCHOR_AMBIGUOUS on mismatch). | |
| from_anchor_total | No | Expected total occurrences of from_anchor in the file. | |
| to_anchor_occurrence | No | Which occurrence of to_anchor (after the start) to use. | |
| expected_content_hash | No | SHA-256 hex digest of the span's current raw bytes (as returned by read_file_range). If provided and the current span does not match, the edit is rejected with HASH_MISMATCH. | |
| from_anchor_occurrence | No | Which occurrence of from_anchor to use (1-based). |