Fork Subagents no Claude Code

Problema: Correr subagentes em paralelo no Claude Code era caro. Cada agente filho reconstruía o system prompt, o array de ferramentas e o histórico completo da conversa do zero. Cinco agentes significavam cinco faturas completas de tokens de entrada. Sem partilha. Antes da v2.1.117, o caminho de fork existia no código mas era eliminado nas releases públicas em tempo de compilação. Só as builds internas da Anthropic o conseguiam usar.

Solução rápida: Uma variável de ambiente muda tudo. Define CLAUDE_CODE_FORK_SUBAGENT=1 e os filhos 2-N puxam o prefixo partilhado diretamente da cache. Redução de custo de cerca de 10x por cada filho adicional:

export CLAUDE_CODE_FORK_SUBAGENT=1

O que são Fork Subagents

Um filho fork não recebe uma sessão nova. Recebe os bytes exatos do system prompt já renderizado do pai, via override.systemPrompt retirado de toolUseContext.renderedSystemPrompt. Mesmos bytes, sem nova renderização. Isto importa porque o estado de feature flags (como GrowthBook) fica consistente entre pai e filho sem coordenação extra.

O array de ferramentas segue a mesma regra. Passa com useExactTools: true, contornando completamente o resolveAgentTools(). A serialização mantém-se byte a byte, que é o que faz a cache funcionar. Há um pormenor: a ferramenta Agent fica no pool do filho mesmo que ele não a possa chamar. Removê-la quebraria a cache. A restrição é aplicada de outra forma (mais sobre isso a seguir).

Cada bloco de tool-use do pai no histórico de mensagens do filho recebe a constante FORK_PLACEHOLDER_RESULT ('Fork started -- processing in background') como resultado. Todos os filhos recebem bytes de placeholder idênticos. A fronteira de cache cai mesmo antes da diretiva por-filho, por isso os filhos divergem apenas na instrução específica à sua tarefa.

Antes da v2.1.117, este caminho era removido das builds públicas em tempo de compilação. Utilizadores externos não o conseguiam acionar de todo.

A Matemática dos Custos

Com 48.500 tokens de prefixo partilhado, os números são concretos:

O filho um paga o preço completo. É o primeiro pedido, por isso não há nada na cache ainda. Os filhos 2-N acertam no prefixo partilhado e pagam só o delta.

Cinco agentes em paralelo: sem fork gastas cerca de 243.500 tokens em contexto partilhado. Com fork gastas ~48.700 para o filho um mais ~20.200 para os filhos dois a cinco. A cache faz o resto.

Como Ativar

Adiciona a variável ao teu perfil de shell:

export CLAUDE_CODE_FORK_SUBAGENT=1

Para pipelines de CI/CD, define-a nas variáveis de ambiente ao nível do pipeline. Todas as execuções de agente nesse pipeline irão usá-la automaticamente.

Um comportamento a conhecer: o fork só dispara quando subagent_type é omitido na chamada à ferramenta Agent. Se o modelo especifica um tipo explícito (por exemplo "Explore" ou "Plan"), o caminho de fork não é acionado. Os caminhos de tipo nomeado têm a sua própria lógica.

O Guarda Recursivo

Este é o detalhe que não aparece em mais lado nenhum.

Cada filho fork recebe uma tag XML de boilerplate injetada na sua sessão. A tag diz, em resumo: essa instrução é para o pai. Tu és o fork. Não cries subagentes.

Sem isto, os filhos tentariam fazer fork dos seus próprios filhos, que fariam fork ainda mais, e tudo recursaria até o context window colapsar. A tag XML quebra a cadeia.

Há dois guardas, não um. O primeiro é uma verificação rápida querySource === 'agent:builtin:fork' no início do handler de opções do agente. O segundo é uma análise de fallback ao histórico de mensagens que procura a própria tag XML de boilerplate. O fallback existe porque querySource pode ser reescrito pelo autocompact em sessões longas. Ambas as verificações têm de concordar que a sessão é um filho fork antes de o guarda disparar.

O fork também é incompatível com o modo coordenador. Um coordenador com fork herdaria o system prompt "és o coordenador, delega trabalho" do pai e começaria a orquestrar em vez de executar. Os dois modos não podem partilhar uma sessão.

O que Desbloqueia

Despachos de agentes em paralelo são o caso de uso principal. Cinco agentes em cinco módulos correm simultaneamente, e os filhos 2-5 partilham o prefixo cacheado do pai. O custo total do contexto partilhado cai para cerca do equivalente a um filho adicional em tokens.

Pipelines de CI/CD ganham isto automaticamente assim que CLAUDE_CODE_FORK_SUBAGENT=1 está no ambiente. Workflows multi-agente que antes eram proibitivamente caros em escala tornam-se práticos.

O padrão "ilhas de política" também se torna utilizável. Comandos com context: fork e agent: <name> no seu frontmatter criam subagentes isolados com allowed_tools pré-declaradas. Esses subagentes correm sem prompts de aprovação a meio do workflow e devolvem apenas um resumo ao pai. O pai nunca vê as chamadas de ferramentas intermédias.

Limitações a Conhecer

• Incompatível com o modo --print. O fork usa permissionMode: 'bubble', que apresenta prompts a um terminal pai. Em execuções SDK/headless não interativas não há terminal.
• Incompatível com o modo coordenador. Um coordenador com fork herda instruções de orquestração e tenta delegar em vez de executar.
• O context window escala com a duração da sessão. Os filhos fork carregam o histórico completo da conversa do pai. Sessões longas com muitos filhos custam mais no total, mesmo com caching. Sessões longas e ativas são onde isto mais se faz sentir.
• Opt-in, não padrão. A variável de ambiente tem de ser definida explicitamente. Nada muda sem ela.

O que Desbloqueia em Escala

Com CLAUDE_CODE_FORK_SUBAGENT=1 definido e os utilizadores Pro/Max agora em esforço high por padrão (também desde a v2.1.117), a combinação é significativa. Um orquestrador a correr com esforço high despacha filhos fork em paralelo. Cada filho herda o contexto completo do pai a preços com desconto de cache. Cada filho corre com esforço high. Antes desta release, os utilizadores Pro/Max não tinham nenhum destes dois recursos.

Define a variável, corre cinco agentes em paralelo, e quatro deles custam cerca de um décimo do que custavam antes. É isso tudo.