v2.1.217에서 서브 에이전트 (Sub-agent)의 동시 실행이 기본 20 병렬로 제한되었습니다. 중첩된 생성도 기본적으로 비활성화됩니다. 1개의 메시지로부터 끝없이 에이전트가 늘어나는 구성은 환경 변수를 명시하지 않으면 구축할 수 없게 되었습니다.

서브 에이전트의 동시 실행에 상한

• 기본 20 병렬. CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS로 변경 가능 (v2.1.217)

중첩된 서브 에이전트 생성이 기본적으로 비활성화

• 허용하려면 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH 명시가 필요 (v2.1.217)
• 상한 도달 시 새로운 spawn을 거부하며, 실행 중인 에이전트도 정지 (v2.1.217)
  --max-budget-usd가 백그라운드 서브 에이전트도 정지

장기 세션의 수 초간 스톨(Stall) 현상 해소

• 메시지 정규화 (Message Normalization) 비용이 턴 수의 제곱으로 증가함 (v2.1.216)
• 파일 시스템 분리만 해제하고, 네트워크 egress 제어는 유지 가능 (v2.1.216)
  sandbox.filesystem.disabled를 추가

격리 경계의 우회로 봉쇄

• worktree의 git 우회나 symlink를 통한 workspace 탈출 및 외부 쓰기를 수정 (v2.1.216 / v2.1.217)

대상 독자: 서브 에이전트를 병렬로 대량 기동하는 워크플로(Workflow)나, 에이전트가 에이전트를 호출하는 다단계 구성을 사용하고 있는 사람.

1개의 메시지로부터 무제한으로 서브 에이전트가 늘어나는 경로가 차단되었습니다.

동시에 실행되는 서브 에이전트는 기본 20 병렬까지입니다. 확장하고 싶다면 환경 변수로 덮어씁니다.

# 예: 병렬 상한을 40으로 확장
export CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS=40

중첩(Nest)에도 제한이 생겼습니다. 서브 에이전트 자신이 다시 서브 에이전트를 생성하는 동작은 기본적으로 비활성화됩니다. CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH로 깊이를 허용했을 때만 동작합니다.

다단계 에이전트 구성을 짜놓은 경우, v2.1.217로 올리면 중첩 생성이 멈춥니다. 기존 동작을 유지하려면 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH 설정이 필요합니다.

--max-budget-usd는 지금까지 예산 상한에 도달해도 백그라운드의 서브 에이전트를 멈출 수 없었습니다. 상한에 걸려도 과금이 늘어날 여지가 있었습니다. 수정 후에는 상한 도달 시 새로운 spawn이 거부되며, 실행 중인 백그라운드 에이전트도 정지합니다.

{
"sandbox": {
"filesystem": {
...

settings에 sandbox.filesystem.disabled를 추가하면, 파일 시스템 격리를 건너뛰면서 네트워크 egress 제어만 유지할 수 있습니다. 샌드박스(Sandbox)의 쓰기 제한 때문에 빌드가 통과되지 않지만, 외부로 향하는 통신 제어는 포기하고 싶지 않은 경우, 파일 시스템 측만 해제하는 중간 선택지가 늘어났습니다.

세션을 길게 유지할수록 응답 전에 멈추거나, resume(재개)도 느려지는 현상이 있습니다. 이 증상의 원인은 메시지 정규화 비용이 턴 수의 제곱으로 증가하는 버그였습니다.

v2.1.216에서 수정되었습니다. 수 초 단위로 멈추던 응답과 느렸던 resume 문제가 그대로 해소됩니다.

서브 에이전트 (sub-agent)의 병렬 수, 중첩 깊이, 예산이 v2.1.217에서 모두 제어 가능해졌습니다. 다단계 에이전트 구성을 사용 중이라면, 업데이트 전에 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH를 확인하세요. v2.1.216의 제곱 스톨 (stall) 수정과 더불어, 장시간·대규모 운영일수록 효과가 큰 버전입니다.