LogoYuxiang Wu

Reliable File Editing for Coding Agents

File editing is the highest-frequency "actuator" in coding agents—and it's where agents most often fail for reasons that have little to do with "can the model code?" and everything to do with interfaces, determinism, and feedback.

This post is a practical blueprint for building a file-edit subsystem that:

If you already have an agent loop, treat this as the missing "edit reliability layer" that turns good plans into correct changes on disk.

TL;DR

Why file editing is still hard (even for strong models)

Most failures in "edit the codebase" aren't deep reasoning failures. They're representation ↔ applier mismatches:

So the core engineering goal is not "make the model smarter." It's: make edits deterministic, verifiable, recoverable, and cheap to repair.

Glossary (terms we'll use consistently)

The architecture that actually works

At scale, reliability comes from one move: normalize everything into an internal Edit IR and make application deterministic and instrumented.

Your agent loop becomes:

  1. Observe (read/search files)
  2. Propose (model emits some representation)
  3. Adapt (parse/translate into Edit IR)
  4. Apply (deterministic applier; strict errors)
  5. Validate (lint/tests/build)
  6. Receipt (send structured results back)
  7. Recover (retry with new context or fall back)
Edit system architecture showing adapters, Edit IR, deterministic applier, validators, and fallback ladder

A minimal Edit IR that covers most agents

You don't need a huge IR. A small set of operations covers 95% of real workflows:

If you support patch-like operations, you can still compile them down into these primitives (e.g., multiple ReplaceExacts).

Key principle: the IR is what you test. Adapters are allowed to be messy; the applier must be boring.

The applier's job: strict determinism + high-quality feedback

A strict applier prevents silent corruption. A helpful applier prevents retry spirals.

What "strict" means in practice

For content-based operations like search/replace:

What "helpful feedback" means in practice

When an apply fails, return an error payload that includes:

That makes "repairing the edit" a mechanical task for the model, not guesswork.

State drift: the failure mode most agents under-engineer

Edits are only meaningful relative to a specific file version. In real agent runs, files change due to:

Fix: include hash/version checks at every step.

This one rule dramatically reduces "phantom edits" and makes failures legible.

State drift flow: hash-gated edit transactions prevent applying patches to wrong file versions

Representations: useful taxonomy, but only as "input adapters"

Here are the dominant edit representations you'll encounter. The point is not to "pick the best one forever," but to:

1) Vendor-native tool calls (preferred when available)

Examples (conceptually):

Why these win: they maximize "well-formedness" and make errors explicit.

2) Search/replace blocks (conflict-marker style)

A robust text-only format is:

Why it's strong: no line numbers; deterministic to apply; easy to reject ambiguity.

Failure mode: SEARCH mismatch or matches multiple times.

3) Unified diff (git-style @@ hunks)

Useful for PR-like workflows and interoperability, but harder to apply robustly unless you invest in a flexible patcher.

Failure mode: malformed hunks, brittle context, line-number/offset confusion.

4) Whole-file rewrite

A blunt but often effective fallback—especially for small files or when edits are widespread.

Failure mode: unintended changes, elision ("… existing code …"), merge conflicts.

Vendor-native recommendations: "most reliable interface," not "format preference"

Models don't "prefer formats" as an abstract aesthetic choice. They're more reliable when the interface matches:

OpenAI-style patch tools (apply_patch)

Use a patch tool when you can expose it as a first-class action. It's designed for iterative, multi-step coding workflows:

Anthropic-style text editor tools (view + str_replace)

This tool family is essentially "editor RPC":

Gemini-style exact replace + checkpointing

This style typically emphasizes:

If your environment supports checkpointing/restore, integrate it into your fallback ladder. Rollback is not a luxury; it's how you prevent error propagation.

The fallback ladder: how to avoid infinite retries

When an edit fails, don't "try again" blindly. Escalate deterministically.

A battle-tested ladder:

  1. Minimal targeted edit

    • tool-based str_replace / replace
    • or a single SEARCH/REPLACE block

  2. Resync + widen context

    • re-read the relevant file region
    • expand the old anchor (more lines; preserve indentation)

  3. Switch representation

    • from exact replace → patch DSL
    • from patch → whole-file rewrite (for that file only)

  4. Sandbox + validate

    • run format/lint/tests
    • if fail, discard and return a concise failure receipt

  5. Rollback

    • revert workspace or restore checkpoint
    • retry with new information, not the same attempt
Fallback ladder flowchart showing escalation from minimal edit to rollback

Implementation: the "boring" applier that makes agents reliable

Below is a strict, production-oriented "exact replace with uniqueness" applier sketch. It intentionally refuses ambiguous edits.

from __future__ import annotations
 
from dataclasses import dataclass
from pathlib import Path
from typing import Iterable
 
@dataclass(frozen=True)
class ReplaceOp:
    path: Path
    old: str
    new: str
    expected_replacements: int = 1
    base_hash: str | None = None  # optional drift control hook
 
class EditError(RuntimeError):
    def __init__(self, code: str, message: str, *, data: dict | None = None):
        super().__init__(message)
        self.code = code
        self.data = data or {}
 
def _file_hash(text: str) -> str:
    # Replace with a real hash (sha256) in production.
    # Keeping it simple here to focus on control flow.
    return str(len(text)) + ":" + str(text.count("\n"))
 
def apply_replace_ops(ops: Iterable[ReplaceOp], *, root: Path) -> list[dict]:
    """
    Deterministic applier:
      - enforces sandbox root
      - enforces unique matching (or explicit expected_replacements)
      - supports drift control via base_hash
      - returns a structured receipt list (one per file)
    """
    root = root.resolve()
    by_file: dict[Path, list[ReplaceOp]] = {}
 
    for op in ops:
        if op.old == "":
            raise EditError("EMPTY_OLD", "Refusing empty 'old' for replace (ambiguous).")
        fp = (root / op.path).resolve()
        if not str(fp).startswith(str(root)):
            raise EditError("OUT_OF_ROOT", f"Refusing to edit outside root: {fp}")
        by_file.setdefault(fp, []).append(op)
 
    receipts: list[dict] = []
    for fp, file_ops in by_file.items():
        if not fp.exists():
            raise EditError("FILE_NOT_FOUND", f"File not found: {fp}", data={"path": str(fp)})
 
        text = fp.read_text(encoding="utf-8")
        current_hash = _file_hash(text)
 
        # Optional drift guard: if any op specifies base_hash, require it.
        for op in file_ops:
            if op.base_hash is not None and op.base_hash != current_hash:
                raise EditError(
                    "OUT_OF_DATE",
                    f"File changed since read: {fp}",
                    data={"path": str(fp), "base_hash": op.base_hash, "current_hash": current_hash},
                )
 
        original_text = text
        for op in file_ops:
            count = text.count(op.old)
            if count != op.expected_replacements:
                raise EditError(
                    "MATCH_COUNT_MISMATCH",
                    f"{fp}: expected {op.expected_replacements} match(es), found {count}.",
                    data={
                        "path": str(fp),
                        "expected": op.expected_replacements,
                        "found": count,
                        # In production: include candidate snippets around occurrences.
                    },
                )
            text = text.replace(op.old, op.new, op.expected_replacements)
 
        if text != original_text:
            fp.write_text(text, encoding="utf-8")
 
        receipts.append({
            "path": str(fp),
            "changed": text != original_text,
            "before_hash": current_hash,
            "after_hash": _file_hash(text),
        })
 
    return receipts

Receipts: the feedback schema that enables fast repair

The receipt is what keeps the model "grounded" in reality.

A good receipt contains:

Example receipt payload:

{
  "ok": false,
  "error": {
    "code": "MATCH_COUNT_MISMATCH",
    "message": "src/foo.py: expected 1 match(es), found 2.",
    "data": {
      "path": "src/foo.py",
      "expected": 1,
      "found": 2,
      "candidates": [
        {"line_start": 42, "line_end": 60, "excerpt": "...\n..."},
        {"line_start": 113, "line_end": 131, "excerpt": "...\n..."}
      ]
    }
  },
  "next_action_hint": "Widen `old` context to uniquely identify the intended occurrence."
}

This is the difference between "agent stuck retrying" and "agent repairs edit in one step."

Whole-file rewrites: make them safe, not scary

Whole-file rewrite is a legitimate tool—especially when:

But you must guard against elision and accidental churn:

Rewrite guardrails

A good policy is: "rewrite is allowed, but only when validation is cheap and the diff is explainable."

Planning vs applying: treat "apply" as a separate subsystem

A recurring pattern in strong systems is splitting:

This can be done with:

Planner-applier split: separating reasoning from reliable edit application

Case studies as patterns (not product trivia)

You'll see the same reliability moves repeated across scaffolds:

The important part is not which tool does it—it's that these are convergent solutions to the same mechanical problem.

Engineering checklist for a high-reliability edit subsystem

Applier correctness

Feedback quality (receipts)

Recovery

Guardrails

Instrumentation (the metrics that matter)

Closing: formats come and go—determinism and receipts don't

The ecosystem will keep shipping new diff syntaxes, editor tools, and "apply models." Don't anchor your system to any single representation.

Anchor it to:

That's what turns "LLM can propose good changes" into "agent reliably lands correct changes."

References