OMC - Hook System

시리즈: oh-my-claudecode 내부 구조부터 플러그인 개발까지

이 시리즈는 Claude Code 플러그인 시스템의 내부 동작을 단계별로 해부하고, 최종적으로 나만의 플러그인을 직접 개발하는 것까지 도달하는 과정이다.

편	내용	핵심
1편	Plugin Anatomy	plugin.json 하나로 시작하는 플러그인 뼈대
2편 (본문)	Hook System	이벤트 → stdin JSON → 스크립트 → stdout JSON
3편	Skill System	SKILL.md로 워크플로우를 정의하는 방법
4편	Agent System	Task tool로 위임되는 실제 작업 수행자
5편	MCP Tools Bridge	LSP, AST 등 커스텀 도구 서버
6편	State & Lifecycle	.omc/ 상태 관리와 모드 지속
7편	Parallel Orchestration	Ultrawork, Team, Autopilot, Ralph 패턴

---

• Claude Code Hook System은 Claude Code가 내부 이벤트 발생 시 외부 스크립트를 실행하여 행동을 가로채거나 조작할 수 있게 하는 공식 인터페이스
• Claude Code가 21가지 이벤트 + stdin/stdout JSON 계약을 정의하고, 플러그인이 그에 맞는 스크립트를 개발하여 등록하는 2-레이어 구조
• 핵심 계약: stdin JSON in → stdout JSON out

작성일: 2026-03-14 Claude Code 공식 문서: https://code.claude.com/docs/en/hooks (21개 이벤트) OMC 소스 버전: hooks/hooks.json 기준 (11개 이벤트, 18개 스크립트 등록)

해당 개념이 필요한 이유

• Claude Code는 기본 도구(Read, Write, Edit, Bash 등)만 제공하며, 사용자의 입력을 가로채거나 종료를 차단하는 기능이 없다
• 플러그인이 Claude Code의 동작에 개입하려면, Claude Code가 제공하는 공식 이벤트 훅 포인트를 통해야 한다
• OMC 같은 플러그인은 이 Hook 인터페이스를 활용하여 키워드 감지, 모드 지속, 에러 복구 등을 구현한다

AS-IS

sequenceDiagram
    autonumber
    participant U as User
    participant CC as Claude Code

    U->>CC: "ultrawork refactor the API"
    CC->>CC: 기본 도구로 처리
    CC-->>U: 응답 완료 (종료)
    Note over CC: 키워드 감지 불가, 종료 차단 불가, 모드 개념 없음

TO-BE

sequenceDiagram
    autonumber
    participant U as User
    participant CC as Claude Code
    box OMC
    participant HK as Hook Script
    end

    U->>CC: "ultrawork refactor the API"
    CC->>HK: UserPromptSubmit 이벤트 (stdin JSON)
    HK->>HK: "ultrawork" 키워드 감지
    HK-->>CC: stdout: { additionalContext: "SKILL 호출 지시" }
    CC->>CC: Skill 로드 → Agent 위임 → 병렬 실행
    CC->>HK: Stop 이벤트 (종료 시도)
    HK-->>CC: { continue: false, decision: "block" } (아직 작업 중)
    Note over CC: 작업 완료까지 종료하지 않음

Hook 시스템의 2-레이어 구조

graph TB
    subgraph Layer2["Layer 2: 플러그인"]
        Scripts["이벤트에 반응할 스크립트 개발"]
        Register["hooks.json에 이벤트별 스크립트 등록"]
        Logic["비즈니스 로직 구현"]
    end

    subgraph Layer1["Layer 1: Claude Code"]
        Events["21가지 Hook 이벤트 정의"]
        Contract["stdin/stdout JSON 계약"]
        HooksJson["hooks.json 로딩 & 스크립트 실행"]
    end

    Logic ~~~ Events

    Events --> HooksJson
    Contract --> HooksJson
    HooksJson -->|"command 실행, stdin 전달"| Scripts
    Scripts -->|"stdout JSON 반환"| HooksJson
    Register -.->|"등록"| HooksJson

Claude Code가 “21개의 콘센트(이벤트)“를 제공하고, 플러그인은 거기에 원하는 “가전제품(스크립트)“을 꽂는 구조. 콘센트 자체를 추가할 순 없지만, 꽂는 건 자유다.

통신 프로토콜 상세

Hook의 작동 흐름

sequenceDiagram
    autonumber
    participant CC as Claude Code
    participant HJ as hooks.json
    participant SC as Hook Script (.mjs)

    CC->>CC: 내부 이벤트 발생 (예: UserPromptSubmit)
    CC->>HJ: 해당 이벤트의 hook 목록 조회
    CC->>SC: command 실행, stdin으로 이벤트 JSON 전달
    SC->>SC: 처리 (키워드 감지, 상태 확인 등)
    SC-->>CC: stdout으로 응답 JSON 반환
    CC->>CC: 응답 해석하여 행동 결정

공통 stdin 입력 (모든 이벤트)

{
  "session_id": "abc123",
  "transcript_path": "/path/to/transcript.jsonl",
  "cwd": "/current/working/directory",
  "permission_mode": "default|plan|acceptEdits|dontAsk|bypassPermissions",
  "hook_event_name": "EventName",
  "agent_id": "optional-subagent-id",
  "agent_type": "optional-agent-name"
}

이벤트별로 tool_name, tool_input, user_prompt, reason 등 추가 필드가 포함된다.

공통 stdout 출력 (모든 Hook)

{
  "continue": true,
  "stopReason": "message",
  "suppressOutput": false,
  "systemMessage": "warning"
}

필드	기본값	설명
continue	true	false면 Claude가 처리 완전 중단. 모든 decision보다 우선
stopReason	없음	continue: false일 때 사용자에게 표시 (Claude에겐 안 보임)
suppressOutput	false	true면 verbose 모드 출력에서 숨김
systemMessage	없음	사용자에게 표시할 경고 메시지

이벤트별 hookSpecificOutput

// UserPromptSubmit, SessionStart, SubagentStart, PostToolUseFailure 등
{
  hookSpecificOutput: {
    hookEventName: "UserPromptSubmit",
    additionalContext: "Claude context에 주입할 텍스트"
  }
}
 
// PreToolUse — 도구 실행 허용/차단/수정
{
  hookSpecificOutput: {
    hookEventName: "PreToolUse",
    permissionDecision: "allow" | "deny" | "ask",
    permissionDecisionReason: "사유",
    updatedInput: { field: "수정된 값" },
    additionalContext: "Claude에게 추가 컨텍스트"
  }
}
 
// Stop, SubagentStop — 종료 차단
{
  continue: false,              // 핵심 필드: false면 종료 차단
  decision: "block",            // 보조 필드
  reason: "차단 사유"
}
// 종료 허용 시
{
  continue: true,
  suppressOutput: true
}
 
// PermissionRequest — 권한 자동 승인/거부
{
  hookSpecificOutput: {
    hookEventName: "PermissionRequest",
    decision: {
      behavior: "allow" | "deny",
      message: "deny 사유"
    }
  }
}

Exit Code 동작

Exit Code	동작
0	성공, stdout에서 JSON 파싱
2	블로킹 에러, stderr가 Claude에게 전달, JSON 무시
기타	비블로킹 에러, 실행 계속 진행

continue, additionalContext, hookEventName은 모두 공식 필드

이 필드들은 OMC가 자체 정의한 것이 아니라 Claude Code 공식 인터페이스의 일부이다. 공식 문서(https://code.claude.com/docs/en/hooks)에 모든 필드가 명시되어 있으며, OMC를 포함한 모든 플러그인이 이 계약에 맞춰 스크립트를 개발한다.

Claude Code 공식 Hook 이벤트 (21가지)

#	이벤트	발생 시점	OMC 사용
1	SessionStart	세션 시작/재개 시	✅
2	UserPromptSubmit	사용자 프롬프트 제출 시	✅
3	PreToolUse	도구 실행 전	✅
4	PermissionRequest	권한 다이얼로그 표시 시	✅
5	PostToolUse	도구 성공 후	✅
6	PostToolUseFailure	도구 실패 후	✅
7	Notification	Claude Code 알림 발송 시
8	SubagentStart	서브에이전트 생성 시	✅
9	SubagentStop	서브에이전트 종료 시	✅
10	Stop	Claude 응답 종료 시	✅
11	TeammateIdle	팀 에이전트가 idle 상태 전환 시
12	TaskCompleted	태스크 완료 표시 시
13	InstructionsLoaded	CLAUDE.md/rules 로드 시
14	ConfigChange	설정 파일 변경 시
15	WorktreeCreate	worktree 생성 시
16	WorktreeRemove	worktree 제거 시
17	PreCompact	컨텍스트 압축 전	✅
18	PostCompact	컨텍스트 압축 후
19	Elicitation	MCP 서버가 사용자 입력 요청 시
20	ElicitationResult	MCP elicitation 응답 후
21	SessionEnd	세션 종료 시	✅

OMC는 이 중 11개 이벤트에 커스텀 스크립트를 등록하여 사용한다.

hooks.json 구조

{
  "hooks": {
    "이벤트이름": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "node \"$CLAUDE_PLUGIN_ROOT\"/scripts/run.cjs ...",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

• 한 이벤트에 여러 matcher 등록 가능 (배열)
• 한 matcher에 여러 hook 등록 가능 (순차 실행)
• matcher: "*"는 모든 경우에 실행, "Bash"는 Bash 도구에만 실행
• timeout 초과 시 hook이 무시되고 Claude Code가 정상 진행

OMC hooks.json 이벤트별 등록 현황 (18개 스크립트)

#	이벤트	matcher	스크립트	timeout	역할
1	UserPromptSubmit	*	keyword-detector.mjs	5s	매직 키워드 감지 → 스킬 주입
		*	skill-injector.mjs	3s	학습된 스킬 매칭 → context 주입
2	SessionStart	*	session-start.mjs	5s	초기 설정, HUD 초기화
		*	project-memory-session.mjs	5s	프로젝트 메모리 로드
		init	setup-init.mjs	30s	최초 초기화 (디렉토리 생성 등)
		maintenance	setup-maintenance.mjs	60s	유지보수 (상태 파일 정리 등)
3	PreToolUse	*	pre-tool-enforcer.mjs	3s	팀 라우팅, 컨텍스트 소진 감지
4	PermissionRequest	Bash	permission-handler.mjs	5s	Bash 명령만 자동 승인 판단
5	PostToolUse	*	post-tool-verifier.mjs	3s	에러 복구, 컨텍스트 주입
		*	project-memory-posttool.mjs	3s	도구 결과에서 프로젝트 메모리 학습
6	PostToolUseFailure	*	post-tool-use-failure.mjs	3s	실패 에러 복구 가이드
7	SubagentStart	*	subagent-tracker.mjs start	3s	서브에이전트 시작 추적
8	SubagentStop	*	subagent-tracker.mjs stop	5s	서브에이전트 종료 추적
		*	verify-deliverables.mjs	5s	서브에이전트 결과물 검증
9	PreCompact	*	pre-compact.mjs	10s	압축 전 핵심 정보 보존
		*	project-memory-precompact.mjs	5s	프로젝트 메모리 보존
10	Stop	*	context-guard-stop.mjs	5s	컨텍스트 가드
		*	persistent-mode.cjs	10s	모드 지속 → 종료 차단
		*	code-simplifier.mjs	5s	코드 간소화 체크
11	SessionEnd	*	session-end.mjs	10s	메트릭 기록, 상태 정리

hooks.json에서 읽는 설계 패턴

순차 실행 — 같은 matcher 안의 hooks 배열

같은 matcher의 hooks 배열은 순차 실행된다.

UserPromptSubmit: keyword-detector.mjs (5s) → skill-injector.mjs (3s)

키워드를 먼저 감지한 뒤, 학습된 스킬을 매칭하는 순서.

matcher로 조건 분기 — SessionStart

SessionStart만 유일하게 3개의 matcher를 사용한다:

• * — 항상 실행 (세션 시작, 메모리 로드)
• init — 초기화 시에만 (timeout 30s)
• maintenance — 유지보수 시에만 (timeout 60s로 가장 길다)

특정 도구만 감시 — PermissionRequest

다른 이벤트는 모두 matcher: "*"인데, PermissionRequest만 matcher: "Bash". Bash 명령 실행 권한만 자동 판단하고, Read/Edit 등 다른 도구는 관여하지 않는다.

Stop 이벤트가 가장 복잡 — 3개 스크립트 순차 실행

context-guard-stop.mjs → persistent-mode.cjs → code-simplifier.mjs

종료 시점에 컨텍스트 상태 확인 → 활성 모드면 종료 차단 → 코드 품질 체크까지 3단계.

실행 체인: scripts/run.cjs

graph LR
    HJ["hooks.json command"] -->|"node run.cjs keyword-detector.mjs"| R["run.cjs"]
    R -->|"process.execPath로 스폰"| KD["keyword-detector.mjs"]
    R -->|"심볼릭 링크 해결, 캐시 경로 해결"| KD
    KD -->|"stdio: inherit, stdin/stdout 전달"| R

run.cjs가 필요한 이유:

• 크로스 플랫폼 지원 (Windows에서 sh 대신 Node.js 사용)
• 플러그인 캐시 경로 해결 (stale $CLAUDE_PLUGIN_ROOT 대응)
• Node 바이너리 경로 자동 탐지

Hook 스크립트 패턴

모든 hook 스크립트는 같은 패턴을 따른다:

// scripts/my-hook.mjs
import { readStdin } from './lib/stdin.mjs';
 
async function main() {
  // 1. stdin에서 JSON 읽기
  const input = await readStdin();
  const data = JSON.parse(input);
 
  // 2. 처리 (이벤트 데이터 분석, 판단)
  const prompt = data.prompt || '';
 
  // 3. stdout으로 JSON 응답
  if (/* 조건 충족 */) {
    console.log(JSON.stringify({
      continue: true,
      hookSpecificOutput: {
        hookEventName: 'UserPromptSubmit',
        additionalContext: '주입할 텍스트'
      }
    }));
  } else {
    console.log(JSON.stringify({ continue: true }));
  }
}
 
main();

참고 문서

• Claude Code Hooks 공식 문서
• OMC hooks.json
• OMC keyword-detector.mjs