From fd12428a5cd63a3a63f12eea6c4ffad780ecf36d Mon Sep 17 00:00:00 2001 From: Jesse Vincent Date: Thu, 16 Jul 2026 00:14:13 +0000 Subject: [PATCH] docs(windows): document shell:bash hook dispatch and the PowerShell/CMD fallback hazards --- docs/windows/polyglot-hooks.md | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/docs/windows/polyglot-hooks.md b/docs/windows/polyglot-hooks.md index 8b84f271..d1bcb84e 100644 --- a/docs/windows/polyglot-hooks.md +++ b/docs/windows/polyglot-hooks.md @@ -6,9 +6,18 @@ Claude Code plugins need hooks that work on Windows, macOS, and Linux. This docu ## The Problem -Claude Code runs hook commands through the system's default shell: -- **Windows**: CMD.exe +Claude Code runs hook commands through a shell: - **macOS/Linux**: bash or sh +- **Windows with Git Bash installed**: Git Bash +- **Windows without Git Bash**: PowerShell (older versions used CMD.exe) + +Neither Windows fallback shell can parse our command string: PowerShell treats +a leading quoted path as a string expression and errors on the next bareword, +and CMD.exe's `/c` quoting rules strip the outer quotes when the path contains +a metacharacter such as `(`. Our hooks therefore declare `"shell": "bash"` +(supported since Claude Code 2.1.81; older versions ignore the key), which +forces the Git Bash route and, when Git Bash is absent, produces an actionable +"install Git for Windows" error instead of a shell parser failure. This creates several challenges: @@ -42,6 +51,7 @@ hooks/ { "type": "command", "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start", + "shell": "bash", "async": false } ]