Concept (개념)aiverifiedFri May 01

Claude Code Hooks 6 이벤트 시스템 (UserPromptSubmit / PreToolUse / PostToolUse / Stop / SessionStart / Notification)

별칭: Hooks 6 Events · Claude Code Hooks 시스템 · 6 이벤트 훅

#hooks#claude-code#harness#settings-json#generalized#hrn

요약

entity/claude-code 의 결정론적 가드레일 1급 메커니즘 — settings.json 의 6 이벤트 Hook 시스템. 프롬프트 입력·도구 호출 전·도구 호출 후·턴 종료·세션 시작·알림 6 시점에서 외부 스크립트 호출 → 통과·차단·수정 결정. 본 강의 03 HRN 의 term/stop-hook 의 상위 개념.

상세

6 이벤트 표

이벤트	발화 시점	입력	용도
UserPromptSubmit	사용자 입력 직후	사용자 프롬프트	입력 검증 — 금지 패턴·정책 위반
PreToolUse	도구 호출 직전	도구 이름 + 파라미터	파라미터 검증 — API 시그니처·PII·권한
PostToolUse	도구 호출 직후	도구 응답	응답 후처리 — PII 스크러빙·로깅
Stop	턴 종료 시	전체 세션	감사 로깅 — request_id, masked_payload, response_hash
SessionStart	세션 시작 시	환경 정보	컨텍스트 주입 — CLAUDE.md, 환경 변수
Notification	시스템 알림 시	알림 메시지	외부 통지 — 슬랙/이메일/HITL 트리거

차단 메커니즘

// 통과
process.exit(0);

// 차단
console.error(JSON.stringify({
  decision: "block",
  reason: "구체적 사유"
}));
process.exit(2);

settings.json 매처 시스템

{
  "hooks": {
    "PreToolUse": [
      { "matcher": "Write|Edit",
        "hooks": [{ "type": "command", "command": "node .claude/hooks/api-validator.js" }] },
      { "matcher": "Bash|WebFetch",
        "hooks": [{ "type": "command", "command": "node .claude/hooks/pii-masker.js" }] }
    ],
    "Stop": [{
      "matcher": ".*",
      "hooks": [{ "type": "command", "command": "node .claude/hooks/audit-logger.js" }]
    }]
  }
}

matcher = 정규식. 어떤 도구에 대해 hook 을 발동할지 결정.
command = 외부 실행 파일. exit code 로 통과 / 차단 신호.

concept/multi-layer-guardrail 와의 매핑

이벤트	가드레일 층
UserPromptSubmit	2 (조직 가치) + 3 (팀 컨벤션)
PreToolUse	1 (시스템 진실) + 4 (PII)
PostToolUse	4 (응답 PII 스크러빙)
Stop	감사
SessionStart	컨텍스트 주입
Notification	HITL

다른 도구의 등가물

도구	등가 메커니즘
Cursor	Run on Stop / Pre-execution scripts
GitHub Copilot	Pre-commit hooks + custom instructions
Generic	Git hooks + CI pipeline

방법론

강의 활용 (03 HRN lesson/hrn-verification-loop 심화):

6 이벤트 표 (3분): 시점 + 입력 + 용도.
settings.json 코드 시연 (2분): 실제 매처 매핑.
차단 메커니즘 (1분): exit code 2 + JSON.
가드레일 매핑 (1분): concept/multi-layer-guardrail 의 4층이 6이벤트로 어떻게 분배되는지.

주의사항

이벤트 종류는 시점에 따라 변동: Claude Code 버전 업그레이드 시 이벤트 추가·이름 변경 가능. 강의 시점 기준 확인.
외부 스크립트 의존성: hooks 가 외부 실행 파일 을 호출 → Node.js / Python 등 환경 필요.
속도 비용: 매 hook 마다 프로세스 spawn → 시간 비용. 가벼운 검증 권장.
무한 루프 방지: hook 이 도구 호출을 트리거하면 재귀 발생 가능 — 안전장치 필요.
단일 vs 체인: 한 매처에 여러 hook 등록 가능 — 체인 실행. 모두 통과해야 통과.