Hooks: Event-Driven Automation

훅 이벤트는 6가지 카테고리로 나뉜다:

1. 세션 생명주기 (비블로킹)

• SessionStart — 세션 시작 시
• SessionEnd — 세션 종료 시
• Setup — --init-only로 한 번만 실행

2. 턴 이벤트

• UserPromptSubmit — 사용자 프롬프트 제출 시 (블로킹, exit 2로 차단 가능)
• Stop — Claude가 턴을 마칠 때 (exit 2로 계속 작업 강제)
• StopFailure — 비블로킹 관찰용

3. 도구 실행 (에이전트 루프 핵심)

• PreToolUse — 모든 도구 호출 전 (블로킹, exit 2로 차단)
• PostToolUse — 도구 성공 후 (응답 수정 가능)
• PermissionRequest — 권한 다이얼로그 전 (자동 승인/거부)
• PostToolBatch — 병렬 도구 배치 완료 후 (블로킹)

4. 에이전트/팀 이벤트

• SubagentStart / SubagentStop
• TeammateIdle — 팀원을 계속 작업하게 유지 가능

5. 파일/설정 이벤트

• FileChanged — 디스크의 파일 변경 감지 (비동기)
• InstructionsLoaded — CLAUDE.md 로드 시
• ConfigChange — settings.json 변경 시 (블로킹, 거부 가능)

6. 태스크/컨텍스트 이벤트

• TaskCreated / TaskCompleted
• PreCompact / PostCompact — 컨텍스트 압축 전후

각 훅 이벤트에 어떤 종류의 핸들러를 붙일지 선택할 수 있다:

1. command — 가장 일반적. 쉘 명령을 실행한다.

{ "type": "command", "command": "prettier --write ${CLAUDE_TOOL_INPUT_FILE_PATH}" }

2. http — HTTP POST로 외부 서비스에 이벤트를 전송한다.

{ "type": "http", "url": "http://localhost:8080/validate" }

3. mcp_tool — 연결된 MCP 서버의 도구를 호출한다.

{ "type": "mcp_tool", "server": "my_server", "tool": "validate_code" }

4. prompt — 단일 턴 LLM 평가. 빠른 모델로 조건을 검사한다.

{ "type": "prompt", "prompt": "이 쉘 명령이 안전한가? $ARGUMENTS" }

5. agent — Read/Grep/Glob 도구를 가진 서브에이전트를 스폰한다 (실험적).

{ "type": "agent", "prompt": "이 작업이 허용된 범위 내인지 확인하라: $ARGUMENTS" }

prompt와 agent 핸들러는 PreToolUse, PostToolUse, PermissionRequest에서만 사용 가능하다.

훅의 동작은 종료 코드에 의해 결정된다:

exit code 2의 이중적 의미가 중요하다. PreToolUse에서는 '이 도구 호출을 막아라'이고, Stop에서는 '아직 작업이 끝나지 않았다 계속해라'이다. 같은 코드가 컨텍스트에 따라 반대 효과를 낸다.

JSON 출력으로 Claude에 피드백을 줄 수 있다:

{
  "systemMessage": "사용자에게 표시할 메시지",
  "continue": false,
  "stopReason": "차단 이유",
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "additionalContext": "Claude의 컨텍스트에 주입될 텍스트"
  }
}

레시피 1: 파일 저장 시 자동 포맷 (PostToolUse)

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{
        "type": "command",
        "command": "jq -r '.tool_input.file_path // empty' | { read -r f; [ -n \"f\" ] && prettier --write \"f\"; } 2>/dev/null || true"
      }]
    }]
  }
}

레시피 2: rm -rf 차단 (PreToolUse)

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "if": "Bash(rm -rf *)",
      "hooks": [{
        "type": "command",
        "command": "echo '{\"continue\": false, \"stopReason\": \"rm -rf는 허용되지 않습니다\"}'"
      }]
    }]
  }
}

레시피 3: 세션 종료 시 테스트 실행 (Stop)

{
  "hooks": {
    "Stop": [{
      "matcher": "*",
      "hooks": [{
        "type": "command",
        "command": "npm test --silent && echo '{\"systemMessage\": \"테스트 통과 완료\"}' || echo '{\"continue\": false, \"stopReason\": \"테스트 실패: 수정 후 완료 선언하세요\"}'"
      }]
    }]
  }
}

레시피 4: .env 파일 읽기 차단 (PreToolUse)

{
  "permissions": {
    "deny": ["Read(.env)", "Read(.env.local)", "Read(.env.production)"]
  }
}