Single Pass Multi Replace

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

┌─────────────────────────────────────────────────────────────┐
│                 Multi-Edit Trajectory Mechanics             │
│                                                             │
│  Sequential Single Edits (3 Turns / 11,500 Tokens):         │
│  • Turn 1: Edits line 4 (Import added) ──► Shifts file by +2│
│  • Turn 2: Edits line 35 ──► FAILS! (Line 35 is now line 37)│
│  • Turn 3: Agent retries edit with new offset calculation   │
│  ↳ 3 Turns, 11,500 tokens billed, high risk of line drift   │
│                                                             │
│  Single-Pass Multi-Replace (1 Turn / 420 Tokens):           │
│  • Turn 1: `multi_replace_file_content`                     │
│    ↳ Chunk 1: Lines 3-6 (Import updated)                    │
│    ↳ Chunk 2: Lines 35-40 (Interface updated)               │
│    ↳ Chunk 3: Lines 120-125 (Function call updated)         │
│  ↳ 1 Turn, 420 tokens billed (96.3% Savings!), Zero Drift!  │
└─────────────────────────────────────────────────────────────┘

Tool Invocation Standard (multi_replace_file_content)

When modifying multiple separated blocks in a single file:

{
  "TargetFile": "c:/Users/ASUS/Documents/Newfolder/Antigravity/Major AI Skills/src/auth.ts",
  "Instruction": "Update JWT import, extend Session interface, and patch verification logic.",
  "Description": "Added Redis session revocation check to auth service.",
  "ReplacementChunks": [
    {
      "StartLine": 2,
      "EndLine": 6,
      "TargetContent": "import jwt from 'jsonwebtoken';\nimport { db } from '@/lib/db';",
      "ReplacementContent": "import jwt from 'jsonwebtoken';\nimport { db } from '@/lib/db';\nimport { redis } from '@/lib/redis';",
      "AllowMultiple": false
    },
    {
      "StartLine": 32,
      "EndLine": 37,
      "TargetContent": "export interface Session {\n  userId: string;\n  role: string;\n}",
      "ReplacementContent": "export interface Session {\n  userId: string;\n  role: string;\n  isRevoked?: boolean;\n}",
      "AllowMultiple": false
    },
    {
      "StartLine": 118,
      "EndLine": 124,
      "TargetContent": "  const decoded = jwt.verify(token, SECRET);\n  return decoded;",
      "ReplacementContent": "  const decoded = jwt.verify(token, SECRET);\n  if (await redis.get(`revoked:${decoded.jti}`)) return null;\n  return decoded;",
      "AllowMultiple": false
    }
  ],
  "toolAction": "Applying multi-chunk atomic patch to auth.ts",
  "toolSummary": "Multi-Replace File Patch"
}

The 3 Rules of Multi-Chunk Patching

┌───────────────────────────────────────────────────────────────────────────┐
│ 1. ORDER CHUNKS TOP-TO-BOTTOM: List ReplacementChunks in ascending line order│
│ 2. INCLUDE EXACT SURROUNDING ANCHORS: Match leading tabs and whitespace   │
│ 3. ATOMIC TRANSACTION: If 1 chunk fails, zero changes apply to disk       │
└───────────────────────────────────────────────────────────────────────────┘

Benchmark Comparison

Refactoring 25 multi-section service files (3 non-contiguous edits per file):

Agent Operational Directive

MANDATORY: When modifying $>1$ non-adjacent code blocks in the same file, agents must call multi_replace_file_content with an array of discrete ReplacementChunks. Never execute multiple sequential replace_file_content calls on the same file across separate turns.