Claude Code v2.1.302 변경점 요약: claude -p 권한 모드 및 fork 기본 설정화

2026년 10월 17일자 최신 릴리스 Claude Code v2.1.302에는 CI나 자동화 스크립트에 영향을 줄 수 있는 변경 사항이 포함되어 있습니다.

• 서드파티 프로바이더에서 claude -p / Agent SDK의 기본 권한 모드가 default로 변경될 수 있음 - fork 서브 에이전트가
  claude -p
  ・Agent SDK・데스크톱・VS Code에서도 기본적으로 활성화됨 - 단일 버전 Claude Design (claude.ai/design)이 2026년 12월 14일까지 종료한다는 공지

특히 첫 번째 항목은 암묵적인 auto 모드를 전제로 한 비대화 실행이 권한 확인에서 중단될 수 있습니다. 본문에서는 영향이 큰 변경 사항을 중심으로 누가 무엇을 해야 하는지 정리합니다.

📌 영향을 받는 사람

• Bedrock / Vertex / LLM 게이트웨이 등, 서드파티 프로바이더에서 claude -p나 Agent SDK를 CI・배치로 구동하는 사람/design-sync
  을 사용하는 디자인 연계 워크플로우를 가진 사람claude -p / Agent SDK로 서브 에이전트를 사용하는 사람- Hooks에 prompt / agent 훅을 대량으로 등록한 사람

⚠️ Breaking Change

권한 모드를 지정하지 않은 claude -p와 Agent SDK 세션은 조건을 충족할 경우 default 모드로 시작됩니다.

대상 환경은 다음과 같습니다.

• 서드파티 프로바이더에서 이용하는 - 그리고,
  텔레메트리가 꺼져 있는 환경 또는 신규 설치 환경

기존 auto 모드로 작동하던 스크립트가 툴 실행할 때마다 권한 확인으로 중단될 위험이 있습니다. 비대화 실행에서는 확인에 응답하는 사람이 없으므로 작업이 진행되지 않습니다.

조치 방법은 --permission-mode auto를 명시하는 것입니다.

터미널에서는 이전부터 기본 활성화되어 있던 `subagent_type:

MCP: 프로토콜 2026-07-28에서 resultType,

・ttlMs

・cacheScope

을 생략하는 서버에서 도구가 나타나지 않거나 모든 호출이 실패하는 문제를 수정했습니다. -
Vertex / Bedrock: 세션 중간 전환 시 diagnostics: Extra inputs are not permitted가 발생하는 문제를 수정했습니다. 접두사가 붙은 Opus 4/4.1 (예: anthropic/claude-opus-4-1)의 경우 /autocompact와 /effort 설정이 다른 모델에 저장되는 문제도 수정했습니다. -
Read 도구: 128MB를 초과하는 이미지 소스는 로드를 거부합니다. -
프롬프트 캐시: ToolSearch에서 재로드하거나 압축 후 발생하는 캐시 미스(cache miss)를 수정했습니다. -
결제: 크레딧 결제 전용 모델에서 프롬프트 후보 생성 시 크레딧이 소비되던 문제를 수정했습니다. -
Windows: PowerShell 도구의 오류 2건과, exFAT/FAT32 드라이브 상에서 모든 파일 쓰기가 거부되는 문제를 수정했습니다. -
플러그인: 다수 활성화 시 시작 속도를 높였습니다 (특히 Windows). git의 reftable 환경에서의 오류도 수정했습니다. -
클라우드 세션/루틴: 스케줄 실행이 도중 실패한 후 1시간 이상 지나서 처음부터 다시 실행되어 작업이 중복되던 문제를 수정했습니다. 실행이 시작되지 않은 이유를 보여주는 배너가 추가되었습니다. -
Claude Tag (Slack): 표시, 이미지 첨부(HEIC/SVG/TIFF/BMP), DM, 권한, 링크 정리 등 9가지 항목을 수정했습니다. 관리 설정은 4개의 탭(Bundles / Connectors / Skills and plugins / Channels)으로 재편되었습니다. -
OpenTelemetry: tool_decision 이벤트의 classifier_category 누락과, 속성 수 제한이 낮은 환경에서의 주요 속성 탈락 문제를 수정했습니다. -
기타: worktree 분리가 git 2.56 이후에서 실패하는 문제, VS Code 확장 표시 및 MCP 로그인, @browser 배너 오류 등도 수정되었습니다.

우선순위는 다음과 같습니다:

• 비대화 실행 시 권한 모드를 명시 (최우선). CI의 작업이 멈추기 전에 대응해 주십시오. -
  Claude Design 의존성 파악. /design-sync를 사용하는 워크플로우가 있다면, 종료일(2026-12-14)까지 마이그레이션 계획을 세워야 합니다. -
  fork 동작 확인. claude -p나 Agent SDK에서 서브 에이전트를 사용한다면, fork가 선택되어도 문제가 없는지 확인해야 합니다. 불필요하다면 CLAUDE_CODE_FORK_SUBAGENT=0으로 비활성화할 수 있습니다. -
  훅 구성 확인. 동일 이벤트에 13개 이상의 prompt/agent 훅이 있다면, 대기 시간 증가를 예상해야 합니다.

💡 Tips

각 변경 사항에는 CLAUDE.md에 추가가 제안되었습니다. 다음과 같이 작성하면 팀이나 후임자가 혼란스러워하지 않습니다:

## 비대화 실행 / 권한 모드
- 서드파티 프로바이더에서 claude -p 또는 Agent SDK를 사용할 경우,
auto가 필요하다면 --permission-mode auto를 명시합니다.
...

Before(권한 모드 미지정. 조건에 따라 default로 시작되어 권한 확인에서 멈출 위험)

claude -p

## fork를 사용하고 싶지 않은 경우
export CLAUDE_CODE_FORK_SUBAGENT=0
claude -p "리포지토리 전체를 조사하여 보고서를 작성해" 

## 클라이언트 측 자동 분류기가 사용하는 모델 지정 (모델명은 환경에 맞게 교체)
export CLAUDE_CODE_AUTO_MODE_MODEL="<model-name>"
claude -p --permission-mode auto "의존성을 업데이트해"

`CLAUDE_CODE_AUTO_MODE_MODEL`

은 클라이언트 측 분류기에만 적용되며, 서버 측 자동 모드의 모델은 변경되지 않습니다.

-
**가장 중요**: 서드파티 프로바이더에서 `claude -p`/Agent SDK를 사용하고 권한 모드를 지정하지 않았다면 `--permission-mode auto`를 명시해야 합니다. 텔레메트리가 꺼져 있거나 새로 설치하는 환경이 대상입니다.
-
**fork 서브에이전트**가 `claude -p`/Agent SDK/데스크톱/VS Code에서도 기본적으로 활성화됩니다. 비활성화하려면 `CLAUDE_CODE_FORK_SUBAGENT=0`로 설정합니다.
-
**단독 버전 Claude Design은 2026년 12월 14일까지 종료됩니다.** `/design-sync` 이용자는 마이그레이션 계획이 필요합니다. -
prompt/agent 훅은 동일 이벤트당 최대 12건까지입니다.
-
`CLAUDE_CODE_AUTO_MODE_MODEL`과 Idle compaction 설정이 추가되었으며, MCP, Windows, 클라우드 세션, Slack 연동 등 다수의 버그가 수정되었습니다.

업데이트 전후로 자동화 스크립트의 권한 모드 지정과 CLAUDE.md의 설명을 검토해 보는 것이 안전합니다.