Your Session Compacted, and It Forgot What It Was Holding
You run long Claude Code sessions because the work is long. Claude Code compacts long sessions. After that the session operates off a summary that the model has written rather than the conversation itself.
Here’s a case where that goes wrong. Two sessions share one repo. Session A is three hours into a refactor. It’s been editing plan.md, and it read docs/api-spec.md an hour ago to work out what step 3 should say. Session B, in the other terminal, has changed the spec (one endpoint now returns a different shape) and has committed it. A’s context then fills up and Claude Code compacts it.
A’s summary is spot on, really. It correctly states that the refactor is on step 3, that plan.md has been updated through step 2 and that the API returns the old shape. The last of those is the issue. It was true when A looked at the spec, and a summary has absolutely no way of saying “as of an hour ago”. It doesn’t state at all that A was holding plan.md either. So A proceeds and writes step 3 against a version of the spec that B has already replaced.
Here’s what changes: the coordinator passes the session the list of what it held and what moved while it was working. The summary can’t be trusted to contain that list.
What does compaction actually drop?
A summary will tell you what the work was about. It’s absolutely terrible at preserving the state of the files. Which files was this session actually editing? What version of each did it last read? Has anyone else changed any of those files since? None of that comes across as progress, so it doesn’t really survive.
Users just see the result and report it as the model getting worse. One of the reports on the Claude Code tracker describes rules that are followed at the start of a session and then get weaker after compaction. Some of that is down to the model’s own decision about what to keep, and no plugin can change that. Anthropic’s suggestion on a related thread was simple: “For deterministic behavior, your best bet is to use hooks.”
The other bit isn’t a model problem at all. The record was outside the model the entire time. The coordinator knew that A held plan.md. It knew that A’s last sighting of the spec was at version 3 and that B had taken it to version 4. That’s the ledger that the infrastructure can verify, and compaction is the point at which the session can no longer see it.
Why doesn’t the normal stale-read warning pick this up?
The plugin already warns a session when it touches a tracked file that another session has changed. That warning is attached to the tool call. If A goes back and reads or edits docs/api-spec.md again, it will be told the file has moved.
After compaction A has absolutely no reason to. As far as A is concerned it has already read the spec, because the summary tells it what’s in the spec. A never opens the file and the warning doesn’t fire. The stale fact ends up in plan.md, which A is allowed to write. No step fails.
What the session is told
Since plugin v0.5.0 a second SessionStart hook fires when the session starts up again after a compaction, either automatic or /compact. Normal starts, resumes and clears do nothing. On a compaction the hook asks the coordinator one question: what did this session hold, and what has moved since it last looked? The answer is then placed into the model’s context:
Post-compaction re-grounding (agent-coherence):
docs/api-spec.md advanced to v4 past your last-observed v3 — re-read before relying on it.
At compaction you held EXCLUSIVE on plan.md (v7) — re-acquire before writing.
Versions are as of this re-grounding; a more recent read supersedes this notice.
Now A has the two facts that its summary dropped. The spec has moved, so A re-reads it before doing step 3. A was holding plan.md, so it takes that file again before editing.
| Question | Answer |
|---|---|
| Where does the list come from? | The coordinator’s own record. Each grant and commit stores the version the session saw, in the same write. |
| When does the model get it? | At the next user message, on --resume, and for a session running on its own, on its next allowed tool call. |
| How long is it? | Three file lines at most, then one line pointing to agent-coherence-status for the rest. |
| What if the session held nothing? | Nothing is sent. |
| Can it arrive twice? | Yes, in one case. A session running on its own gets it mid-run and again at the next user message. The closing line tells the model that a newer read overrides the notice. |
The notice is deliberately short. A session that touched 40 files doesn’t get 40 lines pushed into a context that’s just been cleared out to make space. It has no timestamps, and both coordinators that the plugin can run produce it byte for byte.
Scope, stated plainly
This is for tracked files (CLAUDE.md, plan.md, specs, runbooks and so on) on a single host, for sessions that go through the coordinator. Coordination across machines has not yet shipped.
It doesn’t fix what the model has chosen to remember. If the rules in your CLAUDE.md get weaker after compaction, that happens within the model itself, and this notice has no effect on it. The plugin works on the file, not on the model’s memory of the file.
Nothing compels the model to act on the notice. The model just gets the facts in its context when it needs them. I haven’t actually measured how often it uses them.
It fails open. If the coordinator is down when the session compacts, that compaction’s notice is lost and the session just carries on. One bug to be aware of. Prior to plugin v0.6.0, a Bash or Grep command that strict mode denied was still recorded as a read, which could silence the stale line for a file the session had never seen at its current version. That’s now fixed, so if you’re on v0.5.0 you should update.
The taxonomy of how a write disappears covers which of these failures a runtime can prevent at all.
Why it matters
Compaction is when a session is most likely to lose track of its own state, and it arrives with no error and a perfectly fine summary. The more a session runs on its own, the more often that happens with no one looking. An overnight session can compact several times before anyone actually reads a line of it.
One concrete next step. The next time a long session compacts, ask it which files it was editing and whether any of those files changed while it was working. Then check that answer against git log. If it’s absolutely certain and wrong, you’ve reproduced the problem.
The plugin installs in two commands, and the plugin page has the rest:
claude plugin marketplace add Cohexa-ai/agent-coherence-plugin
claude plugin install agent-coherence@agent-coherence
Source and release notes are available at github.com/Cohexa-ai/agent-coherence-plugin.
Frequently asked
Why does Claude Code lose track of files after compaction?
Compaction replaces the conversation with a summary the model writes. The summary keeps the gist of the work and can drop bookkeeping, such as which shared files the session was editing and whether another session changed one of them. Afterwards the session relies on what the summary says a file contained.
Does the plugin stop Claude from ignoring CLAUDE.md after compaction?
No. Which instructions the model keeps across a compaction is decided inside the model, and the plugin has no influence on it. On a single host, the plugin tells a compacted session which tracked files it held and which ones a peer session changed, so it can re-read them.
Do I see the re-grounding notice myself?
No. It is delivered as hook context, which Claude Code gives to the model and does not show in the interface. To see the same record yourself, run agent-coherence-status in the workspace.
What happens if the coordinator is down when a session compacts?
Nothing is delivered for that compaction. The hook fails open by design, so coordination never blocks a session, and that compaction's re-grounding is lost. The ordinary stale-read warning still fires the next time the session touches a tracked file that moved.