Coherence for the prose subset of project rules that can't be expressed as policy.

The mechanism: one log line in the agent's own context.

The plugin's job is small and visible. When a tracked artifact's version has changed since this session last observed it, the PreToolUse:Read hook injects a single sentence into the agent's additionalContext: the path, the version it last saw, the version the workspace coordinator currently holds, and who last wrote it. The model reads that sentence in line with the read it's about to perform.

One of two things happens next, and both appear in the session transcript:

• The agent acknowledges and re-reads. The next Read tool call fetches current content. The agent's response references the divergence explicitly. The user sees the trace.
• The agent doesn't acknowledge. The warning was emitted; the model chose not to act on it. That choice is in the transcript too — discoverable on review, attributable to the model, not silent.

Tracked artifacts include CLAUDE.md, plan.md, spec.md, runbook.md, DECISIONS.md. The same mechanism applies to anything important loaded at the session-start boundary — skill instructions, slash-command prompts, project rules. The visible case is CLAUDE.md; every plugin that loads instructions at the boundary that compaction crosses inherits the same shape.

Two classes of project rules. The plugin handles one of them.

Rules-as-prose are subject to context economics. The shape of the problem surfaced on a Claude Code thread as a single sentence:

Split CLAUDE.md content into two classes and treat each correctly:

The two fixes don't compete. Moving the tool-class rules out of CLAUDE.md into permissions.deny is hygiene that reduces the surface the plugin has to track. The prose residue — design constraints, architectural decisions, active-work artifacts — is what's left for coherence tracking.

Install.

Two steps. The Python coordinator + hook client comes from PyPI; the Claude Code plugin metadata and hook wiring come from the marketplace.

# Step 1 — Python coordinator + hook client (PyPI)
❯ pip install "agent-coherence>=0.8.0"

# Step 2 — Claude Code plugin
❯ claude plugin marketplace add hipvlady/agent-coherence-plugin
❯ claude plugin install agent-coherence@agent-coherence

# Track an artifact and observe state
❯ agent-coherence-track docs/plans/feature-x.md
❯ agent-coherence-status

After install, the plugin wires PreToolUse:Read + PreToolUse:Edit|Write hooks into Claude Code's hook system. A small per-workspace coordinator process tracks artifact versions across sessions, SQLite-backed for crash recovery and post-compaction rehydration. permissions.deny-aware — doesn't double-warn on tools the config already blocks.

What it looks like in a session.

Five scenes from a real claude run, captured as static screenshots. The hook output in scenes 3 and 4 is verbatim from the library's actual code paths. Scene 3 shows the warn-mode additionalContext advisory (default behavior, v0.1.1+); scene 4 shows the strict-mode permissionDecision: "deny" envelope (v0.2 headline feature, per-artifact opt-in via .coherence/strict_mode.yaml).

1

Two sessions, one plan.

Session A read docs/plans/feature-x.md 30 minutes ago. Session B just updated it. The plan describes a multi-step deploy that just changed.

2

Session A is asked to read it.

A claude invocation with --include-hook-events --output-format stream-json shows the hook events firing in line with the model's tool calls. The plugin's SessionStart hook reports the coordinator is ready; the assistant chooses the Read tool.

3

Warn mode — the stale-read advisory is injected.

Default behavior. Before the Read tool call executes, the plugin's PreToolUse:Read hook fires and an additionalContext sentence arrives in the agent's working memory: this file was updated by another session, your view is stale, here's the current version, consider re-reading. The call is allowed; the model gets to choose.

4

Strict mode — the same stale read returns permissionDecision: "deny".

With the artifact opted into strict mode via .coherence/strict_mode.yaml, the same hook returns a hard denial instead of an advisory. The deny text is structural and byte-identical across retries (per the Phase 0 falsifiability finding — varied text reads as prompt-injection to Opus and worsens retries). The model surfaces the denial verbatim and stops rather than acting on stale content. Strict mode is per-artifact opt-in; warn mode above remains the default. The v0.2 headline feature.

5

The assistant acknowledges before acting.

In warn mode, the model notes the divergence in its response instead of operating on a stale plan; in strict mode, it surfaces the denial verbatim and halts. agent-coherence-status confirms the coordinator's view of the artifact: v3, written by another session two minutes ago, no prior view from this session.

Verification outside the agent loop.

Sub-agent completed is a control-flow signal, not a semantic one. When a sub-agent returns claiming "I wrote file X," the runtime knows it returned — it doesn't know whether the write happened, or whether the content is what the parent expected.

The plugin's coordinator gives you a second source. After a sub-agent returns, the workspace coordinator either saw a PostToolUse Edit event on the claimed file from that session — or it didn't. agent-coherence-status surfaces the coordinator's view independent of any prose in the agent's final message. One primitive of the many a "completion with verification" pattern would need; queryable by any orchestrator before it accepts the sub-agent's claim and moves on.

What the plugin doesn't do.

Claiming less than the plugin does is the cheaper credibility trade.

• v0.2 is warn-mode by default, with per-artifact strict-mode opt-in. Warn mode (default) injects the additionalContext warning; this remains byte-identical to v0.1.1 for any artifact not listed in .coherence/strict_mode.yaml. Strict mode opts a tracked artifact into permissionDecision: "deny" on stale-read attempts — operator-controlled per-artifact, never global. The Phase 0 falsifiability experiment (2026-05-19) confirmed the routing-around-Read mechanism that motivated five-handler coverage and falsified the "varied deny text bounds retries" hypothesis (varied text reads as prompt-injection to Opus); v0.2 deny text is therefore static and byte-identical across retries.
• It doesn't fix model-internal compaction drift. When the model decides which prior context to retain across a compaction boundary, the plugin has no influence — that's an inference-layer decision. The plugin operates on the workspace artifact, not on what the model remembered about it.
• It doesn't fix inference-layer corruption. If the model produces incorrect output despite having current artifact content in context, that's a model-quality problem, not a coherence problem.
• It doesn't fix sandbox or permissions gaps. Tool-class restrictions belong in permissions.deny; the plugin tracks the prose residue that survives config-ification.

The plugin addresses the cross-session and cross-subagent artifact-coherence layer — one piece of the structural pattern Anthropic has explicitly chosen to leave to userspace. "For deterministic behavior, your best bet is to use hooks." Hooks are what the plugin uses.

Status & distribution.

v0.2.0 broad-beta open 2026-05-24 · v0.1.1 marketplace-tested baseline (N=80, 100% re-read-or-acknowledged on claude v2.1.131 / haiku). v0.2 adds per-artifact strict-mode opt-in, five-handler hook coverage, a structural TERMINAL_DENIAL_CLASSES security invariant, the agent-coherence-migrate-deny stricter migration helper, denial-only audit log, and a cross-implementation protocol corpus. 14-day post-launch monitoring window in progress per the BB1–BB8 rubric.

Not using Claude Code? The same coherence machinery is a Python library you can call directly from LangGraph, CrewAI, AutoGen, or custom orchestrators — same MESI protocol, different surface. The library demo runs a planner-executor refactor across three variants with real tsc verification. See the library demo →