무엇이 바뀌었나?
Claude Code 2.1.299가 2026년 10월 14일 출시됐습니다. 쉬고 있는 큰 대화를 미리 압축하는 idle compaction, 파일 멘션 방식을 바꾸는 환경 변수, agent view의 /effort, /fast 설정이 추가됐습니다. MCP 권한 규칙과 UserPromptSubmit 훅의 실행 순서처럼 기존 설정의 결과가 달라질 수 있는 변경도 들어 있습니다. 수정은 서드파티 게이트웨이의 API 키 전송, 샌드박스, MCP, 클라우드 세션과 Remote Control, 한중일 문자와 이모지 줄바꿈에 걸쳐 있고, 2.1.296에서 생긴 문제 두 가지도 고쳐졌습니다. 변경 항목이 매우 많아 아래에는 사용자 영향이 큰 항목을 골라 정리했습니다.
새 기능
-
터미널의 idle compaction
대화를 1시간 넘게 쉬면 프롬프트 캐시가 만료돼, 다음 메시지를 보낼 때 큰 대화 전체를 처음부터 다시 처리해야 했습니다. 이제 20만 토큰 이상인 대화를 약 54분 동안 쉬면, 1시간짜리 프롬프트 캐시가 만료되기 전에 대화를 압축합니다. 최소 기준인 20만 토큰은
CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS로 바꿀 수 있고, settings.json에"idleCompaction": false를 넣으면 꺼집니다. 원문에 따르면 두 설정 모두 v2.1.290 이상이 필요합니다. -
CLAUDE_CODE_DISABLE_FILE_MENTIONS@로 파일을 멘션하면 파일 내용이 그대로 대화에 들어갔습니다. 이 환경 변수를 켜면 Claude는 멘션한 파일의 경로만 받고, 필요한 내용은 파일 도구로 직접 읽습니다. -
agent view의
/effort,/fastagent view에서 새로 시작할 세션의 effort와 fast 모드를 지정할 수 있습니다. 인자 없이
/model,/effort,/fast를 입력하면 선택 창이 열립니다. -
/usage경고 추가사용량을 많이 쓰게 만드는 설정을
/usage에서 알아보기 어려웠습니다. 이제 max effort, workflow, 항상 켜져 있는 컨텍스트, 큰 도구 결과에 대한 경고가 표시됩니다. -
plan mode의 일회성 안내
bypass permissions를 쓸 수 있는 환경에서는 plan mode가 대부분의 편집이나 명령 전에 묻지 않는데, 이 사실이 표시되지 않았습니다. 이제 처음 한 번 안내가 표시됩니다.
-
claude plugin eval의--disallow-tools--disallow-tools옵션과 케이스별disallowed_tools필드로, Agent 같은 특정 기본 도구를 eval 실행에서 뺄 수 있습니다. -
claude self-hosted-runner orchestrator의--shutdown-drain-secSIGTERM을 받으면 새 요청 확인(polling)을 멈추고, 진행 중인 요청과 실행 중인 spawn 훅이 지정한 초만큼 마무리할 시간을 줍니다.
-
게이트웨이 환경의 attribution 블록 끄기
Claude 앱 게이트웨이의
code정책env에CLAUDE_CODE_ATTRIBUTION_HEADER=0을 지정하면 Claude Desktop Code 탭의 attribution 블록을 끌 수 있습니다. 게이트웨이를 거치는 Claude Code 세션의 attribution 블록에는 필드가 하나 추가됐고, 같은 값으로 블록을 없앨 수 있습니다. -
mod API 확장
관리형 설정으로 설치한 mod는
$.prompt.media로 프롬프트에 첨부된 이미지나 문서의 내용을 읽고,$.session.identity()로 세션의 로그인 방식을 확인할 수 있습니다. mod의Text에는size,weight,mono,tabular가,Box에는xs부터xl까지 이름 붙은 간격 단계가 추가됐고,bold는weight로 대체될 예정입니다.skill.prompt훅은 스킬의 frontmatter, 출처, 플러그인 이름, 파일 경로를 함께 받습니다.
주요 개선
-
PDF 멘션의 메모리, 디스크 사용량
@로 멘션한 PDF의 내용이 세션 기록에 그대로 저장돼 메모리와 디스크를 차지했습니다. 이제 PDF 내용은 세션 기록에 남지 않습니다. -
인식되지 않는 모델 ID 경고
시작할 때 길고 가공되지 않은 메시지가 표시됐습니다. 이제 환영 배너 아래에 문서 링크가 달린 짧은 한 줄로 표시됩니다.
-
“Unknown skill” 오류의 이름 제안
Claude가 스킬 이름 앞에
anthropic-skills:를 잘못 붙이면 스킬을 찾지 못하고 끝났습니다. 이제 목록에 있는 실제 이름을 제안합니다. -
/reload-skills안내압축 뒤에 스킬 목록을 되살리는 방법이 드러나지 않았습니다. 이제
/reload-skills가 전체 스킬 목록을 Claude에게 다시 보낸다고 알려 줍니다. -
worktree 생성 오류 메시지
기준 커밋을 찾지 못해 worktree를 만들 수 없을 때, 조회가 어떻게 끝났는지와 커밋이 없는 저장소 같은 가능한 원인을 알려 줍니다. bare 저장소 구조의 최상위에 worktree를 만들려 할 때도 관련 없는 git 오류 대신 구조를 설명합니다.
-
artifact 감시 개수
로컬 세션이 동시에 감시할 수 있는 게시된 artifact가 10개에서 25개로 늘었습니다.
-
백그라운드 에이전트 알림
에이전트가 자신의 백그라운드 작업만 기다리고 있을 때, 결과에 반영하기엔 너무 늦게 메시지를 받았을 때, 사용량 한도로 멈췄을 때 그 사실을 알려 줍니다.
-
클라우드 세션 로그인 만료 안내
claude.ai 로그인이 거부되거나 만료돼 클라우드 세션이 거부되면, 이제
claude auth login으로 다시 로그인하라고 알려 줍니다. -
[VSCode] 시작 속도
Python 환경이 없는 워크스페이스에서는 Python 확장 프로그램이 로드되는 동안 Claude를 함께 시작합니다. 전에 연 폴더를 새 창에서 열면 모델 선택기와 슬래시 명령 메뉴가 바로 채워집니다.
동작이 바뀐 항목
-
MCP 허용 규칙의 적용 범위 (변경)
mcp__a허용 규칙이a__b나a_처럼 이름 앞부분이 같은 다른 서버까지 허용했습니다. 이제 규칙에 적은 서버에만 적용됩니다. 서버의 모든 도구를 허용하려면 정규화된 서버 이름 전체를 사용해mcp__<server>__*로 적습니다. 에이전트의tools:목록도 같은 방식으로 바뀌어, 이름에__가 들어간 서버는mcp__<whole name>__*로 적어야 합니다. -
UserPromptSubmit훅 실행 시점 (변경)스킬이나 사용자 정의 슬래시 명령이 펼쳐진 뒤에 훅이 실행돼, 훅이 프롬프트를 막아도 그 안에 들어 있는 셸 명령은 실행될 수 있었습니다. 이제 펼치기 전에 훅이 실행되므로, 프롬프트를 막으면 그 셸 명령도 실행되지 않습니다. 스킬 frontmatter에 정의한
UserPromptSubmit훅은 스킬을 호출한 프롬프트의 다음 프롬프트부터 실행됩니다. -
종료 시 출력되는 resume 명령 (변경)
세션 이름으로 표시되던 resume 명령이 세션 ID로 표시됩니다. 세션 이름에 들어 있는 내용이 명령을 붙여 넣을 때 실행되지 않게 하기 위해서입니다. worktree 세션은 긴 옵션이 터미널 폭에 맞지 않으면
-w,-r을 씁니다. -
MCP 요청의 HTTP 리디렉션 (변경)
claude.ai 커넥터 프록시와 Anthropic이 호스팅하는 MCP 서버로 가는 요청, 클라우드 세션과 자체 호스팅 runner 세션의 MCP 프록시 요청이 더 이상 HTTP 리디렉션을 따라가지 않습니다. 커넥터 자체 서버의 리디렉션은 영향받지 않습니다.
-
보이지 않는 문자가 들어간 스킬, 명령 이름 (변경)
파일이나 폴더 이름에 숨은 문자, 글자 방향을 바꾸는 문자, 공백처럼 보이는 문자,
<,>가 들어간 스킬과 명령은 이름을 바꿀 때까지 제공되지 않습니다. -
플러그인 훅이 답을 주고받지 못한 경우 (변경)
플러그인 훅이 막을 수 있는 동작인데 훅에 전달하지 못했거나 훅의 답을 받지 못하면, 이제 통과시키지 않고 거부합니다. 이미 실행된 도구는 결과를 보류합니다. 플러그인 훅과 workflow 스크립트가 돌려주는 값은 28,000단계보다 깊게 중첩되면 거부됩니다(workflow 스크립트는 기존에 100,000단계까지 허용).
-
claude plugin test(변경)mod가 제공하는
$메서드 호출이 10초 안에 답하지 않으면 실제 세션처럼 실패합니다.ui.render트리의 각 mod 루트에는part: { plugin }이 붙으므로, 트리 전체를 비교하는 검증에 이 값을 포함해야 합니다. -
MCP 프로토콜 버전, 도구 설명 길이 (변경)
기능 플래그를 받지 않는 설치에서 클라우드 세션과 Remote Control의 MCP 커넥터가 기본으로 MCP 프로토콜 버전 2026-07-28을 사용합니다.
MCP_PROTOCOL_NEGOTIATION=legacy로 이전 방식을 쓸 수 있습니다.api.anthropic.com의 Anthropic 자체 MCP 서버는 도구 설명과 서버 지침이 4,096자에서 잘리지 않고 전부 전달됩니다. -
Cowork 클라우드 세션의 권한 처리 (변경)
auto mode에서는
PermissionRequest훅이 셸 명령이나 서브에이전트를 승인할 수 없습니다. auto mode가 아닐 때 Claude in Chrome이 승인된 사이트에서 하려는 동작을 안전 분류기가 문제로 판단하면, 관리형 설정이 없는 한 거부하지 않고 사용자에게 묻습니다. -
비대화형 세션의
/btw(변경)비대화형 세션에서
/btw곁질문이 11분 안에 답을 받지 못하면 시간 초과 오류를 돌려줍니다. -
/ultrareview업로드 오류 안내 (변경)업로드 실패 시
git add .를 제안해.env같은 추적하지 않는 파일까지 스테이징되거나 커밋될 수 있었습니다. 이제 이 제안을 하지 않습니다. -
기타 (변경)
WebFetch는 웹 검색과 같은 방식으로 effort를 정합니다.
turn.startmod 훅은 메인 루프뿐 아니라 서브에이전트와 teammate의 턴도 받으며,e.agentId로 구분합니다. 사이버 보안 안내는 더 이상 Cyber Verification Program 신청을 요청하지 않습니다.
주요 버그 수정
게이트웨이와 API 키
- 기능 플래그, 시작, fast mode, 프로필, 피드백 요청이 서드파티 게이트웨이(
ANTHROPIC_BASE_URL)용 API 키를 Anthropic으로 보내던 문제 수정. Anthropic API 키는 그대로 전송됩니다. - 관리형 설정 파일이
ANTHROPIC_BASE_URL을 지정할 때, Anthropic으로 가는 서버 관리형 설정 요청에 서드파티 게이트웨이의 API 키가 실리던 문제 수정. - 사용자 지정
ANTHROPIC_BASE_URL을 거치는 스트림이 데이터 없이 180초가 지나면 중단되던 문제 수정. 이제 기능 플래그 로드 여부와 관계없이 300초를 기다립니다. - 사용자 지정
ANTHROPIC_BASE_URL뒤에서 게이트웨이 전용 모델 이름을 쓰는 세션이 20만 토큰 근처에서 요청을 보내지 않고Prompt is too long · automatic compaction failed로 끝나던 문제 수정. - Claude 앱 게이트웨이가 정책의
availableModelsMatch: exact나deniedModels로 막은 모델을 제공하던 문제 수정. 이제 400으로 응답하고 모델 목록에서도 뺍니다. - MDM이나 관리형 설정 파일의
forceLoginOrgUUID,forceLoginMethod가 서버 관리형 설정에 가려지거나 대체되던 문제 수정.
샌드박스와 권한
- 샌드박스 안의 셸 명령이
--plugin-dir폴더에 쓸 수 있던 문제 수정. 이 폴더의 코드는 Claude Code가 다시 불러와 샌드박스 밖에서 실행합니다. - macOS에서 거부된 경로가 심볼릭 링크를 거칠 때, 샌드박스 명령이 실제 위치로 그 경로를 읽거나 쓸 수 있던 문제 수정.
- 폴더 이름에 중괄호, 괄호, 백슬래시가 있으면
denyRead,allowRead글롭을 Claude Code 설정 검사와 샌드박스가 서로 다르게 해석하던 문제 수정. 시작 디렉터리가 심볼릭 링크로 바뀐 경우allowRead,allowWrite를 다시 검사합니다. - plan mode에서
PreToolUse훅이나 mod의tool.check훅이 허용한 쓰기 작업(MCP 도구, 파일, 셸 명령)이 실행되던 문제 수정. - 실행 중에
rm을 만들지 않는 셸-c스크립트에도 rm 확인을 묻던 문제 수정. Claude Code가 읽을 수 없는 스크립트에서 실행 중에 만들어지는 rm은CLAUDE_CODE_STRICT_INLINE_SHELL_RM_PROMPT=1일 때만 묻습니다. - 설명 없이 시작한 agent teammate의 작업 설명에, 프롬프트에 있던 인증 정보 일부가 남던 문제 수정.
- accept-edits 모드에서 설정 디렉터리 경로에
.claude가 없으면 Write, Edit 도구가 묻지 않고 세션의 mods 폴더에 mod를 만들던 문제 수정. - worktree로 격리된 세션이 격리 검사에서 거부해야 할 일부 awk 프로그램을 받아들이던 문제 수정.
MCP
- HTTP로 연결한 MCP 서버가 알림에 대한 응답 본문을 끝내지 않으면 30초 동안 멈췄다가 실패하던 문제 수정 (#99014).
- MCP OAuth 로그인, 토큰 갱신, 로그아웃에서 설정한
headers,headersHelper값을 보내지 않아 인증 프록시 뒤의 서버가 동작하지 않던 문제 수정. claude mcp list,claude doctor,/status가 빈.mcp.json을 잘못된 파일로 표시하던 문제 수정.enabledMcpjsonServers나disabledMcpjsonServers에 서버 이름 하나를 배열이 아닌 일반 문자열로 적으면 설정 파일 전체가 무시되던 문제 수정.- 정책 검사에서 막힌 서버를
claude mcp list,claude mcp get, 서브에이전트가 시작하던 문제 수정. 실행 중인 헤드리스, SDK 세션에 추가된 서버도 정책 검사 전에 연결되지 않습니다. constructor,prototype같은 이름의 MCP 서버가 연결되지 않거나 권한 확인이 잘못 동작하던 문제 수정.- 정규화한 서버 이름에 밑줄 두 개가 들어간 MCP 서버(
mcp__<server>)에 deny, ask 규칙이 적용되지 않던 문제 수정. - 헤드리스, SDK 세션에서 백그라운드 재연결이 연결을 닫으면 실행 중인 MCP 도구 호출이 실패하거나 두 번 실행되던 문제 수정.
세션, 클라우드, Remote Control
- 클라우드, 헤드리스 세션이 재시작 후 재개될 때 새 메시지가 도착하면 승인된 도구 호출이 두 번 실행될 수 있던 문제 수정. 2.1.296에서 생긴 문제입니다.
- Cowork와 claude.ai 클라우드 세션에서
UserPromptSubmit훅이나 mod의prompt.submit훅 실행 중 멈춘 메시지를 Edit, Retry하면 실패하던 문제 수정. 2.1.296에서 생긴 문제입니다. - 느린 연결에서 많은 이벤트를 업로드하지 못하면 Remote Control이나 클라우드 세션의 claude.ai 화면이 멈추던 문제 수정.
- 같은 묶음의 다른 대기 프롬프트가 전달에 실패하면 Remote Control 프롬프트가 사라지던 문제 수정. 30-35 MiB 파일이나 장시간 세션의 파일이 Remote Control로 전달되지 않던 문제도 고쳐졌습니다.
- 클라우드 세션의 작업 프로세스(worker)가 교체되는 사이에 답한 권한 확인이나 질문이 무시되던 문제 수정. 압축 직후나 출력 토큰 한도에 걸린 직후 교체될 때 답이 끝나지 않던 문제도 고쳐졌습니다.
- 많은 서브에이전트를 실행한 클라우드, Remote Control 세션을 재개한 뒤 메모리 사용량이 높던 문제 수정.
- non-streaming 모드로 전환된 요청이 출력 토큰 한도에서 잘리면 재시도나 오류 없이 턴이 조용히 끝나던 문제 수정.
- CLI를 재시작하고 세션을 재개한 뒤
SendMessage가 이름으로 서브에이전트를 찾지 못하던 문제 수정. 마지막 압축 전에 붙인 이름은 여전히 에이전트 ID가 필요합니다. --safe-mode로 시작한 백그라운드 세션이 깨어나거나 재시작되면 safe mode에서 조용히 벗어나던 문제 수정.
예약 작업
- Agent SDK, IDE,
claude remote-control세션에서 백그라운드 작업이 실행 중이면 예약된 깨우기(ScheduleWakeup)가 동작하지 않던 문제 수정. - 예약 도구가 작업의 다음 실행 시각을 잘못된 분으로 알리던 문제 수정.
- 서머타임이 끝나며 같은 시간이 반복될 때 예약 작업과 반복 실행이 턴마다 다시 실행되거나 일찍 실행되던 문제 수정.
메모리와 디버그 로그
- 디버그 로그를 많이 쓸 때(
--debug,--debug-file) 메모리가 늘어나던 문제와, 디버그 로그를 저장하는 디스크나 네트워크 드라이브가 쓰기를 멈추면 종료할 때 멈추던 문제 수정. - 디버그 출력을 stderr로 보낼 때 부모 프로세스가 읽기를 멈추면 메모리가 끝없이 늘어나던 문제 수정.
파일, 이미지, 표시
- Read가 바이트 순서 표시(BOM)가 있는 UTF-16LE 파일을 깨뜨려 읽고, Write가 BOM을 빼거나 Windows-1252, Shift-JIS, GBK, UTF-16BE 파일을 조용히 UTF-8로 바꾸던 문제 수정. 이런 쓰기는 이제 거부됩니다.
- 한중일 문자나 이모지가 영문 단어와 섞인 텍스트가 줄바꿈될 때 마지막 줄이 사라지거나 빈 줄이 남던 문제 수정. 매우 좁은 터미널의 빈 줄, 넓은 문자 옆에서 텍스트가 잘리는 문제도 함께 고쳐졌습니다.
- 굵게, 기울임 같은 스타일이 표 테두리를 넘거나 줄바꿈된 행에서 사라지던 문제 수정.
- API가 큰 이미지 하나를 거부한 뒤 긴 대화에서 새로 첨부한 이미지가 매 턴 사라지던 문제 수정. Claude가 작업 중일 때 첨부한 이미지(VS Code, 데스크톱 앱, SDK)가 원래 크기로 전송되던 문제도 고쳐졌습니다.
- bracketed paste(붙여넣기 구간을 표시하는 터미널 기능)를 지원하지 않는 터미널에서, 보이지 않는 제어 문자 뒤의 붙여 넣은 텍스트가 모두 사라지던 문제 수정.
claude -p가 설정 파일 검증에 실패해도 아무것도 출력하지 않던 문제 수정. 이제 문제 파일과 잘못된 항목을 stderr에 표시합니다./usage, 한도 근접 경고, 상태 줄이 사용량을 100%보다 높게 표시하던 문제 수정 (#92238).
플러그인과 mod
- 원격에서 끈 mod가 열려 있는 세션에서 계속 실행되던 문제 수정. 이제 턴 사이에 내려갑니다.
- 매 턴 끝에 프롬프트를 보내는 mod 때문에 헤드리스 실행이
--max-turns,--max-budget-usd, 중단 요청을 넘어 계속되던 문제 수정. __proto__키가 조용히 제거된 값이 mod 훅에 전달돼, 다른 mod가 만든 도구 호출에서tool.check검사가 건너뛰어질 수 있던 문제 수정.- 사용자가 설치한 mod의
$.env.set이 관리형 설정의 명령 훅이 시작되는 환경을 바꾸던 문제 수정. /reload-plugins가 다른 터미널에서 방금 설치한 플러그인을 불러오지 못하던 문제 수정.claude plugin eval이 API가 거부한 실행을 통과로 처리하던 문제 수정. 이제 0점으로 처리되고 전체가 종료 코드 1로 끝납니다.
Windows
- 바쁜 기기에서 프로세스 생존 확인이 PowerShell 프로세스를 남겨 메모리가 바닥나던 문제 수정.
- Git for Windows가 없을 때 셸을 지정하지 않은 PreToolUse, PermissionRequest 훅이 실패하면 호출이 허용되던 문제 수정. 이제 검사가 실패하면 호출을 막습니다.
- 시작할 때 Git Bash가 PATH를 알려 주지 않으면 세션 내내 Bash 명령이 “command not found”로 실패하던 문제 수정.
- WSL2에서 샌드박스가 Windows 드라이브에 쓸 수 있을 때 샌드박스 명령이
bwrap: Can't mkdir /mnt/c/Program Files/ClaudeCode로 실패하던 문제 수정.
VSCode, Cloud sessions
- [VSCode] 다른 세션으로 갔다가 돌아오면 보내지 않은 프롬프트와 첨부가 사라지던 문제 수정.
- [VSCode] 새 대화를 시작한 뒤 쓰지 않은 빈 채팅이 백그라운드 Claude 프로세스를 계속 실행하던 문제 수정.
- [Cloud sessions] 기존 출력 파일이 한꺼번에 다시 전송되면 메모리가 급증해 세션이 중단될 수 있던 문제 수정.
- [Cloud sessions] 편집한 routine을 저장하면, 원래 환경이 삭제됐거나 목록에 없을 때 다른 환경으로 조용히 옮겨지던 문제 수정.
- [Remote Control] 컴퓨터에 연결할 수 없는 세션이 메시지를 보내는 것처럼 보이던 문제 수정. 이제 다시 연결될 때까지 텍스트가 입력창에 남고 Send가 꺼집니다.
Claude Tag, Code Review
- [Claude Tag] 게스트가 있는 채널에서, 채널 지침이 답하라고 한 태그 없는 글에 Slack의 Claude가 답하지 않던 문제 수정.
- [Claude Tag] 멤버가 아닌 채널의 스레드에 답을 올렸다고 잘못 알리던 문제 수정. 이제 전달되지 않았다는 사실과 해결 방법을 알려 줍니다.
- [Claude Tag] 자체 호스팅 runner 이미지에 python3가 없으면 답을 올리지 않고 턴을 끝내던 문제 수정.
- [Code Review] 월 지출 한도 안내가 관리자를 Claude Code 설정으로 보내던 문제 수정. 이제 한도를 설정하는 Usage 페이지로 연결합니다.
알아두면 좋은 점
- MCP 허용 규칙을
mcp__<서버 이름>형태로 써 왔다면 이제 그 이름의 서버에만 적용됩니다. 이름 앞부분이 같은 다른 서버(a__b등)의 도구는 다시 권한을 물을 수 있으니, 필요하면 정규화된 서버 이름 전체로mcp__<server>__*규칙을 추가합니다. 에이전트의tools:목록도 마찬가지입니다. UserPromptSubmit훅으로 프롬프트를 검사한다면 이제 스킬, 슬래시 명령이 펼쳐지기 전에 실행됩니다. 펼쳐진 내용을 기준으로 검사하던 훅은 동작을 확인해 봐야 합니다.- 2.1.296으로 올린 뒤 클라우드 세션에서 도구가 두 번 실행되거나 Cowork에서 Edit, Retry가 실패했다면 이번 버전에서 고쳐졌습니다.
- idle compaction은 터미널에서 20만 토큰 이상인 대화가 약 54분 쉬었을 때만 동작합니다. 원하지 않으면 settings.json에
"idleCompaction": false를 넣습니다. - 서드파티 게이트웨이(
ANTHROPIC_BASE_URL)를 쓴다면 이전 버전에서 게이트웨이용 API 키가 일부 Anthropic 요청에 함께 전송됐습니다. 이번 버전에서 고쳐졌습니다. /ultrareview업로드가 실패했을 때 예전 안내대로git add .를 실행했다면.env같은 파일이 스테이징되지 않았는지 확인합니다.