Fork Subagents dans Claude Code

Le problème : lancer des subagents en parallèle dans Claude Code coûtait cher. Chaque agent enfant reconstruisait le prompt système, le tableau d'outils complet et tout l'historique de conversation depuis zéro. Cinq agents, cinq factures de tokens complètes. Aucun partage. Avant la v2.1.117, le code du fork existait dans le dépôt mais était éliminé à la compilation dans les releases publiques. Seuls les builds internes d'Anthropic pouvaient l'utiliser.

La solution : une seule variable d'environnement change tout. Active CLAUDE_CODE_FORK_SUBAGENT=1 et les enfants 2-N puisent directement dans le cache du prompt partagé. Environ 10x moins cher par agent supplémentaire :

export CLAUDE_CODE_FORK_SUBAGENT=1

Ce que sont vraiment les fork subagents

Un enfant forké ne démarre pas une session vierge. Il reçoit les octets exacts du prompt système déjà rendu de son parent, via override.systemPrompt tiré de toolUseContext.renderedSystemPrompt. Mêmes octets, pas un nouveau rendu. Ça compte parce que l'état des feature flags (comme GrowthBook) reste cohérent entre parent et enfant sans coordination supplémentaire.

Le tableau d'outils suit la même règle. Il passe tel quel avec useExactTools: true, ce qui court-circuite complètement resolveAgentTools(). La sérialisation reste byte-identique, c'est ce qui fait fonctionner le cache. Un détail à noter : l'outil Agent reste dans le pool d'outils de l'enfant même si l'enfant n'a pas le droit de l'appeler. Le supprimer casserait le cache. La restriction est appliquée autrement (voir plus bas).

Chaque bloc d'appel d'outil du parent dans l'historique de messages de l'enfant reçoit la constante FORK_PLACEHOLDER_RESULT ('Fork started -- processing in background') comme résultat. Tous les enfants reçoivent des octets de placeholder identiques. La frontière du cache tombe juste avant la directive propre à chaque enfant, donc les enfants ne divergent qu'à l'instruction spécifique à leur tâche.

Avant la v2.1.117, tout ce chemin était supprimé des builds publics à la compilation. Les utilisateurs externes ne pouvaient pas l'activer du tout.

Le calcul des coûts

Avec 48 500 tokens de préfixe partagé, les chiffres sont concrets :

Le premier enfant paie plein tarif. C'est la première requête, il n'y a encore rien dans le cache. Les enfants 2-N touchent le préfixe partagé et ne paient que le delta.

Cinq agents en parallèle : sans fork tu dépenses environ 243 500 tokens de contexte partagé. Avec fork tu dépenses ~48 700 pour le premier plus ~20 200 pour les enfants 2 à 5. Le cache fait le reste.

Comment l'activer

Ajoute la variable d'environnement à ton profil shell :

export CLAUDE_CODE_FORK_SUBAGENT=1

Pour les pipelines CI/CD, définis-la dans les variables d'environnement au niveau du pipeline. Chaque exécution d'agent dans ce pipeline la récupèrera automatiquement.

Un comportement à connaître : le fork ne se déclenche que quand subagent_type est omis de l'appel à l'outil Agent. Si le modèle spécifie un type explicite (par exemple "Explore" ou "Plan"), le chemin fork ne se déclenche pas. Les chemins par type nommé ont leur propre logique.

Le garde-fou contre la récursion

C'est le détail qui n'apparaît nulle part ailleurs.

Chaque enfant forké reçoit une balise XML standard injectée dans sa session. Elle dit en gros : cette instruction est pour le parent. TOI tu es le fork. Ne lance PAS de sous-agents.

Sans ça, les enfants tenteraient de forker leurs propres enfants, qui forkent encore, et tout ça recurserait jusqu'à l'effondrement de la fenêtre de contexte. La balise XML brise la chaîne.

Il y a deux gardes, pas un seul. Le premier est un fast-path querySource === 'agent:builtin:fork' en haut du gestionnaire d'options d'agent. Le second est un scan de secours de l'historique des messages qui cherche la balise XML standard elle-même. Ce fallback existe parce que querySource peut être réécrit par autocompact lors de longues sessions. Les deux vérifications doivent confirmer que la session est un enfant fork avant que le garde s'active.

Le fork est aussi incompatible avec le mode coordinateur. Un coordinateur forké hériterait du prompt système "tu es le coordinateur, délègue le travail" et commencerait à orchestrer plutôt qu'à exécuter. Les deux modes ne peuvent pas partager une session.

Ce que ça débloque

Les dispatches d'agents en parallèle sont le cas d'usage principal. Cinq agents sur cinq modules tournent simultanément, et les enfants 2-5 partagent le préfixe mis en cache du parent. Le coût total du contexte partagé tombe à environ un seul enfant supplémentaire de tokens.

Les pipelines CI/CD en bénéficient automatiquement dès que CLAUDE_CODE_FORK_SUBAGENT=1 est dans l'environnement. Les workflows multi-agents qui étaient auparavant trop coûteux à grande échelle deviennent pratiques.

Le pattern "policy islands" devient aussi utilisable. Les commandes avec context: fork et agent: <name> dans leur frontmatter spawne des subagents isolés avec des allowed_tools pré-déclarés. Ces subagents tournent sans invites d'approbation en cours de workflow et ne renvoient qu'un résumé au parent. Le parent ne voit jamais les appels d'outils intermédiaires.

Les limites à connaître

• Incompatible avec le mode --print. Le fork utilise permissionMode: 'bubble', qui remonte les invites vers un terminal parent. Dans les runs SDK/headless non-interactifs, il n'y a pas de terminal.
• Incompatible avec le mode coordinateur. Un coordinateur forké hérite des instructions d'orchestration et essaie de déléguer plutôt qu'exécuter.
• La fenêtre de contexte grandit avec la longueur de session. Les enfants fork portent tout l'historique de conversation du parent. Les longues sessions avec beaucoup d'enfants coûtent plus en tout, même avec le cache. Les longues sessions chaudes sont là où ça pique le plus.
• Opt-in, pas par défaut. La variable d'environnement doit être définie explicitement. Rien ne change sans elle.

Ce que ça débloque à grande échelle

Avec CLAUDE_CODE_FORK_SUBAGENT=1 activé et les utilisateurs Pro/Max désormais à l'effort high par défaut (aussi depuis la v2.1.117), la combinaison est significative. Un orchestrateur tournant à l'effort high dispatche des enfants fork en parallèle. Chaque enfant hérite du contexte parent complet à prix réduit grâce au cache. Chaque enfant tourne à l'effort high. Avant cette release, les utilisateurs Pro/Max n'avaient ni l'un ni l'autre.

Active la variable, lance cinq agents en parallèle, et quatre d'entre eux coûtent environ un dixième de ce qu'ils coûtaient avant. C'est tout.