Clearer warning for classic hooks that risk deadlocking on a turn
Claude Code now explains and prevents a deadlock when a classic hook other than SessionStart, Setup, or SessionEnd tries to wait on the turn it's holding
You'll noticeTier: how much it should matter to you
2Useful: my rating, 1 to 5
1Signal: worth watching, 1 to 5
HooksArea: what it touches
ImprovementsKind: in v2.1.265,
ImprovementsSection of the release
What
Hooks are scripts that run at certain points in a session (for example, when a session starts or ends). Claude Code has "classic" hooks (classic.*) for these events, plus other hook-like calls such as command.run and tool.call.
A new check now catches the case where a call from a classic.* hook — other than SessionStart, Setup, or SessionEnd — would block waiting on the very turn that hook is currently holding. Previously this could silently deadlock. Now it produces a specific, clear error explaining the problem and suggesting the call be made from turn.complete instead. This check is wired in as the fallback case alongside the same checks already used for command.run, tool.call, and similar calls.
Why
This turns a confusing hang into an understandable error message, and tells you exactly how to fix it (move the call to turn.complete), so hook authors aren't left guessing why their hook froze.
The entry above is what we published on the day. These lines were added later, as Anthropic's own pages caught up, and they sit beside the original rather than replacing it.
Confirmed sinceAnthropic's documentation has since written up turn.complete, on React to events with a mod.A turn is everything Claude does in answer to one prompt. Handle `turn.start`, `turn.step`, and `turn.complete` to follow one:plugins/mods/eventssee the edit
How sure we are
One source agreesOne thing we can check says the same as this entry.
Anthropic's documentation agreesAnthropic's documentation has since written up turn.complete, on React to events with a mod.
