docs(bugfixes): PreCompact deadlock writeup for #863

[Robins163]

Follow-up to #867 / #863 as discussed in #867 (comment).

Standalone writeup of the PreCompact deadlock — symptom, root cause, and the fix that shipped in #863 (@mvalentsev). Net-new file; `docs/bugfixes/` does not exist on develop yet.

Contents

• Session-log repro (8 fires in 15 minutes from session `082d4cc3…`)
• Re-fire timeline showing the block → cancel → save → re-fire loop
• Root cause: `hooks_cli.hook_precompact()` returning `{"decision":"block"}` unconditionally while Claude Code cancels compaction and re-fires
• The `decision: "allow"` correction from bug: hooks use invalid decision value "allow" — should be "approve" #872 (only `"block"` is a recognized top-level decision; anything else is a pass-through by accident — `{}` is the documented no-block shape)
• Rationale for removing the block entirely vs layering a stateful guard on top
• Escape hatch for anyone stuck on an unpatched version

Branch rebased on `upstream/develop`. Tests aren't included — #863's `test_precompact_allows` already covers the shape.

[mvalentsev]

Been thinking about this. The realistic repeat scenario here is an LLM agent making the same mistake, not a human dev. The "allow" value from #872 was exactly that: an agent wrote the return value without checking the hook spec. Agents load CLAUDE.md before working on project code but won't discover files in docs/bugfixes/ on their own. The key rule ("PreCompact hooks must not block, return {} not "allow") probably belongs somewhere agents will actually see it.

[Robins163]

Fully agree — that's the right framing. The "allow" mistake in #872 was an agent writing a return value without checking the spec, and the fix for that class of mistake has to live where agents actually load context, not in docs/bugfixes/ which an agent won't discover unprompted.

I checked develop: neither CLAUDE.md nor AGENTS.md currently state the hook return contract. The rule has no agent-facing home right now.

Proposing to add a short Hook return contract section to CLAUDE.md (and mirror the key line in AGENTS.md), as an additional commit on this same branch. Draft:

Hook return contract. Claude Code recognizes exactly one top-level decision value: "block". Anything else is a pass-through by accident — {"decision": "allow"} is NOT a recognized value (see #872). To not block, return {}. PreCompact hooks must never block: Claude Code cancels compaction and re-fires the hook, causing a deadlock (see #863, #856, #858). Mine synchronously, then return {}.

The docs/bugfixes/precompact-deadlock.md writeup stays as the long-form reference with the session-log repro and re-fire timeline; CLAUDE.md/AGENTS.md carries the one-paragraph rule that agents actually see.

Does that scope extension work for you on this PR, or would you prefer I split it into a separate PR so #915 stays docs-only?