클로드 코드(Claude Code) v2.1.317이 출시되었습니다. 기능 추가와 버그 수정이 많은 업데이트입니다. 특히, 보안/관리 관련 추가 사항과 기존 동작 방식이 바뀌는 부분은 CI나 자체 개발 도구에 통합하여 사용하고 있는 분들일수록 확인이 필요합니다.
본문에서는 심각도(severity)가 high인 변경 사항을 중심으로 다음 4가지 포인트를 다룹니다.
- Agent SDK의 훅 콜백에
onFailure: "block"이 추가된 것 (페일클로즈화)
- 세션 내에서 실행된
claude -p가 고유한 세션 ID를 사용하게 된 점
- Claude apps gateway에 비용 보고서 API가 추가된 점
- 계정의 이메일 주소를 외부로 보내기 전에 확인 절차가 생겨난 점
아울러, 영향을 받기 쉬운 medium 등급의 변경 사항(Read 스텁 폐지, 서브 에이전트의 effort, claude -p의 종료 코드)도 함께 다룹니다.
📌 영향받는 사용자
- Agent SDK 훅에서 안전 점검이나 정책 판정을 수행하는 사람
- 클라우드/셀프호스트(self-host) 러너 상에서
claude -p를 호출하는 사람
- Claude apps gateway를 운영하는 관리자
- CI 환경에서
claude -p의 종료 코드를 확인하는 사람
| 구분 | 변경 내용 | severity | 대응 필요 여부 |
|---|
| 추가 | 훅의 onFailure: "block" | high | 있음 |
| 변경 | claude -p의 고유 세션 ID 사용 | high | 있음 |
| 추가 | 비용 보고서 API / IdP 그룹 기록 | high | 없음 |
| 추가 | 이메일 주소 전송 전 확인 절차 | high | 없음 |
| ... | claude -p 쓰기 실패 시 종료 코드 | medium | CI 환경에서 확인 필요 |
지금까지 Agent SDK의 훅 콜백이 실패하더라도 대상 작업은 그대로 실행되던 방식이었습니다 (페일오픈, fail-open). 안전 점검용 훅이 예외로 인해 다운되면, 점검 없이도 작업이 통과될 수 있었습니다.
onFailure: "block"을 지정하면, 콜백 자체에 실패했을 때 작업을 중단시킵니다 (페일클로즈, fail-close).
⚠️ Breaking Change는 아니지만 주의할 사항
기본 동작 방식은 기존과 동일합니다. 아무 조치를 취하지 않으면 페일오픈 상태를 유지하므로, 안전 점검용 훅에는 명시적으로 지정해야 합니다.
클라우드나 셀프호스트 러너의 세션 내에서 실행된 claude -p는 이전에는 다음과 같은 동작을 했습니다.
- 부모(parent) 세션의 ID를 공유하고, 부모의 트랜스크립트에 기록했습니다.
- 이로 인해 재시작 시 다른 대화를 다시 시작하는 경우가 있었습니다.
claude -p가 고유하게 제목을 생성하여 부모 세션으로 전송되었습니다.
v2.1.317에서는 이 두 가지 모두 수정되었습니다. claude -p는 더 이상 부모의 ID나 트랜스크립트를 공유하지 않습니다.
⚠️ Breaking Change
셀프호스트 러너에서 이전 동작(부모 세션의 ID와 트랜스크립트 사용)에 의존하고 있다면, CLAUDE_CODE_DISABLE_NESTED_SESSION_ID=1을 설정하여 되돌릴 수 있습니다.
관리 API에 GET /v1/organizations/analytics/cost가 추가되었습니다. 과거 지출 내역을 다음 단위로 조회할 수 있습니다.
admin:을 설정한 게이트웨이는 각 개발자의 IdP 그룹을 매일 기록하며, admin.identity_retention_days 동안 보관합니다. 그룹별 집계는 이 기록을 사용하므로, 보존 일수가 짧으면 과거 데이터를 조회할 수 없습니다.
아울러 다음 수정 사항들이 포함되었습니다.
- Amazon Bedrock의 "Input is too long." 오류를 게이트웨이가 숨기고, 압축되지 않아 매 턴 실패하던 문제 개선
- 그룹의 공유 예산을 소진한 후,
/usage에서 본인의 한도가 100%로 표시되던 문제 해결 - 필수 게이트웨이에 연결할 수 없을 때 발생하는 시작 오류를 로그인 문제가 아닌 네트워크 문제로 표시하도록 개선 (TLS 인증서를 검증할 수 없는 경우도 동일)
웹 도구(WebFetch / WebSearch)나 셸 도구(Bash)를 호출할 때 계정의 이메일 주소가 네트워크로 전송될 것 같은 경우, 실행 전에 확인 절차가 들어갑니다.
/schedule
에서는 새로 만든 클라우드 스케줄링 작업에 의존하지 않는 커넥터가 포함된 경우 경고가 발생하며, 제거 방법도 안내됩니다.
- Read 미변경 스텁 폐지: 'file unchanged since your last Read'라는 스텁을 사용하던 방식이 중단되었으며, 이제는 재(再) Read를 하더라도 항상 본문을 반환합니다. 스텁 전제 방식으로 운영할 경우 토큰 소비가 증가할 수 있습니다. -
서브 에이전트의 effort: 메인 대화와 별도의 모델을 사용하는 서브 에이전트나 팀메이트는 세션의 effort를 상속받지 않으며, **해당 모델에서 저장된 effort(없으면 기본값)**를 사용합니다. -
: 디스크 가득 참이나 할당량 초과로 인해 트랜스크립트 또는 claude -p
의 종료 코드(~/.claude.json) 쓰기에 실패할 경우, text/json 출력에서는 종료 코드 1이 됩니다. 용량이 가득 찬 NFS 익스포트는 감지하지 못하는 경우가 있을 수 있습니다.
| 할 일 | 대상 | 우선순위 |
|---|
안전 점검용 훅에 onFailure: "block" 추가 | Agent SDK 이용자 | 높음 |
러너 상의 claude -p가 부모 세션에 의존하지 않는지 확인 | 셀프호스트 러너 운영자 | 높음 |
이전 동작이 필요한 경우 CLAUDE_CODE_DISABLE_NESTED_SESSION_ID=1 설정 | 위와 동일 | 높음 |
| Cost Report API에서 지출 가시화 시도 | gateway 관리자 | 중간 |
| CLAUDE.md에서 Read 스텁 전제 기술 삭제 | 전체 | 중간 |
CI에서 claude -p 실패가 감지되는 것을 확인 | CI 관리자 | 중간 |
💡 팁
'실패하면 중단하는 것'이 올바른 방식인 것은 안전 점검이나 정책 판정의 훅(hook)입니다. 로그 출력이나 알림과 같은 보조적인 훅까지 페일 클로즈(fail-close)를 적용할 경우, 알림 서비스 장애로 인해 에이전트 전체가 멈출 수 있습니다. 훅의 역할별로 구분하여 사용해야 합니다.
onFailure
을 배치할 정확한 위치나 시그니처는 공식 문서를 확인해 주세요. 아래는 개념을 보여주는 예시입니다.
Before(실패하면 점검이 누락됨)
hooks: {
PreToolUse: [
{
...
After(실패하면 작업 중단)
hooks: {
PreToolUse: [
{
...
# 부모 세션의 ID와 트랜스크립트를 사용하는 이전 동작이 필요한 경우에만
export CLAUDE_CODE_DISABLE_NESTED_SESSION_ID=1
claude -p "테스트를 실행하고 결과를 요약해줘"
claude -p "변경 내용을 리뷰해줘" --output-format json > review.json
status=$?
if [ "$status" -ne 0 ]; then
...
이전에는 쓰기 실패 시에도 0이 반환되던 환경에서는, 지금까지 통하던 작업이 실패로 바뀔 가능성이 있습니다. 원인은 디스크나 할당량 측에 있으니, 해당 부분을 수정해 주세요.
# 기간 등의 쿼리 항목과 인증 헤더는 공식 문서의 사양에 맞게 설정하세요
curl -sS "https://<your-gateway-or-api-host>/v1/organizations/analytics/cost" \
-H "<인증헤더>"
## Hooks / Agent SDK
+- 안전 점검용 훅 콜백에는 onFailure: "block"을 지정합니다(실패 시 작업 중단)
## CI / 헤드리스 실행
...
- 훅: 실패 시 기본값은 페일 오픈(fail-open) 상태입니다. 안전 점검용으로는
onFailure: "block"을 명시해 주세요. -
: 세션 내에서 실행하더라도 부모의 세션 ID나 트랜스크립트는 공유되지 않습니다. 이전 동작이 필요한 경우 claude -p
CLAUDE_CODE_DISABLE_NESTED_SESSION_ID=1
[...로 복구할 수 있습니다.] -
게이트웨이(gateway): Cost Report API를 통해 개발자별, 일자별, IdP 그룹별 지출을 가져올 수 있습니다. 그룹별 집계는 admin.identity_retention_days의 보유 기간에 영향을 받습니다.
프라이버시(Privacy): 이메일 주소의 외부 전송 전과 /schedule의 불필요한 커넥터에서 확인 및 경고가 추가됩니다.
검토 대상(Review Targets): Read 스텁(stub)을 가정하는 CLAUDE.md, 서브 에이전트의 노력(effort) 가정을 기반으로 하는 부분, 그리고 claude -p의 종료 코드에 의존하는 CI 스크립트.
그 외에도 셀프 호스트 러너(self-hosted runner) 장애 복구, MCP, OTel, 압축(compaction), Windows, VS Code 등 다수의 수정 사항이 포함되었습니다. 자세한 내용은 릴리스 노트(Release Notes)를 확인해 주십시오.
