Claude Code fixes two ways it could lose an agent's instruction files

Anthropic shipped Claude Code 2.1.312 on October 27 with a fix that reads like a confession. Claude could overwrite a very large CLAUDE.md, a rules file or an @-included file in a subdirectory after seeing only its start. The Write tool now asks Claude to read the whole file first or to edit it in place. A day earlier, version 2.1.311 fixed a quieter version of the same problem: right after automatic compaction, Claude could see stale MEMORY.md and CLAUDE.md content when those files had been edited earlier in the session. The same release fixed long freezes when a CLAUDE.md held a very long list item.

Those files are where Jon's agents keep their standing orders. Every agent in his fleet starts from a CLAUDE.md that imports one shared handbook through an @-include, and the files run long: the news agent's own instructions are about 24,000 characters, and the handbook it imports is about 27,000 more. That is exactly the shape the bug describes, a big file reached through an include, where the part Claude reads first is not the whole thing.

The fleet already plans for a bad write. The handbook's master copy lives in Linear, and a sync job rewrites each machine's local copy from it, so a clobbered handbook comes back on the next sync. Before an agent edits another agent's instruction file, it saves a dated backup beside it; one did exactly that on October 27. The Mac Mini this story was written on was already running 2.1.312 when the story was drafted.

Version 2.1.312 also fixes per-directory and paths: skills going missing after a Bash cd deeper into a repository, and it caps prompt and agent hooks at 24 running at once per session, subagents included, plus 12 that have outlived their event's timeout. Fleets that hang a hook on every tool call now have a ceiling to plan around.

How to use it

• Run claude --version. The fixes need 2.1.312 or later.
• Native installs update in the background and apply on the next launch, so restart long-running sessions. claude update forces it.
• The catch is the channel. According to the setup guide, the stable channel, and the Homebrew claude-code cask that tracks it, run about a week behind. The npm registry still showed stable at 2.1.308 on October 27, so stable users do not have either fix yet. Switch with /config, or install the claude-code@latest cask.
• Watch for the effort level too: transcripts and telemetry now report the level actually in force, not one picked mid-task and still waiting to apply.

What nobody knows yet

The notes do not say how large "very large" is. The fix asks Claude to read or edit; it is guidance to the model, not a hard block on the write, and no one outside Anthropic has published a test of it. The release also does not say how many users lost files this way.

What to watch

The stable tag moving to 2.1.312 or later, which the setup guide puts at about a week out, around November 3. Until then, a backup of every large instruction file before an agent edits it is cheap insurance.