[BUG] Hook `if` conditions for Bash fail open on $()/backticks even for command-name-only patterns

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

A hook if condition naming only a command — e.g. Bash(cat *) — fires on Bash commands that do not match it at all, as soon as the command contains a command substitution $(...) or a backtick.

The hooks reference documents the opposite for this exact case. Its Bash matching table contains these two rows:

| if pattern | Bash command | Hook runs? | Why (verbatim from docs) |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------------ | ------------------------------- |
| Bash(rm *) | echo $(date) | no | "no subcommand matchesrm *" |
| Bash(git push *) | echo $(date) | yes | "patterns that specify more than the command name run the hook anyway on $(), backticks, or $VAR" | | |

On Windows the first row is not reproducible: the fail-open applies to command-name-only patterns too, so the distinction the table draws does not hold.

Measured with two PostToolUse spy hooks over two deterministic runs. CMDONLY_NEG is gated on Bash(cat *) while the executed command is always an echo, so it must never fire:

| command executed | markers written | verdict |
| --------------------------- | --------------------------------- | -------------------- |
| echo AAA plain text BBB | CMDONLY_POS | correct |
| echo AAA $HOME BBB | CMDONLY_POS | correct |
| echo AAA $(date) BBB | CMDONLY_NEG + CMDONLY_POS | unexpected |
| `echo AAA date BBB | CMDONLY_NEG + CMDONLY_POS` | unexpected |

Two notes that may help triage:

1. $VAR behaves better than documented. The docs list $VAR among the fail-open triggers, but $HOME discriminates correctly here (row 2). So runtime and docs diverge in both directions: stricter than documented on $VAR, looser on command-name-only + $().
2. This is not just the "best-effort" caveat. The docs' own table gives Bash(rm *) + echo $(date) as a no, so the caveat and the table contradict each other for this case. Either the table row or the implementation needs to change.

What Should Happen?

Per the documented matching table, a pattern naming only the command should discriminate even when the command contains a substitution:

Bash(cat *) must NOT fire on echo AAA $(date) BBB, because no subcommand matches cat *.

Fail-open should stay limited to the case the docs describe: patterns that specify more than the command name (e.g. Bash(git push *)).

If instead universal fail-open on $()/backticks is the intended behaviour regardless of pattern shape, then the fourth row of the table in the hooks reference is incorrect and should be fixed, and the docs should state plainly that any hook using if: "Bash(...)" must re-check tool_input.command inside the script itself.

Error Messages/Logs

markers.log after each run (the spy hook appends its tag)

# echo AAA plain text BBB
CMDONLY_POS

# echo AAA $HOME BBB
CMDONLY_POS

# echo AAA $(date) BBB
CMDONLY_NEG
CMDONLY_POS

# echo AAA `date` BBB
CMDONLY_NEG
CMDONLY_POS

Steps to Reproduce

1. In an empty sandbox folder, create ​.claude/spy.sh​:

#!/bin/bash
cat >/dev/null 2>&1
printf '%s\n' "$1" >> markers.log
exit 0

1. Create ​.claude/settings.json​ with two PostToolUse spy hooks. ​CMDONLY_NEG​ is the test: it names a command (​cat​) that the executed command never uses.

{
  "hooks": {
    "PostToolUse": [
      { "matcher": "Bash", "hooks": [ { "type": "command",
        "command": "bash .claude/spy.sh CMDONLY_NEG", "if": "Bash(cat *)" } ] },
      { "matcher": "Bash", "hooks": [ { "type": "command",
        "command": "bash .claude/spy.sh CMDONLY_POS", "if": "Bash(echo *)" } ] }
    ]
  }
}

1. For each of the four commands below: empty ​markers.log​, then have Claude Code run that command once, verbatim. Non-interactive form used here:

: > markers.log
claude -p --permission-mode bypassPermissions --allowedTools Bash \
  "Run exactly this Bash command once, verbatim: echo AAA $(date) BBB"

Commands to test:

echo AAA plain text BBB
echo AAA $HOME BBB
echo AAA $(date) BBB
echo AAA `date` BBB

1. Inspect ​markers.log​ after each run.

Expected: ​CMDONLY_NEG​ never appears.

Actual: ​CMDONLY_NEG​ appears for the ​$()​ and backtick cases. Deterministic across repeated runs.

Claude Model

None

Is this a regression?

No, this never worked

Last Working Version

_No response_

Claude Code Version

2.1.217 (Claude Code)

Platform

Anthropic API

Operating System

Windows

Terminal/Shell

VS Code integrated terminal

Additional Information

Environment: Windows 11; hooks in shell form are executed through Git Bash.

On the model field: left as None on purpose. The if matching happens in the harness before the hook runs, so the model is irrelevant to this behaviour. The matrix above was produced with fable[1m]; earlier runs of the same bench, covering the multi-token variants, used opus[1m] and matched bit-for-bit.

Context from the same test bench, in case it helps place this report: the bench has tracked two other if-field behaviours across roughly ten CLI versions —

• pipe alternation inside if (e.g. Bash(a *) | Bash(b *)) never matches; later documented as unsupported, with separate handlers as the supported form;
• forward-slash path patterns not matching Windows absolute paths — fixed in 2.1.176, issue #67610.

Practical impact: command substitution is very common in real commands, so a hook whose if matches nothing still runs on a large share of them. Every hook using if: "Bash(...)" therefore needs its own internal re-check of tool_input.command to avoid acting on unrelated commands. That requirement is not obvious from the current documentation, which presents the if field as a filter.