[DOCS] Hooks documentation missing HTTP security constraints (`allowedEnvVars`, sandbox proxy routing, and event limitations)

Documentation Type

Incorrect/outdated documentation

Documentation Location

https://platform.claude.com/docs/en/agent-sdk/hooks

Section/Topic

HTTP hook security model and constraints: environment variable interpolation controls, sandbox network behavior, and unsupported hook events.

Current Documentation

Current hooks docs describe HTTP/webhook usage without these constraints:

Hooks can perform async operations like HTTP requests.

await fetch("https://api.example.com/webhook", { ... })

Separately, Claude Code hook docs only describe script-path env vars:

$CLAUDE_PROJECT_DIR ... ${CLAUDE_PLUGIN_ROOT} ...

No allowedEnvVars requirement or HTTP hook event limitations are documented.

What's Wrong or Missing?

Release v2.1.51 introduced/changed HTTP hook security behavior:

Env var interpolation now requires an explicit allowedEnvVars list in the hook configuration.

and:

HTTP hooks are now routed through the sandbox network proxy when sandboxing is enabled, enforcing the domain allowlist. HTTP hooks are not supported for SessionStart/Setup events.

Current docs do not describe these constraints, which can cause misconfiguration and security misunderstandings.

Suggested Improvement

Add a dedicated "HTTP hooks security constraints" section covering:

• allowedEnvVars configuration schema and examples
• Which fields support env-var interpolation
• Sandbox proxy routing behavior and domain-allowlist enforcement
• Event support matrix clearly stating unsupported events (including SessionStart/Setup)
• Migration notes for previous hook configs

Impact

High - Prevents users from using a feature

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://platform.claude.com/docs/en/agent-sdk/hooks | HTTP hook examples need explicit security constraints and support matrix |
| https://code.claude.com/docs/en/hooks | Hook configuration reference should include allowedEnvVars and unsupported event notes |
| https://platform.claude.com/docs/en/agent-sdk/secure-deployment | Should cross-reference HTTP hook sandbox routing behavior |

Total scope: 3 pages affected

Source: Claude Code release v2.1.51
Changelog entries:

• "Env var interpolation now requires an explicit allowedEnvVars list in the hook configuration."
• "HTTP hooks are now routed through the sandbox network proxy when sandboxing is enabled... HTTP hooks are not supported for SessionStart/Setup events."