2026년 11월 13일에 공개된 Claude Code v2.1.325는 zstd 압축 응답의 디코드 처리와 관련된 보안 수정 외에도, 권한(permission)과 샌드박스 관련 부분이 대폭 강화된 릴리스입니다.
특히 다음 두 가지 사항은 설정을 변경하지 않으면 자동화가 중단될 수 있습니다.
- 샌드박스 내의 Bash가 기본적으로 일반적인 권한 확인을 요구하게 되었습니다.
/loop나 스케줄링 작업에서 allowed-tools 또는 hooks를 선언한 스킬을 실행하기 전에 확인 절차가 추가되었습니다.
📌 영향을 받는 사용자
- CI(지속적 통합)나 야간 배치 등, 무인으로 Claude Code를 구동하는 사용자
- 관리형 설정에서 샌드박스를 활성화한 조직의 관리자
/loop
또는 스케줄링 작업에서 스킬을 사용하는 사용자
- Agent SDK, self-hosted runner, worktree 분리를 사용하는 사용자
pluginDigests 또는 마켓플레이스의 ref 고정을 사용하는 조직
상세한 취약점 내용은 공개되지 않았습니다. 우선 업데이트를 진행하고, 그 후에 설정을 검토해 주십시오.
| 우선순위 | 변경 사항 | 대응 방안 |
|---|
| 최우선순위 | zstd 디코드 보안 수정 | 업데이트 |
| ... | permissions.allow 재검토 | - |
| 높음 | 샌드박스・worktree・self-hosted runner 보호 강화 | 후크 및 운영 확인 |
| 높음 | 권한 규칙・샌드박스의 허점 수정 | 기본적으로는 업데이트만으로 충분 |
| 높음 | 인증・과금 관련 수정 | 이용 상황 확인 |
| 보통 | pluginDigests 사용 중단, ref의 커밋 ID 대응 | 조직 설정 및 클라이언트 버전 수 확인 |
릴리스 노트 시작 부분에 “Fixed a security issue in how zstd-compressed responses are decoded”라고 기재되어 있습니다. 자세한 내용은 공개되지 않았습니다. 보안 수정이므로 신속한 업데이트가 권장됩니다.
⚠️ Breaking Change
샌드박스 내의 Bash 명령어는 기본적으로 일반적인 권한 흐름을 거치게 되었습니다.
기존처럼 확인 과정 없이 실행하려면, sandbox.autoAllowBashIfSandboxed: true 설정을 해야 합니다.
관리형 설정에서 샌드박스를 활성화한 조직도, 확인 절차 없이 계속 실행하려면 가장 우선순위가 높은 관리형 설정 소스에 이 설정을 작성해야 합니다. 샌드박스를 전제로 하는 무인 실행이나 자동화는 확인 대기 상태에서 중단될 수 있습니다.
| 항목 | 새로운 동작 방식 | 조치 사항 |
|---|
| 신뢰하지 않는 리포지토리에서의 읽기 전용 git | 확인을 요구함 | additionalDirectories 대신 --add-dir로 지정 |
스케줄링 작업・/loop에서 allowed-tools / hooks 선언이 포함된 스킬 실행 | 실행 전에 확인 절차를 거침 | permissions.allow에 Skill(name) 추가 |
| Desktop・IDE・SDK 호스트의 “항상 허용” 설정 | 규칙 단독 저장 시, 같은 명령어가 다시 허용되는 경우에만 표시됨 | 의존하던 스케줄링 작업이 응답 대기 상태에서 멈추지 않는지 확인 |
슬래시 명령어의 allowed-tools | 해당 턴 중・후에 시작된 백그라운드 에이전트에도 적용되던 문제 수정 | 조치 불필요 (원치 않는 허용 범위 확대가 해소됨) |
- 추가 디렉토리 내의
.claude (settings・skills・agents・commands・hooks)로의 샌드박스 쓰기는, 시작 폴더와 마찬가지로 거부됩니다. - 분리된 worktree에서는 git bisect run, git maintenance register|start, scalar 등의 설정 명령이 거부되며(대체 작업 안내), - EnterWorktree는 프로젝트 내 심볼릭 링크를 경유하는 WorktreeCreate
Hook 경로 거부. Hook은 실제 경로를 출력해야 합니다 - self-hosted runner는 세션 폴더나 리포지토리 경로가 심볼릭 링크인 세션을 거부합니다 (checkout hook의 checkout 제외).
- 샌드박스가 자체적으로 실행하는 프로그램(네트워크 브릿지 등)의 환경에서, sign-in 토큰과 API 키를 제외함.
- ripgrep, 로컬 git, 샌드박스 런타임 보조 프로그램의 환경에서, mTLS 클라이언트 키의 패스프레이즈를 제외함.
- 컨테이너에 마운트된 worktree나 서브모듈에서
-p
또는 SDK를 실행하는 경우, .claude/settings.local.json의 allow 규칙은 폴더가 신뢰됨(trusted)으로 지정된 후에 적용됩니다.
주요 변경 사항을 정리합니다.
| 분류 | 수정 내용 |
|---|
| Bash | 일부 복합 명령어가 확인 없이 실행될 수 있던 허점을 수정했습니다 (향후에는 확인 필요). |
| ... | mcp__plugin_*_ 규칙이 대소문자가 다른 MCP 서버 이름/도메인에 일치하지 않던 문제를 수정했습니다. |
| 규칙 해석 | self-hosted runner와 claude remote-control에서, 재시작 후 허가 승인이 deny로 적용되지 않던 문제를 수정했습니다. |
| 규칙 해석 | 일부 서브폴더에서 시작할 경우, 커밋된 .claude/settings.local.json이 사용자 본인의 설정으로 처리될 수 있던 문제를 수정했습니다. |
| 샌드박스 | 명령어가 네이티브 업데이트 다운로드 폴더에 쓸 수 있는 케이스를 수정했습니다. |
| ... | /feedback과 /bug는 sign-in 중인 계정/조직이 기록한 세션만 업로드합니다. |
| 기타 | 이메일 주소를 클라이언트 식별자로 사용하는 것도 거부함. |
Read(./.env)와 같은 deny 규칙이 cd 이후에 적용되지 않던 문제는 기밀 파일 보호에 직결되므로, 해당 구성의 사용자는 특히 중요하게 확인해야 합니다.
- claude.ai 로그인 백그라운드 세션이, 백그라운드 서비스를 시작한 셸의 API 키나 토큰으로 과금되던 문제를 수정했습니다.
allowedProviders가 허용하지 않았음에도 불구하고, Bedrock의 토큰 계산에 대화가 Bedrock으로 전송되던 문제를 수정했습니다. -
HOME이 설정되지 않아 AWS credential_process와 Google Cloud 기본 인증 정보가 실패하던 문제를 수정했습니다. -
claude auth status 같은 짧은 명령어가 콘솔 프로파일에 잠금(lock)을 남겨 다음 세션이 약 1분 동안 지연되던 문제를 수정했습니다 - 캐시된 계정 데이터가 없는 경우, claude -p는 첫 번째 요청 전에 해당 데이터를 기다리기 때문에, 클린 환경에서의 최초 실행 시 몇 초간 지연될 수 있습니다.
⚠️ Breaking Change
마켓플레이스의 ref에 전체 커밋 ID를 지정할 수 있게 되었습니다. 다만, 이 버전보다 이전의 클라이언트는 이 형식으로 고정된 마켓플레이스를 읽을 수 없습니다.
-
ALL_PROXY만 설정되어 있는 경우, 플러그인과 마켓플레이스 다운로드는 CONNECT 터널을 사용합니다. CONNECT를 거부하는 프록시에서는 실패합니다 -
pluginDigests는 더 이상 권장되지 않으며 무시됩니다. 관리형 설정(managed settings)으로 선언 및 활성화된 prependPlugins 또는 appendPlugins에 나열된 원격 마켓플레이스 플러그인은 조직의 플러그인으로 취급됩니다 - MCP 번들(.mcpb, .dxt)의 배포 위치가 플러그인 폴더 내의 .mcpb-cache에서 플러그인 디렉토리 하위로 변경되었습니다. URL 가져오기 번들은 한 번만 재다운로드됩니다 -
--plugin-dir로 읽어오는 플러그인 내부의 .claude/skills는 상위 폴더에서 시작된 세션에서는 로드되지 않습니다.
-
Agent SDK: applyFlagSettings()에 잘못된 값이 하나라도 있으면, 이전에 설정한 모든 것이 조용히 폐기되던 문제를 수정했습니다. 이제는 오류로 거부됩니다 -
모델 설정: opusplan / haiku
설정 시, 사용자 지정 모델을 지정한 서브 에이전트가 플랜 모드용 모델로 전환되는 문제 수정. 또한, 타사 게이트웨이나 Foundry에서 매 턴(turn)마다 컨텍스트 길이 오류(context length error)가 발생하던 문제도 수정됨.
MCP: 백그라운드 MCP 작업 질문 중 Esc 키를 누르면 '나중에 답변'으로 처리되고, 질문은 /tasks에 남아있게 됨.
VS Code 확장: 프롬프트 후보(Tab 키로 채택, promptSuggestionEnabled: false 설정 시 비활성화) 기능과 API 키 생성을 요구하지 않는 콘솔 로그인 기능을 추가함.
Remote Control: claude remote-control은 사용자가 직접 중지할 경우 종료 코드 4를 반환하고, 등록할 수 없을 경우 69를 반환하도록 변경됨.
비용 집계: /cost, --max-budget-usd 등이 모듈의 $.model.complete / $.model.classify에서도 집계되도록 개선됨.
전체 사용자: zstd 수정으로 인해 v2.1.325로 업데이트할 것.
무인 실행/CI: 샌드박스 내 Bash가 확인을 기다리며 멈추지 않는지 검증할 것.
조직 관리자: 확인 절차 없이 실행을 계속하고 싶다면, 최우선으로 설정된 관리형 설정 소스에 sandbox.autoAllowBashIfSandboxed: true를 추가해야 합니다. 다만, 자동 허용이 의도한 위험 범위 내인지 먼저 판단해야 합니다.
스킬 사용자: /loop
・스케줄 작업에서 사용할 스킬을 permissions.allow에 등록할 것.
외부 리포지토리 사용 사용자: 읽기 전용(read-only) git도 검사 대상입니다. --add-dir로 지정해 주세요.
worktree 사용자: WorktreeCreate
훅이 실제 경로(실경로, real path)를 출력하는지, 또는 git bisect run과 같은 작업을 분리된 worktree에서 사용하고 있지 않은지 확인할 것.
플러그인 관리자: pluginDigests
를 검토해야 합니다. 커밋 ID가 고정된 마켓플레이스는 모든 멤버가 v2.1.325 이상 버전임을 확인한 후에 도입할 것을 권장합니다.
프록시 환경: ALL_PROXY
구성만으로 CONNECT가 허용되어 있는지 확인할 것.
SDK 사용자: applyFlagSettings()에 오류 처리를 추가해야 합니다.
💡 팁
업데이트 직후에는 무인 작업을 실제 운영 환경에 배포하기 전에 한 번 수동으로 실행하여, 확인 프롬프트에서 멈추지는 않는지 확인하는 것이 안전합니다.
이전 버전(v2.1.325 이전): 샌드박스가 활성화되어 있으면 별도의 확인 없이 실행되었습니다.
{
"sandbox": {
"enabled": true
...
}
현재 버전(v2.1.325 이후): 확인 절차를 유지하려면 명시적인 설정이 필요합니다.
{
"sandbox": {
"enabled": true,
...
}
조직의 관리형 설정에서는 가장 우선순위가 높은 관리형 설정 소스에 작성해야 합니다.
{
"permissions": {
"allow": [
...
}
my-release-check는 예시입니다. allowed-tools나 hooks를 선언한 스킬 이름으로 대체해 주세요.
# Before: additionalDirectories 설정에서 지정
# After: --add-dir로 시작 시 지정
claude --add-dir /path/to/other-repo
아래는 오류로 인해 거부되는 것을 예상한 작성 예시입니다. 실제 타입이나 반환 값은 SDK 문서를 확인해 주세요.
query.applyFlagSettings(settings);
...
Sandbox / Permissions
-
샌드박스 내부의 Bash는 기본적으로 허가 확인을 요청합니다.
-
자동 허가를 유지하려면 settings.json (조직에서는 최우선 관리형 설정)에
...
-
v2.1.325 버전은 **zstd 디코딩 보안 수정(security fix)**을 포함하고 있으므로, 먼저 업데이트해 주십시오.
샌드박스 내 Bash는 기본적으로 허가 확인(permission confirmation)이 필요하게 되었습니다. 무인 실행 시에는 sandbox.autoAllowBashIfSandboxed: true의 필요 여부를 판단해야 합니다.
- 스케줄러 작업(scheduler task)의 스킬은
permissions.allow에 Skill(name)이 필요합니다.
- worktree, self-hosted runner, 샌드박스의 보호가 강화되었으며,
WorktreeCreate 후크는 실제 경로 출력(absolute path output)이 필수입니다.
pluginDigests는 사용 중단 권고(deprecated)되었습니다. 커밋 ID 고정 마켓플레이스는 구형 클라이언트에서는 로드할 수 없습니다.
Bash의 허가 체크 누락, deny/ask 규칙 미적용, 결제 오류 등 보안 및 결제와 관련된 수정이 다수 포함되어 있습니다.
자세한 내용은 공식 릴리스 노트(Official release notes)를 확인해 주십시오.
