File-Edit Engineering: Read Before Write

Three classic ways Agents trash files: wrong spot, overwrite unread files, edit from stale content. DSH’s answer is a trio plus a ledger. The trio is the model-facing read/edit/write tools (docs/tool-catalog.zh.md): read does windowed, line-numbered text; edit does literal replace; write creates or overwrites whole files. The ledger is a weak-map inside the fs-observation-policy plugin, keyed by session, recording each file target’s observation state.

The ledger has three states. unseen: no entry for the file. present@vN: it was read, at version vN — an opaque freshness token from the filesystem backend. absent: the path was confirmed missing, e.g. a failed read. After every successful read/write/edit, the tool emits fs/observed and the plugin updates the books.

The verdict happens before any write. When a tool wants to write or edit, it dispatches fs/write-intent or fs/edit-intent — a single-slot cascade: the first listener that returns a decision owns it, and by deployment convention that’s this policy plugin. It sets guard conditions from the ledger; the real check runs in an atomic critical section on the backend: verify version, then match, then replace — nothing else can slip in.

The whole policy plugin is under 140 lines — two ledger lookups at the core. write’s verdict is a three-line choice: if the ledger shows present, return a replaceIfVersion guard with that version; if there’s no entry or confirmed absent, return createIfAbsent so creation is allowed only when missing. The header comment draws the decision table with two arrows. That’s “write always has a path”: new files need no prior read; overwriting someone else’s file is not allowed.

Source:packages/fs/fs-observation-policy/src/index.ts writeIntent, lines 61–71, verified on 2026-08-13。

edit’s verdict is stricter — unread means you don’t even get a guard; it throws. Worth reading whole: the two throws are this chapter’s title in code:

  editIntent(target: FsTarget, actor: object | undefined): { version: FsVersion } {
    const owner = this.owner(actor)
    const prior = owner ? this.get(owner, target.targetKey) : undefined
    if (!owner || prior === undefined) {
      throw new FsError(`edit requires reading "${target.displayPath}" first`, 'FS_NOT_OBSERVED')
    }
    if (prior.kind === 'absent') {
      throw new FsError(`cannot edit "${target.displayPath}": not found`, 'FS_NOT_FOUND')
    }
    return { version: prior.version }
  }

The returned { version: prior.version } is that freshness token. Backend editText checks it against the current version first — mismatch → FS_STALE_VERSION; only then literal match. old_string must hit exactly once: many hits → FS_AMBIGUOUS_EDIT; none → FS_EDIT_NOT_FOUND unless replace_all was explicit. Match, EOL handling, staleness, and atomic replace all run in one critical section (docs/subsystems/filesystem.zh.md line 151).

Three more details worth keeping. First, the defense is removable: unload the plugin and write/edit fall back to unconditional bare-provider behavior — tool schemas don’t change a character, because tools only dispatch events and never call policy directly. Second, read authorization is freshness-only, whole-file or windowed alike: if the file hasn’t changed, reading 10 lines still authorizes a later whole-file edit. Third, read_image is classic conditional registration: no ctx.attachments capability → never register; registered but the routed model won’t take images → refuse at execute time (docs/tool-catalog.zh.md line 718). Evolution note: the contextual diff card on edit results first recomputed hunks at result time (archived Agent Note .agents/notes/archived/architecture/2026-07-02-result-time-applied-hunk-diffs.zh.md); later the backend returns full before/after, the tool computes hunks into meta, and replay skips recomputation — the channel covered in Tool Output Contract.

Claude Code also forces read-before-write — the rule sits in the tool’s own prompt. FileEditTool prompt, original:

“This tool will error” shows CC’s runtime really enforces the check — not polite prompt theater. Non-unique old_string fails; add context or use replace_all — isomorphic to DSH. The difference is where the defense mounts: CC’s read-first check lives on FileEditTool itself; DSH extracts it into a plugin so read/edit/write/str_replace_editor share one ledger with zero permission code in the tools. How CC detects stale reads after external edits isn’t shown in reviewed study materials — kept provisional on public evidence.

Grok Build’s search_replace tool still shows the same fight. Config has skip_read_before_edit, commented as a deprecated runtime no-op that only gates the Read-tool dependency at config time — read-before-write was once a hard switch, later loosened. Stale-read handling shows the orientation gap even more clearly:

In plain talk: when a human edit makes matching fail, Grok appends a hint in the error text nudging the model to re-read. That’s defense at hint concentration — relies on the model behaving. DSH is version-token concentration: mismatch → FS_STALE_VERSION, physically no write. Grok has strengths too: unicode_normalized_fallback retries when smart quotes or long dashes foil visual matching (same file lines 103–110); DSH edit currently matches exactly after EOL normalization. Hunk-level change tracking lives in Grok’s xai-hunk-tracker crate — see Implementation families, registry & dynamic MCP for the wider tool-system map.