Edit
Read the file first, or pass expected_hash from the last read or write. See OCC.
Every successful edit returns content_hash. Pass it as expected_hash on the next edit.
edit_file modes
Section titled “edit_file modes”mode | What it does |
|---|---|
replace (default) | One exact old_text / new_text match. occurrence: 1 first, -1 last. |
search_replace | All occurrences of pattern. replacement is the new text. |
regex | Capture groups. patterns or patterns_json, or a single pattern. |
insert | Insert new_text before or after a unique anchor. Does not replace the anchor. |
delete_range | Remove lines start_line..end_line, or start_line plus line_count. |
replace_range | Replace that line range with new_text. |
end_line is an absolute line number, not a count. Do not pass end_line and line_count together.
dry_run:true previews and does not write, in every mode.
strict:true disables implicit trim, regex, and escape fallbacks. expected_matches rejects the edit unless old_text matches that many times, and lists candidate lines.
tolerant_whitespace:true treats a tab as four spaces and CRLF as LF when matching. The file’s own bytes are kept.
Rewrite guard
Section titled “Rewrite guard”Default mode replaces only the matched span. The rest of the file stays. A small old_text plus a large new_text, with most of the file outside the match, is blocked (REWRITE_BLOCKED, retryable false). Use write_file for a full rewrite, or allow_rewrite:true if you want edit semantics. force does not bypass this guard. It only passes a CRITICAL risk check. A safety backup is still created.
replacement is not an alias for new_text in default mode. Passing replacement without new_text or new_str is rejected and the file is not modified.
multi_edit
Section titled “multi_edit”One file, several {old_text, new_text} edits, applied together. Pass edits or edits_json, not conflicting both. expected_hash covers the whole batch. An ambiguous match is a counted failure. The file is not written.
apply_patch and diff_files
Section titled “apply_patch and diff_files”diff_files compares path_a and path_b, or a file against its last backup (against:"backup").
apply_patch applies a unified diff. One file: path is the destination. Several files: path is the directory root. The multi-file patch is an in-process transaction, not crash-durable. dry_run previews. expected_hash is for one file. There is no fuzzy match. The destination file’s line endings win. Codex *** Begin Patch is rejected (BEGIN_PATCH). Do not retry that text.
If the code is PATCH_FAILED, read the file and regenerate the hunk. Do not retry the same patch. retryable is false. recovery is read_and_rebase.