claudekit / updates / claude-code-2-1-307
[ PATCH · ]

Claude Code 2.1.307

Claude API 코드를 API 버전 `2026-10-21`로 옮겨 주는 `/claude-api api-version`과, 권한 규칙이나 샌드박스 등이 도구 호출을 막을 때마다 기록되는 OpenTelemetry 이벤트 `claude_code.safety_event`가 추가됐습니다. HTTP MCP 도구 호출이 두 번 전송되던 문제, macOS 키체인이 잠겨 있을 때나 컴퓨터가 잠자기에 들어갈 때 MCP 서버가 실패하던 문제 등 MCP 안정성 수정이 함께 들어갔습니다.

Claude Code
공식 발표 →

이 글은 공식 문서를 바탕으로 요약·정리한 내용입니다.

무엇이 바뀌었나?

Claude Code 2.1.307이 2026년 10월 21일 출시됐습니다. 새 기능으로 Claude API 코드를 최신 API 버전으로 옮기는 /claude-api api-version, 도구 호출이 막히거나 확인을 요청받은 순간을 기록하는 OpenTelemetry 이벤트, Code Review 자동 리뷰를 끄는 @claude review stop이 추가됐습니다. 수정은 MCP 서버 연결과 재시도, 자동 압축과 클라우드 세션, 권한 메뉴, 서브에이전트와 Agent SDK, 데스크톱 앱과 Cowork, self-hosted runner, VS Code 확장에 걸쳐 있습니다.

새 기능

  • /claude-api api-version

    Claude API를 쓰는 코드를 새 API 버전에 맞추려면 무엇을 바꿔야 하는지 직접 찾아 고쳐야 했습니다. 기본 제공 스킬 /claude-api에 api-version이 추가되어, 프로젝트의 Claude API 코드를 API 버전 2026-10-21로 옮기는 작업을 맡길 수 있습니다. Claude Code 자체의 버전이 아니라 사용자 코드가 호출하는 API 버전을 말합니다.

  • OpenTelemetry 이벤트 claude_code.safety_event

    권한 규칙, auto mode, 안전 검사, 훅, 샌드박스가 도구 호출을 멈추거나 사용자 확인을 요청하거나 Claude에게 되돌려 보낸 기록을 텔레메트리로 따로 모아 보기 어려웠습니다. 이제 이런 일이 생긴 도구 호출마다 claude_code.safety_event 이벤트가 전송되어, 조직의 모니터링 도구에서 어떤 장치가 어떤 호출을 막았는지 집계할 수 있습니다.

  • [VSCode] 음성 받아쓰기가 저절로 멈출 때 안내

    음성 받아쓰기(voice dictation)가 저절로 멈추면 이유를 알 수 없었습니다. 이제 15초 동안 인식된 말이 없거나 2분 제한에 도달해 멈추면, 마이크 버튼에 이유와 함께 지금까지 입력된 텍스트는 유지된다는 안내가 표시됩니다.

  • [Code Review] @claude review stop

    pull request에 @claude review always로 자동 리뷰를 걸어 두면, 이를 끄는 간단한 방법이 없었습니다. 이제 @claude review stop(또는 off, pause)으로 구독을 끝낼 수 있으며, 이때 새 리뷰는 시작되지 않습니다.

주요 개선

  • 해석할 수 없는 도구 호출 재시도

    모델이 형식이 깨진 도구 호출을 보내면 그 턴이 바로 오류로 끝났습니다. 이제 최대 두 번까지 다시 시도하고, 그래도 실패할 때만 오류로 턴을 끝냅니다.

  • 동시에 실행한 fork 서브에이전트의 작업 구분

    fork 서브에이전트(현재 대화 맥락을 이어받아 실행되는 서브에이전트) 여러 개를 함께 띄우면, 각 서브에이전트가 자기 몫이 무엇인지 몰라 다른 서브에이전트의 작업까지 시작하려 할 수 있었습니다. 이제 각자 어느 실행이 자기 것인지 전달받아, 이런 일이 훨씬 덜 일어납니다.

  • 브라우저 로그인 완료 화면

    브라우저 로그인이 끝나도 계정 프로필을 불러올 때까지 완료 화면이 늦게 떴습니다. 이제 로그인이 끝나는 즉시 완료 화면이 표시됩니다.

  • 웹 검색 거부 사유 표시

    클라우드 세션과 self-hosted runner 세션에서 웹 검색이 403으로 거부되면 사유와 상관없이 “Authentication error”만 보였습니다. 이제 응답에 사유가 있으면 그 사유가 표시됩니다.

  • 클라우드 세션의 첫 응답 속도

    데스크톱 앱의 MCP 서버 중 하나가 연결되지 않으면 클라우드 세션의 첫 응답이 늦어졌습니다. 이제 이런 경우에도 첫 응답이 더 빨리 옵니다.

  • Remote Control 연결 시간

    대화 기록에 붙여 넣은 큰 이미지나 PDF 읽기가 있으면 Remote Control 연결에 시간이 오래 걸렸습니다. 이제 연결 시간이 줄었습니다.

동작이 바뀐 항목

  • WebSearch 사용량 소진 안내 (변경)

    WebSearch 사용량을 다 쓰면 Claude가 받는 안내에, 브라우저나 computer use로 검색 엔진에 검색하지도 말라는 내용이 추가됐습니다.

  • axScreenReader 설정 적용 범위 (변경)

    axScreenReader 설정과 settings의 env 블록에 넣은 CLAUDE_AX_SCREEN_READER는 사용자 설정, 관리형 설정, --settings로 넘긴 설정에서만 적용됩니다. 이 동작은 2.1.305부터 적용되어 있었고, 이번 릴리스에서 안내됐습니다.

  • [Self-hosted runner] checkout 훅 시간 제한 (변경)

    checkout 훅은 이제 기본으로 30분이 지나면 중단되고, 세션 준비는 실패로 처리됩니다. 더 오래 걸리는 훅이라면 --checkout-hook-timeout-min 값을 늘리거나 0으로 설정해야 합니다.

  • [Self-hosted runner] Anthropic 관리 git용 인증서 파일 (변경)

    Anthropic이 관리하는 git용으로 만드는 인증서 파일이 CLI와 같은 방식으로 신뢰할 인증서를 걸러 냅니다. 제외된 인증서 수는 [runner:warn] 줄로 표시됩니다.

  • [VSCode] “still open somewhere else” 안내 범위 (변경)

    확장을 재시작한 뒤 남아 있는 Claude 프로세스도 이 안내에 포함됩니다. 이런 프로세스는 보통 10분 안팎이면 저절로 종료됩니다.

  • [VSCode] 인증서 처리 (변경)

    음성 받아쓰기와 확장이 직접 보내는 요청이 CLI와 같은 방식으로 신뢰할 인증서를 걸러 냅니다. 확장의 요청은 환경 변수나 사용자 설정에 지정된 NODE_EXTRA_CA_CERTS 파일도 신뢰합니다.

주요 버그 수정

모델과 게이트웨이

  • CLAUDE_CODE_DISABLE_1M_CONTEXT를 설정한 상태에서 opus[1m]처럼 [1m]이 붙은 모델 별칭을 쓰면 model-not-found 오류로 요청이 실패하던 문제 수정.
  • 사용자 지정 ANTHROPIC_BASE_URL 게이트웨이 뒤와 Foundry에서, 효과가 없는 prompt-caching-scope beta 헤더가 전송되던 문제 수정.

MCP

  • macOS에서 로그인 키체인이 잠겨 있으면 claude -p의 MCP 서버가 “needs authentication”으로 표시되던 문제 수정. 이제 이유를 알려 주고, 잠금을 푼 뒤 다음 실행에서는 다시 로그인하지 않아도 연결됩니다.
  • MCP 서버가 연결되는 도중 macOS나 Linux 컴퓨터가 잠자기에 들어가면 시간 초과로 보고되고, headless 실행에서는 계속 실패 상태로 남던 문제 수정.
  • 호출 도중 연결이 끊기면 HTTP MCP 도구 호출이 두 번 전송되던 문제 수정. 이제 읽기 전용이거나 멱등(같은 요청을 여러 번 보내도 결과가 같은)인 도구만 재시도합니다.
  • 백그라운드 작업이 실행 중일 때 SDK MCP 서버의 최신 도구 없이 턴이 시작되던 문제 수정.

자동 압축과 클라우드 세션

  • PDF 페이지, 이미지 등 큰 도구 결과를 많이 읽는 턴에서 “Autocompact is thrashing” 오류가 나던 문제 일부 사례 수정.
  • 클라우드 세션에서 /autocompact로 바꾼 설정이 세션 재시작 후 기본값으로 돌아가던 문제 수정.
  • 클라우드 세션이나 self-hosted runner 세션이 재시작되면 /clear로 지운 대화가 되살아나던 문제 수정.
  • Claude apps gateway 세션에서 CLAUDE_STREAM_FIRST_BYTE_TIMEOUT_MS가 무시되던 문제 수정.
  • OTEL_EXPORTER_OTLP_HEADERS를 설정하면 Claude apps gateway 뒤의 Claude Desktop 세션 텔레메트리가 거부되던 문제 수정.

권한과 명령 메뉴

  • /permissions > Recently denied에 거부된 셸 명령이 표시되지 않던 문제, 그곳에서 승인해도 auto mode의 로컬 분류기가 재시도된 명령을 검사할 때 이를 무시하던 문제 수정. 이제 항목을 승인하면 설명 대신 명령 자체가 표시됩니다.
  • /help와 / 명령 메뉴에 /claude-api 같은 기본 제공 스킬의 짧은 설명 대신 모델용 긴 설명이 표시되던 문제 수정.

서브에이전트와 Agent SDK

  • 스트리밍 응답에서 서브에이전트 대화 기록에 임시 토큰 사용량과 빈 종료 사유가 기록되던 문제 수정.
  • API가 모델 확인에 5초 넘게 걸리면 Agent SDK의 setModel()과 이를 쓰는 앱의 모델 전환이 거부되던 문제 수정. 이제 최대 15초까지 기다립니다.

데스크톱 앱, Cowork

  • 연결된 앱(예: 데스크톱 앱이 유휴 세션을 보관 처리할 때)이 멈춘 백그라운드 명령이 Claude에게 사용자가 멈춘 것으로 보고되던 문제 수정. 이제 안내에 출력 파일 이름이 함께 표시됩니다.
  • Cowork 클라우드 세션에서 사이트가 4xx 상태나 robots.txt 거부로 응답하면 WebFetch가 도구 오류로 보고하던 문제 수정. 이제 로컬 세션처럼 일반 결과로 처리됩니다.
  • 데스크톱 앱 Code 탭에서 직접 설정한 GitHub MCP 서버의 쓰기 도구가 아무것도 만들지 않고 닫히는 양식을 보여 주던 문제 수정.
  • 서버가 재사용 중인 연결을 닫았을 때 Artifact 도구 읽기가 connection reset으로 실패하던 문제 수정.

Self-hosted runner

  • --use-anthropic-git-proxy 세션이 이전 세션이 클론에 남긴 .claude/settings.local.json을 커밋하던 문제 수정.
  • checkout 훅 실행 중 세션을 보관하거나 다시 대기열에 넣거나 runner를 멈추면 훅 프로세스가 계속 실행되고 runner 슬롯이 점유된 채 남던 문제 수정.

VS Code 확장, Cloud sessions

  • [VSCode] Show more로 펼친 긴 프롬프트가 채팅 패널 전체를 덮던 문제 수정. 이제 고정된 프롬프트는 패널의 40%까지만 차지하고 스크롤됩니다.
  • [VSCode] LaTeX 수식이 들어간 목록 항목이나 표 셀의 일부를 리치 텍스트 편집기에 붙여 넣으면 새 목록이나 표로 붙던 문제 수정.
  • [VSCode] NODE_EXTRA_CA_CERTS를 ~/.claude/settings.json에만 설정한 경우 TLS 검사 프록시(Zscaler, Netskope 등) 뒤에서 음성 받아쓰기가 실패하던 문제 수정. 이제 CLAUDE_CODE_CERT_STORE도 따릅니다.
  • [Cloud sessions] 저장소 선택기가 검색 중인데도 “No repositories match”를 표시하던 문제 수정. 이제 결과가 나올 때까지 “Searching…”이 표시됩니다.
  • [Cloud sessions] self-hosted 환경의 “Waiting for a runner” 상태가 잘려 보이던 문제 수정. on-demand runner를 쓰면 마지막 메시지 이후 경과 시간과 실패한 시도가 표시됩니다.

알아두면 좋은 점

  • Claude API 코드를 최신 API 버전으로 옮겨야 한다면 /claude-api api-version으로 API 버전 2026-10-21에 맞추는 작업을 맡길 수 있습니다.
  • HTTP MCP 서버에 읽기 전용이 아닌 도구가 있다면 호출 도중 연결이 끊겼을 때 더 이상 자동으로 재시도하지 않습니다. 같은 요청이 두 번 처리되는 일은 없어지지만, 대신 해당 호출이 실패로 보일 수 있습니다.
  • self-hosted runner의 checkout 훅이 30분 넘게 걸린다면 업데이트 후 세션 준비가 실패합니다. --checkout-hook-timeout-min 값을 늘리거나 0으로 설정하세요.
  • axScreenReader나 CLAUDE_AX_SCREEN_READER를 프로젝트 설정에 넣어 두었다면 2.1.305부터 적용되지 않습니다. 사용자 설정, 관리형 설정, --settings 중 하나로 옮기세요.
  • pull request에 @claude review always를 걸어 두었다면 이제 @claude review stop으로 자동 리뷰를 끌 수 있습니다.