[DOCS] [Hooks] Command hook `args` field (exec form) not documented in hooks reference

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

"Command hook fields" section — the table describing command, async, asyncRewake, and shell fields.

Current Documentation

The Command hook fields table lists:

| Field | Required | Description |
| :------------ | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| command | yes | Shell command to execute |
| async | no | If true, runs in the background without blocking. See [Run hooks in the background](#run-hooks-in-the-background) |
| asyncRewake | no | If true, runs in the background and wakes Claude on exit code 2. Implies async. The hook's stderr, or stdout if stderr is empty, is shown to Claude as a system reminder so it can react to a long-running background failure |
| shell | no | Shell to use for this hook. Accepts "bash" (default) or "powershell". Setting "powershell" runs the command via PowerShell on Windows. Does not require CLAUDE_CODE_USE_POWERSHELL_TOOL since hooks spawn PowerShell directly |

The table makes no mention of an args field.

What's Wrong or Missing?

A. Missing args field (exec form)

The changelog for v2.1.139 describes a new hook feature:

Added hook args: string[] field (exec form) that spawns the command directly without a shell, so path placeholders never need quoting

This args field is not documented in the Command hook fields table. Users reading the hooks reference would have no way to discover this feature.

B. Behavioral difference is significant

When args is provided, the hook spawns the command directly (without shell interpretation), meaning:

• Path placeholders like $CLAUDE_PROJECT_DIR do not need quoting
• Shell metacharacters (*, ?, |, etc.) in arguments are not processed by a shell
• The behavior differs fundamentally from the command string form, which is passed to a shell

This distinction matters for users writing hook commands that include file paths with spaces or special characters.

Suggested Improvement

Add an args row to the Command hook fields table:

| Field | Required | Description |
| :------------ | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| args | no | Array of strings. When provided, the command is spawned directly without a shell (exec form), so path placeholders like $CLAUDE_PROJECT_DIR never need quoting. Use instead of command when you need precise argument handling without shell interpretation |

Also note the behavioral difference under the command field description: when command is a single string, it is interpreted by a shell; when args is provided alongside command, the command is spawned directly.

Impact

High - Prevents users from discovering a feature

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/hooks | Command hook fields table - missing args field documentation |

Version: v2.1.139 introduced this feature.

Changelog entry:

Added hook args: string[] field (exec form) that spawns the command directly without a shell, so path placeholders never need quoting