Summary

Hooks invoked by Claude Code run in an environment whose PATH does not include /opt/homebrew/bin. Hook scripts that rely on Homebrew installed binaries (the default install location on Apple Silicon macOS) silently fail because command -v <tool> returns nothing, even though the binary is on the user's interactive shell PATH.

Reproduction

A third party project (rtk) documented this with a minimal reproduction at rtk-ai/rtk#685:

Claude Code runs hooks with a restricted PATH that does not include /opt/homebrew/bin. The hook does: if ! command -v rtk &>/dev/null; then exit 0 # silent failure, no rewrite happens

The pattern command -v <tool> &>/dev/null || exit 0 is a common hook idiom for graceful degradation. When PATH excludes /opt/homebrew/bin, every Homebrew installed tool triggers the early exit, and the hook appears to run successfully (exit 0) while actually doing nothing.

Expected behavior

Hooks should inherit a PATH that includes the user's interactive shell PATH, or at minimum the default Homebrew prefixes (/opt/homebrew/bin on Apple Silicon, /usr/local/bin on Intel).

Actual behavior

/opt/homebrew/bin is stripped from PATH in the hook runtime environment. Hook authors must either hardcode absolute paths (/opt/homebrew/bin/tool) or re export PATH inside the hook script, neither of which is documented as necessary.

Why existing issues do not cover this

• Desktop app ignores settings.json env block and shell profile PATH on macOS #43210 is about the Desktop app ignoring settings.json env and shell profile PATH. Different scope (Desktop, not CLI hooks).
• Desktop app (macOS) ignores PATH from all sources — Read tool cannot find poppler/pdftoppm #42248 is about the Read tool on Desktop app failing to find poppler/pdftoppm. Different tool and scope.
• Shell snapshot PATH export contains literal $PATH — system directories lost #31799 describes shell snapshot PATH containing literal \$PATH. Different mechanism.
• bug: installer places binary in ~/.local/bin but shell snapshot drops it from PATH, causing spurious startup warning #43127 is about installer placement. Not hook runtime PATH.
• Desktop app shell snapshot writes process.env.PATH instead of resolved shell PATH #43800 (closed) is about Desktop app shell snapshot behavior. Different scope.

Request

1. Document the hook runtime PATH explicitly.
2. Either include common binary prefixes (/opt/homebrew/bin, /usr/local/bin) by default, or provide a settings.json option to inherit the interactive shell PATH for hooks.

Suggested labels: bug, area:hooks, platform:macos