feat: add PostToolUseFailure hook event type (#535)

## Summary
- Add `PostToolUseFailureHookInput` type with fields for `tool_name`,
`tool_input`, `tool_use_id`, `error`, and optional `is_interrupt`
- Add `PostToolUseFailureHookSpecificOutput` type with
`additionalContext` field
- Add `"PostToolUseFailure"` to `HookEvent`, `HookInput`, and
`HookSpecificOutput` union types
- Export new types from `__init__.py` and add to `__all__`

## Test plan
- [ ] Verify `PostToolUseFailureHookInput` can be constructed with
required and optional fields
- [ ] Verify `PostToolUseFailureHookSpecificOutput` accepts valid output
shapes
- [ ] Verify type checking passes with `mypy`
- [ ] Verify existing tests still pass

## Changelog
<!-- CHANGELOG:START -->
Added `PostToolUseFailure` hook event type for handling tool use
failures, including `PostToolUseFailureHookInput` and
`PostToolUseFailureHookSpecificOutput` types.
<!-- CHANGELOG:END -->

🤖 Generated with [Claude Code](https://claude.com/claude-code) (0%
4-shotted by claude)

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: ashwin-ant

src/claude_agent_sdk/__init__.py

@@ -35,6 +35,8 @@
     PermissionResultAllow,
     PermissionResultDeny,
     PermissionUpdate,
+    PostToolUseFailureHookInput,
+    PostToolUseFailureHookSpecificOutput,
     PostToolUseHookInput,
     PreCompactHookInput,
     PreToolUseHookInput,
@@ -335,6 +337,8 @@ async def call_tool(name: str, arguments: dict[str, Any]) -> Any:
     "BaseHookInput",
     "PreToolUseHookInput",
     "PostToolUseHookInput",
+    "PostToolUseFailureHookInput",
+    "PostToolUseFailureHookSpecificOutput",
     "UserPromptSubmitHookInput",
     "StopHookInput",
     "SubagentStopHookInput",

src/claude_agent_sdk/types.py

@@ -163,6 +163,7 @@ class PermissionResultDeny:
 HookEvent = (
     Literal["PreToolUse"]
     | Literal["PostToolUse"]
+    | Literal["PostToolUseFailure"]
     | Literal["UserPromptSubmit"]
     | Literal["Stop"]
     | Literal["SubagentStop"]
@@ -197,6 +198,17 @@ class PostToolUseHookInput(BaseHookInput):
     tool_response: Any
 
 
+class PostToolUseFailureHookInput(BaseHookInput):
+    """Input data for PostToolUseFailure hook events."""
+
+    hook_event_name: Literal["PostToolUseFailure"]
+    tool_name: str
+    tool_input: dict[str, Any]
+    tool_use_id: str
+    error: str
+    is_interrupt: NotRequired[bool]
+
+
 class UserPromptSubmitHookInput(BaseHookInput):
     """Input data for UserPromptSubmit hook events."""
 
@@ -230,6 +242,7 @@ class PreCompactHookInput(BaseHookInput):
 HookInput = (
     PreToolUseHookInput
     | PostToolUseHookInput
+    | PostToolUseFailureHookInput
     | UserPromptSubmitHookInput
     | StopHookInput
     | SubagentStopHookInput
@@ -254,6 +267,13 @@ class PostToolUseHookSpecificOutput(TypedDict):
     additionalContext: NotRequired[str]
 
 
+class PostToolUseFailureHookSpecificOutput(TypedDict):
+    """Hook-specific output for PostToolUseFailure events."""
+
+    hookEventName: Literal["PostToolUseFailure"]
+    additionalContext: NotRequired[str]
+
+
 class UserPromptSubmitHookSpecificOutput(TypedDict):
     """Hook-specific output for UserPromptSubmit events."""
 
@@ -271,6 +291,7 @@ class SessionStartHookSpecificOutput(TypedDict):
 HookSpecificOutput = (
     PreToolUseHookSpecificOutput
     | PostToolUseHookSpecificOutput
+    | PostToolUseFailureHookSpecificOutput
     | UserPromptSubmitHookSpecificOutput
     | SessionStartHookSpecificOutput
 )