Feature request: Expose context usage to hooks for autonomous session handoff

[btecer]

Use case

When working on long-running, multi-phase projects (e.g. codebase migrations, multi-step feature implementations), a single Claude Code session's context eventually fills up. Today the workflow is:

1. User notices context filling up (or Claude proactively warns)
2. User asks Claude to write a "continuation prompt" summarizing state
3. User manually opens a new tab and pastes the prompt
4. New session reads MEMORY.md / PROGRESS.md and continues

This works but the handoff is manual. With a few small additions, the entire loop could be automated via hooks + the existing vscode:// URI handler.

What's missing

1. No context-usage metrics in hook inputs.
The Stop and SessionEnd hook input JSON does not expose input_tokens, output_tokens, or a context_percentage field. This makes it impossible for a hook to decide "we're at 85%, time to hand off."

Current workaround: parse the session's .jsonl transcript file size as a proxy. This is brittle and inaccurate.

2. No official PreCompact hook.
Hooks reference lists Stop, SessionEnd, UserPromptSubmit, SessionStart, etc., but no hook fires before automatic compaction kicks in. A PreCompact event would be a natural place to trigger handoff logic.

3. URI handler doesn't auto-submit.
vscode://anthropic.claude-code/open?prompt=...&session=... pre-fills the prompt but the user must press Enter. Understandable for security, but an opt-in &autoSubmit=true (perhaps gated by a settings.json flag) would close the loop for trusted automations.

Proposed additions

• Add context object to Stop / SessionEnd / new PreCompact hook input:

  {
    "context": {
      "input_tokens": 145000,
      "output_tokens": 8200,
      "max_tokens": 200000,
      "usage_percentage": 76.6
    }
  }

• Introduce PreCompact hook event, fired when auto-compaction is about to run.
• Optional &autoSubmit=true parameter on vscode://anthropic.claude-code/open, guarded by a settings.json opt-in like "allowAutoSubmitFromURI": true.

Why this matters

With these three pieces, users could write a single hook script that:

1. Watches context usage on every Stop
2. At a threshold, derives a continuation prompt from project memory/progress files
3. Fires start vscode://anthropic.claude-code/open?prompt=<...>&autoSubmit=true
4. New tab opens and continues autonomously

This unlocks genuinely autonomous long-horizon work without losing the safety properties of fresh-session context.

Workaround context

Today I'm building this with .jsonl size as a token proxy and manual Enter in the new tab. It works but the metric is approximate and the manual step breaks unattended runs.

[yacb2]

Built the manual half of what you describe as step 3 in your workflow: https://github.com/yacb2/claude-session-handoff. Kills the current claude and respawns it with a handoff prompt injected via SessionStart's additionalContext, so the tab-open + paste becomes a single command. Doesn't address the actual asks here (context-usage in hook inputs, PreCompact, autoSubmit=true) — those are still required to close the loop autonomously.

[csmarshall]

A second downstream consumer voice for primitives (1) and (2) — maury, multi-host Claude Code config sync with mining + drift-detection on ~/.claude/.

Both primitives are load-bearing for the same reason yacb2 names from the read side:

• Context-usage metric in hook stdin. Today maury's "save working state before context disappears" pattern is purely assistant-side discipline — the assistant is supposed to proactively persist a working state file after meaningful events. It works most of the time, fails exactly when context pressure is highest because the model is least likely to volunteer overhead at that moment. A $CLAUDE_CONTEXT_PERCENT (or similar) field in hook stdin would let a shipped hook trigger the save without depending on the model noticing.

• PreCompact event. Compaction is the specific failure mode that destroys the working state. A PreCompact hook gives maury (and claude-session-handoff, and any future downstream) a deterministic save point — the structural answer to "save before the context disappears" that we currently approximate with disciplined eagerness.

No opinion on (3) URI handler auto-submit — different problem domain (process re-entry vs. state persistence), out of scope for maury.

#59492 (consolidation RFC) names these two as part of a three-primitive set alongside UserIdle (#58895). Maury voiced support there for the consolidation framing; this comment adds the data point in the canonical thread for these two specific primitives.