PostToolUseFailure Hook - Claude Code

PostToolUseFailure fires when a tool call fails - nonzero exit, exception, timeout. It's your hook for alerting, retry logic, and failure-specific telemetry.

What it does

The hook receives the tool, arguments, and error details. It can log the failure, send an alert, advise Claude on how to proceed, or even suggest an alternative approach. It runs in the failure path only, so you can keep logic focused on the unhappy case.

When to use it

• Sending pager alerts when deploy tools fail.
• Auto-logging to Sentry or a similar backend.
• Injecting helpful context when a common failure happens ("run pnpm install first").
• Counting failures per tool for diagnostic dashboards.

Gotchas

• Don't spam alerts for expected failures (test assertions, known flaky commands).
• Injecting advice can loop Claude back into the same failure. Include a max-retry check.
• Failure details may contain sensitive output. Scrub before sending to external systems.

Official docs: https://code.claude.com/docs/en/hooks.md#posttoolusefailure