참고) Claude Hook Matcher

Claude Hook Matcher 종류 #

표현 방식 기준 Matcher #

종류	예시	의미	주의점
전체 매칭	빈 값, *, matcher 생략	해당 event가 발생할 때마다 실행	자주 실행되는 event에서는 과도하게 넓을 수 있음
정확 매칭	Bash	특정 값과 정확히 일치할 때 실행	tool event에서는 도구 이름과 정확히 일치해야 함
OR 매칭	`Edit|Write`	여러 값 중 하나와 일치하면 실행	파일 수정 계열 Hook에서 자주 사용
정규식 매칭	mcp__.*	패턴에 맞는 값 전체에 반응	너무 넓게 잡으면 의도치 않은 tool까지 포함될 수 있음
event별 의미 매칭	startup, permission_prompt, manual	event 종류에 따라 matcher의 의미가 달라짐	항상 tool 이름을 의미하는 것은 아님

Tool Event에서 자주 쓰는 Matcher #

Tool event에서는 matcher가 주로 Claude가 사용하려는 도구 이름을 기준으로 동작합니다.

Matcher	반응 대상	주 용도
Bash	Bash 명령 실행	위험 명령 차단, 명령 로깅
Read	파일 읽기	민감 파일 접근 감시
Edit	기존 파일 수정	수정 후 lint, formatter 실행
Write	새 파일 작성 또는 전체 덮어쓰기	생성 파일 검사, 포맷팅
Edit|Write	파일 수정 및 작성
Grep	검색 도구 사용	대규모 검색 로깅
Glob	파일 패턴 검색	파일 탐색 감시
WebFetch	웹 페이지 가져오기	특정 URL의 내용을 직접 읽을 때
WebSearch	웹 검색	검색엔진으로 정보를 찾을 때
Agent	서브 에이전트 호출	agent 실행 감시
mcp__.*	모든 MCP tool	MCP 사용 전체 로깅 또는 제한
mcp__github__.*	GitHub MCP 서버의 모든 tool	GitHub 관련 작업 감시
mcp__memory__.*	memory MCP 서버의 모든 tool	memory 저장/조회 감시

SessionStart Matcher #

SessionStart에서는 matcher가 세션이 어떤 방식으로 시작되었는지를 의미합니다.

Matcher	의미	활용 예
startup	새 Claude Code 세션 시작	프로젝트 상태 자동 주입
resume	기존 세션 재개	이전 작업 요약 불러오기
clear	/clear 이후 새 컨텍스트 시작	필수 규칙 다시 주입
compact	컨텍스트 압축 이후 재시작	압축 후 손실된 중요 정보 재주입

Notification Matcher #

Notification에서는 matcher가 알림 종류를 의미합니다.

Matcher	의미	활용 예
permission_prompt	Claude가 권한 승인을 기다리는 상태	데스크톱, Slack, Discord 알림
idle_prompt	Claude가 사용자 입력을 기다리는 상태	작업 완료 알림
auth_success	인증이 성공한 상태	인증 완료 로그
elicitation_dialog	MCP 서버가 사용자 입력 폼을 띄운 상태	외부 입력 요청 알림
elicitation_complete	MCP 입력 폼이 제출되거나 닫힌 상태	입력 완료 로그
elicitation_response	MCP 응답이 서버로 전달된 상태	MCP 상호작용 기록

Subagent Matcher #

SubagentStart, SubagentStop에서는 matcher가 실행되는 subagent의 이름 또는 타입을 의미합니다.

Matcher	의미	활용 예
general-purpose	기본 범용 subagent	일반 agent 실행 로그
Explore	탐색용 agent	코드베이스 탐색 시작/종료 기록
Plan	계획 수립 agent	계획 단계 감시
custom agent name	사용자가 정의한 agent 이름	보안 리뷰어, 테스트 작성자 등 특정 agent만 감시

Compact 관련 Matcher #

PreCompact, PostCompact에서는 matcher가 컨텍스트 압축 방식을 의미합니다.

Event	Matcher	의미	활용 예
PreCompact	manual	사용자가 수동으로 압축 실행	압축 전 중요 정보 백업
PreCompact	auto	자동 압축 발생	자동 압축 전 작업 상태 저장
PostCompact	manual	수동 압축 완료	압축 후 요약 재주입
PostCompact	auto	자동 압축 완료	압축 후 프로젝트 규칙 재주입

ConfigChange Matcher #

ConfigChange에서는 matcher가 어떤 설정 출처가 변경되었는지를 의미합니다.

Matcher	의미	활용 예
user_settings	사용자 전역 설정 변경	개인 설정 변경 로그
project_settings	프로젝트 설정 변경	팀 공유 설정 변경 감시
local_settings	로컬 프로젝트 설정 변경	개인 실험 설정 감시
policy_settings	조직 관리 정책 변경	엔터프라이즈 정책 변경 기록
skills	Skill 관련 설정 변경	Skill 추가/수정 감시

FileChanged Matcher #

FileChanged는 일반 tool matcher와 다르게, 감시할 파일명을 지정하는 용도로 이해하는 편이 좋습니다.

Matcher	의미	활용 예
.env	.env 파일 변경 감지	환경 변수 변경 후 알림
.envrc	.envrc 파일 변경 감지	direnv reload 안내
package.json	패키지 설정 변경 감지	dependency 변경 후 install 안내
tsconfig.json	TypeScript 설정 변경 감지	typecheck 재실행
CLAUDE.md	Claude 지침 파일 변경 감지	지침 변경 알림

Matcher를 지원하지 않는 Event #

일부 event는 matcher를 적어도 의미가 없고, event 발생 시 항상 실행됩니다.

Event	설명
UserPromptSubmit	사용자가 프롬프트를 제출할 때마다 실행
PostToolBatch	tool batch 처리 후 실행
Stop	Claude가 응답을 끝내려 할 때마다 실행
TeammateIdle	팀원 idle 관련 event
TaskCreated	task 생성 시 실행
TaskCompleted	task 완료 시 실행
WorktreeCreate	worktree 생성 시 실행
WorktreeRemove	worktree 제거 시 실행
MessageDisplay	메시지 표시 시 실행
CwdChanged	작업 디렉터리 변경 시 실행

이런 event에서는 matcher로 거르기보다, handler 내부에서 조건을 검사해야 합니다.

Matcher 작성 시 주의사항 #

주의사항	설명
너무 넓은 matcher는 피하기	*, .*, 빈 matcher는 모든 상황에 실행될 수 있음
권한 관련 Hook은 특히 좁게 잡기	자동 승인이나 차단 로직이 넓으면 보안 문제가 생길 수 있음
자주 실행되는 event에서는 가볍게 사용	PreToolUse, PostToolUse, UserPromptSubmit, Stop 계열은 성능 영향이 큼
MCP matcher는 실제 tool 이름 구조를 알아야 함	MCP tool은 보통 mcp__서버명__도구명 형식
Stop에는 matcher가 적용되지 않음	완료 조건 검사는 handler 내부에서 처리
FileChanged는 단순 파일명 중심으로 사용	복잡한 정규식보다는 .env, package.json처럼 명확히 지정