[DOCS] Internal contradiction regarding supported events for prompt-based hooks

Documentation Type

Unclear/confusing documentation

Documentation Location

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

Section/Topic

The section titled "Prompt-Based Hooks" (specifically the introductory paragraph vs. the "Supported hook events" list).

Current Documentation

The introductory paragraph states:

"Prompt-based hooks are currently only supported for Stop and SubagentStop hooks, where they enable intelligent, context-aware decisions."

However, a few paragraphs down, under "Supported hook events", the documentation lists:

Stop: Intelligently decide if Claude should continue working SubagentStop: Evaluate if a subagent has completed its task UserPromptSubmit: Validate user prompts with LLM assistance PreToolUse: Make context-aware permission decisions * PermissionRequest: Intelligently allow or deny permission dialogs

What's Wrong or Missing?

The documentation contradicts itself. The introductory paragraph explicitly limits prompt-based hooks to only two events (Stop and SubagentStop), but the detailed list immediately following it describes support for five events (adding UserPromptSubmit, PreToolUse, and PermissionRequest).

This causes confusion for developers trying to implement prompt-based logic for tool usage or permissions, as the intro implies these are not supported features.

Suggested Improvement

The introductory paragraph should be updated to reflect the broader support listed in the detailed section (assuming the list is the accurate source of truth).

Suggested text:

"In addition to bash command hooks (type: "command"), Claude Code supports prompt-based hooks (type: "prompt") that use an LLM to evaluate whether to allow or block an action. Prompt-based hooks work with events such as Stop, SubagentStop, UserPromptSubmit, PreToolUse, and PermissionRequest, enabling intelligent, context-aware decisions."

Impact

High - Prevents users from using a feature

Additional Context

The broader list of supported events aligns with other parts of the documentation (such as the plugin reference), suggesting the introductory paragraph is outdated legacy text that was not updated when support for other events was added.