핵심 표면

대표 이벤트
- SessionStart: 세션 시작, resume, compact 시 추가 컨텍스트 주입
- UserPromptSubmit: 사용자 프롬프트 제출 시 검사
- PreToolUse: 도구 실행 전 정책 확인
- PermissionRequest: 승인 요청이 뜨기 전 allow/deny 결정
- PostToolUse: 도구 결과 이후 검토
- Stop: Codex 응답 종료 시 후처리

적용 기준
1. 반복되는 정책 검사를 hook으로 뺀다.
2. 사람이 판단해야 하는 변경은 hook으로 자동 승인하지 않는다.
3. 실패해도 부작용을 되돌릴 수 없는 검사는 PreToolUse 쪽에 둔다.
4. 로그 수집과 결과 리뷰는 PostToolUse 쪽에 둔다.

연결 구조

Hooks는 Codex lifecycle에 붙는 자동 검사 지점이다

Hooks는 Codex가 프롬프트를 받거나, 도구를 쓰거나, 승인을 요청하거나, 응답을 마칠 때 외부 명령을 실행해 정책을 적용하는 장치입니다. Rules가 "어떤 명령 prefix를 어떤 승인 정책으로 처리할지"를 정한다면, Hooks는 "특정 시점에 어떤 검사를 실행할지"를 정합니다. 예를 들어 PreToolUse에서 shell 명령이 금지 경로를 건드리는지 검사하고, PostToolUse에서 실패한 테스트 로그를 요약하게 만들 수 있습니다.

Repo-local hook은 Codex가 하위 디렉터리에서 시작될 수 있으므로 상대 경로만 믿기보다 git root 기준으로 스크립트를 찾는 편이 안정적입니다. 공식 문서 예시처럼 git rev-parse --show-toplevel을 사용하면 .codex/hooks/... 위치를 더 일관되게 해석할 수 있습니다.

PermissionRequest hook은 승인 흐름을 우회할 수 있으므로 좁게 써야 한다

PermissionRequest는 shell escalation이나 managed-network approval처럼 Codex가 사용자에게 승인을 물어보기 직전에 실행됩니다. hook은 요청을 허용하거나 거부하거나, 결정을 내리지 않고 일반 승인 흐름으로 넘길 수 있습니다. 여러 hook이 결정을 내리면 deny가 우선합니다.

이 이벤트는 매우 강력합니다. 사람이 봐야 하는 작업을 자동 allow로 넘기면 승인 체계가 약해집니다. 반대로 명확히 금지된 경로 삭제, 승인되지 않은 배포, 비밀 파일 출력처럼 정책상 차단해야 하는 요청은 hook에서 deny하는 편이 빠릅니다.

적용 기준

hook은 실패 시 작업 흐름을 막을 수 있으므로, 첫 도입은 읽기 전용 검사부터 시작하는 편이 낫습니다. 실제 파일 수정, 배포, 권한 변경을 hook이 직접 수행하게 만들면 디버깅이 어려워집니다. 정책은 "검사와 차단"에 두고, 변경은 Codex의 명시 작업이나 사람이 검토하는 단계에 남기는 구조가 안전합니다.

주의할 점

실패 예시
- PostToolUse에서 rm 실행을 감지하지만 이미 파일이 삭제됨
- PermissionRequest hook이 너무 넓게 allow를 반환해 승인 프롬프트가 사라짐
- hook script가 상대 경로에 의존해 하위 디렉터리에서 실행될 때 실패함
- hook이 자체적으로 긴 네트워크 작업을 수행해 모든 Codex 응답이 느려짐