[DOCS] Hook if-condition documentation omits the changed scope of single-segment dir/** patterns

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

Tool-event hook handlers and the if field used to match a tool name and its arguments.

Current Documentation

The page currently says:

For tool events, you can filter more narrowly by setting the if field on individual hook handlers. if uses permission rule syntax to match against the tool name and arguments together, so “Bash(git )” runs when any subcommand of the Bash input matches git and “Edit(*.ts)” runs only for TypeScript files.

The page links to the general permission-rule syntax but does not explain any hook-specific directory-depth behavior for if conditions.

What's Wrong or Missing?

Claude Code 2.1.214 changes single-segment dir/ hook if conditions to match only <cwd>/dir. A pattern such as Edit(src/) therefore does not match an equivalent src directory at arbitrary depth. Users who intentionally need any-depth matching must write /dir/, while deny and ask permission rules retain their own any-depth behavior.

The current hook documentation only delegates to permission syntax and does not identify this distinction. A hook can therefore silently stop firing, or fire at a narrower scope than its author expects, after upgrading.

Suggested Improvement

Add a hook-specific note after the if-field explanation. For example:

~~~text
For hook if conditions, a single-segment directory pattern such as Edit(src/) is scoped to <cwd>/src. To match src directories at any depth, use Edit(/src/**). This hook if behavior is distinct from deny and ask permission rules, whose matching semantics are documented separately.
~~~

Add examples for a project-relative path, a nested path, and an explicit any-depth path, with a 2.1.214 minimum-version marker.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/hooks | if conditions for tool-event hook handlers |
| https://code.claude.com/docs/en/hooks-guide | Hook configuration and matching cross-reference |
| https://code.claude.com/docs/en/permissions | Related permission-pattern semantics |

Release: Claude Code 2.1.214.