[FEATURE] Context usage threshold hook event with plan-and-continue workflow

Problem

Complex, multi-step tasks frequently exhaust the context window before work is complete. By the time auto-compaction triggers (~95%), critical context has already been lost to summarization, and there's no opportunity to intelligently plan remaining work while the full conversation history is still available.

Current workarounds are inadequate:

• CLAUDE.md heuristics — Claude cannot measure its own token usage, so instructions like "plan ahead when context is getting full" are unreliable
• PreCompact hook — fires too late (compaction is imminent and cannot be blocked), and cannot trigger Claude to take actions like spawning a planning subagent
• SessionStart with compact matcher — fires after compaction, when detailed context is already lost
• CLAUDE_AUTOCOMPACT_PCT_OVERRIDE — can trigger compaction earlier, but compaction still destroys context without giving Claude a chance to plan first
• Manual /compact with instructions — requires the user to guess when context is getting full

Proposed Solution

1. New hook event: ContextThreshold

A hook event that fires when context window usage crosses a configurable percentage threshold. Unlike PreCompact, this is not tied to the compaction lifecycle — it fires independently, giving Claude (or the user) time to act before compaction is needed.

{
  "hooks": {
    "ContextThreshold": [
      {
        "matcher": "80",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Context at 80%. Find a stopping point, then create a detailed plan for remaining work.'"
          }
        ]
      }
    ]
  }
}

Input provided to hook:

{
  "session_id": "abc123",
  "transcript_path": "/path/to/transcript.jsonl",
  "cwd": "/project",
  "hook_event_name": "ContextThreshold",
  "context_usage_pct": 80,
  "context_used_tokens": 160000,
  "context_max_tokens": 200000
}

2. Support decision: "block" to pause execution

The hook should support exit code 2 / decision: "block" to interrupt Claude's current turn and inject feedback, similar to Stop hooks. This allows the hook to instruct Claude to:

1. Find a stopping point — finish the current atomic unit of work
2. Spawn a planning subagent — while full context is still available, create a detailed plan of all remaining work (using the Task tool with a Plan agent)
3. Prompt to clear context — after the plan is saved, prompt the user to start a fresh session that loads and executes the plan

This mirrors the existing behavior when a user creates a plan in plan mode and then implements it — but triggered automatically by context pressure.

3. Configurable thresholds via settings

{
  "contextThresholds": [80]
}

Or multiple thresholds for progressive behavior:

{
  "contextThresholds": [60, 80, 90]
}

Each threshold fires only once per session to avoid repeated interruptions.

Use Cases

1. Automatic session handoff — At 80%, Claude plans remaining work, saves the plan, and the next session picks it up seamlessly
2. Progressive warnings — Notify at 60%, suggest planning at 80%, force wrap-up at 90%
3. Long-running refactors — Multi-file changes that inevitably exceed context can be broken into planned phases automatically
4. Skill integration — Trigger session-handoff or multi-session-planner skills at specific thresholds

Why this is different from existing proposals

• Not tied to compaction — fires at arbitrary thresholds, giving time to act before compaction
• Supports blocking — can interrupt Claude's turn to redirect behavior
• Complete workflow — plan → clear → continue, matching existing plan mode UX
• Composable — works with existing hooks, skills, and subagents

Related Issues

• #24320 — Context threshold hooks to auto-trigger skills (closed as duplicate)
• #17237 — PreCompact and PostCompact hooks for context management (open, 6 👍)
• #19297 — Configurable context limit threshold (closed)
• #14258 — PostCompact hook event and compaction content control
• #15923 — Pre-compaction hook to preserve conversation history
• #23966 — Auto-compact and continue when context limit reached