Справочник по hooks

​

Конфигурация

• ~/.claude/settings.json - Пользовательские настройки
• .claude/settings.json - Настройки проекта
• .claude/settings.local.json - Локальные настройки проекта (не коммитятся)
• Параметры политики, управляемые предприятием

​

Структура

{
  "hooks": {
    "EventName": [
      {
        "matcher": "ToolPattern",
        "hooks": [
          {
            "type": "command",
            "command": "your-command-here"
          }
        ]
      }
    ]
  }
}

• matcher: Шаблон для сопоставления имён инструментов, чувствителен к регистру (применяется только для PreToolUse и PostToolUse)
  • Простые строки совпадают точно: Write совпадает только с инструментом Write
  • Поддерживает regex: Edit|Write или Notebook.*
  • Используйте * для сопоставления всех инструментов. Вы также можете использовать пустую строку ("") или оставить matcher пустым.
• hooks: Массив hooks для выполнения при совпадении шаблона
  • type: Тип выполнения hook - "command" для bash команд или "prompt" для оценки на основе LLM
  • command: (Для type: "command") Bash команда для выполнения (может использовать переменную окружения $CLAUDE_PROJECT_DIR)
  • prompt: (Для type: "prompt") Промпт для отправки LLM для оценки
  • timeout: (Опционально) Как долго hook должен работать в секундах перед отменой этого конкретного hook

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/prompt-validator.py"
          }
        ]
      }
    ]
  }
}

​

Скрипты Hook для конкретного проекта

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check-style.sh"
          }
        ]
      }
    ]
  }
}

​

Hooks плагинов

• Hooks плагинов определены в файле hooks/hooks.json плагина или в файле, указанном пользовательским путём к полю hooks.
• Когда плагин включен, его hooks объединяются с пользовательскими и проектными hooks
• Несколько hooks из разных источников могут реагировать на одно и то же событие
• Hooks плагинов используют переменную окружения ${CLAUDE_PLUGIN_ROOT} для ссылки на файлы плагина

{
  "description": "Automatic code formatting",
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/format.sh",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

• ${CLAUDE_PLUGIN_ROOT}: Абсолютный путь к директории плагина
• ${CLAUDE_PROJECT_DIR}: Корневая директория проекта (то же самое, что и для проектных hooks)
• Все стандартные переменные окружения доступны

​

Hooks на основе промптов

​

Как работают hooks на основе промптов

1. Отправляют входные данные hook и ваш промпт быстрому LLM (Haiku)
2. LLM отвечает структурированным JSON с решением
3. Claude Code автоматически обрабатывает решение

​

Конфигурация

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Evaluate if Claude should stop: $ARGUMENTS. Check if all tasks are complete."
          }
        ]
      }
    ]
  }
}

• type: Должно быть "prompt"
• prompt: Текст промпта для отправки LLM
  • Используйте $ARGUMENTS как заполнитель для входного JSON hook
  • Если $ARGUMENTS отсутствует, входной JSON добавляется к промпту
• timeout: (Опционально) Timeout в секундах (по умолчанию: 30 секунд)

​

Схема ответа

{
  "decision": "approve" | "block",
  "reason": "Explanation for the decision",
  "continue": false,  // Optional: stops Claude entirely
  "stopReason": "Message shown to user",  // Optional: custom stop message
  "systemMessage": "Warning or context"  // Optional: shown to user
}

• decision: "approve" разрешает действие, "block" предотвращает его
• reason: Объяснение, показываемое Claude при решении "block"
• continue: (Опционально) Если false, полностью останавливает выполнение Claude
• stopReason: (Опционально) Сообщение, показываемое при continue равном false
• systemMessage: (Опционально) Дополнительное сообщение, показываемое пользователю

​

Поддерживаемые события hook

• Stop: Интеллектуально решить, должен ли Claude продолжать работу
• SubagentStop: Оценить, завершил ли subagent свою задачу
• UserPromptSubmit: Валидировать пользовательские промпты с помощью LLM
• PreToolUse: Принимать контекстно-зависимые решения о разрешениях

​

Пример: Интеллектуальный Stop hook

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "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\"}",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

​

Пример: SubagentStop с пользовательской логикой

{
  "hooks": {
    "SubagentStop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "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\"}"
          }
        ]
      }
    ]
  }
}

​

Сравнение с bash command hooks

​

Лучшие практики

• Будьте конкретны в промптах: Ясно укажите, что вы хотите, чтобы LLM оценил
• Включите критерии решения: Перечислите факторы, которые LLM должен рассмотреть
• Тестируйте ваши промпты: Проверьте, что LLM принимает правильные решения для ваших случаев использования
• Установите подходящие timeouts: По умолчанию 30 секунд, отрегулируйте при необходимости
• Используйте для сложных решений: Bash hooks лучше для простых, детерминированных правил

​

События Hook

​

PreToolUse

• Task - Задачи subagent (см. документацию subagents)
• Bash - Команды оболочки
• Glob - Сопоставление шаблонов файлов
• Grep - Поиск содержимого
• Read - Чтение файлов
• Edit - Редактирование файлов
• Write - Запись файлов
• WebFetch, WebSearch - Веб-операции

​

PostToolUse

​

Notification

1. Claude нуждается в вашем разрешении для использования инструмента. Пример: “Claude needs your permission to use Bash”
2. Входной промпт был неактивен в течение как минимум 60 секунд. “Claude is waiting for your input”

​

UserPromptSubmit

​

Stop

​

SubagentStop

​

PreCompact

• manual - Вызвано из /compact
• auto - Вызвано из auto-compact (из-за полного окна контекста)

​

SessionStart

• startup - Вызвано при запуске
• resume - Вызвано из --resume, --continue или /resume
• clear - Вызвано из /clear
• compact - Вызвано из auto или manual compact.

​

Сохранение переменных окружения

#!/bin/bash

if [ -n "$CLAUDE_ENV_FILE" ]; then
  echo 'export NODE_ENV=production' >> "$CLAUDE_ENV_FILE"
  echo 'export API_KEY=your-api-key' >> "$CLAUDE_ENV_FILE"
  echo 'export PATH="$PATH:./node_modules/.bin"' >> "$CLAUDE_ENV_FILE"
fi

exit 0

#!/bin/bash

ENV_BEFORE=$(export -p | sort)

# Run your setup commands that modify the environment
source ~/.nvm/nvm.sh
nvm use 20

if [ -n "$CLAUDE_ENV_FILE" ]; then
  ENV_AFTER=$(export -p | sort)
  comm -13 <(echo "$ENV_BEFORE") <(echo "$ENV_AFTER") >> "$CLAUDE_ENV_FILE"
fi

exit 0

​

SessionEnd

• clear - Сессия очищена командой /clear
• logout - Пользователь вышел
• prompt_input_exit - Пользователь вышел, пока был виден входной промпт
• other - Другие причины выхода

​

Входные данные Hook

{
  // Common fields
  session_id: string
  transcript_path: string  // Path to conversation JSON
  cwd: string              // The current working directory when the hook is invoked
  permission_mode: string  // Current permission mode: "default", "plan", "acceptEdits", or "bypassPermissions"

  // Event-specific fields
  hook_event_name: string
  ...
}

​

Входные данные PreToolUse

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "PreToolUse",
  "tool_name": "Write",
  "tool_input": {
    "file_path": "/path/to/file.txt",
    "content": "file content"
  }
}

​

Входные данные PostToolUse

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "PostToolUse",
  "tool_name": "Write",
  "tool_input": {
    "file_path": "/path/to/file.txt",
    "content": "file content"
  },
  "tool_response": {
    "filePath": "/path/to/file.txt",
    "success": true
  }
}

​

Входные данные Notification

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "Notification",
  "message": "Task completed successfully"
}

​

Входные данные UserPromptSubmit

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "UserPromptSubmit",
  "prompt": "Write a function to calculate the factorial of a number"
}

​

Входные данные Stop и SubagentStop

{
  "session_id": "abc123",
  "transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "permission_mode": "default",
  "hook_event_name": "Stop",
  "stop_hook_active": true
}

​

Входные данные PreCompact

{
  "session_id": "abc123",
  "transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "permission_mode": "default",
  "hook_event_name": "PreCompact",
  "trigger": "manual",
  "custom_instructions": ""
}

​

Входные данные SessionStart

{
  "session_id": "abc123",
  "transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "permission_mode": "default",
  "hook_event_name": "SessionStart",
  "source": "startup"
}

​

Входные данные SessionEnd

{
  "session_id": "abc123",
  "transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "SessionEnd",
  "reason": "exit"
}

​

Выходные данные Hook

​

Простой: Код выхода

• Код выхода 0: Успех. stdout показывается пользователю в режиме транскрипта (CTRL-R), за исключением UserPromptSubmit и SessionStart, где stdout добавляется в контекст.
• Код выхода 2: Ошибка блокирования. stderr передаётся Claude для автоматической обработки. См. поведение для каждого события hook ниже.
• Другие коды выхода: Ошибка без блокирования. stderr показывается пользователю и выполнение продолжается.

​

Поведение кода выхода 2

​

Продвинутый: JSON выходные данные

​

Общие поля JSON

{
  "continue": true, // Whether Claude should continue after hook execution (default: true)
  "stopReason": "string", // Message shown when continue is false

  "suppressOutput": true, // Hide stdout from transcript mode (default: false)
  "systemMessage": "string" // Optional warning message shown to the user
}

• Для PreToolUse, это отличается от "permissionDecision": "deny", который только блокирует конкретный вызов инструмента и предоставляет автоматическую обратную связь Claude.
• Для PostToolUse, это отличается от "decision": "block", который предоставляет автоматическую обратную связь Claude.
• Для UserPromptSubmit, это предотвращает обработку промпта.
• Для Stop и SubagentStop, это имеет приоритет над любым выходом "decision": "block".
• Во всех случаях "continue" = false имеет приоритет над любым выходом "decision": "block".

​

Управление решением PreToolUse

• "allow" обходит систему разрешений. permissionDecisionReason показывается пользователю, но не Claude.
• "deny" предотвращает выполнение вызова инструмента. permissionDecisionReason показывается Claude.
• "ask" просит пользователя подтвердить вызов инструмента в UI. permissionDecisionReason показывается пользователю, но не Claude.

• updatedInput позволяет вам изменять параметры входных данных инструмента перед выполнением инструмента. Это объект Record<string, unknown>, содержащий поля, которые вы хотите изменить или добавить.
• Это наиболее полезно с "permissionDecision": "allow" для изменения и одобрения вызовов инструментов.

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow"
    "permissionDecisionReason": "My reason here",
    "updatedInput": {
      "field_to_modify": "new value"
    }
  }
}

​

Управление решением PostToolUse

• "block" автоматически запрашивает Claude с reason.
• undefined ничего не делает. reason игнорируется.
• "hookSpecificOutput.additionalContext" добавляет контекст для Claude для рассмотрения.

{
  "decision": "block" | undefined,
  "reason": "Explanation for decision",
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "additionalContext": "Additional information for Claude"
  }
}

​

Управление решением UserPromptSubmit

• "block" предотвращает обработку промпта. Отправленный промпт стирается из контекста. "reason" показывается пользователю, но не добавляется в контекст.
• undefined позволяет промпту продолжаться нормально. "reason" игнорируется.
• "hookSpecificOutput.additionalContext" добавляет строку в контекст, если не заблокирована.

{
  "decision": "block" | undefined,
  "reason": "Explanation for decision",
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "My additional context here"
  }
}

​

Управление решением Stop/SubagentStop

• "block" предотвращает остановку Claude. Вы должны заполнить reason, чтобы Claude знал, как действовать дальше.
• undefined позволяет Claude остановиться. reason игнорируется.

{
  "decision": "block" | undefined,
  "reason": "Must be provided when Claude is blocked from stopping"
}

​

Управление решением SessionStart

• "hookSpecificOutput.additionalContext" добавляет строку в контекст.
• Значения additionalContext из нескольких hooks объединяются.

{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "My additional context here"
  }
}

​

Управление решением SessionEnd

​

Пример кода выхода: Валидация Bash команды

#!/usr/bin/env python3
import json
import re
import sys

# Define validation rules as a list of (regex pattern, message) tuples
VALIDATION_RULES = [
    (
        r"\bgrep\b(?!.*\|)",
        "Use 'rg' (ripgrep) instead of 'grep' for better performance and features",
    ),
    (
        r"\bfind\s+\S+\s+-name\b",
        "Use 'rg --files | rg pattern' or 'rg --files -g pattern' instead of 'find -name' for better performance",
    ),
]


def validate_command(command: str) -> list[str]:
    issues = []
    for pattern, message in VALIDATION_RULES:
        if re.search(pattern, command):
            issues.append(message)
    return issues


try:
    input_data = json.load(sys.stdin)
except json.JSONDecodeError as e:
    print(f"Error: Invalid JSON input: {e}", file=sys.stderr)
    sys.exit(1)

tool_name = input_data.get("tool_name", "")
tool_input = input_data.get("tool_input", {})
command = tool_input.get("command", "")

if tool_name != "Bash" or not command:
    sys.exit(1)

# Validate the command
issues = validate_command(command)

if issues:
    for message in issues:
        print(f"• {message}", file=sys.stderr)
    # Exit code 2 blocks tool call and shows stderr to Claude
    sys.exit(2)

​

Пример JSON выходных данных: UserPromptSubmit для добавления контекста и валидации

#!/usr/bin/env python3
import json
import sys
import re
import datetime

# Load input from stdin
try:
    input_data = json.load(sys.stdin)
except json.JSONDecodeError as e:
    print(f"Error: Invalid JSON input: {e}", file=sys.stderr)
    sys.exit(1)

prompt = input_data.get("prompt", "")

# Check for sensitive patterns
sensitive_patterns = [
    (r"(?i)\b(password|secret|key|token)\s*[:=]", "Prompt contains potential secrets"),
]

for pattern, message in sensitive_patterns:
    if re.search(pattern, prompt):
        # Use JSON output to block with a specific reason
        output = {
            "decision": "block",
            "reason": f"Security policy violation: {message}. Please rephrase your request without sensitive information."
        }
        print(json.dumps(output))
        sys.exit(0)

# Add current time to context
context = f"Current time: {datetime.datetime.now()}"
print(context)

"""
The following is also equivalent:
print(json.dumps({
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": context,
  },
}))
"""

# Allow the prompt to proceed with the additional context
sys.exit(0)

​

Пример JSON выходных данных: PreToolUse с одобрением

#!/usr/bin/env python3
import json
import sys

# Load input from stdin
try:
    input_data = json.load(sys.stdin)
except json.JSONDecodeError as e:
    print(f"Error: Invalid JSON input: {e}", file=sys.stderr)
    sys.exit(1)

tool_name = input_data.get("tool_name", "")
tool_input = input_data.get("tool_input", {})

# Example: Auto-approve file reads for documentation files
if tool_name == "Read":
    file_path = tool_input.get("file_path", "")
    if file_path.endswith((".md", ".mdx", ".txt", ".json")):
        # Use JSON output to auto-approve the tool call
        output = {
            "decision": "approve",
            "reason": "Documentation file auto-approved",
            "suppressOutput": True  # Don't show in transcript mode
        }
        print(json.dumps(output))
        sys.exit(0)

# For other cases, let the normal permission flow proceed
sys.exit(0)

​

Работа с MCP инструментами

​

Именование MCP инструментов

• mcp__memory__create_entities - Инструмент create entities сервера Memory
• mcp__filesystem__read_file - Инструмент read file сервера Filesystem
• mcp__github__search_repositories - Инструмент search сервера GitHub

​

Конфигурирование Hooks для MCP инструментов

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__memory__.*",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Memory operation initiated' >> ~/mcp-operations.log"
          }
        ]
      },
      {
        "matcher": "mcp__.*__write.*",
        "hooks": [
          {
            "type": "command",
            "command": "/home/user/scripts/validate-mcp-write.py"
          }
        ]
      }
    ]
  }
}

​

Примеры

​

Соображения безопасности

​

Отказ от ответственности

• Вы несёте исключительную ответственность за команды, которые вы настраиваете
• Hooks могут изменять, удалять или получать доступ к любым файлам, к которым может получить доступ ваша учётная запись пользователя
• Вредоносные или плохо написанные hooks могут вызвать потерю данных или повреждение системы
• Anthropic не предоставляет гарантию и не несёт ответственность за любые убытки в результате использования hooks
• Вы должны тщательно тестировать hooks в безопасной среде перед использованием в производстве

​

Лучшие практики безопасности

1. Валидируйте и санитизируйте входные данные - Никогда не доверяйте входным данным вслепую
2. Всегда заключайте переменные оболочки в кавычки - Используйте "$VAR" а не $VAR
3. Блокируйте обход пути - Проверьте наличие .. в путях файлов
4. Используйте абсолютные пути - Укажите полные пути для скриптов (используйте “$CLAUDE_PROJECT_DIR” для пути проекта)
5. Пропускайте чувствительные файлы - Избегайте .env, .git/, ключей и т.д.

​

Безопасность конфигурации

1. Захватывает снимок hooks при запуске
2. Использует этот снимок на протяжении всей сессии
3. Предупреждает, если hooks изменены извне
4. Требует проверки в меню /hooks для применения изменений

​

Детали выполнения Hook

• Timeout: Лимит выполнения 60 секунд по умолчанию, настраивается для каждой команды.
  • Timeout для отдельной команды не влияет на другие команды.
• Параллелизация: Все совпадающие hooks запускаются параллельно
• Дедупликация: Несколько идентичных команд hook автоматически дедублируются
• Окружение: Запускается в текущей директории с окружением Claude Code
  • Переменная окружения CLAUDE_PROJECT_DIR доступна и содержит абсолютный путь к корневой директории проекта (где был запущен Claude Code)
  • Переменная окружения CLAUDE_CODE_REMOTE указывает, запущен ли hook в удалённом (веб) окружении ("true") или локальном CLI окружении (не установлена или пуста). Используйте это для запуска различной логики в зависимости от контекста выполнения.
• Входные данные: JSON через stdin
• Выходные данные:
  • PreToolUse/PostToolUse/Stop/SubagentStop: Прогресс показан в транскрипте (Ctrl-R)
  • Notification/SessionEnd: Логируется только в debug (--debug)
  • UserPromptSubmit/SessionStart: stdout добавлен как контекст для Claude

​

Отладка

​

Базовое устранение неполадок

1. Проверьте конфигурацию - Запустите /hooks чтобы увидеть, зарегистрирован ли ваш hook
2. Проверьте синтаксис - Убедитесь, что ваш JSON в настройках действителен
3. Тестируйте команды - Сначала запустите команды hook вручную
4. Проверьте разрешения - Убедитесь, что скрипты исполняемы
5. Проверьте логи - Используйте claude --debug чтобы увидеть детали выполнения hook

• Кавычки не экранированы - Используйте \" внутри JSON строк
• Неправильный матчер - Проверьте, что имена инструментов совпадают точно (чувствительны к регистру)
• Команда не найдена - Используйте полные пути для скриптов

​

Продвинутая отладка

1. Проверьте выполнение hook - Используйте claude --debug чтобы увидеть детальное выполнение hook
2. Валидируйте JSON схемы - Тестируйте входные/выходные данные hook с внешними инструментами
3. Проверьте переменные окружения - Проверьте, что окружение Claude Code правильно
4. Тестируйте граничные случаи - Попробуйте hooks с необычными путями файлов или входными данными
5. Мониторьте ресурсы системы - Проверьте на истощение ресурсов во время выполнения hook
6. Используйте структурированное логирование - Реализуйте логирование в ваших скриптах hook

​

Пример выходных данных отладки

[DEBUG] Executing hooks for PostToolUse:Write
[DEBUG] Getting matching hook commands for PostToolUse with query: Write
[DEBUG] Found 1 hook matchers in settings
[DEBUG] Matched 1 hooks for query "Write"
[DEBUG] Found 1 hook commands to execute
[DEBUG] Executing hook command: <Your command> with timeout 60000ms
[DEBUG] Hook command completed with status 0: <Your stdout>

• Какой hook запущен
• Выполняемая команда
• Статус успеха/неудачи
• Выходные данные или сообщения об ошибках