UserPromptSubmit: add a 'handled' decision (show output, skip agent, no 'blocked' framing)

+1 — with some implementation-level findings from inspecting the v2.1.217 binary that confirm there is no workaround today, plus a second concrete use case.

Use case. We hit the same wall building a local provider switcher for Claude Code: a UserPromptSubmit hook intercepts /switch <model>, flips a local routing daemon, and blocks the prompt — zero model turns by design, because switching has to keep working while the current model is rate-limited, so "fall through to the agent" is not an option. Functionally perfect; the only problem is that every successful switch renders as an error-styled block.

What the binary shows (2.1.217). Since the rendering isn't specified in the docs, I inspected the bundled JS to map what a hook can actually influence:

• The banner is a hardcoded template applied to every block, no matter how the hook responded (exit 2 + stderr, or exit 0 + JSON):

``js
function K2s(e){returnUserPromptSubmit operation blocked by hook:\n${e.blockingError}}
``

• The consumer appends the prompt echo unless suppressOriginalPrompt is set:

``js
let O=K2s(F.blockingError),
U=F.suppressOriginalPrompt?O:${O}\n\nOriginal prompt: ${H};
return{messages:[wl(U,"warning",void 0,!0)],shouldQuery:!1,resultText:U}
``

• hookSpecificOutput.suppressOriginalPrompt is parsed for UserPromptSubmit — it appears to be undocumented, and it's very welcome:

``js
case"UserPromptSubmit":
u.additionalContext=e.hookSpecificOutput.additionalContext,
u.sessionTitle=e.hookSpecificOutput.sessionTitle,
u.suppressOriginalPrompt=e.hookSpecificOutput.suppressOriginalPrompt;break;
``

• The only other zero-turn stop path, continue: false, is framed too — ` Operation stopped by hook: ${stopReason} ` — and additionally pushes that text into history as a meta message.

So the best reachable rendering today is banner line + reason (echo suppressed): one unavoidable line of "blocked" framing over what is actually a success.

Minimal version of this request. Given suppressOriginalPrompt already exists on this exact path, honoring one more boolean — e.g. hookSpecificOutput.suppressBanner: true (or display: "plain") — would unblock both use cases with no new decision semantics. The proposed decision: "handled" is cleaner still, since "blocked as refusal" and "handled locally" are genuinely different outcomes and could eventually render differently (e.g. like !command cells do).

Happy to test a build.

The block workaround does work today, and getting it right took me long enough that it seems worth writing down the exact shape plus the details that are not documented. It gets you most of what you are asking for, which also makes the remaining gap precise.

All of this is read out of the 2.1.223 bundle, so treat it as reverse-engineered rather than contractual.

{
  "decision": "block",
  "reason": "<what to show the user>",
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "suppressOriginalPrompt": true
  }
}

1. suppressOriginalPrompt is what stops the echo. Without it, the intercepted prompt is appended back underneath your output:

V = H.suppressOriginalPrompt ? q : `${q}\n\nOriginal prompt: ${O}`

So your command reappears as Original prompt: ,api below the result. A bare exit 2 with a message on stderr cannot set this flag. It is in the schema (When decision is "block", omit the original prompt from the block message) but it is easy to miss, and it is the difference between something that reads as a command and something that reads as a rejected message.

**2. Emit the JSON and exit 2.** Two separate reasons, and one of them is not what I originally assumed.

The wrapper you are avoiding:

if (de.status === 2 && !fe.blockingError)
  fe.blockingError = { blockingError: `[${ne}]: ${de.stderr || "No stderr output"}`, command: ne }

Since decision: "block" has already populated blockingError, that never fires, so your reason is used verbatim rather than rendered as [<command>]: <stderr>.

With exit 0 you land in an earlier branch instead:

// zU(e) is !(("async" in e) && e.async === true), i.e. "not an async hook"
if (zU(_e) && !_e.suppressOutput && Ce && de.status === 0) {
  ... yield { ...fe, message: fe.message || <hook_success>, outcome: "success", hook: F }
  return
}

I had assumed this dropped the blocking decision. It does not: it spreads the parsed output, so blockingError survives. What exit 0 actually costs you is a spurious <hook name> completed line plus an outcome reported as success. Possibly useful for #81818: suppressOutput does gate this particular branch, even though it does not touch the block notice itself.

3. The hook must be synchronous, and this failure is silent. The config flag's own schema says it outright:

async: "If true, hook runs in background without blocking"

An async: true hook therefore returns after the prompt has already reached the model, so it cannot gate anything. Nothing warns you. The hook simply stops having any effect while continuing to look correctly configured. That cost me about 90 minutes, and someone else mentioned unprompted that it cost them about the same, so it may deserve a line in the hooks docs independently of what happens to this request.

What none of this fixes is the part the title is about. It is still a block, so whatever notice the client renders around blocks still renders (#81818), and on Desktop and the VS Code extension the reason text is dropped entirely (#73525, #75534). The workaround gets the content right and cannot touch the framing.

Four open issues circling the same missing primitive seems like a better argument for handled than for four separate rendering fixes.

Working implementation if it is useful to anyone: prompt-hook.sh, about 100 lines, MIT. It uses this to run a terminal command from the input box with no turn and no tokens spent.

Thanks for re-filing with the clear use case. One piece exists today: a UserPromptSubmit hook that blocks can set hookSpecificOutput.suppressOriginalPrompt: true so the original prompt isn't echoed back in the message (https://code.claude.com/docs/en/hooks#userpromptsubmit-decision-control). The output is still shown as a blocked-by-hook warning, there's no neutral "handled" rendering, and the model doesn't see the result on later turns, so leaving this open for that.

🤖 Generated with Claude Code