Hooks 매처 — 와일드카드와 패턴 지정

매처(matcher)는 훅이 어떤 조건에서 발화할지를 지정하는 문자열입니다. 한마디로 훅의 "필터"이며, settings.json의 훅 설정에서 이벤트를 좁히는 조건으로 기능합니다. 매처 작성법을 익히면 훅의 발화 조건을 자유자재로 컨트롤할 수 있습니다.

Hooks 환경 변수에서 스크립트가 받는 정보를 다뤘다면, 이 글은 "어떤 때 스크립트를 돌릴 것인가"를 정하는 방법입니다. Hooks의 기본 개념은 훅(Hooks)으로 동작 강제하기를 참고하세요.

핵심 요약

• 매처는 훅의 발화 조건을 지정하는 문자열입니다.
• 빈 문자열 ""을 쓰면 모든 도구에 매치합니다.
• 도구명만("Bash", "Edit" 등) 쓰면 해당 도구의 모든 처리에 매치합니다.
• 파이프 기호(|)로 OR 조건을 지정할 수 있습니다 (예: Edit|Write).
• 정규 표현식을 지원하며, 대소문자를 구별합니다.

매처는 settings.json 어디에 쓰나

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npm run format"
          }
        ]
      }
    ]
  }
}

이 예에서는 matcher에 "Edit"을 지정했습니다. Edit 도구(파일 편집)가 실행된 후에 npm run format이 자동으로 실행됩니다.

기본 매처 패턴 5가지

빈 문자열로 모든 도구에 매치

빈 문자열 ""을 지정하면 모든 도구 실행에 매치합니다. 가장 느슨한 조건으로, 조건을 한정하지 않는 장면에서 씁니다. 예를 들어 "matcher": ""를 PostToolUse에 두면 어떤 도구가 실행되든 훅이 발화합니다.

공식 문서의 매처 패턴 표에는 애스터리스크 *, 빈 문자열 "", 생략 중 어느 것이든 모두에 매치한다고 명기되어 있습니다. 어느 쪽이든 동작하지만, 가독성 관점에서 빈 문자열 ""을 쓰는 것을 추천합니다.

도구명으로 매치

특정 도구명을 지정하면 그 도구의 모든 조작에 매치합니다.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Bash 명령이 실행됐습니다'"
          }
        ]
      }
    ]
  }
}

이 설정은 npm install, git commit, rm -rf, mkdir 등 Bash 도구의 모든 실행에 매치합니다.

OR 조건으로 여러 도구에 매치

파이프 기호(|)를 쓰면 여러 도구를 OR 조건으로 지정할 수 있습니다. 파일 생성·편집에 관련된 조작에 같은 처리를 걸고 싶을 때 편리합니다.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npm run format"
          }
        ]
      }
    ]
  }
}

이 설정은 Edit, Write 중 하나가 실행된 경우에 매치합니다. PostToolUse 훅의 기본 설정은 PreToolUse·PostToolUse 훅에서 다룹니다.

명령 패턴은 매처가 아니라 if 필드로

Bash 도구는 실행 명령의 패턴으로 좁히고 싶어지기 마련이지만, matcher 필드 자체는 도구명의 완전 일치·| 구분 리스트·정규 표현식으로만 평가되며, Bash(명령 패턴) 같은 괄호 붙은 구문은 파싱되지 않습니다. 명령 패턴으로 좁히려면 핸들러마다 지정할 수 있는 if 필드(퍼미션 규칙과 같은 구문)를 씁니다.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(npm install)",
            "command": "echo 'npm install이 실행됐습니다'"
          }
        ]
      }
    ]
  }
}

if 필드의 평가 규칙에 따라 &&로 연결된 서브 명령이나 $()·백쿼트 안의 명령도 개별로 평가 대상이 됩니다. 위 예는 npm install에 인수가 붙지 않는 경우에만 매치하므로, npm install lodash처럼 인수가 붙은 경우에는 매치하지 않습니다.

퍼미션 설정에서는 Bash(npm:*) 같은 접두사 매칭을 쓸 수 있습니다. Hooks의 matcher 자체는 이 작성법에 대응하지 않지만, if 필드를 쓰면 같은 퍼미션 규칙 구문의 접두사 매칭(예: Bash(git *))이 가능합니다. 다만 공식 문서는 if가 베스트 에포트 평가이며, 확실한 허가·거부 강제에는 퍼미션 시스템을 써야 한다고 명시하고 있습니다. (2026년 1월 검증 시점 기준)

SessionStart용 매처

SessionStart 훅에서는 matcher를 생략할 수도, 특정 이벤트를 지정할 수도 있습니다. 생략하면 모든 세션 시작 이벤트에서 발화합니다.

예를 들어 새 기동 시에만 npm install을 실행하고 싶다면 아래처럼 설정합니다.

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          {
            "type": "command",
            "command": "npm install"
          }
        ]
      }
    ]
  }
}

SessionStart 훅의 실전 활용은 SessionStart 훅을 참고하세요.

Stop / SubagentStop 훅의 매처 — Stop 훅에는 매처 개념이 없어 늘 발화합니다. 한편 SubagentStop 훅은 SubagentStart와 같은 값(에이전트 타입)으로 매처에 의한 좁히기가 가능합니다. 자세한 내용은 SubagentStop 훅에서 다룹니다.

Bash 명령은 스크립트 안에서 어떻게 판별하나

matcher로 좁힐 수 있는 것은 도구명 Bash까지입니다. 명령 내용으로 더 좁히려면 if 필드의 접두사 매칭을 쓰거나, 더 복잡한 판정이 필요하면 훅 스크립트 안에서 표준 입력의 JSON을 읽어 명령 내용을 직접 검사합니다.

#!/bin/bash
# npm-check.sh - npm 명령만 처리

# 표준 입력에서 JSON을 읽고 명령을 추출
input=$(cat)
command=$(echo "$input" | jq -r '.tool_input.command // empty')

# npm으로 시작하는 명령인지 체크
if [[ "$command" == npm* ]]; then
    echo "npm 명령이 실행됐습니다: $command"
fi

exit 0

settings.json에서는 "matcher": "Bash"로 매치시키고 command에 이 스크립트의 절대 경로(/path/to/npm-check.sh)를 지정합니다.

스크립트 안에서 자주 쓰는 명령 체크 패턴은 아래와 같습니다.

위험한 Bash 명령을 실제로 차단하는 구현은 종료 코드로 제어에서 다룹니다.

매처 설정 시 주의할 점

대소문자를 구별한다

매처는 대소문자를 구별합니다. "Bash"와 "Edit"은 매치하지만 "bash"와 "edit"은 매치하지 않습니다. 도구명의 첫 글자를 대문자로 쓰는 것이 포인트입니다.

여러 매처가 겹치면 모두 병렬 실행된다

같은 이벤트 타입에 여러 매처를 설정한 경우, 매치한 훅은 모두 병렬로 실행되며 실행 순서는 보증되지 않습니다.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [{ "type": "command", "command": "echo 'Edit 실행'" }]
      },
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "echo 'Edit 또는 Write'" }]
      }
    ]
  }
}

이 설정에서 Edit 도구를 실행하면 'Edit 실행'과 'Edit 또는 Write' 양쪽이 표시됩니다. 여러 매처가 의도치 않게 중복 발화하지 않도록 이 동작을 기억해 두세요.

정규 표현식을 지원한다

Hooks의 매처는 정규 표현식을 지원하므로 더 유연한 패턴 지정이 가능합니다. Edit|Write는 완전 일치의 OR 목록으로 평가되고, Notebook.*처럼 쓰면 Notebook으로 시작하는 도구 전부에 매치합니다. 모든 도구에 매치시키려면 * 또는 빈 문자열을 씁니다.

정리

• 매처는 훅의 발화 조건을 지정하는 문자열 필터입니다.
• 빈 문자열로 모두에 매치, 도구명으로 좁히기, 파이프(|)로 OR 조건, 정규 표현식까지 지원합니다.
• Bash(npm:*) 같은 명령 패턴은 matcher가 아니라 if 필드나 스크립트 안의 판별로 처리합니다.
• 대소문자를 구별하며, 겹치는 매처는 모두 병렬 실행됩니다.
• 심플한 매처부터 시작하고, 익숙해지면 OR 조건이나 정규 표현식을 활용하세요. 훅이 작업을 막지 않게 하는 방법은 비동기 실행 async:true에서 이어집니다.