ИИ‑агенты > Pastukhov Agent > Документация > Хуки

Хуки

Хуки — это готовые правила для действий агента, которые применяются сами, без участия искусственного интеллекта. Правило может запретить агенту выполнять опасную или лишнюю команду либо, наоборот, обязать его перед действием запустить свою проверку. Благодаря этому не нужно каждый раз напоминать ИИ в диалоге, как себя вести, — правила сработают автоматически.

Hooks configuration dialog in Pastukhov Agent

Правила хранятся в файле .pastukhov/hooks.yml — это настройки проекта, которые удобно держать под контролем версий. Pastukhov Agent автоматически передаёт их собственной системе хуков Claude Code, а менять их можно в наглядном диалоге, не редактируя файлы вручную.

Самое частое применение хуков на практике — не защита от опасных команд, а экономия времени и денег. Сборки проекта запускаются сами при изменении файлов, поэтому каждая ручная сборка или проверка кода, которую агент решает выполнить дополнительно, — это лишние минуты и потраченные токены. Если запретить такие команды хуками, обычный сеанс экономит десятки ненужных шагов — за день набегает заметная экономия.

Типы хуков

В Pastukhov Agent есть два вида хуков — они решают разные задачи:

Запрещающие хуки

Запрещающий хук не даёт выполнить действие, если оно совпадает с заданным образцом. Совпало — вызов инструмента отклоняется, и пользователь видит сообщение о запрете.

  • Для команд терминала (инструмент Bash) — образец сравнивается с текстом команды
  • Для остальных инструментов — используйте .* как универсальный образец (он совпадает со всем), чтобы запретить инструмент целиком

У каждого запрещающего хука три настройки:

  • Образец (Pattern) — текст или шаблон, с которым сравнивается ввод инструмента
  • Регулярное выражение (Regex) — включите, чтобы образец обрабатывался как регулярное выражение — язык поиска по шаблону; регистр букв при этом не важен. Когда выключено, образец ищется как обычный фрагмент текста.
  • Сообщение (Message) — текст, который увидит пользователь, когда хук сработает

Выполняемые хуки

Выполняемый хук перед действием запускает команду оболочки. Он получает данные о вызове инструмента (в формате JSON — структурированном виде данных) и может вернуть ответ, который повлияет на поведение Claude Code.

  • Команда (Command) — команда оболочки для запуска. Доступна переменная окружения $CLAUDE_PROJECT_DIR — в ней лежит полный путь к проекту.

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

Хуки сгруппированы по событиям. К одному событию можно привязать несколько хуков — для разных инструментов:

  • PreToolUse — срабатывает перед выполнением инструмента. Здесь задают запреты и команды предварительной проверки. Доступные инструменты: Agent, Bash, Edit, Write, Read, Glob, Grep, WebFetch, WebSearch, NotebookRead, NotebookEdit и другие.
  • UserPromptSubmit — срабатывает, когда пользователь отправляет сообщение ИИ. Удобно, если ввод нужно проверить или изменить до обработки.

Диалог хуков

Диалог хуков можно открыть из главного меню. Он устроен по событиям:

  • Слева выберите событие — «Перед использованием инструмента» (PreToolUse) или «Отправка пользователем» (UserPromptSubmit)
  • Инструменты внутри события перечислены по алфавиту — выберите нужный, чтобы увидеть его хуки
  • Добавьте хук через форму: выберите тип (запрещающий или выполняемый) и заполните поля
  • Нажмите «Сохранить» — настройки запишутся в .pastukhov/hooks.yml

Распространённые случаи использования

Предотвращение ручной сборки и линтинга

Сборки запускаются автоматически при изменении файлов, поэтому агенту не нужно собирать проект, проверять код или запускать его вручную. Создайте запрещающие хуки для инструмента Bash в событии PreToolUse — на каждую команду, которую агент может попытаться выполнить:

  • Образец: dotnet build — сообщение: «Не собирайте проекты вручную — это делается автоматически»
  • Образец: npm run build — сообщение: «Не собирайте проекты вручную — это делается автоматически»
  • Образец: npm run link — сообщение: «Не линтуйте проекты вручную — это делается автоматически»
  • Образец: npx svelte-check — сообщение: «Не линтуйте проекты вручную — это делается автоматически»
  • Образец: npm run check — сообщение: «Не линтуйте проекты вручную — это делается автоматически»
  • Образец: npm run dev — сообщение: «Не запускайте проекты вручную — это делается автоматически»
  • Образец: dotnet run — сообщение: «Не запускайте проекты вручную — это делается автоматически»

Без таких хуков агент регулярно запускает сборку и проверки после каждого изменения файла — тратя время и токены на то, что система сборки уже делает сама. Это самое выгодное применение хуков в Pastukhov Agent.

Файл конфигурации

Все правила хранятся в файле .pastukhov/hooks.yml. Структура простая: событие → инструмент → список хуков:

preToolUse:
  Bash:
    - type: deny
      pattern: "dotnet build"
      message: "Don't build projects manually - it's done automatically"
    - type: deny
      pattern: "npm run build"
      message: "Don't build projects manually - it's done automatically"
    - type: deny
      pattern: "npm run link"
      message: "Don't lint projects manually - it's done automatically"
    - type: deny
      pattern: "npx svelte-check"
      message: "Don't lint projects manually - it's done automatically"
    - type: deny
      pattern: "npm run check"
      message: "Don't lint projects manually - it's done automatically"
    - type: deny
      pattern: "npm run dev"
      message: "Don't start projects manually - it's done automatically"
    - type: deny
      pattern: "dotnet run"
      message: "Don't start projects manually - it's done automatically"
userPromptSubmit: {}

Сохранённые в диалоге правила автоматически передаются собственной системе хуков Claude Code: определения превращаются в формат JSON и записываются в .claude/settings.local.json. Хуки действуют со следующего обращения к ИИ в чате; уже запущенные сеансы работают со старыми правилами до отправки нового сообщения.

Устранение неполадок

  • Хук не срабатывает — проверьте, что он сохранён и передан Claude Code: нажмите «Сохранить» в диалоге и убедитесь, что файл .claude/settings.local.json обновился. Правила вступают в силу при следующем сообщении — идущий разговор продолжает использовать старые.
  • Регулярное выражение не срабатывает — поиск по регулярному выражению не различает регистр букв. Убедитесь, что образец учитывает все варианты ввода, и при необходимости проверьте его в онлайн-тестере регулярных выражений.
  • Выполняемый хук завершается без результата — у команд хуков есть тайм-аут 60 секунд: если команда работает дольше, она прерывается. Проверьте синтаксис команды и убедитесь, что она доступна в системном пути (PATH).
  • Ошибка сохранения YAML — если диалог показывает ошибку формата, проверьте, что в строках образцов нет специальных символов YAML без правильных кавычек. Текст ошибки появляется в нижней части диалога.

← MCP-серверы

Скрипты →