summaryrefslogtreecommitdiff
path: root/docs/windows/polyglot-hooks.md
diff options
context:
space:
mode:
authorJesse Vincent <jesse@fsck.com>2026-07-16 00:14:13 +0000
committerJesse Vincent <jesse@fsck.com>2026-07-16 00:14:13 +0000
commitfd12428a5cd63a3a63f12eea6c4ffad780ecf36d (patch)
tree515f8a53ecf9e30761dd86c4af4c413ab5e0305f /docs/windows/polyglot-hooks.md
parent390bc07abbae22f6bcbeaea98a0c7216dd9d5281 (diff)
docs(windows): document shell:bash hook dispatch and the PowerShell/CMD fallback hazardsfix/windows-hook-shell-bash
Diffstat (limited to 'docs/windows/polyglot-hooks.md')
-rw-r--r--docs/windows/polyglot-hooks.md14
1 files changed, 12 insertions, 2 deletions
diff --git a/docs/windows/polyglot-hooks.md b/docs/windows/polyglot-hooks.md
index 8b84f27..d1bcb84 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
}
]