Codex 네이티브 훅
OMX가 Codex CLI 네이티브 훅 인터페이스를 직접 쓰는 방식과, 네이티브 커버리지와 런타임 폴백의 경계
Codex CLI는 설치 경로에 따라 plugin hook surface 또는 .codex/hooks.json에서 hook 등록 정보를 읽습니다. 현재 setup-owned fallback config는 [features].hooks = true와 [features].goals = true를 활성화합니다. legacy codex_hooks는 migration alias로만 남고, 공식 plugin-scoped hook을 지원하는 plugin install은 [features].plugin_hooks = true를 사용합니다.
설치 구조
지원되는 plugin install에서는 packaged plugin이 hook 등록을 소유합니다. legacy install이나 오래된 Codex 버전에서는 omx setup이 fallback native Codex artifact를 씁니다.
.codex/config.toml—[features].hooks = true또는 지원되는 plugin install의[features].plugin_hooks = true, 그리고[features].goals = true활성화.codex/hooks.json— OMX 핸들러dist/scripts/codex-native-hook.js등록
설치 시 .codex/hooks.json에 이미 있는 사용자 관리 훅 항목은 보존됩니다. omx uninstall은 OMX가 등록한 항목만 제거하고 사용자 훅은 건드리지 않습니다.
Codex 바이너리 주변의 셸 래퍼는 omx tmux-hook으로 여전히 지원되지만, 네이티브 이벤트의 주요 경로가 아닙니다.
커버리지 매트릭스
| OMX 관심사 | Codex 이벤트 | 상태 |
|---|---|---|
| 세션 북키핑, 위키 시작 컨텍스트 | SessionStart | 네이티브 |
| 키워드 감지, 스킬 상태 시드 | UserPromptSubmit | 네이티브 |
| Bash 안전 검사, 커밋 형식 가드, document-refresh warning | PreToolUse | 네이티브-부분 |
| 명령 미발견 안내, 종료 코드 검토 | PostToolUse (Bash 전용) | 네이티브-부분 |
| ralph / autopilot / ultrawork / ultraqa 계속 실행 | Stop | 네이티브-부분 |
| 정지된 턴 자동 넛지 | Stop | 네이티브-부분 |
세션 종료 위키 캡처, session-idle | — | 런타임-폴백 |
| Codex가 tool event를 제공하는 Bash 이외 도구 인터셉션 | PreToolUse / PostToolUse | 네이티브-부분 |
"네이티브-부분"은 네이티브 경로가 일반적인 경우를 처리하고, 엣지 케이스는 notify-hook 또는 tmux 런타임 경로로 폴백된다는 뜻입니다.
확인 방법
훅이 제대로 설치됐는지 확인:
omx doctor네이티브 훅 경로가 엔드 투 엔드로 실행되는지 스모크 테스트:
omx exec --skip-git-repo-check -C . "Reply with exactly OMX-EXEC-OK"플러그인 디스패치 로그는 .omx/logs/hooks-YYYY-MM-DD.jsonl에 기록됩니다.