Cmd. /hooks
Codex lifecycle hooks를 검토하고 신뢰/비활성화 상태를 관리하는 명령
핵심 요약
- Codex lifecycle hooks를 검토하고 신뢰/비활성화 상태를 관리하는 명령
- 새로 추가하거나 바뀐 훅은
/hooks에서 검토·신뢰하기 전까지 실행되지 않습니다. 신뢰는 훅 내용의 해시에 묶이고, 관리형(managed) 훅은 사용자가 끌 수 없습니다.
역할
Codex lifecycle hooks를 검토하고 신뢰/비활성화 상태를 관리하는 명령
/hooks사용 조건
| 항목 | 기준 |
|---|---|
| 입력 위치 | 실행 중인 CLI의 입력창 |
| 종류 | 내장 명령 |
| 상태 | 현재 공식 표 |
| 별칭 | — |
| 공식 최소 버전 | 명시되지 않음 |
| 검증 기준 | 2026-10-23 · Codex CLI 0.163.0 |
설치본의 명령 메뉴와 계정·조직 설정에 따라 사용할 수 있는 항목이 달라집니다.
사용 예
/hooks선택 시점
- 프로젝트
.codex/hooks.json또는[hooks]를 추가한 직후 실행해 실행될 hook과 출처를 확인 - 플러그인 bundled hooks를 켜기 전에
/plugins로 플러그인 상태를 확인하고/hooks로 hook 신뢰 여부를 검토 - 팀 정책상 managed hook과 개인/프로젝트 hook을 구분해 온보딩 문서에 남김
관련 명령 선택
| 명령어 | 차이점 | 언제 선택 |
|---|---|---|
| /hooks | lifecycle hook 검토/신뢰/비활성화 | hook이 실행되기 전 source와 trust 상태를 확인할 때 |
| /plugins | plugin inventory와 bundled hooks 확인 | hook이 plugin에서 온 것인지 확인할 때 |
| /debug-config | 설정 계층 진단 | hook이 왜 로드됐는지 config precedence까지 봐야 할 때 |
훅을 두는 곳
| 위치 | 적용 범위 |
|---|---|
~/.codex/hooks.json, ~/.codex/config.toml의 [hooks] | 사용자 전체 |
<repo>/.codex/hooks.json, <repo>/.codex/config.toml의 [hooks] | 해당 프로젝트. 프로젝트 .codex/ 계층을 신뢰한 경우에만 로드 |
플러그인의 hooks/hooks.json 또는 .codex-plugin/plugin.json의 hooks | 켜 둔 플러그인 |
requirements.toml의 관리형 훅 | 조직 정책. 사용자가 끌 수 없음 |
일치하는 출처의 훅은 모두 실행되고, 같은 이벤트에 걸린 command hook은 동시에 시작됩니다. 한 훅이 다른 훅의 시작을 막을 수는 없습니다.
최소 설정 예
셸 명령을 실행하기 전에 정책 스크립트를 거치게 하는 .codex/hooks.json입니다.
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "python3 \"$(git rev-parse --show-toplevel)/.codex/hooks/check_command.py\"",
"timeout": 30
}
]
}
]
}
}config.toml에 쓸 때는 [[hooks.PreToolUse]]로 matcher 그룹을, [[hooks.PreToolUse.hooks]]로 handler를 적습니다. 파일을 저장한 뒤 /hooks에서 검토·신뢰해야 실행됩니다.
훅 이벤트
| 이벤트 | 실행 시점 | 할 수 있는 일 |
|---|---|---|
SessionStart | 세션 시작·재개·clear·compact·fork | stdout을 개발자 컨텍스트로 추가 |
SessionEnd | 대화 보관·삭제, Codex 종료, 30분 유휴 (메인 스레드만) | 정리 작업. 기본 1초, 최대 3초 |
SubagentStart | 서브에이전트 시작 | stdout을 컨텍스트로 추가 |
SubagentStop | 서브에이전트 종료 | 계속 진행 요청 |
PreToolUse | 지원 도구 실행 전 | 호출 거부 또는 수정 |
PermissionRequest | 승인 요청을 띄우기 전 | 허용 또는 거부 |
PostToolUse | 도구가 출력을 낸 뒤 | 결과 점검 |
PreCompact / PostCompact | 대화 compaction 전후 | 전후 처리 |
UserPromptSubmit | 프롬프트를 보내기 전 | 차단, stdout을 컨텍스트로 추가 |
Stop | turn 종료 | 계속 진행 요청 |
Interrupt | 사용자가 메인 turn을 중단 | 정리 작업. 기본 1초, 최대 3초 |
PreToolUse는 셸 명령, apply_patch 파일 편집, MCP 도구 호출, 그 밖의 로컬 함수 도구에 걸립니다. WebSearch 같은 호스팅 도구에는 걸리지 않습니다.
입력과 출력
- 훅은 stdin으로 JSON 객체 하나를 받습니다. 공통 필드는
session_id,transcript_path,cwd,hook_event_name,model이고 이벤트에 따라tool_name,tool_input,prompt,source가 붙습니다. - 종료 코드 0에 출력이 없으면 성공입니다. 차단을 지원하는 이벤트에서 종료 코드 2를 내면 동작을 막고 stderr를 사유로 씁니다.
PreToolUse거부는hookSpecificOutput.permissionDecision으로,PermissionRequest결정은hookSpecificOutput.decision.behavior(allow·deny)로 돌려줍니다. 하나라도 거부하면 요청이 거부됩니다.matcher는 정규식입니다. 도구 이벤트에서는Bash,Edit|Write,mcp__filesystem__.*처럼 도구 이름을 거르고,"*"나 빈 값이면 모두 일치합니다.timeout은 초 단위이고 기본값은 600초입니다. 약 2,500토큰을 넘는 출력은 디스크에 저장되고 모델에는 미리보기만 전달됩니다.
실행 결과와 유지 범위
구성된 훅과 실행 조건을 확인합니다. 훅을 수정하면 해당 이벤트에서 실행되는 동작이 달라집니다.
/hooks는 설정된 lifecycle hooks를 훑어보고, 새 hook 또는 변경된 hook을 신뢰하거나 non-managed hook을 비활성화하는 명령.
검토가 필요한 훅이 있으면 시작할 때 /hooks를 안내하는 경고가 표시됩니다. 신뢰는 훅의 현재 해시에 묶여 있어서, 훅을 새로 만들거나 고치면 다시 신뢰하기 전까지 그 훅은 건너뜁니다.
주의사항
훅은 기본으로 켜져 있습니다. 모두 끄려면 config.toml의 [features]에 hooks = false를 둡니다(codex_hooks는 이전 이름입니다). --dangerously-bypass-hook-trust는 저장된 신뢰 없이 켜진 훅을 그 실행 한 번만 돌리는 옵션이므로 공용 스크립트에 넣지 마세요.
- managed hooks는 system, MDM, cloud,
requirements.toml정책으로 신뢰되며 사용자 hook browser에서 비활성화할 수 없습니다 - project-local hooks는 프로젝트
.codex/layer를 신뢰한 경우에만 로드됩니다 - project hook의 사용자 trust는 정확한 content hash에 묶이므로 파일이 바뀌면 다시 검토·신뢰합니다
- MCP hook handler는 기존 연결을 재사용해 synchronous로 실행하고 approval을 요청하거나 다른 hook을 다시 trigger할 수 없습니다. auth·availability 실패를 별도 경로로 다룹니다
- hook은 guardrail일 뿐, 모든 shell/tool 경로를 완전한 enforcement boundary로 막아준다고 가정하지 마세요
공식 근거
전체 명령 목록 · 검증 범위 · 이 명령의 변경 기록