Hooks & Scripts Conventions¶
Scoped via paths: frontmatter — loads only when a file under .claude/hooks/
or scripts/ is read or edited (see
code.claude.com/docs/en/memory),
never as part of the always-loaded rules layer. Content here is
hook/script-specific only; universal engineering rules live in
code-quality.md and security.md.
Shell Baseline¶
#!/usr/bin/env bash(or#!/bin/bashfor existing hooks) withset -u— fail loudly on an unset variable instead of silently expanding to empty.- Run
shellcheckandbash -nbefore committing; both are CI-enforced (framework-invariants.yml'sshellcheckjob over.claude/hooks/*.sh+scripts/*.sh;check-invariants.sh'shooks-validcheck runsbash -nover every shipped hook). - Keep each hook/script to roughly ≤120 lines and commented for adaptation — these are illustrative references an adopter edits for their own repo, not a framework to extend indefinitely in place.
Fail-Open, Visibly¶
Hooks are guardrails, not a security boundary — permissions.deny is the hard
boundary (security.md's Enforcement Ladder). The house idiom for an optional
dependency is a one-line early exit:
Guard early and exit 0 rather than let a missing optional tool fail the tool call the hook was meant to check — a broken guardrail must never become a broken workflow. Where the guarded behavior is more than incidental (an entire hook's checks are skipped, not just one branch), also emit a visible one-line degradation notice naming what's disabled — a hook that quietly does nothing hides the gap from the person who could act on it.
Extracting Fields Without jq¶
jq stays optional — no new runtime dependency. When it's unavailable,
extract a single field with a field-scoped sed capture; never match a raw
substring across the whole JSON payload, which both false-positives on
unrelated content and mis-parses escaped quotes. Reuse the existing idiom
(branch-pr-discipline.sh:48) rather than inventing a new one:
cmd="$(printf '%s' "$payload" | sed -n 's/.*"command"[[:space:]]*:[[:space:]]*"\(\([^"\\]\|\\.\)*\)".*/\1/p' | head -n1)"
Deny/Ask JSON Output Contract¶
A PreToolUse hook that wants to block or interrupt a tool call emits exactly
one JSON object on stdout:
echo "{\"hookSpecificOutput\": {\"hookEventName\": \"PreToolUse\", \"permissionDecision\": \"deny\", \"permissionDecisionReason\": \"<why>\"}}"
permissionDecision is "deny" (block outright) or "ask" (prompt the
user); write nothing to stdout to allow silently. Always include a
permissionDecisionReason — it's the only signal the person on the other end
of a denied or ask-gated call gets for why.