[DOCS] Outdated/Deprecated field usage in PreToolUse Hook JSON examples

Documentation Type

Unclear/confusing documentation

Documentation Location

URL: https://platform.claude.com/docs/en/hooks (Source file: docs/en/hooks.md)

Section/Topic

The section titled: "JSON Output Example: PreToolUse with Approval"

Current Documentation

The example code snippet for a Python-based PreToolUse hook currently uses:

if file_path.endswith((".md", ".mdx", ".txt", ".json")):
    # Use JSON output to auto-approve the tool call
    output = {
        "decision": "approve",
        "reason": "Documentation file auto-approved",
        "suppressOutput": True  # Don't show in verbose mode
    }
    print(json.dumps(output))
    sys.exit(0)

What's Wrong or Missing?

Earlier in the same documentation file (docs/en/hooks.md), under the "PreToolUse Decision Control" header, a Note states:

"The decision and reason fields are deprecated for PreToolUse hooks. Use hookSpecificOutput.permissionDecision and hookSpecificOutput.permissionDecisionReason instead. The deprecated fields "approve" and "block" map to "allow" and "deny" respectively."

The current examples at the bottom of the page contradict this note by continuing to use the top-level decision and reason fields. This leads to confusion and ensures developers adopt a deprecated pattern.

Suggested Improvement

Update the code snippets in the "JSON Output Example: PreToolUse with Approval" section to reflect the modern structure.

Suggested Python Snippet Update:

if file_path.endswith((".md", ".mdx", ".txt", ".json")):
    # Use JSON output to auto-approve the tool call using non-deprecated fields
    output = {
        "hookSpecificOutput": {
            "hookEventName": "PreToolUse",
            "permissionDecision": "allow",
            "permissionDecisionReason": "Documentation file auto-approved"
        },
        "suppressOutput": True
    }
    print(json.dumps(output))
    sys.exit(0)

Impact

High - Prevents users from using a feature

Additional Context

• Severity: Minor (The code likely still functions due to backward compatibility mapping, but it is technically incorrect according to the latest API definitions).
• Internal Reference: This contradicts the instruction provided in the "Advanced: JSON Output" -> "PreToolUse Decision Control" section of the same file.
• Goal: Prevent developers from getting deprecation warnings or writing brittle code based on the documentation's own "best-practice" examples.