Documentation inconsistencies in Claude Code hooks examples and titles

note from human: after discussing the docs with claude to see if I was misunderstanding, I asked it to write an issue for me and I've pasted it below.

Summary

Found two documentation inconsistencies in the Claude Code hooks documentation that could confuse users about hook behavior and output methods.

Issue 1: Misleading section title for JSON output example

Location: https://docs.anthropic.com/en/docs/claude-code/hooks#json-output-example%3A-bash-command-editing

Problem: The section is titled "JSON Output Example: Bash Command Editing" but appears to demonstrate the "Simple: Exit Code" method (using exit codes and stderr) rather than the "Advanced: JSON Output" method (structured JSON in stdout).

Expected: Section should either:

• Be retitled to reflect it's an exit code example, or
• Be updated to show actual JSON output with structured data in stdout

Issue 2: Potentially misleading context example

Location: https://docs.anthropic.com/en/docs/claude-code/hooks#userpromptsubmit-example%3A-adding-context-and-validation

Problem: The example appears to use print(context) + exit 0, but the documentation states "Claude Code does not see stdout if the exit code is 0." The title and comments suggest this adds context for Claude, but based on the documented behavior, Claude wouldn't receive this output.

Possible explanations:

1. The example is incorrect and should use exit 2 + stderr or JSON output to actually provide context to Claude
2. The documented behavior of exit code 0 + stdout is incorrect (less likely)

Expected: Either clarify the example's purpose (user-visible vs Claude-visible) or update it to use a method that actually provides context to Claude.

Impact

These inconsistencies make it difficult for users to understand:

• When to use exit codes vs JSON output
• How to properly communicate feedback that Claude can process
• The difference between user-visible and Claude-visible hook output

Environment

• Documentation version: Current (as of July 2025)
• Affected pages: Claude Code hooks documentation