Catch What Claude Just Changed: A PostToolUse Hook That Validates Every File in Your Session

A PostToolUse hook in .claude/settings.json runs your validator after every Write or Edit call. Claude sees the output, understands if something broke, and fixes it — without you prompting again.

Claude Code's hook system lets you intercept every tool call. PostToolUse fires after a tool succeeds. It is different from a pre-commit check: it runs in the middle of a session, while Claude still has context, can still fix the problem, and hasn't moved on to the next task.

The minimal pattern — 12 lines

In .claude/settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/validate-edit.sh"
          }
        ]
      }
    ]
  }
}

In .claude/hooks/validate-edit.sh:

#!/bin/bash
FILE=$(jq -r '.file_path // empty' -)
[[ -z "$FILE" ]] && exit 0
pnpm eslint --quiet "$FILE" 2>&1 | head -30

Exit codes determine what Claude does next:

• Exit 0 — nothing; Claude continues.
• Exit 1 — Claude sees the output and attempts to fix the error before continuing.
• Exit 2 — Claude stops and asks you before doing anything else.

What to validate:

• pnpm eslint --quiet "$FILE" — catch lint before the conversation ends.
• pnpm tsc --noEmit — surface type errors immediately instead of at build time.
• jq empty on any JSON file — structural validation; a corrupted JSON write is caught before it propagates.
• A custom schema check — this blog's .claude/hooks/validate-blog.sh runs after every write to public/blog/ and blocks commits if posts.json is inconsistent. That is PostToolUse in production.

What to watch out for:

Hook commands inherit the session's environment, not a login shell. If your validator requires PATH entries that only exist in a login shell (e.g., nvm-managed node, Homebrew tools), add export PATH=... at the top of the hook script.

The one gap: hooks run in interactive sessions and the main loop. They do not fire inside Workflow SDK subagents. If your validation is critical in a multi-agent workflow, add it as an explicit agent() step after the write agent, not as a hook.

Sources: Automate actions with hooks — Claude Code Docs · Hooks reference — Claude Code Docs · Intercept and control agent behavior — Claude Code SDK Docs