Ch5. Hooks 시스템

Hooks는 Claude Code의 이벤트 시점에 자동으로 실행되는 명령입니다. 도구 실행 차단, 포매팅, 로깅 등 자동화를 구성할 수 있습니다.

이벤트 종류

주요 이벤트(요약):

• SessionStart, SessionEnd
• UserPromptSubmit
• PreToolUse, PostToolUse, PostToolUseFailure
• Notification
• Stop, SubagentStop
• StopFailure — API 에러로 턴이 종료될 때 발생 (v2.1.78)
• TeammateIdle, TaskCompleted (멀티 에이전트 워크플로우)
• PreCompact — compaction 직전에 발생. 최신 버전에서는 이 시점에서 compaction 자체를 차단할 수 있습니다. (v2.1.105)
• PostCompact — compaction 완료 후 발생, 로깅/알림에 활용 (v2.1.76)
• Elicitation — MCP 서버가 사용자에게 구조화된 입력을 요청할 때 발생 (v2.1.76)
• ElicitationResult — 사용자가 elicitation에 응답한 결과 (v2.1.76)
• InstructionsLoaded — CLAUDE.md/rules 파일 로드 시 발생 (v2.1.69)
• ConfigChange — 세션 중 설정 파일 변경 시 발생, 기업 보안 감사에 활용 (v2.1.49)
• WorktreeCreate / WorktreeRemove — worktree 생성/제거 시 커스텀 VCS 설정 (v2.1.50)
• CwdChanged — 작업 디렉토리 변경 시 발생 (v2.1.83)
• FileChanged — 파일 변경 감지 시 발생 (v2.1.83)
• TaskCreated — 태스크 생성 시 발생, 팀 워크플로우 자동화에 활용 (v2.1.84)
• PermissionDenied — Auto 모드 분류기가 도구 실행을 거부했을 때 발생. {retry: true} 응답으로 재시도 가능 (v2.1.88)

Hook 타입

command 타입과 HTTP hooks 타입을 지원합니다.

command 타입

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "prettier --write ."
          }
        ]
      }
    ]
  }
}

HTTP hooks (v2.1.63)

셸 명령 대신 URL에 JSON POST를 보내고 JSON 응답을 수신하는 방식입니다. 외부 웹훅 서비스나 내부 API와 통합할 때 유용합니다.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "http",
            "url": "https://hooks.example.com/format"
          }
        ]
      }
    ]
  }
}

PreToolUse 차단/허용

PreToolUse 훅은 도구 실행을 차단할 수 있습니다.

• 종료 코드 0: 정상 진행
• 종료 코드 2: 도구 실행 차단 (stderr가 Claude에 전달)

설정 위치

조건부 if 필드 (v2.1.85)

훅에 if 필드를 추가하면 퍼미션 규칙 구문으로 실행 조건을 세밀하게 제어할 수 있습니다. matcher보다 정밀한 필터링이 가능합니다.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(git *)",
            "command": "echo 'git 명령 감지' >> /tmp/git-audit.log"
          }
        ]
      }
    ]
  }
}

if 필드는 Bash(git *), Write(src/**) 등 퍼미션 규칙과 동일한 구문을 사용합니다.

matcher 패턴

matcher는 도구 이름 정규식입니다. PreToolUse와 PostToolUse에서만 적용됩니다.

훅 입력 필드

훅이 실행될 때 전달되는 입력 JSON에는 다음 필드가 포함됩니다.

• agent_id / agent_type — 훅을 트리거한 에이전트의 ID와 타입 (v2.1.69)
• worktree — worktree 관련 정보 (name, path, branch, original repo) (v2.1.69)
• last_assistant_message — Stop/SubagentStop 훅 입력에 포함되는 마지막 어시스턴트 메시지 (v2.1.47)

훅 응답으로 에이전트 제어

TeammateIdle/TaskCompleted 훅에서 {"continue": false, "stopReason": "..."} 형태의 JSON을 반환하면 팀메이트 에이전트를 중단시킬 수 있습니다. (v2.1.69)

환경 변수

Hooks 실행 시 다음 변수가 유용합니다.

• CLAUDE_PROJECT_DIR — 프로젝트 루트 경로
• CLAUDE_CODE_REMOTE — 원격 실행 여부
• CLAUDE_ENV_FILE — SessionStart에서 환경 변수 지속 저장 경로
• CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS — SessionEnd hooks의 타임아웃(밀리초) 설정 (v2.1.74)
• CLAUDE_PLUGIN_DATA — 플러그인 영구 상태 저장 경로 (v2.1.78)

실전 레시피

자동 Prettier 포매팅

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "prettier --write . 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

Bash 실행 차단 (예시)

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Bash commands blocked by policy' >&2 && exit 2"
          }
        ]
      }
    ]
  }
}

관리 설정과 훅 비활성화

• disableAllHooks 설정은 managed settings 계층을 존중합니다 — 비관리(unmanaged) 설정에서는 관리(managed) 훅을 비활성화할 수 없습니다. (v2.1.49)
• pluginTrustMessage로 조직별 플러그인 신뢰 경고 메시지를 커스터마이즈할 수 있습니다. (v2.1.69)

PreToolUse 고급 응답 (v2.1.85)

PreToolUse 훅이 updatedInput을 JSON 응답으로 반환하면 AskUserQuestion 도구의 입력을 자동으로 대체할 수 있습니다. 사용자 입력을 자동화하거나 기본값을 주입하는 패턴에 유용합니다.

허용/차단 대신 defer 결정을 반환하면 헤드리스 세션은 해당 도구 호출 지점에서 일시 정지되고, claude -p --resume으로 재개할 때 훅이 다시 평가됩니다. 승인 판단을 사람 검토 뒤로 미루는 운영 흐름에 유용합니다. (v2.1.89)

PreCompact 차단 (v2.1.105)

PreCompact 훅은 이제 compaction을 명시적으로 block할 수 있습니다.

• 프로세스 종료 코드 2
• 또는 JSON 응답 {"decision":"block"}

긴 작업의 중간 상태가 아직 정리되지 않았거나, 먼저 메모리 파일/감사 로그를 남겨야 하는 운영 규칙이 있다면 PreCompact를 마지막 안전장치로 둘 수 있습니다.

보안 참고

• PreToolUse 훅이 "allow"를 반환해도 deny 퍼미션 규칙이 정상적으로 적용됩니다. 이전에는 "allow" 반환이 deny 규칙을 우회하는 버그가 있었으나 수정되었습니다. (v2.1.77)
• PreToolUse/PostToolUse 훅에 전달되는 file_path가 절대 경로로 정규화됩니다. 이전에는 상대 경로가 전달되는 경우가 있었습니다. (v2.1.88)
• 훅 출력이 50K자를 넘으면 디스크에 저장되고, 컨텍스트에는 미리보기와 파일 경로만 주입됩니다. 대용량 감사 로그/검사 결과를 훅으로 다룰 때 세션 비대화를 줄입니다. (v2.1.89)

참고 문서

• Hooks 개요: https://docs.claude.com/ko/docs/claude-code/hooks (한국어)
• Hooks 레퍼런스(이벤트/스키마): https://docs.claude.com/ko/docs/claude-code/hooks#hooks-reference (한국어)
• 설정 파일 위치: https://code.claude.com/docs/ko/settings (한국어)