[FEATURE] PreUserMessage hook — intercept prompt before context is loaded into model

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

In long sessions, every new prompt pays the full token cost of the entire conversation history — even when the new question is completely unrelated
to what came before.

The only hook that fires near this moment is Stop, which runs after the response is complete. By then, tokens are already spent and response quality
has already been affected by irrelevant context noise. There is no hook that fires before Claude reads the user's new message.

This makes it impossible to build session-management tooling that acts automatically — the best a developer can do today is print a warning after
the fact and ask the user to manually change their behavior next time.

Proposed Solution

A PreUserMessage hook that fires after the user submits a message but before Claude loads the full context and processes it.

Following the same pattern as the existing PreToolUse hook:

• Receives session metadata on stdin (message text, estimated context size, turn count, model)
• Exit 0 proceeds normally
• Non-zero exit blocks the message and surfaces a reason to the user

The key addition over PreToolUse would be the ability to signal that the message should be handled with a reduced context window or in a fresh subagent — leaving the implementation details of how that's surfaced to the Claude Code team.

Alternative Solutions

The Stop hook combined with a manual slash command gets close but has a fundamental limitation: it fires post-response, not pre-prompt. Users must notice a suggestion in terminal output and consciously re-run their prompt differently. In practice this rarely happens.

PreToolUse is the right pattern but it's one level too deep — it intercepts tool calls inside a response, not the user message that triggers the response.

There is no current workaround that can act automatically before tokens are spent.

Priority

High - Significant impact on productivity

Feature Category

Configuration and settings

Use Case Example

1. I spend 10 turns debugging a Python data pipeline. Context grows to ~40,000 tokens — file reads, stack traces, test output.

1. Task is done. I want to ask something unrelated:

"Write a bash script to sync two S3 buckets."

1. Without a PreUserMessage hook: Claude processes that question with 40k tokens of Python/pipeline context loaded. I pay for all of it, and the

answer is noisier than it needs to be.

1. With a PreUserMessage hook: a lightweight check can detect the context has no relation to the new message, warn me before processing begins,

or automatically handle it in a clean context — saving both tokens and response quality.

1. I continue the Python session untouched whenever I return to it.

The same pattern covers any workflow where one session spans multiple unrelated topics — which is common when users don't want to manage multiple terminal windows.

Additional Context

Claude Code already ships the PreToolUse hook which demonstrates this intercept pattern works well in practice. This request extends the same
design one level up — from tool calls to user messages.

Similar patterns in other tools:

• git pre-commit (intercepts before the action)
• VS Code onWillSaveTextDocument
• Most LLM orchestration frameworks expose a pre-call hook for exactly

this reason

No UI changes required. Pure lifecycle addition consistent with the existing hook architecture.