Expose Context Usage to Claude + Leverage pause_after_compaction

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

Currently, Claude has no visibility into context state:

• Cannot see current token count or usage percentage
• Cannot anticipate when compaction will occur
• Cannot make informed decisions about whether to read large files

The existing PreCompact hook helps users, but Claude remains blind. This means:

1. No proactive checkpointing - Claude can't suggest saving work before compaction hits
2. Lost nuance - Complex work-in-progress gets summarized, losing detail
3. Degraded continuity - Post-compaction Claude has a summary instead of recent context
4. Repeated questions - Claude re-asks things that were just discussed

Proposed Solution

1. Expose Context Usage to Claude (Primary Ask)

Add context metrics to Claude's environment info (similar to how working directory and platform are exposed):

context_usage_percent: 73%
context_tokens_remaining: 54,000

This allows Claude to:

• Proactively suggest closing sessions at 70-80% usage
• Warn before reading large files that would push context high
• Make informed trade-offs (delegate to agents vs. read directly)
• Follow user-defined rules in CLAUDE.md (e.g., "checkpoint at 75%")

2. Implement API's pause_after_compaction (Secondary Ask)

The Claude API now supports pause_after_compaction which:

1. Pauses after generating the compaction summary
2. Allows preserving recent messages verbatim (not summarized)
3. Enables injecting content before continuing

If Claude Code implemented this:

• Recent exchanges preserved - Last 2-3 turns stay intact, not summarized
• Critical context injected - Active tasks, uncommitted changes, current file paths
• Smoother transitions - Less "starting over" feeling after compaction

Alternative Solutions

The existing PreCompact hook helps users prepare, but Claude itself has no visibility into context state.

Current workarounds:

• Manually track "session weight" based on gut feel
• Hope to close sessions before compaction hits
• Re-establish context after compaction (tedious, error-prone)
• Use --no-auto-compact flag but then risk hitting hard limits

Priority

High - Significant impact on productivity

Feature Category

CLI commands and flags

Use Case Example

Power Users with Session Management Workflows:
Users who maintain session trackers, task lists, and multi-project context need continuity. With context visibility, Claude could say: "We're at 78% context. Want to checkpoint before I read these 5 files?"

Long-Running Agentic Tasks:
When Claude works through complex multi-file refactors, compaction mid-task loses the mental model of what's done. With pause_after_compaction, recent tool calls and decisions would survive intact.

Educational/Exploratory Sessions:
Conversations about learning, ideas, or planning—valuable thought progressions get compressed into generic summaries. No warning to capture these to files before compaction.

Additional Context

Related Issues

This request builds on but is distinct from:

• #6689 - --no-auto-compact flag (user control, not model visibility)
• #23419 - Opt out of compaction to reclaim 10% buffer (user control)
• #3349 - Custom pre/compact/post hooks (closed, but PreCompact hook exists)

What's different here: Those issues focus on user controls. This request is about giving Claude itself the information it needs to manage sessions intelligently, plus leveraging newer API capabilities.

Why This Matters

The API already supports these patterns server-side. Claude Code just doesn't expose them:

• pause_after_compaction - exists in API, not in CLI
• Token usage - returned in API responses, not visible to Claude
• Custom compaction instructions - API supports, CLI doesn't expose

This is about surfacing existing capabilities, not building new ones.

Implementation Notes

1. Backward compatible - Users who don't care see no change
2. Opt-in complexity - Power users define behaviors in CLAUDE.md
3. Low effort for high value - Data already exists, just needs exposing

References

• Compaction API Documentation
• Related issues: #6689, #23419, #3349