PostToolUseFailure Hook

PostToolUseFailure

PostToolUseFailure is triggered when a tool execution fails. This event is triggered when a tool call throws an error or returns a failure result. Can be used to log failures, send alerts, or provide corrective feedback to Hawa Code.

Matching method: Match by tool name, supports the same matcher values as PreToolUse.

Input Parameters

PostToolUseFailure hooks receive the same tool_name and tool_input fields as PostToolUse, along with error information as top-level fields:

Field Description
tool_name Tool name
tool_input Parameters sent to the tool
tool_use_id Unique identifier for the tool use
error String describing the error cause
is_interrupt Optional boolean indicating if the failure was caused by user interruption

Input Example

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.hcode/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "PostToolUseFailure",
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test",
    "description": "Run test suite"
  },
  "tool_use_id": "toolu_01ABC123...",
  "error": "Command exited with non-zero status code 1",
  "is_interrupt": false
}

Output Parameters / Decision Control

PostToolUseFailure hooks can provide context to Hawa Code after a tool failure. In addition to the common JSON output fields for all hooks, the following event-specific fields can be returned:

Field Description
additionalContext Additional context for Hawa Code to consider, provided along with the error message

Output Example

{
  "hookSpecificOutput": {
    "hookEventName": "PostToolUseFailure",
    "additionalContext": "Additional information about the failure"
  }
}

Exit Code Behavior

Exit Code Behavior
0 Success, parse JSON response from stdout
Non-zero Failure, hook output is ignored
Next