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

[coygeek]

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)

[meet-deshani]

I run 20+ Claude Code hooks in production and hit this exact gap. Here's a practical reference for anyone configuring if conditions:

What if: "Bash(git *)" actually matches (post v2.1.88)

Command	Matches?	Why
git status	✅ Yes	Direct git command
git push origin main	✅ Yes	Git with args
ls && git push	✅ Yes (v2.1.88+)	Compound — git subcommand parsed
FOO=bar git push	✅ Yes (v2.1.88+)	Env prefix stripped, git parsed
npm test	❌ No	Not a git command
echo "git push"	❌ No	git is in a string, not a command

Real-world hook patterns that depend on this

// Block --no-verify bypass (needs to catch "FOO=1 git commit --no-verify")
{
  "matcher": "Bash",
  "if": "Bash(git *)",
  "hooks": [{ "type": "command", "command": "npx block-no-verify" }]
}

// Pre-push review (needs to catch "cd repo && git push")
{
  "matcher": "Bash",
  "if": "Bash(git push*)",
  "hooks": [{ "type": "command", "command": "node scripts/pre-push-review.js" }]
}

Before v2.1.88, compound commands like ls && git push silently bypassed if filters — the hook never fired. This is a real security concern for guardrail hooks (like blocking --no-verify).

+1 for updating the docs. The "starts with git" wording is misleading. It should say "matches parsed git commands within the Bash invocation" with the compound/env-prefix examples.

[coygeek]

Issue Summary

This issue reports that the hooks if field documentation on two pages (hooks guide and hooks reference) describes Bash matching as simple prefix matching ("starts with git"), omitting that the if field also matches subcommands inside compound commands (ls && git push) and commands with temporary environment-variable prefixes (FOO=bar git push), which was fixed in v2.1.88.

Affected pages:

• https://code.claude.com/docs/en/hooks-guide (section: "Filter by tool name and arguments with the if field")
• https://code.claude.com/docs/en/hooks (hooks reference — if field description)

---

Verification Results

Claim 1: hooks-guide describes if as literal prefix matching ("starts with git") without mentioning compound or env-prefixed commands

Status: RESOLVED

Evidence: The hooks guide (hooks-guide.md) now reads:

The hook process only spawns when a subcommand of the Bash command matches git *, or when the command is too complex to parse into subcommands. For compound commands like npm test && git push, Claude Code evaluates each subcommand and fires the hook because git push matches.

— hooks-guide.md:691

The earlier "starts with git" phrasing has been replaced with "subcommand of the Bash command matches" language, with an explicit compound-command example.

Verdict: The guide now documents compound command matching.

Claim 2: hooks reference says "Bash(git *)" runs only for git commands, without compound-command or env-prefix examples

Status: RESOLVED

Evidence: The hooks reference (hooks.md) now includes:

"Bash(git *)" runs when any subcommand of the Bash input matches git * and "Edit(*.ts)" runs only for TypeScript files.

— hooks.md:233

And in the common fields table:

The hook only spawns if the tool call matches the pattern, or if a Bash command is too complex to parse.

— hooks.md:296

And in a dedicated paragraph:

For Bash, the rule is matched against each subcommand of the tool input after leading VAR=value assignments are stripped, so if: "Bash(git push *)" matches both FOO=bar git push and npm test && git push. The hook runs if any subcommand matches, and always runs when the command is too complex to parse.

— hooks.md:301

Verdict: Both env-prefix (FOO=bar git push) and compound (npm test && git push) examples are now explicitly documented.

Claim 3: No example table or note showing that if: "Bash(git *)" matches git status, ls && git push, FOO=bar git push, but not npm test

Status: RESOLVED

Evidence: While there is no dedicated table, the three matching scenarios are all explicitly covered:

• git * matching via subcommand evaluation — hooks.md:233, hooks-guide.md:691
• npm test && git push compound example — hooks-guide.md:691, hooks.md:301
• FOO=bar git push env-prefix example — hooks.md:301
• Non-match (npm test) — hooks.md:121

Verdict: All requested match/non-match examples are present in prose form across the two pages.

Claim 4: No note about this behavior being fixed in v2.1.88

Status: RESOLVED

Evidence: The hooks guide includes a version note:

The if field requires Claude Code v2.1.85 or later. Earlier versions ignore it and run the hook on every matched call.

— hooks-guide.md:665

While this notes v2.1.85 (when if was introduced), the v2.1.88 compound/env-prefix fix is documented in the changelog (changelog.md:706). The docs describe the current (fixed) behavior, so users reading the docs today see the correct matching semantics.

Verdict: Adequate — the docs describe the current behavior, and the version floor note prevents confusion with pre-if versions.

---

Current State

Page	Issue Raised	Current State
hooks-guide.md — if section	Said "starts with git", no compound/env-prefix mention	Now documents subcommand matching, compound commands (npm test && git push), and "too complex to parse" fallback
hooks.md — if field description	Said "runs only for git commands", no compound/env-prefix	Now documents subcommand matching, VAR=value stripping (FOO=bar git push), compound commands (npm test && git push), and "too complex to parse" fallback

---

Suggested Fix

No fix needed. The documentation has been updated to address all points raised in this issue.

---

References

• hooks-guide if section: https://code.claude.com/docs/en/hooks-guide (lines 662-693)
• hooks reference if field: https://code.claude.com/docs/en/hooks (lines 233, 296, 301)
• Changelog v2.1.88 entry: https://code.claude.com/docs/en/changelog (line 706)

---

Conclusion & Recommendation

Primary Concern: The hooks if field documentation previously described Bash matching as literal prefix matching, omitting compound-command and env-var-prefix support added in v2.1.88.

Resolution Status: RESOLVED — Both affected pages now describe if matching as parsed subcommand matching with explicit examples for compound commands (npm test && git push) and env-var prefixes (FOO=bar git push). The "too complex to parse" fallback is also documented.

Recommendation: Close as completed.

[github-actions]

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.