agent-coherence. Contact us

Shipped: One Deny, Then the Current Version

Session B adds a step to docs/plan.md, session A's edit from its old copy is denied once, A reads the file again and gets version 2, and A's next edit lands on top of B's change

Strict mode exists so a Claude Code session does not act on a copy of a file that another session already changed. Until this release, it also kept that session from reading the file again.

Take two sessions in one repository. docs/plan.md is tracked and listed in .coherence/strict_mode.yaml, because both sessions work from it and a step written against an old plan is the expensive mistake. Session A reads the plan and starts on step 3. Session B, in the other terminal, adds a step 4, and the coordinator records B’s edit as version 2. A finishes step 3 and goes to mark it done.

A’s Edit is denied. That part is the point. A’s copy of the plan is version 1, and an edit built from it would write over B’s step 4. The deny told A to re-read the file with the Read tool. A did, and the Read was denied too. So was the next one, and every Read of docs/plan.md after it, for the rest of the session. The deny text ended by saying that retrying the same operation would produce the same denial, and for a Read that was exactly true. Only a Bash read run twice, a new session or a new subagent got the file back.

The protection held. The session stopped working on the one file it most needed.

One deny, then the current version

Here is what changes: the first stale Read or Edit is still denied, and the coordinator remembers that it sent that deny. The session’s next Read of the file is admitted at the current version (#514).

A’s Edit now gets this deny, word for word from a 0.16.1 coordinator:

Stale read denied: docs/plan.md was updated by agent 814dac78 at 2026-11-15T15:30:43.140913+00:00. Read docs/plan.md again with the Read tool: the next Read returns the current version, and edits of docs/plan.md are denied until you have read it.

A reads the plan. The coordinator grants A a read at version 2 and answers the hook {"status": "fresh", "version": 2}, with no stale warning, so the Read returns the plan with B’s step 4 in it. A’s next Edit is admitted, and step 3 is marked done on top of B’s change. Both edits are in the file.

A’s next action Through 0.16.0 and plugin 0.7.0 From 0.16.1 and plugin 0.7.1
Edit from the old copy denied denied
The same Edit again, without reading denied denied
Read denied admitted at version 2
Edit after that Read denied admitted

The Python coordinator in agent-coherence 0.16.1 and the plugin’s built-in Node coordinator in plugin 0.7.1 make the same change, with the same deny texts.

What still gets denied

The recovery admits a Read, never a write. An Edit or Write that A sends before it reads the file again is still denied, with the same text, so a write built from the old copy does not land.

A Read is admitted only when the bytes it reads are the content the coordinator recorded for the current version, or the coordinator recorded none. Admitting a Read of any other bytes would let the next Edit build on bytes no session committed. So a file changed outside the coordinator, by hand or by a script, keeps the Read denied, with a text that says the change was made outside the coordinator and tells the session not to restore or overwrite it. When the cause is another session’s write that has not been committed yet, the text can say so instead: wait for that write to be committed, then read again.

The recovery covers one stale copy. A’s next admitted Read or Edit of the file uses it up, so the next time B changes the plan, A starts from a deny again. A commit that lands between the deny and A’s Read costs no second deny, because the Read returns the newer version.

Scope, stated plainly

Single host, one coordinator, sessions that go through it. Cross-host coordination has not shipped.

Only the Claude Code hooks get this recovery. A CoherentVolume, the stale-write-guard-fs MCP server built on it, the substrate session and the effect fence keep the deny that only reacquire() or a new agent id clears. That is deliberate. A volume’s caller can hold a buffer built before a peer’s commit, and two plain reads must not make a write() of that buffer legal. From 0.16.1 the volume marks its plain reads, so the coordinator can tell them from a hook Read.

The limits you are most likely to meet:

  • The coordinator keeps its record of the deny in memory. After a coordinator restart, a session with a stale copy is denied once more, and the Read after that is admitted.
  • A Read and a Write sent in one message, or a Read of part of the file, counts as reading the current version, so a Write of the whole file built from the old copy can then be admitted (#624). Have sessions read a strict file whole, in a message of its own, before they write it.
  • A CoherentVolume from 0.16.0 or earlier marks none of its plain reads. Through a coordinator with the recovery, such as the plugin’s Node coordinator from plugin 0.7.1, its second plain read heals a stale view, and a later write() of a buffer built before a peer’s commit is admitted too (#629). Upgrade the library with the plugin.
  • A coordinator that was running before the upgrade keeps the old behavior until it restarts.

Two smaller changes ship alongside. A volume or substrate session now merges its globs into .coherence/tracked.yaml and strict_mode.yaml under their locks, so a concurrent agent-coherence-track no longer loses its entry, and it reports a policy file it cannot load, lock or write as PolicyFileRefused. And the library’s hook client can deny an edit of a strict file another agent holds, through .coherence/hook_on_held. That setting is off by default, the plugin’s Node hook client does not read it, and how models respond to its deny is not yet measured with real Claude Code sessions, so it stays off until it is.

Upgrading

Upgrade the coordinator, its clients and the Claude Code plugin together, and pair agent-coherence 0.16.1 with plugin 0.7.1. The registry schema stays at 10, so nothing migrates. On the Python backend, and wherever a CoherentVolume or the MCP server runs:

pip install --upgrade "agent-coherence>=0.16.1"

Update the plugin from its marketplace:

claude plugin marketplace update agent-coherence
claude plugin update agent-coherence@agent-coherence

Then stop the coordinator that was running before the upgrade, from the workspace root, and start a new session, which starts a new coordinator:

ps -p "$(head -n 1 .coherence/server.pid)" -o command=   # names dist/coordinator.js or ccs.cli.coherence_coordinator
kill "$(head -n 1 .coherence/server.pid)"

A script or prompt that matches the strict-mode deny texts byte for byte must accept the new wording. The guide’s After a strict-mode stale deny section quotes all four texts, and the v0.16.1 and plugin 0.7.1 release notes have the full upgrade notes.

Why it matters

A deny the session cannot get past leaves a person to clear it, with a new session or a hint to try a Bash read. A deny that names the one action that clears it, and then admits that action, is a deny the session follows on its own. Strict mode should stop a session from acting on a stale copy, not stop the session.

If you run strict mode on a shared plan or rules file, upgrade, restart the coordinator, and watch the next stale deny: one refusal, one Read, and the session is back on the current version. The plugin page has the setup.

Frequently asked

Why does Claude Code keep denying reads of a file after a strict-mode stale read?

Through agent-coherence 0.16.0 and plugin 0.7.0, the coordinator denied a strict-mode session's first stale Read or Edit of a file and then every Read after it, for the rest of the session, although the deny told the session to re-read the file. From agent-coherence 0.16.1 and plugin 0.7.1, on a single host, the first stale Read or Edit is still denied, and the session's next Read of the file gets the current version. Restart a coordinator that was running before the upgrade, because it keeps the old behavior until it restarts.

Can a stale Claude Code session still write over another session's change?

An Edit or Write sent before the session reads the file again is still denied, so a write built from the old copy does not land. One gap remains: a Read and a Write sent in one message, or a Read of part of the file, counts as reading the current version, so a Write of the whole file built from the old copy can then be admitted. Have sessions read a strict file whole, in a message of its own, before they write it.

Does a CoherentVolume or the stale-write-guard-fs MCP server recover the same way?

No. Only the Claude Code hooks get the one-deny recovery. A CoherentVolume, the stale-write-guard-fs MCP server built on it, the substrate session and the effect fence keep the deny until reacquire() or a new agent id clears it. A CoherentVolume from agent-coherence 0.16.0 or earlier must be upgraded, because through a coordinator with the recovery its second plain read heals a stale copy.

What if the file changed outside the coordinator?

Then the Read stays denied. The recovery admits a Read only when the bytes on disk are the content the coordinator recorded for the current version, or it recorded none. A file changed by hand or by a script gets a deny saying the change was made outside the coordinator, and the read stays denied until the change is committed through the coordinator.