Хуки проверки кода для Codex и Claude Code

Хуки подключают CodeGraph к рабочей сессии Codex или Claude Code. Они добавляют контекст проекта к запросу, проверяют полномочия перед запуском инструмента и сохраняют результаты после его выполнения. Это помогает разработчику работать с актуальным контекстом и видеть, почему операция разрешена или остановлена.

Выберите адаптер для своего клиента. Каждый адаптер имеет свой файл регистрации и набор событий. По файлу регистрации можно проверить, какие обработчики запускает текущая версия.

Выберите нужный адаптер

Для Codex используйте хуки установленного плагина CodeGraph. После обновления плагина начните новую сессию клиента. Для Claude Code проверьте регистрацию в .claude/settings.json и пути к обработчикам в своей рабочей копии.

Подготовьте проверку

Для проверок ниже откройте PowerShell в корне исходного репозитория CodeGraph. Нужны Python и зависимости проекта. Для реального запуска нужен соответствующий клиент, загруженный адаптер и работающая среда выполнения CodeGraph. Настройка подключения описана в руководстве оператора MCP.

Проверьте регистрацию без выполнения обработчиков:

$codexHooks = Get-Content -Raw 'plugins/codegraph/hooks/hooks.json' | ConvertFrom-Json
$claudeHooks = Get-Content -Raw '.claude/settings.json' | ConvertFrom-Json
$codexHooks.hooks.PSObject.Properties.Name
$claudeHooks.hooks.PSObject.Properties.Name
Test-Path -LiteralPath 'plugins/codegraph/bin/codegraph_codex_hook.py'

Ожидаются восемь событий Codex, пять событий Claude Code и True для файла запуска. Этот результат подтверждает регистрацию в исходниках. Затем проверьте загрузку хуков в клиенте по разделам ниже. Команды в локальной .claude/settings.json содержат абсолютные пути рабочего каталога: перед использованием другой рабочей копии проверьте каждый путь. Укажите пути своей рабочей копии.

Жизненный цикл Codex

Текущая регистрация Codex содержит следующие события:

Таймаут события фиксирует эксплуатационное состояние. Прохождение продуктовой задачи определяется SDLC-гейтами.

Жизненный цикл Claude Code

Файл .claude/settings.json регистрирует обработчики SessionStart, UserPromptSubmit, PreToolUse, PostToolUse и Stop из .claude/hooks/.

Общие утилиты хуков читают review_pipeline.fail_open непосредственно из config.yaml. При true обработчик ошибки возвращает пустой ответ. При false он возвращает сообщение Hook Error: BLOCK с кодом ошибки и рекомендуемым действием. Отсутствующий параметр или ошибка чтения конфигурации дают false. Текущая конфигурация репозитория и модель ReviewPipelineConfig задают true. Проверьте значение в своей рабочей копии и обработчик нужного события. Этот параметр задаёт обработку ошибок. Полномочия проверяет политика запуска инструмента, а результат ревью подтверждают отчёт и связанные артефакты.

Модель отказа

• Используйте fail-closed для проверки полномочий, опасных инструментов, обязательного согласования, завершения задачи и финансовых ограничений. При сбое этих проверок операция останавливается.
• Используйте fail-open для дополнительного контекста и телеметрии, когда клиент может продолжить работу без этих данных. Сохраните диагностику сбоя для последующей проверки.
• Код возврата хука фиксирует результат его запуска. Для приёмки задачи или релиза сохраните отчёт ревью и связанные артефакты.
• Не помещайте в диагностику секреты, токены провайдера и неограниченные фрагменты исходников.
• Ограничивайте таймаут и возвращайте способ восстановления с названием упавшего этапа.

Как проверить хуки Codex

1. Откройте plugins/codegraph/hooks/hooks.json и убедитесь, что нужное событие зарегистрировано.
2. Проверьте команду ${PLUGIN_ROOT}/bin/codegraph_codex_hook.py или её Windows-вариант и наличие файла обработчика.
3. После установки или обновления плагина начните новую сессию клиента. Изменение исходников не обновляет уже установленный кэш.
4. Вызовите минимальное подходящее событие и изучите структурированную диагностику.
5. Если PreToolUse запретил управляемую операцию, исправьте указанные в диагностике границы задачи, полномочия, согласование или привязку сессии.

Как проверить хуки Claude Code

1. Убедитесь, что .claude/settings.json регистрирует событие и ссылается на существующий файл в .claude/hooks/.
2. Для проверки в клиенте выполните разрешённое действие, которое вызывает нужное событие.
3. Проверьте, что неверный контекст проекта приводит к понятной диагностике.
4. Сравните review_pipeline.fail_open, если поведение различается на рабочих станциях.

Диагностика

Источники

• plugins/codegraph/hooks/hooks.json
• plugins/codegraph/hooks/runtime/
• plugins/codegraph/bin/codegraph_codex_hook.py
• .claude/settings.json
• .claude/hooks/

Сам процесс проверки описан в руководстве Code Review и сценарии 09.