Product · MCP server
pip install "agent-coherence[mcp]" · stdio · single host · fail-closedClaude Code, Cursor, or a custom runtime — any agent that edits shared files over Model Context Protocol carries the same silent failure: it writes from the view it read, not the version on disk. stale-write-guard-fs is a stdio MCP server that closes that gap with no Python integration at all: five tools that wrap the coherent workspace, so a stale view or a foreign edit gets a typed deny with a machine-readable recovery path — never a silent overwrite.
No adapter, no store class, no import. The server binds one workspace per session — SWG_ROOT, defaulting to its working directory — and the whole workspace is guarded unless SWG_MANAGED (a comma-separated glob list) narrows it.
pip install "agent-coherence[mcp]"
{
"mcpServers": {
"stale-write-guard-fs": {
"command": "stale-write-guard-fs",
"env": { "SWG_ROOT": "/path/to/shared/workspace" }
}
}
}
Run the red→green demo yourself — offline, deterministic, no keys: python -m examples.mcp_stale_write_guard.main. Source: agent-coherence/examples/mcp_stale_write_guard.
The tools mirror the coherent workspace's supported API — tracked read, guarded write, explicit recovery, version-checked CAS, and a health probe — so an agent's file loop maps onto them without ceremony.
| Tool | What it does |
|---|---|
swg_read |
Tracked read — registers the agent's view of the file |
swg_write |
Guarded write — a stale view or a foreign edit gets a typed stale_view deny with recover: reacquire, never a silent overwrite |
swg_reacquire |
Recovery — fresh identity + mandatory fresh read after a deny |
swg_write_cas |
Single-shot version-checked write for concurrent same-key contention |
swg_status |
Three-state coordination health: on / off / unknown |
Most guardrails fail agents in prose: an error string the model reads, paraphrases, and routes around. Here, denials come back as typed, machine-readable payloads — the agent can parse recover: reacquire and self-heal instead of retrying blindly.
plan.md, a peer commits a newer version, B writes back — and the newer version is gone. No error, no trace. The next agent builds on B's stale bytes as if the peer's work never existed.swg_write returns a typed stale_view deny naming the recovery step. B calls swg_reacquire — fresh identity, mandatory fresh read — re-derives its change on current bytes, and writes again. Both updates survive, and the denial is in the transcript.That's the sequential regime. For concurrent same-key contention — two agents racing to write one file — swg_write_cas is the single-shot version-checked path: exactly one wins, the loser gets a typed conflict naming the version that beat it, and re-derives. Never last-writer-wins, never a silent drop.
The server rejects path traversal and any access to the coordinator's own state directory, and fails closed on IO errors — an ambiguous filesystem state produces a refusal, not a guess. Foreign edits — a human, a formatter, a tool that doesn't go through the tools — are caught at the next tool call on that file by the same content-hash guards the coherent workspace uses.
Different surface, same family. Pick by where your pain lives:
| Surface | Guards | Reach for it when |
|---|---|---|
| MCP server (this) | Any shared files, through five explicit tools any MCP client can call | Your agents read and write workspace files over MCP — Claude Code, Cursor, or a custom runtime — and a stale or foreign-edit-clobbering write must be denied, not warned about |
| Claude Code plugin | The prose rules parallel Claude Code sessions share — CLAUDE.md, plan.md, specs |
You live in Claude Code and the failure is one session's view of the rules drifting from another's — or from what survives compaction |
Both sit on the same coordinator machinery; they don't conflict, and neither requires the other.
Same contract as the workspace it wraps — stated plainly, before you ask.
SWG_ROOT); the whole workspace is guarded unless SWG_MANAGED narrows it. Files outside the root aren't reachable — path traversal is rejected.swg_reacquire — fresh identity plus a mandatory fresh read. A bare retry of the same stale write stays denied; that's the mechanism, not a bug.Common questions about stale-write-guard-fs and guarded file access over MCP.
No. pip install "agent-coherence[mcp]" gives you the stale-write-guard-fs console script; one JSON block in your MCP client's config wires it in. The agent then uses the five swg_* tools like any other MCP tools. The Python library is under the hood, but you never import it.
Any client that speaks Model Context Protocol over stdio — Claude Code, Cursor, or a custom runtime. The server binds one workspace per session via SWG_ROOT (defaulting to its working directory); the whole workspace is guarded unless SWG_MANAGED, a comma-separated glob list, narrows it.
swg_write returns a typed stale_view deny with recover: reacquire — a machine-readable payload, not a prose error. The agent calls swg_reacquire, which re-mints its identity and forces a fresh read, then re-derives its change and writes again. An agent can parse the recovery field and self-heal instead of retrying blindly; a bare retry does not clear the denial.
That is a foreign edit, and it is caught at the next tool call on that file by the same content-hash guards the coherent workspace uses: a write that would clobber the out-of-band edit gets a typed deny instead of landing. The server is cooperative — it guards agents that route file access through the tools; it cannot see or block an edit as it happens outside them.
No — same contract as the volume it wraps: single host, managed paths, cooperative. Multiple MCP clients on one host sharing one workspace are coordinated; cross-host coordination is on the roadmap, demand-gated.
Different surface, same family. The Claude Code plugin wires coherence into Claude Code's hook system for the prose rules parallel sessions share — CLAUDE.md, plan.md — warning or denying at the tool-call boundary. The MCP server exposes guarded file access as explicit tools any MCP client can call, on any workspace you point it at. If you live in Claude Code and want CLAUDE.md/plan.md coherence across sessions, start with the plugin; if you want agents to read and write shared files through a guarded surface, use the MCP server.
15-minute call. Tell me which clients touch the workspace and how they write, and I'll tell you whether the guard covers your shape — or whether you're in the cross-host case that's still on the roadmap.