Python utility package for building Claude Code hooks

개요

claude-hook-utils는 Claude Code의 실행 시점에 사용자 정의 스크립트인 훅(hook)을 최소한의 코드 중복으로 구축할 수 있도록 돕는 Python 유틸리티 패키지입니다.

주요 내용

* Claude Code Hooks의 종류 및 기능:
* PreToolUse: 도구 실행 전에 파일 경로 검증, 내용 확인, 위험한 작업 차단 등 수행
* PostToolUse: 도구 실행 후에 결과 로깅, 후속 작업 트리거, 메트릭 수집 등 수행
* UserPromptSubmit: 사용자가 프롬프트를 제출할 때 프롬프트 검증, 컨텍스트 추가, 정책 강제 등 수행
* SessionStart: Claude Code 세션 시작 시 상태 초기화, 환경 변수 설정 등 수행
* claude-hook-utils 패키지의 필요성:
* 기존 훅 개발은 JSON 파싱, 입력 구조 검증, 응답 형식 지정, 오류 처리 등 반복적인 보일러플레이트 코드가 필요함.
* 이 패키지는 이러한 반복 작업을 자동화하여 개발자가 검증 로직에 집중할 수 있도록 지원.
* 디자인 철학:
* 단일 패턴: HookHandler를 확장하고 필요한 훅만 오버라이드.
* 타입 안전성: 입력은 Typed dataclass를 사용하며, 응답은 빌더 패턴을 사용.
* 명시적 제어: 입력 객체에 헬퍼 메서드를 제공하지만, 스킵/허용/거부 시점은 개발자가 결정.
* 다중 훅 지원: 하나의 Python 프로그램으로 여러 훅 유형 처리 가능.
* 경량 의존성: 핵심 패키지는 의존성이 최소화되어 있어, 필요한 AI SDK는 별도 설치.
* 설치: pip install claude-hook-utils
* 주요 구성 요소:
* HookHandler: 훅을 정의하는 기본 클래스. pre_tool_use, post_tool_use, user_prompt_submit, session_start 등의 메서드를 오버라이드하여 구현.
* PreToolUseInput / PostToolUseInput / UserPromptSubmitInput / SessionStartInput: 각 훅 유형에 대한 입력 데이터를 포함하는 dataclass. 파일 경로 매칭(file_path_matches), 내용 접근(content) 등의 헬퍼 메서드 제공.
* PreToolUseResponse / PostToolUseResponse / UserPromptSubmitResponse / SessionStartResponse: 훅 실행 결과를 반환하는 클래스. allow(), deny(), ask() 메서드를 통해 도구 실행 허용, 차단, 사용자 확인 요청 결정. with_updated_input() 메서드를 통해 도구 실행 전 입력 수정 가능.
* HookLogger: 네임스페이스별로 JSONL 형식의 로깅을 지원하여 디버깅을 용이하게 함.
* 환경 변수: Claude Code에서 제공하는 CLAUDE_PROJECT_DIR, CLAUDE_CODE_REMOTE와 패키지에서 사용하는 CLAUDE_HOOK_LOG_DIR, CLAUDE_HOOK_LOG_NAMESPACE 활용 가능.
* 새로운 훅 유형 확장: 입력 dataclass, 응답 클래스 생성, HookHandler에 핸들러 메서드 추가, _dispatch() 메서드에 디스패치 케이스 추가로 지원.
* 오류 처리: 유효하지 않은 JSON 입력, 알 수 없는 훅 유형, 핸들러 내 예외 발생 시 "fail open" 방식으로 Claude Code 실행이 중단되지 않도록 처리.
* 응답 형식: 패키지는 공식 hookSpecificOutput 형식에 맞춰 응답을 생성. permissionDecision (allow, deny, ask) 및 permissionDecisionReason 포함.

시사점

claude-hook-utils 패키지는 Claude Code에서 코드 생성 및 수정 프로세스의 신뢰성과 제어력을 높이는 데 기여하며, 개발자가 복잡한 검증 및 자동화 로직을 Python으로 효율적으로 구현할 수 있도록 지원합니다.