-
2026년 10월 22일부터 11월 4일까지의 Claude Code (v2.1.309~v2.1.318)에는 여러 기능이 추가되었습니다. cron이나 CI 환경에서 무인 실행하는 경우, 이 기간 동안 업데이트된 내용이 가장 유용합니다.
-
'실패했음에도 불구하고 exit 0'을 반환하는 문제를 해결한 수정 사항: 대화 측면에서는 [기능]으로 변경되었습니다. 또한, 비활성화할 환경 변수와 서브 에이전트의 effort를 개별적으로 설정할 수 있는 환경 변수가 추가되었습니다.
-
ultrathink가 Opus 5.5 / Sonnet 5.5 / Haiku 5.5 / Fable 5.1에서 턴을 xhigh effort로 구동합니다.
-
안전성 측면의 변경 사항으로, 작업 디렉터리 외부로의 쓰기를 모든 모드에서 거부하는 설정과 계정 이메일 주소를 네트워크에 전송하기 전에 확인하는 체크가 추가되었습니다. 반면, sed -i는 /rewind를 통해 되돌릴 수 없게 되었습니다.
공식 changelog에는 이 2주 동안 v2.1.309부터 v2.1.318까지의 내용이 나와 있습니다 (페이지 상에서는 v2.1.313과 v2.1.315 항목을 찾을 수 없었습니다).
| 버전 | 날짜 |
|---|
| 2.1.309 | 2026-10-22 |
| ... | |
| Enterprise용 gateway나 Claude Tag (Slack 연동), 클라우드 세션 관리 화면 주변에 많은 변경이 있었습니다. 여기서는 개인 개발자가 Claude Code를 사용하는 입장에서 유용한 내용만 추려 정리했습니다. | |
참고로, 제가 가지고 있는 Claude Code는 이 글을 작성하는 시점에서는 v2.1.296이었습니다. 아래 내용은 changelog의 설명을 해석한 것이며, 모든 항목을 직접 재현한 것은 아닙니다. 지난번(9월분) 요약은 여기입니다.
이 기간 동안 가장 중요한 것은 다음 부분이라고 생각합니다. claude -p (헤드리스 실행)가 실패했음에도 불구하고 종료 코드 0을 반환하는 패턴이 연달아 수정되었습니다.
| 버전 | 수정 내용 (changelog 요약) |
|---|
| 2.1.314 | 시작에 실패했을 때 아무것도 출력하지 않고 exit 0 하던 문제 → 에러를 출력하고 exit 1로 변경 (2.1.316에도 동일한 문구 기재 있음) |
| ... | |
cron에서 claude -p ... && 다음 처리와 같이 종료 코드로 분기하는 경우, 이전에는 '시작조차 하지 않았는데 성공'할 수 있었습니다. 쉘 관점에서는 성공으로 간주되어 후속 처리가 그대로 실행되었습니다. | |
2.1.317의 주석에는 'Full NFS exports may be missed'라고 되어 있어, NFS 용량 부족은 감지하지 못하는 경우가 있는 것 같습니다. 홈 디렉터리를 NFS에 두고 있다면 계속 주의가 필요합니다.
claude.ai 구독으로 로그인 상태를 유지한 채 claude -p를 무인으로 실행하면, 어느 날 로그인 기한이 만료되어 멈추는 경우가 있습니다. v2.1.318에서는 이에 대한 사전 감지 수단이 늘어났습니다.
claude auth status에 loginExpiresAt (저장된 로그인 기한)이 표시됨 -claude -p의 JSON 결과에 credential_expires_at가 포함됨 -claude -p의 텍스트 출력에서, 기한 만료 10일 전부터 stderr에 경고 메시지가 한 줄씩 나옴. 기한 만료로 로그인에 실패했을 때는 그 사실을 표시함.claude -p에서는 claude auth login과 claude setup-token을 안내함
관련하여 2.1.317에서는 claude auth status가 토큰 업데이트 저장을 기다리지 않고 종료되어, 다음 실행 시 로그아웃되는 버그도 수정되었습니다. 로그인 상태를 감시하기 위해 claude auth status를 주기적으로 실행하는 경우에도 유효합니다.
제가 가지고 있는 v2.1.296으로 claude auth status를 실행해보니, loggedIn이나 subscriptionType은 나오지만, 기한 관련 필드는 아직 없었습니다. JSON 출력을 파싱하여 감시하고 있다면, credential_expires_at을 확인하여 며칠 전에 알림을 보내는 것이 가장 자연스러운 사용법이라고 생각합니다.
제가 만든 투자 분석 도구의 일일 배치 작업은 이미 claude -p
Anthropic API로 마이그레이션되었습니다. 구독(subscription)의 로그인 기한에 얽매이고 싶지 않은 것도 이전 이유 중 하나였습니다. 그럼에도 불구하고 claude -p를 사용하여 무인으로 운영을 계속하려면, 이번 업데이트는 반드시 적용해 두어야 합니다.
2.1.311 버전부터 터미널에서 ultrathink를 입력하면, Anthropic API를 경유하는 Opus 5.5, Sonnet 5.5, Haiku 5.5, Fable 5.1 모델의 경우 해당 턴을 xhigh effort로 실행하게 되었습니다. Claude가 작업하는 도중에 이 명령어를 사용하면, 해당 턴의 남은 effort 값이 증가합니다.
또한, 무지개색 하이라이트는 effort를 실제로 끌어올릴 수 있는 위치에서만 표시되도록 변경되었습니다. 인용된 ultrathink나 파일 경로 일부에 포함되어 있을 경우에는 반응하지 않습니다. 2.1.316 버전에서는 VS Code 확장 기능도 동일한 동작을 보입니다.
관련 환경 변수도 두 가지 추가되었습니다.
| 환경 변수 | 추가 버전 | 내용 |
|---|
CLAUDE_CODE_DISABLE_ULTRATHINK | 2.1.316 | ultrathink 키워드를 비활성화합니다. |
CLAUDE_CODE_SUBAGENT_EFFORT | 2.1.316 | 별도로 지정하지 않은 경우, 서브 에이전트를 실행할 effort를 결정합니다 (기존에는 세션의 effort를 상속받았습니다). |
2.1.317 버전부터는 메인 대화와 다른 모델로 작동하는 서브 에이전트나 팀메이트가 해당 모델에 저장된 effort(없으면 기본값)를 사용하게 되었습니다. 더 이상 세션의 effort를 상속받지 않습니다. 메인을 max로 실행하고 있더라도, 다른 모델을 사용하는 서브 에이전트가 세션의 max 값에 끌려가지 않게 됩니다.
5.5세대 모델은 adaptive thinking(적응형 사고)을 전제로 하며, 깊이를 조절하는 주요 스위치는 effort입니다. 특히 Opus 5.5와 Fable 5.1은 thinking 기능을 비활성화할 수 없습니다. 따라서 '어떤 에이전트를 어떤 effort로 실행할지'가 비용에 직결됩니다. 조사 목적의 서브 에이전트는 low로, 메인은 high처럼 의도적으로 분리하여 설정할 수 있게 된 점이 큰 개선점입니다.
permissions.blockWritesOutsideWorkingDirectories가 추가되었습니다. 이 기능을 활성화하면 Write, Edit, NotebookEdit 모두 어떤 권한 모드에서도 작업 디렉터리 외부 경로에 대한 쓰기를 거부합니다.
auto 모드나 bypass로 장시간 실행할 경우, 홈 디렉터리의 점 파일(dotfile)이나 다른 리포지토리가 수정되는 것이 우려될 수 있습니다. 이를 설정 한 줄로 막을 수 있습니다. 다만 대상은 Write, Edit, NotebookEdit의 3가지 도구에 국한되므로, Bash를 경유하는 쓰기 작업까지는 막지 못한다는 점에 유의해야 합니다.
웹 도구나 셸 도구를 호출할 때 계정의 이메일 주소를 네트워크로 전송하려 할 경우 확인 절차를 거치게 되었습니다. 이는 프롬프트 인젝션(Prompt Injection)을 통해 이메일 주소 같은 민감 정보를 외부로 유출시키려는 공격에 대한 방어책으로 보입니다.
클라우드의 주기적 실행 작업을 새로 만들 때, 요청하지 않은 커넥터가 붙어 있으면 경고 메시지를 표시하고 제거 방법을 안내하도록 변경되었습니다.
기존에는 sed -i 명령어가 파일 편집의 미리 보기처럼 특수한 취급을 받았습니다. 2.1.309 버전부터는 일반 Bash와 동일한 권한 프롬프트로, 입력한 대로 실행됩니다. 대신, 다른 Bash를 통한 편집과 마찬가지로 /rewind로는 되돌릴 수 없습니다.
만약 'sed로 일괄 치환을 한 후, 마음에 안 들면 rewind'라는 방식으로 사용했다면, 이제는 Git으로 되돌리는 것을 전제로 워크플로우를 변경해야 합니다. 또한, 동일한 파일을 변경 없이 다시 읽었을 때 '이전과 변경 없음'이라는 짧은 응답만 하던 기능이 삭제되었습니다. 앞으로는 매번 내용 전체가 반환됩니다. 이는 컨텍스트상의 판단 실수는 줄여줄 수 있지만, 같은 대용량 파일을 여러 번 읽게 되면 토큰 소모가 커집니다.
백그라운드 서브 에이전트가 실행한 셸 명령어는 모든 프로바이더에서 3분이 경과하면 백그라운드로 전환됩니다. changelog에는 'so the prompt cache doesn't expire while it runs(실행되는 동안 프롬프트 캐시가 만료되지 않도록)'라고 명시되어 있습니다. 이는 긴 테스트나 빌드를 기다리는 동안 프롬프트 캐시가 만료되어 재개 시 캐시 미스(cache miss)로 인해 비용이 급증하는 것을 방지하기 위함입니다.
사용량 제한 메시지에서 'session limit'이라고 불리던 것이 '5-hour limit'으로 변경되었습니다. VS Code에서는 리셋 시점이 'Resets at 3:10 PM'과 같은 시간 표시로 나타납니다. 동작 방식의 변화는 아니지만, '세션(Session)'이라는 단어가 대화 세션과 혼동될 수 있어 명확해졌습니다.
VS Code와 Claude Desktop의 Code 탭에서 20만 토큰을 초과하는 대화를 방치할 경우 요약본이 생성되도록 변경되었습니다. 프롬프트 캐시(Prompt cache)가 만료된 상태로 다음 메시지를 보내면, 이 요약본이 사용됩니다. 도입 직후인 v2.1.318에서는 이 압축(compaction) 기능이 요약이 아닌 답변으로 대화를 대체하는 버그도 수정되었습니다.
v2.1.316의 변경 로그에는 API 측 공지 내용과 동일한 내용이 담겨 있습니다.
Opus 4.8에 대한 fast mode는 2026년 10월 30일부로 사용 중단(Deprecated)되며, 2026년 11월 30일에 완전히 제거됩니다. 제거된 후에는 Opus 4.8에서 fast mode 요청이 오류를 반환하며 표준 Opus 4.8로 폴백(fallback)되지 않습니다. 속도 향상을 유지하려면 Opus 5.5로 마이그레이션하십시오.
핵심은 '표준 속도의 Opus 4.8로 폴백하지 않고, 에러가 발생한다'는 점입니다. Claude Code의 fast mode 문서에서는 기한까지 다음 중 하나를 선택하도록 안내하고 있습니다.
- fast mode를 계속 사용하려면,
/model을 사용하여 Opus 5.5로 전환합니다 (Claude Code v2.1.280 이상 필요. 전환 후에도 fast mode는 활성화 상태를 유지).
- Opus 4.8을 계속 사용하려면,
/fast off로 표준 속도로 되돌립니다.
요금표 기준으로, fast mode는 Opus 5.5가 입력 $8 / 출력 $40 (100만 토큰당), Opus 4.8이 $10 / $50이므로, Opus 5.5로 이동하는 것이 단가가 더 낮습니다.
직접 만든 에이전트(Agent)나 훅(Hook)을 구성할 때 관련될 수 있는 내용들입니다.
- Agent SDK의 훅 콜백이 실패했을 경우, 이전에는 액션을 그대로 통과시켰습니다.
onFailure: "block"
(v2.1.317) onFailure: "block"을 지정하면 중단됩니다. 가드 목적의 훅이라면, 실패 시 중지하는 것이 더 안전합니다.
- 훅 동시 실행 제한 (v2.1.312): prompt / agent 훅은 세션당 최대 24개(서브 에이전트 포함)로 늘어났습니다. 이벤트가 타임아웃을 초과하여 대기하는 것은 별도로 최대 12개까지 가능합니다.
timeout에 1시간 미만을 지정하면 1시간으로 처리됩니다.
- mod의: 간단한 백그라운드 처리를 세션의 effort와 관계없이
$.model.fork에 effort 옵션 (v2.1.318) low로 실행할 수 있습니다.
- 무인 운영 관점에서는, v2.1.314 / v2.1.317 / v2.1.318이 중요합니다. 시작 실패나 디스크 가득 참(disk full), API 에러로 인해 종료되었던 케이스가 exit 0으로 무시되던 문제가 해결되었습니다. 로그인 만료 기한도
claude -p 수정된 credential_expires_at을 통해 사전에 알 수 있게 되었습니다.
- 대화 관점에서는,
ultrathink = xhigh로 서브 에이전트의 effort가 분리된 것이 큰 변화입니다. adaptive thinking 기반의 5.5 세대에서는 effort 배분이 그대로 비용 설계에 영향을 미칩니다. 주의해야 할 변경 사항은 두 가지입니다.
sed -i가 /rewind에서 복원되지 않게 된 점,- Opus 4.8 fast mode가 11월 30일에 에러를 반환하는 점 (Opus 5.5로 이동하거나 /fast off 사용).
- 작업 디렉토리 외부에 쓰기를 막는
permissions.blockWritesOutsideWorkingDirectories는 auto 모드로 장시간 실행할 경우 넣어두면 손해 볼 것이 없습니다.
이 글은 Zenn에도 동일한 내용으로 게시되어 있습니다.
