On Claude Code 2.1.319, when two PreToolUse hooks answered the same Bash call in an interactive session and the hook returning
deferfinished before the hook returningask, the command ran with no permission prompt. On 2.1.322 the same pair showed the prompt and nothing ran. Everywhere else we looked, the merged answer followed the documented order on both versions.
Why the merge matters to us
Our agent repository's .claude/settings.json registers five PreToolUse command hooks in three matcher groups: two on Bash, one on Agent|Task, and two on the tools of a browser-automation MCP server. Each one watches a single thing. One refuses to open URLs with a bare open command. One refuses git commit until a review of the change has been recorded. One checks which model a reviewer subagent is launched with. One makes sure the right browser profile is selected before the browser tools act, and the last one spaces out browser actions.
All five answer the same way: they exit with code 2 to block the call, or they exit quietly and stay out of the way. None of them returns ask or defer. With only blocking hooks there is nothing to merge, because any single block wins. The moment one hook in a stack returns ask instead, its answer has to be combined with whatever the others said about the same call, and the hooks run at the same time, so the order in which they finish is not fixed.
Claude Code 2.1.321 shipped two fixes for exactly that situation. Before relying on the rule, we wanted to see the combinations ourselves, on the version before the fixes and on the version we run now.
What the documentation and the changelog say
The hooks reference gives the rule in one line: when multiple PreToolUse hooks return different decisions, the precedence is "deny > defer > ask > allow". A hook that exits with code 2 is routed the same way as deny, and its stderr becomes the reason. When a hook returns ask, the permission prompt carries a label for where the hook came from, and the label is [settings] "for a hook from any settings file or from agent frontmatter".
defer is the unusual one. It exists for programs that run claude -p as a subprocess and want to pause Claude at a tool call, collect an answer through their own interface, and resume. The reference says Claude Code honors it in non-interactive mode, and "only when Claude makes a single tool call in the turn". In an interactive session "it logs a warning and ignores the hook result". With several tool calls at once, defer "is ignored with a warning and the tool proceeds through the normal permission flow".
That path, where a defer cannot be honored, is where the 2.1.321 changelog fixed a bug: a PreToolUse ask was lost when another hook's defer "finished first and could not be honored". The same release fixed "apps that embed Claude Code getting their own PreToolUse hook's" ask reason "instead of another hook's when both asked". Both bugs are about timing and about which hook's answer survives the merge, which the precedence rule on its own does not show.
The lab
We built a throwaway project and passed it a settings file through --settings, with --setting-sources project so that our own user-level hooks and plugins stayed out of the runs. Two command hooks sat in one matcher group on Bash. Both were the same small script, taking a decision and a delay as arguments: the first answered immediately, and the second slept 1.5 seconds before answering, so we always knew which one finished first. Each hook wrote its start and end time to a log.
A permission rule, Bash(echo:*), allowed the probe command. If every hook stayed out of the way, echo hooklab-probe ran without a prompt. That gives each possible answer a visible effect: an allow lets the echo run, a deny refuses it, a defer stops the run, and an ask produces a permission request.
Print mode needs someone on the other end to receive that request. We wrote a small host in Python that starts claude -p with --input-format stream-json, --output-format stream-json and --permission-prompt-tool stdio, answers the initialize request, sends one user message, and answers every can_use_tool request with a refusal. It logged each permission request it received, including the decision_reason field. For two of the pairings, the host also registered its own PreToolUse callback in the initialize request and answered it with ask and a reason of its own, the way a program built on the Agent SDK can.
Interactive mode ran under expect, with two more hooks used only as probes: a PermissionRequest hook that logs when the permission dialog is about to appear, and a PostToolUse hook that logs when the command has actually run. When the dialog appeared, the script pressed Esc.
Every run asked a Haiku model, in the default permission mode, to run the probe once. We ran the same plan on 2.1.319, the last version before the fixes that we had installed, and on 2.1.322: 18 print-mode sessions and 3 interactive sessions on each version.
Print mode: the documented order held
| First hook (answers at once) | Second hook (answers after the delay) | What happened on 2.1.319 and on 2.1.322 |
|---|---|---|
| silent | silent | echo ran |
allow |
allow |
echo ran |
allow |
ask |
host received a permission request with the second hook's reason |
allow |
deny |
refused, with the second hook's reason |
allow |
defer |
run ended with stop_reason: "tool_deferred"
|
ask |
deny |
refused |
ask |
defer |
deferred |
defer |
ask |
deferred |
deny |
defer |
refused |
defer |
deny |
refused |
ask |
ask |
host received one request, with the first hook's reason |
| exit 2 | ask |
refused, with the exit-2 hook's stderr |
In print mode, all 12 single-call pairings of two settings hooks followed the documented order on both 2.1.319 and 2.1.322, whichever hook finished first.
Two details in that table are worth carrying away. When both hooks asked, the host received a single permission request, and its reason was the one from the hook that finished first. The other hook's reason did not appear anywhere in the output the host could read. And when a call was refused, the model saw a tool error that began with PreToolUse:Bash hook error: followed by the refusing hook's reason, so the model is told why it was stopped, not only that it was.
Where the two versions differed
| Pairing | 2.1.319 | 2.1.322 |
|---|---|---|
Interactive: defer finishes first, then ask
|
no dialog; PostToolUse fired, echo ran | dialog with [settings]; nothing ran |
Interactive: ask finishes first, then defer
|
dialog | dialog |
Interactive: defer with a silent hook |
echo ran | echo ran |
| Print mode: host's own hook asks first, settings hook asks second | host received its own reason | host received the settings hook's reason |
| Print mode: settings hook asks first, host's hook asks second | settings hook's reason | settings hook's reason |
The first row is the fixed bug, reproduced. In an interactive session defer cannot be honored, so Claude Code drops it with a warning. On 2.1.319 our interactive session with the deferring hook finishing first showed no dialog, the PostToolUse probe fired, and the echo ran; the ask that arrived later was lost along with the defer, and the call fell through to the normal permission flow, where our allow rule let it run. On 2.1.322 the same pairing showed the permission dialog. The order mattered on the older version: when the ask hook finished first, both versions showed the dialog, and a deferring hook next to a silent one let the echo run on both, as the reference describes.
The dialog on 2.1.322 named the hook event, showed the reason from the hook that had answered ask, and carried the [settings] label. Nothing in it mentioned the defer.
The host rows match the second changelog line. In print mode on 2.1.319, when the host's own hook asked first, the permission request handed the host its own reason back. On 2.1.322 the host received the settings hook's reason whichever hook finished first. For a program that registers its own hooks, that is the difference between being told something it already knows and being told why some other hook in the project wants confirmation.
Where our runs and the reference did not line up
We also asked the model for two Bash calls in one message, the case where the reference says defer is ignored. In all 4 of those runs on each version the model did put both calls in a single message, and every one of those runs still ended with stop_reason: "tool_deferred". The result's deferred_tool_use field named only the second call, and neither echo printed anything. The hook log showed the hooks for the second call starting before the slower hook on the first call had finished, so the two calls were checked at the same time. We did not resume those sessions, so we cannot say what would have happened to the first call afterwards. We are reporting what we saw with one tool and one model, not claiming the reference is wrong; a different mix of tools may well take the path it describes.
The reference also does not say which reason wins when two hooks both ask. In our runs it was whichever hook finished first. With hooks that take different amounts of time from one call to the next, the reason a person reads in the dialog can change between two identical calls.
What we take from it
An ask is the weakest answer short of allow. Any deny, any exit code 2, and any defer that can be honored overrides it. If a hook must stop a call, it should deny or exit with code 2; an ask that has to survive a merge is a request, not a guarantee.
If any hook in your stack returns defer, for instance a hook shared between a program built on claude -p and people who use the same project interactively, run 2.1.321 or later. Before that, a fast defer could erase a slower ask, and nothing on screen said that a hook had wanted confirmation.
Write every ask reason so that it makes sense on its own and names the hook it came from. The person at the prompt sees one reason, and which one depends on timing.
Test the combination as well as the hook. A hook that behaves correctly alone tells you little about the merged answer, and the merge is where both of the bugs fixed in 2.1.321 lived.
For our five hooks, exit code 2 stays the right contract. Every one of them is meant as a hard stop, and in every pairing we ran, a hard stop beat everything it was paired with.
Do you stack PreToolUse hooks that can answer differently, and have you seen a reason or a prompt go missing? Tell us how your hooks combine, and which version you saw it on, in the comments below.


Top comments (2)
One thing worth adding: since
deferis only honored for a single tool call in non-interactive mode, a hook stack that gates risky commands should treataskas advisory and keep a hard block (exit 2) for anything that must never run unprompted. A cheap regression guard is aPostToolUsehook that logs every command that actually executed, diffed against thePermissionRequestlog in CI, so a merge-order bug shows up as a command with no matching prompt. Re-running the hook-pair matrix on each Claude Code upgrade is also worth it, because the finish order of concurrent hooks isn't deterministic.The PostToolUse probe is the part I'm stealing. Without it, "no prompt appeared" reads the same whether the merge allowed the call or never got asked, and that's exactly the kind of silence that hides a bug like this one. I learned it the hard way on a different guard: a drawdown breaker that replayed a whole day with zero fires looked healthy, and it turned out it had never been given a number that could move.
The ask + ask row surprised me more than the fixed bug, honestly. Only the first hook's reason reaching the host means a stack of narrow hooks can end up showing the user the less useful explanation depending on timing. Did you see that ordering stay stable across repeated runs, or did it flip with the 1.5s delay removed?