[DOCS] Deprecated fields used in PreToolUse hook code example despite warning

Documentation Type

Unclear/confusing documentation

Documentation Location

https://code.claude.com/docs/en/hooks#json-output-example-pretooluse-with-approval

Section/Topic

The "JSON Output Example: PreToolUse with Approval" section within the Hooks reference.

Current Documentation

The documentation includes a note stating:

"Note: 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."

However, the Python code example immediately following this note uses the deprecated schema:

    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?

The code example contradicts the deprecation warning provided in the text. While the text advises the user to use the new hookSpecificOutput schema, the example code still demonstrates the deprecated decision and reason fields. This is confusing for developers trying to implement hooks using the current best practices.

Suggested Improvement

Update the Python code snippet to use the recommended hookSpecificOutput schema.

Revised Code Snippet:

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

Impact

High - Prevents users from using a feature

Additional Context

• The issue is located near the bottom of the Hooks reference page.
• Note that in the new schema, "approve" should be updated to "allow" as per the mapping described in the documentation text.