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

Claude Code 2.1.296

Read 도구에 큰 텍스트 파일을 한 번에 읽는 `allow_large` 옵션이, 서브에이전트에 `autoCompactWindow`가 추가됐습니다. UTF-8이 아닌 파일을 Edit, NotebookEdit로 고치면 ASCII가 아닌 문자가 모두 바뀌던 문제, 관리형 설정의 훅이 도구 호출을 거부해도 턴이 끝나지 않던 문제가 고쳐졌고, MCP 도구 설명의 기본 길이 제한이 2,048자에서 4,096자로 늘었습니다.

공식 발표 →

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

무엇이 바뀌었나?

Claude Code 2.1.296이 2026년 10월 9일 출시됐습니다. Read 도구의 큰 파일 읽기 옵션, 서브에이전트별 자동 압축 기준, workflow 에이전트 모델을 지정하는 환경 변수가 추가됐습니다. 수정은 관리형 설정의 훅, UTF-8이 아닌 파일 편집, 백그라운드 전환(←), Windows의 PowerShell과 플러그인 설치에 집중돼 있고, 2.1.295에서 생긴 게이트웨이 로그인 문제도 고쳐졌습니다. 아래에는 사용자 영향이 큰 항목을 골라 정리했습니다.

새 기능

  • Read 도구의 allow_large 옵션

    Read 도구에는 크기 제한이 있어, 큰 텍스트 파일은 한 번의 호출로 전부 읽을 수 없었습니다. 이제 파일 전체가 필요하고 컨텍스트에 여유가 있으면 Claude가 allow_large 옵션으로 평소 제한을 넘는 텍스트 파일을 한 번에 읽을 수 있습니다.

  • 서브에이전트의 autoCompactWindow

    서브에이전트의 자동 압축은 메인 대화의 컨텍스트 크기 기준을 따랐습니다. 이제 서브에이전트 frontmatter와 --agents 정의에 autoCompactWindow를 지정해, 서브에이전트가 메인 대화보다 일찍 자동 압축하도록 설정할 수 있습니다.

  • CLAUDE_CODE_WORKFLOW_SUBAGENT_MODEL

    모든 workflow 에이전트를 하나의 모델로 실행하는 환경 변수가 추가됐습니다. 다른 서브에이전트는 각자의 모델을 그대로 사용합니다.

  • CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS

    과부하(529) 요청을 재시도할 때 대기 간격의 최댓값을 더 길게 설정할 수 있는 환경 변수가 추가됐습니다.

  • Claude 앱 게이트웨이 managed.policies[]의 code 키

    cli와 같은 설정을 담으며 Claude Desktop의 Code 탭에도 적용됩니다. desktop과 함께 쓰면 Claude Desktop의 게이트웨이 모드를 켭니다.

  • 이름이 겹치는 플러그인의 훅 누락 안내

    활성화된 다른 플러그인과 이름이 같아 훅이 제외된 플러그인은 그 사실을 확인할 방법이 없었습니다. 이제 /plugin에서 해당 플러그인에 안내가 표시됩니다.

  • [Cloud sessions] 자체 호스팅 환경 Activity 탭의 상태 필터

    관리자 설정의 Sessions, Runners 목록에 상태 필터가 추가됐습니다. 여러 상태를 동시에 고를 수 있습니다.

  • [Claude Tag] Memory 탭의 메모리 파일 관리

    Claude Tag Admin 권한이 있는 구성원은 Activity 페이지의 Memory 탭에서 워크스페이스, 채널 메모리 파일을 만들고, 고치고, 삭제할 수 있습니다.

주요 개선

  • --debug 출력의 훅 실행 기록

    어느 훅이 느린지 찾기 어려웠습니다. 이제 도구 호출, 프롬프트, SessionStart, Stop의 명령 훅이 끝날 때 명령, 플러그인, 결과, 소요 시간을 기록해 느린 훅을 가려낼 수 있습니다. 사용자 정의 에이전트 파일의 인식되지 않는 frontmatter 필드도 알려 주고, 오타로 보이면 힌트를 덧붙입니다.

  • auto mode의 실행되지 않은 도구 호출 표시

    auto mode의 검사가 쓸 수 있는 답을 내지 못해 실행되지 않은 도구 호출이 빨간 오류로 표시됐습니다. 이제 흐린 “Not run” 행으로 표시됩니다.

  • 대화 기록 전환(ctrl+o) 반응 속도

    코드가 많은 대화에서 대화 기록 전환이 느렸습니다. 구문 강조된 코드 블록을 캐시해 반응이 빨라졌습니다.

  • 전체 화면 모드의 링크 표시

    마우스 포인터 아래의 링크에 밑줄이 그어져, 열 수 있는 링크임을 알 수 있습니다.

  • 거부된 클라우드 세션의 오류 메시지

    조직의 정책을 불러오지 못한 이유를 알려 주고, claude.ai 로그인보다 우선 적용되는 API 키나 인증 토큰이 있으면 그 이름을 알려 줍니다.

  • 게이트웨이 환경의 Claude Desktop Code 탭

    Claude 앱 게이트웨이 환경에서 세션을 시작하지 못하면 이유가 답변으로 표시됩니다. 게이트웨이의 code 설정이 준비되지 않은 기기도 포함됩니다.

  • CLAUDE_CODE_TRANSCRIPT_LOCAL_GC의 불필요한 재작성 생략

    큰 대화 기록 파일은 다시 써도 확보되는 공간이 10% 미만이면 더 이상 다시 쓰지 않습니다.

동작이 바뀐 항목

  • MCP 도구 설명과 서버 지침의 기본 길이 제한 (변경)

    처음부터 전송되는 MCP 도구 설명과 MCP 서버 지침의 기본 제한이 2,048자에서 4,096자로 늘었습니다.

  • ← 전환 중 시작된 턴 (변경)

    세션이 백그라운드로 이동하는 동안 시작된 턴이나 ! 명령은 보이지 않는 곳에서 끝까지 실행됐습니다. 이제 중단됩니다.

  • Sonnet 5.5 캐시 읽기 가격 (변경)

    /cost, 상태 줄, --max-budget-usd, SDK의 비용 수치가 Sonnet 5.5 캐시 읽기를 100만 토큰당 $0.10로 계산합니다. 이전에는 $0.20였습니다.

  • [VSCode] Claude in Chrome의 브라우저 동작 확인 (변경)

    @browser로 연결한 세션을 포함해 모든 세션에서, 터미널과 마찬가지로 브라우저 동작 전에 묻습니다. 세션 동안 사이트를 허용하면 다시 묻지 않습니다.

  • [Claude Tag] Slack 답변의 하단 정보 (변경)

    세션 링크, 모델, 비용이 담긴 하단 정보가 스레드의 가장 최근 답변에만 표시됩니다. 그 앞 답변에서는 사라집니다.

주요 버그 수정

훅

  • 관리형 설정의 PreToolUse 훅이 "continue": false로 도구 호출을 거부하거나 관리형 prompt 훅이 호출을 막을 때, 호출만 거부되고 턴은 끝나지 않던 문제 수정.
  • 관리형 설정의 PostToolUse 훅이 일부 세션에서 updatedMCPToolOutput을 적용하지 않던 문제 수정.
  • UserPromptSubmit 훅이나 mod의 prompt.submit 훅 실행 중 Esc나 중단을 하면 헤드리스(대화형 화면 없이 claude -p 등으로 실행하는) 세션이 끝나거나, 입력한 프롬프트가 지워지거나, 검사되지 않은 프롬프트가 통과되던 문제 수정.
  • 훅 출력에 플러그인 힌트 태그와 비슷한 텍스트가 있으면 출력이 바뀌던 문제 수정.
  • 훅이 CLAUDE_ENV_FILE에 쓴 변수를 PowerShell 명령이 보지 못하던 문제 수정. 파일에 단순 대입문만 있을 때 적용됩니다.
  • 헤드리스 세션 시작 뒤에 불러온 플러그인의 SessionStart 훅이, 이름이 같거나 표기만 다른 플러그인이 이미 실행됐으면 건너뛰어지던 문제 수정.

파일 편집과 권한

  • 유효한 UTF-8이 아닌 파일(Windows-1252, Shift-JIS, GBK)에서 Edit, NotebookEdit가 ASCII가 아닌 문자를 모두 바꿔 버리던 문제 수정. 이런 편집은 이제 거부됩니다.
  • BASH_ARGV0 셸 변수에 값을 대입한 뒤 사용하는 일부 명령을 Bash 권한 검사가 자동 승인하던 문제 수정. 이제 승인을 묻습니다.
  • 공유 대화 기록과 디버그 로그의 비밀 값 가리기가, 값 없는 키 뒤에 오는 일부 값을 놓치던 문제 수정. 셸 문자열 안에 쓴 JSON도 해당됩니다.
  • 클라우드 세션에서 기능 플래그가 불러와지지 않았을 때, 저장된 권한이 허용하는 Claude in Chrome 동작에 대해 auto mode 검사를 건너뛰던 문제 수정.
  • auto mode가 공유 설정이 바뀌지 않았는데도 바뀌었다며 자신의 artifact 업데이트를 가끔 거부하던 문제 수정.

백그라운드 전환(←)과 세션

  • 백그라운드 서비스의 응답이 느릴 때 ← 직후 보낸 프롬프트가 두 번 실행되던 문제 수정. 한 번은 포그라운드에서 보이지 않게 실행됐습니다.
  • SessionStart 훅이 실행 중일 때 보낸 프롬프트가 ←로 세션을 백그라운드로 보내면 사라지던 문제 수정. 여전히 전송되지는 않지만 이제 ↑로 되찾을 수 있습니다.
  • 세션 기록을 읽지 못했을 때 --teleport가 빈 대화를 열던 문제 수정.
  • 세션 종료로 중단된 도구 호출을, 재개된 서브에이전트에게 사용자가 거부했다고 알리던 문제 수정.
  • CLAUDE_CODE_RESUME_INTERRUPTED_TURN이 MCP 도구 결과로 끝난 턴을 재시작 뒤 다시 실행하던 문제 수정.
  • /diff 패널이나 대화 상자가 열려 있는 동안 토스트와 알림이 보이지 않은 채 기다리던 문제 수정.

모델, MCP, 게이트웨이

  • Haiku 5.5처럼 adaptive thinking(모델이 사고 분량을 스스로 정하는 방식)만 받는 모델의 토큰 수 계산이 일부 게이트웨이에서 실패하고, 다른 곳에서는 budget thinking(사고 분량을 미리 지정하는 방식) 기준으로 계산되던 문제 수정.
  • 헤드리스 세션이 디렉터리를 바꾸거나 플러그인을 다시 불러온 뒤, 그 폴더에서 꺼 둔 .mcp.json 서버나 플러그인 MCP 서버를 시작하던 문제 수정.
  • 관리형 설정이 forceLoginGatewayUrl 없이 forceLoginMethod를 gateway로 지정한 기기에서, 저장된 Claude 앱 게이트웨이 로그인이 무시되던 문제 수정. 2.1.295에서 생긴 문제입니다.
  • allowedProviders에 "gateway"를 넣어 제공하는 Claude 앱 게이트웨이가, 사용자 설정에 그 게이트웨이를 지정한 노트북의 접속을 막던 문제 수정.
  • MCP 서버에 인증이 필요할 때 Claude가 클라우드 세션을 비대화형이라고 부르며 /mcp나 claude mcp를 제안하던 문제 수정.

플러그인, mod, workflow

  • 여러 세션이 설정 디렉터리를 함께 쓸 때 claude.ai에서 동기화한 스킬이 설치를 끝내지 못하고 동기화할 때마다 다시 내려받던 문제 수정.
  • claude.ai에서 동기화한 플러그인이, 선언한 마켓플레이스 의존성도 claude.ai에서 동기화된 경우 비활성화되던 문제 수정.
  • Linux 기기에서 복사한 플러그인 경로가 /home 아래를 가리키면 macOS에서 시작할 때 멈추던 문제 수정.
  • constructor 같은 이름의 마켓플레이스에서 claude plugin marketplace add, marketplace update, plugin install이 내부 오류로 실패하던 문제 수정. 이제 add가 이런 이름을 거부하고 이유를 알려 줍니다.
  • 플러그인이 제공하는 $ 메서드가 호출한 에이전트가 아니라 메인 세션의 작업 디렉터리에서 실행되던 문제 수정.
  • Workflow 도구가 CRLF 줄바꿈이 있는 스크립트 파일(예: Windows에서 체크아웃한 파일)을 거부하던 문제 수정.
  • /code-review가 클라우드 세션, Agent SDK, IDE 연동에서 원시 JSON 배열로 끝나던 문제 수정. 이제 지적 사항이 번호 목록으로 출력됩니다.

Windows

  • 약 1 KB보다 긴 PowerShell 명령이 항상 권한을 묻던 문제 수정. 허용 규칙과 읽기 전용 감지가 이제 32 KB까지 적용됩니다.
  • 종료할 때 stdio MCP 서버가 강제 종료되던 문제 수정. 이제 stdin을 먼저 닫고, 300 ms 뒤에도 서버가 실행 중일 때만 프로세스 트리를 종료합니다.
  • GitHub SSH 키가 없는 기기에서 GitHub owner/repo 플러그인 소스의 claude plugin install이 실패하던 문제 수정. 이제 HTTPS로 다시 클론을 시도합니다.
  • bypass permissions 모드에서 Git Bash의 rm -rf /c/Users/<name>이 묻지 않고 실행되던 문제 수정.

VSCode

  • 확장 프로그램 설정에 claudeCode.spinnerVerbs가 빠져 있던 문제 수정. settings.json에서 자동 완성과 검증이 되고, 형식이 잘못된 값이 채팅 패널을 깨뜨리지 않습니다.
  • C:\repo\file.ts나 file:///C:/repo/file.ts처럼 전체 Windows 경로로 쓴 채팅 링크가 Windows에서 파일을 열지 못하던 문제 수정.
  • OS, VS Code, prefersReducedMotion 설정에서 동작 줄이기를 켜도 작업 표시가 계속 움직이던 문제 수정.

Cloud sessions, Self-hosted runner

  • 자체 호스팅 runner를 기다리는 모든 클라우드 세션이 같은 대기 순번을 표시하던 문제 수정. 이제 각 세션이 자기 앞에 있는 세션 수를 표시합니다.
  • 클라우드 세션에서 Claude가 답하는 도중 보낸 메시지가, 답이 끝나면 그 답 위로 올라가던 문제 수정.
  • --capacity가 1보다 큰 runner에서 같은 저장소의 다른 세션이 시작되는 동안 세션의 git fetch, pull, push가 실패하던 문제 수정.
  • 등록이 거부될 때 claude self-hosted-runner가 오해를 부르는 오류를 출력하던 문제 수정. 이제 조직 관리자 설정 이름을 알려 주거나, 다시 시작한 on-demand runner(요청이 있을 때만 실행되는 runner)에는 새 work order(작업 지시)가 필요하다고 알려 줍니다.

Claude Tag, Code Review

  • [Claude Tag] 괄호가 들어간 URL 링크가 Claude의 일부 Slack 답변과 작업 체크리스트에서 깨지던 문제 수정.
  • [Claude Tag] 여섯 자리 풀 리퀘스트 번호처럼 16진수 색상처럼 보일 뿐인 코드 옆에 색상 견본이 그려지던 문제 수정.
  • [Claude Tag] 자체 호스팅 환경의 세션이 작업 도중 새 runner로 옮겨지면 Claude의 Slack 답변이 가끔 사라지던 문제 수정.
  • [Claude Tag] 채널 자체 설정에 없는 플러그인을 제거하는 카드를 Claude가 올리던 문제 수정. 이제 그 플러그인이 어디서 온 것인지 설명합니다.
  • [Code Review] 검토가 끝난 뒤에도 풀 리퀘스트의 Code Review 체크가 “in progress”로 남던 문제 수정. 이제 검토 결과가 표시됩니다.

알아두면 좋은 점

  • Windows-1252, Shift-JIS, GBK처럼 UTF-8이 아닌 파일을 다룬다면 이제 Edit, NotebookEdit가 이런 파일의 편집을 거부합니다. 이전 버전에서는 ASCII가 아닌 문자가 모두 바뀌었습니다.
  • 2.1.295에서 게이트웨이 로그인이 풀렸다면 forceLoginGatewayUrl 없이 forceLoginMethod가 gateway로 지정된 기기에서 생긴 문제로, 이번 버전에서 고쳐졌습니다.
  • Sonnet 5.5의 비용 표시가 달라집니다. 캐시 읽기를 100만 토큰당 $0.10로 계산하므로 /cost와 --max-budget-usd의 수치가 이전보다 낮게 나올 수 있습니다.
  • MCP 서버를 만든다면 처음부터 전송되는 도구 설명과 서버 지침의 기본 제한이 4,096자로 늘었습니다.
  • ←로 세션을 백그라운드로 보내는 도중 시작한 턴이나 ! 명령은 이제 중단됩니다.