claude-hook-utils: хуки для Claude Code без бойлерплейта

На GitHub появился claude-hook-utils — Python-пакет для построения хуков Claude Code. Задача конкретная: убрать бойлерплейт, который неизбежно возникает при каждом новом хуке — парсинг JSON из stdin, валидация структуры входных данных, форматирование ответа в нужную схему, обработка ошибок. Пакет ставится через pip install claude-hook-utils, не тянет тяжёлых зависимостей.

Контекст

Claude Code hooks — официальный механизм расширяемости агента. Он позволяет запускать произвольные скрипты в ключевых точках цикла: PreToolUse (до выполнения инструмента), PostToolUse (после), UserPromptSubmit (при отправке промпта), SessionStart (при старте сессии). Хуки конфигурируются в .claude/settings.json и вызываются как обычные shell-команды — язык произвольный, Python — очевидный выбор.

Без утилит каждый хук — это один и тот же шаблонный код. Распарсить stdin, достать нужные поля, проверить структуру, вернуть ответ в формате hookSpecificOutput. Умножьте на пять хуков в проекте — и получите несколько сотен строк инфраструктурного кода, который не делает ничего интересного.

Появление claude-hook-utils — признак взросления экосистемы. Год назад разработчики пробовали Claude Code как инструмент. Сейчас они строят вокруг него слои абстракции. Паттерн знакомый: так развивались экосистемы вокруг Kubernetes, GitHub Actions, VSCode — сначала официальный API, потом community-библиотеки, потом стандарты де-факто.

Аналитика

Хуки — это не удобство. Это инфраструктурный контроль над поведением агента на уровне ниже промптов. Запрет записи в определённые директории, обязательная структура файлов, аудит всех действий — всё это инкапсулируется в хуки и применяется системно, вне зависимости от того как пользователь формулирует задачи. Это сдвиг от промпт-инженерии к агент-инженерии: вы управляете не только входом, но и точками принятия решений внутри цикла.

Дизайн пакета отражает правильные принципы для production-инструментов. Fail-open при ошибках — если хук упал, агент продолжает работу, а не блокируется. Типизированные датаклассы для входных данных — меньше ошибок при обращении к полям. Явный контроль: вы сами решаете когда вернуть allow, deny или ask. Встроенный HookLogger пишет JSONL — структурированные логи с session_id, именем инструмента, путём к файлу, итоговым решением.

Хуки с правильным логированием — это observability для AI-агентов. Без этого непонятно что агент делал, почему остановился, какие файлы трогал. В production это не опция.

Важная деталь: with_updated_input() позволяет модифицировать параметры инструмента до его выполнения. Автоматическое исправление пути, нормализация регистра директорий, подстановка правильного контекста — агент даже не узнает что его входные данные были скорректированы. Это уровень контроля, который раньше требовал патчинга системных промптов или сложных wrapper-скриптов.

Кейсы применения в бизнесе

B2B-SaaS стартап с кодовой базой на Laravel/Vue: PreToolUse-валидаторы пишутся за несколько часов. Хук проверяет что Vue-компоненты соблюдают порядок тегов template/script/style, PHP-контроллеры находятся в app/Http/Controllers/, запрещённые паттерны вроде FormRequest не пролезают в код. Claude Code становится не просто помощником, а системой с жёсткими рейлами — как линтер, только с обратной связью на уровне агента. Разработчик получает понятное объяснение почему действие заблокировано, а не молчаливый отказ.

Корпорация с legacy и требованиями к аудиту: PostToolUse-хуки логируют каждое изменение файла с session_id, tool_name, путём, временной меткой в JSONL. Готовый audit trail без дополнительных интеграций. SessionStart-хук при запуске проверяет переменные окружения, инициализирует нужный контекст, убеждается что разработчик работает с правильной веткой. Политика применяется ко всей команде через единый .claude/settings.json в репозитории.

SMB и локальный бизнес в КР/СНГ, который использует Claude Code для внутренней разработки: хуки — это политика безопасности, которую вы определяете один раз. Запрет записи в .env, обязательный формат коммит-сообщений, уведомления при изменении критичных конфигов. Если вы отдаёте задачи агенту и хотите контролировать что именно он может менять — хуки дешевле и надёжнее чем ручной review каждого действия.

Кейсы в личной жизни

Разработчик: напишите PreToolUse-хук который блокирует хардкод API-ключей, запрещает console.log в production-коде, проверяет именование файлов по вашим конвенциям. 20 строк Python — и агент останавливается сам при нарушении правил, не дожидаясь code review.

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

Студент или фрилансер, который изучает Claude Code: claude-hook-utils — чистый учебный материал. Код открытый, паттерны типичные (базовый класс плюс override нужных методов), архитектура прозрачная. Разобраться как устроены хуки на практике — задача на вечер. Попутно получите рабочий инструмент для своих проектов.

Как применить сегодня

• Установите пакет: pip install claude-hook-utils. README на GitHub содержит готовые примеры валидаторов для PHP, Vue, Laravel — берите как шаблон.
• Начните с одного PreToolUse-хука: запрет записи в .env файлы. Это 10–15 строк кода — хороший первый шаг без риска сломать рабочий процесс.
• Подключите хук в .claude/settings.json через matcher "Write|Edit" — он будет срабатывать именно при операциях записи.
• Добавьте HookLogger с JSONL-выводом. Через неделю у вас будет история всех решений агента — понятно что он делал, почему блокировал или пропускал.
• Если работаете в команде — вынесите хуки в отдельный репозиторий или пакет, устанавливайте как dev-зависимость. Единая политика для всех, версионируется вместе с кодом.