Feature: Programmatic context compaction trigger from hooks

Feature Request: Programmatic Context Compaction

The Problem

Context compaction is currently a crisis response — it happens when the window fills up, or when a user manually types /compact. There's no way for hooks or extensions to trigger it programmatically, which means there's no way to build intelligent context management.

The Opportunity

With hooks (PreCompact, PostCompact, SessionStart) and the statusline stdin (which already exposes context_window.used_percentage), all the pieces exist for proactive context rotation — except the trigger.

What this enables:

1. Transaction-aware compaction — An epistemic measurement system (like Empirica) tracks work in transactions (PREFLIGHT → work → POSTFLIGHT). Transaction boundaries are natural compact points — all important state has been captured. A hook could trigger compact at the end of a measured work unit, knowing the recovery pipeline will reload only what's relevant for the next task.

1. Context budget management — Instead of running until 95% and losing everything in a panic compact, extensions could compact at 60% and reload selectively. Like garbage collection vs running out of memory.

1. Selective context loading — Combined with MCP resources and skill-based architectures, compact becomes a "page swap" — evict stale context, load fresh context relevant to the current task. The PreCompact hook saves what matters, post-compact recovery loads what's needed.

1. Long-running session support — Sessions that span hours or days could rotate context proactively, maintaining coherence across many tasks without accumulating irrelevant history.

Proposed API

A hook could trigger compact by returning a specific action:

{
  "hookSpecificOutput": {
    "action": "compact",
    "reason": "Transaction complete. Context at 72%, rotating for next task."
  }
}

Or a tool/command accessible from hooks:

claude --compact --reason "Proactive rotation at transaction boundary"

Or even a context management API in the statusline/hook protocol:

{
  "context": {
    "compact": true,
    "preserve_system": true,
    "preserve_last_n_turns": 3
  }
}

Why This Matters

The context window is the most constrained resource in AI-assisted development. Right now it's managed reactively (fill up → compact → lose state → recover what you can). With a programmatic trigger, it becomes a managed resource — like memory in an OS, with the hook ecosystem providing the page table.

The infrastructure for intelligent recovery already exists in the ecosystem (measurement systems, MCP resources, semantic search). The missing piece is the eviction primitive.

Current Workaround

We suggest compact to users via statusline nudges at transaction boundaries, and they manually type /compact. This works but requires human intervention for what should be an automated optimization.

Environment

• Claude Code 2.1.81
• Empirica v1.6.23 (epistemic measurement system with full hook integration)
• Using PreCompact and post-compact hooks for state preservation/recovery
• Statusline reads context_window.used_percentage from stdin JSON