AI: Hooks

AI: Hooks

Hooks — это пользовательские скрипты, команды, HTTP-запросы или плагины, которые автоматически срабатывают на заранее заданных этапах работы ИИ-агента (например, перед выполнением bash-команды, после редактирования файла или при завершении сессии).
Зачем нужно:
  • Промпты — это лишь пожелания, которые LLM может случайно или намеренно проигнорировать. Хуки обеспечивают строгий, детерминированный контроль над тем, что агенту делать можно, а что нельзя.
Польза:
  • Безопасность: Перехват и блокировка опасных действий (например, защита от выполнения rm -rf или запрет на чтение .env файлов с секретами).
  • Автоматизация: Мгновенный запуск автоформатирования (Prettier/Black), линтеров или юнит-тестов сразу после того, как ИИ изменил файл.
  • Удобство: Отправка уведомлений на рабочий стол или в мессенджер, когда ИИ завершил задачу или ждет разрешения на действие.


Настройка

Обычно настраивается в конфигурационном файле агента.
Пример:
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "bash ./scripts/block-danger.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write ."
          }
        ]
      }
    ],
    "Notification": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "say 'Claude expects your input'"
          }
        ]
      }
    ]
  }
}


Виды событий

Событие (Event)
Что фильтрует matcher
Примеры значений matcher'а
PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest
имя инструмента
Bash, `Edit
SessionStart
как началась сессия
startup, resume, clear, compact
SessionEnd
почему сессия завершилась
clear, logout, prompt_input_exit, bypass_permissions_disabled, other
Notification
тип уведомления
permission_prompt, idle_prompt, auth_success, elicitation_dialog
SubagentStart
тип агента
Bash, Explore, Plan или пользовательские имена агентов
PreCompact
что вызвало сжатие контекста
manual, auto
SubagentStop
тип агента
те же значения, что и у SubagentStart
ConfigChange
источник конфигурации
user_settings, project_settings, local_settings, policy_settings, skills
UserPromptSubmit, Stop, TeammateIdle, TaskCompleted, WorktreeCreate, WorktreeRemove, InstructionsLoaded
не поддерживает matcher
всегда срабатывает при каждом возникновении


Best Practices

  • Настройте базовые уведомления и банальное автоформатирование файлов после события PostToolUse.
  • Настройте регулярные выражения на перехват деструктивных shell-команд или попыток сделать коммит напрямую в main ветку.
  • Полезно настроить хук, который автоматически делает локальный git-коммит после каждого успешного завершения задачи агентом.
  • Пишите максимально быстрые скрипты, чтобы не создавать задержек в цикле работы агента.
  • Настраивайте строгие Matchers и проверяйте аргументы внутри плагинов, чтобы хуки не срабатывали вхолостую.