Expose context window utilization to hooks and as machine-readable output

The Ask

Expose current context window utilization (tokens used / tokens available) in two places:

1. As a field in the PostToolUse hook stdin JSON (e.g. "context_utilization": 0.47)
2. As machine-readable output from /context --json

Why

We're building an agent memory system where Claude Code writes decisions, errors, and learnings to a persistent vector store (mcp-memory-service) throughout a session. The challenge is knowing when to flush memories before context gets compressed.

Currently available:

• PreCompact hook — fires when compaction happens, but by then it's too late for a thoughtful memory write. It's the fire alarm, not the smoke detector.
• Tool call counting — crude proxy that doesn't account for varying response sizes.
• Manual /context — not machine-parseable, requires human intervention.

What we need is a gauge, not just an alarm. A context utilization metric would let us:

• Trigger memory writes at 50% saturation (while there's still rich context to capture)
• Implement context health handoff — summarize and offload to external memory before compaction compresses details away
• Build smarter pre-compaction hooks that prioritize what to preserve

Proposed Shape

PostToolUse stdin addition:

{
  "session_id": "abc123",
  "tool_name": "Edit",
  "tool_input": {},
  "tool_response": {},
  "context": {
    "tokens_used": 487000,
    "tokens_available": 1000000,
    "utilization": 0.487
  }
}

Or /context --json:

{
  "tokens_used": 487000,
  "tokens_available": 1000000,
  "utilization": 0.487,
  "components": {
    "conversation": 320000,
    "system_prompt": 15000,
    "claude_md": 8000,
    "tool_definitions": 45000,
    "auto_memory": 3000
  }
}

---

Thanks to the entire Claude Code team — the hook system, the extensibility, and the overall developer experience are genuinely exceptional. The fact that we can build a Kurzweil-inspired hierarchical memory system on top of Claude Code's hook architecture is a testament to how well it was designed. Really appreciate all the work that's gone into this platform.