Hook의 종류와 생명주기

Hooks는 Claude Code가 작업을 진행하는 동안 특정 생명주기 이벤트에 도달할 때마다 자동으로 실행되는 사용자 정의 명령입니다. 모델에게 "이렇게 해 주세요"라고 부탁하는 프롬프트와 달리, 훅은 정해진 시점에 반드시 실행됩니다. 이 결정론적 성격이 훅을 신뢰성 도구로 만드는 핵심입니다.

주요 Hook 이벤트

Claude Code는 한 작업 흐름 안에서 여러 지점에 훅을 끼워 넣을 수 있도록 이벤트를 정의합니다. 대표적인 이벤트는 다음과 같습니다.

• SessionStart / SessionEnd: 세션이 시작되거나 종료될 때 발생합니다. 작업 시작 시 컨텍스트를 주입하거나, 종료 시 로그를 정리하는 데 씁니다.
• UserPromptSubmit: 사용자가 프롬프트를 제출한 직후, 모델이 처리하기 전에 발생합니다. 입력을 검증하거나 추가 컨텍스트를 붙이고, 부적절한 요청을 차단할 수 있습니다.
• PreToolUse: 모델이 도구를 호출하기 직전에 발생합니다. 도구 호출을 검사·차단·수정할 수 있는 유일한 사전 개입 지점입니다.
• PostToolUse: 도구가 실행을 마친 직후에 발생합니다. 결과를 기록하거나 후처리(예: 포맷팅, 출력 필터링)하는 데 씁니다.
• Notification: Claude Code가 사용자에게 알림을 보낼 때 발생합니다. 외부 알림 시스템과 연동할 수 있습니다.
• Stop / SubagentStop: 메인 에이전트 또는 서브에이전트가 응답을 마치고 멈추려 할 때 발생합니다. 작업이 덜 끝났다고 판단되면 멈춤을 막고 계속 진행시킬 수 있습니다.
• PreCompact: 컨텍스트 압축(compaction)이 일어나기 직전에 발생합니다.

시험 포인트: 이벤트 이름과 발생 시점을 짝지어 기억하세요. 특히 "도구가 실행되기 전"(PreToolUse)과 "도구가 실행된 후"(PostToolUse)를 혼동하게 만드는 함정 보기가 자주 나옵니다. 위험한 명령을 막아야 하는 시나리오에서 PostToolUse를 고르면 오답입니다. 이미 실행된 뒤이기 때문입니다.

한 작업 흐름에서 이벤트가 발생하는 순서와, 각 이벤트가 사전(차단 가능)인지 사후(관찰 전용)인지를 그림으로 정리하면 다음과 같다.

생명주기와 개입 가능 시점의 차이

훅을 이해하는 가장 중요한 축은 "이 이벤트에서 흐름을 막을 수 있는가"입니다. 같은 종료 코드 2를 반환해도 이벤트에 따라 효과가 다릅니다.

• PreToolUse, UserPromptSubmit처럼 아직 행위가 일어나지 않은 이벤트에서 차단 신호를 보내면 해당 행위가 실제로 중단됩니다. 도구 호출이 취소되고, 프롬프트가 처리되지 않습니다.
• Stop, SubagentStop에서 차단 신호는 "멈추지 말고 계속하라"는 의미로 해석됩니다.
• PostToolUse는 도구가 이미 실행을 마친 뒤이므로, 출력이나 종료 코드가 행위 자체를 되돌리지는 못합니다. 결과를 관찰하고 모델에게 피드백을 줄 수는 있지만 실행을 취소할 수는 없습니다.

이 구분은 단순 암기가 아니라 의사결정의 근거입니다. "되돌릴 수 없는 작업을 모델이 협조하지 않아도 막아야 한다"면 답은 사전 이벤트(PreToolUse)이고, "실행 결과를 기록하거나 검증한다"면 사후 이벤트(PostToolUse)입니다.

구성 위치와 형태

훅은 settings.json의 hooks 키 아래에 이벤트별로 등록합니다. 각 이벤트는 matcher(어떤 도구·상황에 적용할지)와 실행할 훅 목록을 가집니다. 훅의 type은 외부 명령을 실행하는 command와, 이벤트 데이터를 HTTP로 전송하는 http가 있습니다.

// .claude/settings.json{  "hooks": {    "PreToolUse": [      {        "matcher": "Bash",        "hooks": [          {            "type": "command",            "command": "~/.claude/hooks/guard.sh"          }        ]      }    ]  }}

matcher는 특정 도구 이름(예: Bash, Edit)에 매칭됩니다. 비워 두면 해당 이벤트의 모든 호출에 적용됩니다. 명령형 훅은 stdin으로 이벤트 JSON을 받아 처리하므로, 도구 이름과 입력값을 검사해 세밀한 정책을 구현할 수 있습니다. 자세한 입출력 규약은 다음 절에서 다룹니다.

시험 포인트: 훅이 모델의 시스템 프롬프트가 아니라 Claude Code 설정(settings.json)에 정의된다는 점이 자주 출제됩니다. "모델에게 매번 잊지 말라고 지시한다"는 보기는 신뢰성 보장 측면에서 틀린 접근입니다. 결정론적 강제가 필요하면 훅을 쓰고, 모델의 자율적 판단이 필요하면 프롬프트나 도구 설명을 씁니다.

정리

• Hooks는 정해진 생명주기 이벤트마다 반드시 실행되는 결정론적 제어 장치로, 프롬프트의 비결정성을 보완한다.
• 핵심 이벤트는 SessionStart/End, UserPromptSubmit, PreToolUse, PostToolUse, Notification, Stop/SubagentStop, PreCompact다.
• 이벤트가 사전(차단 가능)인지 사후(관찰 전용)인지가 의사결정의 핵심이다. 되돌릴 수 없는 작업을 막으려면 PreToolUse가 정답이다.
• 훅은 settings.json의 hooks 키에 matcher와 함께 등록하며, command와 http 두 타입을 지원한다.