Claude Code v2.1.321부터 v2.1.325까지는 새로운 기본 Fable 모델인 Claude Fable 5.2가 추가되었고, Claude가 도구를 JavaScript로 호출하는 실험적인 Code Mode, 플러그인의 engines["claude-code"]를 통한 버전 범위 지정 등이 포함되었습니다. 아울러, 샌드박스 내 Bash 명령이 기본적으로 일반 권한 흐름(normal permission flow)을 따르게 되는 등 기존 동작 방식이 변경되는 수정 사항과 Bash 권한 관련 보안 수정이 대량으로 포함되어 있습니다.
Claude Fable 5.2 (v2.1.321)
claude-fable-5-2를 추가하여 기본 Fable 모델로 설정할 수 있으며, 이는 1M 컨텍스트를 제공하고 비용은 입력 $8 / 출력 $40(Mtok당)이며 캐시 읽기는 $0.20/Mtok입니다.- 저장된 Fable 5.1 선택은
fable로 변경되었습니다 (Pro / Max는 즉시, Team / Enterprise는 조직이 허가하는 시점에 적용). 이전 버전으로 되돌리려면 /model claude-fable-5-1을 사용합니다.
Vertex에서 fast mode (v2.1.322)
- Vertex의 global / us / eu 리전에서 fast mode를 사용할 수 있게 되었습니다. Vertex가 거부할 경우 표준 속도로 폴백(fallback)됩니다.
Code Mode (실험적, 옵트인) (v2.1.323)
- Claude가 JavaScript를 작성하여 도구를 호출하는 모드입니다.
- 활성화 및 조직 단위 비활성화는 Code Mode 문서를 참조하십시오.
claude remote-control --settings <file>
(v2.1.321)
claude remote-control이 시작되는 모든 세션에 설정 파일을 적용합니다. 파일이 변경되면, claude remote-control을 재시작할 때까지 새 세션은 시작되지 않습니다.- v2.1.325에서는 자동 종료 시 exit 4, 등록 불가 시 exit 69를 반환하도록 변경되어 서비스 매니저에서 재시작하기가 용이해졌습니다.
정책으로 차단되었을 때 안내 (v2.1.325)
- 조직 정책에 의해 요청이 차단된 오류 메시지 아래에, 계속 진행하는 방법(메시지를 변경하려면
/rewind를 사용하거나, /clear를 사용)을 표시합니다.
MCP 작업 개선 (v2.1.325)
- Claude에게 작업이 답변 대기 중임을 알리고,
/tasks로 안내할 수 있도록 했습니다.
- 백그라운드 MCP 작업 질문에서 Esc 키를 누르면 '나중에 답변'으로 처리됩니다. 서버에는 아무것도 전송되지 않으며, 질문은
/tasks에 남아 있습니다.
/mcp 표시 개선 (v2.1.323)
- API가 입력 스키마를 거부하기 위해 제외한 도구의 수와 이유를 표시합니다.
MCP 클라이언트 변경 (v2.1.323)
- v1 MCP 클라이언트가 삭제되었으며,
MCP_SDK_GENERATION=v1은 v2 클라이언트의 호환 모드(이전 핸드셰이크, 느슨한 OAuth 체크)로 작동합니다.
- MCP 서버에 로그인하는 도구는 bypass / auto 모드에서도 확인을 요청하도록 변경되었습니다. 응답할 수 없는
dontAsk 모드의 경우 /mcp를 사용하십시오.
- 프로젝트(
.mcp.json)의 MCP 서버 승인이 서버 이름의 완전 일치로 변경되었습니다. 표기가 다른 승인 항목은 재확인을 거칩니다.
장시간 훅(hook) 하트비트 (v2.1.323)
claude -p 및 SDK 세션에서 훅이 오래 실행되는 동안, 30초마다 진행 상황 하트비트를 전송합니다. 이는 Claude Desktop과 같은 호스트가 멈춤(hang)으로 판단하여 턴을 종료하지 않도록 하기 위함입니다.
훅과 권한 체크의 관계 (v2.1.323)
지원하는 Claude Code의 버전 범위를 선언할 수 있습니다. 범위 외의 플러그인은 설치, 업데이트 또는 로드되지 않으며, 범위 내에서 최신 버전이 선택됩니다.
기술 명세 예시 (범위 형식은 공식 문서를 확인하세요):
{
"name": "my-plugin",
"engines": {
...
}
claude plugin validate 강화 (v2.1.323 / v2.1.325)
- 플러그인의 TypeScript 훅 모듈에 대한 타입 검사. 지적은 경고(warning)이며,
--strict 지정 시 실패로 처리됩니다 (v2.1.323).
- mod의
engine.create 훅이 추가, 보류 또는 대체하는 $n 명사 표시 (v2.1.323). 플러그인 폴더 내의 안전하지 않은 경로 및 링크를 보고합니다 (로드 시에는 건너뜀) (v2.1.325).
기타 플러그인 관련 변경 사항 (v2.1.323 / v2.1.325)
-
claude plugin install --json 결과에 설정되지 않은 userConfig 개수(unsetOptionCount)가 추가되었습니다 (v2.1.323).
-
플러그인의 agent 설정이 비권장(deprecated)되었습니다. 계속 적용되지만, 시작 시 또는 claude plugin list /validate에서 경고가 발생합니다 (v2.1.323).
-
플러그인의 언어 서버가 시작할 수 없을 때 경고가 표시됩니다 (v2.1.323).
-
플러그인 MCP 번들(.mcpb, .dxt)의 배포 위치가 플러그인 디렉토리 하위로 변경되어, 읽기 전용 플러그인 폴더에서도 로드할 수 있게 되었습니다 (v2.1.325).
-
관리형 설정의 pluginDigests는 비권장 및 무시됩니다. prependPlugins /appendPlugins로 나열된 원격 마켓플레이스의 플러그인을 조직 소유물처럼 취급합니다 (v2.1.325).
-
마켓플레이스의 ref에 브랜치나 태그상의 임의 커밋 전체 ID를 지정할 수 있게 되었습니다 (이전 클라이언트에서는 복제할 수 없었음에 유의) (v2.1.325).
-
마켓플레이스 추가 및 플러그인 설치 시 경고 메시지에 "플러그인은 파일이나 셸에 접근하여 코드를 실행할 수 있습니다"라는 내용이 명시되었습니다 (v2.1.325).
-
사용량 크레딧이 필요한 모델에서 크레딧이 꺼져 있거나 소진되었을 때, 옵션 메뉴(중지, 사용량 크레딧으로 전환, 업그레이드)가 표시됩니다 (v2.1.323).
-
-p, SDK, IDE, 클라우드 세션의 Fable 제한 메시지에 재설정 시간과 계속하는 방법을 표시합니다 (v2.1.323).
-
subagentStatusLine 설정이 삭제되었습니다. 서브 에이전트 줄은 항상 기본값으로 표시됩니다 (설정이 남아 있어도 로드는 가능) (v2.1.323).
-
출력 토큰 제한으로 중단된 서브 에이전트에게 끝부분만 반환하는 것이 아니라, 짧게 전체 내용을 다시 답변하도록 합니다 (v2.1.325).
-
CLAUDE_CODE_DISABLE_AGENT_PROGRESS_SUMMARIES=1로 서브 에이전트의 진행 상황 요약 및 관련 요청을 비활성화합니다 (v2.1.318부터 사용 가능) (v2.1.323).
-
동일한 머신상의 세션 간에 프롬프트 없이 전송할 수 있는 메시지 수가 약 20개에서 100,000개로 증가했습니다 (v2.1.323).
-
분할 페인(split pane)의 에이전트 팀메이트가 요청이 자신의 팀 리드로부터 온 것인지 확인하도록 합니다 (v2.1.323).
-
tmux / iTerm2의 팀메이트와 에이전트 뷰에서 ←로 연 세션이 셸의 마지막 cd 위치가 아닌, 해당 세션 폴더에서 시작됩니다 (v2.1.325).
-
auto 모드에서 헤드리스(headless) / 데스크톱 / VS Code 환경에서, 대기 중인 여러 백그라운드 서브 에이전트의 보고를 한 번의 모델 호출로 처리합니다 (v2.1.321).
-
1,000자를 초과하는 명령어의 백그라운드 알림 및 TaskStop 결과는 시작 부분과 끝부분만 Claude에게 보여 컨텍스트를 절약합니다 (v2.1.321).
샌드박스 내 Bash의 기본 동작 변경 (v2.1.325)
- 샌드박스 내 Bash 명령이 기본적으로 일반 권한 흐름을 따르도록 합니다.
- 기존처럼 프롬프트 없이 실행하려면
sandbox.autoAllowBashIfSandboxed: true를 설정해야 합니다.
설정(Setting)을 설정합니다. 관리형(Managed) 설정에서 샌드박스를 활성화한 경우, 최상위 관리 소스에 설정해야 합니다.
{
"sandbox": {
"enabled": true,
...
}
read-only git 명령어 확인 (v2.1.325)
- 프로젝트 외부 또는 신뢰하지 않는 리포지토리에서 read-only인 git 명령은 확인을 요구합니다. 프롬프트 없이 실행하려면 설정 변경이 아닌
--add-dir로 지정해야 합니다.
스케줄링 작업 / /loop에서의 스킬 실행 (v2.1.325)
allowed-tools나 훅(hook)을 선언하는 스킬은 실행 전에 확인하도록 합니다. 무인 실행하려면 permissions.allow에 Skill(name)을 추가합니다.
{
"permissions": {
"allow": ["Skill(my-skill)"]
...
}
"항상 허용(Always allow)" 변경 (v2.1.325)
- Desktop / IDE / SDK 호스트에서 저장된 규칙이 해당 명령을 다시 허용하는 경우에만 규칙 자체를 제시합니다. 이 기능에 의존했던 스케줄링 작업은 대기 상태가 될 수 있습니다.
샌드박스 및 worktree 제한 강화 (v2.1.323 / v2.1.325)
- macOS / Linux 샌드박스에서
git worktree add / move / remove가 read-only로 실패합니다. 세션이 시작되거나 부여되지 않은 worktree에서의 커밋도 마찬가지입니다 (v2.1.323) - 쓰기 가능한 폴더 내의 심볼릭 링크를 통한 쓰기 권한은 무시하고 실제 경로에 권한을 부여합니다 (v2.1.323).
- 추가 디렉토리 내
.claude 설정, 스킬, 에이전트, 명령어, 훅으로의 샌드박스 내부 쓰기를 거부합니다 (v2.1.325) - 격리된 worktree 세션 / 에이전트에서는 git bisect run, git maintenance register|start, scalar 등의 설정 명령을 거부합니다 (v2.1.325) - .git 폴더가 링크나 하드링크를 포함하는 체크아웃(git-new-workdir, cp -al 등)에서의 worktree 생성을 거부합니다 (v2.1.323).
인증 정보 처리 (v2.1.323 / v2.1.325)
- Claude Code 자체의 ripgrep 및 대부분의 내부 git 명령어는 사인인 토큰이나 API 키를 포함하지 않는 환경에서 실행됩니다 (v2.1.323).
- 샌드박스의 네트워크 브릿지 등 내부 프로그램도 마찬가지입니다 (v2.1.325).
- "다시 묻지 않기(don't ask again)" 기능을 통해, 비밀 정보를 포함하는 것처럼 보이는 규칙이나 git 관리 하의
settings.local.json에 저장되는 규칙은 세션 한정으로 적용됩니다 (v2.1.323) - /security-review는 Claude가 실행하기 전에 확인하도록 합니다 (v2.1.323).
알 수 없는 모델 ID의 컨텍스트 창 (v2.1.323)
- Claude Code가 인식하지 못하는 모델 ID의 컨텍스트 창을 200K에서 1M으로 가정하도록 변경되었습니다.
- 빠르게 압축하려면
/autocompact를 사용하고, 200K로 유지하려면 CLAUDE_CODE_DISABLE_1M_CONTEXT=1을 설정합니다.
- 다른 공급업체의 작은 창 모델의 경우, 가득 차면
/clear까지 매 턴 실패할 수 있으므로, 사전에 CLAUDE_CODE_DISABLE_1M_CONTEXT=1을 설정해 두는 것이 좋습니다. v2.1.325에서는 CLAUDE_CODE_MAX_CONTEXT_TOKENS가 claude-로 시작하는 알 수 없는 모델 ID(게이트웨이의 claude-sonnet-latest 등)의 컨텍스트 창에도 적용되도록 했습니다.
export CLAUDE_CODE_DISABLE_1M_CONTEXT=1
기타 환경 변수 (v2.1.323)
CLAUDE_CODE_RESUME_HINT_COMMAND
Claude Code를 실행하는 프로그램이 종료 시 힌트로 자체 재개 명령을 표시하도록 변경되었으며, CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS의 상한이 64000에서 300000으로 증가했습니다.
- 조직 설정 및 정책 요청 시,
ALL_PROXY만으로 설정된 프록시는 사용하지 않게 되었으며, 필요하다면 HTTPS_PROXY를 설정해야 합니다.
- Perforce 설정이 되어 있음에도 불구하고
CLAUDE_CODE_PERFORCE_MODE가 꺼져 있을 경우, 시작 시 한 번만 알림을 표시합니다.
Bash(PORT=* npm run dev)와 같이 변수 값에 *를 포함하는 Bash 허용 규칙에 시작 시 경고 추가 기능이 도입되었습니다.
주요 개선 사항 (버전별):
- (v2.1.323) diff 패널에
/diff to close 힌트가 추가되었으며, ? 단축 가이드에 패널 포커스 및 종료 키가 추가되었습니다.
- (v2.1.323) 다수의 서브 에이전트를 사용할 때, 완료된 서브 에이전트의 트랜스크립트를 조기에 해제하도록 개선되었습니다.
- (v2.1.321) 설치 스크립트에서 최신 버전을 중복 다운로드하지 않도록 하여
claude install 실행 시간이 2~4초 단축되었습니다.
- (v2.1.323) WebFetch의 깊게 중첩된 페이지에서의 속도 및 메모리 사용량이 개선되었습니다.
- (v2.1.321) 신뢰할 수 있는 TLS 인증서 로딩 가속화, Windows의 PATH 탐색 생략 및 Git for Windows 판별 과정 생략을 통해 시작 시간이 단축되었습니다.
- (v2.1.321)
/model 피커에서
답변하지 않은 메시지가 요약에서 사라지는 문제 수정
v2.1.323: 재개된 세션에서 다음 메시지가 오래된 중단 메시지와 결합되는 문제 수정
v2.1.323: 매우 큰 파일 변경 후, 다음 프롬프트에서 메모리가 급증하는 문제 수정
v2.1.323: 실행 중인 세션에서 저장된 설정이 직전의 settings.json 수동 편집 내용을 되돌리는 문제 수정
v2.1.323: claude -p가 설정으로 차단된 모델 대신 조용히 다른 모델을 사용하는 문제 수정 (stderr에 경고 출력)
v2.1.323: claude update 완료 직후의 Ctrl+C로 인해 claude 명령어가 사라질 수 있는 문제 수정
v2.1.321: 응답 도중에 연결이 끊겼을 때 "API Error: EPROTO: The TLS handshake failed"로 턴이 끝나는 문제 수정 (v2.1.302 이전 동작으로)
v2.1.321: fast mode가 속도 제한 또는 과부하 시 응답을 잃거나 장시간 재시도하는 문제 수정 (먼저 동일 모델의 표준 속도를 테스트)
v2.1.321: 큰 파일을 한 줄씩 반복해서 읽는 장시간 세션에서의 메모리 사용량 수정
v2.1.321: 세션 시작 시 Claude에 전달되는 git status가 실패했을 때 'clean'으로 읽히는 문제 및 스테이징되지 않은 변경 사항을 스테이징된 것으로 표시하는 문제 수정
v2.1.321: MCP OAuth 요청이 서버의 리디렉션으로 Refresh Token 등의 비밀 정보를 다른 호스트로 보내는 문제 수정
v2.1.323: MCP 도구 호출이 TOKEN_EXPIRED 등 사인인 서버 오류로 끝나 재사인인을 요구하지 않는 문제 수정
v2.1.323: 서버 연결이 느릴 때, 재개된 대화에서 과거의 MCP 도구 호출이 누락되는 문제 수정
v2.1.325: 일시적인 토큰 갱신 거부 후, MCP 서버가 "needs authentication" 상태로 남아 mcp_tool 훅이 건너뛰어지는 문제 수정
v2.1.325: 백그라운드 MCP 작업의 질문이 입력 중인 메시지 위에 열리는 문제, Esc 키로 닫은 작업이 멈춰있는 문제 수정
v2.1.325: SDK 호스트에서 MCP 도구 호출 시 재연결 후에 "Not connected"를 반환하는 문제 수정
v2.1.325: zstd 압축 응답의 디코딩과 관련된 보안 문제 수정
v2.1.325: Bash의 일부 복합 명령어가 확인 없이 실행될 수 있었던 문제 수정
v2.1.325: Bash의 allow 규칙이 이름과 다른 프로그램을 실행할 수 있게 했던 문제 수정
v2.1.325: Read(./.env)와 같은 상대 경로의 deny/ask 규칙이 cd 이후 프로젝트를 덮어쓰지 못하게 하는 문제 수정 (추가 디렉토리에도 적용)
v2.1.325: mcp__plugin_*_로 시작하는 deny/ask 규칙이 대소문자가 다른 서버 이름이나 도구 이름을 놓치던 문제 수정
v2.1.325: worktree의 설정 및 훅, 그리고 연결된 worktree의 공유 git 폴더를 Bash Sandbox가 완전히 보호하지 못했던 문제 수정
v2.1.325: 슬래시 명령어의 allowed-tools 허용이 해당 턴 중/후에 발생한 백그라운드 에이전트에도 적용되던 문제 수정
v2.1.323: --permission-mode auto 또는 defaultMode: auto가 auto 모드 사용 불가 시 더 많은 것을 허용할 수 있는 모드로 시작하는 문제 수정 (Manual 모드에서 시작)
v2.1.323: Bash(ls*)와 같은 와일드카드 포함 allow 규칙이 확인을 건너뛰는 경우가 있던 문제 수정
v2.1.323: sudo나 env와 같은 래퍼를 거치는 명령어를 Bash의 deny/ask 규칙이 놓치던 문제 수정
v2.1.323: Write / Edit 도구가 Read
• Deny 규칙 대상 경로에 쓰기할 수 있었던 문제 수정 -
v2.1.323: Bash 샌드박스가 세션 중에 꺼질 수 있는 문제 수정 -
v2.1.323:--settings
• Agent SDK가 샌드박스 없이 Bash를 실행하는 문제 (시작 시 중단) -
v2.1.323:plansDirectory
• 설정 시 프로젝트 외부로 플랜 파일이 작성될 수 있는 문제를 수정 -
v2.1.321: 읽기 전용(read-only) Bash 명령어가 확인 없이 샌드박스 외에서 실행될 수 있는 문제를 수정 -
v2.1.321: 디렉터리로 cp / mv로 쓰여지는 파일에 Deny 규칙이나 보호 파일 확인이 적용되지 않는 문제
• v2.1.325: 긴 선택지가 줄 바꿈 시 일부 덮어쓰여지는 문제, 좁은 터미널에서 첫 화면의 행이 누락되는 문제를 수정 -
v2.1.325:claude -p
• v2.1.325: 텍스트 출력이 터미널에 스타일 외 제어 시퀀스를 흘리는 문제를 수정 -
v2.1.323: 결합 문자(악센트 기호 등)가 줄 바꿈 시 어긋나거나 사라지는 문제를 수정 -
v2.1.323: 여러 줄 상태 표시줄이 화면 밖으로 밀려나는 문제를 수정 -
v2.1.323:/usage
• v2.1.323: Setup 토큰이나 CLAUDE_CODE_OAUTH_TOKEN으로 상한 바를 숨기는 문제를 수정 -
v2.1.323: Remote Control에서 Wi-Fi 전환 또는 VPN 재연결 후 1분 이상 연결 끊김 표시가 되는 문제를 수정 -
v2.1.323: OpenTelemetry의 otlp exporter에서 OTEL_EXPORTER_OTLP_PROTOCOL 미지정 시 조용히 실패하는 문제 (기본값은 http/protobuf)
• v2.1.325: 접근할 수 없는 폴더 하위에 PATH 항목이 있으면 시작이 약 1초 동안 멈추는 문제를 수정 -
v2.1.325: 드라이브 문자 대소문자나 구분자 차이로 /resume가 세션을 거부하거나 숨기는 문제를 수정 -
v2.1.323: 같은 PATH 폴더의 .exe 옆에 있는 .cmd/.bat 래퍼를 실행해 버리는 문제 -
v2.1.323: 와일드카드나 파일 목록을 전달한 파일 읽기 계열의 Bash 명령어가 확인 없이 실행되는 문제를 수정 -
v2.1.321: 네트워크 경로(UNC 공유, WSL 폴더, /net 마운트)에서 Edit / NotebookEdit이 잘못된 부분을 편집하는 문제
• v2.1.325: 모델 피커의 체크 표시가 재부팅 후나 Remote Control에서의 모델 전환 후에 이전 모델에 남아있는 문제를 수정 -
v2.1.325: 노력(effort) 선택이 조직이나 maxEffortLevel 상한을 초과하는 레벨을 제시하는 문제 -
v2.1.323: CRLF 줄 바꿈 파일에서 여러 줄 편집의 diff 탭이 열리지 않는 문제를 수정 -
v2.1.323: 세션 전환 후에도 음성 입력이 녹음을 계속하는 문제
버전별 주요 변경 사항 요약
| 버전 | 주요 토픽 |
|---|
| v2.1.325 | 샌드박스 내 Bash가 기본적으로 권한 흐름을 따르도록 변경 (sandbox.autoAllowBashIfSandboxed) , 스케줄링 작업 / /loop의 스킬 실행 확인, 읽기 전용(read-only) git 확인, MCP 작업 개선, VS Code 프롬프트 후보, zstd 및 Bash 권한 등의 보안 수정 |
| v2.1.323 | Code Mode (실험적), engines["claude-code"] , claude plugin validate의 타입 체크, 알 수 없는 모델 ID의 컨텍스트를 1M으로 가정, 후크(hook)의 하트비트, subagentStatusLine 삭제, v1 MCP 클라이언트 삭제, 대규모 Bash 권한 및 샌드박스 수정 |
| v2.1.322 | Vertex (global / us / eu)에서의 fast mode |
| v2.1.321 | Claude Fable 5.2가 기본 Fable 모델로 추가, claude remote-control --settings ,MCP OAuth의 시크릿 유출 수정, fast mode의 폴백 개선, 시작 시간 단축 |
이번 주요 내용은 Claude Fable 5.2의 추가와 실험적인 Code Mode, 플러그인의 버전 범위 지정(engines["claude-code"])입니다. 한편으로, v2.1.325에서는 샌드박스 내 Bash 명령이 기본적으로 확인을 요구하게 되었으며, 스케줄링 작업이나 /loop에서 allowed-tools를 사용하는 스킬도 확인 대기 상태가 됩니다. 무인 실행(unmanned execution)을 구성하고 있다면 sandbox.autoAllowBashIfSandboxed나 Skill(name)의 allow 규칙을 검토해 두는 것이 안전합니다. v2.1.323의 '알 수 없는 모델 ID를 1M 컨텍스트로 가정하는' 변경 역시 게이트웨이나 타사 벤더의 모델을 사용하는 환경에서는 영향을 미칠 수 있으니 확인해 두시기 바랍니다.
