[DOCS] Conflicting JSON Response Schemas for Hook Events (`PreToolUse` vs `PostToolUse`)

Documentation Type

Unclear/confusing documentation

Documentation Location

https://code.claude.com/docs/en/hooks

Section/Topic

The Advanced: JSON Output section, specifically the sub-sections for PreToolUse Decision Control and PostToolUse Decision Control.

Current Documentation

In the PreToolUse Decision Control section, the documentation states:

"The decision and reason fields are deprecated for PreToolUse hooks. Use hookSpecificOutput.permissionDecision and hookSpecificOutput.permissionDecisionReason instead."

However, in the very next section, PostToolUse Decision Control, the example provided is:

{
  "decision": "block" | undefined,
  "reason": "Explanation for decision",
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "additionalContext": "Additional information for Claude"
  }
}

The Stop/SubagentStop Decision Control section similarly uses the root-level keys:

{
  "decision": "block" | undefined,
  "reason": "Must be provided when Claude is blocked from stopping"
}

What's Wrong or Missing?

The documentation is contradictory and confusing regarding the "modern" way to return a decision from a hook.

1. It labels root-level decision and reason keys as deprecated for PreToolUse, implying a move toward nesting these within hookSpecificOutput.
2. It then immediately provides examples for PostToolUse and Stop hooks that require the deprecated root-level keys to function.
3. This creates an inconsistent developer experience where the JSON schema changes fundamentally depending on which lifecycle event is being hooked, despite these events being part of the same hooks configuration object.

Suggested Improvement

The documentation should clarify if the deprecation of root-level keys applies to all hook events or strictly to PreToolUse.

If the SDK is moving toward a unified schema:
Update the PostToolUse, Stop, and UserPromptSubmit examples to use the hookSpecificOutput object for decisions.

If the schemas must remain different:
Add a "Schema Transition Table" or a clear warning at the top of the Advanced: JSON Output section that explicitly maps hook events to their required response structure.

Suggested Text for a Warning Note:

"Note: While PreToolUse has migrated to using hookSpecificOutput for permission decisions, PostToolUse and Stop hooks still currently require the root-level decision and reason keys to trigger a block. Refer to the specific event sections below for the correct schema."

Impact

High - Prevents users from using a feature

Additional Context

• Related documentation: https://code.claude.com/docs/en/hooks#pretooluse-decision-control
• Related documentation: https://code.claude.com/docs/en/hooks#posttooluse-decision-control
• Implementation Risk: Developers following the PreToolUse guidance may attempt to use the same logic for PostToolUse, resulting in hooks that silently fail to "block" Claude because the model/SDK is looking for a root-level decision key that is now missing.