Expose context window usage to the agent via tool or environment variable

Problem

When Claude Code runs long autonomous sessions (deep investigations, multi-step analyses, extended coding tasks), the context window fills up silently. The agent has no way to know how full the context is until the system either auto-compacts or — worse — enters an infinite loop showing 0 tokens with no way to recover (must force-kill the process).

The /context command shows usage beautifully in the CLI:

us.anthropic.claude-opus-4-6-v1 · 88k/200k tokens (44%)

But this is only available as a client-side slash command. The agent itself cannot call /context, check an environment variable, or use any tool to get this information.

Current workaround

I've built a heuristic in my CLAUDE.md instructions that counts tool calls and estimates when to save state and compact:

• ~50 heavy tool calls (file reads, SQL outputs) ≈ 88k tokens (44%) based on manual stress testing
• ~80 tool calls with subagents doing heavy lifting

This is crude — a 10-line file read and a 500-line DESCRIBE TABLE output count the same, so the threshold is either too aggressive (wasting compacts) or too conservative (risking crashes).

Proposed solution

Expose context window usage to the agent through one or more of these mechanisms:

Option A: Environment variable (simplest)

CLAUDE_CONTEXT_USED_TOKENS=88000
CLAUDE_CONTEXT_MAX_TOKENS=200000
CLAUDE_CONTEXT_USED_PCT=44

Updated after each turn. Agent reads via env | grep CLAUDE_CONTEXT.

Option B: Built-in tool
A GetContextUsage tool (or similar) that returns:

{
  "used_tokens": 88000,
  "max_tokens": 200000,
  "used_pct": 44,
  "autocompact_threshold_pct": 83.5,
  "categories": {
    "system_prompt": 3300,
    "tools": 4200,
    "memory": 5200,
    "messages": 73700
  }
}

Option C: Hook event
A pre-autocompact or context-threshold hook that fires when usage crosses a configurable threshold (e.g., 70%). The agent could register a handler that saves state before the system auto-compacts.

Option D: System reminder injection
Automatically inject a system reminder like <context-usage>88k/200k (44%)</context-usage> into the conversation every N turns or when usage crosses thresholds (e.g., 50%, 70%, 85%).

Why this matters

• Autonomous agents crash without it. Long-running tasks (overnight investigations, multi-hour deep dives) reliably hit context limits. Without visibility, the agent can't self-manage.
• Heuristics waste resources. My workaround compacts too early (~44%) because it can't tell actual usage. Each compact loses nuance despite state files.
• The data already exists. /context computes and displays it — it just isn't exposed to the agent.

Environment

• Claude Code 2.1.72 (Homebrew cask)
• Model: Opus 4.6 via Bedrock (200k context)
• macOS, zsh