Adopt exec-form hook rows fleet-wide once upstream #90495 is ruled out on Windows

[kyle-sexton]

Summary

Every shell-form hook row (no args key) is passed to a shell before its own interpreter starts: sh -c on macOS and Linux, Git Bash on Windows (hooks doc, "Exec form and shell form"). Exec form (an args array, even empty) spawns the executable directly with no shell and substitutes ${CLAUDE_PLUGIN_ROOT} into command and each args element as plain strings. On this fleet 51 of the 52 always-on rows measured by the hook-performance program are shell form; only context-budget's node row is exec form. That row was the cheapest per-tool-call hook in the final run (81 ms against 1,360 ms and up for the bash-scripted rows), though it also does the least work, so the shell spawn's share is unmeasured.

Why it is bigger than the shebang hop (#3684)

Two spawns disappear per fire, not one: the Git Bash bash.exe that shell form starts, and the env the shebang adds. A peer session's host measurement adds a third cost: C:\Program Files\Git\usr\bin\bash.exe carries a signer certificate that expired 2026-05-05 and msys-2.0.dll is unsigned, and Microsoft documents that Defender real-time protection scans every launch of an unsigned binary (learn.microsoft.com, defender-endpoint troubleshoot-performance-issues). That fits the steady MsMpEng share the peer observed; exec form on a signed interpreter avoids the scan too. The machine-side remedy (a Defender performance recording, then a narrow process exclusion or a Git for Windows update with a re-signed bash) is outside this repo.

What blocks it

The hook-performance program deferred exec form on purpose (its constraint 8): upstream anthropics/claude-code#90495, open, last updated 2026-08-29, reports that on Windows exec-form args are dropped and the hook is still routed through bash.exe, crashing on stdin. The program's phase 3 live probe under claude --debug-file did show the context-budget exec-form row firing and returning ask on this host, which is one data point against the bug reproducing here, but it never exercised a bash-scripted hook in exec form.

Ask

1. A live probe on this Windows host: one throwaway hook row in exec form ("command": "bash", "args": ["${CLAUDE_PLUGIN_ROOT}/hooks/x.sh"]) under claude --debug-file, confirming the args arrive and the script reads its stdin payload. That decides whether #90495 applies.
2. If it works: a paired fan-out harness run (--runs 3, one host) on a representative row set, then a fleet sweep of hooks.json commands to exec form, one plugin per PR, every touched plugin bumped. Rows that need shell features (pipes, &&) stay shell form. The harness itself must learn to spawn exec-form rows the way Claude Code does, or its numbers will not reflect the change.
3. If #90495 reproduces: subscribe to it and keep this issue open as the tracker.

Related

• Invoke hook scripts through bash to skip the env shebang hop on every fire #3684 (the env shebang hop; subsumed by exec form on any row that adopts it)
• guardrails dispatcher is the whole per-tool-call budget miss after the hook-performance program #3685 (guardrails dispatcher; its row is the single largest beneficiary)
• Hook performance program: measure and cut every runtime-cost surface on the Windows host #3623 (program tracking issue)

[kyle-sexton]

Live exec-form probe, as requested. Result: on this host, exec form works for bash-scripted rows, including a bare bash command name, with args intact and the JSON payload delivered on stdin. anthropics/claude-code#90495 did not reproduce.

Host: melo-lap-001 class (Windows 11 Pro 26200), Claude Code 2.1.259, Git for Windows 2.55.0.3 (bash 5.3.15), WSL 2 installed (so System32\bash.exe exists on PATH as a competing resolution target).

Setup: a throwaway directory with no project settings; hooks supplied via --settings <file> so nothing touched a plugin row. Three PreToolUse Bash handlers pointing at the same probe script, which reads fd 0 with a bare cat (not /dev/stdin, which MSYS cannot resolve for a Win32 pipe) and writes a marker file:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "C:\\Program Files\\Git\\usr\\bin\\bash.exe", "args": ["<abs>/probe-hook.sh", "fullpath"], "timeout": 20 },
          { "type": "command", "command": "bash", "args": ["<abs>/probe-hook.sh", "bare"], "timeout": 20 },
          { "type": "command", "command": "bash \"<abs>/probe-hook.sh\" shellform", "timeout": 20 }
        ]
      }
    ]
  }
}

Run: claude -p 'Run exactly this bash command and reply with its output: echo probe-ok' --model sonnet --settings <file> --debug-file <file>. Two runs; identical outcome both times.

Markers (all three written, every run):

row	argv0	args	bash	exe	uname	stdin bytes
exec, full path to Git bash.exe	probe-hook.sh	fullpath	5.3.15(1)-release	/usr/bin/bash	MINGW64_NT-10.0-26200	540
exec, bare bash	probe-hook.sh	bare	5.3.15(1)-release	/usr/bin/bash	MINGW64_NT-10.0-26200	540
shell form (control)	probe-hook.sh	shellform	5.3.15(1)-release	/usr/bin/bash	MINGW64_NT-10.0-26200	540

The 540-byte stdin payload was the normal PreToolUse JSON (session_id, transcript_path, cwd, tool_name, tool_input, ...). The bare bash row resolved to Git Bash, not the WSL relay: uname reports MINGW64 and the process image is the MSYS one. Each hook exited 0 and the tool call proceeded (probe-ok printed).

Debug file: it records if-gated skips (Skipping hook due to if condition "Bash(*hygiene.py*)" not matching, etc.) and a completed with status 0 line for the SessionEnd command hook, but no per-hook completion line for these PreToolUse handlers, so the markers are the evidence of execution rather than the log. No error, timeout, or stdin-related line appears anywhere in either debug file.

What this does and does not show: two bash-scripted exec-form rows, one with an absolute image path and one relying on PATH resolution of bash, fired correctly with args and stdin on 2.1.259 with WSL present. It does not cover ${CLAUDE_PLUGIN_ROOT} expansion inside args (the probe used literal absolute paths) or the fleet's hook-utils stdin buffering; those are the next things a plugin-row conversion should check.

[kyle-sexton]

Thank you; that clears gate 1 for bare bash on this host (2.1.259, WSL present). Two things still stand between the probe and a fleet sweep, so the issue stays open and unassigned rather than moving to a PR: (1) ${CLAUDE_PLUGIN_ROOT} expansion inside args is untested, and every plugin row depends on it; the doc says it is substituted as a plain string, so one more marker probe with args: ["${CLAUDE_PLUGIN_ROOT}/hooks/x.sh"] under a real plugin install (a throwaway local marketplace or a fork of one small plugin) decides it. (2) The fan-out harness spawns rows the way shell form does; before any before-and-after number is trusted the harness needs an exec-form branch that reads args and spawns without a shell, otherwise the sweep measures nothing. The guardrails dispatcher row (#3685) is the first candidate once both are in hand.

[kyle-sexton]

Gate 2 probe: ${CLAUDE_PLUGIN_ROOT} substitution inside exec-form args under a real plugin load. Same host and Claude Code 2.1.259 as the previous comment; the plugin was a throwaway loaded with --plugin-dir <dir> (its own .claude-plugin/plugin.json and hooks/hooks.json), so the substitution path is the plugin one, not --settings.

Three PreToolUse Bash rows on the same probe script:

row	fired	argv0 as the script saw it	CLAUDE_PLUGIN_ROOT in env	stdin
exec: "command": "bash", "args": ["${CLAUDE_PLUGIN_ROOT}/hooks/probe.sh", "args-pluginroot"]	yes	C:\Users\<user>\...\plugin/hooks/probe.sh	C:\Users\<user>\...\plugin	540 bytes
exec: "command": "${CLAUDE_PLUGIN_ROOT}/hooks/probe.sh", "args": ["command-pluginroot"]	no	(no marker written)
shell (control): bash "${CLAUDE_PLUGIN_ROOT}/hooks/probe.sh" shellform-pluginroot	yes	C:/Users/<user>/.../plugin/hooks/probe.sh	C:/Users/<user>/.../plugin	540 bytes

So the sweep pattern that works is "command": "bash" with the script path in args; substitution happens before spawn and the payload arrives on fd 0. Putting the script itself in command does not work in exec form on Windows: there is no shell to honour the shebang, and the spawn fails at the libuv layer. Exact stderr Claude Code recorded (surfaced by the claude-ops Stop hook as a failure record for PreToolUse:Bash [${CLAUDE_PLUGIN_ROOT}/hooks/probe.sh command-pluginroot]): Failed to run: EFTYPE: inappropriate file type or format, uv_spawn, exit 1. The tool call itself proceeded, so this failure mode is silent unless something audits hook exits.

One difference worth carrying into the sweep: in exec form the substituted root uses backslashes (C:\Users\...\plugin plus the row's own /hooks/... suffix), while shell form hands the script a forward-slash root. MSYS bash resolves the mixed form for $0 and for ${BASH_SOURCE[0]%/*}, so the probe ran, but any hook that compares CLAUDE_PLUGIN_ROOT textually, feeds it to a regex, or strips with a backslash pattern will see a different string than it sees today. Worth a grep across hooks/ before converting a row.

[kyle-sexton]

Gate 3: the dotfiles harness now has an exec-form branch, and here is a first before-and-after through it.

Harness change: melodic-software/dotfiles#628 (branch perf/hook-fanout-exec-form). hook_rows reads the form off each hooks.json row (exec when args is present, an empty array included), resolve_exec rebuilds the argument vector with ${CLAUDE_PLUGIN_ROOT} substituted, and time_command lets timeout exec the program directly instead of bash -c. Such rows report as RAN(exec). 56/56 harness assertions pass, 13 of them new.

Measurement: laptop under five-session load, both runs valid (spawn floor S = 20 ms before, 19 ms after), --runs 3. The installed eol-normalizer (shell form) versus a copy whose single row was rewritten to "command": "bash", "args": ["${CLAUDE_PLUGIN_ROOT}/hooks/eol-normalizer.sh"], measured through --plugin-root eol-normalizer=<copy> on the same event set:

row	shell form (installed)	exec form (copy)
PostToolUse:Write eol-normalizer, median ms (runs)	610 (346, 712, 610)	514 (514, 862, 382)
PostToolUse:Edit eol-normalizer, median ms (runs)	721 (533, 776, 721)	484 (347, 484, 720)

Medians move 96 ms and 237 ms in the expected direction (one fewer bash spawn plus the env shebang hop), but three samples per row with this spread is not a sweep-grade number; --runs higher and an interleaved pair of runs would be, and the harness now supports both. Everything else in the two reports is the fleet's existing shell-form baseline and matches the earlier capture.

Sweep pattern confirmed across gates 1-3: "command": "bash" (bare, resolves to Git Bash with WSL present) with the script path in args, ${CLAUDE_PLUGIN_ROOT} substituted before spawn, JSON on fd 0, and a backslash root in the substituted path and in the exported variable. Script-as-command fails with EFTYPE ... uv_spawn and should not be used.

[kyle-sexton]

Correction: the sweep pattern this issue's gate probes recommended is one this repo already bans

I need to retract the conclusion in my gate 2 and gate 3 comments above. They state that the sweep pattern is "command": "bash" with the script path in args. That shape is empirically correct on this host, and it is also the exact shape scripts/check-hook-exec-form.sh exists to reject. I found this by writing the guardrails conversion and running the repo's own gates against it.

EXEC-FORM HOOK: plugins/guardrails/hooks/hooks.json:.hooks.PreToolUse[0].hooks[0]: exec-form hook (`args` present) with bare command "bash"

All four guardrails rows fail. EXEC_NAME_ALLOWLIST is (node).

That gate is not a stylistic preference. Its doc-block records the defect class shipping three times (#1006 fixed it, #1504 reintroduced it, #2570 fixed it again) and cites #1416, where the disk-hygiene destructive guard logged 73 runs that were every one a hook_non_blocking_error while the guard was believed live. A failed hook launch is non-blocking, so a PreToolUse guard wired to a name that does not resolve silently enforces nothing.

The specific hazard it names is the one my probe host cannot see. On Windows a bare bash resolves to the WSL relay at System32\bash.exe. My gate 1 comment reported that bare bash works here and explicitly noted WSL is installed, which is precisely the condition that makes the relay succeed instead of failing. A fleet host without a distro providing /bin/bash gets execvpe(/bin/bash) failed, and the guard goes quiet rather than erroring visibly. I proved the pattern on the one configuration where the bug is invisible and generalised from it.

Both branches are closed for a bash-scripted row

command shape	exec form fires?	passes check-hook-exec-form.sh?
bash (bare), script in args	yes, on this host	no, bare name
${CLAUDE_PLUGIN_ROOT}/hooks/probe.sh, args after	no, EFTYPE: inappropriate file type or format, uv_spawn	yes
absolute path to bash.exe	untested	yes, but machine-specific and unshippable

The middle row is the one recorded in the gate 2 table above: exec form has no shell to honour the shebang, so libuv refuses to spawn a text file. So there is no shape that is both launchable on Windows and acceptable to the gate, unless a row's interpreter is already an allowlisted executable such as node. That is exactly why context-budget's node row is the one exec-form row in the fleet, and it explains the single data point the program had.

What this means for the sweep

Ask item 2 should not proceed for bash-scripted rows as written. Options, none of them free:

1. Leave bash rows in shell form and take the win only where the interpreter is a real executable. That is node today, and it retires most of the projected benefit, since the expensive rows are the bash dispatchers.
2. Give the gate a Windows-safe way to name Git Bash, for example an allowlist entry paired with a resolution the gate can verify, so bash stops meaning the WSL relay. This is a change to the gate's contract and should be argued on its own issue, not smuggled in through a sweep.
3. Move a hot row's entrypoint to an allowlisted interpreter. The guardrails dispatcher is the largest beneficiary, and a node entrypoint that execs the guards would clear the gate, but that is a rewrite rather than a config change.

I am not opening a guardrails PR. The branch I built to test this is discarded. Gates 1 through 3 stand as measurements; it is their conclusion that was wrong, and the fleet-sweep instruction in this issue should be treated as blocked until one of the options above is chosen.

[kyle-sexton]

Filed #3708 for option 2 from my correction above: the gate-contract question of whether there can be a Windows-safe, gate-legal way to name Git Bash. That issue carries the two closed branches, the honestly-scoped payoff (roughly 100-240 ms per fire on the eol-normalizer rows, and nothing off the guardrails body cost), and four candidate directions each with its objection, including why the userConfig route runs into check-hook-userconfig-argv.sh.

This issue's sweep stays blocked until #3708 is decided. Nothing else needed here.

[kyle-sexton]

This was generated by AI during triage.

Blocked by #3708 decision. This item waits on the decision tracked in #3708; resolving it there unblocks this one.