Claude Code v2.1.301 릴리스 변경점 요약: mod의 .catch 및 $.env.set 동작 변경

Claude Code v2.1.301이 출시되었습니다. 이번 버전에는 mod API의 파괴적 변경이 1건 포함되어 있어, 기존 mod를 제작하는 사용자는 확인이 필요합니다.

아울러 놓치면 작업에 차질을 빚을 수 있는 버그나 무단으로 크레딧이 소모되는 문제도 수정되었습니다.

구분	내용
파괴적 변경	mod hook의 `.catch`와 `$.env.set` 동작 변경
...
이 글에서는 severity가 high인 4건을 중심으로, medium 등 주요 변경 사항들을 정리합니다.

📌 영향을 받는 사람

mod / 플러그인을 직접 제작하는 사람 (.catch나 $.env.set을 사용하는 경우)
WorktreeCreate hook에서 worktree를 생성하는 사람
조직 단위로 fable/best 별칭(alias)을 사용하는 사람
CI 등 무인 환경에서 Claude Code를 구동하는 사람
셀프 호스팅 러너를 managed settings로 운영하는 사람

⚠️ Breaking Change (파괴적 변경)

mod hook의 .catch가 호출되는 조건과, $.env.set의 반환값이 변경되었습니다. 해당 mod는 재검토가 필요합니다.

항목	내용
`.catch`가 실행되는 조건	hook 자체가 예외를 발생시키거나 타임아웃한 경우에만
hook 자체 호출 하에서 발생한 이벤트	해당 hook을 건너뛰고, `.catch`에도 문의하지 않음

'hook 호출 하에서 발생한 이벤트'를 .catch로 포착하여 처리하던 mod는, 해당 이벤트가 전달되지 않습니다.

상황	resolve 하는 값
변수 설정 또는 삭제 완료 시	`{}`
쓰기가 이루어지지 않은 경우	이유를 나타내는 `{ deny }`

반환값의 내용물을 전제로 한 코드는 동작이 변경될 수 있습니다.

WorktreeCreate hook에서 생성한 worktree는, 커밋되지 않은(un-push) 커밋을 포함하고 있을 수 있습니다. 이전에는 Claude Code를 종료하면 확인 절차 없이 삭제되었습니다. 작업 손실의 위험이 있는 버그였습니다.

이번 수정으로, 삭제 전에 확인 절차가 추가됩니다.

Anthropic API에서, 조직이 최신 Fable 모델을 이용할 수 없을 때, fable (및 best) 별칭이 오류를 일으키는 문제가 있었습니다.

수정 후에는, 이전 Fable 모델로 1회만 재시도합니다.

항목	내용
개선	컨텍스트 창이 작은 모델로 전환할 때, 이전 모델이 먼저 요약하는 과정에서 새 모델에 담기지 않는 대화 내용을 처리함
수정	해당 요약 과정에서 확인 절차 없이 이용 크레딧을 소모하던 케이스가 있었음

💡 Tips (팁)

긴 대화 도중에 컨텍스트 창이 작은 모델로 전환하면, 이전 모델에 의한 요약이 실행됩니다. 이제 크레딧을 소비하기 전에 확인 절차가 생겼기 때문에, 의도치 않은 소모를 방지할 수 있습니다.

기능	개요
`CLAUDE_CODE_RETRY_WATCHDOG_MAX_USAGE_LIMIT_WAIT_MS`	무인 재시도 모드에서, 사용량 제한 초기화까지의 시간이 이 값을 초과할 경우, 대기하지 않고 요청을 종료함
OpenTelemetry `tool_decision`의 새 속성	`classifier_verdict`와 `permission_mode`를 추가. auto mode의 classifier에 의한 판정(판단)과 permission 규칙에 의한 판정을 구분할 수 있음. `OTEL_LOG_TOOL_DETAILS=1`인 경우 `classifier_category` (classifier가 차단했을 때 일치한 내장 규칙 이름)도 출력
mod `Input`의 `rows`	터미널 상에 여러 줄의 텍스트 필드를 표시함. Enter로 전송하고, Shift+Enter 또는 행 끝의 백슬래시+\Enter로 개행함
mod의 질문 다이얼로그의 트리	VS Code・데스크톱・모바일에서 Markdown을 사용할 수 있으며, 최대 48줄까지 표시 가능 (터미널은 기존과 같이 일반 텍스트 12줄)
VS Code의 LaTeX 수식	`$$` 블록, 여러 줄의 `[ \[ … \]` , 인라인의 $…$ 및 `$…$`를 렌더링
VS Code / JetBrains	Pro・Max 플랜의 사용량 제한 배너에 “Get more usage” 링크 추가

대상	내용
Grep / Glob	검색 프로그램이 비정상 종료했을 때 “일치 없음”으로 보고했음. 수정 후에는 검색 실패를 에러로 반환함
Read	`.xlsm` , `.parquet` , `.epub` , `.heic` 등 바이너리를 텍스트로 읽던 문제를 수정함
LLM 게이트웨이	요청과 다른 모델명을 응답으로 반환하는 게이트웨이를 통해, 선택하지 않은 모델로 compaction이 반복되던 문제를 수정함
인증	짧은 명령어가 토큰 업데이트 중에 종료되면 로그아웃되는 문제, 디스크 부족 시 “Please run /login”이라고 오안내되던 문제를 수정함
skill / command	인자 이름이 매우 많거나 긴 경우의 중단 및 메모리 소비를 수정함. 전개는 처음 64개 항목・각 64글자로 제한됨
...	-
mod 개발자-
`.catch`
에 의해 hook 호출 하단에서 발생한 이벤트를 처리하지 않았는지 확인함 -
`$.env.set`
의 반환값이 `{}` 또는 `{ deny }`가 될 것을 전제로 코드를 재검토함

셀프호스트 러너 관리자- managed settings에서 MCP 서버를 제한하고 있을 경우, Slack에서 시작된 세션이 리포지토리를 찾지 못해 첨부할 수 없었습니다. 수정 후에는 해당 도구를 사용하지 못하게 하고 싶을 때 deniedMcpServers를 사용합니다.

: 업데이트 후 종료 시 확인 메시지가 표시됩니다. 커밋되지 않은 커밋이 없는지 확인한 후에 삭제해 주세요. WorktreeCreate hook 사용자 -
CI / 무인 실행 사용자: 장시간 대기를 피하고 싶을 경우 CLAUDE_CODE_RETRY_WATCHDOG_MAX_USAGE_LIMIT_WAIT_MS를 설정합니다. -
모니터링 시스템 담당자: OpenTelemetry의 tool_decision에 새 속성을 추가하면, classifier에 의한 판정과 permission 규칙에 의한 판정을 구분할 수 있습니다. -
CLAUDE.md 업데이트: 다음 내용을 추가하면 팀 공유가 용이해집니다.

## mod / 플러그인 개발
- mod hook의 .catch는, hook 자체의 예외/타임아웃 시에만 실행됨
- $.env.set은 {} (완료) 또는 { deny } (쓰기 없음)으로 resolve 함
...

입력 데이터에는 mod의 구체적인 코드나 API의 시그니처는 포함되어 있지 않습니다. 아래는 변경점을 확인하기 위한

이는 사고방식을 보여주는 유사 코드입니다. 실제 작성 방법은 mod의 공식 문서를 확인해 주세요.

// 유사 코드
const result = await $.env.set("MY_VAR", "value");
// 설정/삭제가 완료된 경우 {}를, 쓰기가 이루어지지 않은 경우 { deny }를 반환합니다.
...

# 사용 한도 리셋까지의 시간이 이 값(밀리초)을 초과할 경우, 대기하지 않고 요청을 종료합니다.
# 예: 30분 = 1800000 ms
export CLAUDE_CODE_RETRY_WATCHDOG_MAX_USAGE_LIMIT_WAIT_MS=1800000

# classifier_category (classifier가 차단했을 때 일치한 내장 규칙 이름)도 출력합니다.
export OTEL_LOG_TOOL_DETAILS=1

파괴적 변경: mod hook의 .catch
은 hook 자체의 예외/타임아웃 시에만 실행되며, $.env.set은 {} 또는 { deny }로 resolve합니다. mod를 직접 제작하는 분들은 재검토해 주세요. -
작업 손실 방지: WorktreeCreate
hook에서 만든 worktree가 종료 시 확인 없이 삭제되지 않게 되었습니다. -
별칭 안정화: 최신 Fable을 사용할 수 없는 조직에서도, fable/best는 한 단계 이전의 Fable로 1회 폴백합니다. -
크레딧 소비 투명화: 작은 컨텍스트 모델로 전환할 때의 요약은 확인 없이 크레딧을 소비하지 않게 되었습니다. -
비대면 실행/모니터링 강화: CLAUDE_CODE_RETRY_WATCHDOG_MAX_USAGE_LIMIT_WAIT_MS와 OpenTelemetry의 classifier 속성이 추가되었습니다. -
검색 신뢰성: Grep・Glob 실패가 '일치 없음'과 구분되도록 되어 모델이 잘못된 전제 하에 진행할 위험이 줄었습니다.

우선 mod 확인과, WorktreeCreate hook 및 셀프호스트 러너를 사용하고 있다면 동작 여부 확인부터 시작하는 것을 추천합니다.

Claude Code v2.1.301 릴리스 변경점 요약: mod의 .catch 및 $.env.set 동작 변경

요약

핵심 포인트

댓글

Ternary Bonsai 2 (2B, 4B, 9B)가 Hugging Face에 출시되었습니다. 2B 모델은 M4 Max에서 커스텀

Nvidia의 Qwen3.8-Flash-Next 모델 FP4 QAD 양자화 정보

첫 번째 분석: 무료 모델 코드가 고정된 버전에서 실행되는가? (n=10)

Comfy에서 Minimax를 사용한 캐릭터 스왑 시연

Ternary Bonsai 2 (2B, 4B, 9B)가 Hugging Face에 출시되었습니다. 2B 모델은 M4 Max에서 커스텀

Nvidia의 Qwen3.8-Flash-Next 모델 FP4 QAD 양자화 정보

첫 번째 분석: 무료 모델 코드가 고정된 버전에서 실행되는가? (n=10)

Comfy에서 Minimax를 사용한 캐릭터 스왑 시연