[DOCS] Hooks `if` docs omit compound and env-prefixed Bash matching

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/hooks-guide

Section/Topic

"Filter by tool name and arguments with the if field"

Current Documentation

The docs currently say:

The if field uses permission rule syntax to filter hooks by tool name and arguments together, so the hook process only spawns when the tool call matches. This goes beyond matcher, which filters at the group level by tool name only. ... The hook process only spawns when the Bash command starts with git. Other Bash commands skip this handler entirely.

The hooks reference also says:

if uses permission rule syntax to match against the tool name and arguments together, so "Bash(git *)" runs only for git commands and "Edit(*.ts)" runs only for TypeScript files.

There is no note here about compound Bash commands such as ls && git push or commands with temporary environment-variable prefixes such as FOO=bar git push.

What's Wrong or Missing?

The current wording reads like raw prefix matching: "starts with git" or "runs only for git commands." That no longer describes the full supported behavior.

Changelog v2.1.88 says:

Fixed hooks if condition filtering not matching compound commands (ls && git push) or commands with env-var prefixes (FOO=bar git push)

That means users configuring hook handlers like if: "Bash(git *)" now need to know that the filter can match parsed git subcommands inside compound Bash commands and commands prefixed by temporary environment variables. Without that note, it is hard to tell whether policy hooks will fire for common real-world commands such as ls && git push or FOO=bar git push.

Suggested Improvement

Update the hooks guide and hooks reference to describe Bash if matching as parsed command matching, not just a literal "command starts with" prefix check.

Add a small example table or note for if: "Bash(git *)" showing that it:

• matches git status
• matches ls && git push
• matches FOO=bar git push
• does not match npm test

It would also help to note that this behavior was fixed in v2.1.88, so older versions may behave differently.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/hooks-guide | if field walkthrough says the Bash command must "start with git" and does not mention compound or env-prefixed commands |
| https://code.claude.com/docs/en/hooks | Hooks reference says "Bash(git *)" runs only for git commands, again without compound-command or env-prefix examples |

Total scope: 2 pages affected

Source: Changelog v2.1.88

Exact changelog entry:

Fixed hooks if condition filtering not matching compound commands (ls && git push) or commands with env-var prefixes (FOO=bar git push)