batch_replace
Replace specified text across multiple files in one atomic operation, with fuzzy matching and detailed per-file change reports.
Instructions
Replace the same text across multiple files in one call. Engine staging is atomic for applied writes (all written files succeed or none change). Pattern misses are soft by default: matching files still apply and total misses appear in refused[]; set require_change=true to fail the whole batch if any file has no match. Canonical field is files (array); singular file is accepted as an alias for one path. Optional fuzzy enables similarity fallback; when exact old is absent, refuse by default unless allow_absent_old=true (#1758). JSON reports match_mode (exact/fuzzy/anchored), optional match_score, optional matched_text, match_count per change and aggregate (#1674). IMPORTANT: do NOT issue concurrent write calls targeting the same files; use execute_plan for multi-op atomicity. Example: {"files": ["Cargo.toml", "README.md"], "old": "0.1.0", "new": "0.2.0"}
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| new | Yes | Text to replace with. Alias `to` accepted because agents often emit that name (LLM prior). | |
| old | Yes | Text to find in each file. Alias `from` accepted because agents often emit that name (LLM prior). | |
| file | No | Single file (LLM prior). Equivalent to `files: [file]` when `files` is empty. If both are set, `files` wins. Alias `path` matches replace_text priors. | |
| files | No | File paths to apply the replacement to (relative to working directory). Canonical multi-file form. | |
| fuzzy | No | When exact match fails, try fuzzy/similarity fallback (#1668). | |
| regex | No | Use regex mode for the `old` pattern. | |
| strict | No | Roll back all writes when format/validate lifecycle steps fail. | |
| if_exists | No | If true, silently succeed when a file does not contain the pattern instead of returning an error. Useful for idempotent batch replacements. | |
| multiline | No | Enable multiline matching (dot matches newlines in regex mode). | |
| word_boundary | No | Match only at word boundaries. Prevents 'SetupFile' from matching inside 'BenchSetupFile'. Auto-escapes regex metacharacters. | |
| require_change | No | Fail when a file has zero matches (fail closed). Softened when if_exists is true. | |
| min_fuzzy_score | No | Reject fuzzy matches below this similarity floor (#1687). `None` = no floor. | |
| allow_absent_old | No | Allow fuzzy apply when exact `old` is absent (#1758). Default false (fail closed; report best candidate without writing). | |
| case_insensitive | No | Case-insensitive matching. | |
| command_position | No | Only rewrite shell command-position tokens (not arguments / longer words). Peels wrappers like sudo, timeout, busybox, flock, runuser, setsid. |