정의

Claude Code 라이프사이클의 26 개 이벤트 — 각 이벤트마다 셸 명령·HTTP·MCP·프롬프트·에이전트 5 유형 hook 부착 가능. CLAUDE.md 권고 를 결정론적 강제 로 격상.

기존 concept/hooks-6-events (6 이벤트) 의 대체·확장 카드. 2026 년 v2.1.x 기준 총 26 이벤트.

26 이벤트 분류

도구 (가장 빈번)

• PreToolUse — 도구 실행 전 (★ 차단 가능)
• PostToolUse — 도구 성공 후
• PostToolUseFailure — 도구 실패 후
• PostToolBatch — 병렬 도구 호출 전체 해결 후
• PermissionRequest — 권한 대화 표시 시
• PermissionDenied — auto mode 분류기 거부 시

세션

• SessionStart (startup / resume / clear / compact)
• SessionEnd (clear / resume / logout / 등)
• Setup (--init-only / -p 모드 --init·--maintenance)

사용자 입력

• UserPromptSubmit — 프롬프트 제출, Claude 처리 전
• UserPromptExpansion — 명령 → 프롬프트 확장 전

Subagent

• SubagentStart / SubagentStop
• TaskCreated / TaskCompleted

Claude 응답

• Stop — Claude 응답 완료 시
• StopFailure — API 오류로 턴 종료
• TeammateIdle — agent team 팀원 유휴 직전

★ 본 강의 핵심

• InstructionsLoaded — CLAUDE.md / .claude/rules/*.md 컨텍스트 로드 시 (세션 시작 + lazy load). 디버깅 도구 — `CLAUDE.md 가 언제·왜 로드되는지 정확히 기록**
• ConfigChange — 구성 파일 변경 (user_settings·project_settings·local_settings·policy_settings·skills)

파일·환경

• CwdChanged — 작업 디렉토리 변경 (cd 실행)
• FileChanged — 감시 파일 디스크 변경 (matcher = 감시 파일명)
• WorktreeCreate / WorktreeRemove

압축

• PreCompact / PostCompact

MCP

• Elicitation / ElicitationResult

5 가지 Hook 유형

• command (셸) — 가장 일반
• http — 이벤트 데이터를 URL POST
• mcp_tool — MCP 서버 도구 호출
• prompt — 단일 턴 LLM 평가 (Haiku 기본)
• agent — 도구 액세스 가능 다중 턴 LLM (실험적, 60 초 / 50 턴)

★ Exit Code 의미

★ 권한 모드와의 관계 (CLAUDE.md 부족 보완)

"PreToolUse hooks 는 모든 권한 모드 확인 전 발생. deny → bypassPermissions·--dangerously-skip-permissions 에서도 차단."*

→ 사용자가 권한 모드 변경으로 우회 ❌ — 헌법보다도 강한 물리적 가드.

강의 활용

• Ch6 §6.4 — 4 층 인프라의 Hooks 절. 권고적 CLAUDE.md ↔ 결정론적 Hooks 분리.
• Ch3 안티 패턴 — CLAUDE.md 에 결정적 규칙 박지 말고 Hook 으로 이전 권장.
• 헌법 메타포 — Hook = 행정규칙·고시 의 기술적 강제 측면.