docs: polyglot-hooks.md is stale — describes an older hook wrapper that diverges from the current run-hook.cmd #1653

New issue

Closed

opened 2026-05-29 21:53:19 +00:00 by obra · 1 comment

obra commented

2026-05-29 21:53:19 +00:00

(Migrated from github.com)

Verified divergences (doc vs. `hooks/run-hook.cmd` + `hooks/hooks*.json` on `dev`)

Topic	polyglot-hooks.md says	Actual repo
File layout	`session-start.cmd` + `session-start.sh` (per-script `.cmd` wrapper, `.sh` logic)	Extensionless scripts (`session-start`, `session-start-codex`) dispatched by a single generic `run-hook.cmd`
Extensionless requirement	Not mentioned	Scripts are deliberately extensionless because Claude Code on Windows prepends `bash` to any command containing `.sh` (documented in `run-hook.cmd` itself). This is the key fix and the doc omits it.
Bash invocation	`"C:\Program Files\Git\bin\bash.exe" -l -c "...cygpath..."`	Direct `"C:\Program Files\Git\bin\bash.exe" "%HOOK_DIR%%~1"`, then `(x86)` path, then `where bash`; exits 0 (no error) if no bash found. No `-l`, no `cygpath`.
`matcher` example	`startup	resume
"Reusable wrapper" example (lines ~141-155)	`bash -l -c "cd $(cygpath...) && ./$SCRIPT_NAME"`, args passed as `.sh` filenames	Real `run-hook.cmd` execs the named extensionless script directly and `exec bash` on Unix

Why it matters

The new docs/porting-to-a-new-harness.md guide points porters at this doc for Windows/cross-platform background. Following the stale doc would lead a contributor to recreate the .cmd/.sh + cygpath + bash -l pattern that run-hook.cmd was rewritten to avoid. The porting guide currently works around this by telling readers to "trust the code over that doc where they differ," which is a band-aid.

Suggested fix

Rewrite polyglot-hooks.md to describe the current run-hook.cmd (single generic dispatcher, extensionless scripts, the .sh-auto-bash-prepend rationale, the bash-location fallback chain, clean exit when bash is absent), or replace it with a short pointer to run-hook.cmd as the authoritative implementation plus the rationale.

Environment

Model: Claude Opus 4.8 (claude-opus-4-8)
Harness: Claude Code 2.1.156
Plugins: superpowers (+ github-triage)

Found while writing the porting-to-a-new-harness guide; the divergence was confirmed by reading both files on dev.

docs/windows/polyglot-hooks.md documents a cross-platform hook technique that no longer matches the implementation actually shipped in hooks/run-hook.cmd. Every concrete detail in the doc diverges from the code, so a contributor following the doc would reproduce the older, since-replaced approach. ## Verified divergences (doc vs. `hooks/run-hook.cmd` + `hooks/hooks*.json` on `dev`) | Topic | polyglot-hooks.md says | Actual repo | |---|---|---| | File layout | `session-start.cmd` + `session-start.sh` (per-script `.cmd` wrapper, `.sh` logic) | Extensionless scripts (`session-start`, `session-start-codex`) dispatched by a single generic `run-hook.cmd` | | Extensionless requirement | Not mentioned | Scripts are deliberately **extensionless** because Claude Code on Windows prepends `bash` to any command containing `.sh` (documented in `run-hook.cmd` itself). This is the key fix and the doc omits it. | | Bash invocation | `"C:\Program Files\Git\bin\bash.exe" -l -c "...cygpath..."` | Direct `"C:\Program Files\Git\bin\bash.exe" "%HOOK_DIR%%~1"`, then `(x86)` path, then `where bash`; exits 0 (no error) if no bash found. No `-l`, no `cygpath`. | | `matcher` example | `startup|resume|clear|compact` | `hooks.json` uses `startup|clear|compact` (Codex uses `startup|resume|clear`) | | "Reusable wrapper" example (lines ~141-155) | `bash -l -c "cd $(cygpath...) && ./$SCRIPT_NAME"`, args passed as `.sh` filenames | Real `run-hook.cmd` execs the named extensionless script directly and `exec bash` on Unix | ## Why it matters The new `docs/porting-to-a-new-harness.md` guide points porters at this doc for Windows/cross-platform background. Following the stale doc would lead a contributor to recreate the `.cmd`/`.sh` + `cygpath` + `bash -l` pattern that `run-hook.cmd` was rewritten to avoid. The porting guide currently works around this by telling readers to "trust the code over that doc where they differ," which is a band-aid. ## Suggested fix Rewrite polyglot-hooks.md to describe the current `run-hook.cmd` (single generic dispatcher, extensionless scripts, the `.sh`-auto-bash-prepend rationale, the bash-location fallback chain, clean exit when bash is absent), or replace it with a short pointer to `run-hook.cmd` as the authoritative implementation plus the rationale. ## Environment - Model: Claude Opus 4.8 (claude-opus-4-8) - Harness: Claude Code 2.1.156 - Plugins: superpowers (+ github-triage) Found while writing the porting-to-a-new-harness guide; the divergence was confirmed by reading both files on `dev`.

arimu1 commented

2026-05-31 03:46:29 +00:00

(Migrated from github.com)

Planning to submit a fix for this. The approach: rewrite polyglot-hooks.md to describe the actual run-hook.cmd implementation — extensionless scripts, three-location bash fallback, no -l, no cygpath, silent exit on no-bash. Will also update the hooks.json example to use the correct matcher (startup|clear|compact) and command (run-hook.cmd session-start). Documentation-only change, single file.

Planning to submit a fix for this. The approach: rewrite `polyglot-hooks.md` to describe the actual `run-hook.cmd` implementation — extensionless scripts, three-location bash fallback, no `-l`, no `cygpath`, silent exit on no-bash. Will also update the `hooks.json` example to use the correct matcher (`startup|clear|compact`) and command (`run-hook.cmd session-start`). Documentation-only change, single file.