Claude Code의 Hook 라이프사이클

이 요약은 AI가 원문을 분석해 생성했습니다. 정확한 내용은 원문 기준으로 확인하세요.

TL;DR

제공된 슬라이드는 Claude Code의 훅(Hook) 라이프사이클을 시각적으로 정리한 자료로, 세션 시작부터 사용자 프롬프트, 에이전틱 루프 내부의 툴 사용 전후 단계, 서브에이전트 오케스트레이션, 세션 정리까지 주요 이벤트를 노드와 화살표로 연결해 보여준다. 세부적으로는 PreToolUse에서 PermissionRequest로 권한을 확인하고 도구를 실행한 뒤 PostToolUse 또는 PostToolUseFailure로 결과를 받아 처리하는 흐름을 명시해 권한 검사·성공/실패 처리·재시도·로깅을 훅 단위로 분리할 수 있음을 보인다. 또한 ConfigChange·WorktreeCreate/Remove 같은 운영 이벤트와 TeammateIdle·PreCompact/PostCompact·SessionEnd 같은 정리 단계가 별도로 표시되어 장기 세션의 자원 관리와 정리 절차를 함께 다룬다. 이 구조를 채택하면 툴 호출 로직과 세션 관리를 훅으로 모듈화해 디버깅·감사·복구를 간결하게 만들 수 있으나, 다이어그램만으로는 각 훅의 구체적 입력/출력 스펙이나 예외 정책(재시도 횟수·타임아웃 등)이 제공되지 않아 실제 구현 시 추가 명세가 필요하다.

섹션별 상세

사용자 요청과 에이전트 내부 처리의 경계가 모호하면 상태 추적·오류 복구가 어려워진다는 문제의식에서 시작해, 슬라이드는 세션 단위 이벤트로 훅을 분류해 흐름을 명확히 한다. 입력으로는 SessionStart·UserPromptSubmit 같은 상위 이벤트가 들어오고, 에이전틱 루프 내부에서는 PreToolUse→PermissionRequest→(tool executes)→PostToolUse 형태로 처리되어 결과가 다시 에이전트 상태로 합류한다. 다이어그램의 노드·화살표는 각 훅의 호출 순서와 성공/실패 분기(예: PostToolUseFailure)를 직접 표시해 설계 근거를 제공한다. 이 구조를 따르면 툴 호출 전 권한검사·후처리·실패 대응을 훅 단위로 분리해 운영·디버깅 효율을 높일 수 있다.

Claude Code 슬라이드 — 훅(Hook) 라이프사이클을 단계별 노드로 시각화한 다이어그램 — Diagram다이어그램은 SessionStart→UserPromptSubmit로 시작해 agentic loop 내부의 PreToolUse, PermissionRequest, [tool executes], PostToolUse/PostToolUseFailure, SubagentStart/Stop, TaskCompleted 등 주요 훅을 순서도 형태로 배치한다. 좌측과 하단에는 비동기 알림(Notification), 설정 변경(ConfigChange), 작업트리 생성/제거 같은 운영·환경 이벤트와 Stop/StopFailure, TeammateIdle, PreCompact/PostCompact, SessionEnd 같은 정리 단계가 연결되어 있어 세션 관리와 도구 호출 흐름을 동시에 보여준다. 이 이미지는 훅 배치와 실패 분기, 서브에이전트 오케스트레이션 설계를 논의할 때 근거 자료로 바로 활용할 수 있다.

외부 툴 사용에서 권한과 실패 처리가 반복적인 난제로 남아있다는 맥락에서, 슬라이드는 권한 요청(PermissionRequest)과 툴 실행(success/failure) 사이에 명확한 입출력·후속 훅을 배치하는 방식을 제시한다. 프리툴 단계에서 입력을 검증하고 권한을 취득하면 도구가 실행되고, 실행 결과는 PostToolUse 또는 PostToolUseFailure 훅으로 수신되어 상태 갱신·재시도·로깅으로 이어진다. 도식은 이 흐름을 화살표와 별도 노드로 근거 있게 표현해 어떤 단계에서 어떤 처리가 필요할지 바로 알 수 있게 한다. 실무적으로는 성공·실패 훅을 모두 구현해 예측 가능한 오류 복구 루틴과 감사 로그를 확보하는 것이 권장된다.

세션 전반의 자원 관리와 장기 보존 문제를 다루는 맥락에서, 다이어그램은 설정(Setup), 알림(Notification), 구성 변경(ConfigChange), 작업트리 생성/제거(WorktreeCreate/WorktreeRemove) 같은 이벤트와 SessionEnd·PreCompact/PostCompact 같은 정리 단계의 역할을 구분해 보여준다. 입력 이벤트들이 트리거되면 해당 훅이 실행되어 작업공간 생성·파일 변경 감지·세션 압축 같은 후속 처리를 수행하고, 최종적으로 세션 종료로 이어진다. 해당 노드들이 좌우로 배치되어 있어 어느 이벤트가 운영·정리 단계와 연결되는지가 시각적으로 확인된다. 이 패턴을 적용하면 장시간 세션의 리소스 누수와 로그 산출물을 체계적으로 관리할 수 있다.

용어 해설

후크(이벤트 훅)(Hook): — 시스템이나 에이전트의 특정 이벤트(예: 세션 시작, 툴 사용 전/후)에 연결해 사용자 정의 로직을 실행하는 콜백 메커니즘이다. 입력 이벤트를 수신하면 등록된 훅이 실행되어 상태 변경·로깅·권한검사·에러 처리를 수행하고 결과를 다음 단계로 전달한다. 훅을 적절히 배치하면 에이전트의 도구 호출 흐름과 상태 관리를 분리해 유지보수성과 복원력을 높인다.
에이전틱 루프(Agentic Loop): — 사용자 프롬프트를 받아 계획을 생성하고 도구 호출·결과 검토를 순환하며 목표를 달성하는 에이전트의 반복 제어 루프다. 입력(프롬프트) → 계획(내부 의사결정) → 툴 호출(외부 액션) → 결과 피드백(검증/후처리) 순으로 작동한다. 루프의 각 단계에 훅을 걸면 권한 요청, 실패 처리, 서브에이전트 호출 등을 단계별로 분리해서 처리할 수 있다.
툴 사용(도구 호출)(Tool Use): — 에이전트가 외부 API·스크립트·플러그인 등 도구를 호출해 상태를 변경하거나 정보를 얻는 행위다. 호출 전(PreToolUse)에는 검증·권한 확인을 하고 호출 후(PostToolUse)에는 성공/실패 처리와 결과 통합을 수행한다. 툴 사용의 전후 단계에 훅을 두면 권한 정책 적용·재시도 로직·로그 집계가 용이해진다.
서브에이전트(Subagent): — 메인 에이전트의 일부 작업을 위임받아 독립적으로 실행되는 보조 에이전트다. 특정 작업(예: 코드 리팩터링, 검색 집계)을 담당하도록 시작·중지되며, 시작/중지 이벤트를 통해 메인 에이전트와 상태를 교환한다. 서브에이전트 관련 훅은 작업 단위 분리와 실패 격리에 유리하다.
세션 관리(Session Management): — 사용자 상호작용(세션) 전반의 상태·리소스·수명주기(시작·종료·압축 등)를 제어하는 기법이다. 세션 시작(SessionStart)과 종료(SessionEnd), 중간의 정리(PreCompact/PostCompact)·유휴 감지(TeammateIdle) 같은 이벤트에 훅을 걸어 리소스 해제·로그 정리·상태 보존을 자동화한다. 안정적인 운영을 위해 필수적인 시스템 레벨 관리 지점이다.