context-economy 2.0.0: the compaction is the handoff, built on function hooks

[bjvle]

Summary

Ports context-economy's automatic handoff path from command hooks to Claude Code's function hooks
("mods") and releases it as 2.0.0. Design: docs/design.md §v2 (D29–D34). Measurements:
docs/measured.md #37–#45.

• Compaction = handoff. hooks/register.ts answers session.compact:

  1. A $.model.fork over the live session writes the handoff (~99.7% served from the prompt cache).
  2. The gate checks the draft, and a failed draft gets one corrected retry.
  3. The gated document replaces core's summary.

  A malformed draft never overwrites the stored handoff, and core's summary is the fallback.

• /clear handover in-band. On session.end (clear), a marker is stored in $.store under
  lastClear:<processKey>. The key is a random id minted per process in session.start and kept in
  CONTEXT_ECONOMY_PROCESS_KEY, which outlives both a /clear and a hot reload. ($.state is per
  session and does not survive a /clear: finding shepard: leave the code simpler, and think the fix through before pushing #45.) The next prompt.submit then carries the
  handoff the cleared session wrote, with its GATE: line. If no handoff covers that session, it
  carries a note saying so, with the claude --resume line. Either way it writes a debug line.
  session.end drops the process's marker on any other reason and prunes markers older than a day.

• The handoff goes to the work's checkout, not always the cwd (D34). A mission_control run's
  cwd is mission_control while its work is in a sibling worktree. Keyed to cwd, its compaction
  handoff landed in the shared mission_control/main slot, was gated against the wrong tree, and
  replaced core's summary. The checkout is now:

  1. CONTEXT_ECONOMY_CHECKOUT, set by the launcher; the fork is told to copy it.
  2. Else the checkout the fork names, once orienting from it succeeds.
  3. Else the session's cwd.

  A source that does not orient falls through to the next. The toast and the debug log always name
  the checkout and the source that chose it, so a stale override shows. The /clear marker
  records where the last compaction wrote, with the cwd as fallback. The skill's Step 1 takes the
  variable as its TARGET and prints target-from=, so a run's manual and automatic handoffs
  share one slot.

• Windows bash. $.process.run takes no shell, and from PowerShell a bare bash resolves to
  System32's WSL launcher. The lib scripts now run under Git for Windows' own bash.exe, and
  orient() reports why it failed (finding Realign the catalog with kendo's 2026-09-05 review and plan work #43).

• No trigger of the plugin's own. /autocompact decides when it happens.

• Removed (breaking):

  • The three v1 shell hooks and their suites.
  • The detached writer's skeleton, lock and liveness machinery.
  • The store helpers and threshold constants that only those hooks used.

• CI: the claude CLI stub is gone, since only the fork-write suite needed it.

Commits: the implementation and the release commit (version bump + CHANGELOG), then fixes from the
live tests (Windows bash, the process-keyed /clear marker), each followed by the measurement that
found or confirmed it, then the checkout resolution from mission_control's read-through. The 2.0.0 CHANGELOG entry was amended in place rather than bumped.

Known gaps

• If a resumed process compacts before its first response, there is nothing to fork, so core's
  summary is used.
• A hot reload between a /clear and the next prompt mints a new process key, so that prompt gets
  no handoff. The orphaned marker is pruned a day later.
• After a /clear, a handoff the skill wrote by hand to a sibling checkout is looked for in the cwd
  if the session neither compacted nor had CONTEXT_ECONOMY_CHECKOUT set.
• Not yet measured live: the precompute veto, and the checkout resolution (D34).

Test plan

• bash plugins/context-economy/tests/gate.sh --run: 38 checks OK
• claude plugin test plugins/context-economy: 28 pass
• claude plugin validate plugins/context-economy: passed
• End-to-end manual /compact in a live session (finding agents: delete the five retired reviewers, close the catalog resync #42): fork 6.1 s, gate exit 0 first try
• Live autocompaction answered by the module (finding Replace the per-repo reference files with a template #44)
• Live /clear retest: handoff and GATE: line delivered to the next prompt, handoff marked
  consumed (finding shepard: leave the code simpler, and think the fix through before pushing #45)
• The skill's Step 1 block, run with no override, a valid one and a stale one
• A live mission_control run with CONTEXT_ECONOMY_CHECKOUT set by its launcher
• After merge: claude plugin tag plugins/context-economy --push

🤖 Generated with Claude Code