Subagent는 seam: 프로세스 안에서 Claude Code 위임까지

같은 하위 과제 「이 모듈을 조사해 보고 보고해」에 네 provider를 바꿔가며 각각 한 번씩 위임해 보세요. 두 가지를 봅니다: seam 양쪽에서 무엇이 전혀 변하지 않는지, 구현에 따라 무엇이 바뀌는지. 「persona 요구 포함」을 켜면 능력 래치가 범위를 벗어난 요청을 시작 전에 어떻게 막는지도 확인하세요.

결론부터 말할게요. DSH는 별도의 서브 Agent 기능을 만든 게 아니라 ctx.subagents라는 레지스트리를 만들었어요. SubagentProvider 계약을 구현한 전송층은 이름으로 등록할 수 있습니다. 공식 배포판에는 여섯 개: spawn(프로세스 내 새로 시작), fork(프로세스 내 컨텍스트 포함), acp(프로토콜 브리지), codex, claude-code(각각 실제 제품 CLI 프로세스), sdk(원격 DSH 인스턴스). 출처: docs/subsystems/subagent.zh.md 5–7행.

입력: 도구층이 모델의 위임 요청을 SubagentStartRequest로 조립합니다. prompt, 부모 Agent, 취소 신호, 네 가지 선택 항목(구조화 출력 schema, 깊이 상한, 도구 필터, persona). 처리: 서비스가 선택한 provider의 정적 능력 표를 먼저 봅니다. 선택 항목마다 대응 capability flag가 있어야 하고, 하나라도 없으면 시작 전 UNSUPPORTED_CAPABILITY를 던집니다. 출력: SubagentRun 핸들. 부모 Agent는 result를 기다리고, 최종적으로 일반 도구 결과 한 건이 됩니다. 부모 입장에서 네 provider 모두 같은 종류의 결과를 돌려줍니다.

fork의 정체를 잠깐 짚을게요. 많은 프레임워크는 부모 컨텍스트 포함 여부를 불리언 하나로 둡니다. DSH는 fork를 독립 provider로 뒀어요. 차이가 스위치 하나가 아니기 때문입니다. fork는 부모 로그에서 「완료된 턴의 균형 접두사」를 시드로 잘라 내고, 마지막 turn/end까지 자릅니다. 진행 중인 턴은 불균형이라 리플레이할 수 없어 반드시 제외합니다. 세션 로그 계약이라 flag 하나로는 설명이 안 됩니다.

첫 번째 증거는 능력 래치 본체입니다. 코드 없이도 로직은 분명해요. assertCapabilities는 요청의 네 선택 항목을 요구 목록으로 만듭니다. outputSchema가 있으면 provider 표에서 outputSchema가 true여야 하고, maxDepth면 depthLimit, toolFilter와 persona도 같습니다. 항목별로 대조해 첫 불일치에서 SubagentError를 던지고, 어떤 provider가 어떤 능력을 지원하지 않는지 말하며 코드는 UNSUPPORTED_CAPABILITY입니다. 다운그레이드 없음, 경고 후 진행 없음, 이전에 자식 프로세스는 하나도 안 뜹니다.

출처: packages/subagent/subagent/src/index.ts 481–495행, 확인일 2026-08-13. 데모 오류 문구는 490–493행을 그대로 따랐습니다.

두 번째 증거는 fork 시드 함수입니다. 컨텍스트 포함이 실제로 무엇인지 일곱 줄로 말합니다:

function completedTurnPrefix(parent: Agent): SessionEvent[] {
  const events = parent.session.events
  const lastEnd = events.findLast(e => e.type === 'turn/end')
  if (lastEnd === undefined) return []
  // seq === array index (the append contract), so slice up to and including it.
  return events.slice(0, lastEnd.seq + 1)
}

코드 없이 두 메커니즘만 글로 표시합니다. Claude Code provider 전체 구현은: claude 실행 파일을 찾고, 부모 세션 cwd에서 공식 Agent SDK로 실제 CLI 프로세스를 띄워 공유 subprocess owner에 붙입니다(subagent-claude-code/src/index.ts 62–91행). 공식 네 preset에서 codex·claude-code 위임 도구 행은 disabled: true로 출하되며, 주석은 preset 복사 후 disabled를 지우면 복사본 세션에만 그 제품 백엔드를 연다고 적습니다(apps/cli/config/agent-presets/standard/agent.cordis.yml 200–219행). DSH에서 다른 제품 위임은 설정 스위치 문제입니다.

Claude Code는 위임을 제품층에 둡니다. Task 도구(AgentTool) 한 입구에 매개변수로 여러 형태를 넣습니다: subagent_type으로 역할, run_in_background 백그라운드, isolation: "worktree" 격리 복제, model로 모델 교체(원고 study/chapters/05-multi-agent.md 32–52행이 AgentTool.tsx 인용). 그 위에 Coordinator Mode와 Agent Teams가 있습니다. 표현력은 크지만 각 형태는 이 제품 안의 기능 분기입니다. 위임 대상은 항상 또 다른 Claude Code 인스턴스이고, 다른 제품에 일을 넘기는 자리는 없습니다. DSH는 반대로 제품 차이를 provider층으로 내리고, seam 위에는 어휘 하나만 둡니다.

Grok Build는 세 번째 길입니다. 서브 Agent 설정 해석을 순수 로직 crate xai-grok-subagent-resolution로 빼고, explicit override > role > persona > parent 우선순위로 유효 설정을 만듭니다(해당 crate src/lib.rs 7–8행). 실행은 자사 shell 프로세스 안에 둡니다. 추상화 대상은 서브 Agent가 어떻게 생겼는지이고, DSH는 어디서 도는지입니다. Grok의 역할·컨텍스트 상속·트리 계보는 사이트에 세 레슨이 있습니다: 서브 Agent 네 가지 역할, 컨텍스트 상속과 깊이 제어, 서브 Agent 세션 계보.