UserPromptSubmit runs right after you hit Enter and before Claude sees the prompt. Use it to validate, transform, or block what goes to the model.

What it does

The hook receives the submitted prompt. It can allow it through unchanged, modify it (append project context, redact secrets), or reject it with a reason. This is the cleanest way to enforce team prompt policies, strip sensitive data, or inject reminders into every turn.

When to use it

Auto-appending "run tests after your changes" to every prompt.
Redacting secrets like tokens or passwords before they hit the model.
Blocking prompts that match a forbidden pattern (e.g., "delete production").
Injecting per-prompt context like the current branch or PR number.

Gotchas

Heavy transformations confuse users when the model responds to something they didn't type. Keep transforms visible.
Synchronous hooks add latency to every turn. Stay fast.
Rejection messages should be clear - "denied by policy: reason" beats a silent block.

Official docs: https://code.claude.com/docs/en/hooks.md#userpromptsubmit