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

[coygeek]

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.

[github-actions]

Found 3 possible duplicate issues:

1. [DOCS] Deprecated fields used in PreToolUse hook code example despite warning #18967
2. [DOCS] Clarify output structure and hookEventName usage for Stop hooks #15485
3. [DOCS] Outdated/Deprecated field usage in PreToolUse Hook JSON examples #18063

This issue will be automatically closed as a duplicate in 3 days.

• If your issue is a duplicate, please close it and 👍 the existing issue instead
• To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

[coygeek]

Thank you for the updates to the hooks documentation. After reviewing the current live site at https://code.claude.com/docs/en/hooks, I have conducted a follow-up audit to see if the schema inconsistencies reported in my original issue have been resolved.

What’s FIXED

• Clarified PreToolUse Deprecation: The documentation at https://code.claude.com/docs/en/hooks#pretooluse-decision-control now explicitly states that decision and reason are deprecated for this specific event. It also helpfully includes the mapping logic (e.g., approve maps to allow) which helps with backward compatibility.
• Updated PreToolUse Example: The JSON block for PreToolUse has been updated to use the modern hookSpecificOutput.permissionDecision syntax.

What’s UNRESOLVED

The core issue regarding contradictory schema requirements and cognitive load remains unresolved. Specifically:

• Missing High-Level Warning: The "Advanced: JSON Output" section at https://code.claude.com/docs/en/hooks#advanced-json-output still lacks a unifying note or "Schema Transition Table" explaining that the JSON structure is event-dependent. A developer reading the deprecation notice for PreToolUse will reasonably assume those keys are deprecated globally for the SDK, which is not the case.
• Continued Use of "Deprecated" Keys in Examples:
  • The PostToolUse section at https://code.claude.com/docs/en/hooks#posttooluse-decision-control still provides an example using the root-level "decision": "block" key.
  • The Stop/SubagentStop section at https://code.claude.com/docs/en/hooks#stopsubagentstop-decision-control also continues to use the root-level keys.
  • The comprehensive Python example at https://code.claude.com/docs/en/hooks#json-output-example-userpromptsubmit-to-add-context-and-validation explicitly uses output = {"decision": "block", "reason": ...}.
• Implementation Risk remains: Because the documentation labels these keys as "deprecated" in one section but "required" in the next, there is a high risk of developers attempting to use the hookSpecificOutput.permissionDecision syntax for PostToolUse or UserPromptSubmit. This will result in hooks that silently fail to block actions because the SDK is looking for the root-level keys for those specific events.

Conclusion

I am keeping this issue open.

While the documentation for PreToolUse is more accurate, the overall developer experience is still fragmented and confusing. To fully resolve this issue, the documentation needs a clear warning at the top of the Advanced: JSON Output section that explicitly states: "While PreToolUse has migrated to hookSpecificOutput, all other events (PostToolUse, Stop, UserPromptSubmit) still require root-level decision keys."

Alternatively, if the SDK is planning to unify these schemas, the documentation for all other events should be updated to support the nested hookSpecificOutput structure. Until one of these paths is taken, the documentation remains technically contradictory.

[github-actions]

Closing for now — inactive for too long. Please open a new issue if this is still relevant.

[github-actions]

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.