docs: add bash security hook example

[corvid-agent]

Summary

Adds a comprehensive bash command security analyzer as a PreToolUse hook example, plus a README for the examples/hooks/ directory.

The hook detects and blocks:

• Destructive operations — rm -rf, dd of=, mkfs, git push --force, git reset --hard, DROP TABLE
• Privilege escalation — sudo, su, doas, chmod 777, chmod +s, chown root
• Network exfiltration — curl | bash, wget | sh, nc -l, curl --data $VAR
• Credential exposure (warns) — cat .env, echo $API_KEY, printenv, history
• File-write bypass (warns) — sed -i, tee, python -c open(), perl -pie, ruby -e File.

Destructive/escalation/exfiltration patterns block (exit 2). Credential/bypass patterns warn (exit 0 with stderr). Configurable allowlist via BASH_SECURITY_HOOK_ALLOWLIST env var.

Why

The examples/hooks/ directory currently has a single example that redirects grep to rg. Community issues document real concerns about rm -rf executing without prompts (#29984), tool-switching circumvention where blocking Edit/Write causes Claude to use sed -i/tee via Bash instead (#29795), and requests for sudo/privilege watchers (#29275).

This hook addresses all of those patterns in a single, drop-in example.

Changes

• examples/hooks/bash_security_hook.py — new hook (165 lines)
• examples/hooks/README.md — documents both hook examples and exit code conventions

Test plan

• Run the hook against known-dangerous commands (rm -rf /, sudo apt install, curl | bash) — should block
• Run against safe commands (ls, git status, bun test) — should pass through
• Verify BASH_SECURITY_HOOK_ALLOWLIST=sudo allows sudo commands
• Verify no false positives on commands like grep "rm" logfile.txt

Relates to #29795, #29984, #29275, #29328

🤖 Generated with Claude Code