Sous-agents Claude Code : déléguer une tâche sans encombrer sa session

Fouiller tout un dépôt ou dépouiller des logs depuis la session principale, c’est remplir son contexte de sorties qu’on ne relira pas. Un sous-agent fait ce travail à part et ne rapporte que le résultat.

Chaque sous-agent tourne dans sa propre fenêtre de contexte, avec un prompt système, des outils et des permissions qui lui sont propres. Pour l’effet sur la consommation, voir ce billet.

Le fichier

Un fichier Markdown dans .claude/agents/ pour le projet, ou ~/.claude/agents/ pour tous vos projets. À nom égal, l’ordre de priorité est : réglages gérés, option --agents, projet, utilisateur, plugin.

---
name: relecteur-config
description: Relit des fichiers de configuration et signale les écarts avec la convention du dépôt. À utiliser après toute modification de configuration.
tools: Read, Grep, Glob
model: sonnet
---

Tu relis des fichiers de configuration sans jamais les modifier.
Pour chaque écart : fichier, ligne, valeur trouvée, valeur attendue.
Termine par une liste triée par gravité.

Seuls name et description sont obligatoires. Le corps devient le prompt système du sous-agent, qui ne reçoit pas celui de Claude Code.

Restreindre ce qu’il peut faire

Sans tools, le sous-agent hérite de tous les outils disponibles pour les sous-agents. tools fixe une liste, disallowedTools retire des outils de la liste héritée ou fixée. L’exemple de la doc : avec tools: Read, Grep, Glob, Bash, le sous-agent ne peut ni éditer, ni écrire, ni appeler un outil MCP.

permissionMode est plus trompeur. Si la session principale est en bypassPermissions, acceptEdits ou auto, le sous-agent tourne dans ce même mode et la valeur fixée est ignorée ; elle ne s’applique qu’en default, dontAsk ou plan, à deux exceptions près détaillées dans la doc. Une restriction qui doit tenir passe donc par la liste d’outils, ou par un hook PreToolUse déclaré dans l’en-tête du sous-agent (voir ce billet).

model accepte sonnet, opus, haiku, fable, un identifiant complet ou inherit, qui force le modèle de la conversation principale. Ordre de résolution : le paramètre model passé à l’invocation, le champ model du sous-agent, la variable CLAUDE_CODE_SUBAGENT_MODEL, puis le modèle de la conversation principale.

Ce que voit le sous-agent

Hors fork, un sous-agent ne voit ni l’historique de la conversation, ni les skills déjà invoquées, ni les fichiers déjà lus. Il démarre avec son prompt système, le message de délégation rédigé par Claude, les fichiers CLAUDE.md, un instantané de git status et les skills listées dans son champ skills, injectées en entier (voir ce billet). Explore et Plan se passent de CLAUDE.md et de git status pour rester rapides. Un fork, lui, hérite de toute la conversation, du prompt système et du modèle de la session.

Conséquence : hors fork, le message de délégation doit tout porter, chemins, périmètre et format de retour attendu.

Comment Claude délègue

Automatiquement, d’après la demande, le champ description et le contexte ; « use proactively » dans la description encourage la délégation. Explicitement, en le nommant dans la demande, par une mention @"relecteur-config (agent)", ou pour toute la session avec claude --agent relecteur-config.

Utile ou gaspillage

Selon la doc, un sous-agent se justifie pour une sortie verbeuse inutile dans le contexte principal, des restrictions d’outils ou de permissions à imposer, ou un travail autonome qui peut se résumer.

La conversation principale reste préférable pour les allers-retours fréquents, les phases qui partagent beaucoup de contexte, un changement rapide et ciblé, ou quand la latence compte : un sous-agent (hors fork) part de zéro et doit d’abord rassembler son contexte. Enfin, les résultats remontent dans la session principale : beaucoup de sous-agents qui rendent des comptes détaillés finissent par la remplir quand même.

Ce qu’il faut retenir

• Un fichier Markdown dans .claude/agents/ : name, description, et un corps qui devient le prompt système.
• Sans tools, tout est hérité ; permissionMode s’efface devant bypassPermissions, acceptEdits et auto.
• Hors fork, le sous-agent part de zéro : le message de délégation porte tout le contexte utile.
• Sous-agent pour un travail autonome qui se résume ou exige des outils restreints ; session principale pour l’itératif, le contexte partagé et ce qui doit aller vite.

In English

A subagent works in its own context, with its own tools and model. How to write its file, restrict what it can do, and know when delegating is not worth it. Outside a fork, a subagent sees neither the conversation history nor the files already read, and without a tools field it inherits every available tool.

Sources & vérification

Relevé sur : Documentation Claude Code, relevé 2026-10

• Claude Code, Subagents code.claude.com
• Claude Code, Choose a permission mode code.claude.com

Comment les billets sont vérifiés et corrigés