Claude Code v2.1.302 변경점 요약: fork subagents 기본 활성화 및 Read 툴 메모리 문제 수정 등 35개 항목

claude -p

으로 배치(batch)를 구동하는 시스템을 몇 개 운영하고 있다. 매일 자동으로 실행되어 아침까지 처리가 완료되는 구성이다. 오늘 발표된 리포트에서 눈길이 갔던 부분이 바로 이 때문인 것 같다.

Changed fork subagents (subagent_type: "fork") to be on by default in claude -p

설정을 변경하지 않아도 동작이 달라질 수 있는 변경 사항이다.

v2.1.302는 2026년 10월 17일 출시 버전이며, 변경점은 35개 이상이다. 모든 것을 업무에 적용할 수는 없지만, 무인 실행(unmanned execution), 배치 처리(batch processing), 클라우드 연동과 관련된 것들을 중심으로 정리했다.

이번 변경에서 가장 신경 쓰이는 부분은 여기다.

claude -p

(비대화형/무인 실행 모드)로 사용할 경우, 이전에는 fork subagents가 명시적으로 설정하지 않으면 꺼져 있었다. v2.1.302부터는 기본값으로 켜졌다 (ON) (Agent SDK, 데스크톱 앱, VS Code에서도 동일).

fork subagent란 Claude Code가 내부적으로 다른 서브 에이전트를 구동하여 처리의 일부를 병렬화하거나 분담하는 메커니즘을 말한다. 이를 사용하지 않는 전제하에 작성된 스크립트나, 리소스 충돌을 피하기 위해 직렬 실행(sequential execution)으로 구성했던 파이프라인은 동작이 달라질 수 있다.

다시 끄려면: 환경 변수 CLAUDE_CODE_FORK_SUBAGENT=0

설정해야 한다.

내 환경에서는 동일한 처리를 여러 채널에 순차적으로 실행하고 있다. fork subagents가 ON이 되면, 동일 파일을 여러 서브 에이전트가 동시에 읽고 쓰는 상황이 발생할 수 있다. 업데이트 후 동작이 이상하다고 느껴지면 가장 먼저 이 부분을 확인하기로 했다.

Cloud Sessions를 사용하는 경우의 수정 사항은 다음과 같다.

• Fixed a scheduled routine run that failed partway being run again from the start an hour or more later, which could repeat work such as posting the same report twice: 중간에 실패한 루틴이 1시간 이상 후에 처음부터 다시 실행되어 동일 보고서 재게시와 같은 작업을 반복할 수 있는 문제가 수정되었다.

내 환경은 Windows 작업 스케줄러를 이용해 claude -p
을 직접 호출하는 것이라 Cloud Sessions는 아니지만, 실패 후 자동 재시도 메커니즘을 자체적으로 가지고 있다. 재시도는 '이어서'가 아닌 경우와 동일하게 발생할 수 있다는 점을 다시 한번 확인했다.

• Changed the desktop app and VS Code to always run the main conversation's subagents in the background: 데스크톱 앱이나 VS Code를 통해서도 메인 서브 에이전트가 항상 백그라운드에서 구동되도록 변경되었다. claude -p에는 직접적인 영향은 없지만, IDE를 통해 자동화 작업을 흘려보내는 경우에는 동작 확인을 해보는 것이 좋다.

• Fixed a prompt cache miss when a tool added mid-session was loaded again through ToolSearch or after compaction: 세션 도중에 툴이 추가된 경우, ToolSearch를 통하거나 압축(compaction) 후에 다시 로드되는 툴의 캐시 미스(cache miss)가 수정되었다.

긴 무인 세션에서 '캐시 로딩 토큰 수가 예상보다 적음', '비용이 불균형적으로 높음' 등의 기록이 있었다면, 이 수정 사항이 해당될 수 있다.

• Fixed a "Prompt is too long" error when stopping a turn while the conversation was being compacted: 압축(compaction) 중에 턴을 중지했을 때 'Prompt is too long' 오류가 발생하던 문제가 수정되었다. 장시간 세션을 도중에 중단하는 경우와 관련이 있다.

Read 툴이 모든 크기의 이미지 파일을 로드하거나, 이미지처럼 이름 붙여진 파이프 또는 장치(device)를 메모리에 완전히 불러오는 문제를 수정했습니다. 이제 128 MB가 넘는 이미지 소스는 거부됩니다.

이는 보안 및 안정성과 관련된 수정입니다.

기존에는 Read 툴로 이미지 파일의 경로(또는 이미지와 유사한 이름의 파이프/장치 파일)를 읽으려고 할 때, 크기에 관계없이 메모리에 전부 로드했습니다. 거대한 이미지 파일이나 /dev/urandom 같은 장치 파일을 실수로 읽으려고 하면 메모리를 고갈시킬 가능성이 있었습니다.

수정 후에는 128 MB를 초과하는 이미지 소스는 거부됩니다.

리포지토리에 큰 이미지가 섞여 있거나, 어떤 이유로든 장치 파일이 혼재된 환경에서 무인 실행할 경우 오류가 발생할 수 있습니다. 대상 파일의 크기를 확인해 보는 것이 좋습니다.

CLAUDE_CODE_AUTO_MODE_MODEL을 추가하여 클라이언트 측 auto mode 분류기가 사용하는 모델을 지정할 수 있게 되었습니다 (서버 측 auto mode 모델은 변경되지 않습니다).

환경 변수를 통해 클라이언트 측 auto mode의 분류기에 사용할 모델을 지정할 수 있게 되었으며, 이는 서버 측 auto mode의 모델에는 영향을 주지 않습니다. 비용 최적화를 위해 분류기만 가벼운 모델을 사용하고 싶을 때 유용합니다.

/config에 Idle compaction row를 추가하여 비활성 상태에서의 컴팩션(대화 자동 압축)을 켜거나 끌 수 있게 되었습니다.

비활성 상태에서의 컴팩션을 /config에서 ON/OFF할 수 있게 되었으며, 컴팩션 후 알림에도 '끄는 방법' 안내가 추가되었습니다. 무인 실행 시 예상치 못한 타이밍의 컴팩션을 없애고 싶을 때 선택지가 늘어났습니다.

게이트웨이가 Opus 4 또는 4.1에 접두사(prefix)를 붙여 이름 지을 경우, /autocompact와 /effort saving이 잘못된 모델로 설정되던 버그가 수정되었습니다 (예: anthropic/claude-opus-4-1).

Vertex AI나 AWS Bedrock 등 모델명에 접두사가 붙는 게이트웨이를 사용하는 경우, /autocompact나 /effort 설정이 잘못된 모델에 저장되었던 버그를 확인해 보는 것이 좋습니다.

/design-sync와 /design-login에 독립형 Claude Design (claude.ai/design)가 2026년 12월 14일에 폐쇄된다는 공지사항이 추가되었습니다.

Claude Design을 사용하는 경우 마이그레이션 계획을 세울 필요가 있습니다.

MCP 서버가 프로토콜 버전 2026-07-28로 네고시에이션하지만 resultType, ttlMs 등을 생략하는 경우, 툴이 표시되지 않거나 모든 툴 호출이 실패하던 문제가 수정되었습니다. 자체 제작 MCP 서버나 다소 오래된 버전의 MCP 서버를 사용하는 경우 관련될 수 있습니다.

플러그인이 많이 활성화된 상태에서 시작 시간이 개선되었습니다: 플러그인 명령어와 에이전트 파일이 로드할 때 발생하는 파일 시스템 호출 횟수가 크게 줄어들었으며, 이는 주로 Windows 환경에서 두드러집니다.

다수의 플러그인을 활성화할 경우, 시작 시 파일 시스템 접근 횟수가 대폭 줄어들었다. 특히 Windows 환경에서 개선이 크다고 한다. claude -p

매번 실행하는 배치 처리에서는 시작 시간 단축 효과가 미미하게 느껴진다.

플러그인 서브 커맨드가 설정 쓰기가 완료되기 전에 종료되어, 변경 사항을 잃거나 .tmp 파일을 남기던 문제가 수정되었다.

exFAT 또는 FAT32 형식 드라이브 상의 프로젝트에서 --plugin-dir로 시작된 세션을 포함하여 모든 파일 쓰기가 거부되거나 권한 확인을 요구하던 문제가 수정되었다. 외장 드라이브나 특정 파티션에 프로젝트를 관리할 때 영향을 미친다.

• Vertex/Bedrock 전환 후 diagnostics: Extra inputs are not permitted 오류 발생 문제를 수정 - 자동 모드에서 대화가 너무 길어질 경우 압축하도록 개선 (모든 체크된 도구 호출이 거부되던 문제)
• 아티팩트 게시/업데이트 실패 수정 (빈 편집 목록을 보냈을 때, 잘못된 재시도를 하던 문제)
• OpenTelemetry의 tool_decision 이벤트에서 classifier_category가 누락되는 문제를 수정 -
  claude remote-control --help가 미로그인 시 출력되지 않고 종료되던 문제를 수정 - URL의 하이퍼링크 표시 수정 (줄 바꿈 시 첫 번째 줄만 링크로 인식되던 문제)
• 워크스페이스 분리가 git 2.56 이상에서 실패하는 문제를 수정
• 프롬프트 제안이 크레딧 대상 모델에서 사용량을 소모하던 문제를 수정
• [VSCode] 코드 블록 표시 수정
• [VSCode] MCP 서버 패널의 로그인 URL 수정
• [VSCode] @browser 배너 수정

총 35개 항목 변경 중, claude -p를 사용한 무인 배치 실행에서 가장 확인이 필요하다고 느낀 것은 fork subagents의 기본 활성화였다.

설정 변경 없이 동작이 바뀌는 변경 사항은 사전에 확인하지 않으면 원인 불명의 동작으로 이어질 수 있다. CLAUDE_CODE_FORK_SUBAGENT=0로 이전 동작으로 되돌릴 수 있다.

나머지는 Read 도구의 128MB 제한이다. 무인 실행 시 예상치 못한 파일을 지정하는 경우에 대한 안전장치 역할을 한다. 스크립트가 오류가 났을 때 원인 후보로 염두에 두어야 할 점이다.

변경점 전체 목록: https://github.com/anthropics/claude-code/releases/tag/v2.1.302