Search⌘ K
AI Features
Home
Courses
Harness Engineering for Reliable Coding Agents

Make Small Edits Without Clobbering Files

Explore techniques to safely modify code with a robust AI harness that replaces whole-file writes with precise small edits. Learn to use exact text anchors to ensure edits apply only if the current file state matches expectations, preventing overwrites or conflicts. Understand how to manage concurrent edits with a mutation queue, verify permissions, and maintain file integrity through atomic operations. This lesson equips you to build safer, more reliable editing tools for coding agents.

We'll cover the following...

Wren found the right file for CLIN-547, read it, and made a valid change. The diff still deleted somebody else’s work.

Two tool calls had read the same version of availability.js. The first added a provider-time-off check. The second changed the waitlist rule, then wrote back the complete file it had read thirty seconds earlier:

call A: read availability.js              -> version 12
call B: read availability.js              -> version 12
call A: write complete file               -> version 13, time-off check added
call B: write its version 12 plus one fix -> version 14, time-off check gone
Two reads at version 12, one fix lost

Every call succeeded. The final file parsed. The waitlist test passed. Nothing in the old write(path, content) contract could tell Wren that the content it supplied was stale.

This is a power failure inside an allowed workspace. Wren may change the file, but its only writing tool is a paint roller. The job needs a small brush. A stronger prompt about being careful cannot detect that the file changed after the read. The harness needs an edit tool that can reject an old or unclear request.

What are we building in this lesson?

Consider a paper form with one incorrect sentence. We would not recreate the entire form from memory. We would identify the exact existing sentence and specify its replacement.

Wren applies the same targeted-editing approach to code:

path      = which file
old_text  = the exact text Wren saw
new_text  = what should replace it
mode      = preview or apply
The four fields an edit call must carry

The old text is more than a location. It is a small claim about current state: “this exact text still exists once.” The edit may continue only while that claim remains true.

Why is whole-file writing unsafe?

A full-file write mixes two decisions that should remain separate:

  • What should change?

    • The intended replacement may be one condition or import.

  • What should remain?

    • Everything else in the model’s cached copy is silently treated as current.

Wren has evidence for the first decision. It usually has no fresh evidence for the second. A formatter, tool call, hook, or person may change the file after Wren reads it. Sending the whole old document back can erase that later work.

Wren replaces write with edit. One request carries a path, the exact old text, the replacement text, and an explicit mode:

edit({
  path: "availability.js",
  old_text: "return candidate.start < held.end;",
  new_text: "return overlaps(candidate, held);",
  mode: "preview"
})
One edit call, in preview mode

The old text is called an anchor. It states what Wren observed and what must still be true when the write begins. If the anchor is gone or appears twice, the harness stops and asks for a new read.

What must an edit prove before it touches disk?

The Edit Contract has six checks. Read them in the order a request travels:

  • The session has write authority.

  • The written path and resolved destination stay inside the workspace.

  • The destination is an ordinary file, not a symbolic link.

  • The old text is nonempty and occurs exactly once in the current file.

  • Preview mode returns the proposed patch without writing.

  • Apply mode replaces the file atomically, through a per-executor mutation queue.

Different parts of the harness own different checks. permit answers, “may this session write?” The edit code answers, “does this request still match the file?” The executor answers, ...