agent-coherence (Claude Code plugin)
Coherence for the prose subset of project rules that can't be expressed as policy.
CLAUDE.md is your project's prose contract — what to track, what to escalate, what to never touch. Most of those rules can't be expressed as permissions.deny or .claude/settings.json because they're about state, not tools: "this spec is now v3, your branch is editing v1", "the planner reorganized the auth section while you weren't looking", "session B just committed a change to the file you're about to write." agent-coherence is the runtime layer that makes those state changes visible across parallel Claude Code sessions sharing the same workspace.
Philosophy
Worktrees prevent file collisions, not stale-spec collisions. Two parallel Claude Code sessions can both read plan.md at v1, work independently in their per-session worktrees, and produce pull requests that reflect incompatible interpretations of v1 — even though the planner published v2 hours ago. The git surface stays clean; the model's understanding goes stale silently.
agent-coherence exists because that failure shape is structural — CLAUDE.md tool restrictions don't propagate to subagents, context compaction weakens rule adherence, and multi-session coordination has no platform-level synchronization primitive. Anthropic has confirmed this twice on the record: the official position is that hooks are the deterministic-behavior seam, and CLAUDE.md / .claudeignore are guidance, not constraints. This plugin lives in that seam.
The design bias: surface stale state to the agent itself via additionalContext, let the agent decide. The agent reads the warning alongside the file and almost always re-reads before acting. The 2026-05-18 launch gate measured 100% re-read-or-acknowledged rate across N=80 trials, zero ignored.
What it does
Watches tracked artifacts (CLAUDE.md, AGENTS.md, DECISIONS.md, docs/specs/, docs/plans/, docs/brainstorms/, plan.md / task.md / spec.md) across:
- Agent View ✓
- Multi-terminal (multiple
claude processes in the same workspace) ✓
- Task-tool subagents (subagent hooks fire under the parent's
session_id; warnings surface to the parent's context) ✓
Verified against claude v2.1.131 (2026-05-17 via internal Phase E.0 probe). The claude agents subcommand on v2.1.131 is a management UI, not a session spawner — out of coverage scope.
When one session is about to act on an artifact another session has updated, the plugin injects a warning into the agent's own context via additionalContext. The agent sees:
⚠ Stale read: docs/plans/feature-x.md was updated by session 90b1dfd3 at 2026-05-23T13:42:18Z. Current version is v3; you previously saw v1. Consider re-reading docs/plans/feature-x.md before acting on stale assumptions.
For tool-class rules that can be expressed as policy ("use rg, not grep"; "never sudo"; "no python -c"), run agent-coherence-migrate-rules or the stricter agent-coherence-migrate-deny — they propose permissions.deny entries derived from prose in CLAUDE.md. permissions.deny is structurally stronger than runtime hook denies: the runtime enforces it before the model can choose which tool to invoke.
Validation signal: anthropics/claude-code#59309 (filed 2026-05-13) plus three documented duplicates (#40459, #19471, #29423) confirm the failure shape across 6 months. Anthropic's position is "use hooks" — that's exactly what this plugin does.
Quick example
A typical cycle takes about 30 seconds. Set up the plugin in a workspace, then watch the agent re-read after a peer commit:
# Terminal 1 (session A)
claude
> Read docs/plans/feature-x.md and summarize the steps.
# Terminal 2 (session B, same workspace)
claude
> Edit docs/plans/feature-x.md to add a "v2: dual-write migration" step at the top.
> (B's session commits the edit; coordinator invalidates A's cached view)
# Back to Terminal 1 (session A)
> Now implement the first step you summarized earlier.
# Agent A receives a stale-read warning in its own context:
# ⚠ Stale read: docs/plans/feature-x.md was updated by session <B-short> at <ts>.
# Re-read docs/plans/feature-x.md before acting on stale assumptions.
# Agent A re-reads the file first, sees the new v2 step, and revises its plan.
