En bref

Quand Claude Code lance un sous-agent via l’outil Agent Tool, ce sous-agent ne dispose pas de 200 000 tokens de contexte. Il en a environ 100 000. C’est ce que nos tests montrent de manière reproductible : l’auto-compaction se déclenche à environ 94-96K tokens, ce qui place le budget effectif autour de 99-101K. Autre point important : chaque sous-agent a son propre budget indépendant. Deux agents parallèles ne se partagent pas un pool commun — chacun démarre avec son enveloppe personnelle.

Contexte

Les modèles Claude Sonnet et Opus affichent une fenêtre de contexte de 200 000 tokens dans la documentation officielle Anthropic. Avec l’accès Max, Team ou Enterprise, cette fenêtre monte même à 1 million de tokens. Ces chiffres sont corrects pour une session interactive classique.

Mais Claude Code fonctionne différemment. Il consomme une partie du contexte pour son propre système : le prompt système, les définitions d’outils, les schémas MCP, les fichiers mémoire. Selon la documentation de Claude Code et plusieurs analyses indépendantes, ce surcoût structural représente 30 000 à 40 000 tokens avant même d’écrire une ligne de prompt. Et lorsqu’un sous-agent est lancé via l’Agent Tool, une question se posait : de quel budget dispose-t-il réellement ?

Avant nos mesures, l’hypothèse courante — présente dans certaines issues GitHub comme la #10212 — était que les sous-agents partageaient le budget du parent, autour de 200K tokens. Ce n’est pas ce que nous observons.

Ce qu’on observe

Nos tests portent sur deux runs indépendants d’un agent Sonnet lancé via Agent Tool, dans deux versions de Claude Code (v2.1.75 et v2.1.79).

Budget mesuré : ~99-101K tokens par sous-agent Sonnet.

Dans le premier run, l’agent a consommé 92 051 tokens sans déclencher l’auto-compaction. Dans le test intensif (lectures répétées de fichiers sur plusieurs passes), l’auto-compaction s’est déclenchée après avoir atteint environ 93 991 tokens. En appliquant le ratio observé — la compaction intervient à environ 95% du budget maximal — on obtient un plafond estimé à environ 99 000 tokens. La réplication en v2.1.79 confirme : 95 936 tokens avant compaction, soit un budget estimé à environ 101 000 tokens. Le delta entre les deux runs (+4,2%) est explicable par une légère différence de taille des fichiers sources, pas par un changement logiciel.

La limite de 128K n’a pas été atteinte empiriquement.

Des sources tierces évoquent parfois un plafond à 128K tokens pour les sous-agents Claude. Nos mesures ne confirment pas ce chiffre pour Sonnet : la compaction intervient bien avant, autour de 95-96K, ce qui indique un plafond effectif nettement inférieur à 128K. Cette valeur de 128K reste une hypothèse non vérifiée — elle pourrait correspondre à un autre modèle ou à une limite API théorique.

Les budgets sont indépendants — pas de pool partagé.

C’est probablement la donnée la plus utile en pratique. Lors d’un test à deux agents parallèles, l’un a consommé 70 092 tokens, l’autre 76 766 tokens, soit 147K tokens combinés — sans qu’aucun des deux ne déclenche l’auto-compaction. Si le budget était partagé (200K pour le parent et tous ses enfants), deux agents à 70K+ chacun ne pourraient pas coexister sans collision. Ce n’est pas ce qu’on observe : chaque agent dispose de son enveloppe propre, indépendante du parent et des autres agents.

L’auto-compaction fonctionne et est transparente.

Quand un sous-agent atteint le seuil (~95% du budget), Claude Code déclenche automatiquement une compaction du contexte : les messages anciens sont résumés, la session continue sans interruption. D’après nos observations, ce mécanisme est stable depuis la version v2.1.79 — pas de crash, pas de troncature silencieuse. La documentation Anthropic sur la compaction décrit ce comportement comme intentionnel.

Attention au compteur total_tokens après compaction.

Après une compaction, le champ total_tokens retourné par l’API reflète l’état post-compaction, pas le cumul historique. Dans nos tests, ce compteur affichait 23 470 tokens alors que le run avait réellement consommé plus de 93 000 tokens avant compaction. Ce chiffre ne peut pas être utilisé comme métrique comparative entre un agent qui a compacté et un autre qui ne l’a pas fait.

Implications

Pour concevoir une tâche sous-agent, le budget utile est ~100K tokens, pas 200K.

En pratique, si vous assignez à un sous-agent Sonnet une tâche qui implique la lecture de fichiers volumineux, plusieurs passes de traitement, ou un prompt système détaillé, vous pouvez tabler sur une enveloppe d’environ 100 000 tokens. Au-delà, la compaction se déclenche. La session continue, mais le contexte historique est résumé — ce qui peut affecter la cohérence sur des tâches nécessitant un état précis sur l’ensemble des données.

Le parallélisme est réellement parallèle.

Puisque les budgets sont indépendants, lancer 10 agents en parallèle ne réduit pas le budget de chacun. Chaque agent dispose de ses ~100K tokens propres. Le facteur limitant n’est pas le pool de tokens, c’est la complexité de ce qu’on demande à chaque agent individuellement.

La mise à jour v2.1.75 → v2.1.79 n’a pas modifié le budget.

Cette version incluait un correctif sur la compaction prématurée. D’après nos mesures, le budget contexte des sous-agents Sonnet est resté identique avant et après : la correction a amélioré la stabilité, pas l’enveloppe.

Ce qu’il faut retenir

  • Le budget effectif d’un sous-agent Sonnet est d’environ 100 000 tokens, pas 200 000.
  • L’auto-compaction se déclenche à environ 94-96K tokens (soit ~95% du plafond).
  • Les budgets sont indépendants par agent : pas de pool partagé entre le parent et ses enfants.
  • La limite de 128K n’a pas été confirmée empiriquement pour Sonnet — traiter ce chiffre comme une hypothèse.
  • Le compteur total_tokens post-compaction n’est pas comparable à un compteur pré-compaction : ne pas s’en servir pour des métriques croisées.
  • Ces observations sont stables sur deux runs et deux versions de Claude Code (v2.1.75 et v2.1.79).

Sources