# Shipped: One Deny, Then the Current Version

> In agent-coherence 0.16.1 and plugin 0.7.1, a strict-mode Claude Code session whose copy of a file went stale is denied once, and its next Read gets the current version.

Published: 2026-11-15 · Canonical: https://agent-coherence.dev/blog/shipped-stale-read-recovery/

---
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](https://github.com/cohexa-ai/agent-coherence/issues/514)).

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

```text
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](https://github.com/cohexa-ai/agent-coherence/issues/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](https://github.com/cohexa-ai/agent-coherence/issues/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:

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

Update the plugin from its marketplace:

```bash
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:

```bash
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](https://github.com/cohexa-ai/agent-coherence/blob/v0.16.1/docs/guide.md#after-a-strict-mode-stale-deny) section quotes all four texts, and the [v0.16.1](https://github.com/cohexa-ai/agent-coherence/releases/tag/v0.16.1) and [plugin 0.7.1](https://github.com/cohexa-ai/agent-coherence-plugin/releases/tag/v0.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](/plugin/) has the setup.
