claude-skills/skills/session-handoff/hooks

session-handoff hooks

Opt-in PostToolUse hook that detects substantive git commit invocations and signals the agent ("consider running session-handoff write-mode") via a system reminder. Replaces the agent-side commit-detection heuristic in the SKILL.md When to use section with a deterministic harness-side trigger.

Why opt-in (not auto-installed)

install.sh deliberately does not mutate ~/.claude/settings.json. Auto-rewriting the user's hook config on every skill install is the wrong shape — user expects install.sh to copy files, nothing more. The hook is shipped as scripts; user enables it once per machine.

Enable on Windows (PowerShell)

Add to ~/.claude/settings.json. Use powershell for stock Windows (PS 5.1, always present); use pwsh if you have PowerShell 7+ installed. The hook script runs cleanly under both.

Substitute C:\\Users\\<you> with your actual home path before pasting — see "Why literal path" below.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "powershell -NoProfile -ExecutionPolicy Bypass -File \"C:\\Users\\<you>\\.claude\\skills\\session-handoff\\hooks\\commit-detector.ps1\""
          }
        ]
      }
    ]
  }
}

Swap powershell for pwsh if you prefer PS 7+. To check which you have: Get-Command pwsh -ErrorAction SilentlyContinue (empty → PS 7 not installed → use powershell).

If hooks.PostToolUse already exists — append the matcher block to the array. Don't overwrite existing entries.

Restart Claude Code after editing settings.json — hooks are loaded at session start. A running session won't pick up the new hook until it's restarted (close + reopen the CC instance). Verify the hook is active by making a substantive commit and checking for a Substantive commit detected on ... system reminder in the next turn.

Why literal path (no $env:USERPROFILE / %USERPROFILE% / ~)

Claude Code on Windows invokes hook commands through git-bash, not PowerShell or cmd.exe directly. The outer-shell layer mangles shell-specific variable references before PowerShell ever sees the args:

• $env:USERPROFILE (PowerShell syntax) → bash treats $env as an empty variable and the rest :USERPROFILE\... becomes a literal, so PowerShell receives -File ":USERPROFILE\..." and fails with неверный формат имени / "invalid filename format".
• %USERPROFILE% (cmd syntax) → bash passes through literally, PowerShell doesn't expand it, same failure.
• ~/.claude/... → bash expands ~ to git-bash-style /c/Users/<you>/..., which PowerShell's -File can't resolve to a real Windows path.

Literal absolute path with C:\\Users\\<you>\\... (escaped backslashes for JSON) survives every outer shell unchanged. settings.json is per-user anyway — portability across machines isn't a concern at this layer.

Enable on Linux / macOS (bash)

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash ~/.claude/skills/session-handoff/hooks/commit-detector.sh"
          }
        ]
      }
    ]
  }
}

The bash variant needs python3 on PATH (used to parse the PostToolUse JSON stdin).

What gets signalled

On a successful git commit whose subject prefix is not in {meta, docs, style, chore} or fix typo, and whose body exceeds 200 characters or which touches more than 3 files — the hook emits a hookSpecificOutput.additionalContext system reminder of shape:

Substantive commit detected on <cwd>: <subject> (N files changed, body M chars). Consider invoking session-handoff write-mode to update .tasks/NEXT_SESSION.md.

On any of these → silent skip (exit 0, no JSON):

• malformed PostToolUse stdin
• Bash command isn't git commit
• command is git commit --amend
• commit returned non-zero exit
• cwd isn't a git work-tree
• subject prefix is in trivial set
• body ≤ 200 chars AND files ≤ 3

Smoke test (without enabling the hook)

Pipe a synthetic PostToolUse JSON to the script. On Windows:

$payload = @{
  tool_input    = @{ command = 'git commit -m "subject"' }
  tool_response = @{ exit_code = 0 }
  cwd           = (Get-Location).Path
} | ConvertTo-Json -Compress

$payload | pwsh -NoProfile -File .\skills\session-handoff\hooks\commit-detector.ps1

If your HEAD is a non-trivial commit (e.g. recent feat: with > 200-char body or > 3 files), output is JSON containing additionalContext. Otherwise — empty stdout (silent skip).

Caveats

• Rebase / cherry-pick noise. Every commit in a rebase or cherry-pick batch will re-fire the hook. Deferred to a follow-up if it actually annoys in practice; the hook is opt-in so the cost is bounded.
• First-non-trivial commit of session. The agent-side heuristic in SKILL.md treats the first non-trivial commit of a session as "always substantive" regardless of thresholds. The hook can't see session boundaries — uses only body/file thresholds. Slight under-detection on small first commits; acceptable trade-off for harness-side determinism.
• No automatic write-mode invocation. Hook only signals. The agent still decides whether to run session-handoff write-mode in response — keeps the user-agency invariant from SKILL.md What NOT to do.