1줄 정의

에이전트의 특정 이벤트 (도구 실행 전후, 세션 종료 시 등) 에 자동 실행되는 처리. Claude Code 등이 제공.

전체 시스템에서 맡는 역할

Claude Code 같은 에이전트형 도구는 거동에 끼어들고 싶은 장면이 있다. 파일 편집 전 포매팅, 명령 실행 전 확인, 세션 종료 시 로그 저장 등.

이걸 설정 파일 (settings.json 등) 에 등록한 shell 명령으로 자동 실행시키는 구조가 훅.

전형 이벤트:

• PreToolUse: 도구 실행 직전 (검증, 거부 판단)
• PostToolUse: 도구 실행 직후 (포매팅, 테스트)
• SessionEnd: 세션 종료 시 (로그 수집, 알림)
• UserPromptSubmit: 사용자 입력 시 (전처리, 검열)

훅은 harness 의 일부로 기능한다. 에이전트 본체 프롬프트를 바꾸지 않고 운영 규칙을 꽂을 수 있어서 개조 없이 제어하는 게 요점.

흔한 오해

• 오해 1: 훅은 단순한 이벤트 리스너, 라고 여겨지기 쉽다.

– 실제로 훅의 종료 코드나 출력으로 에이전트 거동을 변경할 수 있는 것도 있다 (예: PreToolUse 가 2 를 돌려주면 도구 실행이 거부됨). 수동적이 아니라 능동적 제어점.

이 용어가 중요한 이유

훅을 알면 에이전트를 개조하지 않고 조직 규칙을 강제할 수 있다.

• 본 운영 환경 조작 전 반드시 확인
• 기밀 파일 편집 시 로그
• 테스트 실패 시 자동 재시도

다음에 읽을 용어 3개

• Claude Code — 훅을 제공하는 대표 구현.
• harness — 훅이 들어가는 상위층.
• permissions — 훅으로 권한 검증 구현 가능.