Claude Code hooks exit code 2: 차단 훅이 실제로 멈추는지 검증하는 법 | DAKER 커뮤니티
Claude Code hooks 보안 운영의 핵심은 exit code 2 차단 결과와 stdout JSON 형식을 함께 테스트하는 것입니다. Claude Code hook이란 도구 실행 전후에 팀 규칙을 검사해 승인, 질문, 차단을 결정하는 자동화 지점입니다. 2026년 7월 20일 KST 기준 최신 공식 changelog는 hook 차단 결과와 권한 판정 보강을 함께 다루므로, 팀 보안 훅은 작성보다 재현 테스트가 중요합니다.
문제 상황: 차단 훅을 만들었는데 정말 멈추는지 어떻게 알까?
팀이 위험 명령을 막기 위해 hook을 만들었다고 해도, 실제 실행 경로에서 멈추지 않으면 보안 정책은 문서로만 남습니다. 특히 표준 출력 JSON 형식, 종료 코드, 권한 프롬프트가 함께 얽히면 “차단 의도”와 “실제 차단”이 달라질 수 있습니다.
핵심 개념: exit code 2와 stdout JSON을 왜 같이 봐야 할까?
한 줄 요약: hook은 종료 코드만이 아니라 Claude Code가 읽는 출력 형식까지 맞아야 의도한 차단 흐름이 됩니다. 최신 changelog는 stdout JSON 스키마 검증에 실패한 경우 exit code 2가 문서대로 막지 못하던 문제를 고친 항목을 포함합니다. 그래서 팀은 hook 규칙을 만들 때 실패 형식까지 테스트해야 합니다.
단계별 사용법: 차단 훅 검증은 어떤 순서로 할까?
- 막아야 할 위험 명령을 실제 명령 대신 안전한 더미 명령으로 재현합니다.
- hook이 exit code 2를 반환하는 경우와 정상 JSON을 반환하는 경우를 따로 기록합니다.
- stdout JSON이 스키마에 맞지 않을 때 Claude Code가 어떻게 반응하는지 확인합니다.
- 권한 프롬프트가 필요한 명령과 즉시 차단해야 하는 명령을 분리합니다.
- 검증 결과를 팀 문서에 명령 예시, 기대 결과, 실제 결과로 저장합니다.
짧은 예시: 위험 명령 차단을 안전하게 재현하기
실제 파일 삭제 명령을 실행하지 말고, 같은 패턴을 가진 무해한 문자열이나 테스트용 임시 경로로 hook 반응을 봅니다. 기본 hook 설계는 위험 명령 차단 hooks 글을 기준으로 잡고, 권한 프롬프트 기준은 권한 하드닝 글과 함께 맞추면 좋습니다.
팀 적용 체크리스트: 훅을 배포하기 전에 무엇을 확인할까?
- exit code 2가 기대한 차단 메시지로 이어지는지 확인합니다.
- stdout JSON 필드 이름과 값 형식이 문서 기준에 맞는지 봅니다.
- Bash, PowerShell, 원격 컨테이너 명령처럼 해석기가 다른 경로를 분리합니다.
- 차단, 질문, 허용 세 가지 결과를 각각 테스트합니다.
- 실패 로그에는 토큰, 내부 경로, 고객 데이터를 남기지 않습니다.
공식 출처 기준으로 무엇을 조심해야 할까?
작성 기준일은 2026년 7월 20일 KST입니다. 기능 사실은 공식 changelog에서 비공개로 확인했고, 공개 본문에는 DAKER 내부 링크만 남겼습니다. 이 글은 보안 감사를 대체하지 않으며, 팀의 실제 hook 스키마와 권한 모드는 저장소별로 다시 확인해야 합니다.
자주 묻는 질문
exit code 2만 반환하면 무조건 안전한가요?
아닙니다. 출력 형식과 Claude Code의 hook 처리 결과까지 함께 확인해야 실제 차단을 말할 수 있습니다.
위험 명령을 실제로 실행해 봐야 하나요?
아닙니다. 테스트용 임시 경로나 무해한 더미 명령으로 같은 패턴을 재현하는 방식이 안전합니다.
PowerShell 팀도 같은 기준을 쓰면 되나요?
큰 원칙은 같지만 명령 해석과 출력 인코딩이 다를 수 있습니다. Windows 경로는 별도 케이스로 남기는 편이 좋습니다.
오늘 바로 점검할 항목은 무엇인가요?
팀이 믿고 있는 차단 훅 하나를 골라, 차단 결과와 stdout JSON 형식을 함께 재현해 보세요.
오늘은 가장 위험한 명령 패턴 하나부터 더미 테스트로 검증하고, 성공 기준을 팀 문서에 남겨 보세요.