[DOCS] Missing `PostToolUseFailure` event definition in Hooks reference

Documentation Type

Unclear/confusing documentation

Documentation Location

• https://code.claude.com/docs/en/plugins-reference#hooks * https://code.claude.com/docs/en/hooks#hook-events

Section/Topic

The "Hook Events" and "Hook Input" sections of the Hooks reference.

Current Documentation

In the Plugins Reference page (https://code.claude.com/docs/en/plugins-reference#hooks), the documentation lists PostToolUseFailure as an available event:

Available events: PreToolUse: Before Claude uses any tool PostToolUse: After Claude successfully uses any tool * PostToolUseFailure: After Claude tool execution fails ...

However, in the primary Hooks Reference page (https://code.claude.com/docs/en/hooks#hook-events), this event is entirely absent from the list of events and the detailed input schema sections.

What's Wrong or Missing?

The PostToolUseFailure event is mentioned as an available hook for plugins, but it is not documented in the main hooks guide. Specifically:

1. Timing: There is no explanation of exactly when this fires relative to the model's retry logic.
2. Input Schema: There is no JSON schema provided for what is sent to stdin for this event. Developers need to know if it receives the tool_input plus an error field or a tool_response with a failure status.
3. Consistency: The main Hooks documentation should be the source of truth for all events supported by the CLI.

Suggested Improvement

Add a PostToolUseFailure section to the Hook Events list in https://code.claude.com/docs/en/hooks.

Suggested Text for Event Description:

PostToolUseFailure: Runs immediately after a tool call fails to execute (e.g., a Bash command returns a non-zero exit code or a file read fails). This allows for automated error logging or custom recovery logic.

Suggested Text for Hook Input:
Define the input schema, for example:

{
  "session_id": "abc123",
  "hook_event_name": "PostToolUseFailure",
  "tool_name": "Bash",
  "tool_input": {
    "command": "invalid-command"
  },
  "error": "Command 'invalid-command' not found",
  "exit_code": 127
}

Impact

High - Prevents users from using a feature

Additional Context

• This issue causes friction for plugin developers who see the event listed in the "Plugin components reference" but cannot find the technical details required to implement a handler for it in the main "Hooks reference."
• Related documentation: https://code.claude.com/docs/en/hooks-guide