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

Claude Code 2.1.287

플러그인이 더 깊은 동작까지 바꿀 수 있는 Claude Mods와, 보조 에이전트가 사용자나 Claude가 놓칠 수 있는 부분을 짚어 주는 내장 모드 You should know가 추가됐습니다. Bedrock, Vertex, Foundry에서 Opus 4.7 이상과 Fable이 기본으로 1M 컨텍스트 창을 쓰고, `alwaysLoad: false`인 MCP 서버의 도구는 모두 도구 검색 뒤로 미뤄집니다. 수정은 화면 낭독기 모드, Remote Control과 클라우드 세션의 파일 전송, MCP, 권한 안전장치에 집중됐습니다.

Claude Code
공식 발표 →

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

무엇이 바뀌었나?

Claude Code 2.1.287이 2026년 10월 1일 출시됐습니다. 플러그인이 Claude Code의 더 깊은 동작을 바꿀 수 있는 Claude Mods가 도입됐고, 첫 내장 모드로 You should know가 함께 나왔습니다. 동작 변경으로는 Bedrock, Vertex, Foundry, Claude apps 게이트웨이의 1M 컨텍스트 기본 적용, MCP 서버의 alwaysLoad: false 의미 확대, 위험한 셸 쓰기에 대한 확인 강화가 있습니다. 수정 사항은 화면 낭독기(screen reader) 모드, Remote Control과 클라우드 세션의 파일 전송, MCP 연결, 모델 전환, 권한 안전장치에 많이 모였습니다.

새 기능

  • Claude Mods

    플러그인이 Claude Code의 더 깊은 동작까지 바꿀 수 있게 됐습니다. 릴리스 노트에는 이 한 줄 외의 세부 내용이 없으며, 첫 내장 모드로 아래 You should know가 함께 제공됩니다.

  • 내장 모드 You should know

    작업에 집중하다 보면 사용자도 Claude도 놓치는 부분이 생깁니다. You should know를 켜면 보조 에이전트(side agent)가 작업을 지켜보다가 놓칠 수 있는 부분을 짚어 줍니다. /plugin enable cc-plugin-you-should-know@builtin으로 켜며, 텔레메트리가 켜진 first-party(Bedrock, Vertex 등을 거치지 않고 Anthropic에 직접 연결한) 세션에서 사용할 수 있습니다.

  • 에이전트 화면의 n:<text> 필터

    claude agents 화면에서 원하는 세션을 찾으려면 목록을 직접 훑어야 했습니다. 이제 n:<text>로 세션 이름과 작업을 검색할 수 있습니다. 필터를 쓰면 접힌 섹션 안의 일치 항목도 보이고, Enter를 누르면 첫 번째 일치 항목이 열립니다.

  • MCP 서버의 URL 요청 지원

    2025-11-25 프로토콜을 쓰는 MCP 서버가 로그인처럼 URL을 열어야 하는 요청을 보낼 수 있게 됐습니다. 업데이트 후 서버가 연결되지 않으면 해당 MCP 설정 항목에 "bareElicitationCapability": true를 추가합니다.

  • OpenTelemetry user_prompt 이벤트의 prompt_text

    점(.)이 들어간 키를 중첩 구조로 바꾸는 백엔드에서는 prompt 값을 다루기 어려웠습니다. prompt의 복사본인 prompt_text가 추가됐습니다. prompt를 버리거나 가리는 곳에서는 prompt_text도 똑같이 처리해야 합니다.

  • self-hosted runner의 내장 gh api

    GitHub CLI가 설치되지 않은 macOS, Linux 머신에서 Anthropic이 관리하는 git을 쓰는 세션은 GitHub API를 호출할 수 없었습니다. 이제 내장 gh api(REST 전용)를 쓸 수 있습니다.

  • [Windows] 셸 도구가 없어지는 설정 경고

    Bash 도구를 거부하면 PowerShell 도구도 함께 꺼져 Claude가 쓸 수 있는 셸 도구가 하나도 남지 않는데, 이를 알 방법이 없었습니다. 이제 시작할 때 경고가 표시됩니다.

  • [VSCode] 기능 추가

    • 실행 중인 명령이나 서브에이전트에 “Run in background”가 추가돼, 백그라운드로 옮기고 다른 작업을 이어 갈 수 있습니다.
    • 에이전트 맵의 백그라운드 셸, Monitor 카드에 출력이 표시됩니다.

주요 개선

  • /config 조작 방식

    값을 순환하는 설정은 한 방향으로만 넘길 수 있었고, 좁은 터미널에서는 값이 잘 보이지 않았습니다. 이제 순환 설정에 ‹ ›가 표시되고 ←/→로 양방향 이동하며, 좁은 터미널에서는 값이 이름 아래에 표시됩니다. PgUp/PgDn으로 목록을 페이지 단위로 넘길 수 있습니다.

  • 플러그인 마켓플레이스 오류와 의존성 안내

    마켓플레이스가 무시되거나 거부된 이유를 오류에서 알기 어려웠습니다. 이제 이유와 해결 방법을 쉬운 말로 알려 줍니다. 플러그인 목록은 의존성이 설치되지 않은 경우를 표시하고, 플러그인을 업데이트하면 끝나지 않은 설치를 다시 시도합니다.

  • 클라우드 세션과 Remote Control의 파일 전송

    Claude가 보내는 파일이 일시적인 오류로 실패해도 그대로 끝났고, 큰 파일은 메모리에 통째로 올라갔습니다. 이제 시간 초과, 네트워크 오류, 502, 503, 504 응답으로 실패한 업로드를 한 번 재시도합니다. 큰 파일은 디스크에서 스트리밍되며, 크기 제한을 넘는 파일은 서버의 제한값을 밝히며 거부됩니다. 일시적인 이유로 보내지 못하면 몇 분 뒤 다시 요청할 수 있다고 안내하고, 서버가 파일을 거부한 경우(큰 이미지 등)에도 이유를 설명합니다.

  • 큰 MCP 도구 결과 처리

    큰 MCP 도구 결과가 메모리와 세션 파일 크기를 키웠습니다. 이제 메모리 사용과 세션 파일이 줄었고, 한도를 크게 넘는 결과는 토큰 수를 세기 위한 추가 업로드를 하지 않습니다.

  • headless 모드의 MCP 시작

    원격 서버의 첫 연결이 일시적으로 실패하면 가장 느린 서버가 연결을 마칠 때까지 기다린 뒤에야 재시도했습니다. 이제 기다리지 않고 바로 재시도합니다.

  • SDK 세션의 priority “now” 메시지

    priority “now”로 보낸 메시지가 실행 중인 웹 가져오기(web fetch)나 웹 검색을 취소했습니다. 이제 이 작업들은 백그라운드에서 계속 진행됩니다.

  • 메시지 중간에 입력한 /skill 이름

    메시지 중간에 /스킬이름을 입력해도 Claude가 이를 스킬로 인식하지 못할 수 있었습니다. 이제 Claude에게 스킬이라고 알려 주며, disable-model-invocation 스킬도 포함됩니다.

  • [Windows] Bash 도구 속도

    모든 명령 앞에 실행되던 서브셸을 없애 Bash 도구가 빨라졌습니다.

  • 기타 개선

    • /memory에서 ←/→ 키로 Auto-memory 같은 켜기/끄기 설정을 바꿀 수 있습니다.
    • 밝은 테마에서 프롬프트 입력 테두리와 이전 메시지 앞 ❯의 대비가 높아졌습니다.
    • 다른 세션에서 보류된 메시지를 확인하는 창, MCP와 기타 도구의 권한 확인 창이 파일 편집 확인 창처럼 내용을 점선 사이에 표시합니다.
    • Amazon Bedrock이 모델 ID를 거부하면 Claude apps 게이트웨이 오류가 어떤 모델을 쓸 수 없는지 알려 주고, 게이트웨이 로그에 전송된 ID가 남습니다.
    • [VSCode] Manage plugins 창에서 마켓플레이스 추가, 제거, 새로 고침이 실패하면 원인을 알려 줍니다.
    • [Claude Tag] 긴 Slack 스레드에서 백그라운드 작업이 작업 목록을 새 메시지로 다시 올리지 않아, 스레드를 구독한 사람에게 알림이 가지 않습니다.
    • [Code Review] 대화가 잠긴 pull request에서 리뷰가 실패하면, 잠금 때문에 리뷰가 막혔고 아무것도 게시되거나 청구되지 않았다고 알려 줍니다.

동작이 바뀐 항목

  • Opus 4.7 이상과 Fable의 1M 컨텍스트 기본 적용 (변경)

    Bedrock, Vertex, Foundry, Claude apps 게이트웨이에서 1M 컨텍스트 창을 쓰려면 모델 이름에 [1m] 접미사를 붙여야 했습니다. 이제 Opus 4.7 이상과 Fable은 접미사 없이 기본으로 1M 컨텍스트 창을 씁니다. 200K를 유지하려면 CLAUDE_CODE_DISABLE_1M_CONTEXT=1을 설정합니다.

  • MCP 서버 alwaysLoad: false (변경)

    alwaysLoad: false로 설정한 MCP 서버의 도구는 이제 모두 도구 검색(tool search) 뒤로 미뤄집니다.

  • 위험한 셸 쓰기의 확인 강화 (변경)

    • 저장소에 커밋된 심볼릭 링크를 거쳐 민감한 파일이나 작업 트리 밖으로 쓰는 셸 명령은 실제로 기록되는 위치를 밝히고 사람의 승인을 기다립니다. ~ 대상이 있는 줄에도 적용됩니다.
    • Bash 전체를 허용하는 규칙이나 허용하는 훅이 있어도, Claude Code의 파일 도구가 아예 거부하는 파일(Anthropic 프로필 저장소, 호스트 인증 정보 파일)에 대한 셸 쓰기는 바로 실행하지 않고 확인을 요청합니다.

  • claude agents의 답장과 슬래시 명령 (변경)

    claude agents에서 보낸 답장이 대기열 메시지로 전달됩니다. 턴이 실행 중일 때 보낸 슬래시 명령은 /stop을 제외하고 턴이 끝난 뒤 실행됩니다.

  • 권한 확인 창 순서 (변경)

    새 권한 요청이 지금 읽고 있는 요청을 덮었습니다. 이제 대기 중인 요청은 오래된 것부터 표시됩니다. 카운트다운이 있는 요청은 여전히 맨 위에 열립니다.

  • 자동 모델 전환 시 effort 수준 유지 (변경)

    메시지가 플래그된 뒤 모델이 자동으로 바뀌면 새 모델의 기본 effort 수준이 적용됐습니다. 이제 현재 effort 수준을 유지합니다.

  • 기타 동작 변경

    • Windows, Linux의 오른쪽 클릭 붙여넣기와 Linux의 가운데 클릭 붙여넣기가 버튼을 뗄 때 실행됩니다. 떼기 전에 포인터를 다른 곳으로 옮기면 취소됩니다.
    • 화면 낭독기 모드에서 새 줄이나 바뀐 줄을 쓸 때 커서를 줄 앞에 두고 잠시 멈추지 않습니다. 이전처럼 멈추게 하려면 CLAUDE_AX_PREPARK_MS=50을 설정합니다.
    • [VSCode] Claude in Chrome의 “Enabled by default” 스위치가 편집기 자체 세션도 연결합니다. 브라우저 동작 전에는 여전히 확인을 요청합니다.

주요 버그 수정

권한과 보안

  • /나 홈 디렉터리에 대한 rm 같은 위험한 명령이 출력을 ~나 와일드카드 경로로 리디렉션하면 항상 확인하는 안전장치가 사라지던 문제 수정.
  • 이름이 __proto__인 MCP 도구에 조직의 도구별 권한 상한이 조용히 적용되지 않던 문제 수정.
  • Bash 권한 확인 창이 쉬운 설명 대신 “Contains simple_expansion” 같은 내부 파서 이름을 표시하던 문제 수정.
  • Linux에서 샌드박스로 실행한 Bash 명령이 Claude Code 실행 파일에 대한 열린 핸들을 물려받던 문제 수정.
  • 취소된 claude.ai 로그인이 “OAuth token revoked” 대신 일반적인 API Error: 401로 표시되던 문제 수정. -p 모드에서는 오류가 “Failed to authenticate”로 시작합니다.

모델과 컨텍스트

  • claude.ai 로그인에서 /model로 Fable을 고르면 현재 버전의 id가 저장되던 문제 수정. 이제 Opus, Sonnet처럼 저장된 기본값이 최신 Fable을 따라갑니다.
  • Opus 5.5와 Sonnet 5.5 사이를 전환하면(/model, opusplan) 이전 MCP 도구 안내가 다시 쓰이면서 이전 확장 사고(extended thinking)가 빠질 수 있던 문제 수정.
  • 답변이 실행 중일 때 모델을 바꾸면 claude -p와 SDK 세션이 이후 모든 메시지에서 모델 대체를 반복하던 문제 수정.
  • Bedrock, Vertex의 시작 시 모델 확인이 강제된 availableModels 목록을 무시해 /model이 Opus 한 줄로 줄어들 수 있던 문제 수정.
  • 답변이 thinking으로 시작한 경우, 응답 도중 도착한 Amazon Bedrock Guardrails 차단이 가드레일 메시지 대신 API 오류로 턴을 끝내던 문제 수정.
  • /advisor 짝 확인 문제 수정. Sonnet 5.5가 Opus 4.7, 4.8의 advisor가 될 수 있고, API가 거부할 advisor 조합은 조용히 빠지지 않고 미리 표시됩니다.
  • 사용자 계정 없이 에이전트가 소유한 원격 세션에서, 조직이 허용해도 fast mode가 꺼진 채로 남던 문제 수정.
  • 세션을 재개하거나 압축(compaction)한 뒤 폴더의 CLAUDE.md가 한 번 더 첨부되던 문제 수정.
  • 압축 뒤 커밋 작성자 표기 안내가 도구 결과 안에 전달되던 문제 수정.
  • CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS가 세션 제목, 프롬프트 훅 요청에서 구조화된 출력 형식을 빼지 않아 Bedrock 기반 게이트웨이가 거부하던 문제 수정.
  • [Bedrock, Vertex, Mantle] ANTHROPIC_CUSTOM_HEADERS가 Authorization 헤더를 반복하면 CLAUDE_CODE_SKIP_*_AUTH에서의 모델 가용성 확인이 실제 요청과 다른 헤더를 보내던 문제 수정.

Remote Control과 클라우드 세션

  • 재연결 요청에 응답이 없으면 Remote Control이 몇 분 동안 메시지를 받지 못하던 문제 수정. 이제 30초 뒤 포기하고 다시 시도합니다.
  • HTTP 프록시 뒤에서 claude remote-control이 “Check your organization permissions”라는 잘못된 오류와 함께 등록에 실패하던 문제 수정.
  • [macOS] Mac이 유휴 잠자기에 들어가면 claude remote-control로 시작한 세션이 턴 도중 멈추던 문제 수정.
  • 클라우드, Remote Control 세션에서 Claude가 보낸 파일의 업로드가 30초 제한 직후에 끝나면 실패하던 문제 수정. 이제 35초까지 기다립니다.
  • 한 변이 8,000픽셀을 넘는 PNG, JPEG, WebP 이미지를 원격 세션에서 보내지 못하던 문제 수정. 축소한 사본을 보냅니다.
  • Claude 앱에서 파일 17-20개를 첨부해 보낸 메시지가 처음 16개만 전달하던 문제 수정.
  • 압축 중에 세션이 다시 시작되면 클라우드 세션이 이전 대화를 잃던 문제 수정.
  • 클라우드, SDK 세션에서 도중에 추가한 저장소의 스킬과 플러그인이 불러와지지 않고, CLAUDE.md가 Claude가 디렉터리를 옮긴 뒤에야 늦게 불러와지던 문제 수정.
  • 동기화된 플러그인의 SessionStart 훅이 새 클라우드 세션에서 실행되지 않던 문제 수정.
  • 시작 시 --plugin-url 다운로드와 플러그인 다시 불러오기가 겹치면 세션에 캐시된 플러그인 압축 파일이 손상되던 문제 수정.
  • [Cloud sessions] 새로 발급한 액세스 토큰을 GitHub가 잠시 거부하면 GitHub에서 가져오기나 푸시가 가끔 실패하던 문제 수정.

MCP와 플러그인

  • 서버가 지원하는 MCP 프로토콜 버전을 바꾸면 MCP 커넥터 도구 호출이 가끔 두 번 실행되거나, 재시작할 때까지 커넥터 호출이 실패하던 문제 수정.
  • headless 세션에서 호출이 한 번 거부되면, 이후 호출은 성공하는데도 MCP 서버를 인증이 필요한 상태로 보고하던 문제 수정.
  • JSON으로 저장된 큰 MCP 결과를 Read의 offset과 limit으로 나눠 읽으라고 Claude에게 안내하던 문제 수정. offset과 limit으로는 긴 한 줄을 나눌 수 없습니다.
  • 저장소가 일반 http로 제공되면 claude plugin marketplace add --sparse와 git-subdir 플러그인 설치가 “transport ‘http’ not allowed”로 실패하던 문제 수정.

훅, 스킬, SDK

  • asyncRewake로 설정한 훅의 스크립트 파일이 없으면 “found issues” 알림으로 Claude를 계속 깨우던 문제 수정. 이제 고장 난 훅을 한 번만 보고합니다.
  • transcript의 “N hooks ran” 요약과 상세 디버그 로그의 일치 훅 수가 Claude Code 내부 콜백까지 세던 문제 수정. 설정한 훅 하나가 두 개로 표시되지 않습니다.
  • /<skill>을 프롬프트로 입력해 context: fork 스킬을 실행하면 --output-format stream-json과 SDK가 해당 턴을 스트리밍하지 않던 문제 수정. Skill 도구의 fork와 똑같이 동작합니다.
  • 모델의 응답 스트림이 데이터 없이 멈춘 동안 도구 heartbeat가 SDK 호스트에 전달되지 않던 문제 수정.
  • --include-partial-messages가 중간에 끊긴 답변의 message_stop을 늦게 보내거나 보내지 않아, 앱이 답변을 계속 진행 중으로 표시할 수 있던 문제 수정.

에이전트 화면과 백그라운드 세션

  • 에이전트가 종료되며 세션을 시작한 worktree를 지운 뒤 claude agents에서 백그라운드 세션을 다시 열 수 없던 문제 수정.
  • claude agents가 백그라운드 세션이 기다리는 권한 확인 창을 가끔 표시하지 않던 문제 수정.

화면 낭독기 모드와 접근성

  • 검색 상자(/resume, /permissions 등)와 로그인 코드 입력란에서 커서가 입력한 글자와 떨어진 곳에 남던 문제 수정.
  • /rewind의 요약 옵션에서 아무것도 입력하지 않으면 Enter를 거부하던 문제 수정. 덧붙이는 내용은 선택 사항입니다.
  • Tab이 아무 동작도 하지 않는 승인 창에 “Tab to amend” 안내가 표시되던 문제 수정.
  • /permissions, /mcp에서 동작하지 않는 화살표 키를 안내하고, 빈 메뉴나 검색 상자가 키를 받는 중에도 “Select with numbers”라고 읽던 문제 수정.
  • 파일 편집 승인 창과 다른 diff에서 바뀐 줄이 빠지던 문제 수정.
  • claude --teleport 진행 화면과 확인 중인 MCP 양식 입력란을 스피너가 돌 때마다 화면 낭독기에 다시 보내던 문제 수정.
  • 이전 화면이 터미널 창보다 길면 두 번째 승인 창, 바뀐 /config 행, 거부된 계획 줄의 윗부분이 빠지던 문제 수정.
  • claude agents의 시간이 매초 바뀌던 문제 수정. 이제 최대 10초마다 바뀝니다.
  • “Reduce motion” 설정을 켜도 실행 중인 도구 점과 스피너 세 개가 움직이고, /rewind 확인 화면의 “ago” 시간이 메모 입력 중에 바뀌던 문제 수정.

기타

  • Chrome에 연결할 수 없을 때 Claude in Chrome 브라우저 선택 화면에 JSON 파싱 오류가 표시되던 문제 수정.
  • 느리거나 바쁜 머신에서 긴 대화 중 스크롤 키를 누르고 있으면 전체 화면 세션이 “Claude Code exited after an unrecoverable interface error”와 함께 종료되던 원인 하나 수정.
  • /feedback, /bug로 미리 채운 GitHub 이슈에 최근 오류 메시지가 들어가던 문제 수정. 이제 확인 화면에서 보고서에 포함되는 항목으로 보여 줍니다.
  • /ultrareview 업로드가 읽을 수 없는 커밋된 .gitattributes(UTF-16으로 저장된 파일 등)에서 멈추면 .git/info/attributes에 대한 안내를 하던 문제, 업로드 거부 시 저장소 설정 파일이 지정한 변수를 사용자 설정에 복사하라고 안내하던 문제 수정.
  • Claude Desktop 열기가 시간 초과되거나 출력이 너무 많을 때 /desktop이 출력 일부를 인용하던 문제 수정. 이제 원인을 밝힙니다.
  • [Windows] 입력이 파이프나 리디렉션으로 들어오면 대화형 claude가 “Raw mode is not supported”와 함께 멈추거나 비정상 종료되던 문제 수정. 이제 이유를 알리고 종료합니다. 파이프 입력에는 -p를 사용합니다.

[VSCode]

  • Claude Code의 응답이 너무 커서 저장을 확인할 수 없을 때 설정 창이 시간 초과를 원인으로 표시하던 문제 수정.
  • 사이드바가 이미 이 머신으로 가져온 클라우드 세션을 다시 열면 새 탭에서 한 번 더 열리던 문제 수정. 사이드바가 표시됩니다.
  • 사이드바의 Web 탭이 창이 열린 뒤 시작한 클라우드 세션을 보여 주지 않던 문제 수정. 불러오기에 실패하면 “No web sessions yet” 대신 “Remote server is not connected”가 표시됩니다.
  • 새로 고침 후 복원된 탭이 사이드바에 이미 열린 대화에 대해 두 번째 Claude 프로세스를 시작하던 문제 수정. “still open somewhere else” 안내가 표시됩니다.
  • 도구 행의 파일 링크, 세션 목록 링크, 안내 두 개가 일반 텍스트로 표시되던 문제 수정.
  • 메인 턴이 끝나면 백그라운드 에이전트의 실행 중인 명령이 실패로 표시되던 문제 수정.
  • 명령 메뉴에서 사용자 자신의 /usage, /context 명령을 고르면 실행되지 않고 확장 대화 상자가 열리던 문제 수정.
  • 계획 미리보기 탭의 파일 링크를 클릭해도 아무 일이 없던 문제 수정.
  • WSL 같은 원격 호스트에서 도구 입출력을 편집기 탭으로 열면 “Timeout waiting after 1000ms”로 실패하던 문제 수정.

[Claude Tag]

  • GitHub 활동 같은 백그라운드 이벤트가 Claude를 깨웠을 때, 아무도 답을 기다리지 않는데 Slack 스레드에 지출 한도 알림 같은 실패 경고를 올리던 문제 수정.
  • 채널이 많은 조직에서 관리자 설정의 지출 한도 페이지에 최근 만든 채널과 비공개 채널이 빠지던 문제 수정.

[Code Review]

  • 발견 코멘트와 “Why this was flagged” 설명이 문장 중간에 끊기던 문제 수정.
  • 이전 커밋에서 리뷰가 두 번 실패한 pull request에 새로 푸시해도 Code Review가 건너뛰던 문제 수정. 이제 최신 커밋을 리뷰합니다.

알아두면 좋은 점

  • You should know는 직접 켜야 합니다 — /plugin enable cc-plugin-you-should-know@builtin으로 켜며, 텔레메트리가 켜진 first-party 세션에서만 사용할 수 있습니다.
  • Bedrock, Vertex, Foundry, Claude apps 게이트웨이에서 Opus 4.7 이상과 Fable은 기본으로 1M 컨텍스트 창을 씁니다 — 200K를 유지하려면 CLAUDE_CODE_DISABLE_1M_CONTEXT=1을 설정합니다.
  • 업데이트 후 연결되지 않는 MCP 서버가 있으면 해당 MCP 설정 항목에 "bareElicitationCapability": true를 추가합니다.
  • alwaysLoad: false인 MCP 서버의 도구는 모두 도구 검색 뒤로 미뤄집니다.
  • OpenTelemetry로 프롬프트를 수집한다면 prompt_text도 확인합니다 — prompt를 버리거나 가리는 곳에서 새 prompt_text도 똑같이 처리해야 프롬프트 내용이 남지 않습니다.
  • 턴 실행 중 보낸 슬래시 명령은 /stop을 제외하고 턴이 끝난 뒤 실행됩니다.