Управление моделями через хуки

Хуки — это «жёсткие правила», которые Pastukhov Agent навязывает модели: если навыки и файл CLAUDE.md объясняют агенту, как нужно работать, то хуки просто не дают ему сделать нежелательное действие. Самое полезное применение хуков — запретить модели запускать сборку и проверку кода вручную. Автоматическая система сборки уже делает это сама, быстрее и без лишнего расхода, поэтому каждая ручная попытка модели — это потерянное время и деньги.

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

Хуки сгруппированы по событиям — моментам, когда они срабатывают. Pastukhov Agent поддерживает два события:

PreToolUse — срабатывает перед выполнением любого инструмента (действия модели). Здесь задаются запреты и подготовительные команды. Хук можно привязать к конкретному инструменту: Bash (команды в терминале), Edit и Write (правка и создание файлов), Read, Glob, Grep (поиск и чтение), Agent (запуск другого агента), NotebookEdit и другие
UserPromptSubmit — срабатывает, когда вы отправляете модели сообщение. Используется, чтобы проверить или изменить ваш запрос до начала обработки

Хуки запрета

Хуки запрета блокируют выполнение инструмента, сравнивая его входные данные с заданным шаблоном. Для команд терминала (Bash) шаблон сравнивается со строкой команды. Для остальных инструментов используется шаблон .* (подходит под всё) — так инструмент запрещается целиком.

Каждый хук запрета имеет три основных поля:

Pattern (шаблон) — текст или маска поиска, с которой сравниваются данные инструмента
Regex — если включено, шаблон понимается как регулярное выражение (гибкая маска, не различающая регистр букв), если выключено — как обычная подстрока, которую нужно найти в тексте
Message (сообщение) — текст отказа, который увидите вы и модель, когда хук сработает

Хуки выполнения

Хуки выполнения запускают команду в терминале перед выполнением инструмента. Команда получает данные о вызове инструмента через стандартный ввод в формате JSON (структурированный вид данных) и может вернуть ответ, который повлияет на поведение модели. В команде доступна переменная окружения $CLAUDE_PROJECT_DIR — путь к папке вашего проекта.

Запрет ручных сборок

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

preToolUse:
  Bash:
    # сборка (компиляция) проекта
    - type: deny
      pattern: "dotnet build"
      message: "Не собирайте проект вручную — это делается автоматически"
    - type: deny
      pattern: "npm run build"
      message: "Не собирайте проект вручную — это делается автоматически"
    # проверка кода (линтеры, проверка типов)
    - type: deny
      pattern: "npm run lint"
      message: "Не проверяйте код вручную — это делается автоматически"
    - type: deny
      pattern: "npx svelte-check"
      message: "Не проверяйте код вручную — это делается автоматически"
    - type: deny
      pattern: "npm run check"
      message: "Не проверяйте код вручную — это делается автоматически"
    # запуск проекта
    - type: deny
      pattern: "npm run dev"
      message: "Не запускайте проект вручную — это делается автоматически"
    - type: deny
      pattern: "dotnet run"
      message: "Не запускайте проект вручную — это делается автоматически"
userPromptSubmit: {}

Когда хук запрета блокирует команду, модель получает сообщение об отказе и исправляет поведение. За одну сессию это экономит десятки лишних действий — а значит, и заметные деньги. Начинать всё же стоит с настроек и файла CLAUDE.md, чтобы модель реже пыталась делать лишнее сама, а хуки оставить как «последний рубеж»: они ловят модель тогда, когда она забывает о правилах — например, в длинном или сильно уплотнённом разговоре.

Как хуки попадают в Claude Code

Хуки хранятся в файле .pastukhov/hooks.yml — читаемый текстовый файл с простым синтаксисом. Pastukhov Agent автоматически переносит их в собственную систему хуков Claude Code: переводит настройки в нужный формат и записывает их в файл .claude/settings.local.json. Хуки вступают в силу при следующем вашем сообщении в чате.

Синхронизация происходит так:

При запуске программы и после каждого сохранения файла служба хуков читает настройки из YAML
Каждый хук переводится в формат Claude Code, при этом автоматически подставляется путь к исполняемому файлу приложения
Хуки с одинаковой командой объединяются, чтобы не было конфликтов
Готовые настройки записываются в .claude/settings.local.json
Уже запущенные сессии продолжают работать со старыми хуками до следующего вашего сообщения

Исполняемый файл, который обрабатывает хуки, программа находит сама: рядом с запущенным процессом, в каталоге приложения, а в крайнем случае — через команду запуска dotnet Agent.dll.

Другие цели проверки

Кроме запрета ручных сборок, хуки решают и другие задачи:

Защита от опасных команд — запрет rm -rf (удаление папок со всем содержимым), принудительной отправки в git и других операций, повреждение от которых нельзя отменить, даже внутри изолированного окружения
Соблюдение правил проекта — запрет записей в конкретные защищённые файлы, запрет правки файлов настроек или изменений в тестовых данных
Своя логика проверки — хуки выполнения могут запускать нужную команду перед каждым действием модели: проверку перед отправкой в git, контроль форматирования или собственные защиты

Настройки проверяются автоматически при каждом сохранении hooks.yml: программа предупредит о неизвестных событиях и свойствах, а в сообщении об ошибке укажет нужный раздел документации .pastukhov/README.md.

Полезные приёмы

Всегда запрещайте ручные сборки, если настроены автоматические — это самая полезная конфигурация хуков. Добавьте правила запрета для каждой команды сборки и проверки, которую модель может попробовать
Простые шаблоны — простой поиск — pattern: "npm run build" с regex: false ловит любую команду, содержащую эту фразу, в том числе с дополнительными параметрами
Сложные шаблоны — маски поиска — включайте regex: true, когда нужно записать шаблон с учётом разных вариантов, например rm\s+-rf (удаление с любым количеством пробелов)
Проверяйте хуки после сохранения — новые правила вступают в силу при следующем вашем сообщении. Отправьте тестовое сообщение и убедитесь, что хук блокирует нужные команды

Полный справочник по хукам — в разделе Хуки. О системе сборки, которую хуки защищают от ручного запуска, читайте в Сборка и развёртывание. Об изоляции окружения, которая делает хуки дополнительной защитой, а не единственным барьером, — в разделе Изоляция Docker и пропуск разрешений.

← Изоляция Docker и пропуск разрешений

Аналитика и контроль →