CodeGraph поставляет разные адаптеры хуков для Codex и Claude Code. Оба клиента могут обогащать сессию и учитывать события инструментов, но используют разные файлы регистрации и наборы событий. Источник истины — файл регистрации в текущей версии, а не наличие похожего Python-модуля.
Выберите нужный адаптер
| Клиент | Файл регистрации | Реализация | Когда применять |
|---|---|---|---|
| Codex | plugins/codegraph/hooks/hooks.json |
plugins/codegraph/hooks/runtime/ через plugins/codegraph/bin/codegraph_codex_hook.py |
Установлен плагин CodeGraph для Codex, и клиент загружает его нативные хуки. |
| Claude Code | .claude/settings.json |
.claude/hooks/ |
Репозиторий открыт в Claude Code, локальные хуки разрешены. |
Адаптеры не взаимозаменяемы. Файл из .claude/hooks/ не регистрирует событие Codex. Установленный кэш плагина Codex нельзя редактировать как исходники репозитория.
Жизненный цикл Codex
Текущая регистрация Codex содержит следующие события:
| Событие | Назначение | Обычная граница |
|---|---|---|
SessionStart |
Определяет проект и контекст сессии до начала работы. | Ограниченная диагностика или обогащение контекста. |
UserPromptSubmit |
Добавляет актуальный контекст CodeGraph к задаче. | При деградации возвращается явная диагностика. |
PreToolUse |
Проверяет политику инструмента и финансовые ограничения до выполнения. | Решения о полномочиях и разрешениях работают как fail-closed. |
PostToolUse |
Сохраняет результат Bash и ограниченную телеметрию. | Отчётность обычно fail-open и не может задним числом разрешить команду. |
SubagentStart / SubagentStop |
Связывает и завершает делегированный контекст. | Подтверждения относятся к действующему carrier. |
PreCompact |
Сохраняет ограниченный контекст перед compaction. | Блокировку определяет настроенная compact barrier. |
Stop |
Формирует диагностику, memory и данные completion guard. | Сам Stop намеренно неблокирующий; закрытие определяют SDLC-гейты. |
Таймаут события фиксирует эксплуатационное состояние. Прохождение продуктовой задачи определяется SDLC-гейтами.
Жизненный цикл Claude Code
Файл .claude/settings.json регистрирует обработчики SessionStart, UserPromptSubmit, PreToolUse, PostToolUse и Stop из .claude/hooks/.
Общая политика review pipeline по умолчанию использует fail-closed, если ошибка хука может скрыть обязательную проверку. Параметр review_pipeline.fail_open разрешается только явной настройкой оператора. Он сохраняет возможность продолжить работу и обязан оставить диагностику; отсутствие review evidence от этого не становится успешной проверкой.
Модель отказа
- Используйте fail-closed для авторизации, опасных инструментов, обязательного approval, completion- и финансовых гейтов.
- Используйте fail-open только для ограниченного обогащения или телеметрии, когда отсутствие дополнительного контекста безопаснее полной остановки клиента.
- Exit code хука фиксирует результат его запуска. Acceptance evidence для Story, задачи или релиза включает review и связанные артефакты.
- Не помещайте в диагностику секреты, токены провайдера и неограниченные фрагменты исходников.
- Ограничивайте таймаут и возвращайте способ восстановления с названием упавшего этапа.
Как проверить хуки Codex
- Откройте
plugins/codegraph/hooks/hooks.jsonи убедитесь, что нужное событие зарегистрировано. - Проверьте команду
${PLUGIN_ROOT}/bin/codegraph_codex_hook.pyили её Windows-вариант и наличие runtime-файла. - После установки или обновления плагина начните новую сессию клиента. Изменение исходников не обновляет уже установленный кэш.
- Вызовите минимальное подходящее событие и изучите структурированную диагностику.
- Если
PreToolUseзапретил управляемую операцию, исправьте scope, полномочия, approval или carrier, а не обходите проверку.
Как проверить хуки Claude Code
- Убедитесь, что
.claude/settings.jsonрегистрирует событие и ссылается на существующий файл в.claude/hooks/. - Передайте хуку минимальный JSON через стандартный ввод.
- Проверьте, что неверный контекст проекта приводит к понятной диагностике.
- Сравните
review_pipeline.fail_open, если поведение различается на рабочих станциях.
Диагностика
| Симптом | Что проверить | Восстановление |
|---|---|---|
| Событие не запускается | Регистрацию, версию плагина, перезапуск клиента | Обновите адаптер и начните новую сессию. |
| Выбран неверный проект | Project detector и session cache | Очистите только документированный кэш адаптера и повторите discovery. |
PreToolUse запрещает команду |
Permission, approval, carrier и политику опасных команд | Исправьте управляющие данные; не переключайте отказ в fail-open. |
| Enrichment завершается по таймауту | Здоровье MCP/runtime и лимит события | Продолжите с явной отметкой деградации или восстановите сервис. |
| Хук сработал, но review отсутствует | Review-команду и acceptance evidence | Запустите канонический review и сохраните acceptance evidence. |
Источники
plugins/codegraph/hooks/hooks.jsonplugins/codegraph/hooks/runtime/plugins/codegraph/bin/codegraph_codex_hook.py.claude/settings.json.claude/hooks/
Сам процесс проверки описан в руководстве Code Review и сценарии 09.