Claude Code 훅 레퍼런스

한 줄 요약: Claude Code 공식 문서 "Hooks reference". 훅 이벤트 전체(원본 표 기준 33개, 개수는 편집자가 셈)의 발생 시점·matcher·입력 JSON·결정 제어, 훅 핸들러 다섯 종류의 필드, 종료 코드와 stdout의 조합 규칙, JSON 출력 공통 필드, additionalContext 전달 방식, 실패 시 막기(onFailure), 백그라운드(async) 훅, 작업 공간 신뢰를 포함한 보안 고려, 디버그 로그를 다룬다. 가이드(Claude Code 훅 가이드)가 "레퍼런스로 넘긴" 부분이 여기 있다.

원본 정보#

• 제목: Hooks reference
• 발행: Anthropic, Claude Code 공식 문서 (원본 날짜 미상)
• URL: https://code.claude.com/docs/en/hooks (새 창)
• 수집(fetch)일: 2026-10-18. 이벤트 목록, matcher 값, 필드 이름, 기본 타임아웃, 버전 조건(v2.1.105~v2.1.299 사이 여러 개)은 이 날짜 기준이다.
• 범위: 원본은 스스로 이벤트 스키마, 설정 옵션, JSON 입출력 형식, async·HTTP·MCP 도구 훅 같은 고급 기능을 찾아보는 레퍼런스라고 밝히고, 시작 예제는 가이드로 넘긴다. 플러그인이 JavaScript 함수로 등록하는 훅(mod)은 이 페이지가 아니라 "React to events" 문서가 다룬다고 밝힌다.

핵심 주장#

1. 같은 훅이 어디서나 돈다. 터미널, IDE 확장, 데스크톱 앱, 클라우드 세션에서 같은 훅 이벤트가 발생한다. 다만 클라우드 세션은 로컬 ~/.claude/settings.json을 읽지 않는다. settings 파일·managed 정책·플러그인의 훅은 서브에이전트 안의 도구 호출에도 실행되고, 입력의 agent_id·agent_type으로 어느 에이전트인지 알 수 있다. → 훅, 서브에이전트
2. "조용히 끝나면 승인"이 아니다. 종료 코드 0에 출력이 없으면 훅은 결정이 없다는 뜻이고 도구 호출은 일반 권한 흐름으로 간다. 원본: "The hook can deny the call, but staying silent doesn't approve it." 반대로 막으려면 종료 코드 2나 JSON 결정이 필요하고, 종료 코드 1은 관례상 실패 코드라도 올바른 JSON 없이 끝나면 막지 않는 오류다(실패하면 막도록 설정한 훅, 즉 onFailure: "block"은 예외). 원본: "If your hook is meant to enforce a policy, use exit 2." → 훅 입출력 규칙
3. 정책 훅은 기본으로 실패하면 열린다(fail open). 대부분의 이벤트에서 훅이 시작하지 못하거나, 0·2가 아닌 코드로 끝나거나, 시간을 넘기면 동작은 그대로 진행된다. 원본: "A policy hook with a wrong path or a crashing script then lets everything through." 막으려면 command·http 훅에 "onFailure": "block"(v2.1.295 이상)을 둔다. 예외도 있다: PreModelSwitch는 시간 초과면 전환을 막고, Windows에서 Git Bash가 없으면 PreToolUse·PermissionRequest 셸 형식 훅의 실패가 호출을 막을 수 있다. → Claude Code 차단 훅 단단하게 만들기
4. 이벤트마다 막을 수 있는지, 무엇으로 결정하는지가 다르다. 종료 코드 2로 막을 수 있는 이벤트(예: PreToolUse, UserPromptSubmit, Stop, PreCompact, ConfigChange 단 policy_settings 제외)와 막을 수 없는 이벤트(예: PostToolUse, SessionStart, Notification)가 표로 나뉜다. PermissionRequest는 종료 코드 2를 받지 않고 decision 객체로만 결정한다. 결정 필드도 최상위 decision, hookSpecificOutput.permissionDecision, decision.behavior, retry, 경로 반환 등으로 이벤트마다 다르다. → 훅 이벤트 레퍼런스
5. 신뢰하지 않은 폴더에서 -p로 돌리면 저장소의 훅이 실행된다. 대화형 세션은 그 폴더(또는 신뢰가 이어지는 상위 디렉터리)의 작업 공간 신뢰 대화상자를 수락하기 전까지 모든 settings 파일(자기 ~/.claude/settings.json 포함)의 훅을 보류한다. -p·SDK 세션은 대화상자를 띄우지 않고 폴더를 신뢰한 것으로 다루므로, 저장소 .claude/settings.json에 커밋된 훅이 처음 보는 폴더에서도 돈다. 원본은 남이 만든 저장소에 claude -p를 돌리기 전에 .claude/ 설정을 검토하거나 --bare로 시작하거나 --settings '{"disableAllHooks": true}'로 그 실행의 훅을 끄라고 한다. command 훅은 사용자의 전체 권한으로 셸 명령을 실행한다. → Claude Code 차단 훅 단단하게 만들기

원본이 밝힌 세부 동작 (2026-10-18 기준)#

이 페이지는 원본이 무엇을 말했는지의 기록이다. 찾아보기용 정리는 아래 세 페이지에 나눠 두었다.

• 이벤트별 발생 시점·matcher·입력 필드·종료 코드 2 동작·결정 제어·지원 핸들러 종류: 훅 이벤트 레퍼런스
• 설정 구조, 핸들러 필드, exec form·shell form, 입력 공통 필드, 종료 코드×stdout 표, JSON 출력, additionalContext, 타임아웃, async 훅: 훅 입출력 규칙
• 정책 훅이 새지 않게 만드는 점검(실패 시 막기, 우회 경로, 작업 공간 신뢰, 보안 습관): Claude Code 차단 훅 단단하게 만들기

원본에서 특히 인용할 만한 문장:

• "The hook can deny the call, but staying silent doesn't approve it." (종료 코드 0 무출력)
• "Exit code 1 without valid JSON output is a non-blocking error ... If your hook is meant to enforce a policy, use exit 2."
• "A policy hook with a wrong path or a crashing script then lets everything through." (onFailure 미설정)
• "Because the if filter is best-effort, use the permission system rather than a hook to enforce a hard allow or deny."
• "suppressOriginalPrompt changes only the block message ... a blocking hook isn't a way to keep a secret off disk."
• "Command hooks execute shell commands with your full user permissions."

우회 경로로 원본이 직접 밝힌 것 (정책 훅 설계 때 확인할 목록):

• 프롬프트에서 @로 참조한 파일은 도구 호출 없이 들어가므로 Read에 맞춘 PreToolUse 훅도 돌지 않는다. 막으려면 Read deny 규칙을 쓰거나 CLAUDE_CODE_DISABLE_FILE_MENTIONS=1(v2.1.299 이상, 프로젝트·로컬 설정에서는 무시)을 쓴다.
• /스킬이름을 직접 입력하면 Skill 도구에 맞춘 PreToolUse를 거치지 않는다. 이 경로는 UserPromptExpansion이 받는다.
• Edit|Write에 맞춘 PostToolUse는 Bash 명령이나 Claude Code 밖 프로세스가 같은 파일을 고칠 때 돌지 않는다. 파일 자체를 보려면 FileChanged(막지는 못함)를 쓴다.
• Claude가 Bash로 git worktree add를 돌리면 WorktreeCreate 훅이 돌지 않는다. PreToolUse Bash 훅으로 봐야 한다.
• Windows에서 PowerShell 도구가 켜져 있으면 셸 명령이 PowerShell로 가고, Git Bash가 없으면 Bash 도구가 아예 등록되지 않는다. Bash에만 맞춘 훅은 거기서 돌지 않으므로 Bash|PowerShell로 맞춘다.
• Windows 경로는 역슬래시로 온다. 슬래시로 쓴 비교(/src/)는 맞지 않고 호출은 "막을 것이 없는 것처럼" 진행된다.
• 훅이 결정을 백그라운드 프로세스에서 내리고 먼저 끝나면, 나중에 찍힌 deny는 호출을 막지 못한다.

버전 조건 (원본 표기 그대로, 수집일 기준)

• onFailure: v2.1.295 이상. async 훅 응답이 여러 줄에 걸치는 것: v2.1.295 이상.
• CLAUDE_CODE_DISABLE_FILE_MENTIONS: v2.1.299 이상. PowerShell 명령이 CLAUDE_ENV_FILE 변수를 받는 것: v2.1.296 이상. 디버그 로그 Hooks: 소요 시간 줄: v2.1.296 이상.
• PreModelSwitch·PostModelSwitch, SessionStart의 재개 비용 필드(context_tokens 등): v2.1.251 이상.
• PreToolUse 입력의 mcp_server: v2.1.274 이상. StopFailure cloud_credential_error: v2.1.267 이상. scratchpad_dir: v2.1.257 이상. classifierContext: v2.1.236 이상.
• 변경 이력: v2.1.211 전에는 자동 모드 분류기가 훅의 "ask"를 건너뛰고 샌드박스 밖 Bash를 승인할 수 있었다. v2.1.218 전에는 프로젝트 서브에이전트 frontmatter 훅이 신뢰하지 않은 폴더에서도 돌 수 있었다. v2.1.216 전에는 WorktreeCreate 경로를 심볼릭 링크 검사 없이 따랐다. v2.1.214 전에는 if의 "Edit(src/**)"가 아무 깊이의 src에 맞았다. v2.1.105~v2.1.284 사이에는 Elicitation·ElicitationResult의 최상위 decision이 무시됐다. SessionEnd 매처 bypass_permissions_disabled는 v2.1.234에서 제거됐다.

가이드와의 관계#

• 가이드 요약(Claude Code 훅 가이드)이 적은 이벤트 목록, matcher 미지원 이벤트 목록, 기본 타임아웃, PreToolUse 결정 우선순위(deny > defer > ask > allow), 종료 코드 2의 이벤트별 차이, allowManagedHooksOnly 표시는 이 레퍼런스와 같다.
• 레퍼런스가 더 넓게 말하는 곳: allowManagedHooksOnly가 켜지면 가이드가 든 user·project·local 훅뿐 아니라 플러그인 훅도 막힌다(managed enabledPlugins로 강제 활성화한 플러그인의 훅은 예외). 상충이라기보다 범위 추가다. → managed settings
• 컴팩션과 훅 출력의 상충(블로그 vs 공식 컨텍스트 창 문서)에 대해서는 직접 판정하지 않지만, SubagentStart가 넣은 컨텍스트를 자동 컴팩션이 버린다는 문장 등 부분 근거를 준다. → 장기 작업 컨텍스트 관리