Claude Code를 2.1.217로 업데이트했더니, SubAgent 안에서 SubAgent를 호출할 수 없게 되었습니다. 어렵게 6월에 SubAgent의 중첩(Nest)이 해제되었는데 어떻게 된 일인가 싶어 CHANGELOG를 확인해 보니, 사양이 변경된 것 같아 정리해 보았습니다.

슬그머니 기본값으로 비활성화됨

2.1.217의 CHANGELOG에는 다음과 같이 적혀 있습니다.

Changed subagents to no longer spawn nested subagents by default; set

CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH

to allow deeper nesting

중첩(Nest) 자체는 2.1.172에서 해제되어, 5단계까지라는 깊이 제한과 함께 사용할 수 있었습니다. 그것이 2.1.217부터 기본적으로 비활성화되어, 환경 변수를 통한 옵트인(Opt-in) 제도로 바뀌었습니다. 영문판 환경 변수 레퍼런스와 서브 에이전트(SubAgent) 문서에도 반영되어 있습니다. (일본어판은 아직 미반영)

실제로 어떤 일이 발생하는가

기본 상태에서 SubAgent 안에서 Agent 도구를 호출하려고 하면, 다음과 같은 에러가 발생합니다.

Error: No such tool available: Agent.
Agent exists but is not enabled in this context.

SubAgent의 중첩(Nest)이 봉쇄되어 있네요.

물론, 메인(Main)에서 직접 SubAgent를 호출하는 경우에는 이전처럼 작동합니다. 금지된 것은 2단계째부터입니다.

한 가지 보충하자면, context: fork 스킬은 이 게이트의 영향을 받지 않습니다. SubAgent 안에서 fork 스킬을 호출하는 것도, fork 스킬 안에서 fork 스킬을 호출하는 것도 변함없이 작동합니다. 중첩(Nest) 제한이 걸리는 것은 Agent 도구를 통한 스폰(Spawn)뿐입니다.

환경 변수를 설정하기

프로젝트의 .claude/settings.json에 작성하는 것이 정석이겠지요.

{
"env": {
"CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH": "3"
...

값은 "메인 아래에 겹칠 수 있는 SubAgent의 수"이며, 기본값은 1입니다. 1은 메인 $\rightarrow$ Sub만 가능하며 중첩 불가, 2가 되어야 비로소 메인 $\rightarrow$ Sub $\rightarrow$ Sub라는 중첩이 허용됩니다. SubAgent를 3단으로 겹치고 싶다면 3이라고 세는 방식입니다. 이 값은 높이는 것만 가능하며, 0으로 설정하여 SubAgent 자체를 비활성화하는 방식으로는 사용할 수 없습니다.

소감

SubAgent의 중첩(Nest)이 해제된 한편, 200개의 스폰(Spawn) 상한(2.1.212), 이번의 기본값 비활성화 등 제한을 가하는 업데이트가 이어지고 있습니다 (상한을 두는 것 자체는 자연스럽지만, 왠지 서둘러 막고 있는 느낌이 듭니다). Anthropic도 아직 동작을 완전히 제어하지 못하고 있는 것 같네요.

개인적으로는 SubAgent의 중첩(Nest)을 이용한 개발 워크플로우를 짜고 있었기에, 앞으로 어떻게 될지 궁금한 부분입니다. 이전에 claude -p의 종량제 과금이 화제가 된 이후(철회되었습니다만), claude -p 이외에 유연하게 컨텍스트(Context)를 분리할 수 있는 방법을 찾고 있었는데, SubAgent의 중첩(Nest)으로 잘 해낼 수 있겠는데! 라고 생각하던 차에 일어난 일이었습니다.

SubAgent의 중첩(Nest)에 의한 동작은 버그인지 사양인지 알 수 없는 것들을 여러 가지 관측하고 있으므로, 시간이 나면 다시 한번 기사로 정리하고 싶네요.

Discussion