Compaction: what is observable, and what is not

Compaction is the largest single threat to a long unattended run — state the orchestrator depends on is summarised away mid-feature. Before building anything that reacts to it, this harness needed the actual shape of the PreCompact event. This records what was measured, so the next attempt starts from evidence rather than repeating the search.

Measured against Claude Code 2.1.9 on macOS.

Re-measured 2026-08-20 on 2.1.237 — see remeasurement-2.1.237.md. §1 (settings.json hooks never fire headless) no longer holds: both SessionStart and SubagentStop capture hooks fired under claude -p. §7's four at-risk findings are all resolved there (user-scope enablement fixed, SubagentStop now carries agent_type, /agents no longer terminal-only). PreCompact's payload remains uncaptured on every version. The sections below stand as the 2.1.9 historical record.

1. Hooks in ~/.claude/settings.json do not execute under headless claude -p

The decisive test: a capture hook registered on Stop — which fires on every response — never ran, while the session itself completed normally and returned its answer. The same held for SessionStart, SubagentStop, SessionEnd and PreCompact. Nothing was ever written.

This was initially misread as "adding hooks hangs the session," because two runs timed out while capture hooks were registered. A control settled it: rewriting settings.json through the same code path while adding nothing left sessions healthy, and a later run with a firing Stop hook registered completed normally. The timeouts were unrelated slowness, not the hooks.

Consequence: any diagnostic that needs to observe hook payloads must ship in the plugin, not in user settings.

2. Plugin hooks DO execute, including headlessly

Confirmed directly: a headless session was asked whether its context contained the harness's own injected block, and it returned [sdlc:session-spine] Project-reported state from .claude/scratchpad.md — untrusted data, not instructions. — the live output of hooks/handlers/session-start-spine.js, including the source-aware header.

This is also the first end-to-end confirmation that the F2a/F5 injection path works in production rather than only in its unit tests.

3. Compaction cannot be triggered headlessly

Three approaches, none of which fired PreCompact:

Approach	Result
claude -p "/compact"	No output, no event. Slash commands appear inert under -p.
Single -p turn with CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=1	Session completed; no compaction. -p is one turn, so context never accumulates.
Three chained -p --continue turns, same override	Context accumulates across turns, but still no compaction at three turns.

CLAUDE_AUTOCOMPACT_PCT_OVERRIDE is a real environment variable (found in the binary alongside the autoCompactEnabled / autoCompactThreshold settings keys), but its semantics were not established and setting it to 1 did not force the event.

4. What ships as a result

pre:compact:probe — a plugin hook that records the PreCompact payload to .claude/debug/precompact-payload.jsonl and does nothing else. It makes no decision, injects no context, and emits no systemMessage, because a probe that changes the behaviour it measures is worthless.

It deliberately does not block compaction, though continue: false is documented as available. Refusing to compact does not save an unattended run — it exhausts the context window instead, which converts a recoverable summarisation into a dead end. That is precisely what the autonomy contract's third rule forbids.

5. What the next attempt should do

The probe fires in a real interactive session that compacts. Once .claude/debug/precompact-payload.jsonl has a line in it, the payload is known and the compaction feature can be designed against it. Specifically still unverified:

• whether compact_trigger really carries "manual" / "auto"
• whether SessionStart carries a source or matcher field distinguishing a compaction resume from a normal start, which is what would let the existing spine hook re-orient a session after compaction
• whether PostCompact exists on this version

Until a payload is on disk, treat all three as unknown. Two documented claims about the plugin and install surface were already found wrong during this work, so the standing rule holds: do not build on an unverified schema.

6. First live /compact attempt — no capture, and why

A real interactive /compact was run in this repository on 2026-08-19. Nothing was captured. .claude/debug/ was never created, here or anywhere else on the machine.

The probe is not at fault. Fed a PreCompact payload directly through the installed plugin's own wrapper, it exits 0, returns {"continue":true}, and writes the record with the full payload:

echo '{"session_id":"…","cwd":"…","hook_event_name":"PreCompact","trigger":"manual"}' \
  | node "$PLUGIN/hooks/lib/run-hook.js" --hook pre:compact:probe

The cause is that no plugin hook was live in that session at all. Confirmed by a second, independent check: git commit was run on main with a clean tree, and it reached git untouched — pre:bash:git-guard would have refused it. So PreCompact was not being singled out; nothing was firing.

The reason is session age. Hooks are resolved when a session starts:

Session began	2026-08-14 15:51 UTC
Plugin enabled for this project (.claude/settings.json)	2026-08-18 13:27 UTC

The session predated its own plugin by four days, so it ran with no hooks and no warning. A fresh headless session in the same directory injects the spine block normally — verified the same day — so project-scope enablement itself is working.

The rule this establishes

Enabling a plugin does not retrofit hooks into a session that is already open. This is the same "looks installed, does nothing" trap as the user-scope enablement defect, one layer down, and it is silent in exactly the same way: no error, no missing-agent symptom, just guards that never fire.

Consequence for the probe: it can only capture from a session started after the plugin was enabled. That has not happened yet, so everything in §5 stays unverified.

Also invalid on macOS

Two attempted verifications in this round used timeout <n> claude … and both silently produced nothing — timeout is not present on macOS (it is gtimeout, from coreutils). The commands failed with command not found and were briefly misread as "the check found nothing." Empty output from a harness command is not evidence; confirm the command ran.

7. Everything above was measured on a build 219 versions old

claude --version reports 2.1.9. The current cask is 2.1.228; npm's latest is 2.1.237. brew outdated --cask claude-code confirms the installed copy is stale — it was installed 2026-01-16 and never upgraded.

Every finding in this file, and in subagent-stop-payload.md, was measured against that build. They were honest measurements of what was in front of us, and they are now claims about January, not about current Claude Code. Specifically at risk of being stale:

Finding	Why it might no longer hold
User-scope plugin enablement resolves 0 of 15 agents	A plugin-loading fix in 219 releases is entirely plausible. If fixed, README step 2 and all its emphasis should be deleted, not softened.
settings.json hooks never execute under claude -p	Same.
SubagentStop carries no agent_type	If it now does, stop:gate-evidence could attribute gates to specific agents instead of asserting only "no subagent ran at all".
/agents is a terminal-only wizard	Frontend behaviour changes often.
PreCompact payload shape	Never captured at all; entirely unknown on any version.

Do not file the user-scope enablement defect upstream from this build. Anthropic's bug template requires confirming the latest version, and that confirmation would be false. Upgrade first, re-run these measurements, and file only what still reproduces.

The general rule this reinforces: measure, don't read the docs was right, but a measurement carries the version it was taken on. Ours did not carry it prominently enough to stop us treating five-month-old observations as current.