Single-Pass Multi-Replace Protocol (Atomic Non-Contiguous Mutations)

Overview

When an agent updates a file across multiple non-contiguous locations (e.g., adding an import on line 4, updating an interface definition on line 35, and modifying a function call on line 120), naive agents execute 3 sequential replace_file_content calls across 3 separate turns.

Sequential multi-turn editing suffers from two critical failure modes:

1. The Line-Drift Bug: When Turn 1 adds 3 lines to the top of the file, all downstream line numbers shift down by +3. In Turn 2, the agent provides obsolete StartLine/EndLine ranges, causing edit failures.
2. Turn & Token Multiplication: 3 separate turns re-send the entire conversation history 3 times, burning 12,000+ tokens for a 15-line edit.

The Single-Pass Multi-Replace Protocol bundles all non-contiguous edit chunks into a single tool call payload (multi_replace_file_content), executing all mutations atomically in 1 turn without line-drift errors.

Sequential Turn Edits vs. Single-Pass Multi-Replace