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

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

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

📌 영향을 받는 사람

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

⚠️ Breaking Change (파괴적 변경)

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

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

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

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

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

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

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

💡 Tips (팁)

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

셀프호스트 러너 관리자- 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 및 셀프호스트 러너를 사용하고 있다면 동작 여부 확인부터 시작하는 것을 추천합니다.