[DOCS] Agent SDK hooks documentation should clarify that tool_use_id is not in input_data

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://platform.claude.com/docs/en/agent-sdk/hooks

Section/Topic

"Callback function inputs" and "Input data" sections

Current Documentation

The callback inputs section states:

Every hook callback receives three arguments: 1. Input data (dict / HookInput): Event details. See input data for fields 2. Tool use ID (str | None / string | null): Correlate PreToolUse and PostToolUse events

The "Input data" section lists fields like hook_event_name, tool_name, tool_input, but does not include tool_use_id.

What's Wrong or Missing?

Users familiar with CLI hooks (code.claude.com/docs/en/hooks) see JSON examples where tool_use_id is a field in the payload:

{
  "tool_name": "Bash",
  "tool_input": {...},
  "tool_use_id": "toolu_01ABC123..."
}

The Agent SDK docs don't explicitly clarify that:

1. tool_use_id is not present in the input_data dictionary for SDK hooks
2. The SDK extracts it and passes it as a separate callback argument for convenience
3. This differs from the CLI hooks JSON structure

This could confuse users who:

• Wonder if tool_use_id is available in both places (redundant)
• Try to access input_data['tool_use_id'] and get a KeyError
• Expect CLI hook and SDK hook data structures to be identical

Suggested Improvement

Add a clarifying note in the "Input data" section:

Note: Unlike CLI hooks (which include tool_use_id in the JSON payload), the Agent SDK extracts tool_use_id and passes it as a separate callback argument. It is not present in input_data.

Alternatively, add a brief note to the HookCallback parameter description:

- input_data: Hook-specific input data (see Hooks guide). Does not include tool_use_id. - tool_use_id: Optional tool use identifier, extracted from the event for convenience

Impact

High - Prevents users from using a feature

Additional Context

• Mirror location: platform.claude.com/docs/en/agent-sdk/hooks.md
• Related: CLI Hooks documentation shows tool_use_id in JSON payload, while Agent SDK passes it separately
• The Python SDK reference at platform.claude.com/docs/en/agent-sdk/python.md shows HookCallback = Callable[[dict[str, Any], str | None, HookContext], ...] but doesn't note that the dict excludes tool_use_id