PostToolUse hook in `~/.claude/settings.json` was using
`$env:USERPROFILE` (PowerShell syntax), but Claude Code on
Windows runs hook commands through git-bash. Bash treats `$env`
as an empty variable, leaving `":USERPROFILE\..."` as the literal
`-File` argument — PowerShell fails with "invalid filename
format" and the hook never fires.
Install snippet in hooks/README.md now uses literal absolute
path `C:\Users\<you>\.claude\...` with a "Why literal path"
section explaining why `$env:VAR` / `%VAR%` / `~` all break
through the bash-harness chain on Windows.
Retracts the v0.3.0 "live-hook e2e smoke done" closure — that
result was from synthetic replay through the PowerShell tool,
which bypassed the broken harness chain. Real e2e verification
requires this fix plus a CC restart, then a substantive commit
to observe `additionalContext` surface.
Two findings from live-hook e2e smoke 2026-05-25 on this Windows machine:
(1) README snippet was pwsh-only — PS 7 Core isn't on stock Windows. PS 5.1
(`powershell`) is always present and the hook script runs cleanly under both.
README now leads with `powershell` and notes the `pwsh` swap for PS 7+ users.
(2) Missing caveat that hooks load at Claude Code session start — mid-session
edits to ~/.claude/settings.json don't activate the hook until CC restart.
Without this note user would think the hook is broken after applying the
snippet (standalone smoke would pass but live in-session wouldn't fire).
Added explicit restart instruction + verification recipe.
Also: dist/session-handoff.skill now tracked (was missing since promotion —
inconsistent with other dist/*.skill artifacts that ship in repo).
PATCH bump 0.3.1 → 0.3.2 (docs-only, no behavioral change in hook or skill).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Hooks live in skills/session-handoff/hooks/:
- commit-detector.ps1 Windows/PowerShell
- commit-detector.sh POSIX (python3 for JSON parsing)
- README.md opt-in instructions, cross-platform settings.json
snippets, smoke procedure
Hook reads PostToolUse stdin, detects substantive `git commit` (prefix
not in meta/docs/style/chore + fix typo, AND body >200 chars OR files >3).
On hit, emits hookSpecificOutput.additionalContext so Claude Code
surfaces a system reminder next iteration. Silent skip on --amend, failed
commits, non-git cwd, trivial prefix, below thresholds.
install.sh deliberately does NOT mutate settings.json — opt-in via the
README hook config snippet, applied once per machine. SKILL.md body
mentions the hook as an optional alternative to the agent-side
behavioral heuristic.
Bump 0.2.1 -> 0.3.0 MINOR (new opt-in capability, backward-compatible —
SKILL keeps working without the hook).
Deferred (separate follow-ups if needed):
- live-hook e2e smoke (would interfere with current session commits)
- rebase/cherry-pick batch deduplication
Closes [session-handoff-posttooluse-hook] (partial: stdin smoke,
live-hook deferred).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
