[DOCS] Deprecated `PreToolUse` hook syntax used in Hooks Guide example

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

The "JSON Output Example: PreToolUse with Approval" section within the "Get started with Claude Code hooks" guide.

Current Documentation

The Python example script in the guide currently constructs the output JSON using the decision and reason fields:

    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 example in the introductory guide uses fields (decision and reason) that are explicitly marked as deprecated in the Hooks Reference documentation.

The reference documentation states:

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

New users following the "Get started" guide will inadvertently implement hooks using deprecated syntax rather than the current standard.

Suggested Improvement

Update the Python example in hooks-guide to use the modern hookSpecificOutput structure.

Proposed code change:

    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

• Reference Documentation: https://code.claude.com/docs/en/hooks#pretooluse-decision-control
• Note in Reference: "The deprecated fields "approve" and "block" map to "allow" and "deny" respectively."