feat(beta): Context Anti-Compact — session handoff hook to block /compact

[joeblackwaslike]

Summary

Context Anti-Compact is a new beta feature that intercepts /compact before it runs, generates a structured session handoff via claude -p, and blocks the built-in compaction (exit code 2). It preserves full session context — decision rationale, exact commands, issue IDs, file paths — in a copyable prompt for a fresh session.

Status: Beta

The hook is wired and working. The feature ships opt-in (LESSONS_PRECOMPACT_HANDOFF=1) while we collect feedback on:

• Handoff quality across session types (feature dev, debugging, planning)
• claude -p reliability and latency in various environments
• Token estimation accuracy (current approach: chars ÷ 4, msg + attachment records)
• Fallback quality when claude -p is unavailable

How to enable

export LESSONS_PRECOMPACT_HANDOFF=1

Or inline in hooks.json:

"command": "LESSONS_PRECOMPACT_HANDOFF=1 node \"/path/to/hooks/precompact-handoff.mjs\""

See the full docs for installation, behavior, and limitations.

Future: standalone plugin

Context Anti-Compact is conceptually independent of lesson injection — it doesn't read from the lesson store, it doesn't write candidates, and it would be useful without the rest of lessons-learned. The plan is to extract it into its own plugin and repository once the beta period concludes.

Tracking checklist

• Collect feedback on handoff quality
• Improve token estimation accuracy
• Handle edge case: very short sessions (< 5 turns) — fallback fires immediately
• Test on Opus 4.7 (1M token window) — window inference formula should still hold
• Decide on default-on vs. opt-in for 1.0
• Extract to standalone plugin/repo

[joeblackwaslike]

Extracted to standalone plugin

The extraction is done — anti-compact now lives at https://github.com/joeblackwaslike/anti-compact.

Changes from this copy:

• Env vars renamed: LESSONS_PRECOMPACT_HANDOFF → ANTI_COMPACT, LESSONS_HANDOFF_ONLY → ANTI_COMPACT_HANDOFF_ONLY
• Command renamed: /lessons:handoff → /handoff
• Standalone package.json and plugin.json (no lessons-learned dependencies)
• All 43 tests passing

The copy in lessons-learned is deprecated in place (docs updated with notice + link). Leaving this issue open to track ongoing feedback collection and the remaining checklist items.