Claude Code 후크 matcher 완전 일치화 및 버그 수정 정리

Claude Code v2.1.195가 출시되었으며, **기존의 후크 (hooks) 설정에 영향을 미치는 파괴적 변경 (Breaking Change)**을 포함한 여러 수정이 이루어졌습니다. 그중에서도 「하이픈 구분 식별자의 매칭 동작 변경」은 MCP 서버의 후크를 설정하고 있는 모든 개발자가 대응 여부를 확인해야 합니다.

또한, 백그라운드 에이전트의 데이터 손실 버그 수정 및 일본어·중국어·태국어 사용자에게 직접적인 영향을 미치는 음성 입력 수정 등 실용적으로 중요한 개선 사항도 포함되어 있습니다.

📌 영향을 받는 사람

.claude/settings.json에서 후크 (hooks)를 설정하고 있는 개발자

• MCP 서버를 이용하여 자동화를 구축하고 있는 개발자

claude agents로 백그라운드 작업 (background jobs)을 운용하고 있는 개발자

• 일본어·중국어·태국어로 음성 받아쓰기 (dictation)를 사용하고 있는 분

우선순위	ID	종별	타이틀	대응 필요 여부
🔴 높음	change-001	파괴적 변경	후크 matcher의 하이픈 구분 식별자가 완전 일치로 변경	대응 필요
...

⚠️ Breaking Change

하이픈을 포함하는 식별자 (code-reviewer, mcp__brave-search 등)의 matcher가 기존의 부분 일치 (substring match)에서 **완전 일치 (exact match)**로 변경되었습니다. 기존의 후크 설정이 부분 일치 동작에 의존하고 있었다면, 후크가 실행되지 않게 됩니다.

영향을 받는 케이스:

확인해야 할 설정 파일:

• ~/.claude/settings.json (글로벌 설정)
• .claude/settings.json (프로젝트 설정)

claude agents로 백그라운드 작업을 운용하고 있는 개발자에게 직접적인 영향을 주는 버그가 수정되었습니다. 새로운 버전의 Claude Code가 쓰기 작업을 수행할 때, 작업이 소실되거나 데이터를 잃는 문제입니다.

버전 업데이트 후에는 자동으로 수정된 동작이 적용되므로 추가 대응은 필요하지 않습니다. 다만, 업데이트 전에 발생한 손실 데이터는 복구할 수 없습니다.

일본어·중국어·태국어 등 공백으로 단어를 구분하지 않는 언어에서 음성 받아쓰기의 자동 전송 (auto-submit)이 한 번도 실행되지 않았던 문제가 수정되었습니다.

일본어 사용자가 Claude Code의 음성 입력 기능을 이용할 경우, 이번 업데이트를 통해 처음으로 정상적으로 동작하게 됩니다.

프로젝트의 .claude/settings.json에서만 활성화된 외부 플러그인이 일부 로더 경로에서 설치 동의를 요구하지 않고 실행되는 보안상의 문제가 수정되었습니다.

업데이트를 통해 모든 경로에서 명시적인 동의가 필요하게 됩니다.

풀스크린 모드에서 마우스 클릭·드래그·호버를 무효화하면서, 휠 스크롤은 유지할 수 있는 환경 변수가 추가되었습니다. 터미널 멀티플렉서 (terminal multiplexer)나 특수한 환경에서의 조작성 향상에 도움이 됩니다.

Before (이전 동작: 부분 일치로 인해 의도치 않게 모든 툴에 매칭됨)

// .claude/settings.json
{
"hooks": {
...

이전 동작에서는 mcp__brave-search가 mcp__brave-search__web_search나 mcp__brave-search__local_search에도 부분 일치했습니다.

After (새로운 동작: 완전 일치이므로, 모든 툴을 대상으로 하려면 와일드카드 필요)

// .claude/settings.json
{
"hooks": {
...

💡 Tips

특정 툴 하나만을 대상으로 하고 싶은 경우: "mcp__brave-search__web_search"와 같이 완전 일치로 지정
지정 서버 하위의 모든 툴을 대상으로 하고 싶은 경우: "mcp__brave-search\..*"와 같이 와일드카드를 끝에 부여

• 하이픈을 포함하지 않는 식별자 (Bash, Read 등)는 이 변경의 영향을 받지 않습니다.

# 풀스크린 모드에서 클릭/드래그/호버를 무효화
export CLAUDE_CODE_DISABLE_MOUSE_CLICKS=1
claude

쉘 설정 파일 (~/.zshrc 등)에 추가함으로써 영구적으로 적용할 수 있습니다.

포인트	내용
최우선 대응	하이픈을 포함하는 후크 matcher (hook matcher)를 사용 중인 경우, .* 와일드카드(wildcard)로 업데이트가 필요
안정성 향상	백그라운드 에이전트 (background agent)의 데이터 손실 및 실행 방해 버그가 수정됨
일본어 사용자 희소식	음성 받아쓰기 (voice dictation)의 자동 전송이 마침내 일본어에서도 동작하도록 개선
보안 수정	플러그인 설치 동의 플로우 (consent flow)가 모든 경로에서 적절하게 요구되도록 수정
전체 평가	안정성, 음성 경험, 보안을 개선하는 유지보수 릴리스

이번 릴리스에서 가장 주의해야 할 점은 후크 matcher (hook matcher)의 동작 변경입니다. MCP 서버의 자동화 후크를 설정해 둔 경우, 업데이트 후에 설정 파일을 확인하고 필요에 따라 와일드카드를 추가해 주세요. 그 외의 변경 사항은 버그 수정과 개선이 중심이므로, 기본적으로 추가 대응은 필요하지 않습니다.