[BUG] PreToolUse hook that fails to launch is treated as a deliberate deny — exit-code 2 collision causes unrecoverable tool lockout

Environment

• Claude Code 2.1.218 (native install)
• Windows 11, python from the Microsoft Store distribution
• Reproduced with user and project settings excluded (--setting-sources project in an empty directory) and no MCP servers (--strict-mcp-config) — i.e. a minimal environment, not a side effect of a local configuration.

Summary

When a PreToolUse hook's command cannot be launched (script missing, path typo, wrong interpreter), the launcher's own failure exit code is interpreted as the hook protocol's "block this tool call" signal. Claude Code cannot distinguish

• "the hook ran and deliberately returned 2 (deny)", from
• "the hook never ran at all (broken configuration)".

CPython exits with 2 when it cannot open the target script (can't open file '...': [Errno 2] No such file or directory). That is exactly the value the hook protocol reserves for "block". The collision is not exotic — 2 is a common "usage/launch error" code across interpreters and CLIs.

Reproduction

Run each in an empty directory.

Test — hook script does not exist:

claude --print --setting-sources project --strict-mcp-config \
  --settings '{"permissions":{"allow":["Bash(echo:*)"]},"hooks":{"PreToolUse":[{"matcher":"Bash","hooks":[{"type":"command","command":"python C:/nonexistent/ghost_hook.py"}]}]}}' \
  "Run this bash command and report its output verbatim: echo REPRO_MARKER_OK"

Result — the Bash tool is blocked:

PreToolUse:Bash hook error: [python C:/nonexistent/ghost_hook.py]:
python.exe: can't open file 'C:\nonexistent\ghost_hook.py': [Errno 2] No such file or directory

Control — identical, but the hook exists and exits 0:

claude --print --setting-sources project --strict-mcp-config \
  --settings '{"permissions":{"allow":["Bash(echo:*)"]},"hooks":{"PreToolUse":[{"matcher":"Bash","hooks":[{"type":"command","command":"python -c pass"}]}]}}' \
  "Run this bash command and report its output verbatim: echo CONTROL_MARKER_OK"

Result — the Bash tool runs normally and returns CONTROL_MARKER_OK.

The only difference between the two runs is whether the hook command can be launched. This isolates "failed to launch" as the cause, rather than "a hook is configured at all".

Expected behaviour

A hook command that never executed is a configuration error, not a policy decision. It should be surfaced distinctly from a deliberate deny — for example by inspecting the spawn result (ENOENT / non-zero spawn error) before interpreting the exit code, and reporting "hook could not be started" as a loud configuration warning rather than a silent block.

Actual behaviour

The launch failure is reported as PreToolUse:<Tool> hook error and the tool call is blocked, identically to a deliberate exit 2 deny.

Impact

1. Any typo in a hook path disables the affected tool, with a message that reads like policy enforcement rather than a broken config.
2. Unrecoverable from inside the session. A common hardening pattern is a PreToolUse hook that protects the settings and hook files themselves from agent modification. If such a hook's script is renamed or removed — e.g. by a "temporarily disable the guard" helper that renames guard.py to guard.py.disabled while the settings entry still points at guard.py — every subsequent tool call is blocked, including the one that would restore it. The session can open the cage and lock itself inside, with no path back except editing the configuration from outside the agent.
3. Because exit 2 is a routine interpreter/CLI error code, this is reachable through ordinary mistakes (moved repository, changed interpreter, unresolved environment variable in the path), not only through deliberate action.

Suggested fix

Separate the two signals:

• Treat a spawn/launch failure (command not found, script not readable) as a hook configuration error: surface it prominently, and do not silently convert it into a deny.
• Reserve exit code 2 for hooks that actually executed.

If fail-closed is the intended default for launch failures, the message should say so explicitly ("hook could not be started — blocking by policy") so the operator can tell a broken path from an enforced rule, and the documentation should warn that disabling a hook by renaming its script blocks all matched tool calls.

Related issues

• #77912 — claude plugin validate passes manifests whose hook commands reference files that don't exist. That report covers the validation side: a bad hook path is not caught up front. This report covers the runtime consequence that makes it costly — the same missing file does not degrade gracefully, it blocks the tool. The two are complementary: fixing validation reduces how often this is reached, but does not change what happens when it is.
• #59643 (closed) — PreToolUse hook deny reason not surfaced to agent's tool_result. Same general area, opposite direction: there a real decision was not reported; here a non-decision is reported as a decision.

I searched the tracker with several phrasings before filing and found no report of this specific exit-code collision. Given the size of the tracker that is "not found", not "does not exist" — happy to see this closed as a duplicate if one is known.

Workaround (for others hitting this)

Do not disable a hook by renaming or deleting its script while the settings entry still references it. Replace the script's contents with a no-op that exits 0, or remove the hook entry from settings — never leave a configured command pointing at a missing file.