agent-coherence. Contact us

Shipped: Asking for a File Instead of Taking It

A planning agent holds plans/migration.md through its third pass, a reviewing agent's write to the file is refused as other_holder with nothing written, and the reviewer goes next once the planner releases the file

Agents that share a workspace take turns on the same files all day. Getting one agent to wait while another is halfway through a file is the hard part.

Take two agents in one repository. A planner rewrites plans/migration.md in three passes, the schema first, then the backfill, then the cutover, and each pass is its own write. A reviewer reads the plan and appends its notes. Both go through CoherentVolume, so neither can write over a version it never saw.

Between the planner’s second pass and its third, the reviewer reads the plan and writes its notes. That write takes the file. The planner holds a write grant on plans/migration.md, and by default a write takes a file from whoever holds it. The notes land on a plan with a finished schema, a finished backfill and an empty cutover. The planner’s third write then raises StaleView, because the file moved under it, and the planner has to reacquire and rebuild its cutover on top of notes written against half a plan.

Nothing is lost silently. Invalidation does its job. But the reviewer reviewed half a plan, and the planner lost the file in the middle of a change it was still making. The protection worked. Until this release, the reviewer had no way to hear “not yet”.

The key idea: a write can ask instead of take

Here is what changes: a writer that opts in asks for a file only if no other agent holds it, and a refusal leaves everything as it was.

from ccs.adapters.coherent_volume import CoherentVolume
from ccs.core.exceptions import OtherHolder

reviewer = CoherentVolume(root, managed=("plans/**",), on_held="refuse")
plan = reviewer.read("plans/migration.md")
try:
    reviewer.write("plans/migration.md", plan + b"\n## Review\n- Dry-run the backfill first.\n")
except OtherHolder as refused:
    print("held by", refused.holder_agent_id)  # nothing written, the planner keeps the file

While the planner holds plans/migration.md, the reviewer’s write raises OtherHolder and names the planner in holder_agent_id. No bytes reach the file and no grant changes hands. The planner finishes its cutover on its own plan.

How does the coordinator decide?

A refuse-mode write() on a managed path sends its pre-edit with "if_unheld": true. While another agent holds the path EXCLUSIVE or MODIFIED, the coordinator answers {"ok": false, "reason": "other_holder", "holder_agent_id": "..."} and changes nothing. A SHARED reader is not a holder, so the reviewer can read the plan while the planner works. The check runs inside the same registry hold as the grant, so two opted-in writers racing for a free file get one grant and one refusal naming the winner.

A refusal that quietly fell back to taking the file would be worse than none, because you would believe holds are honoured. So a refuse-mode volume reads pre_edit_if_unheld from the coordinator’s /status when it attaches, and raises RefuseModeUnsupported before it sends anything when the coordinator does not advertise it. That rules out a coordinator through 0.15.0 and the plugin’s Node coordinator through plugin 0.6.0.

The refusal also covers every spelling of the file. On a disk that folds names, such as the default macOS disk, every spelling the disk opens as one file now reaches that file’s one record, so a write of PLANS/Migration.md is refused while the planner holds plans/migration.md.

Giving the file back

A refusal is half the protocol. The other half is a holder that lets go when it is done.

A successful write() keeps its write grant after it returns, which is what keeps the planner’s three passes together. Until this release the only way to give that grant back was reacquire(), which drops every hold and starts a new attempt, so a refused writer waited for the coordinator’s sweep, about 600 seconds. Now the planner says when it is done:

planner = CoherentVolume(root, managed=("plans/**",), on_held="refuse")
for rewrite in (rewrite_schema, rewrite_backfill, rewrite_cutover):
    plan = planner.read("plans/migration.md")
    planner.write("plans/migration.md", rewrite(plan))
planner.release("plans/migration.md")  # True: the grant went back

release(path) gives back the grant on one file, keeps the planner’s other holds, and leaves it a read of the version it held. close() gives back every grant and ends the volume, and leaving a with CoherentVolume(...) as vol: block does the same. True means a grant went back. It does not mean the file is free.

The reviewer then reacquires and writes once, on the finished plan:

plan = reviewer.reacquire("plans/migration.md")  # the planner's finished plan
reviewer.write("plans/migration.md", plan + b"\n## Review\n- Dry-run the backfill first.\n")

The reacquire matters. One write() is both the ask and the write, so a write built without reading lands over whatever the holder committed once the file comes free. A reviewer that read before the planner’s last commit gets StaleView instead, and reacquire() hands it the planner’s bytes. Between tries, back off from 4 seconds, doubling with jitter, and stop at a bound you choose, because one holder can keep a file for up to 30 minutes.

The same turn-taking over MCP

An agent that edits files over Model Context Protocol gets the same behavior from the stale-write-guard-fs server. Refuse mode is the operator’s choice, set once in the server’s environment:

{
  "mcpServers": {
    "stale-write-guard-fs": {
      "command": "stale-write-guard-fs",
      "env": {
        "SWG_ROOT": "/path/to/shared/workspace",
        "SWG_MANAGED": "plans/**",
        "SWG_ON_HELD": "refuse"
      }
    }
  }
}
Step CoherentVolume stale-write-guard-fs
Opt in on_held="refuse" SWG_ON_HELD=refuse
Another agent holds the file raises OtherHolder reason: other_holder, recover: wait_then_reacquire, retryable: false
Find the holder holder_agent_id on the refusal holder_agent_id on the refusal, and swg_status
Give one file back release(path) swg_release
Give every file back close(), or leaving a with block the server’s normal exit
The coordinator cannot refuse RefuseModeUnsupported at attach one stderr line, exit 2

The refusal tells the agent how to wait. Its next_step says to release its own holds first, poll swg_status with backoff, then swg_reacquire the path, rebuild from those bytes and write once. Releasing first matters: two agents that keep their holds while each waits for the other wait 30 minutes and then overwrite each other’s work. swg_status reports the mode as on_held, lists the session’s own holds in held, and names each held path’s holder_agent_id and held_by. swg_release makes eleven tools.

On the Claude Code plugin’s coordinator

From plugin 0.7.0, the plugin’s built-in Node coordinator advertises pre_edit_if_unheld and serves the operator view of /status, so a volume with managed globs attaches to it, in refuse mode too. The volume needs that coordinator already running with its globs listed in .coherence/tracked.yaml and .coherence/strict_mode.yaml, because a volume never starts it.

Two things differ there. Claude Code sessions never opt in, so their edits take a file a refuse-mode volume holds, and on a workspace the Node coordinator serves those sessions are usually the other writers. Refuse mode there protects a volume’s files from other refuse-mode writers only. And the Node coordinator has no sweep. An opted-in request takes back a grant another agent has held for 30 minutes or more, so a refuse-mode volume that exits without close() refuses other refuse-mode writers on its files for up to 30 minutes.

A Node coordinator that plugin 0.6.0 started keeps serving after the update, and a refuse-mode volume fails closed against it, so restart it as the plugin’s upgrade note describes.

Scope, stated plainly

Single host, one coordinator, writers that go through it. That has not moved, and cross-host coordination still has not shipped.

A hold is not a lock. It is honoured only among opted-in writers, such as refuse-mode volumes and refuse-mode servers, and to every other writer it is a hold that does not stop an overwrite. An ordinary pre-edit still takes the file, and that includes every Claude Code hook edit, every displace-mode server and every older volume. The holder then meets a stale-view refusal at its next write, as before. The contract covers tracked paths only, and a volume opts in on its managed paths only, so a write outside them asks nothing and takes the file. Refuse mode needs on_error="strict", which is the default, and managed globs, and it is not available with remote_endpoint. It needs an agent-coherence 0.16.0 coordinator or the plugin’s Node coordinator from 0.7.0.

The known limits you are most likely to meet:

  • A stale-write-guard-fs server that exits without closing its volume, from a signal, a crash or a host that kills it, leaves its write grants standing until the coordinator takes them back: about 10 minutes on this package’s coordinator, up to 30 on the plugin’s. A restarted server cannot release them, so in refuse mode its own writes to those paths are refused other_holder until then (#591).
  • A model that runs both the plugin’s hooks and a refuse-mode MCP server is two sessions to the coordinator. After it edits a file with its own file tools, its swg_write of that file in the same turn is refused other_holder, naming its own hooks session, which lets go only when the turn ends (#592).
  • Nothing closes a volume when its process exits. Without close() or a with block, its grants stand until the coordinator takes them back, and every refuse-mode writer behind them waits that long.

The full list is under Known limitations in the v0.16.0 release notes, and the taxonomy covers which failures are the runtime’s to prevent at all.

Upgrading from 0.15.0

The registry schema stays at 10, so nothing migrates, and 0.15.0 still opens a store this release has opened. Upgrade the coordinator, its clients and the Claude Code plugin together, and pair this release with plugin 0.7.0 or later. A few changes can break a setup that worked before. A coordinator start refuses a workspace whose .coherence is a symbolic link or holds one directly inside it, a second read-write open of one store raises StoreHeldError, a volume attached to a coordinator that restarts must be built again, and write() returns a WriteResult. The guide’s Upgrading from 0.15.0 section lists every change.

Get it running

Writers that can only take files from each other coordinate by interruption. Writers that can ask coordinate by turns: one finishes, gives the file back, and the next starts from the finished work. The refusal and the release are both small, and together they make taking turns on a shared file something the coordinator enforces, on a single host, among the writers that ask.

pip install "agent-coherence[mcp]"

The guide’s Refusing a file another agent holds section lists every answer a refuse-mode write can get, and the MCP server page has the server’s setup. Start with the file your agents already take turns on.

Frequently asked

How do I make an agent wait while another agent is still editing a file?

On agent-coherence 0.16.0, build the waiting agent's CoherentVolume with on_held="refuse", or start its stale-write-guard-fs MCP server with SWG_ON_HELD=refuse. While another agent holds a managed file, that agent's write is refused with OtherHolder or other_holder, nothing is written, and the holder keeps the file. On a single host this holds only among writers that opted in, so an ordinary write, including a Claude Code hook edit, still takes the file.

Is agent-coherence refuse mode a lock?

No. A hold is honoured only among writers that opted in, so a Claude Code hook edit, a displace-mode MCP server or an older volume still takes the file, and the holder finds out at its next write. On a single host with default settings, the Python coordinator's sweep takes a grant back from a holder that goes quiet after about 10 minutes, and from any holder after 30 minutes.

How does an agent give a file back after writing it?

Call release(path) on the CoherentVolume, or swg_release on the stale-write-guard-fs MCP server, to give back the write grant on one file while keeping the others, or close() to give back every grant and end the volume. A writer waiting in refuse mode can then go next at once instead of waiting for the coordinator's sweep. A process that exits without closing its volume leaves its grants standing until the coordinator takes them back.

Does refuse mode work on the Claude Code plugin's coordinator?

Yes, from plugin 0.7.0, when the plugin's Node coordinator is already running and its .coherence/tracked.yaml and strict_mode.yaml list the volume's managed globs. Claude Code sessions never opt in, so their edits still take a file a refuse-mode volume holds. That coordinator has no sweep, so an opted-in request takes back a grant another agent has held for 30 minutes or more.