차단되는 자리와 풀리지 않는 자리
이벤트 선택, 응답 방식, 퍼미션과의 우선순위
훅을 처음 도입한 팀이 가장 많이 겪는 사고는 훅은 돌았는데 아무것도 막히지 않는 것입니다. 원인은 거의 항상 이벤트 선택이거나 응답 방식의 혼용입니다. 여기에 하나 더, 훅은 제약을 죌 수는 있어도 퍼미션 규칙이 허용한 범위 너머로 풀어 주지는 못합니다. PreToolUse의 deny는 퍼미션 모드 검사보다 먼저 실행되어 bypassPermissions나 --dangerously-skip-permissions 환경에서도 도구를 막지만, allow는 deny 퍼미션 규칙을 우회하지 못합니다.
| 제어 수단 | 실제 효과 | 주의점 |
|---|---|---|
| 종료 코드 2 | 차단하고 stderr를 Claude에 피드백 | PostToolUse 계열은 차단 안 됨 |
| 종료 코드 0 + stdout JSON | allow·deny·ask·defer 정밀 결정 | 종료 코드 2면 JSON이 무시됨 |
| matcher | 이벤트 필드 이름으로 발동 범위 제한 | 대소문자를 구분함 |
| if 필드 | 퍼미션 규칙 구문으로 조건 판별 | 도구 이벤트에만 붙일 것 |
| permissionDecision: allow | 대화형 퍼미션 프롬프트만 건너뜀 | deny 규칙은 그대로 적용됨 |
- 이벤트 먼저 고르기차단이 목적이면 아직 동작이 일어나지 않은 시점의 이벤트에 겁니다.
- 응답 방식 통일종료 코드 2와 stdout JSON 중 하나만 쓰고 분기마다 섞지 않습니다.
- 발동 범위 좁히기matcher와 if로 필요한 호출에서만 훅 프로세스가 생성되게 합니다.
- 폭주 방지 배치stop_hook_active 조기 종료 분기와 큰 출력 처리 방식을 미리 정합니다.