Claude Code Function Hooks: Полный гид по мидлварам и контролю агента

Claude Code Function Hooks: кратко о главном

🎯 О чём этот конспект: Разбор ключевого обновления Claude Code — хуков-функций (Function Hooks), работающих по принципу Express.js middleware. Видео объясняет, как перехватывать и модифицировать команды агента, заменять инструменты, защищать секреты через энтропию, кастомизировать CLI-интерфейс живыми виджетами и подключать фоновые модели (Haiku) для озвучки и проверок.

👤 Кому будет полезно: Вайбкодерам, разработчикам и лидам проектов, активно использующим Claude Code в терминале и желающим добиться 100% детерминированного поведения агента без утечек данных и сломанных веток.

✨ Что получите: Готовую инструкцию по активации plugin-authoring, шаблоны хуков для санитизации секретов, перехвата npm-команд, кеширования веб-запросов, мониторинга деплоев в Vercel и интеграции внешних LLM в процесс разработки.

1. Детерминированный контроль Claude Code: почему текстовых правил в CLAUDE.md недостаточно

Контекст: При длительных сессиях контекстное окно терминального агента забивается выводами команд, диффами файлов и системными логами. Инструкции из файлов CLAUDE.md со временем размываются (prompt fading), и модель начинает забывать запреты на деструктивные действия — например, удаление баз данных Supabase или веток main. Базовые шелл-хуки (shell scripts) решали часть проблем, но они были изолированными скриптами без доступа к состоянию сессии. Они не могли модифицировать входящий промпт, переписывать параметры запускаемых команд, хранить память между вызовами или отрисовывать интерактивный UI. Хуки-функции превращают Claude Code из хаотичного исполнителя в строгий детерминированный пайплайн.

Тайминг: ▶ 00:52, ▶ 01:12, ▶ 08:58

Выгода: 100% гарантия невозможности случайного выполнения деструктивных операций (DROP TABLE, rm -rf, удаление прод-проекта) независимо от степени переполнения контекста.

Как применить:

• Шаг 1: Анализ рисков проекта — Терминал — Выделите критические CLI-утилиты, используемые в проекте (Supabase, Vercel, AWS CLI, Prisma), и перечислите деструктивные флаги (--force, db push --accept-data-loss, delete).
• Шаг 2: Создание защитного хука через Claude — Claude Code — Запустите Claude Code и сформулируйте задачу на создание хука-перехватчика, который будет блокировать опасные вызовы до их передачи в системный шелл.

Сделай хук для перехвата Bash-команд, который проверяет вызовы supabase CLI. Если команда содержит destructive операции вроде "db reset", "projects delete" или "branches delete", немедленно блокируй выполнение с предупреждением.

Результат: Попытки Claude Code или пользователя вызвать деструктивную команду отсекаются на уровне пре-валидации шелла.

2. Архитектура Function Hooks: паттерн Middleware для AI-агента

Контекст: Function Hooks в Claude Code работают идентично middleware в Express.js: они получают контекст события, объект вызова инструмента и функцию next(). Это позволяет не просто разрешать или запрещать выполнение (allow / block), но и модифицировать аргументы на лету (rewriting), возвращать ответ раньше времени из кеша (short-circuiting) и сохранять состояние между вызовами через store. Хуки хранятся в проекте в директории .claude в виде TypeScript-файлов с метаданными в JSON.

Тайминг: ▶ 01:39, ▶ 01:57, ▶ 02:30

Выгода: Полная адаптация поведения Claude Code под инфраструктуру команды без необходимости форкать или патчить сам CLI-клиент.

Как применить:

• Шаг 1: Включение поддержки хуков-функций — Shell — Запустите Claude Code со специальной переменной окружения, которая активирует встроенный скилл plugin-authoring:

CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 claude

• Шаг 2: Реализация подмены пакетного менеджера (Rewriting) — TypeScript — Создайте логику, перехватывающую запуск инструмента Bash. Если команда содержит npm install, хук заменяет её на pnpm install, сохраняя единообразие lockfile в репозитории:

// Пример логики хука в .claude/
export async function onToolCall(event: { tool: string; input: { command: string } }, next: Function) {
  if (event.tool === "Bash" && event.input.command.includes("npm install")) {
    event.input.command = event.input.command.replace("npm install", "pnpm install");
  }
  return next();
}

• Шаг 3: Настройка кеширования веб-запросов (Short-circuiting) — TypeScript — Добавьте проверку во внутренний key-value store хука: если URL уже запрашивался через web_fetch, возвращайте сохранённый HTML без повторного выхода в сеть.

Результат: Автоматическая нормализация команд разработчика и агента (например, замена npm на pnpm) и экономия токенов/времени за счет кеша.

3. Переопределение встроенных инструментов: подмена Web Search на Exa MCP

Контекст: По умолчанию Claude Code использует встроенный веб-поиск (на базе Brave Search), который не всегда выдает качественные технические результаты для сложных стеков. Многие разработчики предпочитают Exa Search через MCP, но агент часто сбивается и упорно вызывает нативный web_search вместо MCP-сервера. С помощью Function Hooks можно создать мидлвар, перехватывающий системный инструмент web_search. Хук проверяет наличие переменной EXA_API_KEY: при её наличии запрос перенаправляется в Exa API, а в случае сбоя или отсутствия ключа запрос элегантно откатывается (fallback) на стандартный web_search.

Тайминг: ▶ 02:10, ▶ 02:40, ▶ 02:64

Выгода: Использование поисковой выдачи Exa без необходимости вручную напоминать агенту вызывать нужный MCP-инструмент. Возможность пустить весь web_fetch через корпоративные прокси для обхода блокировок Cloudflare.

Как применить:

• Шаг 1: Активация плагина переопределения поиска — Claude Code CLI — В сессии с включенным флагом вызовите генерацию хука для перехвата поиска:

/plugin-authoring

• Шаг 2: Описание логики фоллбека — Промпт — Передайте агенту ТЗ на перехват инструмента:

Сделай function hook для перехвата инструмента web_search. Проверь наличие EXA_API_KEY в окружении. Если ключ есть — сделай HTTP-запрос в Exa API с параметрами поиска и верни результаты напрямую в сессию, пропуская стандартный web_search. Если ключа нет или запрос вернул ошибку — вызови стандартный web_search.

• Шаг 3: Проверка и перезагрузка плагина — Claude Code CLI — Примените изменения командой:

/reload plugins

Результат: Все обращения агента к поиску прозрачно обслуживаются через Exa API без изменения поведения пользователя.

4. Защита секретов: перехват API-ключей, энтропия и In-Memory Proxy

Контекст: Частая проблема при работе с CLI-агентами — случайный вывод токенов, ключей и паролей в консоль (например, при cat .env или выводе логов curl). После этого секрет попадает в контекст сессии (transcript), который сохраняется на диске и может утечь. Хуки-функции позволяют реализовать архитектуру, аналогичную Infisical Agent Proxy. Хук на входе анализирует энтропию строк и регулярные выражения (почты, IP-адреса, токены вида sk-ant-*), вырезает найденный секрет, сохраняет его в защищенное хранилище store, а агенту передает псевдоним (ID секрета, например $SECRET_1). Когда агент отправляет запрос во внешний API, хук на выходе заменяет $SECRET_1 на реальный ключ прямо перед сетевым вызовом.

Тайминг: ▶ 02:90, ▶ 03:20, ▶ 03:70, ▶ 04:10

Выгода: Секреты физически отсутствуют в текстовом файле транскрипта сессии и системном контексте Claude, но агент сохраняет возможность делать авторизованные запросы.

Как применить:

• Шаг 1: Генерация плагина санитизации контекста — Claude Code CLI — Попросите плагин-ассистента создать систему ретракции:

/plugin-authoring
Создай function hook для автоматической санитизации транскрипта сессии. 
1. Хук должен сканировать ввод пользователя и вывод Bash на высокую энтропию (API-ключи), а также форматы email и IP-адресов.
2. При обнаружении секрета он заменяет его на UUID-плейсхолдер и сохраняет реальное значение в in-memory store.
3. При выполнении исходящих сетевых вызовов хук должен прозрачно подставлять реальный секрет из store вместо ID.

• Шаг 2: Проверка файлов конфигурации — VS Code / Терминал — Убедитесь, что в директории .claude/ появились файлы:
  • plugins.json
  • transcript_redactor.json
  • hooks.json
  • redact.ts (содержит логику анализа энтропии и маппинга)
• Шаг 3: Тестирование защиты — Claude Code CLI — Отправьте агенту тестовый ключ и команду:

Вот мой ключ: sk-ant-api03-test-key-demo-12345. Сделай тестовый curl запрос к API Anthropic и верни статус.

• Шаг 4: Анализ транскрипта — Терминал — Проверьте вывод: в окне терминала отобразится redacted-ID, а в сеть уйдет реальный ключ.

Результат: Устранена опасность утечки credentials при публикации логов сессий или коммите истории работы агента.

5. Кастомизация UI Claude Code: динамические панели и мониторинг Vercel Deploy

Контекст: Function Hooks дают доступ к расширению интерфейса терминального клиента Claude Code. Вы можете создавать интерактивные статус-панели (status lines), строки состояния и кнопки прямо в консоли. Например, после пуша изменений в ветку main разработчик вынужден открывать вкладку браузера или запускать отдельный процесс vercel logs, чтобы понять статус сборки. Хук-функция может перехватывать git-команды деплоя, опрашивать API Vercel и отрисовывать интерактивную строку прямо под строкой ввода промпта со статусами: queued → building → ready и таймером длительности сборки.

Тайминг: ▶ 04:53, ▶ 05:14, ▶ 05:38

Выгода: Полная видимость инфраструктурных процессов (CI/CD, сборки, миграции баз данных) прямо в окне терминала без переключения контекста.

Как применить:

• Шаг 1: Постановка задачи через интерактивное интервью — Claude Code CLI — Запустите модуль создания плагинов с запросом на опрос архитектуры UI:

/plugin-authoring
Сделай UI-хук, который отображает статус деплоя в Vercel рядом со статус-баром промпта:
- Показывай стадию: queued, building, ready.
- Отображай секундомер длительности билда.
- Добавь кнопку скрытия/раскрытия этой панели.
- Панель должна оставаться активной 60 минут после завершения сборки.
Перед кодингом задай мне вопросы и предложи варианты отображения.

• Шаг 2: Конфигурация виджета — Claude Code CLI — Ответьте на вопросы агента о желаемом расположении строк и цветов индикаторов.
• Шаг 3: Проверка в реальном пайплайне — Claude Code CLI — Выполните операцию деплоя:

Включи sale banner на сайте, смерджи ветку в main и запушь.

• Шаг 4: Интерактивный контроль — Консоль — Наблюдайте появление нового статусного ряда с длительностью сборки (например, ready (5m 50s)).

Результат: Терминал получает нативный дашборд фоновых процессов без необходимости использовать сторонние CLI-обертки.

6. Защитные барьеры качества: Dry Run, интерактивные подтверждения и лимит длины файлов

Контекст: LLM часто генерируют монолитные спагетти-файлы по 1000–3000 строк кода вместо модульной структуры. Кроме того, агенты могут запускать опасные скрипты обработки данных без предварительной проверки. Комбинируя метод хука ask (интерактивный вопрос пользователю) и перехват файловых операций, можно навязать агенту жесткие стандарты рефакторинга и безопасного выполнения. Если агент редактирует файл и его объем превышает 1000 строк, хук прерывает операцию и заставляет агента спросить у разработчика разрешение на декомпозицию.

Тайминг: ▶ 06:90, ▶ 07:22, ▶ 07:47, ▶ 08:28

Выгода: Предотвращение деградации архитектуры кодовой базы и защита от запуска непроверенных скриптов миграции данных.

Как применить:

• Шаг 1: Создание хука лимита строк (Refactoring Guard) — Claude Code CLI — Опишите логику контроля размера модулей:

/plugin-authoring
Создай function hook, который срабатывает при каждом редактировании или создании файла. 
Если итоговый файл превышает 1000 строк кода, хук должен вызывать функцию ask() и принудительно спрашивать у меня: "Файл превысил 1000 строк. Хотите разбить его на несколько компактных модулей?". Не продолжай работу без моего ответа.

• Шаг 2: Настройка режима Dry Run для аналитики — Claude Code CLI — Добавьте проверку для скриптов миграции данных:

Создай хук для Bash. Если запускается скрипт из папки /scripts/migrations или аналитический пайплайн, проверяй наличие флага --dry-run. Если флага нет — блокируй команду и выводи в UI красным предупреждением: "Запуск на живой БД запрещен без предварительного dry run".

• Шаг 3: Включение подтверждения отправки email/рассылок — Claude Code CLI — Для нетехнических задач настройте задержку и обязательный таймер предпросмотра контента перед отправкой.

Результат: Кодовая база сохраняет модульность, а опасные операции проходят через обязательный человеческий фильтр (Human-in-the-loop).

7. Мультимодельные пайплайны: интеграция $model (Haiku), Text-to-Speech и аудит-логов

Контекст: Хуки-функции предоставляют системный примитив $model, позволяющий вызывать легковесные и быстрые LLM (например, Claude 3.5 Haiku) прямо внутри жизненного цикла основного агента, не расходуя контекст основной сессии Sonnet. Это открывает возможности для мгновенной суммаризации действий агента с голосовым озвучиванием через нативный Apple Voice / системный TTS, автоматической генерации поисковых тегов для RAG по корпоративной базе знаний и создания квизов перед открытием Pull Request.

Тайминг: ▶ 07:65, ▶ 08:10, ▶ 09:04, ▶ 09:44, ▶ 09:68

Выгода: Фоновый аудит, голосовой фидбек о завершении длительных фоновых задач и автоматическая инъекция корпоративного контекста через HTTP без перегрузки основного контекста сессии.

Как применить:

• Шаг 1: Создание хука голосовой суммаризации (TTS) — Claude Code CLI — Запросите генерацию хука с вызовом вспомогательной модели:

/plugin-authoring
Создай function hook, который срабатывает при завершении каждого шага (turn ends). 
1. Хук берет результат действия и через $model передает его в Haiku с промптом: "Дай краткое резюме изменений в одном предложении".
2. Полученный ответ озвучь через встроенный системный text-to-speech (утилита say в macOS).

• Шаг 2: Тестирование голосового оповещения — Claude Code CLI — Перезагрузите конфигурацию и запустите тестовый промпт:

/reload plugins

Обнови README.md: добавь раздел о системных требованиях.

Система синтезом речи проговорит краткий отчет о выполненном коммите или редактировании.

• Шаг 3: Настройка корпоративного комплаенс-аудита — TypeScript — Добавьте в хук отправку всех событий (tool calls, input, output, execution time) через системную команду $http во внутренний лог-коллектор (Datadog, Elastic, Logstash) для соответствия требованиям PCI-DSS / HIPAA.
• Шаг 4: Защита PR через генерацию квиза — TypeScript — Настройте хук, который перед командой gh pr create генерирует для инженера 3 проверочных вопроса по диффу: агент не запушит код, пока разработчик не подтвердит понимание внесенных изменений.

Результат: Автономный голосовой ассистент, полный корпоративный аудит всех действий агента и страховка от бездумного мерджа сгенерированного кода.

Claude Code Function Hooks: ответы на частые вопросы

В: Чем Function Hooks принципиально отличаются от старых хуков в Claude Code? О: Старые хуки были простыми shell-скриптами: они могли только завершиться с кодом 0 (разрешить) или 1 (запретить). Function Hooks написаны на TypeScript/JavaScript, имеют доступ к объектам сессии, могут перезаписывать аргументы команд на лету, кешировать данные, делать промежуточные вызовы LLM через команду $model, вызывать системные диалоги $ask и динамически модифицировать UI терминала.

В: Где хранятся созданные хуки и как поделиться ими с командой? О: Все хуки сохраняются внутри вашего проекта в директории .claude/ в виде файлов конфигурации (hooks.json, plugins.json) и TypeScript-скриптов логики. Чтобы раскатать их на всю команду, достаточно закоммитить папку .claude/ в общий Git-репозиторий проекта.

В: Не замедляют ли хуки работу Claude Code при постоянных вызовах? О: Локальные проверки (регулярные выражения, замена строк, проверка размера файлов) выполняются за миллисекунды и практически незаметны. Сетевые вызовы (например, обращение к Haiku или Vercel API) работают асинхронно или вызываются только в конце хода (on turn end), не блокируя генерацию основного кода.

В: Безопасно ли хранить токены в in-memory store хука? О: Это существенно безопаснее, чем передавать токены открытым текстом в промпт. В памяти хука они изолированы внутри локального Node.js процесса сессии, не попадают в системный лог transcript.jsonl и не отправляются на серверы Anthropic в теле системного промпта.

В: Можно ли полностью заменить файл CLAUDE.md хуками? О: Не полностью, но большую часть критических запретов и архитектурных правил стоит перенести. В CLAUDE.md следует оставить общую справку по проекту и стилю кода, а все жесткие ограничения (запрет деструктивных команд, лимиты строк, стандарты пакетов) перенести в детерминированные Function Hooks.

В: Как отладить сломанный хук, если он падает с ошибкой? О: Для этого предназначен специальный режим /plugin-authoring. Запустите его внутри сессии и скажите агенту: «Хук X падает с такой-то ошибкой при вызове Bash, помоги отладить». Claude Code прочитает исходники в .claude/ и исправит ошибки сигнатур или асинхронных вызовов.

Claude Code Function Hooks: инструменты и ссылки из видео

• Agentic Coding School — образовательная программа автора по полному циклу разработки с AI-агентами — упомянут в видео.
• Agent Sandboxing Infrastructure — изолированная инфраструктура песочниц для безопасного запуска агентов — упомянут в видео.
• Infisical Agent Proxy — архитектурный паттерн перехвата и подстановки секретов для автономных агентов — упомянут в видео.
• Exa Search MCP — MCP-сервер семантического поиска для LLM — упомянут в видео.

Конспект создан на основе видео «Claude Code Function Hooks» канала Ray Fernando. Все права на оригинальный материал принадлежат авторам. Источник: https://www.youtube.com/watch?v=B-YQANvDOq0