llm-wiki/docs/superpowers/notes/2026-06-04-phase2-codex-hook-schema.md

title, date

title	date
Phase 2 — codex 훅 payload·차단 규약 경험적 캡처	2026-06-04

codex 0.136.0 훅 실측 결과

훅 지원 여부

• codex 0.136.0 은 훅 기능 보유. 근거: codex exec --help 에 --dangerously-bypass-hook-trust ("Run enabled hooks without requiring persisted hook trust for this invocation. DANGEROUS.") 플래그 존재.
• 즉 훅은 trust(신뢰) 게이트 가 있다 — repo 의 .codex/hooks.json 은 신뢰 등록 전엔 실행되지 않음(임의 명령 실행 방지 보안).

실측 (probe 캡처 시도 3회)

• .codex/hooks.json 에 PreToolUse/PostToolUse(matcher *) → stdin 덤프 probe 를 걸고 codex exec 로 shell tool(ls) 실행.
• 결과: shell tool 은 실행됐으나(출력 정상) probe 훅은 한 번도 안 뜸 — --dangerously-bypass-approvals-and-sandbox + --dangerously-bypass-hook-trust 동시 적용에도 미발화.
• codex doctor 출력에 hooks 섹션 없음(config/auth/mcp/updates/reachability 만 보고).

해석

• codex exec(비대화형/automation) 모드는 project-local 훅을 로드하지 않는 것으로 보임 — exec 는 자동화용이라 신뢰 안 된 repo 훅을 건너뛰는 보안 설계로 추정. 훅은 대화형 codex TUI 에서 repo 진입 시 trust 프롬프트로 활성화되는 구조로 판단(공식 hooks 문서의 project-local 지원과 일치하되, exec 경로에선 비활성).
• 환경 제약도 있었음: 이 샌드박스가 bubblewrap user namespace 를 못 만들어 -s read-only 에선 shell 자체가 실패(별도 우회 필요).

결정 (Task 3 반영)

• .codex/hooks.json 을 공식 문서 포맷으로 작성(forward-compatible). PreToolUse(claim_gate) + PostToolUse(structure_lint --hook), matcher 는 Edit/Write 계열.
• 활성화는 대화형 codex 에서 hook trust 승인 필요 — 본 repo 첫 진입 시 codex 가 신뢰를 물음. codex exec 자동화에선 미발화 가능(문서에 명시).
• 차단 규약/payload 필드는 미캡처 → claim_gate 는 이미 멀티-variant 리더(tool_name/tool_call.name/hook_event_name)라 Claude/codex 공통 필드면 동작. 첫 신뢰 실행에서 실거동 확인 권장.
• 구조/claim 강제는 훅 외에도 /depth(skill·workflow)·/lint 가 동일 스크립트를 직접 호출하므로 훅 미발화 상황에서도 우회 수단 존재.