Hook scripts break BASH_ENV on macOS: hardcoded #!/bin/bash forces bash 3.2

[ulisesbocchio]

Summary

All hook scripts use #!/bin/bash as their shebang. On macOS, /bin/bash is permanently pinned to bash 3.2.57 (Apple won't ship newer versions due to GPLv3 licensing). Users who install a modern bash (4.x/5.x) via Homebrew or similar have their $PATH configured to use the newer version, but the hardcoded shebang bypasses $PATH entirely.

When bash runs a script (non-interactive shell), it sources $BASH_ENV if set. Because the hooks force /bin/bash 3.2, $BASH_ENV gets sourced under bash 3.2 instead of the user's expected bash version. Any bash 4+ or 5+ features in the $BASH_ENV target file will fail or behave unexpectedly.

How it breaks

1. User has bash 5.x installed (e.g. /opt/homebrew/bin/bash) and $PATH prioritizes it
2. User has $BASH_ENV set, pointing to a file that uses modern bash features
3. Claude Code hook fires → kernel sees #!/bin/bash → launches /bin/bash (3.2.57)
4. Bash 3.2 inherits the environment, sees $BASH_ENV, and sources the file
5. Modern bash features fail under 3.2 (associative arrays, ${var,,}, |&, readarray, declare -g, etc.)

Reproduction

# Confirm macOS system bash version
/bin/bash --version
# GNU bash, version 3.2.57(1)-release (arm64-apple-darwin...)

# Confirm user's actual bash
bash --version
# GNU bash, version 5.2.37(1)-release ...

# If BASH_ENV is set and its target uses any bash 4+ feature,
# hook scripts will error or produce unexpected behavior
echo $BASH_ENV

Affected files

All .sh scripts under plugins/warp/scripts/ and plugins/warp/scripts/legacy/:

• on-post-tool-use.sh
• on-session-start.sh
• on-prompt-submit.sh
• on-stop.sh
• on-permission-request.sh
• on-notification.sh
• build-payload.sh
• emit-terminal-sequence.sh
• should-use-structured.sh
• warp-notify.sh
• legacy/on-session-start.sh
• legacy/on-stop.sh
• legacy/on-notification.sh
• legacy/warp-notify.sh

Fix

Replace #!/bin/bash with #!/usr/bin/env bash in all scripts:

find plugins/warp/scripts/ -name "*.sh" -exec sed -i '' 's|^#!/bin/bash|#!/usr/bin/env bash|' {} +

This ensures the user's $PATH-resolved bash is used, so $BASH_ENV is sourced by the correct version.

Related

• Hook scripts fail on NixOS: hardcoded #!/bin/bash shebang not found #60 — Same root cause (hardcoded shebang), different manifestation (NixOS has no /bin/bash at all)

Environment

• OS: macOS (Apple Silicon)
• /bin/bash: 3.2.57
• User's bash: 5.2.37 (Homebrew)
• Claude Code: latest
• Plugin: claude-code-warp latest