Beyond Prompting: A Practical Guide to Claude Code Hooks for Safe AI Coding

Why Prompt Files Alone Aren’t Enough

Prompt files such as CLAUDE.md are soft constraints that influence the model’s reasoning but cannot guarantee enforcement at execution time. In long sessions the rules can be diluted, phrasing can be ambiguous, the model may trade‑off compliance for task completion, and there is no audit trail.

Claude Code Hooks Overview

UserPromptSubmit

– before the user submits a prompt (e.g., add context, block dangerous requests). PreToolUse – just before a tool is executed (e.g., rewrite parameters, require confirmation). PermissionRequest – when a permission is requested (e.g., auto allow/ask/deny based on project policy). PostToolUse – after a tool succeeds (e.g., record audit logs, collect metrics). TaskCompleted – when a task is marked complete (e.g., verify tests, lint, build artifacts). Stop – when Claude is about to finish a reply (e.g., decide whether the task truly finished). ConfigChange – when a configuration file changes (e.g., block unauthorized edits).

Minimal Viable Hooks: Intercept Three High‑Risk Actions

Block dangerous shell commands with a PreToolUse hook that runs a script detecting patterns such as rm -rf, git push --force, or chmod -R 777. The script exits with code 2, which Claude interprets as a block signal.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/block-dangerous-bash.sh"
          }
        ]
      }
    ]
  }
}

#!/bin/bash
input=$(cat)
command=$(echo "$input" | jq -r '.tool_input.command // ""')
if echo "$command" | grep -E 'rm -rf|git push --force|chmod -R 777' >/dev/null; then
  echo "Blocked: high‑risk shell command requires manual approval." >&2
  exit 2
fi
exit 0

Prevent premature completion by attaching Stop or TaskCompleted hooks that verify test output, build artifacts, or other definition‑of‑done criteria before allowing the assistant to claim success.

Guard configuration changes with a ConfigChange hook that audits or rejects modifications to files such as .claude/settings.json or other deployment‑critical configs.

Four‑Layer Hook Strategy

Audit – record events without blocking (e.g., log all Bash commands, permission requests, final replies).

Notify – detect risk and add contextual reminders but do not stop execution.

Intercept – actively block dangerous actions (e.g., forbid rm -rf, require test passing before marking a task complete).

Accept – enforce a full “definition of done” checklist before allowing the task to finish.

Combining Hooks with Subagents

Hooks decide *when* to trigger; subagents decide *who* performs the work. Typical combinations include: PreToolUse – quick script check. PostToolUse – log or run lightweight checks. Stop – keep the assistant in the loop if criteria are unmet. SubagentStart / SubagentStop – launch a dedicated agent for code review, security audit, or test verification.

The recommended pattern is deterministic command‑based rules first, with model judgment as a fallback.

Adoption Roadmap for a Small Team

Week 1 – enable audit hooks in .claude/settings.json to observe tool usage.

Week 2 – add three hard gates: block dangerous Bash, block unauthorized config edits, block unverified Stop events.

Week 3 – migrate high‑impact rules from documentation into hooks.

Week 4 – experiment with prompt or agent hooks for specialized tasks (e.g., diff review, API doc sync).

Limitations and Pitfalls

Hooks increase complexity and can make Claude’s behavior harder to trace.

Parallel hooks run independently; a deny in one does not cancel side‑effects from another. PostToolUse cannot undo actions – place blocking logic in PreToolUse whenever possible.

HTTP hooks must return the proper JSON decision, not just a non‑2xx status. Stop hooks can loop; guard against repeated blocking with stop_hook_active.

Auto Mode Permission Gate – Empirical Findings

A 2026 paper measuring Claude Code Auto Mode reports a false‑positive rate of 0.4 % and a false‑negative rate of 17 % for permission checks. This demonstrates that the built‑in classifier is probabilistic and cannot replace project‑specific policy enforcement.

Hooks Maturity Layers in Detail

Audit

Record events (e.g., log every Bash command, send permission requests to Slack, store final replies) to gain visibility before adding enforcement.

Notify

Detect risky actions and inject contextual reminders (e.g., when modifying migrations/, add a note that migration tests must run).

Intercept

Block actions such as: rm -rf must be blocked. git push --force must be blocked.

Tasks cannot be marked complete without passing tests.

Unauthorized changes to deployment configuration must be blocked.

Accept (Definition of Done)

Automate checks for test success, lint passing, generated files updated, documentation synced, PR description containing risk notes, UI screenshots, etc. Start with the most frequently failing gate rather than trying to cover every possible check.

Team Rollout Template

Week 1 – audit only: add logging hooks for Bash, file edits, and Stop events in .claude/settings.json and observe patterns.

Week 2 – hard gates: implement the three minimal hooks (dangerous Bash, config change, unverified Stop).

Week 3 – migrate documented team policies that have high cost when violated into hook rules.

Week 4 – optional prompt/agent hooks for specialized checks (e.g., a review agent that runs diff analysis before task completion).

Complexity Warning

Hooks can appear from multiple scopes (global, project, local, plugins); use /hooks to inspect the effective configuration.

Parallel hooks may log before a block occurs, leaving side‑effects recorded. PostToolUse cannot revert actions; place blocking logic in PreToolUse.

HTTP hooks must return the documented JSON decision format, not merely a non‑2xx HTTP status.

Repeated Stop blocks can cause loops; check stop_hook_active to avoid infinite retries.

Each hook should have a clear trigger, responsibility, and failure behavior.

References:

Claude Code Hooks Reference – https://code.claude.com/docs/en/hooks

Hooks Guide – https://code.claude.com/docs/en/hooks-guide

"Measuring the Permission Gate" – https://arxiv.org/abs/2604.04978

Claude Code Subagents Documentation – https://code.claude.com/docs/en/sub-agents

"Dive into Claude Code" – https://arxiv.org/abs/2604.14228

"Configuring Agentic AI Coding Tools" – https://arxiv.org/abs/2602.14690