read_state: flag write overwriting a file the agent never read

[bobzhang]

What

Adds a session-scoped ReadState (agent_tool/read_state) — a seen-set the file tools share for one agent run — and uses it to flag a write that overwrites a file the agent never read this session:

ok: wrote N chars to <path> (overwrote existing file you had not read this session)

read records a path only on a complete read (whole file shown, untruncated); write records after writing (it authored the content) and checks before overwriting. The agent loop creates one ReadState and hands it to read/write. Standalone tool use (no ReadState) keeps prior behavior.

ReadState::ReadState() is the constructor, as requested.

Why a soft flag, and these exact rules (data-driven)

I analyzed 19 recorded toml-parser agent runs before building this. Across 395 writes: only 71 (18%) followed a read; 175 were blind re-writes of self-authored files; 149 were first-touch creates. In a from-scratch task (empty workspace) that's almost all benign — there's nothing pre-existing to clobber. So:

• Soft annotation, not a hard "read first" error. A hard guard would loop on those 175 self-rewrites. write records the path after writing, so re-writing a file the agent itself created is never flagged.
• Seen-set only, no mtime/staleness. The "changed since you read it" check guards against concurrent editors/linters — which don't exist in a single batch CLI session.
• Net effect: dormant in from-scratch tasks (would have fired ~0 of those 395 writes); the value shows up on pre-existing codebases.

(The live e2e against DeepSeek is firewalled in CI, so those recorded runs are the evidence.)

Subtleties (caught by codex review, now fixed)

• A partial read (start_line, small max_lines, or a max_output_chars truncation) must not mark the file fully seen — otherwise a later overwrite of the unseen remainder wouldn't warn. Recording now requires shown_lines == total_lines && !truncated (a high max_lines that still covers the file counts).
• edit deliberately does not record. openseek doesn't require read-before-edit, so an edit only shows the agent a fragment; promoting an edit-only path to "fully seen" would wrongly suppress a later write's warning.

Validation

• moon check + moon fmt clean; 75 tests pass across the touched packages (incl. partial-vs-full read and unread-overwrite cases).
• Public API: read/write definition() gain an optional read_state?; new agent_tool/read_state package. edit unchanged.
• Reviewed by codex over three rounds (it found the partial-read gap and the edit-promotion issue; both fixed): final "No actionable correctness issues were found in the diff."

🤖 Generated with Claude Code