Справочник по хукам

​

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

• ~/.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
  • Поддерживает регулярные выражения: Edit|Write или Notebook.*
  • Используйте * для сопоставления всех инструментов. Вы также можете использовать пустую строку ("") или оставить matcher пустым.
• hooks: Массив команд для выполнения при совпадении шаблона
  • type: В настоящее время поддерживается только "command"
  • command: Команда bash для выполнения (может использовать переменную окружения $CLAUDE_PROJECT_DIR)
  • timeout: (Опционально) Как долго команда должна выполняться в секундах, прежде чем отменить эту конкретную команду.

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

​

Скрипты хуков для конкретного проекта

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

​

Хуки плагинов

• Хуки плагинов определяются в файле hooks/hooks.json плагина или в файле, указанном пользовательским путём к полю 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}: Корневая директория проекта (то же самое, что и для проектных хуков)
• Все стандартные переменные окружения доступны

​

События хуков

​

PreToolUse

• Task - Задачи подагентов (см. документацию по подагентам)
• 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 - Вызвано из автоматического компактирования (из-за полного окна контекста)

​

SessionStart

• startup - Вызвано при запуске
• resume - Вызвано из --resume, --continue или /resume
• clear - Вызвано из /clear
• 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 - Другие причины выхода

​

Ввод хука

{
  // 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"
}

​

Вывод хука

​

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

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

{
  "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 - Инструмент создания сущностей сервера Memory
• mcp__filesystem__read_file - Инструмент чтения файлов сервера Filesystem
• mcp__github__search_repositories - Инструмент поиска сервера GitHub

​

Настройка хуков для инструментов 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"
          }
        ]
      }
    ]
  }
}

​

Примеры

​

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

​

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

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

​

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

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

​

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

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

​

Детали выполнения хука

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

​

Отладка

​

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

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

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

​

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

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

​

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

[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>

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