Claude Code hooks can run deterministic logic at lifecycle and tool events. Because hooks execute code automatically, a repository hook is part of the trusted software supply chain. Review it before accepting workspace trust.
Choose Guardrail, Feedback, or Audit
- Guardrail: block a forbidden command/path before execution.
- Feedback: run a targeted formatter or validator after a change.
- Audit: record a minimal structured event.
Hooks should be fast, deterministic, bounded, and fail in a documented direction. Do not send repository contents to an external endpoint without explicit authorization.
Build Safely
Parse structured hook input rather than interpolating it into a shell string. Resolve paths to an approved root. Use timeouts. Redact secrets. Pin helper dependencies. Make messages actionable.
if requested file resolves outside repo → block
if path is generated/** → block and name generator command
if edited file matches src/**/*.ts → run targeted formatter
Avoid running the full build after every tiny tool action; use staged checks and preserve the final full gate.
Worked Example
A Karachi fintech sample repo adds a pre-tool hook that blocks edits to migrations and .env*, plus a post-edit hook that runs a TypeScript formatter on changed source files. The pre-tool check resolves canonical paths and cannot be bypassed with ../.
The team tests allowed edit, forbidden file, path traversal, timeout, malformed input, and missing formatter. A separate CI build remains authoritative.
Failure Cases to Diagnose
- Hook concatenates untrusted command text: parse and allowlist.
- Repository hook accepted blindly: inspect before trust.
- Hook contains a secret: use managed environment and rotate exposure.
- Network upload is hidden telemetry: remove or obtain authority.
- Every edit triggers long tests: scope fast feedback.
- Failure silently ignored: define block/warn behavior.
Operator Note
Version hooks alongside the repository and require ordinary code review. Record which event invokes each hook, its maximum runtime, exit-code meaning, and owner. A break-glass disable mechanism should be documented, but disabling a security hook must be visible and temporary. When a hook changes, rerun its abuse tests before trusting the workspace again.
🇵🇰 Pakistan Angle
Do not upload Pakistani customer, banking, CNIC, payroll, or health data through a hook. Client repositories may contain sensitive fixtures; treat automated scanners and SaaS endpoints as third-party processors requiring approval.
On unstable networks, local deterministic checks should fail clearly, not retry forever. Keep the final build reproducible offline where feasible.
Hands-On Exercise
- Define one guardrail and one feedback hook.
- Parse structured input and resolve paths safely.
- Add timeout, redaction, and clear exit behavior.
- Test traversal, malformed input, and missing dependency.
- Document trust and disable procedure.
Completion Rubric
- Hook has one deterministic purpose.
- Input is parsed, not shell-concatenated.
- Paths and destinations are allowlisted.
- Runtime and retries are bounded.
- Sensitive data is not exported.
- CI/final gates remain authoritative.
Sources
Key takeaway: hooks are executable policy; keep them deterministic, reviewed, path-safe, data-minimal, and fast.