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

Claude Code 2.1.317

웹 또는 셸 도구 호출이 계정 이메일 주소를 네트워크로 보내기 전에 묻는 확인 절차, 실패한 Agent SDK 훅 콜백이 동작을 막게 하는 옵션, Claude apps gateway의 비용 보고 API가 추가됐습니다. 클라우드나 셀프 호스팅 러너 세션 안에서 실행한 `claude -p`가 그 세션의 ID와 대화 기록을 함께 쓰던 문제 등 80건이 넘는 변경이 포함됐습니다.

공식 발표 →

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

무엇이 바뀌었나?

Claude Code 2.1.317이 2026년 11월 3일 출시됐습니다. 계정 이메일 전송 확인, Agent SDK 훅 실패 시 차단, /schedule의 커넥터 경고처럼 의도하지 않은 동작을 막는 장치와 Claude apps gateway의 비용 보고 API가 새로 들어왔습니다. 수정은 MCP 서버, 세션과 압축, claude -p, OpenTelemetry 내보내기, 에이전트 팀, 셀프 호스팅 러너, VS Code 확장에 걸쳐 전체 변경의 절반이 넘습니다.

새 기능

  • 계정 이메일 전송 전 확인

    웹 도구나 셸 도구 호출이 계정 이메일 주소를 네트워크로 보내도 이를 따로 확인하는 단계가 없었습니다. 이제 전송 전에 묻는 확인 절차가 추가됐습니다.

  • Agent SDK 훅 콜백의 onFailure: "block"

    훅 콜백이 실패하면 동작이 그대로 실행됐습니다. 이 옵션을 설정하면 콜백이 실패했을 때 해당 동작을 차단합니다.

  • /schedule의 커넥터 경고

    새 클라우드 예약 작업에 요청하지 않은 커넥터가 연결돼도 알아차리기 어려웠습니다. 이제 경고와 함께 제거 방법을 알려 줍니다.

  • Claude apps gateway 비용 보고 API

    지난 지출을 관리자 API로 조회할 수 있는 보고서가 없었습니다. GET /v1/organizations/analytics/cost로 기간을 지정해 전체, 개발자별, 일별, IdP(사내 로그인 시스템) 그룹별 지출을 읽을 수 있습니다.

  • Claude apps gateway의 IdP 그룹 일별 기록

    admin:이 설정된 gateway에서 개발자별 IdP 그룹을 매일 기록합니다. 보관 기간은 admin.identity_retention_days로 정하며, 위 비용 보고서는 이 기록을 기준으로 그룹별 지출을 묶습니다.

  • OTel 속성 4가지

    OTel(OpenTelemetry, 동작 데이터를 수집하는 표준)의 metrics, events, spans에 anthropic.plan, anthropic.seat_type, anthropic.provider, anthropic.custom_base_url이 추가됐습니다.

  • CLAUDE_CODE_DISABLE_NESTED_SESSION_ID

    클라우드나 셀프 호스팅 러너 세션 안에서 실행한 claude -p는 이번 버전부터 바깥 세션의 ID를 함께 쓰지 않습니다. 셀프 호스팅 러너에서 이전처럼 그 세션의 ID와 대화 기록을 써야 한다면 이 환경 변수를 1로 설정합니다.

  • Claude Desktop Code 탭의 관리 설정 안내

    조직의 원격 관리 설정(remote managed settings)이 세션에 아직 불러와지지 않았는지 Code 탭에서 알 수 없었습니다. 이제 불러오지 못한 상태와 불러온 뒤에 각각 안내가 표시됩니다.

  • 서브에이전트 도구 호출에 대한 auto mode 안내

    auto mode의 확인 단계가 서브에이전트의 도구 호출에 답을 내지 못하면 메인 화면에 아무것도 남지 않았습니다. 이제 안내가 표시됩니다.

  • [Cloud sessions] 링크 카드

    MCP 서버가 사용자에게 방문을 요청한 링크는 보지도 못한 채 지나갈 수 있었습니다. 이제 링크 카드가 나타나 열거나 거절할 수 있습니다.

주요 개선

  • Read 도구의 “file unchanged since your last Read” 응답 제거

    변경되지 않은 파일을 다시 읽으면 내용 대신 이 안내 문구만 돌아왔습니다. 이제 파일 내용을 그대로 돌려줍니다.

  • 실행 중인 백그라운드 에이전트로 보내는 SendMessage

    메시지가 도착하기까지 기다려야 했습니다. 이제 에이전트가 실행 중인 명령을 중단하지 않고 백그라운드로 옮기므로 메시지가 더 일찍 도착합니다.

  • 메인 대화와 다른 모델을 쓰는 서브에이전트와 팀원의 effort

    모델이 달라도 세션의 effort 수준을 따랐습니다. 이제 해당 모델에 저장된 effort 수준이나 그 모델의 기본값을 사용합니다.

  • 종료 시 표시되는 “Resume this session with” 안내

    안내에 나오는 명령에 처음 실행할 때 쓴 플래그가 빠져 있었습니다. 이제 --chrome --debug처럼 실행 때 쓴 플래그를 --resume 앞에 함께 보여 줍니다.

  • Claude apps gateway 연결 실패 시 시작 오류

    필수 gateway에 연결할 수 없을 때도 로그인 문제처럼 안내했습니다. 이제 네트워크를 확인하라고 안내하고, gateway의 TLS 인증서를 검증할 수 없는 경우에는 그 사실도 알려 줍니다.

  • Microsoft Foundry의 Azure 자격 증명 오류

    Azure 자격 증명을 불러오지 못했을 때 표시되는 오류가 이제 자격 증명을 확인하거나 갱신하라고 안내하고, cloud_credential_error로 보고합니다.

  • /design-sync의 사전 안내

    디자인 시스템이 Claude로 옮겨 간 경우 업로드 단계에서야 실패했습니다. 이제 처음에 이를 알리고 빌드 전에 멈춥니다.

  • 셀프 호스팅 러너의 서버 오류 복구

    서버 오류 뒤에도 실패한 연결을 다시 사용했습니다. 이제 501, 529를 제외한 5xx(서버 측 오류) 뒤에는 러너의 다음 폴링(주기적 확인 요청)과 세션이 새 연결을 엽니다. 세션의 하트비트(연결 확인 신호)에 응답이 없을 때도 유휴 연결을 하나씩 시도하지 않고 새 연결을 엽니다.

  • 플러그인 모니터 실행 중 종료

    종료할 때 플러그인 모니터 때문에 “Background work is running” 확인이 표시됐습니다. 이제 플러그인 모니터에는 이 확인을 건너뜁니다.

  • plugin-authoring 스킬의 공유 제안

    내장 plugin-authoring 스킬이 직접 만든 mod(Claude의 인터페이스나 동작을 바꾸는 확장)가 동작한 뒤 공유를 도와주겠다고 한 번 제안합니다.

  • Remote Control의 포크 이름

    앱이 이름을 정하지 않은 포크의 이름이 이제 길어도 “(fork)“로 끝납니다. claude remote-control로 시작한 세션에서는 “Name (fork)“를 다시 포크하면 “Name (fork 2)“가 됩니다.

  • [Cloud sessions] 조직 환경 대화상자

    관리자 설정의 조직 환경 대화상자가 개인 대화상자와 같은 짧은 구성으로 바뀌었습니다. 각 섹션은 행을 눌러 열고, 저장하지 않은 입력이 있으면 닫기 전에 묻습니다.

  • [Claude Tag] Slack의 아티팩트 링크 카드

    Slack에 새로 붙여 넣은 아티팩트 링크가 Slack 측면 패널 대신, Open 버튼으로 Claude에서 아티팩트를 여는 간단한 카드로 표시됩니다.

주요 버그 수정

MCP, 플러그인, 스킬

  • 일부 Claude 데스크톱 세션에서 프로젝트 및 로컬 MCP 서버가 첫 턴 뒤에 연결이 끊기던 문제 수정.
  • stdio MCP 서버의 env 설정에서 AWS_BEARER_TOKEN_BEDROCK을 비워 두면 빈 값이 전달되던 문제 수정. 이제 변수 자체를 해제하므로 서버가 컴퓨터의 AWS 자격 증명을 사용할 수 있습니다.
  • 동기화된 플러그인에 같은 서버가 포함돼 있으면, 클라우드 세션에서 정상 동작하는 claude.ai 커넥터를 두고 Claude가 인증이 필요하거나 실패했다고 말하던 문제 수정.
  • claude.ai에서 동기화한 스킬을 디스크에 쓸 수 없을 때 스킬이 사라지거나 10분마다 다시 내려받던 문제 수정.
  • 명령을 등록하는 플러그인이 많은 헤드리스 세션에서 메모리 사용량이 높고 시작이 느리던 문제 수정.

로그인과 네트워크

  • claude auth status가 느린 토큰 갱신이 저장되기 전에 종료해, 다음 실행 때 로그아웃될 수 있던 문제 수정.
  • 지역이나 네트워크 차단(HTTP 403)이 로그인 실패로 표시되던 문제 수정. 이제 오류가 차단 사실을 설명합니다.
  • 루트 인증서 갱신 뒤 TLS 트래픽을 검사하는 일부 프록시 환경에서 API 요청이 “unable to get local issuer certificate”로 실패하던 문제 수정.

OpenTelemetry

  • 프록시를 거쳐 https:// 엔드포인트로 내보낼 때, 다른 내보내기가 진행 중에 시작된 내보내기가 전송되지 않던 문제 수정.
  • 프록시가 http:// 엔드포인트로의 내보내기를 HTTP 403으로 차단하면 연결 시도가 대량으로 발생하던 문제 수정.
  • 응답하지 않는 프록시 뒤에서 내보내기가 무기한 멈추던 문제 수정. 이제 10초 뒤 시간 초과되며, OTEL_EXPORTER_OTLP_TIMEOUT으로 최대 30초까지 늘릴 수 있습니다.

auto mode와 권한

  • 기본 URL로 설정한 LLM gateway가 서버 측 안전 확인에 403이나 422로 응답하면 auto mode가 매 턴 실패하던 문제 수정. apiKeyHelper를 쓰는 경우의 403은 동작이 바뀌지 않았습니다.
  • 클라우드 세션의 auto mode가 Artifact 도구의 업로드, 데이터베이스 쓰기, outputs 폴더를 통한 파일 저장에서 승인을 기다리며 멈추던 문제 수정.
  • 리드 세션이 manual mode인데 tmux나 iTerm2 창의 에이전트 팀 팀원이 auto mode로 시작하던 문제 수정.
  • 백그라운드 세션이 업그레이드되거나 종료될 때 방금 바꾼 권한 모드를 가끔 잃던 문제 수정.
  • 권한 확인 두 개가 동시에 뜨면 claude.ai와 모바일 앱에서 두 번째 확인에 파일 경로나 명령이 표시되지 않던 문제 수정.
  • Remote Control과 SDK 호스트가 mod의 도구 호출에 “don’t ask again”을 제시하던 문제 수정.

세션과 압축

  • 아주 큰 CLAUDE.md가 마지막 전송 이후 바뀐 세션에서 자동 압축 뒤 “Prompt is too long”이 나던 문제 수정.
  • 압축 과정에서 자체 요청을 줄여야 할 때, 매우 긴 대화의 이전 요약이 사라지던 문제 수정.
  • 재개한 세션이 Claude가 이미 알고 있는 파일 변경을 다시 알려 주던 문제 수정.
  • 도구가 꺼져 있어 이전 호출이 실패한 경우, 재개한 세션에서 Claude가 내장 도구를 가끔 쓰지 않던 문제 수정.
  • 제목을 생성하는 동안 새 메시지나 Stop이 도착하면 클라우드와 SDK 세션의 제목이 사라지던 문제 수정.
  • 세션이 많은 프로젝트에서 연결된 세션이 첫 페이지보다 오래되면 claude --from-pr이 “No conversations found”를 보고하던 문제 수정.
  • 데스크톱 앱 Code 탭의 새 세션처럼 앱이 미리 시작해 두었다가 프로젝트에서 여는 세션이 프로젝트의 effortLevel 설정을 무시하던 문제 수정.
  • 실행 직후 1초 안팎에 고친 설정 파일이, 설정 파일이 다시 바뀔 때까지 반영되지 않던 문제 수정.
  • --setting-sources를 쓰는 실행처럼 정리를 건너뛰는 실행이 있는 컴퓨터에서 오래된 대화 기록이 정리되지 않던 문제 수정.

claude -p 실행

  • 디스크나 할당량이 가득 차 대화 기록이나 ~/.claude.json 쓰기에 실패해도 종료 코드 0으로 끝나던 문제 수정. 이제 오류를 출력하고, text와 json 출력에서는 종료 코드 1로 끝납니다.
  • 클라우드나 셀프 호스팅 러너 세션 안에서 실행한 claude -p가 그 세션의 ID를 함께 쓰던 문제 수정. 그 세션의 대화 기록에 내용을 기록했고, 재시작하면 엉뚱한 대화를 이어 갈 수 있었습니다.
  • 클라우드나 셀프 호스팅 러너 세션 안에서 실행한 claude -p가 자체 제목을 만들어 그 세션으로 보내던 문제 수정.

에이전트 팀과 백그라운드 작업

  • 삭제한 에이전트 팀 수신함이 팀원이 늦게 보낸 메시지로 다시 생기던 문제 수정.
  • 다시 만든 에이전트 팀원이 이전의 종료 승인 때문에 팀에서 제거되던 문제 수정.
  • 프롬프트에 입력한 글자를 지우려고 Ctrl+C를 누르면 실행 중인 백그라운드 에이전트가 모두 멈추던 문제 수정.
  • 멈춘 셸 명령의 자식 프로세스에 SIGTERM(종료 요청 신호)이 가끔 두 번 전달돼, 일부 프로그램이 정리 작업을 건너뛸 수 있던 문제 수정.

예약 작업과 /team-onboarding

  • Claude가 요청에서 필드를 빠뜨리면, 실행 간격을 스스로 정하는 /loop의 다음 실행이 가끔 예약되지 않던 문제 수정.
  • /schedule이 클라우드 예약 작업을 만들거나 수정한 뒤 결과에 다음 실행 시각과 링크를 넣지 않던 문제 수정.
  • 예약 작업 기능을 끈 뒤에는 저장된 예약 작업을 조회하거나 삭제할 수 없던 문제 수정.
  • 어떤 가이드인지 지정하지 않고 삭제를 요청하면 Claude가 가장 최근에 수정한 /team-onboarding 가이드를 지우던 문제 수정.
  • 서버가 삭제를 거부했는데도 Claude가 /team-onboarding 가이드를 삭제했다고 말하던 문제 수정.

도구와 명령

  • 검색이 시간 제한에 걸렸을 때 Claude가 Grep과 Glob의 일부 결과를 전체 결과로 다루던 문제 수정.
  • PDF 자체 메타데이터 때문에 Read와 @-멘션이 페이지 수를 적게 셀 수 있던 문제 수정.
  • DISABLE_PROMPT_CACHING_OPUS와 DISABLE_PROMPT_CACHING_SONNET이 기본 모델의 [1m], 다른 리전, 날짜 없는 표기에 적용되지 않던 문제 수정.
  • 내 아티팩트가 200개 이상이면 /artifacts와 Artifact 도구의 공유 목록에 공유된 아티팩트가 표시되지 않던 문제 수정.
  • disableRemoteControl 설정으로 Remote Control이 꺼져 있을 때 /remote-control이 그 이유 대신 “Unknown command”로 답하던 문제 수정.
  • 스크린 리더 모드에서 실행 중인 서브에이전트의 경과 시간과 토큰 수가 바뀔 때마다 읽히던 문제 수정.

Claude apps gateway

  • gateway가 Amazon Bedrock의 “Input is too long.” 오류를 가려, 세션이 압축하지 못하고 매 턴 “upstream rejected the request”로 실패하던 문제 수정.
  • 그룹 공유 예산이 소진되면 상태 표시줄과 /usage가 개발자 본인의 지출 한도를 100% 사용한 것으로 표시하던 문제 수정.

Windows

  • 네이티브 경로 조회(native path lookup)가 실패하는 일부 볼륨에서 모든 도구 호출이 거부되던 문제 수정. 이제 작업 디렉터리 확인은 폴더의 식별 정보를 비교합니다.
  • Claude Desktop이 시작하지 않은 세션에서 임시 작업 공간(scratchpad) 등의 임시 경로가 프로젝트 경로 길이만큼 늘어나, 그 안에 복제한 저장소가 260자 경로 제한에 걸리던 문제 수정.

셀프 호스팅 러너

  • 계획 승인 대기 중에 재시작하면 세션이 최근 턴이나 대화 전체를 잃던 문제 수정.
  • 세션이 새 러너로 옮겨 가고 턴이 CLAUDE_CODE_RESUME_INTERRUPTED_TURN_MAX_AGE_MS보다 오래되면 Claude가 중단된 도구 호출을 보지 못하던 문제 수정.
  • 세션 서비스가 설정 저장을 거부한 경우, 끈 MCP 서버가 세션이 새 컴퓨터로 옮겨 간 뒤 다시 켜지던 문제 수정.

Remote Control

  • claude remote-control을 재시작한 뒤, 이전 메시지로부터 1분 안에 유휴 세션에 보낸 다음 메시지에 응답이 없던 문제 수정.

VS Code 확장

  • 포크한 대화에서 메시지가 빠지던 문제 수정. 병렬로 실행한 도구 호출 중 하나만 남고 압축이 유지한 마지막 메시지가 사라져, Claude의 답변만 있고 질문이 없는 대화가 될 수 있었습니다.
  • Claude가 제때 시작을 마치지 못하면 메시지가 사라지던 문제 수정. 이제 오류를 보여 주기 전에 Claude를 한 번 더 시작합니다.
  • 지역이나 네트워크 때문에 요청이 차단됐을 때 로그인 화면이 열리던 문제 수정.
  • Claude 탭의 파일 링크가 다른 편집기 그룹이 아니라 채팅 위에 열리던 문제 수정.
  • chat.fontSize를 키워도 Claude 패널의 첨부 칩, 메뉴, 배너, 대화상자가 작게 유지되던 문제 수정.
  • 텔레메트리를 끄면 ultrathink가 해당 턴의 effort를 높이지 않고 무지개색으로도 표시되지 않던 문제 수정.

Cloud sessions

  • 이미 비밀 값이 있는 호스트에 네트워크 비밀 값을 추가하면 기존 값이 조용히 대체되던 문제 수정. 이제 Add secret 양식이 추가를 거부하고 기존 비밀 값을 안내합니다.
  • 새 예약 작업이 조직의 기본 환경을 무시하던 문제 수정. 이제 양식이 Anthropic 호스팅 기본값 대신 관리자가 고른 환경으로 시작합니다.

알아두면 좋은 점

  • 이메일 전송 확인이 추가됐습니다. 웹 도구나 셸 도구 호출이 계정 이메일 주소를 네트워크로 보내려 하면 묻는 절차를 거칩니다.
  • 셀프 호스팅 러너에서 claude -p의 세션 ID에 의존하는 흐름이 있다면 이번 버전의 동작 변화를 확인하세요. 이전처럼 쓰려면 CLAUDE_CODE_DISABLE_NESTED_SESSION_ID를 1로 설정합니다.
  • Read 도구는 변경되지 않은 파일도 내용을 다시 돌려줍니다. “file unchanged since your last Read” 응답을 전제로 한 자동화가 있다면 함께 살펴보세요.
  • 메인 대화와 다른 모델을 쓰는 서브에이전트와 팀원은 세션의 effort 대신 해당 모델에 저장된 effort 수준이나 그 모델의 기본값을 사용합니다.
  • claude -p의 종료 코드 수정에는 예외가 있습니다. 공간이 가득 찬 NFS(네트워크 파일 시스템) 내보내기는 감지하지 못할 수 있습니다.
  • OpenTelemetry 내보내기는 이제 10초 뒤 시간 초과됩니다. OTEL_EXPORTER_OTLP_TIMEOUT으로 최대 30초까지 늘릴 수 있습니다.
  • 이 글은 주요 항목만 정리했습니다. 전체 변경 목록은 GitHub 릴리스 노트에서 볼 수 있습니다.