fix(hooks): invoke viz hooks in shell form so Windows uses Git Bash (#27)

[ZayanKhan-12]

Fixes #27.

The fix

hooks/hooks.json, two lines:

-"hooks": [{ "type": "command", "command": "bash", "args": ["${CLAUDE_PLUGIN_ROOT}/viz/hooks/session_end.sh"] }]
+"hooks": [{ "type": "command", "command": "\"${CLAUDE_PLUGIN_ROOT}\"/viz/hooks/session_end.sh" }]

Passing args is what puts a hook in exec form, where Claude Code resolves command against PATH and spawns it directly with no shell. That is why bare bash becomes the WSL launcher on Windows, exactly as the report diagnosed.

Dropping args switches to shell form, where the string goes to sh -c on macOS and Linux and to Git Bash on Windows — which resolves the plugin path correctly. This is the form the plugin docs show for ${CLAUDE_PLUGIN_ROOT} script hooks.

Shell form executes the file itself rather than handing it to an interpreter, so both scripts go to mode 755. At 644 they exit 126 with "Permission denied" — verified, not assumed.

forward.sh has the same bug

The report is about SessionEnd, but PostToolUse carried the byte-identical exec-form invocation and is just as broken on Windows. It only escaped notice because it fires on visualization tool calls rather than on every exit.

It needed the opposite treatment from session_end.sh, though. Off macOS forward.sh is not a no-op — it calls bail unsupported_os, which is what tells the model the chart is available at the sandbox URL. So it has to keep working on Windows, not stop being registered. Both hooks are fixed the same way; only session_end.sh is a true no-op.

On "registered unconditionally"

I could not fix cause 1 as described, and I think the premise doesn't hold — flagging it rather than quietly skipping it.

There is no OS conditional for hook registration. The if field takes permission-rule syntax and, per the hooks reference, "Only evaluated on tool events: PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest, and PermissionDenied. On other events, a hook with if set never runs." Putting if on SessionEnd would disable the hook on macOS too — the one platform it exists for.

So a macOS-only hook can only be made cheap and silent, not unregistered. With cause 2 fixed it is: the shell starts, uname misses Darwin, the script exits 0 with no output. Cause 1 stops being a bug once cause 2 is fixed. If you'd rather not spawn a shell at all on non-macOS, that needs a Claude Code-side feature.

Verified on Windows

.github/workflows/hooks.yaml runs the suite on macOS, Linux and Windows. All four jobs green.

The job that matters is test (windows-latest, native plugin root). Git Bash reports $PWD in Unix form, so an ordinary Windows job would never see the path shape that caused this bug. That job injects CLAUDE_PLUGIN_ROOT as GitHub's native workspace path instead, so the hook receives a real D:\... root:

shell: C:\Program Files\Git\bin\bash.EXE --noprofile --norc -e -o pipefail {0}
env:
  CLAUDE_PLUGIN_ROOT: D:\a\claude-code-plugin\claude-code-plugin

hooks run clean on this host
  ok   SessionEnd exits 0 on MINGW64_NT-10.0-26100
  ok   SessionEnd prints nothing

the non-macOS no-op is reachable and silent
  ok   SessionEnd is a silent no-op when uname reports MINGW64_NT-10.0
  ok   SessionEnd is a silent no-op when uname reports MSYS_NT-10.0
  ok   SessionEnd is a silent no-op when uname reports CYGWIN_NT-10.0
  ok   SessionEnd is a silent no-op when uname reports Linux

PostToolUse still falls back off macOS
  ok   PostToolUse exits 0 off macOS
  ok   PostToolUse returns the sandbox-URL fallback off macOS

14 passed, 0 failed

Full run: https://github.com/ZayanKhan-12/claude-code-plugin/actions/runs/34900090384

Worth reporting: the first Windows run went red, and it caught a real bug — in the test harness, while every behavioural check already passed. The harness recovered the script path with sed, and sed treats backslashes in the replacement as escapes, so D:\a\... became D:<BEL>.... That is the same class of bug as #27 itself, reproduced inside the test written to catch it. Fixed in the third commit by substituting with bash parameter expansion, and by resolving the file checks against the checkout rather than the injected root — path shape is what the behavioural runs are for. The mode assertion now reads git ls-files -s instead of testing -x, because git doesn't materialise permission bits on Windows, so -x says nothing there while the recorded mode is what actually ships.

Tests

tests/hooks_test.sh — POSIX-ish bash, jq the only dependency, no network, never opens the ddviz socket, runs with DO_NOT_TRACK=1 so a local run can't post to intake.

Run against the pre-fix config it reports 11 passed, 1 failed, and the one failure is the exec-form check. That is deliberate. The harness understands both hook forms, so it invokes the old config the way Claude Code actually would; macOS was never broken and the suite says so instead of manufacturing a failure. The single red line is the real defect.

CLAUDE.md

Added, since there wasn't one. The part that matters is the hook rule above — shell form, mode 755, and why if can't gate SessionEnd — so this doesn't get reintroduced. It also records what I had to work out from the code and would have wanted stated:

• forward.sh's off-macOS bail is load-bearing, not dead code; don't "optimize" it into an early exit.
• forward.sh's template.ddviz_telemetry.sh fallback is live in the internal source tree, so it looks dead here but isn't.
• Skill scripts are a different mechanism — SKILL.md runs them through the Bash tool, which already uses Git Bash on Windows. They correctly keep bash "<path>" and mode 644, and this change deliberately leaves them alone.
• DO_NOT_TRACK=1 belongs in anything exercising these scripts.

Noted from CONTRIBUTING that this repo is regenerated from an internal source, so I kept the fix itself to two lines and a mode change. The tests, CI and CLAUDE.md are separable — happy to split them into their own PR if that's easier to carry across, or drop the CI workflow if you'd rather own that yourself.

🤖 Generated with Claude Code

https://claude.ai/code/session_01UdFDRJ6HXM45hua8JnXomE