[DOCS] Agent SDK hook callback timeout behavior is incomplete for unattended sessions

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

The Hook timeout troubleshooting section, together with the callback-timeout behavior documented for UserPromptSubmit and UserPromptExpansion.

Current Documentation

The Agent SDK hooks page currently says:

### Hook timeout Increase the timeout value in the HookMatcher configuration Use the AbortSignal from the third callback argument to handle cancellation gracefully in TypeScript A UserPromptSubmit or UserPromptExpansion callback that exceeds its timeout blocks that prompt with a timeout message and the session continues. Interrupting the query while a callback is pending cancels the pending tool call. Before v2.1.208, a callback timeout on those events ended the query with error_during_execution, and an interrupt during a pending PreToolUse callback could let the tool call proceed.

What's Wrong or Missing?

The page documents timeout behavior for UserPromptSubmit and UserPromptExpansion, but does not explain the timeout contract for callback hooks on the other supported events, such as PreToolUse, PermissionRequest, and PostToolUse.

In particular, it does not distinguish an infrastructure timeout from an explicit user decision. An explicit denial is a deliberate permissionDecision: "deny" or behavior: "deny" result that Claude can treat as a user rejection. The v2.1.210 changelog says a hook callback timeout was being reported to the model as a user rejection, which made unattended sessions stop and wait for a user who could not respond. The current guidance gives unattended Agent SDK users no way to understand that failure mode or the corrected behavior in v2.1.210.

Suggested Improvement

Expand the Hook timeout section with a versioned note for v2.1.210 or later that:

1. Explains that a callback timeout is not an explicit user rejection and must not be presented to the model as one.
2. States what the model receives when a callback times out and whether the affected tool call, prompt, or turn is canceled, blocked, or allowed to continue for each relevant hook event.
3. Clarifies how this differs from returning permissionDecision: "deny" from a PreToolUse hook or behavior: "deny" from canUseTool.
4. Gives unattended and headless users recovery guidance, including how to use the callback cancellation signal and how to choose a timeout appropriate for the workload.

Keep the existing UserPromptSubmit and UserPromptExpansion details, but label them as event-specific rather than the complete callback-timeout behavior.

Impact

High - Prevents users from using a feature

Additional Context

Affected Pages:
| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/agent-sdk/hooks | Callback timeout troubleshooting and event-specific timeout behavior |
| https://code.claude.com/docs/en/hooks | UserPromptSubmit callback timeout behavior and distinction between timeout and blocking decisions |
| https://code.claude.com/docs/en/headless | Unattended claude -p and Agent SDK execution context |

Total scope: 3 pages affected

The behavior change is recorded in the Claude Code v2.1.210 changelog. The existing Agent SDK documentation separately defines explicit denial results as permission decisions, so the timeout guidance should make clear that a timeout is not equivalent to one of those deliberate user responses.