CONCEPT Hooks run arbitrary shell — automatically, as you
This is the single most important fact about hooks: they execute arbitrary shell commands on your system automatically, with your user privileges, without asking for confirmation each time. A hook can read files, hit the network, delete data, or exfiltrate secrets. The official docs frame this as "USE AT YOUR OWN RISK": by configuring hooks you accept responsibility for what they do, and Anthropic is not liable for damage from a misconfigured hook.
command lands in a settings file you
trust, it runs the next time its event fires — silently..claude/settings.json is executable code, not just config.CONCEPT Best practices before you deploy one
- Review the command — read exactly what each hook runs before adding it, especially hooks that arrived via a cloned repo or plugin.
- Validate and sanitize input — the JSON on stdin is model/tool-influenced. Don't
evalit or interpolate it into a shell command unquoted. - Always quote shell variables — write
"$VAR", not$VAR, so a path with spaces or metacharacters can't break out of the command. - Block path traversal — reject inputs containing
..before touching a file path. - Use absolute paths — reference scripts with
"$CLAUDE_PROJECT_DIR"/…or a full path so the hook doesn't run a stray binary from the working directory. - Skip sensitive files — have hooks avoid reading or writing
.env,.git/, keys, and credentials.
DIAGRAM Trust boundary of a hook
it runs as YOU, no prompt"] Q -->|"yes — reviewed"| RUN["Event fires → command runs
your privileges, automatically"] RUN --> SAFE["✅ Quote vars · validate input
absolute paths · block traversal"] REV -.->|"only after review"| RUN classDef ok fill:#d4edda,stroke:#28a745,color:#155724; classDef gate fill:#ffe8cc,stroke:#ff9f40,color:#9a4a0a; classDef bad fill:#f8d7da,stroke:#dc3545,color:#721c24; class SAFE ok; class RUN gate; class REV bad;
CODE Defensive vs. dangerous
The same guard hook — written unsafely, then safely. The unsafe version interpolates untrusted input straight into a command; the safe version quotes, validates, and rejects traversal.
# ❌ DANGEROUS — unquoted, no validation, injectable INPUT=$(cat) FILE=$(echo $INPUT | jq -r .tool_input.file_path) rm $FILE # spaces / ; / $() all break out # ✅ DEFENSIVE — quote, validate, block traversal INPUT=$(cat) FILE=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty') case "$FILE" in *..*|"") echo "Rejected suspicious path" >&2; exit 2 ;; esac if [[ "$FILE" == *".env"* ]]; then echo "Refusing to touch secrets file" >&2; exit 2 fi
TRADE-OFFS Convenience vs. exposure
✅ Well-reviewed, tightly-scoped hooks
- Deterministic guarantees you control
- Narrow matchers + input validation limit blast radius
- Committed to the repo, so the whole team can audit them
⚠️ Broad, unreviewed, or third-party hooks
- Run silently with your full privileges
- Unquoted input is a shell-injection vector
- A trusted-looking settings file can hide a payload
EXAM TRAPS
settings.json hook is executable code. Review it before working in the repo..tool_input into a shell command unquoted. → That's
a shell-injection hole. Always quote variables and validate/sanitize input.PRACTICE
Q1 · Why are hooks riskier than a normal tool call?
A tool call is mediated by the permission system and can prompt you. A hook runs arbitrary shell automatically with your privileges and no runtime prompt — so a bad hook executes silently.
Q2 · Name three concrete hardening steps for a hook script.
Quote all shell variables ("$VAR"); validate/sanitize the stdin JSON and reject
path traversal (..); use absolute paths and skip sensitive files like .env and
.git/.
Q3 · You clone a repo with a .claude/settings.json full of hooks. First move?
Read them before running anything. Those hooks are executable code that will run as you when their events fire. Never trust hook config from an untrusted source unreviewed.