Build Production Claude Code Hooks for Formatting, Policy, Audit, and Verification

Quick answer

Use hooks for small, deterministic controls: format only the edited file, block known-dangerous command classes before execution, require a bounded verification script before stopping, and record sanitized audit facts after sensitive tools. Do not turn hooks into an invisible orchestration platform. Keep policy in version control, test every decision path, and provide a documented escape/diagnostic procedure. Follow Anthropic's hook guide and reference for exact schemas.

Recipe 1: format the edited file

A PostToolUse hook can extract the changed path and run the repository formatter only when the extension and location are supported. Requirements:

• resolve against CLAUDE_PROJECT_DIR;
• reject paths outside the repo and generated/vendor trees;
• choose the existing formatter, not install a new one;
• avoid changing unrelated files;
• return quickly;
• report formatter failure clearly.

After formatting, Claude should inspect the resulting diff because a formatter can reveal syntax damage or produce a larger-than-expected change.

Recipe 2: gate dangerous commands

Use a PreToolUse hook for organization-specific policies that permission patterns cannot express safely. Parse the structured command and classify operations such as production deploys, force pushes, destructive database commands, credential access, and unapproved network destinations.

Do not rely on naive substring tests:

BAD: command.includes("prod")
BETTER: parse known CLI structure, resolve environment/account, deny unknown forms,
and keep a narrow explicit allowlist for read-only inspection.

Shell parsing is difficult. Prefer removing dangerous tools or credentials entirely to building a perfect parser.

Recipe 3: completion verification

A Stop hook can run a fast, deterministic check and block premature completion. Keep it bounded—perhaps focused tests or a task-specific verification script, not a 45-minute suite after every turn. Prevent infinite loops and respect Claude Code's documented stop-hook safeguards.

The check should distinguish:

• pass: completion may proceed;
• fail: give concise actionable output;
• infrastructure error: report inability to verify rather than pretending the code failed;
• not applicable: exit successfully without noise.

Recipe 4: sanitized audit trail

For sensitive tool categories, append an event timestamp, session identifier, canonical tool name, policy outcome, and non-secret target category. Never log full prompts, authorization headers, environment values, file content, or MCP payloads by default. Protect the audit destination from tampering and define retention.

Audit is evidence, not prevention. Pair it with deny/ask rules and sandbox controls.

Avoid recursive and conflicting automation

A formatter hook that edits a file may retrigger edit hooks. Use event semantics and a reentrancy marker where appropriate. Two formatters can oscillate. A stop hook can repeatedly block because its own generated files remain dirty. Test the entire chain, document order, and keep each hook single-purpose.

Production rollout checklist

1. Unit-test fixture inputs and outputs.
2. Integration-test in a disposable repository.
3. Measure median and worst-case latency.
4. Test missing dependencies and timeouts.
5. Review secrets and log data.
6. Roll out to a small group.
7. Publish troubleshooting and disable instructions.
8. Monitor false blocks and bypass attempts.

FAQ

Should a hook automatically fix every failed check?

No. Hooks should produce deterministic signals; Claude can reason about the repair in the normal agent loop.

Can hooks replace CI?

No. Local hooks improve feedback and policy, while CI provides an independent, reproducible gate.

What should happen if a policy hook crashes?

For high-risk actions, design a documented fail-closed behavior where supported. For low-risk formatting, fail visibly without corrupting the edit.