02-구조

02. 구조 — 이벤트와 등록

주요 이벤트(eesel/공식 종합)

이벤트	발화 시점	흔한 용도
UserPromptSubmit	사용자 입력 직후, 모델 호출 전	입력 검증, 자동 컨텍스트 주입
PreToolUse	도구 디스패치 직전	추가 권한 검사, 인자 검증, 위험 명령 차단
PostToolUse	도구 실행 직후	결과 변환, 로그, 자동 lint/test
Stop	end_turn 직후	마무리 작업(자동 커밋, 알림)
SubagentStop	서브에이전트 종료 시	결과 검증
Notification	사용자 알림 시점	데스크탑 알림, Slack 핑

등록 위치

~/.claude/settings.json(또는 프로젝트 .claude/settings.json)의 hooks 섹션. 각 hook은 매처(matcher) + 명령으로 구성된다.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {"type": "command", "command": ".claude/hooks/check-bash.sh"}
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {"type": "command", "command": ".claude/hooks/auto-format.sh"}
        ]
      }
    ],
    "Stop": [
      {"hooks": [{"type": "command", "command": ".claude/hooks/notify.sh"}]}
    ]
  }
}

핵심:

• 이벤트 + matcher (정규식)로 언제 발화할지 결정.
• hook 명령은 stdin으로 컨텍스트(JSON)를 받고 stdout/stderr로 결정·메시지를 돌려준다.
• exit code가 비-0이면 PreToolUse는 도구 호출을 차단할 수 있다.

hooks가 모델에게 말하는 법

PreToolUse hook이 stdout으로 메시지를 출력하면 그것이 system-reminder로 모델에게 들어간다. 즉 hooks는 모델의 다음 결정에 영향을 줄 수 있다 — 단, 결정적인 시점에서만.

이 글의 첫 turn에서 본 system-reminder(“Grift 거북이가 옆에 앉아 있다”) 같은 메시지가 정확히 그 메커니즘이다.