Add Windows support for plugin hooks

docs/windows/polyglot-hooks.md

@@ -0,0 +1,212 @@
+# Cross-Platform Polyglot Hooks for Claude Code
+
+Claude Code plugins need hooks that work on Windows, macOS, and Linux. This document explains the polyglot wrapper technique that makes this possible.
+
+## The Problem
+
+Claude Code runs hook commands through the system's default shell:
+- **Windows**: CMD.exe
+- **macOS/Linux**: bash or sh
+
+This creates several challenges:
+
+1. **Script execution**: Windows CMD can't execute `.sh` files directly - it tries to open them in a text editor
+2. **Path format**: Windows uses backslashes (`C:\path`), Unix uses forward slashes (`/path`)
+3. **Environment variables**: `$VAR` syntax doesn't work in CMD
+4. **No `bash` in PATH**: Even with Git Bash installed, `bash` isn't in the PATH when CMD runs
+
+## The Solution: Polyglot `.cmd` Wrapper
+
+A polyglot script is valid syntax in multiple languages simultaneously. Our wrapper is valid in both CMD and bash:
+
+```cmd
+: << 'CMDBLOCK'
+@echo off
+"C:\Program Files\Git\bin\bash.exe" -l -c "\"$(cygpath -u \"$CLAUDE_PLUGIN_ROOT\")/hooks/session-start.sh\""
+exit /b
+CMDBLOCK
+
+# Unix shell runs from here
+"${CLAUDE_PLUGIN_ROOT}/hooks/session-start.sh"
+```
+
+### How It Works
+
+#### On Windows (CMD.exe)
+
+1. `: << 'CMDBLOCK'` - CMD sees `:` as a label (like `:label`) and ignores `<< 'CMDBLOCK'`
+2. `@echo off` - Suppresses command echoing
+3. The bash.exe command runs with:
+   - `-l` (login shell) to get proper PATH with Unix utilities
+   - `cygpath -u` converts Windows path to Unix format (`C:\foo` → `/c/foo`)
+4. `exit /b` - Exits the batch script, stopping CMD here
+5. Everything after `CMDBLOCK` is never reached by CMD
+
+#### On Unix (bash/sh)
+
+1. `: << 'CMDBLOCK'` - `:` is a no-op, `<< 'CMDBLOCK'` starts a heredoc
+2. Everything until `CMDBLOCK` is consumed by the heredoc (ignored)
+3. `# Unix shell runs from here` - Comment
+4. The script runs directly with the Unix path
+
+## File Structure
+
+```
+hooks/
+├── hooks.json           # Points to the .cmd wrapper
+├── session-start.cmd    # Polyglot wrapper (cross-platform entry point)
+└── session-start.sh     # Actual hook logic (bash script)
+```
+
+### hooks.json
+
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/session-start.cmd\""
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Note: The path must be quoted because `${CLAUDE_PLUGIN_ROOT}` may contain spaces on Windows (e.g., `C:\Program Files\...`).
+
+## Requirements
+
+### Windows
+- **Git for Windows** must be installed (provides `bash.exe` and `cygpath`)
+- Default installation path: `C:\Program Files\Git\bin\bash.exe`
+- If Git is installed elsewhere, the wrapper needs modification
+
+### Unix (macOS/Linux)
+- Standard bash or sh shell
+- The `.cmd` file must have execute permission (`chmod +x`)
+
+## Writing Cross-Platform Hook Scripts
+
+Your actual hook logic goes in the `.sh` file. To ensure it works on Windows (via Git Bash):
+
+### Do:
+- Use pure bash builtins when possible
+- Use `$(command)` instead of backticks
+- Quote all variable expansions: `"$VAR"`
+- Use `printf` or here-docs for output
+
+### Avoid:
+- External commands that may not be in PATH (sed, awk, grep)
+- If you must use them, they're available in Git Bash but ensure PATH is set up (use `bash -l`)
+
+### Example: JSON Escaping Without sed/awk
+
+Instead of:
+```bash
+escaped=$(echo "$content" | sed 's/\\/\\\\/g' | sed 's/"/\\"/g' | awk '{printf "%s\\n", $0}')
+```
+
+Use pure bash:
+```bash
+escape_for_json() {
+    local input="$1"
+    local output=""
+    local i char
+    for (( i=0; i<${#input}; i++ )); do
+        char="${input:$i:1}"
+        case "$char" in
+            $'\\') output+='\\' ;;
+            '"') output+='\"' ;;
+            $'\n') output+='\n' ;;
+            $'\r') output+='\r' ;;
+            $'\t') output+='\t' ;;
+            *) output+="$char" ;;
+        esac
+    done
+    printf '%s' "$output"
+}
+```
+
+## Reusable Wrapper Pattern
+
+For plugins with multiple hooks, you can create a generic wrapper that takes the script name as an argument:
+
+### run-hook.cmd
+```cmd
+: << 'CMDBLOCK'
+@echo off
+set "SCRIPT_DIR=%~dp0"
+set "SCRIPT_NAME=%~1"
+"C:\Program Files\Git\bin\bash.exe" -l -c "cd \"$(cygpath -u \"%SCRIPT_DIR%\")\" && \"./%SCRIPT_NAME%\""
+exit /b
+CMDBLOCK
+
+# Unix shell runs from here
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)"
+SCRIPT_NAME="$1"
+shift
+"${SCRIPT_DIR}/${SCRIPT_NAME}" "$@"
+```
+
+### hooks.json using the reusable wrapper
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start.sh"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" validate-bash.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Troubleshooting
+
+### "bash is not recognized"
+CMD can't find bash. The wrapper uses the full path `C:\Program Files\Git\bin\bash.exe`. If Git is installed elsewhere, update the path.
+
+### "cygpath: command not found" or "dirname: command not found"
+Bash isn't running as a login shell. Ensure `-l` flag is used.
+
+### Path has weird `\/` in it
+`${CLAUDE_PLUGIN_ROOT}` expanded to a Windows path ending with backslash, then `/hooks/...` was appended. Use `cygpath` to convert the entire path.
+
+### Script opens in text editor instead of running
+The hooks.json is pointing directly to the `.sh` file. Point to the `.cmd` wrapper instead.
+
+### Works in terminal but not as hook
+Claude Code may run hooks differently. Test by simulating the hook environment:
+```powershell
+$env:CLAUDE_PLUGIN_ROOT = "C:\path\to\plugin"
+cmd /c "C:\path\to\plugin\hooks\session-start.cmd"
+```
+
+## Related Issues
+
+- [anthropics/claude-code#9758](https://github.com/anthropics/claude-code/issues/9758) - .sh scripts open in editor on Windows
+- [anthropics/claude-code#3417](https://github.com/anthropics/claude-code/issues/3417) - Hooks don't work on Windows
+- [anthropics/claude-code#6023](https://github.com/anthropics/claude-code/issues/6023) - CLAUDE_PROJECT_DIR not found

hooks/hooks.json

@@ -6,7 +6,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/session-start.sh"
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start.sh"
           }
         ]
       }

hooks/run-hook.cmd

@@ -0,0 +1,15 @@
+: << 'CMDBLOCK'
+@echo off
+REM Polyglot wrapper: runs .sh scripts cross-platform
+REM Usage: run-hook.cmd <script-name> [args...]
+REM The script should be in the same directory as this wrapper
+
+"C:\Program Files\Git\bin\bash.exe" -l "%~dp0%~1"
+exit /b
+CMDBLOCK
+
+# Unix shell runs from here
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)"
+SCRIPT_NAME="$1"
+shift
+"${SCRIPT_DIR}/${SCRIPT_NAME}" "$@"

hooks/session-start.sh

@@ -17,9 +17,27 @@ fi
 # Read using-superpowers content
 using_superpowers_content=$(cat "${PLUGIN_ROOT}/skills/using-superpowers/SKILL.md" 2>&1 || echo "Error reading using-superpowers skill")
 
-# Escape outputs for JSON
-using_superpowers_escaped=$(echo "$using_superpowers_content" | sed 's/\\/\\\\/g' | sed 's/"/\\"/g' | awk '{printf "%s\\n", $0}')
-warning_escaped=$(echo "$warning_message" | sed 's/\\/\\\\/g' | sed 's/"/\\"/g' | awk '{printf "%s\\n", $0}')
+# Escape outputs for JSON using pure bash
+escape_for_json() {
+    local input="$1"
+    local output=""
+    local i char
+    for (( i=0; i<${#input}; i++ )); do
+        char="${input:$i:1}"
+        case "$char" in
+            $'\\') output+='\\' ;;
+            '"') output+='\"' ;;
+            $'\n') output+='\n' ;;
+            $'\r') output+='\r' ;;
+            $'\t') output+='\t' ;;
+            *) output+="$char" ;;
+        esac
+    done
+    printf '%s' "$output"
+}
+
+using_superpowers_escaped=$(escape_for_json "$using_superpowers_content")
+warning_escaped=$(escape_for_json "$warning_message")
 
 # Output context injection as JSON
 cat <<EOF