훅

정의#

Claude Code가 생명주기 이벤트에 이르렀을 때 실행되는 동작이다. 셸(용어 사전) 명령(스크립트), HTTP 요청, MCP 도구 호출, LLM 프롬프트, 서브에이전트 중 하나를 돌린다. Claude Code 확장 기능 개요

이벤트 예: 도구 실행, 세션 경계, 프롬프트 제출, 권한 요청, 컴팩션. 원본이 이름으로 든 것은 PostToolUse, SessionStart, PreToolUse다. Claude Code 확장 기능 개요

(2026-06-18 기준) 블로그 글은 훅을 파일 편집, 도구 호출, 세션 시작 같은 생명주기 이벤트에 실행되는 사용자 정의 명령, HTTP 엔드포인트, LLM 프롬프트로 설명한다. 등록 위치는 settings.json, managed 정책 설정, 스킬·에이전트 frontmatter다. 종류는 command, HTTP, mcp_tool, prompt, agent 다섯 가지다. Steering Claude Code 공식 훅 가이드(2026-10-18 기준)가 다섯 종류와 등록 위치(settings 파일, managed 정책, 스킬·서브에이전트 frontmatter, 그리고 플러그인 hooks/hooks.json)를 확인한다. 같은 가이드는 agent 훅이 실험 기능이라 바뀔 수 있으니 운영 워크플로에는 command 훅을 권한다. Claude Code 훅 가이드

(2026-10-18 기준) 공식 훅 가이드의 정의: 훅은 사용자가 정의한 셸 명령으로, Claude Code가 생명주기의 정해진 지점에서 실행해 결정론적 통제를 준다. 원본 표현: "certain actions always happen rather than relying on the LLM to choose to run them." 규칙이 아니라 판단이 필요한 결정에는 Claude 모델이 조건을 평가하는 prompt 훅(단일 LLM 호출)이나 agent 훅(도구로 파일·명령을 확인하는 서브에이전트)을 쓸 수 있다. Claude Code 훅 가이드

(2026-10-18 기준) 공식 레퍼런스는 훅을 "user-defined shell commands, HTTP endpoints, MCP tool calls, LLM prompts, or subagents"로 정의하고, 터미널·IDE 확장·데스크톱 앱·클라우드 세션 어디서 돌든 같은 이벤트가 발생한다고 말한다. 단 클라우드 세션은 로컬 ~/.claude/settings.json을 읽지 않는다. 플러그인이 Claude Code 프로세스 안에서 부르는 JavaScript 함수로 등록하는 훅(mod)은 별도 문서가 다루고, 이 페이지의 훅과 함께 동작한다. settings 파일·managed 정책·플러그인의 훅은 서브에이전트 안의 도구 호출에도 실행된다. Claude Code 훅 레퍼런스 → 서브에이전트

핵심: 결정론적 실행#

• 훅은 Claude가 결정하지 않아도 자기 이벤트에서 실행된다. 반면 스킬은 Claude가 해석하므로 결과가 달라질 수 있다. Claude Code 확장 기능 개요
• (2026-06-18 기준) 블로그 글은 트리거와 실행을 나눠 말한다. 모든 훅은 결정론적으로 트리거된다. command·HTTP·mcp_tool은 결정론적으로 실행되고, prompt·agent 훅은 규칙 대신 Claude의 판단으로 출력을 정한다. 하네스가 핸들러를 직접 돌리거나(command, http, mcp_tool) 별도 창에서 모델을 호출한다(prompt, agent). Steering Claude Code
• 가드레일은 훅에 둔다. CLAUDE.md나 스킬에 쓴 "절대 .env를 고치지 마라"는 요청이지 보장이 아니다. 편집을 막는 PreToolUse 훅이 강제다. 매번 지켜져야 하는 규칙이면 프롬프트 지시가 아니라 훅으로 만든다. Claude Code 확장 기능 개요
• 메모리(CLAUDE.md)와 출력 스타일은 둘 다 지시로만 따르므로 어느 쪽도 강제되지 않는다. 매번 일어나야 하는 일은 훅을 쓴다. Claude Code 확장 기능 개요 공식 출력 스타일 문서(2026-10-18 기준)도 출력 스타일은 "아무것도 강제하지 않는다"며, 편집마다 포맷하거나 명령을 막는 것처럼 예외 없이 매번 일어날 일은 훅에 두라고 한다. 이유: Claude Code가 생명주기 이벤트에 훅을 직접 실행해 Claude가 지시를 따르는지에 기대지 않는다. Claude Code 출력 스타일 → 출력 스타일
• (2026-06-18 기준) 블로그 글: "절대 하지 마라"를 CLAUDE.md에 쓰는 것은 잘못된 도구다. Claude는 대부분 따르지만 압박, 긴 세션, 모호한 상황, 작업 중 읽은 파일의 프롬프트 인젝션으로 프롬프트 규칙을 못 지킬 수 있다. 진짜 가드레일은 결정론적이어야 하고 강제 수단은 훅과 권한(권한 모드)이다. PreToolUse 훅은 어떤 도구 호출이든 검사해 종료 코드 2로 막는다. managed settings는 조직 전체의 결정론적 가드레일을 강제하는 유일한 방법이다(블로그 평가). Steering Claude Code 이 "덮어쓸 수 없다·유일한 방법"은 블로그 단독 주장이다. 공식 권한 모드 문서(2026-10-18)는 일부만 확인한다: managed·project의 permissions.defaultMode는 ~/.claude/settings.json보다 우선하지만, 시작 모드는 --permission-mode 플래그(또는 --dangerously-skip-permissions)가 settings보다 먼저이고, managed defaultMode로 시작해도 "people can still switch to auto mode"라서 자동 모드를 아무도 못 고르게 하려면 permissions.disableAutoMode를 따로 써야 한다. "유일한 방법"이라는 일반 주장은 공식 문서가 확인하지 않는다. Claude Code 권한 모드 → Claude Code 관리자 권한 통제 공식 managed settings 배포 문서(2026-10-18)는 "덮어쓸 수 없다"를 설정 파일 기준으로 확인한다: user·project·local·--settings 값은 managed 값을 덮어쓰지 못하되, 몇몇 보안 민감 예외에서는 낮은 레벨의 더 엄격한 값이 효력을 갖는다. 같은 문서는 이 규칙 밖의 경우(managed model·autoCompactWindow는 기본값, 로컬 관리자의 관리 출처 수정, Claude Code 밖의 도구)도 적고, "유일한 방법"이라고는 말하지 않는다. Claude Code managed settings 배포 → managed settings
• 공식 메모리 문서도 같은 입장이다. Claude가 무엇을 결정하든 행동을 막으려면 PreToolUse 훅을 쓰고, 커밋 전이나 파일 편집 후처럼 특정 시점에 돌아야 하는 지시는 훅으로 쓰라고 한다. 훅은 고정된 생명주기 이벤트에 셸 명령으로 실행된다. Claude Code 메모리
• (2026-10-18 기준) 공식 훅 가이드는 가드레일로서의 훅을 확인하면서 조건을 붙인다. PreToolUse 훅은 어떤 권한 모드 검사보다 먼저 dontAsk를 포함한 모든 모드에서 돌고, permissionDecision: "deny"는 bypassPermissions나 --dangerously-skip-permissions에서도 도구를 막는다. 원본은 이것으로 "users can't bypass by changing their permission mode" 정책을 강제할 수 있다고 말한다. 같은 원본이 밝힌 조건과 한계는 다음과 같다. Claude Code 훅 가이드
  • matcher가 맞춘 도구만 검사한다. Edit|Write matcher는 Bash를 보지 않고, Claude는 셸 명령으로도 파일을 만들거나 고칠 수 있다. 모든 파일 변경을 봐야 하면 턴마다 작업 트리를 훑는 Stop 훅을 더하거나, 호출마다 보려면 Bash|PowerShell도 맞추고 git status --porcelain으로 바뀐 파일을 나열하라고 한다.
  • 도구 인자까지 거르는 if 필드는 최선 노력이다. 확실한 허용·거부는 훅이 아니라 권한 시스템으로 하라고 한다.
  • 설치한 mod가 tool.check를 다루면 PreToolUse 훅이 막은 호출을 승인할 수 있다(plan 모드에서는 읽기 전용 호출만). 가이드는 managed settings에 둔 훅을 예외로 들고, 세부 기준은 권한 문서로 넘긴다. (2026-10-21 기준) 권한 문서 기준으로 정리하면: 기기에 managed settings가 있거나 Team·Enterprise /login이 세션 자격 증명이면 훅이 막은 호출은 훅이 어느 설정 파일에 있든 기본으로 막힌 채 남고, 둘 다 없으면(API 키·CLAUDE_CODE_OAUTH_TOKEN 세션 포함) mod가 훅이 막은 호출도 승인할 수 있다(아래 ‘원본끼리 달랐던 점’ 상자). Claude Code 권한 설정
  • 훅은 disableAllHooks로 꺼질 수 있다(아래 "조합과 레벨").
  • 블로그의 "PreToolUse 훅은 어떤 도구 호출이든 검사해 종료 코드 2로 막는다"는 이 조건 안에서 읽는다. 편집자 해석: "어떤 도구 호출이든"은 matcher가 그 도구를 맞출 때로 볼 수 있다. 근거는 가이드의 "The "Edit|Write" matcher fires only when Claude uses the Edit or Write tool, not when it uses Bash" 문장이다. 공식 레퍼런스(2026-10-18 기준)는 PreToolUse가 EndConversation을 뺀 모든 도구 이름에 맞을 수 있다고 적는다. 다만 프롬프트에서 @로 참조한 파일은 도구 호출 없이 들어가 Read에 맞춘 PreToolUse 훅도 돌지 않는다. Claude Code 훅 레퍼런스

• (2026-10-18 기준) 공식 레퍼런스가 더하는 조건: 차단이 실제로 일어나려면 신호가 정확해야 하고, 훅이 실패해도 막도록 설정해야 한다. Claude Code 훅 레퍼런스 → Claude Code 차단 훅 단단하게 만들기
  • 종료 코드 0에 출력이 없으면 승인이 아니라 일반 권한 흐름으로 간다. 원본: "The hook can deny the call, but staying silent doesn't approve it."
  • 종료 코드 1은 올바른 JSON이 없으면 막지 않는 오류다(실패하면 막도록 설정한 훅, 즉 onFailure: "block"은 예외). 원본: "If your hook is meant to enforce a policy, use exit 2."
  • 대부분의 이벤트에서 훅이 시작하지 못하거나 0·2가 아닌 코드로 끝나거나 시간을 넘기면 동작이 진행된다(원본: "lets everything through"). command·http 훅에 "onFailure": "block"(v2.1.295 이상)을 두면 실패를 차단으로 바꾼다. Stop·SubagentStop·TaskCompleted·TeammateIdle과 async 훅에는 효과가 없다.
  • 대화형 세션은 작업 공간 신뢰를 수락하기 전까지 settings 파일의 훅을 보류하지만, -p·SDK 세션은 폴더를 신뢰한 것으로 다뤄 저장소에 커밋된 훅을 바로 돌린다. command 훅은 사용자의 전체 권한으로 실행된다. (2026-10-21 기준) 공식 권한 문서의 표도 상위 폴더만 신뢰했거나 -p·SDK로 돌릴 때 settings 파일 훅과 프로젝트 스킬 훅이 쓰인다고 확인한다. 편집자 해석: 같은 표에서 프로젝트 .claude/settings.json의 allow 규칙은 -p에서도 쓰이지 않으므로, "신뢰한 것으로 다룬다"는 훅에 대한 말로 읽는 편이 맞다고 볼 수 있다. 근거는 표의 첫째 행(settings 파일 훅, -p 열 "Used")과 둘째 행(permissions.allow, -p 열 "Not used")이다. 권한 문서가 -p·SDK 세션을 "counts as accepted"로 적는 곳은 local 설정 파일의 git 검사를 설명하는 문단이다. Claude Code 권한 설정 → 작업 공간 신뢰

이벤트와 설정 형식 (2026-10-18 기준)#

• 설정은 settings 파일의 hooks 객체 하나 안에 이벤트 이름을 키로 두고, 이벤트마다 matcher와 hooks 배열(핸들러 목록)을 단다. 핸들러마다 type(command·http·mcp_tool·prompt·agent)과 그 종류의 필드(command, url, prompt 등)를 쓴다. Claude Code 훅 가이드
• 원본 표의 이벤트는 세션(SessionStart, Setup, SessionEnd), 프롬프트(UserPromptSubmit, UserPromptExpansion), 도구(PreToolUse, PermissionRequest, PermissionDenied, PostToolUse, PostToolUseFailure, PostToolBatch), 응답·알림(Notification, MessageDisplay, Stop, StopFailure), 서브에이전트·작업·팀(SubagentStart, SubagentStop, TaskCreated, TaskCompleted, TeammateIdle), 지시·설정·파일(InstructionsLoaded, ConfigChange, CwdChanged, DirectoryAdded, FileChanged, WorktreeCreate, WorktreeRemove), 컴팩션(PreCompact, PostCompact), 모델 전환(PreModelSwitch, PostModelSwitch), MCP(Elicitation, ElicitationResult)에 걸쳐 있다. 묶음은 편집자가 나눈 것이고 원본은 한 표로 나열한다. Claude Code 훅 가이드
• matcher가 거르는 필드는 이벤트마다 다르다(도구 이벤트는 도구 이름, SessionStart는 startup·resume·clear·compact·fork, Notification은 알림 종류, ConfigChange는 설정 출처 등). UserPromptSubmit, Stop, CwdChanged 등 일부 이벤트는 matcher를 지원하지 않아 매번 실행된다. 도구 이벤트에서는 if 필드로 인자까지 거를 수 있다. Claude Code 훅 가이드
• 기본 타임아웃: command·http·mcp_tool 10분(단 UserPromptSubmit·PreModelSwitch·PostModelSwitch 30초, MessageDisplay 10초), prompt 30초, agent 60초. SessionEnd 훅은 모두 1.5초 예산을 나눈다(훅별 timeout을 길게 두면 최대 60초). Claude Code 훅 가이드
• command 훅은 stdout·stderr·종료 코드로만 말하고 / 명령이나 도구 호출을 일으키지 못한다. HTTP 훅은 응답 본문으로 말한다. Claude Code 훅 가이드
• (2026-10-18 기준) 공식 레퍼런스는 세 층을 hook event, matcher group, hook handler로 부른다. 같은 핸들러를 settings 파일 여러 곳에 두면 한 번만 돌고, 플러그인·스킬의 같은 사본은 따로 돈다. 맞는 훅은 모두 병렬로 돈다. matcher·핸들러 필드·exec form과 shell form·입력 공통 필드·JSON 출력 규칙 전체는 훅 입출력 규칙, 33개 이벤트 각각의 matcher·입력·결정 제어는 훅 이벤트 레퍼런스. Claude Code 훅 레퍼런스
• 레시피(알림, 포맷, 보호 파일, 컴팩션 뒤 재주입, 설정 감사, direnv, 자동 승인)는 Claude Code 훅 설정 레시피.

언제 쓰는가#

• 같은 방식으로 매번 일어나야 하고 Claude가 생각할 필요가 없는 동작. 원본 예: 저장 시 포맷, rm -rf / 거부, 세션 종료 때 Slack 메시지. Claude Code 확장 기능 개요
• 잘 맞는 용도: 편집 후 린트, 위험한 명령 차단, 로깅, 알림. 원본 예: 파일을 편집할 때마다 ESLint 실행. Claude Code 확장 기능 개요
• (2026-06-18 기준) 블로그 글의 용도: 결정론적으로 일어나야 하는 모든 것. 편집 후 린터, 완료 시 Slack 게시, 실행 전 특정 명령 차단, PreCompact에서 대화 기록 백업. CLAUDE.md에 "매번 X면 항상 Y"를 쓰고 있다면 훅으로 옮길 신호다. Steering Claude Code → Claude Code 확장 기능 고르기
• 훅과 스킬은 멈춤 조건을 만날 때까지 반복하는 에이전트 루프를 설계하는 구성 요소다. Steering Claude Code
• 셋업 계기: 묻지 않아도 매번 무언가 일어나게 하고 싶을 때. Claude Code 확장 기능 개요 → Claude Code 셋업 점진적으로 키우기
• 쓰지 않을 때: Claude가 단계를 어떻게 적용할지 판단해야 하거나, 내용이 스크립트가 아니라 지식일 때는 스킬을 쓴다(/release 체크리스트, API 스타일 가이드, 디버깅 플레이북). Claude Code 확장 기능 개요

컨텍스트 비용#

• 기본으로는 아무것도 로드되지 않는다. 훅은 메인 대화 밖에서 실행되므로 비용이 0이다. 단, 훅이 출력을 돌려주면 그 출력이 대화에 메시지로 들어간다. Claude Code 확장 기능 개요
• 원본은 Claude의 컨텍스트에 영향을 줄 필요가 없는 부작용(린트, 로깅)에 훅이 이상적이라고 한다. Claude Code 확장 기능 개요 → 컨텍스트 비용
• (2026-06-18 기준) 블로그 글은 비용 등급을 Low로 적는다(블로그 평가). 설정과 지시가 메인 컨텍스트 창 밖에 있고, 훅은 Claude에게 로드되는 지시가 아니라 하네스가 실행하는 코드이기 때문이다. 일부 출력은 메인 컨텍스트에 남는다. 예컨대 차단 훅의 표준 오류는 Claude가 호출이 왜 거부됐는지 알도록 컨텍스트에 남는다. 그러나 대부분의 훅 출력은 설정이 명시적으로 돌려주지 않는 한 남지 않는다. PreCompact에서 대화 기록을 다른 파일에 백업해도 Claude는 어느 파일에 저장됐는지 모른다. 원본은 이 점에서 훅이 CLAUDE.md·rules·스킬과 근본적으로 다르다고 말한다. 0과 Low의 표기 차이는 컨텍스트 비용의 메모 참고(2026-10-21 상충에서 일반 메모로 낮춤). Steering Claude Code
• 컴팩션: (2026-06-18 블로그. 공식 기준으로 정리돼 날짜 계산에서 뺀다, 아래 콜아웃) 훅은 컴팩션을 완전히 우회한다. Steering Claude Code → 장기 작업 컨텍스트 관리
• (2026-10-18 기준) 공식 컨텍스트 창 문서는 컴팩션 뒤 동작을 둘로 나눠 적는다. 앞서 훅이 더한 컨텍스트는 나머지 대화와 함께 요약되고, compact 소스에 맞는 SessionStart 훅은 컴팩션 뒤 실행돼 출력을 컴팩션된 컨텍스트에 더한다. 위 블로그 문장과의 정리(공식 기준) 콜아웃과 편집자 해석은 장기 작업 컨텍스트 관리에 있다. Claude Code 컨텍스트 창
• (2026-10-18 기준) 공식 훅 가이드는 두 주장의 차이를 직접 판정하지 않는다. 다만 컴팩션이 대화를 요약하며 "This can lose important details"라고 말하고, 그래서 compact matcher를 단 SessionStart 훅으로 "after every compaction" 핵심 컨텍스트를 다시 넣으라고 한다. 컴팩션 앞뒤에 실행되는 PreCompact·PostCompact 이벤트도 있고, matcher로 manual·auto를 거른다. Claude Code 훅 가이드 → Claude Code 훅 설정 레시피
• (2026-10-18 기준) 공식 레퍼런스도 두 주장의 차이를 직접 판정하지 않지만 부분 근거를 준다. additionalContext는 훅이 발생한 지점의 대화에 system reminder로 들어가고 트랜스크립트에 저장된다. SubagentStart 훅이 서브에이전트에 넣은 사본은 "After auto-compaction discards that copy" 다시 넣는다고 적는다. PreCompact는 컴팩션을 막을 수 있고, PostCompact는 생성된 요약(compact_summary)을 받는다. 판단은 장기 작업 컨텍스트 관리의 정리 콜아웃에 적었다. Claude Code 훅 레퍼런스

• 훅 출력은 컨텍스트에 들어간다. 린터를 돌리는 PostToolUse 훅은 결과를 Claude가 읽는 텍스트로 되돌려 주고, /fix-lint 스킬은 그걸 어떻게 고칠지 알려 준다. Claude Code 확장 기능 개요
• (2026-10-18 기준) 어떤 출력이 들어가는지는 공식 컨텍스트 창 문서가 구체적으로 적는다. Claude Code 컨텍스트 창
  • Claude에게 정보를 보내려면 JSON의 hookSpecificOutput.additionalContext로 출력한다. 이 필드가 Claude의 컨텍스트에 들어간다.
  • (공식 훅 가이드) additionalContext는 hookSpecificOutput 안에 둬야 한다. 최상위에 두면 JSON은 파싱되지만 Claude Code가 오류 없이 무시한다. 돌려준 텍스트는 system reminder로 주입되고 Claude는 일반 텍스트로 읽는다. 같은 이벤트에 여러 훅이 맞으면 모든 훅의 additionalContext가 함께 전달된다. Claude Code 훅 가이드
  • 종료 코드 0의 일반 stdout은 컨텍스트에 들어가지 않고 디버그 로그에만 쓰인다. 원본은 이것을 PostToolUse 훅 예와 시뮬레이션 요약("plain stdout on exit 0 goes to the debug log, not the transcript")에서 말한다. 같은 원본에서 compact 소스 SessionStart 훅은 출력을 컴팩션된 컨텍스트에 더하므로 이벤트별 차이가 있다. 공식 훅 가이드가 이 차이를 확인한다: 종료 코드 0에서 Claude Code가 일반 텍스트로 다루는 stdout은 UserPromptSubmit·UserPromptExpansion·SessionStart·PostModelSwitch 훅에서 Claude의 컨텍스트에 더해진다. 원본이 이름으로 든 것은 이 네 이벤트이고, 나머지 이벤트의 처리는 레퍼런스로 넘긴다. Claude Code 훅 가이드 공식 레퍼런스(2026-10-18 기준)가 이것을 일반 규칙으로 확인한다: 대부분의 이벤트에서 stdout은 디버그 로그로만 가고 트랜스크립트에 보이지 않으며, 예외는 같은 네 이벤트다. 파싱에 실패한 stdout은 이 네 이벤트에서도 더하지 않는다. Claude Code 훅 레퍼런스 → 훅 입출력 규칙
  • 종료 코드 2는 stderr를 오류로 Claude에게 보여 준다. 다만 PostToolUse 훅에서는 도구가 이미 실행됐으므로 막지 못한다.
  • (공식 훅 가이드) 종료 코드 2의 stderr가 가는 곳은 이벤트마다 다르다. 어떤 이벤트는 Claude에게 피드백으로 주고, 어떤 이벤트는 사용자에게 보여 주며, ConfigChange·Elicitation 같은 몇몇은 메시지를 보이지 않는다. SessionStart처럼 막을 수 없는 이벤트에서는 stderr를 사용자에게 보여 주고 실행이 계속된다. 0과 2가 아닌 종료 코드는 대부분의 이벤트에서 막지 않는 오류로 처리된다. Claude Code 훅 가이드
  • 출력이 10,000자를 넘으면 파일로 저장되고, Claude는 미리보기와 파일 경로를 받는다.
  • (공식 레퍼런스, 2026-10-18 기준) 이 상한은 additionalContext·systemMessage·initialUserMessage 문자열과 일반 stdout 각각에 따로 적용되고, 미리보기는 앞 2,000자까지다. 올리는 설정이나 환경 변수는 없고, Claude Code는 Claude에게 그 파일을 읽으라고 하지 않으므로 꼭 봐야 할 것은 상한 안에 둔다. additionalContext는 사실 진술로 쓰라고 한다. 명령형 시스템 지시처럼 쓰면 Claude의 프롬프트 인젝션 방어를 건드려 컨텍스트로 쓰지 않고 사용자에게 보고할 수 있다. 재개(--continue·--resume) 때 세션 중 이벤트의 주입 텍스트는 훅을 다시 돌리지 않고 저장본을 다시 쓰므로 낡을 수 있다. Claude Code 훅 레퍼런스 → 훅 입출력 규칙
  • 맞는 도구 이벤트마다 다시 실행된다(원본 예: 파일을 편집할 때마다 prettier). 훅 실행은 터미널에 보이지 않는다.

메모리 관련 훅 (2026-10-18 기준)#

• InstructionsLoaded: 어떤 CLAUDE.md와 규칙 파일이 언제, 왜 로드됐는지 기록한다. 경로별 규칙이나 하위 디렉터리 지연 로드를 디버깅할 때 쓴다. 설정으로 직접 읽은 AGENTS.md에는 실행되지 않는다. Claude Code 메모리 → CLAUDE.md 문제 해결 공식 훅 가이드는 이 이벤트의 matcher(로드 이유)로 session_start, nested_traversal, path_glob_match, include, compact를 든다. Claude Code 훅 가이드
• 매 세션 시작 때 같은 컨텍스트를 넣는 일이면 훅 대신 CLAUDE.md를 고려하라고 공식 훅 가이드가 말한다. 컴팩션 뒤에만 다시 넣을 것은 compact matcher의 SessionStart 훅으로 한다. Claude Code 훅 가이드
• SessionStart로 AGENTS.md를 출력하던 예전 우회 설정은, Claude Code가 AGENTS.md를 직접 읽게 되면 사본이 하나 더 들어가므로 지운다. Claude Code 메모리 → AGENTS.md와 CLAUDE.md 함께 쓰기

권한과 맞닿는 훅 (2026-10-18 기준)#

공식 권한 모드 문서는 훅을 사용자 정의 권한 로직(PreToolUse, PermissionRequest)으로 소개한다. Claude Code 권한 모드 → 권한 모드

• dontAsk 모드는 물어야 할 호출을 모두 거부하지만, PreToolUse 훅이 승인한 호출은 실행한다. Claude Code 권한 모드
• 그래도 치명 경로(루트, 홈, 작업 디렉터리 등)를 겨냥한 rm·rmdir은 PreToolUse 훅이 "allow"를 돌려줘도 승인되지 않는다. 원본은 모델 오류에 대비한 차단기라 부른다. Claude Code 권한 모드
• 확인 창을 띄우는 모드에서는 PermissionRequest 훅이 그 확인 창에 답할 수 있다. Claude Code 권한 모드
• 훅이 강제로 띄운 확인 창에는 "Yes, and switch to auto mode" 선택지가 붙지 않는다. 자동 모드에서도 그 창은 뜨기 때문이다. Claude Code 권한 모드
• PostToolUse 훅의 classifierContext 필드로 호출 결과에 주석을 달면, 자동 모드 분류기가 애플리케이션이 준 맥락으로 읽는다(v2.1.236 이상). Claude Code 권한 모드

공식 훅 가이드(2026-10-18 기준)가 더하는 것: Claude Code 훅 가이드

• 조이기는 되고 풀기는 안 된다. settings 파일과 플러그인 hooks/hooks.json의 훅은 제한을 더할 수 있지만 권한 규칙이 허용하는 범위 너머로 풀 수 없다. "allow"를 돌려줘도 settings의 deny 규칙을 넘지 못하고, 네트워크 경로 읽기, requiresUserInteraction 표시 MCP 도구, 조직이 ask로 정한 커넥터 도구(그 설정이 Claude Code에 닿는 세션에서)의 확인 창을 없애지 못한다. 위의 치명 경로 rm·rmdir은 권한 모드 문서가 든 항목이고, 가이드의 목록에는 없다.
• plan 모드에서 PreToolUse 훅이 파일 편집을 "allow"하면 훅이 없을 때와 같은 확인·차단·승인을 받는다. 이 제한을 풀려면 계획을 승인하거나 다른 모드로 바꾼다.
• PreToolUse 결정 값은 allow, deny, ask, 그리고 -p 비대화형 모드의 defer(도구 호출을 보존한 채 끝내 Agent SDK 래퍼가 재개)다.
• PermissionRequest 훅은 hookSpecificOutput.decision.behavior: "allow"로 확인 창에 대신 답하고, updatedPermissions의 setMode로 세션 권한 모드를 바꿀 수 있다. bypassPermissions로의 전환은 세션을 bypass가 가능한 상태로 시작했을 때만 적용되고 permissions.disableBypassPermissionsMode나 restricted mode에서는 적용되지 않는다. matcher를 비우거나 .*로 두면 파일 쓰기·셸 명령을 포함한 모든 확인을 자동 승인하므로 최대한 좁게 둔다. → Claude Code 훅 설정 레시피
• PermissionDenied는 자동 모드가 호출을 거부할 때 실행되고, hookSpecificOutput.retry: true로 모델에게 다시 시도해도 된다고 알릴 수 있다. 분류기 판정이 없는 거부에서는 retry를 무시한다.

훅은 샌드박스 밖에서 돈다 (2026-10-21 기준). 공식 Sandboxing 문서는 명령 훅을 로컬 MCP 서버·상태 줄 명령과 함께 "사용자의 전체 권한으로 도는" 프로세스로 든다. 샌드박스를 켜도 훅 스크립트는 그 경계 밖이고, 샌드박스는 오히려 .claude/hooks와 .claude 설정 파일을 보호 경로로 두어 샌드박스 명령이 훅을 더하지 못하게 한다. 이 보호는 작업 디렉터리와 그 위 디렉터리, ~/.claude 기준이고, 파일 격리를 끄는 filesystem.disabled를 켜면 꺼지며, excludedCommands나 샌드박스 밖 재시도처럼 샌드박스 밖에서 도는 명령에는 적용되지 않는다. Claude Code 샌드박스 → 샌드박스

조합과 레벨#

• 훅 + MCP: 중요한 파일을 고치면 편집 후 훅이 MCP를 통해 Slack 알림을 보낸다. Claude Code 확장 기능 개요
• 여러 곳(user, project, 플러그인, managed 정책)에 등록된 훅은 덮어쓰지 않고 합쳐진다. 출처와 상관없이 등록된 훅 모두가 맞는 이벤트에 실행된다. Claude Code 확장 기능 개요
• (2026-10-18 기준) 공식 훅 가이드가 이 "모두 실행"에 붙이는 조건: 훅을 끄는 "disableAllHooks": true는 설정 우선순위를 적용한 뒤의 값을 읽어 프로젝트 설정이 사용자 설정을 덮을 수 있고, managed settings의 훅은 managed settings에도 disableAllHooks가 있어야 꺼진다. 조직이 allowManagedHooksOnly를 켜면 user·project·local 설정 파일의 훅은 실행되지 않는다. Claude Code 훅 가이드
• (2026-10-18 기준) 같은 이벤트에 맞는 훅은 병렬로 끝까지 실행된 뒤 결과가 합쳐진다. PreToolUse 권한 결정은 가장 제한적인 답이 이긴다(deny, defer, ask, allow 순). 한 훅의 deny는 다른 훅의 실행을 멈추지 않으므로 다른 훅의 부작용을 막는 데 기대지 않는다. 여러 훅이 updatedInput으로 같은 도구의 인자를 고치면 마지막에 끝난 것이 적용되고 순서는 비결정적이다. Claude Code 훅 가이드
• (2026-10-18 기준) 공식 레퍼런스: user·project·local 설정은 managed 훅을 지우지 않고 자기 훅을 더한다. 한 번만 훅을 끄려면 --settings '{"disableAllHooks": true}'(프로젝트·로컬 설정보다 우선)를 쓰고, 훅 하나만 설정에 남긴 채 끄는 방법은 없다. allowManagedHooksOnly는 가이드가 든 user·project·local 훅뿐 아니라 플러그인 훅도 막는다(managed enabledPlugins로 강제 활성화한 플러그인의 훅은 예외). HTTP 훅 허용 목록은 managed를 포함한 모든 출처의 훅에 적용된다. Claude Code 훅 레퍼런스 → managed settings
• (2026-10-21 기준) 공식 Settings 문서: 설정 파일의 hooks 편집은 재시작 없이 실행 중인 세션에 적용된다. 팀에 훅을 나누려면 .claude/settings.json을 커밋한다. 설정 파일 변경마다 ConfigChange 훅이 돌지만 MDM·claude.ai 콘솔로 오는 managed settings에는 돌지 않는다. Claude Code 설정 파일과 우선순위 → Claude Code 설정 파일
• 플러그인에 훅을 묶어 배포할 수 있다. Claude Code 확장 기능 개요
• (2026-10-18 기준) 조직이 훅을 통제하는 managed 키: allowManagedHooksOnly: true는 실행되는 훅을 제한하고(Claude Code 훅 가이드: 이때 /hooks 메뉴에 "Only hooks from managed settings run here"가 보이고 user·project·local 설정 파일의 훅은 실행되지 않고 목록에도 없다. 전체 효과는 settings reference), strictPluginOnlyCustomization은 user·project 출처의 훅을 막을 수 있다. HTTP 훅의 URL과 헤더에 넣을 환경 변수는 allowedHttpHookUrls·httpHookAllowedEnvVars 허용 목록으로 다루며, 이 두 목록은 user·project·local 설정 파일의 값과 합쳐진다. 여러 관리 출처를 managedSourcesBehavior: "merge"로 합치면 낮은 출처의 훅도 정책에 더해지므로, 아래 출처가 모두 관리자 통제 아래 있을 때만 켠다. 잘못된 managed disableAllHooks는 true로 강제하지 않고 버린다(그러면 조직이 배포한 훅까지 내려가기 때문). Claude Code managed settings 배포 → managed settings
• (2026-10-21 기준) settings reference가 밝힌 두 키의 전체 효과. allowManagedHooksOnly: true: managed 훅, Agent SDK가 프로세스 안에서 등록한 훅, managed enabledPlugins로 강제 활성화한 플러그인의 훅(plugin@marketplace 전체 ID가 맞아야 함)만 돈다. user·project·local 훅, 다른 플러그인의 훅과 mod, 에이전트 frontmatter에 선언한 훅은 막히고, Claude Code 내장 mod는 계속 돈다. disableAllHooks: 훅과 함께 커스텀 상태줄·@ 파일 제안 명령도 끈다. managed에 두면 managed 훅까지 모두 끄고 Agent SDK 훅만 남기며(v2.1.242 이상), 다른 파일에 두면 user·project·local·플러그인 훅만 끄고 managed 훅·SDK 훅·강제 활성화 플러그인 훅은 남는다. 두 키 중 하나라도 훅을 막고 있으면 /goal 명령이 돌지 않는다. hooks 키는 파일끼리 합쳐지고 managed 훅은 다른 파일이 지우지 못한다. Claude Code 설정 키 전체 레퍼런스 → Claude Code 설정 키 레퍼런스

스킬 안에 두는 훅 (2026-10-18 기준)#

• 위 블로그 글이 든 등록 위치 중 "스킬 frontmatter"는 공식 스킬 문서도 확인한다. 스킬의 hooks 필드에 적은 훅은 스킬을 부를 때 등록되고 세션 끝까지 돈다. Claude Code 스킬
• 공식 스킬 문서의 문제 해결 지침: Claude가 스킬을 따르다가 매번 지켜야 할 규칙을 건너뛰면 그 규칙을 훅으로 옮긴다. 훅은 Claude가 스킬을 따르든 말든 이벤트마다(예: 파일 편집 전마다) 돈다. 규칙을 스킬과 함께 두려면 스킬의 hooks frontmatter에 정의한다. Claude Code 스킬 → 스킬 문제 해결
• 공식 훅 가이드의 위치 표도 같다: 스킬 frontmatter의 훅은 스킬을 부른 뒤 세션 끝까지, 서브에이전트 frontmatter의 훅은 그 서브에이전트가 도는 동안 유효하다. Claude Code 훅 가이드
• (2026-10-18 기준) 공식 서브에이전트 문서도 frontmatter 훅이 그 서브에이전트가 활성인 동안만 돌고 끝나면 정리된다고 확인하고, 서브에이전트로 띄울 때와 --agent·agent 설정으로 메인 세션으로 돌 때 모두 돈다고 더한다. 프로젝트 서브에이전트 frontmatter 훅은 폴더 신뢰 전에는 건너뛰지만 서브에이전트 자체는 그대로 돈다(디버그 로그에 신뢰 방법). ~/.claude/agents/와 --agents의 훅은 이 확인 없이 돌고, 플러그인 서브에이전트는 hooks 필드를 무시한다. Claude Code 서브에이전트 → 서브에이전트 정의 파일 레퍼런스
• (2026-10-18 기준) 공식 레퍼런스가 더하는 것: 스킬 훅은 스킬의 턴 뒤 턴에도 계속 돌고, 첫 성공 뒤 지우려면 once: true(스킬 frontmatter에서만 유효)를 둔다. 서브에이전트 frontmatter의 Stop 훅은 SubagentStop으로 바뀐다. 프로젝트 스킬의 frontmatter 훅은 settings 파일과 같은 작업 공간 신뢰 규칙을 따르고, 신뢰하지 않은 폴더의 -p 실행에서도 스킬을 부르면 등록된다. 프로젝트 서브에이전트 frontmatter 훅은 신뢰 대화상자를 수락한 뒤에만 돈다(v2.1.218 이상). Claude Code 훅 레퍼런스
• 스킬 폴더를 플러그인으로 로드하는 경우, 그 폴더의 hooks/ 변경은 SKILL.md 실시간 반영 대상이 아니라 /reload-plugins가 필요하다. Claude Code 스킬

다른 도구에서: Antigravity CLI (2026-10-21 기준)#

Google의 전환 공지(2026-05-19)는 Antigravity CLI가 Gemini CLI의 핵심 기능 가운데 하나로 Hooks를 유지한다고 말했다. Gemini CLI의 Antigravity CLI 전환 공지 Antigravity 공식 Hooks 문서(원본 날짜 미상, 수집 2026-10-21)가 CLI·App·IDE의 훅 지원과 정의 방법을 적는다. 아래는 모두 이 문서 기준이다. Antigravity 훅 문서

• 용도: 실행 루프의 정해진 시점에 셸 명령을 돌려 규칙을 강제하고, 린터를 돌리고, 진단 정보를 남긴다. CLI 절의 예는 실행 전 점검과 파일을 쓴 뒤 prettier 같은 포매터 실행이다.
• 위치(CLI): 워크스페이스 .agents/hooks.json, 전역 ~/.gemini/config/hooks.json 또는 ~/.gemini/antigravity-cli/settings.json 안, 설치한 플러그인의 hooks.json. TUI에서 /hooks로 로드된 훅을 확인한다.
• 이벤트 6개: SessionStart, PreToolUse, PostToolUse, PreInvocation(모델 호출 전), PostInvocation(모델 호출 직후마다), Stop. matcher는 PreToolUse·PostToolUse에서만 쓰이는 도구 이름 정규식(예: "run_command|view_file", "browser_.*")이고, 나머지 이벤트에서는 무시된다.
• 핸들러: 원본은 "Currently only "command" is supported"라고 쓴다. command(필수), timeout(초, 기본 30). 훅 이름에 enabled: false를 두면 지우지 않고 끈다.
• 입출력: stdin으로 JSON을 받고 stdout으로 JSON을 돌려준다(camelCase). PreToolUse는 decision(필수)으로 allow·auto_approve·deny·ask·force_ask·deny_unless_prior_grant 중 하나를 고르고, overwrite로 도구 인자를 바꿀 수 있다. Stop은 decision: "continue"로 멈춤을 막는다. SessionStart·PreInvocation·PostInvocation은 injectSteps로 대화에 단계(메시지나 도구 호출)를 넣는다.

{
  "my-linter-hook": {
    "PostToolUse": [
      {
        "matcher": "run_command",
        "hooks": [
          { "type": "command", "command": "./scripts/lint.sh", "timeout": 10 }
        ]
      }
    ]
  }
}

막는 훅의 조건과 한계(원본 기준): deny는 "Hard blocks execution immediately"라고 쓰지만, matcher가 맞춘 도구 호출에만 걸린다. allow는 승인을 강제하지 않고 다음 훅이나 기본 정책에 판단을 넘기며, auto_approve도 사용자가 명시적으로 설정한 규칙은 따른다. 훅 명령이 실패하거나 시간을 넘기거나 잘못된 출력을 낼 때 도구 호출이 막히는지 진행되는지는 원본이 말하지 않는다. 그래서 "훅으로 반드시 막힌다"고 안내하려면 이 경우를 직접 시험해 봐야 한다. Antigravity 훅 문서

편집자 해석: 이벤트 이름 가운데 SessionStart, PreToolUse, PostToolUse, Stop은 위 Claude Code 이벤트 이름과 같다. 다만 Antigravity 문서는 Claude Code를 언급하지 않고, 형식도 다르다. Antigravity는 hooks.json 최상위에 훅 이름을 두고 그 아래 이벤트를 적으며 결정은 stdout JSON의 decision으로 돌려준다. 핸들러 종류도 Antigravity는 command 하나, Claude Code 공식 훅 가이드는 다섯 가지다(Claude Code 훅 가이드). 그래서 이름이 같다고 같은 설정 파일이나 같은 스크립트를 두 도구에서 그대로 쓸 수 있다고 볼 근거는 없다고 볼 수 있다. Antigravity 훅 문서