PostToolUse Patterns — Format, Validate, Notify
PostToolUse fires after a tool completes. You can't undo what happened, but you can auto-format, run tests, validate output, and notify — all before Claude's next action. These patterns enforce standards without requiring Claude's cooperation.
Quick Reference
- →PostToolUse fires after every tool completes — cannot undo the action
- →Exit 2 from PostToolUse causes Claude to stop and see your output as an error
- →$CLAUDE_FILE_PATH env var: the file path for Edit/Write/Read tool calls
- →Auto-format pattern: run prettier/eslint --fix/gofmt on file after every edit
- →Test pattern: run the relevant test file after editing the source file
- →Validation pattern: exit 2 with a message if output doesn't meet criteria
- →Notification pattern: send macOS notification or Slack webhook when Claude stops
- →PostToolUseFailure: fires when a tool fails — use for cleanup and logging
What PostToolUse Does — and Doesn't Do
PostToolUse fires after a tool call completes successfully. At this point, the action has already happened — the file was edited, the command ran, the MCP tool returned. PostToolUse can't undo any of it.
What it can do is influence what happens next. If your PostToolUse hook exits 2, Claude sees your hook's output as an error message and stops its current action. It reads your message and can decide how to proceed. This is the mechanism for using PostToolUse as a gate: not blocking the action itself, but blocking Claude from continuing if the action's result doesn't meet your criteria.
PostToolUse fires after each individual tool call. Stop fires when Claude finishes an entire turn response. For per-action automation (format this file), use PostToolUse. For end-of-turn actions (run the full test suite, send a notification), use Stop.