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

Claude Code 2.1.248

명령이나 코드를 실행하는 내장 도구와 `WebFetch`를 빼고, 파일 도구를 작업 디렉토리 안으로 묶고, 사용자, 프로젝트, 로컬 설정 파일을 무시하는 `--restricted` 모드가 추가됐습니다. 긴 세션에서 한 시간에 한 번꼴로 발생하던 프롬프트 캐시 미스(OAuth 토큰 갱신 후 도구 정의가 다시 렌더링되던 문제)가 수정돼 확장 사고 맥락이 유지되고, 에이전트 정의에 `experimental.cacheTtl`로 에이전트별 캐시 유지 시간을 지정할 수 있습니다. Claude 데스크톱 앱과 Cowork 세션이 30일 뒤 사라지던 문제, `claude agents` 목록이 오래된 백그라운드 세션을 되살리거나 이미 다른 터미널에서 연 세션을 두 번 실행하던 문제도 정리됐고, `/ultrareview`와 로컬에서 시작한 클라우드 세션이 `prod.env` 계열 파일과 자격 증명 파일의 임시, 백업 사본을 업로드하던 문제가 수정됐습니다.

Claude Code
공식 발표 →

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

무엇이 바뀌었나?

Claude Code 2.1.248이 2026년 8월 27일 출시됐습니다. 실행 도구를 걷어낸 --restricted 모드가 추가되고, 긴 세션에서 한 시간에 한 번씩 캐시가 깨지던 원인이 밝혀져 수정됐습니다. 백그라운드 세션 관리 화면인 claude agents의 오작동(오래된 세션 되살리기, 중복 실행, 삭제 거부)이 정리됐고, 클라우드로 올라가는 파일에서 자격 증명 파일의 사본이 제외됐습니다.

새 기능

  • --restricted 모드

    도구 사용 범위를 좁히려면 권한 규칙을 직접 조합해야 했고, 설정 파일이 그 범위를 다시 넓힐 수 있었습니다. --restricted(또는 CLAUDE_CODE_RESTRICTED=1)는 명령이나 코드를 실행하는 내장 도구와 WebFetch를 제거하고(--tools에 명시한 경우는 예외), 파일 도구를 작업 디렉토리 안으로 묶고, bypassPermissions를 거부하며, 사용자, 프로젝트, 로컬 설정 파일을 무시합니다.

  • 에이전트별 프롬프트 캐시 유지 시간(experimental.cacheTtl)

    서브에이전트의 캐시 유지 시간은 전역 설정으로만 정할 수 있었습니다. 이제 에이전트 정의 frontmatter에 experimental.cacheTtl("5m" 또는 "1h")을 지정할 수 있고, 서브에이전트 캐시 설정이 따로 없을 때 이 값이 적용됩니다.

  • 서버 관리형 설정 진단

    서버에서 내려오는 관리형 설정이 적용되지 않아도 그 사실을 알기 어려웠습니다. 이제 설정을 불러오지 못하면 시작 시점에 경고가 뜨고, /doctor와 /status에 실패 이유나 설정을 아예 가져오지 않은 이유(Bedrock, Vertex, 서드파티 제공자, 커스텀 ANTHROPIC_BASE_URL)가 표시됩니다.

  • Bedrock, Vertex, Foundry에서 세션 간 메시지

    같은 컴퓨터의 다른 세션에 메시지를 보내는 기능은 일부 환경에서 쓸 수 없었습니다. 이제 Bedrock, Vertex, Foundry 환경과 텔레메트리를 끈 환경에서도 SendMessage, ListAgents를 사용할 수 있습니다.

  • Enterprise 조직의 /usage-credits 확대

    AWS 마켓플레이스를 통한 청구, 셀프서브 Enterprise, Enterprise 체험 조직의 구성원은 사용량 한도를 올려달라고 요청할 경로가 없었습니다. 이제 이 조직들에서도 /usage-credits로 관리자에게 요청할 수 있습니다.

  • 자체 호스팅 러너의 라벨 지정

    자체 호스팅 러너는 호스트 이름으로만 등록돼, 여러 대를 구분하기 어려웠습니다. claude self-hosted-runner --client-label <label>이나 SELF_HOSTED_RUNNER_CLIENT_LABEL로 등록 라벨을 직접 지정할 수 있습니다.

  • /web-setup의 GitHub 토큰 범위 경고

    GitHub CLI 토큰에 workflow 범위가 없으면 아주 큰 저장소로의 푸시가 거부될 수 있는데, 설정 단계에서는 그 사실을 알 수 없었습니다. 이제 /web-setup이 범위 누락을 경고합니다.

주요 개선

  • Workflow 도구의 설명 분량 축소

    Workflow 도구의 설명이 약 5.7k 토큰을 차지해, 쓰지 않는 세션에서도 그만큼 분량을 먹었습니다. 이제 설명은 약 1k 토큰이고, 스크립트 작성 참고 자료는 함께 제공되는 workflow-authoring 스킬로 옮겨졌습니다.

  • /ultrareview <PR#>의 사전 확인

    클라우드 세션이 시작된 뒤에야 저장소에 접근할 수 없다는 사실이 드러났습니다. 이제 실행 전에 Claude 계정에 연결된 GitHub 계정이 해당 저장소에 접근할 수 있는지 확인하고, 안 되면 해결 방법을 알려줍니다.

  • 프롬프트 하단 PR 배지의 조회 감소

    풀 리퀘스트에 변화가 없어도 배지가 GitHub를 자주 조회했습니다. 이제 변화가 없으면 조회 간격을 늘리고, 푸시나 gh pr 명령이 있으면 즉시 갱신합니다.

  • 관리형 설정 승인 대상 조정

    클라이언트 측 시간 초과, MCP 시작 모드, 스트림 감시 관련 환경 변수까지 승인 화면을 띄웠습니다. 이제 이 항목들은 설정 승인 프롬프트를 발생시키지 않습니다.

  • 세션 간 메시지의 디렉토리 대체

    기본 디렉토리를 쓸 수 없는 환경에서는 세션 간 메시지가 동작하지 않았습니다. 이제 사용자별 비공개 /tmp 디렉토리로 대체하고, 안내 문구와 /status에 어떤 디렉토리를 손봐야 하는지 표시됩니다.

  • 에이전트 뷰 입력창의 키 동작 변경

    에이전트 뷰의 실행 입력창은 프롬프트 입력창과 shift+enter 동작이 달랐습니다. 이제 shift+enter는 줄바꿈을 넣고, ctrl+enter가 실행 후 해당 세션에 연결합니다.

  • /loop의 사용 환경 확대

    스스로 주기를 정하는 dynamic 모드와 프롬프트 없이 실행하는 기본 동작이 일부 환경에서 제한됐습니다. 이제 Bedrock, Vertex, Foundry를 포함해 항상 사용할 수 있습니다.

  • 텔레메트리 오류 로그 구분

    Anthropic 텔레메트리 전송 실패가 [3P telemetry] OTEL diag error로 기록돼, 조직이 운영하는 OTel 수집기의 문제로 오해할 수 있었습니다. 이제 디버그 수준에서 [Anthropic telemetry]로 기록됩니다.

  • 서브에이전트가 보낸 메시지의 응답 경로 안내

    서브에이전트가 다른 세션에 SendMessage를 보내면 답장이 어디로 오는지 알 수 없었습니다. 이제 결과에 답장이 서브에이전트가 아니라 상위 세션의 대화로 전달된다는 점이 함께 표시됩니다.

주요 버그 수정

프롬프트 캐시와 세션 유지

  • 긴 세션에서 한 시간에 한 번꼴로 프롬프트 캐시가 깨지고 확장 사고 맥락이 유실되던 문제 수정. OAuth 토큰 갱신 이후 도구 정의가 다시 렌더링되던 것이 원인이었습니다.
  • 계정이 사용량 초과 상태에 들어간 뒤 ScheduleWakeup 도구 정의가 원래 세션과 --resume 세션에서 달라져, 재개한 세션의 첫 턴에서 캐시가 전부 깨지던 문제 수정.
  • Claude 데스크톱 앱과 Cowork 세션이 30일 뒤 사라지던 문제 수정. 이제 앱에 남아 있는 데스크톱 세션은 정리 대상에서 제외되며(조직 정책이 보관 기간을 관리하는 경우는 예외), desktopSessionCleanupPeriodDays 설정으로 예외 기간에 상한을 둘 수 있습니다.
  • 세션 토큰이 만료된 상태에서 다른 Claude Code 프로세스가 토큰 갱신 잠금을 쥐고 있으면 로그인 화면으로 넘어가던 문제 수정. 이제 다시 시도할 수 있는 오류로 처리됩니다.

에이전트 뷰와 백그라운드 세션

  • 컴퓨터를 껐다 켠 뒤 에이전트 뷰가 몇 주 지난 백그라운드 세션을 되살리던 문제 수정. 이제 실제 종료 시점에 멈춘 것으로 표시되고, 열 때 저장된 대화를 이어갈지 묻습니다.
  • 이미 다른 터미널에서 재개한 세션을 claude agents에서 다시 열면 같은 대화에 두 번째 프로세스가 뜨던 문제 수정. 이제 해당 항목에 터미널에서 열려 있다고 표시됩니다.
  • 새 세션을 시작할 때 에이전트 뷰가 이전 대화를 열고 입력한 프롬프트를 버리던 문제 수정.
  • 작업 트리 브랜치가 체크아웃된 기본 브랜치(예: 로컬 main)에 이미 병합됐지만 아직 푸시되지 않았을 때 claude agents와 claude rm이 “has commits that are not pushed anywhere”라며 세션 삭제를 거부하던 문제 수정.
  • 백그라운드로 보낸 작업 트리 세션이 체크아웃을 잃던 문제 수정. 이제 백그라운드 세션이 실행되는 동안 작업 트리의 잠금을 쥐고 있어, 정리 작업이나 git worktree remove가 건드리지 않습니다.
  • PermissionRequest나 PreToolUse 훅이 형식에 맞지 않는 응답을 출력하면 백그라운드 세션이 아무 표시 없이 멈춰 있던 문제 수정. 이제 claude agents 항목에 어떤 훅에서 어떤 형식 오류가 났는지 표시됩니다.
  • 훅이 표준 출력으로 내보낸 {…} 객체가 올바른 JSON이 아니면 조용히 일반 텍스트로 처리되던 문제 수정. 이제 파싱 오류 메시지와 함께 훅 오류로 보고됩니다.
  • [Windows] 세션에서 빠져나온 뒤나 win32-input-mode가 남은 터미널 탭에서 claude agents 목록이 키보드 입력에 반응하지 않던 문제 수정.
  • CI 환경 변수가 설정되면 claude agents가 작업 공간 신뢰 확인을 건너뛰던 문제 수정.
  • PR 상태 캐시에 잘못된 항목이 있으면 claude agents가 실행 중 종료되던 문제 수정.

로그인, MCP, 설정

  • ANTHROPIC_API_KEY나 API 키 헬퍼가 설정돼 콘솔 로그인을 쓸 수 없는 환경에서 /login이 로그인 URL도 보여주지 못한 채 OAuth 오류로 실패하던 문제 수정. 이제 API 키 로그인으로 넘어갑니다.
  • 관리형 설정의 보안 승인 화면이 필요한 상황에서 Claude apps gateway로의 /login이 멈춰 있던 문제 수정.
  • apiKeyHelper만 자격 증명으로 쓰는 환경에서 게이트웨이 모델 검색(CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY)이 아예 동작하지 않던 문제 수정.
  • 프로젝트 .mcp.json에 claude.ai 커넥터 유형으로 선언된 항목이 /mcp에서 신뢰된 “claude.ai” 항목 아래에 표시되던 문제 수정. 이제 실제 범위 아래에 표시됩니다.
  • headersHelper가 Authorization 헤더를 제공하는 MCP 서버가 401을 받으면 헬퍼를 다시 실행해 재시도하지 않고 OAuth 검색으로 넘어가던 문제 수정.
  • crossSessionInbound 값이 잘못돼도 조용히 무시되던 문제 수정. 이제 경고를 띄우고, 사용자 설정이면 세션 간 메시지를 보류하고 관리형 설정이면 거부합니다.

원격, 클라우드 세션

  • /ultrareview와 로컬에서 시작한 클라우드 세션이 커밋하지 않은 prod.env 계열 파일과 *.tfvars 파일, 자격 증명 파일의 편집기 임시, 백업 사본(예: key.pem.tmp, id_rsa.swo)까지 업로드하던 문제 수정. 이제 이 파일들은 컴퓨터 밖으로 나가지 않습니다.
  • CLI가 조용히 재연결한 뒤 Remote Control 세션이 연결된 기기에 권한 요청이나 최신 메시지를 보여주지 않던 문제 수정.
  • 컨테이너의 세션 자격 증명을 아직 읽을 수 없는 시점에 클라우드 세션이 시작에 실패하던 문제 수정.
  • 전역 플래그나 래퍼가 넣은 옵션이 하위 명령 앞에 오면 claude remote-control이 자기 플래그(예: --spawn, --name)를 거부하던 문제 수정.

터미널과 화면 표시

  • 한국어 IME처럼 라틴 문자가 아닌 방식으로 입력한 이름은 다른 세션을 @로 부를 때 일치하지 않던 문제 수정.
  • claude logs가 실행한 터미널에 마우스 추적, 괄호 붙여넣기, 대체 화면 설정을 켜둔 채 종료되던 문제 수정.
  • /model과 fast mode 전환 안내의 모델 이름이 코드로 표시되지 않아 [1m] 같은 접미사가 링크처럼 보이던 문제 수정.
  • 긴 규칙이 이모지 중간에서 잘리면 신뢰 확인 대화상자의 저장소 권한 규칙 목록에 깨진 문자가 표시되던 문제 수정.
  • ctrl+c 직후 shift+tab을 누르면 권한 모드 표시가 “Press Ctrl-C again to exit” 안내에 가려지던 문제 수정.
  • 시작 시 경고(“N MCP servers need authentication” 등)가 다른 내용보다 한 칸 오른쪽에 표시되던 문제 수정.
  • 조직에서 /usage-credits를 쓸 수 없는데도(예: DISABLE_EXTRA_USAGE_COMMAND로 숨긴 경우) 사용량 한도, 사용량, fast mode 안내가 그 명령을 실행하라고 알려주던 문제 수정.
  • [VSCode] 저장된 적 없는 세션의 채팅 탭이 “No conversation found”에서 멈춰 있던 문제 수정. 이제 새 대화를 시작합니다.

알아두면 좋은 점

  • --restricted는 설정 파일도 무시합니다 — 도구 제한뿐 아니라 사용자, 프로젝트, 로컬 설정 파일을 읽지 않고 bypassPermissions를 거부합니다. 평소 설정에 의존하는 작업이라면 동작이 달라집니다.
  • 데스크톱 세션의 보관 정책이 바뀌었습니다 — Claude 데스크톱 앱과 Cowork에서 만든 세션은 앱에 남아 있는 동안 30일 정리 대상에서 빠집니다. 예외 기간의 상한은 desktopSessionCleanupPeriodDays로 정하고, 조직 정책이 보관 기간을 관리하면 그 정책이 우선합니다.
  • 클라우드로 올라가는 파일에서 자격 증명 사본이 제외됩니다 — /ultrareview와 로컬에서 시작한 클라우드 세션은 prod.env 계열, *.tfvars, 그리고 key.pem.tmp, id_rsa.swo 같은 편집기 임시, 백업 파일을 더 이상 업로드하지 않습니다.
  • 에이전트 뷰에서 shift+enter 동작이 바뀌었습니다 — 이제 shift+enter는 줄바꿈이고, 실행하려면 ctrl+enter를 누릅니다.
  • Workflow 도구 참고 자료의 위치가 바뀌었습니다 — 스크립트 작성 방법은 도구 설명이 아니라 workflow-authoring 스킬에 들어 있습니다.
  • crossSessionInbound 값이 잘못되면 그냥 넘어가지 않습니다 — 사용자 설정이면 세션 간 메시지가 보류되고, 관리형 설정이면 거부됩니다. 값을 고칠 때까지 이 상태가 유지됩니다.