[FEATURE]

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

1. Expose context usage to hook environment variables

Make the current context usage percentage available to all hook scripts via an environment variable like $CLAUDE_CONTEXT_USAGE_PCT (integer 0-100).

Use case: I use CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=80 to trigger compaction at 80%. I want a UserPromptSubmit hook that detects when context hits ~70% and injects instructions (via additionalContext) to write a handoff file before compaction compresses the context. Today
this is impossible because hooks have no visibility into context usage.

Proposed Solution

Proposed behavior:
-context Available in all hook types (UserPromptSubmit, PreToolUse, PostToolUse, Stop, PostCompact, etc.)

• Integer value 0-100 representing percentage of context window used
• Optional: also expose $CLAUDE_CONTEXT_TOKENS_USED and $CLAUDE_CONTEXT_TOKENS_MAX for finer control

Alternative Solutions

1. Add PreCompact hook

Add a PreCompact hook that fires before auto-compaction runs, giving hooks/skills a chance to preserve full context state before it's compressed.

Use case: The new PostCompact hook (v2.1.76) is helpful, but by the time it fires, context is already compressed and information is lost. A PreCompact hook would allow injecting instructions to write a handoff file while the full context is still available.

Proposed behavior:

• Fires after compaction is triggered but before it executes
• Supports additionalContext in response (like other hooks)
• The injected context is processed before compaction runs, so Claude can write files with full context intact

Priority

Medium - Would be very helpful

Feature Category

Performance and speed

Use Case Example

_No response_

Additional Context

_No response_