# Shipped: Asking for a File Instead of Taking It

> In v0.16.0 a writer that opts in is refused a file another agent holds, instead of taking it, and a holder gives the file back when it is done.

Published: 2026-11-13 · Canonical: https://agent-coherence.dev/blog/shipped-refuse-mode/

---
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](/blog/shipped-write-side/) 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.

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

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

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

```json
{
  "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](https://github.com/cohexa-ai/agent-coherence-plugin/releases/tag/v0.7.0) 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](/blog/agent-swarm-reinvented-locks/). 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](https://github.com/cohexa-ai/agent-coherence/issues/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](https://github.com/cohexa-ai/agent-coherence/issues/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](https://github.com/cohexa-ai/agent-coherence/releases/tag/v0.16.0), and [the taxonomy](/blog/silent-data-loss-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](https://github.com/cohexa-ai/agent-coherence/blob/v0.16.0/docs/guide.md#upgrading-from-0150) 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.

```bash
pip install "agent-coherence[mcp]"
```

The guide's [Refusing a file another agent holds](https://github.com/cohexa-ai/agent-coherence/blob/v0.16.0/docs/guide.md#refusing-a-file-another-agent-holds) section lists every answer a refuse-mode write can get, and the [MCP server page](/mcp/) has the server's setup. Start with the file your agents already take turns on.
