Claude Code v2.1.314가 출시되었습니다. 이번 버전에는 신규 기능 외에도 기존 설정의 결과가 달라질 수 있는 동작 변경과 보안 관련 수정이 포함되어 있습니다.
주요 포인트는 다음과 같습니다.
permissions.blockWritesOutsideWorkingDirectories 추가 (작업 디렉토리 외부로의 쓰기를 모든 권한 모드에서 금지)forceRemoteSettingsRefresh 및 샌드박스(sandbox), --setting-sources 관련 보안 수정FORCE_HYPERLINK=false의 의미 반전, Bash의 which 처리 등 동작 변경
📌 영향을 받는 사용자
- auto mode나 CI에서 Claude Code를 구동하는 사용자
- 조직 관리 설정(managed settings)을 통해 Claude Code를 배포하는 관리자
- 후크(hook)의
if 조건, FORCE_HYPERLINK, sandbox.excludedCommands를 사용하는 사용자 - Bedrock / Vertex / Foundry / LLM gateway를 통해 이용하는 사용자
새 설정 permissions.blockWritesOutsideWorkingDirectories를 활성화하면 Write, Edit, NotebookEdit 기능이 작업 디렉토리 외부를 가리키는 경로로의 쓰기를 거부합니다. auto mode를 포함한 모든 권한 모드에 적용되므로, 쓰기 범위를 명확하게 구분하는 가드레일(guardrail)로 활용할 수 있습니다.
| 항목 | 내용 |
|---|
| 설정 키 | permissions.blockWritesOutsideWorkingDirectories |
| ... | |
| ⚠️ 주의 | |
| 관리 설정을 사용하는 조직에서는 다음 수정 내용을 확인해 주십시오. | |
| # | 수정 내용 | 영향 |
|---|
| 1 | forceRemoteSettingsRefresh를 원격 관리 설정만으로 지정했을 경우, 저장된 복사본의 만료 후에는 작동하지 않았음 | 서버에 연결할 수 없는 경우, 정책 없이 세션이 시작될 가능성이 있었음 |
| 2 | claude -p --resume / --continue로 진입한 worktree에서 샌드박스가 적용되지 않음 | 보호 장치 없이 동작하고 있었음 |
| 3 | --setting-sources에서 제외한 설정 파일이 auto mode의 규칙이나 저장된 권한 동의를 계속 제공함 | 의도하지 않은 설정이 적용되고 있었음 |
| 4 | Monitor 도구가 시작한 셸 명령어에서 Bash에 매치되는 후크가 동작하지 않음 | 차단이나 확인은 가능하지만, 승인이나 수정은 할 수 없게 되었음 |
| 5 | CI(터미널 있음)에서 claude ultrareview / claude remote-control이 신뢰 확인을 요청함 | CI 설정 시, 신뢰되지 않은 폴더는 즉시 거부됨 |
| 6 | 관리자의 TLS 신뢰 설정이 Claude Desktop 세션에 적용되지 않음 | 수정 완료 |
| 7 | 관리 플러그인 설정 하에서, 자신의 --plugin-dir / --plugin-url 플러그인이 손상되었을 경우 모델 전환이 거부됨 | 수정 완료 |
| 8 | sandbox.excludedCommands의 설명이 잘못되어 있었음 | 후술 |
⚠️ sandbox.excludedCommands의 올바른 동작
설명문은 '열거된 명령어는 항상 샌드박스 외부에서 작동한다'였으나 이는 오류였습니다. 한 번의 호출에 포함되는 모든 명령어가 항목과 일치할 때만 적용됩니다.
⚠️ Breaking Change
기존 설정의 결과가 달라질 수 있는 변경입니다.
⚠️ [IMG:N] 형식 토큰은 이미지 placeholder 입니다. 번역하지 말고 원래 위치에 그대로 유지하세요.
| 대상 | 변경 내용 |
|---|
FORCE_HYPERLINK=false (no ・off도 동일) | 하이퍼링크를 비활성화합니다 (기존에는 활성화되어 있었음). |
Bash 도구의 which | 상속된 which의 별칭(alias) 및 함수를 제거하고, export된 which / unsetenv 함수도 전달하지 않습니다. which는 항상 시스템 명령어 또는 zsh 내장 기능으로만 작동합니다. |
훅 if 조건 | Monitor(tail *)로 작성하면 Monitor 도구의 셸 명령어와 일치하게 됩니다 (Bash(tail *)와 유사). |
| 파일 도구 | 조직의 서버 관리 설정 로컬 복사본을 편집하기 전에 확인 메시지를 요청합니다. |
/ultrareview | git 실행 전에 워크스페이스 신뢰 여부를 확인합니다. |
/permissions의 Recently blocked | 전체 내용을 읽을 수 없는 호출(터미널 높이 부족 포함)에 대한 승인을 거부합니다. |
| Cowork 클라우드의 auto mode | 훅이 MCP 도구 호출을 허용하더라도 '응답 없음'으로 간주하며, 분류기 또는 권한 프롬프트가 판단하게 합니다. |
VS Code와 Claude Desktop의 Code 탭에 추가되었습니다. 20만 토큰 이상의 대화가 유휴 상태(idle)가 되면 요약본을 생성하고, 다음 메시지를 전송할 때 프롬프트 캐시가 만료된 경우 이 요약본을 사용합니다.
- 텔레메트리를 비활성화한 구독자에게도 작동합니다.
- Bedrock, Vertex, Foundry, LLM gateway에서는 1시간 동안 프롬프트 캐시가 유효하면 작동합니다.
- PreCompact 훅의 출력이 매우 클 때 발생하는 압축 실패/반복 문제를 수정했습니다.
각 훅의 출력은 10,000자로 잘립니다.
- 업스트림에
groups
을 지정할 수 있게 되었습니다. 목록에 있는 IdP 그룹의 개발자만 해당 업스트림으로 전송됩니다 (장애 복구 시에도 동일 조건). - Bedrock 업스트림에
guardrail_trace
를 추가했습니다. 발동된 가드레일 필터를 로그에 남깁니다 (일치하는 텍스트는 기록하지 않음). - Google의 토큰 엔드포인트가 응답하지 않을 때 Vertex 업스트림이 몇 분 동안 멈추던 문제를 수정했습니다.
- 더 이상 사용되지 않는 Claude Desktop 키에 대해, 만료일 이후 실행 시 경고 메시지가 'stops being accepted'로 잘못 표시되던 문제를 수정했습니다.
| 현상 | 수정 내용 |
|---|
| 관리자의 effort 상한에서 매 턴마다 'Invalid effort level'이 발생하던 문제 | effort를 낮춰 재시도하고 사용된 레벨을 표시합니다. |
claude -p가 실행 실패해도 종료 코드 0으로 처리되던 문제 | 오류 메시지를 표시하고 종료 코드 1로 처리합니다. |
| 이미지가 많은 Bedrock 세션에서 '400 Input is too long.' 발생하던 문제 | 오래된 이미지를 삭제하여 압축(compaction)을 수행합니다. |
| Foundry에서 기본 Sonnet/Opus/Haiku 배포가 없으면 실패하던 문제 | 동일 계열의 이전 모델로 폴백(fallback)합니다. |
gateway가 tool_reference를 거부하던 문제 | tool search 없이 한 번만 재전송하고, 세션 동안 기억하도록 합니다. |
| gateway가 베타 헤더를 명시적으로 거부하던 문제 | 해당 헤더를 제거하고 다시 전송합니다. |
claude-opus-4.8와 같은 점(dot)으로 구분된 모델 ID가 이전 모델로 취급되던 문제 | 수정되었습니다 (컨텍스트 길이, 출력 상한, effort, thinking, 비용이 올바르게 적용됨). |
시스템 인증서 스토어의 교차 서명 루트에서 UNABLE_TO_GET_ISSUER_CERT 발생하던 문제 | 수정되었습니다. |
그 외에도, --resume 기능이나 거부 후 모델 전환 시 알 수 없는 모델 이름의 세션이 다른 모델로 이동하는 문제, ANTHROPIC_DEFAULT_OPUS_MODEL, availableModels, deniedModels 지정 시 이전 Opus만 남는 경우 재시도 동작, 관리 설정에서 모델 고정 시 Bedrock/Vertex 업그레이드 안내가 매번 표시되던 것도 수정 및 변경되었습니다.
MCP: 저장된 로그인 정보가 무효화된 (로그인이 필요 없는) MCP 서버를 로그아웃 상태에서도 사용할 수 있도록 합니다. claude mcp logout
실패했음에도 성공으로 표시되던 문제 수정 —
auto mode / 권한: 블록 메시지에 대상 명령어 이름과 재확인 필요 여부를 안내하는 /permissions를 표시합니다. 리뷰 탭은 'Recently blocked'로 이름이 변경되었습니다. 안전 검사(safety check)가 판단을 반환하지 않은 호출을 차단 처리하던 문제를 수정했습니다.
세션: 사용 한도 도달 시 자동 계속('Continue automatically at usage limit') 기능이 3회를 초과하여 자동으로 지속되는 문제, 비활성화했던 Ultracode가 다시 활성화되는 문제 등을 수정했습니다.
성능: 다수의 서브 에이전트를 사용하는 헤드리스(headless)/SDK 트랜에서 메모리를 절감하고, --resume /context의 속도를 높였으며, .trash의 비대화(약 1024개에서 제한) 및 git의 index.lock 충돌을 수정했습니다. macOS에서는 git grep을 C 로케일로 실행합니다.
클라우드 세션: 예약 작업이 claude.ai 계정에서 유효한 플러그인을 읽도록 변경되었습니다. 설정 스크립트가 오류 종료되어도 세션이 시작됩니다.
Remote Control / Cowork: 워커 등록 재시도, Cowork의 WebFetch가 PDF 파일에서 100,000자 이상의 내용을 조용히 버리던 문제 등을 수정했습니다.
VS Code: CLAUDE_CODE_DISABLE_CFC_PROMPT 설정이 Claude in Chrome에 추가되는 지침까지 막도록 변경되었습니다(브라우저 도구 자체는 사용 가능).
내장 스킬/TUI/Claude Tag (Slack): 사소한 수정과 개선 사항이 다수 포함되었습니다.
💡 팁
작성 범위(쓰기 권한)를 엄격하게 제한하고 싶다면, permissions.blockWritesOutsideWorkingDirectories를 활성화한 후 샌드박스(sandbox)와 함께 사용하는 것이 안전합니다.
관리자: forceRemoteSettingsRefresh의 운영 방식, --setting-sources의 동작, TLS 설정이 이번 수정으로 예상대로 작동하는지 확인해야 합니다.
: FORCE_HYPERLINK를 설정한 경우 false의 의미가 반전되었으므로 값을 재검토해야 합니다.
: Bash 툴 내에서는 항상 시스템 버전이 되는 점을 고려하여 which의 별칭(alias)이나 함수를 사용하는 사용자는 주의해야 합니다.
훅(Hook): if문을 작성하는 경우, Monitor(...) 형식으로 셸 명령어와 일치하게 되었으므로 의도하지 않은 일치가 없는지 확인해야 합니다.
: 한 번의 호출 내 모든 명령어가 일치할 필요가 있다는 전제하에 규칙을 재검토하는 sandbox.excludedCommands를 사용하는 사용자는 주의해야 합니다.
CLAUDE.md를 관리하는 사용자: 다음 항목 추가를 고려해 보세요(후술).
Bedrock / Vertex / Foundry / gateway 이용자: 업데이트 후 알려진 오류가 해결되었는지 확인하십시오.
{
"permissions": {
"blockWritesOutsideWorkingDirectories": true
...
}
# 이전: 하이퍼링크가 켜져 있었음
# 이후 : 하이퍼링크가 꺼짐(no / off도 마찬가지)
export FORCE_HYPERLINK=false
{
"hooks": {
"PreToolUse": [
...
}
훅 구성은 예시일 뿐입니다. 실제 설정은 사용자의 환경에 맞게 조정해야 합니다. Monitor 도구 실행의 셸 명령어에서는 차단이나 확인은 할 수 있지만, 승인하거나 수정할 수는 없습니다.
## 권한/보안 설정
- permissions.blockWritesOutsideWorkingDirectories로 작업 디렉터리 외부로의 쓰기를 방지합니다(전체 권한 모드에서 활성화).
- sandbox.excludedCommands는 한 번의 호출에 포함된 모든 명령어가 항목과 일치할 때만 작동합니다.
...
신규 기능: permissions.blockWritesOutsideWorkingDirectories로 전체 권한 모드에서 작업 디렉터리 외부로의 쓰기를 방지할 수 있습니다.
보안 수정: forceRemoteSettingsRefresh
worktree의 샌드박스(sandbox), --setting-sources 등의 제외 누락 등이 수정되었습니다. 관리 설정을 사용하는 조직은 특히 확인이 필요합니다.
행동 변경: FORCE_HYPERLINK=false의 반전, which의 고정, 훅(hook)의 Monitor(...) 일치 등 기존 설정의 결과가 달라질 수 있습니다.
문서 오류: sandbox.excludedCommands는 "모든 명령어가 일치"했을 때만 작동합니다.
호환성: Bedrock, Vertex, Foundry, LLM gateway 주변에서 노력(effort) 상한, 이미지 과다, 점 구분 모델 ID 등 다수의 문제가 수정되었습니다.
idle compaction: 긴 대화 재개 시 캐시 만료 비용을 줄일 수 있습니다.
업데이트 후에는 먼저 위에 언급된 행동 변경에 해당하는 설정이 없는지 확인하는 것을 권장합니다.
