Claude Code 가이드: 훅 수명주기 자동화와 실행 경계
Answer in brief
Claude Code 훅은 이벤트와 matcher를 command, HTTP, MCP tool, prompt 또는 agent handler에 연결해 수명주기 작업을 자동화합니다. 권한 판단은 명시적인 실행 경계로 유지되며, /hooks, handler 직접 테스트, 실패 이벤트, 종료 코드 처리, timeout 문서가 핵심 디버깅 경로를 이룹니다.
Key facts at a glance
| Product / model | Current ID or version | Use case | Evidence |
|---|---|---|---|
| claude-code | Official source does not specify a selectable model ID | Confirm the current product surface | Official source Official source |
Failure modes and verification
| Failure mode | Verification action |
|---|---|
| Stale model or version reference | Compare the model name and ID with the official source before release. |
| Unstructured or incomplete output | Validate the response against the documented contract and a deterministic fixture. |
| Unverified factual claim | Keep the claim qualified or remove the claim when the official source does not support it. |
FAQ
Claude Code는 hook에서 선택할 수 있는 model ID를 공개합니까?
아니요. 공식 출처는 이 제품에 대해 선택 가능한 model ID를 공개하지 않습니다. Prompt 기반과 agent 기반 hook이 Claude model을 사용할 수 있지만, 제공된 공식 문서에는 사용자가 선택할 model ID가 명시되어 있지 않습니다.
Claude Code hook은 어디에 설정합니까?
Claude Code settings file의 단일 hooks object 아래에 설정합니다. 예를 들어 ~/.claude/settings.json을 사용할 수 있습니다. /hooks menu는 설정 내용을 보여 주지만 read-only입니다. 자세한 예시는 automation guide를 참고하십시오.
Matcher는 hook 실행 범위를 어떻게 줄입니까?
Matcher는 이벤트가 발생한 뒤 handler가 실행되기 전에 대상을 필터링합니다. 공식 예시는 Edit|Write 또는 Bash 같은 tool name을 선택하며, if field로 tool argument를 다시 제한할 수 있습니다.
Hook이 tool 권한을 통제할 수 있습니까?
PreToolUse는 실행 전에 tool을 차단할 수 있고, PermissionRequest는 필요한 권한 결정을 다루며, PermissionDenied는 auto mode의 거부를 보고합니다. 제공된 출처는 hook이 권한 경계를 일반적으로 우회한다고 설명하지 않습니다.
Hook 실패는 어떻게 조사해야 합니까?
/hooks에서 event와 matcher를 확인하고, 외부 command를 직접 시험하며, PostToolUseFailure와 StopFailure를 구분하십시오. 이어서 Hooks reference에서 이벤트별 JSON, exit code, timeout, HTTP response, async hook 동작을 확인하십시오.
Sources and freshness
- Official source
- Official source
- Last verified: 2026-08-29
Extended guide
바로 답하기
Claude Code 훅은 예측 가능한 수명주기 자동화를 제공합니다. 설정된 이벤트가 발생하고 matcher가 일치하면 Claude Code는 해당 이벤트의 JSON context를 선택된 handler에 전달합니다. 따라서 파일 편집 뒤 formatter 실행, 명령 검증, 알림 전송, context 주입, 보호된 작업 차단처럼 반복 가능한 규칙을 자동화할 수 있습니다. 사람과 비슷한 판단이 필요한 조건에는 prompt 기반 또는 agent 기반 훅을 사용할 수 있습니다. 이 문서는 공식 문서를 기준으로 2026-08-29에 검증했습니다.
공식 출처는 이 제품에 대해 사용자가 선택할 수 있는 model ID를 공개하지 않습니다. Prompt handler와 agent handler가 Claude model을 사용할 수 있다는 설명은 있지만, 제공된 공식 자료에는 선택 가능한 model ID가 명시되어 있지 않습니다.
수명주기와 실행 경계
| 구간 | 문서에 명시된 동작 | 적합한 실행 경계 |
|---|---|---|
| Session | SessionStart와 SessionEnd는 session마다 한 번 발생 |
Session 범위의 초기화와 종료 작업 |
| Turn | UserPromptSubmit, Stop, StopFailure는 turn 경계에서 작동 |
입력 검증, 정상 응답 완료 처리, API error 종료 감지 |
| Tool call | PreToolUse는 실행 전에 발생하며, 성공하면 PostToolUse, 실패하면 PostToolUseFailure가 발생 |
실행 전 차단과 실행 결과 관찰을 분리 |
| Permission | PermissionRequest는 tool call에 권한 판단이 필요할 때 발생하며, PermissionDenied는 auto mode 거부를 보고 |
권한 요청과 거부를 일반 tool 결과와 분리 |
EndConversation call은 PreToolUse와 PostToolUse를 건너뜁니다. 이 밖에도 공식 문서는 notification, subagent, task, configuration 변경, working directory 변경, compaction, worktree, file 감시, MCP elicitation, session 종료에 대응하는 이벤트를 설명합니다. 각 이벤트가 받는 전체 input schema와 허용되는 decision control은 Hooks reference에서 확인해야 합니다. 모든 이벤트가 같은 결정을 반환할 수 있다고 가정하면 안 됩니다.
설정 절차
-
이벤트를 선택합니다. Claude Code settings file의 단일
hooksobject 안에 필요한 event key를 추가합니다. 예를 들어Notification은 Claude Code가 notification을 보낼 때 실행됩니다.PreToolUse는 tool이 실행되기 직전의 통제 지점입니다. 기존hooksobject가 있다면 새 이벤트를 형제 key로 추가해야 하며, object 전체를 교체할 필요는 없습니다. -
Matcher로 범위를 제한합니다. Matcher는 발생한 이벤트 가운데 어떤 항목을 handler로 전달할지 결정합니다. 공식 예시는
Edit|Write를 사용해 해당 tool name들을 선택합니다.PreToolUse예시는 먼저Bashtool call을 선택한 다음iffield를 이용해 argument가rm *형태인 명령으로 다시 좁힙니다. 즉 event, matcher,if조건은 서로 다른 필터 단계입니다.FileChanged에서는 matcher가 감시할 filename을 지정합니다. -
Handler 종류를 선택합니다. Claude Code는 사용자가 정의한 shell command, HTTP endpoint, MCP tool call, LLM prompt, subagent를 hook handler로 지원합니다. Command handler는 stdin으로 event JSON을 받습니다. HTTP handler는 같은 context를 POST request body로 받습니다. Handler는 input을 검사하고 작업을 수행할 수 있습니다. 해당 이벤트가 decision control을 지원하는 경우에는 선택적으로 결정을 반환할 수도 있습니다. 반복 가능한 규칙에는 command가 적합하고, 판단이 필요한 조건에는 prompt 또는 agent 방식이 문서에 제시됩니다.
-
권한 경계를 분리합니다. 작업을 실행 전에 차단해야 한다면
PreToolUse를 사용합니다. 권한 결정을 기다리는 call은PermissionRequest에서 다룹니다. Auto mode가 tool call을 거부한 사실은PermissionDenied에서 관찰합니다.PermissionDenied의 JSONhookSpecificOutput.retry: true는 model이 거부된 tool call을 다시 시도할 수 있음을 알리는 용도입니다. 다만 classifier가 verdict를 만들지 않았다면 Claude Code는 이 retry 표시를 무시합니다. 제공된 출처는 hook이 더 넓은 권한 우회를 제공한다고 명시하지 않으므로, 그런 우회를 가정해서는 안 됩니다. -
설정을 검증하고 디버깅합니다.
/hooks를 열어 event, matcher, type, source file, handler command를 확인합니다./hooksmenu는 read-only이므로 설정을 추가하거나 바꾸거나 제거하려면 settings JSON을 직접 편집해야 합니다. Hook이 실행되지 않으면 먼저 실제로 해당 event가 발생했는지 확인합니다. 그런 다음 matcher와 추가if조건이 모두 일치하는지 점검합니다. Notification이 보이지 않으면 운영체제 command를 terminal에서 직접 실행해야 합니다. Desktop notification permission, notification daemon 부재, headless server, SSH session, container 환경, 설치되지 않은 command가 눈에 보이는 결과를 막을 수 있기 때문입니다.
실패 처리 체크리스트
- 성공한 tool call은
PostToolUse, 실패한 call은PostToolUseFailure에서 구분해 처리합니다. - 정상적인 응답 완료인
Stop과 API error로 turn이 끝나는StopFailure를 구분합니다. - 출력이 없다는 이유만으로 성공이라고 판단하지 말고 hook error output을 확인합니다.
- Structured JSON output, exit-code output, 기타 exit code, timeout의 효과는 이벤트별 공식 규칙을 확인합니다.
- Background 실행이 필요하면 공식 reference의 async hook 설정과 실행 제한을 확인합니다.
- 빠른 설정 예시는 automation guide, schema와 고급 동작은 Hooks reference를 기준으로 삼습니다.
모델 제공 범위 안내: 공식 출처는 선택 가능한 모델 ID를 지정하지 않습니다.
근거와 최신성
근거 수준: 공식 문서 검증
AI-assisted editorial content; verify current product details against the linked official sources.
마지막 검증: