[FEATURE] Add PostToolUseError hook for failed tool executions

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Currently, PostToolUse hooks only fire when a tool completes successfully. There is no hook that fires when a tool fails (non-zero exit code for Bash, errors for other tools).

This makes it impossible to:

• Inject helpful context into Claude when a command fails
• Log or track tool failures
• Trigger notifications on errors
• Provide Claude with debugging guidance when things go wrong

Proposed Solution

Add a new hook event PostToolUseError (or similar) that fires when a tool execution fails:

{
  "hooks": {
    "PostToolUseError": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "my-error-handler"
          }
        ]
      }
    ]
  }
}

The hook input would include:

• tool_name: Which tool failed
• tool_input: The original input
• exit_code: For Bash, the exit code
• error_output: stderr or error message
• Standard fields: session_id, cwd, etc.

The hook output would support additionalContext to inject information into Claude's context about the failure.

Alternative Solutions

1. Make PostToolUse fire on failure too - Could work with a config flag, but might break existing hooks that assume success
2. Single PostToolUse with success/failure indicator - Add tool_success: boolean to input, let hooks decide what to do

Priority

Medium - Enables error handling patterns

Feature Category

Hooks

Use Case Example

First-use documentation on error:

# User runs invalid command
$ mytool badcommand
Error: No such command 'badcommand'.

# PostToolUseError hook fires, injects mytool docs
# Claude now has context to suggest correct usage

Error notification:

# Build fails
$ npm run build
# Error...

# PostToolUseError hook sends notification
# User gets alerted even if away from terminal

Failure logging:

# Any tool failure gets logged for later analysis
# Hook appends to ~/.claude/tool-failures.log

Additional Context

The current hook events are:

• PreToolUse - before tool runs
• PostToolUse - after tool succeeds
• Notification - Claude wants attention
• Stop - session ends

Adding PostToolUseError would complete the tool lifecycle coverage.