무엇이 바뀌었나?
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자로 늘었습니다.
←로 세션을 백그라운드로 보내는 도중 시작한 턴이나!명령은 이제 중단됩니다.