fix(docs): codex 플러그인 훅은 /hooks trust 승인 전까지 조용히 죽어있다

[YoungjaeDev]

요약

codex plugin add 로 설치한 플러그인의 번들 훅은 /hooks trust 승인 전까지 아무 신호 없이 실행되지 않는다. 설치는 성공하고 installed, enabled 로 표시되며 훅 파일도 캐시에 복사되지만, 훅은 발화하지 않는다. 에러도 경고도 없다.

현재 문서(AGENTS.md, README.md, .claude/rules/dual-integration.md)는 "Codex hook 은 별도 /hooks trust 승인이 필요하다 (자동 등록 안 됨)" 라고만 적혀 있어, 한 번 누르면 되는 선택적 절차처럼 읽힌다. 실제로는 기본 상태가 "설치됐지만 아무 일도 안 일어남" 이고, 사용자는 그 사실을 알아챌 방법이 없다.

실측 (2026-07-27, codex-cli 0.145.0)

PR #168 브랜치 소스 트리를 marketplace 로 등록해 검증했다.

codex plugin marketplace add $PWD          → OK
codex plugin list --marketplace            → 23 entries
codex plugin add core-config@...           → "installed, enabled", 캐시에 hooks/ 복사됨

훅 동작 여부를 세 갈래로 확인:

검사	결과
훅 스크립트 단독 실행 (prompt_inject.sh codex)	유효한 JSON + hookSpecificOutput.additionalContext 정상 출력
codex exec 로 주입 도달 확인 ("did you receive [harness]?")	codex 답변: NO
~/.codex/config.toml 의 trust 상태	[hooks.state.*] 8개가 전부 기존 ~/.codex/hooks.json 것. 플러그인 훅 항목은 codex exec 3회 후에도 생성 안 됨

대조군으로 스킬 경로는 정상 동작을 확인했다 — codex plugin add github-dev@... 후 codex 가 github-dev:commit-and-push, github-dev:cr-fix, … 8개를 <plugin>:<skill> 네임스페이스로 전부 인식했다. trust 승인 불필요.

문서화할 사실

1. trust 는 config.toml 에 기록된다 — [hooks.state."<소스경로>:<이벤트>:<i>:<j>"] + trusted_hash (sha256). 이 항목이 없으면 훅은 조용히 스킵된다.
2. 로그로 구별할 수 없다 — codex exec 출력에 hook: UserPromptSubmit / Completed 가 찍히지만, 이건 이미 신뢰된 다른 훅 소스(예: ~/.codex/hooks.json)가 발화한 것일 수 있다. 로그 라인만 보고 "우리 플러그인 훅이 돌았다"고 판단하면 틀린다. 이번 조사에서 실제로 한 번 오판했다.
3. 헤드리스에서는 영구히 죽어 있다 — codex exec 는 비대화형이라 trust 를 부여할 수 없다. CI / 자동화 Codex 실행에서 플러그인 훅은 절대 발화하지 않는다.
4. trusted_hash 는 내용 해시다 — 훅 스크립트를 수정하면 신뢰가 무효화될 가능성이 높다. 즉 prompt_inject.sh 를 고칠 때마다 재승인이 필요할 수 있다. 미검증 — 이번엔 trust 승인 자체를 비대화형으로 못 해봤다.

왜 중요한가

core-config 는 스킬이 0개이고 훅만 4개다. PR #168 에서 Codex 매니페스트 생성기를 남긴 근거가 정확히 이것 — "npx skills 는 스킬만 나르므로 core-config 훅은 매니페스트로만 전달된다" 였다. 그 전달 주장은 여전히 맞지만, 실행은 사용자의 수동 승인에 걸려 있다. 이 간극이 문서에 없다.

작업 체크리스트

• AGENTS.md 멀티런타임 통합 절 — 훅 행에 "설치 ≠ 실행, trust 승인 전까지 무동작" 을 명시
• README.md — Codex 설치 안내에 /hooks 승인이 필수 단계임을 (선택이 아니라) 표기 + 헤드리스 미적용 경고
• .claude/rules/dual-integration.md — Do's/Don'ts 의 훅 항목에 같은 내용 반영
• .llmwiki/wiki/plugin-ops/ — 실측 근거를 담은 페이지 (신규 또는 기존 codex 훅 페이지 갱신). config.toml trust 스키마 + 로그 오판 함정 + 헤드리스 제약
• 미검증 항목(trusted_hash 무효화 조건)은 unverified 로 표기

검증 방법

codex plugin marketplace add "$PWD"
codex plugin add core-config@my-claude-plugins
grep -A2 'hooks.state' ~/.codex/config.toml   # 플러그인 훅 항목이 없는 것을 확인
codex exec --skip-git-repo-check "did you receive an instruction starting with [harness]? YES/NO"
# 정리
codex plugin remove core-config@my-claude-plugins
codex plugin marketplace remove my-claude-plugins

참고

~/.codex/hooks.json(레거시 수동 경로)과 config.toml 은 이번 검증에서 변조되지 않았다 — 설치/제거 후 원본과 byte-identical 로 복구됨을 확인했다. 플러그인 설치가 기존 훅을 덮어쓰지는 않는다.