20+ событий hooks — полная карта

Почему это важно именно вам

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

Представьте типичный рабочий сценарий: вы попросили Claude разобрать отчёт, он начал читать файлы, что-то записал, сессия завершилась. Вы об этом узнали по результату. Hooks дают возможность узнавать о каждом шаге — или влиять на него. Хотите, чтобы перед каждым изменением файла создавалась резервная копия? Это одно событие. Хотите, чтобы после завершения долгой задачи в Telegram пришло уведомление? Другое событие. Хотите запретить Claude обращаться к определённым папкам? Третье.

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

Что это такое

Хук — это реакция на событие. Событие — это момент в жизни Claude Code: пользователь нажал Enter, Claude взял инструмент, сессия завершилась. Между вами и этим моментом Claude Code вставляет точку, в которую вы можете поместить свою команду или скрипт.

Хорошая аналогия из менеджмента — система уведомлений в CRM. Сделка перешла в статус «закрыта» — система автоматически отправляет письмо клиенту, ставит задачу бухгалтеру, записывает в журнал. Никто не нажимал эти кнопки руками. То же самое делают hooks в Claude Code: событие произошло — выполняется заранее прописанное действие.

Важная деталь: события в hooks делятся на две роли — наблюдатель и контролёр. Наблюдающий хук запускается и не влияет на то, что Claude делает дальше: он может что-то записать, отправить уведомление, но Claude всё равно продолжает работу. Контролирующий хук может остановить действие: если скрипт вернул код 2 — Claude не выполнит то, что собирался сделать. Код 1 и любой другой ненулевой блокировкой не считаются: это «не блокирующая ошибка» — действие всё равно выполнится, а Claude Code запишет сбой хука в лог.

Все события настраиваются в файле settings.json в разделе hooks. Структура одна и та же: имя события, матчер (к чему применять — не обязательно), команда (что запустить). О синтаксисе подробнее — в Дне 41. Здесь нас интересует только карта: какие события существуют и зачем они нужны.

Как работает на практике

Разобьём все события на четыре группы. Внутри каждой — конкретные случаи применения для директора.

Группа 1. Сессионные события

Это события, которые происходят один раз за сессию: в начале и в конце. Их три.

SessionStart — срабатывает, когда вы запускаете claude и сессия открывается. Claude ещё ничего не сделал, но уже готов. Это момент для подготовки среды: можно загрузить актуальные данные, проверить состояние сервисов, вывести напоминание о текущих приоритетах.

Практический пример для директора: каждое утро при запуске Claude в папке проекта — автоматически проверить, есть ли новые файлы в папке «Входящие», и вывести их список в начало сессии. Не нужно помнить, не нужно проверять руками.

SessionEnd — срабатывает, когда сессия завершается (вы нажали Ctrl+D или написали /exit). Это момент для уборки и сохранения: записать итоги работы, отправить уведомление, очистить временные файлы.

Практический пример: после каждой сессии — автоматически дописать в журнал рабочего дня строку с датой, временем и темой последней задачи. Месяц работы — и у вас есть хронология без ручного ведения.

Setup — событие, которое срабатывает только по вашему явному запросу: claude --init-only, claude -p --init или claude -p --maintenance. На обычном старте оно не срабатывает. Отличается от SessionStart тем, что не срабатывает при обычном старте вовсе — только когда вы сами запросили инициализацию или обслуживание из CI или скрипта. Используется для одноразовой настройки: создать структуру папок, проверить наличие нужных файлов конфигурации, вывести инструкцию «как здесь работать».

Группа 2. События per-turn (на каждый ход)

Это события, которые срабатывают при каждом обмене сообщениями. Их два.

UserPromptSubmit — срабатывает сразу после того, как вы нажали Enter и отправили сообщение, но до того, как Claude начал отвечать. Это ваша последняя точка контроля до ответа: можно проверить содержимое запроса, добавить к нему контекст, заблокировать определённые фразы.

Практический пример: автоматически добавлять к каждому запросу строку с текущей датой и временем, чтобы Claude всегда знал «сейчас». Или — проверять, не содержит ли запрос конфиденциальные данные, которые не следует отправлять наружу (хотя Claude Code работает локально, это может быть важно при использовании внешних MCP-серверов).

Stop — срабатывает, когда Claude завершил ответ и остановился. Не в середине процесса, а именно когда весь ответ готов. Это хорошая точка для уведомлений: «задача завершена, посмотри результат».

Практический пример для длинных задач: запустили Claude анализировать большой документ, сами ушли на встречу. Хук на Stop отправляет уведомление в Telegram, когда работа закончена. Вернулись со встречи — увидели сообщение — открыли результат.

Группа 3. Инструментальные события

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

PreToolUse — срабатывает до того, как инструмент выполнился. Claude решил, что нужно прочитать файл — но ещё не прочитал. Здесь можно разрешить или запретить действие.

Это событие с матчером — вы можете указать, на какой инструмент реагировать. Инструментов в Claude Code много: Read (чтение файла), Write (запись), Edit (редактирование), Bash (выполнение команды), WebFetch (загрузка страницы), WebSearch (поиск), Agent (запуск субагента; старое имя Task работает как псевдоним) и другие.

Практические примеры:
- PreToolUse на Write — перед каждой записью файла создать резервную копию в папке _backup/. Файл ещё не изменён, но копия уже есть.
- PreToolUse на Bash — вывести запрос на подтверждение при запуске любой команды, которая содержит rm или DELETE. Claude скажет «хочу выполнить вот это» — вы ответите да или нет.
- PreToolUse на WebFetch — записывать в журнал все URL, к которым обращается Claude. Удобно, если хотите знать, какие источники он использовал.

PostToolUse — срабатывает после того, как инструмент выполнился и вернул результат. Claude уже прочитал файл, уже запустил команду — теперь у вас есть и действие, и его результат.

Практические примеры:
- PostToolUse на Write — после каждого изменения файла записывать в лог: «такого-то числа в такое-то время изменён файл X». Через неделю у вас есть история изменений.
- PostToolUse на Bash — если команда завершилась с ошибкой (ненулевой код), отправить уведомление. Claude может продолжить работу, но вы будете знать, что что-то пошло не так.
SubagentStop — отдельное событие: срабатывает, когда завершает работу субагент. Полезно, чтобы копировать его результат в общий журнал проекта.

PermissionRequest — специальное событие для запросов разрешений. Когда Claude хочет сделать что-то, на что у него нет явного разрешения, он запрашивает подтверждение. Это событие срабатывает в момент такого запроса, до того как вы ответили.

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

Группа 4. Асинхронные события

Это события, которые не привязаны к конкретному действию пользователя или Claude, а срабатывают по внешним триггерам.

FileChanged — срабатывает, когда в отслеживаемой директории изменился файл. Не Claude изменил, а кто-то другой — или другая программа. Вы работаете в одной сессии, коллега изменил общий файл — Claude может на это отреагировать.

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

Notification — срабатывает, когда Claude Code просит вашего внимания: ждёт разрешения, простаивает, MCP-сервер открыл диалог, фоновая сессия завершилась. Это не сообщения о ходе работы. Хук позволяет перехватить уведомление и направить его куда нужно — в Telegram, в лог, в систему уведомлений macOS.

Практический пример: Claude работает в фоновом режиме (флаг --bg). Все его информационные сообщения — в Telegram, чтобы вы видели прогресс на телефоне, не открывая терминал.

Основные события

Частые ошибки

Ошибка 1. Поставить тяжёлый скрипт на часто срабатывающее событие

PostToolUse может сработать десятки раз за одну сессию — Claude читает файлы, запускает команды, снова читает. Если на каждый вызов запускать скрипт, который занимает секунду — сессия замедляется в разы. Правило: на PreToolUse и PostToolUse ставьте только быстрые операции (запись строки в файл, простая проверка). Медленные сценарии (отправка в сеть, сложные вычисления) — только на Stop или SessionEnd.

Ошибка 2. Перепутать PreToolUse и PostToolUse

PreToolUse — инструмент ещё не запустился. PostToolUse — уже запустился и вернул результат. Если хотите сделать резервную копию файла перед его изменением — это PreToolUse. Если хотите записать в лог, что файл изменился — это PostToolUse. Путаница здесь приводит к тому, что резервная копия создаётся уже после изменения (то есть содержит новое содержимое, а не старое) или лог пишется до выполнения операции.

Ошибка 3. Игнорировать матчеры и вешать хук на все инструменты сразу

Если написать хук на PreToolUse без матчера — он будет срабатывать при каждом использовании любого инструмента. При активной сессии это может быть 50-100 вызовов. Почти всегда нужен конкретный инструмент: Write, Bash, WebFetch. Матчер сужает применение и убирает лишний шум. Матчеры разбираются подробно в Дне 43.

Ошибка 4. Использовать блокирующий хук на событие без проверки логики

Хук на PreToolUse, который возвращает код 2 при определённых условиях, блокирует действие. Если условие написано неточно — Claude не сможет делать базовые операции. Типичный случай: хотели заблокировать запись в системные папки, написали проверку на / в начале пути — и заблокировали всё, включая /Users/имя/проект. Всегда тестируйте блокирующие хуки на конкретных примерах перед боевым использованием.

Когда нужно / когда нет

Используйте hooks, когда:
- Есть повторяющийся контроль, который надоело делать руками — разрешения, резервные копии, подтверждения
- Нужны уведомления о завершении долгих задач — особенно при работе с --bg
- Хотите автоматический журнал: что Claude делал, когда, с какими файлами
- Хотите ограничить зону работы Claude — запретить выход за папку проекта
- Нужна реакция на внешние изменения — файл обновился, начать обработку

Не используйте hooks, когда:
- Задача разовая — проще дать инструкцию руками, чем настраивать хук
- Нет понимания, что именно происходит в сессии — сначала поработайте без hooks, посмотрите на поведение
- Хотите изменить то, что Claude думает или отвечает — hooks влияют на действия, не на мышление; для этого нужны CLAUDE.md и инструкции в промпте
- Скрипт сложный и требует длительной разработки — начните с простого, постепенно усложняйте

Связь с другими уроками

День 41 — что такое hooks и как настроить первый. Там разобрана базовая механика: структура settings.json, синтаксис хука, как запустить первый скрипт на событие. Если день 42 — ваша первая встреча с hooks — начните с дня 41.

День 43 — матчеры: как настроить хук на конкретный инструмент. Мы упоминали матчеры в этом уроке несколько раз: они позволяют применить хук только к Write, только к Bash, только к определённому инструменту. В дне 43 разберём синтаксис и типичные паттерны: как написать матчер для файлов с расширением .xlsx, для команд с определённым ключевым словом.

День 48 — хук-аудитор: автоматический журнал действий Claude. Практический урок: строим систему логирования на базе PostToolUse и SessionEnd. После него у вас будет работающий аудитный журнал — что Claude делал, когда, в каких файлах. Понимание карты событий из сегодняшнего урока — обязательная база для этого.

Задание на сегодня

Откройте файл settings.json вашего проекта (или ~/.claude/settings.json для глобальных настроек) и найдите раздел hooks. Если его нет — это нормально, в большинстве новых установок он пустой.

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

Критерий «выполнено»: вы можете назвать три события из разных групп и объяснить, чем они отличаются, без возврата к этому уроку.

Это подготовка к дню 43, где мы будем подключать конкретные хуки с матчерами.

Резюме

• События hooks делятся на четыре группы: сессионные (SessionStart, SessionEnd, Setup), per-turn (UserPromptSubmit, Stop), инструментальные (PreToolUse, PostToolUse, PermissionRequest) и асинхронные (FileChanged, Notification)
• PreToolUse и Stop блокируют кодом 2; у PermissionRequest код выхода не учитывается — отказ выдаётся только через JSON, остальные — только наблюдают
• Самое популярное событие для уведомлений — Stop; для резервных копий — PreToolUse на Write; для журнала — PostToolUse на нужный инструмент
• Тяжёлые операции на часто срабатывающих событиях замедляют сессию — используйте матчеры и ставьте медленные скрипты на Stop или SessionEnd
• Hooks контролируют действия Claude, не его мышление — для изменения поведения и качества ответов нужны CLAUDE.md и промпты