Claude Code 2.1.302의 기본 권한 모드와 서브에이전트 변경
매일 밤 실행되는 작업이 --permission-mode 없이 claude -p를 호출합니다. 목요일에는 잘 동작했습니다. 업그레이드 후에는 같은 명령이 실행 자체는 계속 진행되지만, 변경 내용은 거부된 상태로 돌아올 수 있습니다.
10월 16일, Anthropic은 Claude Code 2.1.302 를 태그했습니다. 60여 줄에 달하는 릴리스 노트의 대부분은 수정 사항입니다. 그중 두 줄은 스크립트가 원하는 동작을 명시하지 않을 때 헤드리스 실행이 어떻게 동작하는지 바꿉니다. 즉, claude -p 또는 Agent SDK 세션이 어떤 permission mode로 시작하는지, 그리고 Claude가 대화를 하위 에이전트로 분기할 수 있는지입니다. Claude Code를 CI에서, Amazon Bedrock에서, 또는 텔레메트리를 끈 상태로 사용한다면, 버전을 올리기 전에 이 내용을 읽어야 합니다.
스크립트에 중요한 두 줄
릴리스 노트의 해당 부분을 그대로 옮기면 다음과 같습니다. release notes :
claude -p및 permission mode를 지정하지 않은 Agent SDK 세션이 서드파티 제공자, 텔레메트리 비활성화 상태, 또는 새로 설치한 환경에서는default모드로 시작하도록 변경함.--permission-mode auto는 계속 auto를 유지함. 또한subagent_type: "fork"인 fork 하위 에이전트를claude -p, Agent SDK, 데스크톱 앱, VS Code에서 기본 활성화로 변경함. 이는 터미널에서는 이미 기본값이었음.CLAUDE_CODE_FORK_SUBAGENT=0은 이를 끄며,claude mcp serve는 이 기능을 제공하지 않음
변경 로그 추적기인 gradually.ai 도 10월 16일에 같은 두 가지 변경 사항이 포함된 동일한 릴리스를 나열합니다. 둘 다 breaking change로 표시되지는 않았습니다. 하지만 고정해 두지 않은 스크립트는 기본값을 그대로 상속하므로, 두 변경 모두 작업이 수행하는 동작을 바꿉니다.
지금 헤드리스 실행은 어떤 모드로 시작하는가
permission modes 페이지 는 10월 18일 기준으로도, 기능 플래그를 가져오지 않는 -p 또는 Agent SDK 세션이, "서드파티 제공자이거나 텔레메트리가 꺼져 있는 경우와 같은" 상황에서는 v2.1.285 이상에서 auto로 시작한다고 설명합니다. auto 모드에서는 사람이 아니라 분류기 모델이 작업을 검토합니다. 릴리스 2.1.302는 이런 세션을 다시 default로 되돌리며, CLI에서는 이를 Manual mode라고 부릅니다.
노트에 나온 세 번째 트리거는 새로 설치한 환경이며, 이 경우 Anthropic API를 사용하는 CI에도 해당될 수 있습니다. 같은 permission-modes 섹션 에 따르면, 설치 또는 업그레이드 후 첫 세션은 기능 플래그가 도착하기 전에 시작 모드를 선택할 수 있습니다. 매 작업 시작 시 Claude Code를 설치하고 저장된 설정이 없는 러너는 매번 새로 설치한 환경처럼 보일 수 있습니다.
Manual mode에서는 읽기 작업은 확인 없이 실행 되며, 대부분의 편집과 셸 명령에는 확인을 요청합니다. -p 실행에는 그 확인에 응답해 줄 사람이 없습니다. 헤드리스 문서 는 이를 분명히 설명합니다. "-p 실행에서 호스트가 없으면, 이러한 요청은 어떤 경우든 거부됩니다."
따라서 기본값에 기대어 파일을 수정하던 작업은, 클라우드 제공자(Bedrock, Google Cloud의 Agent Platform, Microsoft Foundry)에서 실행하든, 텔레메트리를 끄고 실행하든, 새 러너에서 실행하든, 예전에는 diff가 생기던 곳에서 거부 결과를 마주칠 수 있습니다. --allowedTools로 필요한 모든 도구를 나열하거나, ~/.claude/settings.json 또는 관리형 설정에서 permissions.defaultMode를 지정한 작업은 계속 예전처럼 동작합니다. 저는 2.1.302를 Bedrock에서 직접 실행해 보지는 않았습니다. 이 해석은 릴리스 노트와 문서에 근거한 것입니다.
해결책은 기본값에 의존하지 않는 것입니다. 명령에서 모드를 명시하세요. 분류기가 작업을 검토하는 무인 작업이라면:
claude -p "Run the test suite and fix failures" \
--permission-mode auto \
--permission-prompts none--permission-prompts none는 v2.1.259 이상이 필요하며, 승인해 줄 사람이 없는 요청은 Claude가 다시 시도하지 않도록 합니다. Bedrock과 다른 클라우드 제공업체에서는 자동 모드가 Sonnet 5 이상, Opus 4.7 이상, Haiku 5.5 및 Fable 모델에서만 작동합니다. 다른 어떤 모델에서도 세션은 어쨌든 Manual로 시작됩니다.
잠금이 걸린 CI에서는 dontAsk가 프롬프트를 띄우게 될 모든 작업을 거부합니다. 읽기 및 읽기 전용 명령은 계속 실행되며, --allowedTools 항목이 허용하는 것들도 실행됩니다:
claude -p "Apply the lint fixes" \
--permission-mode dontAsk \
--allowedTools "Read,Edit,Bash(npm run lint *)"조용한 거부를 잡아내려면 스트림에서 읽어오면 됩니다. stream-json을 사용하면 최종 결과 메시지에 permission_denials로 목록이 나옵니다. 이것을 jq로 넘기는 방법은 다음과 같습니다:
claude -p "Apply the lint fixes" \
--permission-mode dontAsk \
--output-format stream-json --verbose \
| jq -c 'select(.type == "result")
| .permission_denials'Fork 서브에이전트는 claude -p와 SDK에서 활성화됩니다
subagents 문서에서 fork는 "새로 시작하는 대신 지금까지의 전체 대화를 상속하는 서브에이전트"라고 설명합니다. 이것은 메인 세션과 동일한 시스템 프롬프트, 도구, 모델을 가지며, 최종 결과만 돌아옵니다. 접두어가 동일하므로 첫 요청은 부모의 프롬프트 캐시를 재사용합니다. 그래서 문서에서는 fork가 "같은 컨텍스트가 필요한 작업에서 새 서브에이전트보다 비용이 덜 든다"고 설명합니다.
2.1.302 전까지는 이것이 대화형 터미널의 기본값이었습니다. 10월 18일 기준으로도 subagents 페이지에는 -p와 Agent SDK에서 fork 모드가 기본적으로 꺼져 있다고 나와 있습니다. 릴리스 노트가 더 최신의 기준입니다.
Fork 모드는 fork만 바꾸는 것이 아닙니다. 이 모드를 켜면 문서에 따르면 Claude Code가 Claude가 생성한 서브에이전트를 백그라운드에서 실행하며, "fork와 비fork 서브에이전트 모두"에 적용되고 Agent 도구의 run_in_background 매개변수를 제거합니다. 백그라운드 서브에이전트는 전경 서브에이전트보다 내장 도구 세트가 더 작습니다. 단, fork는 예외입니다. 또한 -p 실행은 백그라운드 서브에이전트가 끝날 때까지 열린 상태로 유지됩니다. 그 결과가 최종 출력의 일부이기 때문입니다. 같은 릴리스에서는 -p, SDK, 데스크톱 앱, VS Code에서 서브에이전트가 자체적으로 하는 Agent 호출도 기본적으로 전경에서 실행되도록 바뀌었습니다.
파이프라인이 사용자 정의 서브에이전트가 예전처럼 동작하는 데 의존한다면, 해당 작업에서는 fork 모드를 끄세요:
export CLAUDE_CODE_FORK_SUBAGENT=0
claude -p "Summarize the open TODOs" \
--permission-mode dontAskfork 모드는 유지하되 Claude가 fork를 생성하지 못하게 하려면, 문서에서는 Agent(fork) 규칙으로 fork 유형을 거부하라고 제안합니다:
{
"permissions": {
"deny": ["Agent(fork)"]
}
}알아두면 좋은 더 작은 변경 사항들
2.1.302 노트의 나머지는 대부분 수정 사항이지만, 몇 가지는 동작에 영향을 줍니다:
- Prompt 및 agent hook은 이제 한 번에 같은 이벤트를 최대 12개까지만 실행되며, 나머지는 차례를 기다립니다.
CLAUDE_CODE_AUTO_MODE_MODEL은 클라이언트 측 자동 모드 분류기에 사용할 모델을 선택합니다. 서버 측 분류기는 바꾸지 않습니다.
- Read 도구는 이제 이미지 소스가 128 MB를 넘으면 메모리에 불러오지 않고 거부합니다.
/config에Idle compaction행이 추가되어 유휴 압축을 끌 수 있습니다.
/design-sync와/design-login은 독립형 Claude Design이 종료된다고 경고합니다. Anthropic의 마이그레이션 문서에서는 종료 시점을 2026년 12월 14일로 안내합니다. 디자인 시스템은 이전할 수 있지만, 채팅과 댓글은 종료 후 삭제되며, "독립형 버전의 프로젝트에 대한 공개 링크는 더 이상 작동하지 않습니다."
에이전트가 시작되기 전에 모드를 확인하기
Hermes IDE를 만들고 있으므로, 그 점을 감안해서 이 섹션을 보겠습니다. Hermes는 기본적으로 Claude Code를 실제 터미널에서 대화형 세션으로 실행하므로, 위의 두 -p 기본값은 여기에 적용되지 않습니다. Claude용 선택적 Agent 보기는 대신 Claude Agent SDK를 실행하므로, 그런 세션에서는 SDK의 기본값을 확인하면 됩니다. 아래에 보이는 ⌘N 새 작업 시트(Windows와 Linux에서는 Ctrl+Shift+N)에서는 권한 모드가 에이전트와 프로젝트 옆의 칩에 표시되고, 시작 전에 claude 명령을 보여주는 "Hermes will run" 줄이 나타납니다.
Hermes 2.3.4의 ⌘N 새 작업 시트: Claude Code, 프로젝트, 새 worktree, Accept edits, model and effort 칩, 그리고 claude 명령의 "Hermes will run" 미리보기.
Hermes는 당신을 대신해 권한 프롬프트에 절대 응답하지 않습니다 . 에이전트가 그 프롬프트에서 막히면, attention inbox가 그것을 카운트하고 ⌘I를 누르면 가장 오래 기다린 에이전트로 이동합니다. 이 도구는 무료이며, BSL 1.1 아래에서 소스 공개로 제공되고, macOS, Windows, Linux에서 실행됩니다. 여기서 다운로드하세요 . Hermes는 Anthropic과 제휴하지 않습니다.
고정한 뒤 업그레이드하기
2.1.302가 러너에 도달하기 전에, 모드를 명시하지 않는 헤드리스 호출을 찾아보세요:
grep -rn "claude -p" .github/ scripts/ \
| grep -v -- "--permission-mode"이렇게 하면 한 줄로 된 호출만 잡아냅니다. \로 여러 줄에 나뉜 명령은 직접 눈으로 확인해야 합니다. 그런 다음 각 호출에 --permission-mode를 추가하고, 그 작업에서 fork를 사용할지 결정한 뒤, CLAUDE_CODE_FORK_SUBAGENT를 그에 맞게 설정하세요.
CI 작업에서 권한 모드를 고정해 두셨나요, 아니면 기본값에 기대고 계셨나요? 댓글로 알려주세요.
이 내용이 유용했다면
코딩 에이전트를 비대화형으로 실행하고 있다면, 저는 같은 작업의 대화형 측면을 위해 Hermes IDE를 만들고 있습니다. 에이전트마다 하나의 터미널, 작업마다 하나의 worktree를 제공합니다.
권한 모드와 fork된 subagent는 오래된 같은 질문에 대한 두 가지 답입니다. 에이전트에게 어느 정도 자율성을 줄 것인지, 그리고 한 에이전트가 다른 에이전트에게 작업을 어떻게 넘길 것인지입니다. AI Agents Pocket Guide는 이러한 패턴을, 도구 호출 루프부터 멀티 에이전트 오케스트레이션과 가드레일까지, 특정 벤더의 플래그에 묶지 않고 다룹니다.
출처
- 원문: https://dev.to/gabrielanhaia/claude-code-21302-flips-two-claude-p-defaults-permission-mode-and-fork-subagents-2k48 (2026-10-18 · Gabriel Anhaia)