[DOCS] Security disclaimer for hooks feature buried at end of 1377-line reference doc

Documentation Type

Unclear/confusing documentation

Documentation Location

https://code.claude.com/en/hooks

Section/Topic

The "Security Considerations" section placement. Currently appears as the second-to-last section (after Hook Execution Details).

Current Documentation

The critical security disclaimer appears at line 1270 of a 1377-line document (92% through):

## Security Considerations

### Disclaimer

**USE AT YOUR OWN RISK**: Claude Code hooks execute arbitrary shell commands on
your system automatically. By using hooks, you acknowledge that:

* You are solely responsible for the commands you configure
* Hooks can modify, delete, or access any files your user account can access
* Malicious or poorly written hooks can cause data loss or system damage
* Anthropic provides no warranty and assumes no liability for any damages
  resulting from hook usage

Document structure places security considerations after all implementation details:

1. Hook lifecycle (line 9)
2. Configuration (line 34)
3. Plugin hooks (line 125)
4. Prompt-based hooks (line 216)
5. Hook events (line 341)
6. Hook input (line 527)
7. Hook output (line 811)
8. MCP tools (line 1214)
9. Examples (line 1260)
10. Security Considerations (line 1266) ← buried here
11. Hook Execution Details (line 1306)
12. Debugging (line 1322)

What's Wrong or Missing?

The security implications are severe and the placement doesn't reflect this:

1. Hooks bypass Claude Code's permission system - They're raw shell commands, not Claude tool calls
2. Project-level hooks (.claude/settings.json) can be committed to repositories - A cloned repo could contain malicious hooks
3. Plugin hooks run with the same privileges - Third-party plugins can execute arbitrary commands
4. No sandboxing mechanism exists - Hooks have full access to anything the user account can access

A developer following the tutorial workflow (reading top-to-bottom) would configure hooks, possibly add project hooks to git, and only discover the security implications after reading 1,200+ lines of documentation.

Note: The companion getting-started guide (hooks-guide.md) does include a <Warning> near the top linking to Security Considerations. However:

• Users may read the reference doc directly without seeing the guide
• The guide's warning uses softer language ("consider the security implication") vs. the reference doc's "USE AT YOUR OWN RISK"

Suggested Improvement

Move the Security Considerations section to the top of the document, immediately after the introductory paragraph. This matches the pattern used in sensitive documentation like API authentication, where security guidance comes first.

Suggested structure:

# Hooks reference

> This page provides reference documentation for implementing hooks in Claude Code.

## Security Considerations  ← Move here

**USE AT YOUR OWN RISK**: Claude Code hooks execute arbitrary shell commands...

## Hook lifecycle
...

Additionally, consider:

• Adding the same security disclaimer to plugins-reference.md where plugin hooks are documented
• Ensuring consistent warning language between hooks-guide.md and hooks.md

Impact

High - Prevents users from using a feature

Additional Context

Files affected:
| File | Issue |
|------|-------|
| code-claude/docs/en/hooks.md | Security disclaimer at line 1270 of 1377 (92% through document) |

Comparison with best practices:

• The getting-started guide (hooks-guide.md) places a warning near the top (line 30-35)
• The Agent SDK hooks documentation (platform-claude/docs/en/agent-sdk/hooks.md) mentions security in the introductory bullet points (line 9)

Mirror location: code-claude/docs/en/hooks.md

Current models reference: https://docs.anthropic.com/en/docs/about-claude/models