Claude Code v2.1.318이 출시되었습니다. 신규 기능(예: Claude apps gateway의 assume_role 지원 등) 외에도, 운영 중인 환경을 손상시킬 수 있는 3건의 파괴적 변경 사항이 포함되어 있습니다. 또한, 공유 네트워크 홈에서의 설정 소실, 세션 지속성 문제, 헤드리스 실행에서 실패가 성공으로 처리되는 문제 등 중요한 버그 수정도 다수 이루어졌습니다.
본 기사에서는 심각도가 높은 항목들을 중심으로 '무엇이 바뀌었는지', '누가 영향을 받는지', '무엇을 해야 하는지'를 정리합니다.
📌 영향 받는 사용자
- 셀프호스트 러너의 로그를 모니터링하거나 파싱하는 사람
- IDE 터미널에서 Claude Code를 실행하여 확장을 자동으로 도입하던 팀
deniedMcpServers로 MCP 서버를 제한하는 관리자- 공유 네트워크 홈(NFS 등)에서 Claude Code를 사용하는 사람
/agent SDK를 CI나 자동화에 통합하는 사람
| 구분 | 건수 | 주요 내용 |
|---|
| 파괴적 변경 | 4 | 로그 형식, IDE 확장, MCP 거부 설정, 서브 에이전트 동작 |
| ... | | |
오케스트레이터의 ok session=…와 nack session=… 형식이 바뀌고 출력 위치도 달라졌습니다.
| 항목 | 변경 전 | 변경 후 |
|---|
ok session=…의 출력 위치 | debug 레벨일 때만 stderr | 모든 로그 레벨에서 stdout |
ok session=…의 끝부분 | jti=… | jti=… 뒤에 reason=… 추가 |
nack session=…의 끝부분 | retryable=…: 형식 | retryable=… 뒤에 reason=…으로 종료 |
⚠️ Breaking Change (파괴적 변경)
retryable=true: / retryable=false:와 일치하도록 설정된 로그 모니터링 및 파싱 스크립트는 작동하지 않게 됩니다. 알림이 조용히 발생하지 않아 인지하기 어렵다는 점이 가장 위험합니다.
IDE 터미널에서 Claude Code를 실행해도 IDE 확장 기능의 자동 설치/자동 업데이트는 수행되지 않습니다. 확장을 추가하려면 다음 중 하나가 필요합니다.
- 외부 터미널에서
/ide 실행
- 에디터의 확장 기능 뷰에서 추가
URL 엔트리는 업스트림 URL이 일치하는 Anthropic 제공 서버와 클라우드 세션/셀프호스트 러너 커넥터에도 적용됩니다.
⚠️ Breaking Change (파괴적 변경)
기존에 사용하던 서버나 커넥터가 기존의 거부 설정으로 인해 차단될 수 있습니다.
- 'Switch models when a message is flagged'가 'Ask each time'일 때, 서브 에이전트는 모델을 전환하지 않고 중지합니다. 도중에 멈추는 경우가 발생할 수 있습니다. - 2.1.286 이전의 대화를 재개하면, 이전에 진행된 thinking이 폐기될 수 있습니다 (2.1.288 수정 사항 철회).
| 기능 | 개요 |
|---|
gateway mantle upstrem의 assume_role | 다른 AWS 계정의 역할을 사용할 수 있습니다. 개발자별 AWS 비용 분배에도 활용 가능 |
$.model.fork의 effort | 세션의 effort와 무관하게, 가벼운 사이드 작업을 low로 실행할 수 있음 |
| 로그인 만료일 표시 | claude auth status (loginExpiresAt), claude -p의 JSON (credential_expires_at). 만료 10일 전부터 stderr에 경고 출력 |
| 클라우드 세션 | 'No repository' 옵션, Chrome 이름(google-chrome, CHROME_PATH) 추가 |
CLAUDE_RUNNER_SPAWN_REASON | spawn-runner hook에 시작 이유(runner_lost, resumed 등)를 전달 |
mod의 경우, prompt.submit
또한, mod가 첨부한 내용이 시스템 메시지가 아닌 사용자 턴(turn) 내에 남게 된 점에도 주의해야 합니다.
공유 네트워크 홈(Shared Network Home): 설정 파일 업데이트 실패 시에도 /logout,
claude auth logout,
claude mcp remove가 성공으로 표시되었고, 신뢰(trust)・동의・MCP 설정이 알림 없이 손실되던 문제가 수정되었습니다. 그 외에도, 다른 호스트에서 재로그인 시 Not logged in 상태가 되거나, claude mcp add/remove가 잠금(lock)을 가져가지 않거나, 저장된 로그인 정보가 용량 부족으로 빈 파일이 되는 등의 문제들이 수정되었습니다. 다만, claude mcp add/remove는 다른 작업(job) 저장 시 저장된 서버가 덮어쓰여질 가능성은 남아 있습니다.
- 비대화형 시작(non-interactive startup) 시 유효하지 않은 JSON 파일이 기본값으로 덮어쓰여지던 문제(#87551)가 수정되었습니다. 이제는 실행 실패를 발생시키고 복구 방법을 표시하며, 파일은 그대로 유지됩니다.
~/.claude.json
- 세션 지속성(Session Continuity): 유효하지 않은 도구 호출(tool call) 재시도 한계 초과 후
--continue가 대화를 잃는 회귀 문제(2.1.314), 비활성화 상태에서의 압축(compaction)이 요약이 아닌 답변으로 대체되던 등의 문제가 수정되었습니다.
- 헤드리스/SDK: mod가
turn.step을 후킹하고 있을 경우, API 오류로 인해 답변이 끊겨도 claude -p와 Agent SDK가 성공했다고 보고하던 문제가 수정되었습니다.
- 권한 프롬프트(Permission Prompt): 메시지 전송 직후 등의 선행 입력 키에 의해 답변되는 문제를 수정했습니다 (의도치 않은 승인 방지).
- 재시작 후 쉘 명령어: 셀프호스트 러너/클라우드 세션 재시작 후, 승인된 쉘 명령어가 지정 폴더가 아닌 세션 시작 폴더에서 실행되던 문제가 있었습니다. 이제는 해당 폴더에 있지 않으면 실행하지 않습니다.
- 바이너리 삭제(Binary Deletion): 업데이트나 정리 과정에서 실행 중인 바이너리가 사라져
claude remote-control 호스트나 러너가 spawn ENOENT로 새 세션을 시작할 수 없게 되던 문제를 수정했습니다.
| 대상 | 액션 |
|---|
| 러너 운영자 | 로그 모니터링 패턴 수정, stdout 수집 확인 |
| ... | deniedMcpServers의 URL 항목 정리 및 동작 확인 |
| 공유 홈 사용자 | 업데이트 후 ~/.claude.json 또는 인증 상태 확인 |
| CI/자동화 담당 | credential_expires_at을 이용한 만료 감시 도입 |
💡 팁
'Ask each time'에서 서브 에이전트가 멈추는 경우, 설정을 검토하거나 중지해도 문제가 없는 운영인지 확인해야 합니다. --release-idle-session-min이 값이 없거나 마지막 인자 또는 공백만인 경우, 시작 시 경고 메시지가 표시되도록 변경되었습니다.
retryable=true:와 같이 콜론(:)으로 일치시키던 경우에는 끝 부분이 reason=…로 바뀌는 점에 대응해야 합니다. 실제 로그 전문은 데이터에 포함되어 있지 않으므로, 정규 표현식은 자체 환경의 로그에서 확인해 주십시오.
# 이전: 콜론(:)으로 일치 (v2.1.318 이후로는 일치하지 않음)
grep -E 'nack session=.*retryable=(true|false):' runner.log
# 이후: 콜론에 의존하지 않고 retryable 값만 확인
...
또한, ok session=…는 stdout으로 출력되게 되었기 때문에, stderr만 수집하는 구성에서는 보이는 방식이 달라집니다.
# 만료 확인 (loginExpiresAt 포함)
claude auth status
# JSON 출력을 통해 credential_expires_at을 가져와 판별에 이용
...
만료된 경우에는 claude auth login 또는 claude setup-token으로 재인증해야 합니다.
{
"deniedMcpServers": [
{ "serverUrl": "https://example.com/mcp" }
...
}
위와 같은 URL 항목은 클라우드 세션 및 셀프호스트 러너에서는 커넥터에도 적용됩니다. 그 외의 환경에서는 이름으로 거부됩니다. 설정 키의 정확한 형식은 공식 문서를 확인해 주십시오.
- 최우선: 셀프호스트 러너의 로그 형식 변경 (
ok 출력지 및 reason= 추가, nack 끝 부분 변경). 모니터링 스크립트가 조용히 고장 날 수 있습니다. -
설정 절차 재검토: IDE 터미널에서의 확장 자동 도입 기능이 폐지되었습니다. 이제 /ide 또는 확장 기능 뷰를 사용해야 합니다. -
MCP 거부 설정 재점검: deniedMcpServers의 URL 항목은 Anthropic 제공 서버 및 클라우드/러너 커넥터에 영향을 미칩니다. -
개선 사항: 공유 네트워크 홈 설정 사라짐, ~/.claude.json 덮어쓰기 방지, --continue 회귀(regression) 수정, 헤드리스 환경의 오탐 성공 보고 수정, 선행 입력으로 인한 오승인 등 다수의 중대한 버그가 수정되었습니다. -
신규 기능: assume_role, fork의 effort 지정, 로그인 만료 기간 가시화는 엔터프라이즈 또는 CI 운영에 유용합니다.
업데이트를 적용하기 전에 상단의 플로우차트를 통해 자신의 환경이 해당되는지 확인하는 것을 권장합니다.
