DEV Community

maxisbusy-beep
maxisbusy-beep

Posted on Edited on

Your Claude Code hooks might not be firing on Windows. Here's the 10-second check.

Claude Code hooks are the only programmable stop between an agent and a destructive command. Permission prompts catch some of it, but hooks are the part you write yourself — which means they are also the part that can be quietly wrong.

On Windows, quietly wrong is the normal failure mode. Not an error. Nothing. The hook never fires, or it fires under a shell that cannot run it, and Claude carries on exactly as if you had configured nothing. You find out when something gets deleted.

The 10-second check

Before anything else, look at your matcher:

Get-Content .\.claude\settings.json -Raw | ConvertFrom-Json |
  ForEach-Object { $_.hooks.PreToolUse } | Select-Object matcher
Enter fullscreen mode Exit fullscreen mode

If a matcher meant to guard shell commands says Bash and not Bash|PowerShell, keep reading — that one is live right now and doing less than you think.

Three traps worth knowing about, whether or not you use any of this.

Trap 1: "matcher": "Bash" does not cover the PowerShell tool

On Windows, Claude Code can run commands through a separate PowerShell tool, not only the Bash tool. The matcher is tested against the tool's name, so a PreToolUse hook matched on Bash never sees those calls.

Which means this:

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{ "type": "command", "command": "..." }]
    }]
  }
}
Enter fullscreen mode Exit fullscreen mode

…routes nothing to your hook when the agent reaches for PowerShell. Every rule you wrote for Remove-Item -Recurse, rd /s, del or format C: is unreachable. The script is fine. The regex is fine. Nothing ever calls it.

The matcher takes a pipe-separated list of tool names, so the fix is one word longer:

"matcher": "Bash|PowerShell"
Enter fullscreen mode Exit fullscreen mode

This bug shipped in v1.0.0 of my own hook pack. The script had patterns for all four of those PowerShell commands, every one of them covered by a passing test, sitting behind a matcher that could never deliver a PowerShell call to them. The tests passed because they invoked the script directly. The wiring was never tested at all.

That is the real lesson, and I will come back to it.

Trap 2: shell form vs exec form

The usual way to write a PowerShell hook is shell form — one command string:

{
  "type": "command",
  "command": "powershell -NoProfile -ExecutionPolicy Bypass -File \"${CLAUDE_PROJECT_DIR}/.claude/hooks/block.ps1\""
}
Enter fullscreen mode Exit fullscreen mode

That works, but it has two sharp edges: it goes through a shell — Git Bash on Windows, or PowerShell when Git Bash is not installed — so you have taken on a dependency you did not ask for, and you are trusting quoting to survive a project path with a space in it.

Exec form avoids both. Set args, and each element is passed as one argument with no shell quoting at all:

{
  "type": "command",
  "command": "powershell.exe",
  "args": [
    "-NoProfile",
    "-ExecutionPolicy",
    "Bypass",
    "-File",
    "${CLAUDE_PROJECT_DIR}/.claude/hooks/block.ps1"
  ],
  "timeout": 15
}
Enter fullscreen mode Exit fullscreen mode

${CLAUDE_PROJECT_DIR} is substituted into each args element before launch, so C:\My Projects\thing cannot split into two arguments. No shell involved, and no Git Bash requirement for the hook.

One gotcha: if you set args, the shell key is ignored. Pick one form and commit to it.

Trap 3: the contract is exit codes, and nothing reminds you

A PreToolUse hook speaks by exiting:

Exit Meaning
2 Block. Your stderr becomes the message Claude sees.
0 No verdict. Normal permission flow continues — 0 does not approve the call.
anything else Non-blocking error. The action goes ahead.

That last row is the trap. A PowerShell script that throws an unhandled exception exits non-zero-and-not-2, and the dangerous command proceeds. Your safety hook fails open at precisely the moment you needed it.

Which means the whole body belongs inside the guard, not just the parsing. An exception thrown after a try/catch that only wraps ConvertFrom-Json puts you right back in the fail-open case:

$ErrorActionPreference = 'Stop'

try {
    $raw  = [Console]::In.ReadToEnd()
    $data = $raw | ConvertFrom-Json
    $command = [string]$data.tool_input.command

    if (-not [string]::IsNullOrWhiteSpace($command)) {
        # Deliberately spares --force-with-lease: it is the safe one,
        # and blocking it is how you get your own hook deleted.
        if ($command -match '(?i)\bgit\s+push\b.*\s(--force|-f)(\s|$)') {
            [Console]::Error.WriteLine("BLOCKED by hook: force push. Command: $command")
            exit 2
        }
    }
} catch {
    # Unreadable payload, or any unexpected throw: exit 0 rather than a
    # random code. A broken hook must not freeze your work -- but know
    # this means it fails OPEN. Choose it on purpose.
    exit 0
}

exit 0
Enter fullscreen mode Exit fullscreen mode

Fail-open versus fail-closed is a real decision with no free answer. Fail-closed on a malformed payload means one bad message bricks your session; fail-open means a crash disarms your guardrail. This pack fails open, and says so in its README. The point is choosing, not the choice.

How to actually test this

The payload arrives on stdin as JSON, which means you can test a hook properly with no agent involved:

'{"tool_name":"Bash","tool_input":{"command":"git push --force origin main"}}' |
  powershell -NoProfile -ExecutionPolicy Bypass -File .\.claude\hooks\block.ps1
"exit=$LASTEXITCODE"   # expect 2
Enter fullscreen mode Exit fullscreen mode

Wrap that in a loop over a table of cases and you have a real suite. Two things most people miss:

Test the allows, not just the blocks. A rule that blocks git push --force-with-lease, or rm -rf ./dist, is worse than no rule — the first time it gets in your way you will disable the whole file, and then you have nothing. Assert exit 0 on everything that must be permitted.

Test the wiring, not just the scripts. This is Trap 1 again. Read your own settings.json in the suite and assert properties of it:

$settings = Get-Content .\.claude\settings.json -Raw | ConvertFrom-Json
$cmdGroup = @($settings.hooks.PreToolUse) |
    Where-Object { $_.matcher -match 'Bash' } | Select-Object -First 1

# The case that would have caught my bug:
if ($cmdGroup.matcher -notmatch 'PowerShell') {
    throw "matcher does not cover the PowerShell tool"
}
# And: every referenced script exists, every handler sets a timeout,
# every handler uses exec form.
Enter fullscreen mode Exit fullscreen mode

A passing script behind a broken matcher is the failure mode that looks most like success. That is the one worth a test.

Checklist

  1. Every command matcher is Bash|PowerShell, not Bash.
  2. Hooks use exec form — command plus args.
  3. Every hook sets a timeout.
  4. Every code path exits 0 or 2 deliberately, error paths included.
  5. Tests cover blocks, allows, and the settings.json wiring.
  6. /hooks in a live session lists every matcher you expect to see. If one is missing, it is not loaded.
  7. Then actually trigger one. Ask Claude to run something your hook should block and watch for your own BLOCKED message. A hook that has never fired in anger is a hypothesis.

Trap 1 takes ten seconds to check and it is the one that silently voids everything else.


The hook and self-test from this article are on GitHub under MIT, free: https://github.com/maxisbusy-beep/claude-code-windows-guardrails-lite — clone it and run the suite in a minute. I also sell a fuller Windows pack (three hooks, two subagents, two skills, an installer, a 74-case suite) for $29: https://maxibee4.gumroad.com/l/claude-code-windows-guardrails. Everything in this article works without it.

Top comments (0)