[FEATURE] Hook event or callback when context window is near capacity

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

When running long agentic sessions, Claude Code prints a visual warning when context is running low, but there's no programmatic way to act on this event. Users who want to run cleanup tasks (write a handoff document, summarize progress, checkpoint state) before context is exhausted have no reliable trigger to do so.

Currently the only options are:

• Watch the UI manually and run a slash command in time
• Poll $CLAUDE_CONTEXT_REMAINING_PERCENT on every PostToolUse hook, which fires for every tool call regardless of context state

Proposed Solution

Add a dedicated hook event that fires when the context window drops below a configurable threshold:

"hooks": {
  "ContextLow": [
    {
      "threshold_percent": 10,
      "command": "python3 ~/.claude/hooks/on_low_context.py"
    }
  ]
}

The hook would fire once per session when the threshold is crossed (not on every tool call), giving the user or script a chance to:

• Trigger a custom slash command (e.g. /handoff)
• Write a checkpoint file
• Prompt the user whether to continue or exit cleanly

Alternative Solutions

/compact compresses context but doesn't run user-defined logic or allow for custom pre-compaction actions. A hook would be complementary, users could run their own logic before compacting or exiting.

The PostToolUse polling workaround:

• Runs on every tool call, adding overhead throughout the session
• By the time the flag is detected and acted on, context may already be critically low
• Relies on Claude reliably reading CLAUDE.md instructions when context is already degraded, bad time for instruction-following

Priority

Medium - Would be very helpful

Feature Category

Configuration and settings

Use Case Example

Any workflow where session state needs to be preserved across context boundaries: long refactoring sessions, multi-step data pipelines, research sessions where reasoning context is as valuable as code changes.

Additional Context

_No response_