Issue Draft: Edit tool's "modified since read" error message is misleading and triggers unnecessarily

Type: Bug / UX issue Target repo: anthropics/claude-code Filed by: Joe (PAI user) on behalf of agent observation Date: 2026-04-15

Summary

The Edit tool emits a "File has been modified since read, either by the user or by a linter" error when the modification was actually caused by Claude's own previous Edit on the same file in the same response. This produces:

1. Misleading attribution — the message implies external interference (user or linter) when none occurred.
2. Visible error noise — the user sees Error editing file followed by an auto-recovery Read and retry, which looks like a problem even though it always succeeds.
3. Unnecessary auto-recovery turns — wastes a tool call to re-Read the file and retry, when the agent's own prior Edit was the only writer.

Reproduction

In a session where Claude edits a single file multiple times in sequence (e.g., updating frontmatter + multiple checkbox flips in a PRD/markdown file), the second or third Edit will frequently fail with:

Error: File has been modified since read, either by the user or by a linter.

There is no actual external linter or user modification — the file was modified by Claude's own preceding Edit tool call.

Root cause hypothesis

The Edit tool maintains an internal cache: (file_path, last_known_mtime). After a successful Edit, the cache should update to the post-write mtime. In practice, it appears that:

• Either the cache update lags slightly behind the filesystem mtime update,
• Or filesystem events from PostToolUse hooks (which read the same file but don't write it) bump some "seen" timestamp that confuses the cache,
• Or the cache is refreshed only on explicit Read calls, not on the agent's own Edit/Write writes.

The result is that two back-to-back Edits on the same file race the cache, and the second one fails.

Why the message is misleading

The current text — "File has been modified since read, either by the user or by a linter" — directs investigation toward:

• Checking what user action might have edited the file (none).
• Checking what linter is configured (often none).
• Wondering if a hook is interfering (in our case, no PostToolUse hook writes the file).

The actual cause — "your own prior Edit advanced the file's mtime past my cached value" — is never suggested by the message. This makes diagnosis disproportionately expensive for what is effectively a tool-internal cache lag.

Proposed fix

Option A (preferred): Fix the root cause

After a successful Edit/Write, the tool should update its read-cache to the new mtime atomically. If this is already the intent, the bug is that it doesn't always work — likely a race between the write and the cache update. Investigate.

Option B (cheap): Improve the error message

If the cache lag is hard to fix structurally, at minimum change the message to acknowledge the most common cause:

Current: File has been modified since read, either by the user or by a linter. Read the file again to see the latest content.

Proposed: File has been modified since the last Read by this tool. This commonly happens when Claude's own prior Edit/Write advances the mtime faster than the read-cache refreshes; less commonly, a user or linter modified the file externally. Re-reading the file will refresh the cache.

This re-prioritizes the likely cause and stops misdirecting investigation.

Option C (deeper): Auto-recovery should be silent

The Edit tool already triggers an automatic Read-and-retry when the modified-since-read error fires. If this auto-recovery succeeds (which it does in 99%+ of cases when no external writer exists), the user should not see the error at all — only the successful retry. Surface the error to the user only when the retry also fails (i.e., true external interference).

Why this matters

Agent sessions that do iterative file editing (PRDs, structured docs, configuration files) hit this multiple times per session. The visible error noise:

• Erodes user trust ("did something break?").
• Forces the user to stop and investigate ("what linter is interfering?") when no real problem exists.
• Sends the agent down debugging rabbit holes searching for hooks that touch the file (in PAI's case, we verified no hook writes PRD.md, and yet the error fires routinely).

Affected workflow

Specifically: PAI's Algorithm phases (EXECUTE/VERIFY) where the agent maintains a PRD.md file with frontmatter (phase, progress) and ISC checkboxes that flip throughout execution. Each EXECUTE phase produces 5-10 Edits to the same file, of which 2-4 typically race the cache and produce visible errors + auto-recovery turns.

Repro environment

• Claude Code v2.1.109 (also reproduces on v2.1.107 and v2.1.92)
• macOS, zsh
• No external editors or linters touching the affected files
• Verified: no PostToolUse hooks in PAI's settings.json write to the affected file

Related

This affects the perceived stability of long agent runs and is a recurring source of user-visible "errors" that aren't really errors.