Codex CLI 훅은 Claude Code 훅과 페이로드·스키마가 호환된다 (0.144.1 실측)

주장#

codex-cli 0.144.1의 hooks 기능(feature stage: stable, 기본 true)은 Claude Code 훅과 이벤트 이름·JSON 페이로드 필드가 동일하다. 따라서 하나의 훅 스크립트를 두 에이전트가 공유할 수 있다.

설정 위치와 스키마#

~/.codex/config.toml의 [hooks] 테이블. 파일 경로가 아니라 인라인 구조체다 (hooks = "./hooks.json" 는 invalid type: string, expected struct HooksToml 로 거부됨. hooks.json은 플러그인 매니페스트 전용).

[hooks]
SessionStart     = [ { hooks = [ { type = "command", command = "..." } ] } ]
UserPromptSubmit = [ { hooks = [ { type = "command", command = "..." } ] } ]
PostToolUse      = [ { matcher = "*", hooks = [ { type = "command", command = "...", timeout = 5 } ] } ]

MatcherGroup 필드: matcher(string), hooks(sequence)
HookHandlerConfig: type ∈ {command, prompt, agent}, command(필수), timeout(u64)
prompt/agent 핸들러는 0.144.1에서 미구현 (prompt hooks are not supported yet, agent hooks are not supported yet)

지원 이벤트 (설정 키 수용 여부로 전수 확인)#

지원: PreToolUse PostToolUse PermissionRequest UserPromptSubmit SessionStart Stop SubagentStart SubagentStop PreCompact PostCompact

미지원: SessionEnd, Notification

→ Codex에는 세션 종료 훅이 없다. 세션 마감 시점 플러시를 훅에 의존하는 설계는 불가. Stop은 턴 종료마다 발화한다.

실제 페이로드 (stdin, JSON)#

{"session_id":"019fdae6-...","turn_id":"019fdae6-...",
 "transcript_path":"~/.codex/sessions/2026/08/07/rollout-2026-08-07T15-26-01-<sid>.jsonl",
 "cwd":"/tmp","hook_event_name":"PostToolUse","model":"gpt-5.6-sol",
 "permission_mode":"bypassPermissions",
 "tool_name":"Bash","tool_input":{"command":"echo hi4"},"tool_response":"hi4\n",
 "tool_use_id":"exec-caa37337-..."}

Codex 내부 exec 툴인데도 tool_name이 "Bash"로 정규화되어 나온다
Stop은 stop_hook_active, last_assistant_message 포함 — Claude Code와 동일
SessionStart는 source(예: "startup") 포함
출력도 hookSpecificOutput.additionalContext 등 Claude와 같은 wire 타입(SessionStartHookSpecificOutputWire 등)을 씀

함정: 훅 신뢰 게이트 (배포 시 최대 빈발 이슈)#

설정만 넣으면 조용히 발화하지 않는다. 에러도 경고도 없다. Codex는 훅에 trust 게이트가 있어서 TUI 훅 리뷰 화면에서 1회 승인해야 한다("New hook - review required" / "Modified since last trusted - review required"). 훅 내용이 바뀌면 재승인이 필요하다.

비대화형(codex exec)에서는 --dangerously-bypass-hook-trust 플래그로 우회
조직 배포 시에는 관리형(admin/MDM) config 레이어를 쓰면 "Managed hooks are always on"으로 승인 없이 항상 활성. 관련 정책 키: allow_managed_hooks_only

검증 방법#

임시 CODEX_HOME으로 실행해 실제 사용자 설정을 건드리지 않고 확인했다.

CODEX_HOME=/tmp/ch codex exec --skip-git-repo-check \
  --dangerously-bypass-approvals-and-sandbox --dangerously-bypass-hook-trust \
  -C /tmp "run shell: echo hi" </dev/null

설정 키의 유효성은 잘못된 타입을 넣어 serde 에러 메시지를 읽는 방식으로 전수 확인했다 (SessionStart = 5 → invalid type: integer, expected a sequence = 유효한 키). 알 수 없는 키는 에러 없이 무시되므로, 무반응 = 미지원 키다.

배포 경로: 플러그인 훅은 Codex 0.144.1에서 동작하지 않음 (실측)#

Codex 플러그인(plugin.json의 "hooks": "./hooks.json")으로 훅을 배포하려는 시도는 실패한다. 훅 설정은 ~/.codex/config.toml의 [hooks]만 유효하다.

실측 절차와 결과:

# 로컬 마켓플레이스 구성 — 매니페스트는 반드시 <root>/.agents/plugins/marketplace.json
# 플러그인 source.path 는 마켓플레이스 root 기준 상대경로
codex plugin marketplace add /path/to/rosaic-mp   # → Added marketplace `rosaic`
codex plugin add rosaic-scrum@rosaic              # → 설치 성공

설치는 정상: ~/.codex/plugins/cache/<marketplace>/<plugin>/<version>/ 에 hooks.json이 그대로 복사됨
config.toml에 [marketplaces.rosaic], [plugins."rosaic-scrum@rosaic"] enabled = true 자동 기록됨
그런데 SessionStart 훅이 발화하지 않음. --dangerously-bypass-hook-trust를 켜도, -c features.plugin_hooks=true로 강제해도 동일
codex features list 상 plugin_hooks는 stage=removed, value=false

→ Claude Code는 플러그인으로 훅을 배포할 수 있지만 Codex는 안 되므로, 두 에이전트에 같은 훅을 깔려면 git 레포 + install.sh 로 ~/.claude/settings.json과 ~/.codex/config.toml 양쪽에 병합하는 방식으로 통일하는 편이 낫다.

업데이트 마찰을 없애는 설정 패턴#

config.toml에는 로직을 넣지 말고 안정적인 한 줄만 둔다:

[hooks]
SessionStart = [ { hooks = [ { type="command", command="/home/<user>/.rosaic/scrum/bin/hook session-start", timeout=5 } ] } ]

신뢰 해시는 훅 정의(이벤트+matcher+command 문자열)를 대상으로 한다고 보는 게 타당하다 — command가 임의의 셸 문자열이라 대상 스크립트 내용을 해시할 방법이 원리적으로 없고, 리뷰 UI도 command 문자열을 보여준다. (※ 이 부분은 추론이며 실제 머신에서 1회 검증 필요: 승인 후 스크립트만 수정하고 계속 발화하는지 확인)

따라서 스크립트 내용 수정은 재승인 불필요, command 문자열이나 이벤트 목록 변경은 전원 재승인. 처음에 필요한 이벤트를 넉넉히 걸어두고 스크립트 내부에서 no-op 처리하는 편이 유리하다.

부수 효과: 신뢰 대상이 "코드"가 아니라 "커맨드라인"이므로, 훅 스크립트 레포에 push 권한을 가진 사람은 전 팀원 노트북에서 임의 코드를 실행할 수 있다. 브랜치 보호·리뷰 필수.

Sagwan Revalidation 2026-08-31T11:58:49Z#

verdict: refresh
note: codex-cli 훅은 빠르게 변동하며 0.144.1 실측 재확인이 필요함

Sagwan Revalidation 2026-09-03T03:01:35Z#

verdict: ok
note: 0.144.1 실측·스키마 주장이 버전 한정이라 현재도 재사용 가능

Sagwan Revalidation 2026-09-09T05:14:43Z#

verdict: ok
note: [chatgpt HTTP 404] {

Sagwan Revalidation 2026-09-11T19:48:11Z#

verdict: refresh
note: Claude Code가 hookSpecificOutput.additionalContext 등 신규 필드를 추가했고, 이벤트 수 차이(CC ~30 vs Codex ~12)가 커져 '완전 호환' 주장을 재정밀 검증할 필요 있음.

Sagwan Revalidation 2026-09-15T13:32:12Z#

verdict: refresh
note: Claude Code 신규 훅 필드·이벤트 차이로 완전 호환 주장은 재검증 필요

주장#