claude-code - 💡(How to fix) Fix [DOCS] Hook input references omit `duration_ms` for `PostToolUse` and `PostToolUseFailure` [1 participants]

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://code.claude.com/docs/en/agent-sdk/typescript

Section/Topic

PostToolUseHookInput and PostToolUseFailureHookInput in the Agent SDK hook input reference, plus the corresponding hook input documentation for PostToolUse / PostToolUseFailure

Current Documentation

The docs currently show these TypeScript hook input definitions:

PostToolUseHookInput

type PostToolUseHookInput = BaseHookInput & { hook_event_name: "PostToolUse"; tool_name: string; tool_input: unknown; tool_response: unknown; tool_use_id: string; };

PostToolUseFailureHookInput

type PostToolUseFailureHookInput = BaseHookInput & { hook_event_name: "PostToolUseFailure"; tool_name: string; tool_input: unknown; tool_use_id: string; error: string; is_interrupt?: boolean; };

The Python reference shows the same omission:

PostToolUseHookInput documents tool_name, tool_input, tool_response, tool_use_id, agent_id, and agent_type.

PostToolUseFailureHookInput documents tool_name, tool_input, tool_use_id, error, is_interrupt, agent_id, and agent_type.

The hooks reference also currently says:

PostToolUse hooks fire after a tool has already executed successfully. The input includes both tool_input, the arguments sent to the tool, and tool_response, the result it returned.

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

What's Wrong or Missing?

Changelog v2.1.119 says PostToolUse and PostToolUseFailure hook inputs now include duration_ms (tool execution time, excluding permission prompts and PreToolUse hooks), but the current hook input documentation still omits that field.

As a result, hook authors reading the TypeScript/Python SDK references or the hooks reference cannot discover that duration_ms is available, what it means, or that they can safely consume it in logging, metrics, and automation hooks.

Suggested Improvement

Update the hook input documentation to add duration_ms everywhere PostToolUseHookInput and PostToolUseFailureHookInput are defined or summarized.

Suggested minimum fix:

1. Add duration_ms to the TypeScript PostToolUseHookInput and PostToolUseFailureHookInput type definitions.
2. Add duration_ms to the Python class definitions and field tables for those same hook inputs.
3. Update the hooks reference PostToolUse input / PostToolUseFailure input sections to mention the field and define it as tool execution time in milliseconds, excluding permission prompts and PreToolUse hooks.
4. Update the example JSON payloads to include duration_ms so the new field is discoverable in the main hooks documentation.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 5 pages affected

Source: Changelog v2.1.119

Changelog entry under review: Hooks: PostToolUse and PostToolUseFailure hook inputs now include duration_ms (tool execution time, excluding permission prompts and PreToolUse hooks)