Hooks 시스템

Hooks란?

Hooks는 Claude Code의 생명주기 내 특정 지점에서 자동으로 실행되는 사용자 정의 셸 명령, HTTP 엔드포인트, 또는 LLM 프롬프트입니다. 예시와 함께하는 빠른 시작 가이드를 보려면 Automate actions with hooks를 참조하세요. 이 레퍼런스를 사용하여 이벤트 스키마, 설정 옵션, JSON 입력/출력 형식, 비동기 Hook, HTTP Hook, MCP 도구 Hook과 같은 고급 기능을 확인할 수 있습니다. Hooks를 처음 설정하는 경우, 가이드부터 시작하는 것이 좋습니다.

Hooks의 핵심 특징

• 결정론적: LLM이 아닌 규칙 기반으로 동작하여 예측 가능
• 자동 실행: 이벤트 발생 시 사용자 개입 없이 실행
• 확장 가능: 셸 명령, HTTP 엔드포인트, LLM 프롬프트, 서브에이전트 등 다양한 핸들러 지원
• 안전한 제어: 도구 실행 차단, 입력 검증, 자동 포맷팅 등 안전장치 구축

Hook 생명 주기

Hooks는 Claude Code 세션의 특정 지점에서 실행됩니다. 이벤트가 발생하고 매처가 일치하면, Claude Code는 Hook 핸들러에 이벤트에 대한 JSON 컨텍스트를 전달합니다.

• Command 핸들러: 입력이 stdin으로 도착
• HTTP 핸들러: 입력이 POST 요청 본문으로 도착

핸들러는 입력을 검사하고, 조치를 취하며, 선택적으로 의사결정(decision)을 반환할 수 있습니다.

이벤트는 3가지 주기로 발생합니다:

• 세션당 1회: SessionStart, SessionEnd
• 턴당 1회: UserPromptSubmit, Stop, StopFailure
• 도구 호출 루프 내: PreToolUse, PostToolUse

아래 표는 각 이벤트가 언제 발생하는지 요약합니다. Hook 이벤트 섹션은 각 이벤트에 대한 전체 입력 스키마 및 의사결정 제어 옵션을 문서화합니다.

Hook 동작 방식 (How a hook resolves)

Hook이 어떻게 동작하는지 이해하기 위해, 위험한 셸 명령을 차단하는 PreToolUse Hook을 예시로 살펴보겠습니다. 매처는 Bash 도구 호출로 좁혀지고, if 조건은 rm *와 일치하는 Bash 서브커맨드로 더 좁혀지므로, block-rm.sh는 두 필터가 모두 일치할 때만 실행됩니다:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(rm *)",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh",
            "args": []
          }
        ]
      }
    ]
  }
}

스크립트는 stdin에서 JSON 입력을 읽고, 명령어를 추출한 후 rm -rf를 포함하면 permissionDecision을 "deny"로 반환합니다:

#!/bin/bash
# .claude/hooks/block-rm.sh
COMMAND=$(jq -r '.tool_input.command')
 
if echo "$COMMAND" | grep -q 'rm -rf' ; then
  jq -n '{
    hookSpecificOutput: {
      hookEventName: "PreToolUse",
      permissionDecision: "deny",
      permissionDecisionReason: "Destructive command blocked by hook"
    }
  }'
else
  exit 0 # no decision; normal permission flow applies
fi

이제 Claude Code가 Bash "rm -rf /tmp/build"를 실행하려고 한다고 가정해 봅시다. 다음 상황이 발생합니다:

1. 이벤트 발생: PreToolUse 이벤트가 발생합니다. Claude Code는 도구 입력을 JSON으로 stdin에 Hook으로 전달합니다:

   {
     "tool_name": "Bash",
     "tool_input": {
       "command": "rm -rf /tmp/build"
     },
     "session_id": "abc123",
     "cwd": "/home/user/project",
     "hook_event_name": "PreToolUse"
   }

2. 매처 검증: 매처 "Bash"가 도구 이름과 일치하므로 이 Hook 그룹이 활성화됩니다. 매처를 생략하거나 "*"를 사용하면 이벤트 발생 시마다 그룹이 활성화됩니다.
3. if 조건 검증: if 조건 "Bash(rm *)"가 일치합니다. rm -rf /tmp/build는 rm * 패턴과 일치하는 서브커맨드이기 때문입니다. 따라서 이 핸들러가 실행됩니다. 만약 명령어가 npm test였다면 if 검사는 실패하고 block-rm.sh는 실행되지 않아 프로세스 생성 오버헤드를 피할 수 있습니다. if 필드는 선택 사항이며, 없으면 일치하는 그룹의 모든 핸들러가 실행됩니다.
4. Hook 핸들러 실행: 스크립트가 전체 명령어를 검사하고 rm -rf를 발견하면 stdout으로 결정을 출력합니다.

   {
     "hookSpecificOutput": {
       "hookEventName": "PreToolUse",
       "permissionDecision": "deny",
       "permissionDecisionReason": "Destructive command blocked by hook"
     }
   }

   만약 명령어가 rm file.txt와 같이 더 안전한 rm 변형이었다면, 스크립트는 대신 exit 0을 실행했을 것입니다. 출력이 없는 종료 코드 0은 Hook이 보고할 결정이 없음을 의미하므로, 도구 호출은 정상적인 권한 흐름을 통해 계속됩니다. Hook은 호출을 거부할 수 있지만, 침묵한다고 해서 승인하는 것은 아닙니다.
5. Claude Code가 결과에 따라 조치: Claude Code는 JSON 결정을 읽고, 도구 호출을 차단하며, Claude에게 거부 이유를 표시합니다.

Hook 이벤트

Claude Code는 다음과 같은 Hook 이벤트를 지원합니다:

5가지 핸들러 타입

각 Hook 이벤트에는 5가지 타입의 핸들러를 연결할 수 있습니다.

Command 핸들러

셸 명령을 실행하는 가장 일반적인 핸들러입니다. JSON을 stdin으로 받고, stdout으로 JSON을 출력합니다.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write $CLAUDE_FILE_PATH"
          }
        ]
      }
    ]
  }
}

HTTP 핸들러

외부 HTTP 엔드포인트로 요청을 보냅니다. 원격 서버나 웹훅 서비스와 통합할 때 사용합니다.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "http",
            "url": "https://example.com/hooks/post-tool",
            "method": "POST"
          }
        ]
      }
    ]
  }
}

MCP Tool 핸들러

MCP (Model Context Protocol) 서버의 도구를 호출합니다. 외부 도구와 통합하여 Hook에서 복잡한 작업을 수행할 때 사용합니다.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "mcp_tool",
            "tool_name": "external_service",
            "arguments": {
              "action": "validate"
            }
          }
        ]
      }
    ]
  }
}

Prompt 핸들러

단일 LLM 호출을 수행합니다. yes/no 판단이나 간단한 분석에 적합합니다.

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "방금 완료한 작업이 원래 요청을 충분히 만족하는지 검토하세요. 누락된 부분이 있다면 'no'를, 완료되었다면 'yes'를 응답하세요."
          }
        ]
      }
    ]
  }
}

Prompt 핸들러가 "no"를 반환하면 Claude가 추가 작업을 수행합니다.

Agent 핸들러

서브에이전트를 실행하여 복잡한 검증을 수행합니다. 최대 50턴, 60초 타임아웃이 적용됩니다.

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "이전 작업의 결과를 검토하고, 모든 요구사항이 충족되었는지 확인하세요. 필요한 경우 추가 작업을 수행하세요."
          }
        ]
      }
    ]
  }
}