Protokoll #1031

{
    "event": "PreToolUse",
    "tool_name": "WebFetch",
    "tool_input": {
        "url": "https:\/\/code.claude.com\/docs\/en\/hooks.md",
        "prompt": "PreToolUse Hook blocking JSON format exit code allow deny decision"
    }
}

{
    "tool_response": {
        "bytes": 35967,
        "code": 200,
        "codeText": "OK",
        "result": "# Hooks reference\n\n> This page provides reference documentation for implementing hooks in Claude Code.\n\n<Tip>\n  For a quickstart guide with examples, see [Get started with Claude Code hooks](\/en\/hooks-guide).\n<\/Tip>\n\n## Configuration\n\nClaude Code hooks are configured in your [settings files](\/en\/settings):\n\n* `~\/.claude\/settings.json` - User settings\n* `.claude\/settings.json` - Project settings\n* `.claude\/settings.local.json` - Local project settings (not committed)\n* Enterprise managed policy settings\n\n<Note>\n  Enterprise administrators can use `allowManagedHooksOnly` to block user, project, and plugin hooks. See [Hook configuration](\/en\/settings#hook-configuration).\n<\/Note>\n\n### Structure\n\nHooks are organized by matchers, where each matcher can have multiple hooks:\n\n```json  theme={null}\n{\n  \"hooks\": {\n    \"EventName\": [\n      {\n        \"matcher\": \"ToolPattern\",\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"your-command-here\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n* **matcher**: Pattern to match tool names, case-sensitive (only applicable for\n  `PreToolUse`, `PermissionRequest`, and `PostToolUse`)\n  * Simple strings match exactly: `Write` matches only the Write tool\n  * Supports regex: `Edit|Write` or `Notebook.*`\n  * Use `*` to match all tools. You can also use empty string (`\"\"`) or leave\n    `matcher` blank.\n* **hooks**: Array of hooks to execute when the pattern matches\n  * `type`: Hook execution type - `\"command\"` for bash commands or `\"prompt\"` for LLM-based evaluation\n  * `command`: (For `type: \"command\"`) The bash command to execute (can use `$CLAUDE_PROJECT_DIR` environment variable)\n  * `prompt`: (For `type: \"prompt\"`) The prompt to send to the LLM for evaluation\n  * `timeout`: (Optional) How long a hook should run, in seconds, before canceling that specific hook\n\nFor events like `UserPromptSubmit`, `Stop`, and `SubagentStop`\nthat don't use matchers, you can omit the matcher field:\n\n```json  theme={null}\n{\n  \"hooks\": {\n    \"UserPromptSubmit\": [\n      {\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"\/path\/to\/prompt-validator.py\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n### Project-Specific Hook Scripts\n\nYou can use the environment variable `CLAUDE_PROJECT_DIR` (only available when\nClaude Code spawns the hook command) to reference scripts stored in your project,\nensuring they work regardless of Claude's current directory:\n\n```json  theme={null}\n{\n  \"hooks\": {\n    \"PostToolUse\": [\n      {\n        \"matcher\": \"Write|Edit\",\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"\\\"$CLAUDE_PROJECT_DIR\\\"\/.claude\/hooks\/check-style.sh\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n### Plugin hooks\n\n[Plugins](\/en\/plugins) can provide hooks that integrate seamlessly with your user and project hooks. Plugin hooks are automatically merged with your configuration when plugins are enabled.\n\n**How plugin hooks work**:\n\n* Plugin hooks are defined in the plugin's `hooks\/hooks.json` file or in a file given by a custom path to the `hooks` field.\n* When a plugin is enabled, its hooks are merged with user and project hooks\n* Multiple hooks from different sources can respond to the same event\n* Plugin hooks use the `${CLAUDE_PLUGIN_ROOT}` environment variable to reference plugin files\n\n**Example plugin hook configuration**:\n\n```json  theme={null}\n{\n  \"description\": \"Automatic code formatting\",\n  \"hooks\": {\n    \"PostToolUse\": [\n      {\n        \"matcher\": \"Write|Edit\",\n        \"hooks\": [\n          {\n            \"type\": \"command\",\n            \"command\": \"${CLAUDE_PLUGIN_ROOT}\/scripts\/format.sh\",\n            \"timeout\": 30\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n<Note>\n  Plugin hooks use the same format as regular hooks with an optional `description` field to explain the hook's purpose.\n<\/Note>\n\n<Note>\n  Plugin hooks run alongside your custom hooks. If multiple hooks match an event, they all execute in parallel.\n<\/Note>\n\n**Environment variables for plugins**:\n\n* `${CLAUDE_PLUGIN_ROOT}`: Absolute path to the plugin directory\n* `${CLAUDE_PROJECT_DIR}`: Project root directory (same as for project hooks)\n* All standard environment variables are available\n\nSee the [plugin components reference](\/en\/plugins-reference#hooks) for details on creating plugin hooks.\n\n## Prompt-Based Hooks\n\nIn 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 are currently only supported for `Stop` and `SubagentStop` hooks, where they enable intelligent, context-aware decisions.\n\n### How prompt-based hooks work\n\nInstead of executing a bash command, prompt-based hooks:\n\n1. Send the hook input and your prompt to a fast LLM (Haiku)\n2. The LLM responds with structured JSON containing a decision\n3. Claude Code processes the decision automatically\n\n### Configuration\n\n```json  theme={null}\n{\n  \"hooks\": {\n    \"Stop\": [\n      {\n        \"hooks\": [\n          {\n            \"type\": \"prompt\",\n            \"prompt\": \"Evaluate if Claude should stop: $ARGUMENTS. Check if all tasks are complete.\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n**Fields:**\n\n* `type`: Must be `\"prompt\"`\n* `prompt`: The prompt text to send to the LLM\n  * Use `$ARGUMENTS` as a placeholder for the hook input JSON\n  * If `$ARGUMENTS` is not present, input JSON is appended to the prompt\n* `timeout`: (Optional) Timeout in seconds (default: 30 seconds)\n\n### Response schema\n\nThe LLM must respond with JSON containing:\n\n```json  theme={null}\n{\n  \"decision\": \"approve\" | \"block\",\n  \"reason\": \"Explanation for the decision\",\n  \"continue\": false,  \/\/ Optional: stops Claude entirely\n  \"stopReason\": \"Message shown to user\",  \/\/ Optional: custom stop message\n  \"systemMessage\": \"Warning or context\"  \/\/ Optional: shown to user\n}\n```\n\n**Response fields:**\n\n* `decision`: `\"approve\"` allows the action, `\"block\"` prevents it\n* `reason`: Explanation shown to Claude when decision is `\"block\"`\n* `continue`: (Optional) If `false`, stops Claude's execution entirely\n* `stopReason`: (Optional) Message shown when `continue` is false\n* `systemMessage`: (Optional) Additional message shown to the user\n\n### Supported hook events\n\nPrompt-based hooks work with any hook event, but are most useful for:\n\n* **Stop**: Intelligently decide if Claude should continue working\n* **SubagentStop**: Evaluate if a subagent has completed its task\n* **UserPromptSubmit**: Validate user prompts with LLM assistance\n* **PreToolUse**: Make context-aware permission decisions\n* **PermissionRequest**: Intelligently allow or deny permission dialogs\n\n### Example: Intelligent Stop hook\n\n```json  theme={null}\n{\n  \"hooks\": {\n    \"Stop\": [\n      {\n        \"hooks\": [\n          {\n            \"type\": \"prompt\",\n            \"prompt\": \"You are evaluating whether Claude should stop working. Context: $ARGUMENTS\\n\\nAnalyze the conversation and determine if:\\n1. All user-requested tasks are complete\\n2. Any errors need to be addressed\\n3. Follow-up work is needed\\n\\nRespond with JSON: {\\\"decision\\\": \\\"approve\\\" or \\\"block\\\", \\\"reason\\\": \\\"your explanation\\\"}\",\n            \"timeout\": 30\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n### Example: SubagentStop with custom logic\n\n```json  theme={null}\n{\n  \"hooks\": {\n    \"SubagentStop\": [\n      {\n        \"hooks\": [\n          {\n            \"type\": \"prompt\",\n            \"prompt\": \"Evaluate if this subagent should stop. Input: $ARGUMENTS\\n\\nCheck if:\\n- The subagent completed its assigned task\\n- Any errors occurred that need fixing\\n- Additional context gathering is needed\\n\\nReturn: {\\\"decision\\\": \\\"approve\\\" or \\\"block\\\", \\\"reason\\\": \\\"explanation\\\"}\"\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n\n### Comparison with bash command hooks\n\n| Feature               | Bash Command Hooks      | Prompt-Based Hooks             |\n| --------------------- | ----------------------- | ------------------------------ |\n| **Execution**         | Runs bash script        | Queries LLM                    |\n| **Decision logic**    | You implement in code   | LLM evaluates context          |\n| **Setup complexity**  | Requires script file    | Configure prompt               |\n| **Context awareness** | Limited to script logic | Natural language understanding |\n| **Performance**       | Fast (local execution)  | Slower (API call)              |\n| **Use case**          | Deterministic rules     | Context-aware decisions        |\n\n### Best practices\n\n* **Be specific in prompts**: Clearly state what you want the LLM to evaluate\n* **Include decision criteria**: List the factors the LLM should consider\n* **Test your prompts**: Verify the LLM makes correct decisions for your use cases\n* **Set appropriate timeouts**: Default is 30 seconds, adjust if needed\n* **Use for complex decisions**: Bash hooks are better for simple, deterministic rules\n\nSee the [plugin components reference](\/en\/plugins-reference#hooks) for details on creating plugin hooks.\n\n## Hook Events\n\n### PreToolUse\n\nRuns after Claude creates tool parameters and before processing the tool call.\n\n**Common matchers:**\n\n* `Task` - Subagent tasks (see [subagents documentation](\/en\/sub-agents))\n* `Bash` - Shell commands\n* `Glob` - File pattern matching\n* `Grep` - Content search\n* `Read` - File reading\n* `Edit` - File editing\n* `Write` - File writing\n* `WebFetch`, `WebSearch` - Web operations\n\nUse [PreToolUse decision control](#pretooluse-decision-control) to allow, deny, or ask for permission to use the tool.\n\n### PermissionRequest\n\nRuns when the user is shown a permission dialog.\nUse [PermissionRequest decision control](#permissionrequest-decision-control) to allow or deny on behalf of the user.\n\nRecognizes the same matcher values as PreToolUse.\n\n### PostToolUse\n\nRuns immediately after a tool completes successfully.\n\nRecognizes the same matcher values as PreToolUse.\n\n### Notification\n\nRuns when Claude Code sends notifications. S... [TRUNCATED-6b934f30c983a501]",
        "durationMs": 117,
        "url": "https:\/\/code.claude.com\/docs\/en\/hooks.md"
    }
}