Architecture des agents : créer des environnements de développement basés sur l’IA

TL;DR : Claude Code n’est pas une boîte de dialogue avec accès aux fichiers. C’est un runtime programmable doté de 31 événements de cycle de vie documentés, auxquels vous pouvez associer des scripts shell que le modèle ne peut pas ignorer. Empilez des hooks dans des dispatchers, des dispatchers dans des skills, des skills dans des agents, des agents dans des workflows, et vous obtenez un harness de développement autonome qui applique des contraintes, délègue le travail, conserve la mémoire d’une session à l’autre et orchestre une délibération multi-agent. Les workflows dynamiques de Claude Code (v2.1.154+) ont fait de l’orchestration multi-agent déterministe une primitive native — de dizaines à des centaines d’agents en arrière-plan via /workflows — et la plateforme exécute désormais les subagents en arrière-plan par défaut (20 en simultané, imbrication de profondeur 3), permet à vos sessions de s’envoyer des messages entre pairs (v2.1.224) et exécute des sessions cloud sur des runners auto-hébergés. Les hooks et les evidence gates restent garants de la correction.⁵²⁵³⁸⁷ Ce guide couvre chaque couche de cette pile : d’un seul hook à un système de consensus à 10 agents. Aucun framework requis. Tout en Bash et JSON.

Andrej Karpathy a inventé un terme pour ce qui se développe autour d’un agent LLM : les claws. Les hooks, scripts et mécanismes d’orchestration qui permettent à l’agent de saisir le monde au-delà de sa fenêtre de contexte.¹ La plupart des développeurs considèrent les agents de programmation IA comme des assistants interactifs. Ils saisissent un prompt, le regardent modifier un fichier, puis passent à autre chose. Cette approche plafonne la productivité à ce que vous pouvez superviser personnellement.

Le modèle mental de l’infrastructure est différent : un agent de programmation IA est un runtime programmable avec un noyau LLM. Chaque action effectuée par le modèle passe par des hooks que vous contrôlez. Vous définissez des politiques, pas des prompts. Le modèle opère au sein de votre infrastructure de la même façon qu’un serveur web opère selon les règles nginx. Vous ne vous asseyez pas devant nginx pour saisir des requêtes. Vous le configurez, le déployez et le surveillez.

Cette distinction compte parce que l’infrastructure produit des effets cumulés. Un hook qui bloque les identifiants dans les commandes Bash protège chaque session, chaque agent et chaque exécution autonome. Un skill qui encode votre grille d’évaluation s’applique systématiquement, que vous l’invoquiez ou qu’un agent le fasse. Un agent qui examine le code sous l’angle de la sécurité effectue les mêmes vérifications, que vous le surveilliez ou non.²

Points clés

• Les hooks garantissent l’exécution ; les prompts, non. Utilisez des hooks pour le linting, le formatage, les vérifications de sécurité et tout ce qui doit s’exécuter à chaque fois, quel que soit le comportement du modèle. Le code de sortie 2 bloque les actions. Le code de sortie 1 ne fait qu’avertir.³
• Les skills encodent une expertise métier qui s’active automatiquement. Le champ description détermine tout. Claude utilise le raisonnement LLM (et non une correspondance par mots-clés) pour décider quand appliquer un skill.⁴
• Les subagents évitent l’encombrement du contexte. Des fenêtres de contexte isolées pour l’exploration et l’analyse maintiennent la session principale légère. Exécutez des subagents indépendants en parallèle et utilisez des équipes d’agents lorsque les collaborateurs ont besoin d’une coordination durable.⁵
• La mémoire vit dans le système de fichiers. Les fichiers persistent au-delà des fenêtres de contexte. CLAUDE.md, MEMORY.md, les répertoires de règles et les documents de passation forment un système de mémoire externe structuré.⁶
• La délibération multi-agent révèle les angles morts. Les agents seuls ne peuvent pas remettre en question leurs propres hypothèses. Deux agents indépendants aux priorités d’évaluation différentes détectent des défaillances structurelles que les quality gates ne peuvent pas traiter.⁷
• Le modèle du harness constitue le système. CLAUDE.md, les hooks, les skills, les agents et la mémoire ne sont pas des fonctionnalités indépendantes. Ils se composent en une couche déterministe entre vous et le modèle, qui évolue avec l’automatisation.

Comment utiliser ce guide

Chaque section s’appuie sur la précédente. Le cadre de décision, à la fin, fournit une table de consultation pour choisir le bon mécanisme selon chaque type de problème.

Chemin d’or en cinq minutes

Avant la plongée en profondeur, voici le chemin le plus court entre zéro et un harness opérationnel. Un hook, un skill, un subagent, un résultat.

Étape 1 : Créer un hook de sécurité (2 minutes)

Créez .claude/hooks/block-secrets.sh :

#!/bin/bash
INPUT=$(cat)
CMD=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
if echo "$CMD" | grep -qEi '(AKIA|sk-|ghp_|password=)'; then
    echo "BLOCKED: Potential secret in command" >&2
    exit 2
fi

Branchez-le dans .claude/settings.json :

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": ".claude/hooks/block-secrets.sh" }]
      }
    ]
  }
}

Résultat : chaque commande bash que Claude exécute est désormais passée au crible pour détecter les identifiants divulgués. Le modèle ne peut pas contourner cette vérification.

Étape 2 : Créer un skill de revue de code (1 minute)

Créez .claude/skills/reviewer/SKILL.md avec un frontmatter (name: reviewer, description: Review code for security issues, bugs, and quality problems. Use when examining changes, reviewing PRs, or auditing code., allowed-tools: Read, Grep, Glob) et une checklist : injection SQL, XSS, secrets codés en dur, gestion d’erreurs manquante, fonctions de plus de 50 lignes.

Résultat : Claude active automatiquement cette expertise dès que vous mentionnez revue, vérification ou audit.

Étape 3 : Lancer un subagent (30 secondes)

Dans n’importe quelle session Claude Code, demandez à Claude de passer en revue les 3 derniers commits à la recherche de problèmes de sécurité en utilisant un agent séparé. Claude lance un Explore agent qui lit le diff, applique votre skill de revue et renvoie un résumé. Votre contexte principal reste propre.

Ce que vous avez maintenant

Un harness à trois couches : une porte de sécurité déterministe (hook), une expertise métier qui s’active automatiquement (skill) et une analyse isolée qui protège votre contexte (subagent). Chaque section ci-dessous développe l’une de ces trois couches.

Pourquoi l’architecture d’agents est importante

Simon Willison cadre le moment présent autour d’une seule observation : écrire du code ne coûte plus rien aujourd’hui.⁸ Exact. Mais le corollaire, c’est que la vérification est désormais la partie coûteuse. Du code bon marché dépourvu d’infrastructure de vérification produit des bugs à grande échelle. L’investissement qui paie n’est pas un meilleur prompt. C’est le système autour du modèle qui rattrape ce que le modèle laisse passer.

Trois forces rendent l’architecture d’agents nécessaire :

Les fenêtres de contexte sont finies et lacunaires. Chaque lecture de fichier, sortie d’outil et tour de conversation consomme des tokens. Microsoft Research et Salesforce ont testé 15 LLMs sur plus de 200 000 conversations simulées et ont constaté une baisse de performance moyenne de 39 % entre les interactions à un seul tour et les interactions multi-tours.⁹ La dégradation commence dès deux tours et suit une courbe prévisible : des modifications précises multi-fichiers lors des 30 premières minutes dégénèrent en vision tunnel sur un seul fichier dès la 90ᵉ minute. Des fenêtres de contexte plus longues ne résolvent pas ce problème. La condition « Concat » de la même étude (conversation complète en tant que prompt unique) atteint 95,1 % des performances à un seul tour avec un contenu identique. La dégradation vient des frontières entre tours, pas des limites de tokens.

Le comportement du modèle est probabiliste, pas déterministe. Dire à Claude « exécute toujours Prettier après avoir édité des fichiers » fonctionne environ 80 % du temps.³ Le modèle peut oublier, privilégier la rapidité ou décider que le changement est « trop petit ». Pour la conformité, la sécurité et les standards d’équipe, 80 % n’est pas acceptable. Les hooks garantissent l’exécution : chaque Edit ou Write déclenche votre formateur, à chaque fois, sans exception. Le déterministe l’emporte sur le probabiliste.

Les perspectives uniques passent à côté des problèmes multidimensionnels. Un agent seul chargé de passer en revue un endpoint API vérifiait l’authentification, validait l’assainissement des entrées et vérifiait les en-têtes CORS. Diagnostic clean. Un second agent, sollicité séparément en tant que testeur d’intrusion, a découvert que l’endpoint acceptait des paramètres de requête non bornés pouvant déclencher un déni de service via amplification de requêtes en base de données.⁷ Le premier agent n’a jamais vérifié ce point parce que rien dans son cadre d’évaluation ne traitait la complexité des requêtes comme une surface de sécurité. Cette lacune est structurelle. Aucune quantité de prompt engineering ne la corrige.

L’architecture d’agents répond à ces trois enjeux : les hooks imposent des contraintes déterministes, les subagents gèrent l’isolation du contexte et l’orchestration multi-agents fournit des perspectives indépendantes. Ensemble, ils forment le harness.

Le modèle du harness

Le harness n’est pas un framework. C’est un modèle : un ensemble composable de fichiers, de scripts et de conventions qui enveloppent un agent de codage IA dans une infrastructure déterministe. Les composants :

┌──────────────────────────────────────────────────────────────┐
│                      THE HARNESS PATTERN                      │
├──────────────────────────────────────────────────────────────┤
│  ORCHESTRATION                                                │
│  ┌────────────┐  ┌────────────┐  ┌────────────┐             │
│  │   Agent     │  │   Agent    │  │  Consensus │             │
│  │   Teams     │  │  Spawning  │  │  Validation│             │
│  └────────────┘  └────────────┘  └────────────┘             │
│  Multi-agent deliberation, parallel research, voting          │
├──────────────────────────────────────────────────────────────┤
│  EXTENSION LAYER                                              │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐    │
│  │  Skills   │  │  Hooks   │  │  Memory  │  │  Agents  │    │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘    │
│  Domain expertise, deterministic gates, persistent state,     │
│  specialized subagents                                        │
├──────────────────────────────────────────────────────────────┤
│  INSTRUCTION LAYER                                            │
│  ┌──────────────────────────────────────────────────────┐    │
│  │     CLAUDE.md  +  .claude/rules/  +  MEMORY.md       │    │
│  └──────────────────────────────────────────────────────┘    │
│  Project context, operational policy, cross-session memory    │
├──────────────────────────────────────────────────────────────┤
│  CORE LAYER                                                   │
│  ┌──────────────────────────────────────────────────────┐    │
│  │           Main Conversation Context (LLM)             │    │
│  └──────────────────────────────────────────────────────┘    │
│  Your primary interaction; finite context; costs money        │
└──────────────────────────────────────────────────────────────┘

Couche d’instructions : les fichiers CLAUDE.md et les répertoires de règles définissent ce que l’agent sait de votre projet. Ils se chargent automatiquement au début de la session et après chaque compaction. Il s’agit de la mémoire architecturale à long terme de l’agent.

Couche d’extension : les skills fournissent une expertise métier qui s’active automatiquement selon le contexte. Les hooks fournissent des garde-fous déterministes qui se déclenchent à chaque appel d’outil correspondant. Les fichiers de mémoire conservent l’état entre les sessions. Les agents personnalisés fournissent des configurations de subagents spécialisés.

Couche d’orchestration : les modèles multi-agents coordonnent des agents indépendants pour la recherche, la revue et la délibération. Les budgets de création évitent la récursion incontrôlée. La validation par consensus garantit la qualité.

Idée clé : la plupart des utilisateurs travaillent exclusivement dans la couche centrale, tout en regardant le contexte gonfler et les coûts augmenter. Les utilisateurs avancés configurent les couches d’instructions et d’extension, puis n’utilisent la couche centrale que pour l’orchestration et les décisions finales.²

Harnesses managés ou auto-hébergés (avril 2026)

Tout au long du début de 2026, la seule véritable option consistait à « créer votre propre harness ». En avril 2026, cela a changé. Anthropic a lancé Claude Managed Agents en bêta publique (8 avril) : boucle de harness + exécution d’outils + conteneur sandbox + persistance de l’état sous forme d’une API REST, facturés aux tarifs standard des tokens, auxquels s’ajoutent 0,08 $ par heure de session. La mise à jour Agents SDK d’OpenAI (16 avril) a formalisé la même séparation — harness et calcul comme couches distinctes, avec des fournisseurs de sandbox natifs (Blaxel, Cloudflare, Daytona, E2B, Modal, Runloop, Vercel) et snapshot/rehydrate pour survivre à la perte d’un conteneur.²³²⁴

La surface SDK plus approfondie pour le côté OpenAI est arrivée dans openai-agents Python v0.14.0 (publiée le 15 avril 2026 ; annoncée le 16 avril) : une sous-classe SandboxAgent de Agent avec default_manifest, des instructions et des capacités de sandbox ; un Manifest décrivant le contrat d’espace de travail vierge (fichiers, répertoires, fichiers locaux, dépôts Git, env, utilisateurs, mounts) ; un SandboxRunConfig pour le câblage par exécution du client sandbox, l’injection de session active, les remplacements de manifeste, les snapshots et les limites de concurrence de matérialisation. Les capacités intégrées couvrent l’accès au shell, l’édition du système de fichiers, l’inspection d’images, les skills, la mémoire sandbox et la compaction. La mémoire sandbox conserve les enseignements extraits entre les exécutions et les divulgue progressivement ; les espaces de travail prennent en charge les fichiers locaux, les entrées de dépôts Git et les mounts distants (S3, R2, GCS, Azure Blob, S3 Files) ; les snapshots sont portables entre fournisseurs. Backends : UnixLocalSandboxClient, DockerSandboxClient, ainsi que des clients hébergés pour Blaxel, Cloudflare, Daytona, E2B, Modal, Runloop et Vercel via des extras facultatifs.²⁴

Pour les projets Python qui souhaitent intégrer le runtime Claude Code comme bibliothèque — entre « exécuter claude depuis le shell » et « API REST vers Managed Agents » — claude-agent-sdk-python constitue la troisième option. La série des 28-29 avril (v0.1.69 → v0.1.71) a fait passer le CLI intégré à v2.1.123, relevé le minimum de la dépendance mcp à >=1.19.0 (les versions antérieures ignoraient silencieusement les retours CallToolResult provenant d’outils MCP en processus, ne laissant au modèle qu’un blob d’erreur de validation), et aligné le schéma de SandboxNetworkConfig sur le SDK TypeScript (allowedDomains, deniedDomains, allowManagedDomainsOnly, allowMachLookup).³⁰ Au 12 août 2026, le package est en v0.2.137 sur PyPI et le SDK TypeScript en v0.3.229 (tous deux vérifiés dans les registres en direct) ; la série 0.2.x est incrémentale par rapport à la surface 0.1.x décrite ici — les options include_hook_events, skills et de configuration de sandbox ci-dessous restent d’actualité — les versions récentes étant axées sur le nettoyage des sous-processus et la fiabilité des flux NDJSON.⁹⁰⁸⁶

Si votre harness inclut une couche vocale ou temps réel, openai-agents-python v0.17.0 (8 mai 2026) a mis à jour RealtimeAgent afin d’utiliser gpt-realtime-2 par défaut.⁴¹ Les sessions temps réel existantes adoptent automatiquement ce nouveau modèle par défaut ; épinglez explicitement le modèle précédent si vous devez conserver l’ancien comportement pour une évaluation.

En juillet 2026, la colonne managée a également gagné une solution multi-agent du côté d’OpenAI : openai-agents-python v0.18.2 (11 juillet) et openai-agents-js v0.13.2 (10 juillet) ajoutent la prise en charge multi-agent hébergée en bêta — une orchestration par OpenAI de plusieurs agents en tant que service hébergé, pendant direct de la bêta publique Managed Multiagent Orchestration de Anthropic traitée dans la section Orchestration multi-agent.⁷³ Les deux fournisseurs proposent désormais, au niveau multi-agent, le même compromis que celui décrit dans le tableau ci-dessous pour les agents seuls : le fournisseur exécute la boucle de délégation, vous renoncez à la surface des hooks.

La bifurcation architecturale est désormais réelle :

Quand choisir quoi : l’auto-hébergement reste adapté aux équipes disposant déjà de solides capacités d’infrastructure, qui souhaitent contrôler leurs skills/hooks ou optimiser en profondeur un workflow précis. La solution managée convient aux équipes sans ingénieurs de plateforme dédiés, lorsque le délai de mise en valeur compte davantage que la personnalisation, ou lorsque les exécutions d’agents doivent survivre de manière fiable à la fermeture d’un ordinateur portable sans que vous construisiez cette couche de persistance. Les deux approches sont compatibles — vous pouvez exécuter un harness auto-hébergé qui délègue certaines tâches longues à Managed Agents via sa API REST.

À quoi ressemble le harness sur le disque

~/.claude/
├── CLAUDE.md                    # Personal global instructions
├── settings.json                # User-level hooks and permissions
├── skills/                      # Personal skills (44+)
│   ├── code-reviewer/SKILL.md
│   ├── security-auditor/SKILL.md
│   └── api-designer/SKILL.md
├── agents/                      # Custom subagent definitions
│   ├── security-reviewer.md
│   └── code-explorer.md
├── rules/                       # Categorized rule files
│   ├── security.md
│   ├── testing.md
│   └── git-workflow.md
├── hooks/                       # Hook scripts
│   ├── validate-bash.sh
│   ├── auto-format.sh
│   └── recursion-guard.sh
├── configs/                     # JSON configuration
│   ├── recursion-limits.json
│   └── deliberation-config.json
├── state/                       # Runtime state
│   ├── recursion-depth.json
│   └── agent-lineage.json
├── handoffs/                    # Session handoff documents
│   └── deliberation-prd-7.md
└── projects/                    # Per-project memory
    └── {project}/memory/MEMORY.md

.claude/                         # Project-level (in repo)
├── CLAUDE.md                    # Project instructions
├── settings.json                # Project hooks
├── skills/                      # Team-shared skills
├── agents/                      # Team-shared agents
└── rules/                       # Project rules

Chaque fichier de cette structure a une fonction. L’arborescence ~/.claude/ est une infrastructure personnelle qui s’applique à tous les projets. L’arborescence .claude/ de chaque dépôt est spécifique au projet et partagée via git. Ensemble, elles forment le harness complet.

Système de skills

Les skills sont des extensions invoquées par le modèle. Claude les découvre et les applique automatiquement selon le contexte, sans que vous ayez à les appeler explicitement.⁴ Dès que vous vous surprenez à réexpliquer le même contexte d’une session à l’autre, il est temps de créer un skill.

Quand créer un skill

Les skills servent aux connaissances dont Claude dispose toujours. Les slash commands servent aux actions que vous déclenchez explicitement. Si vous hésitez entre les deux, demandez-vous : « Claude doit-il appliquer cela automatiquement, ou dois-je décider quand l’exécuter ? »

Créer un skill

Les skills peuvent se trouver à quatre emplacements, du périmètre le plus large au plus restreint :⁴

Chaque skill nécessite un fichier SKILL.md avec un frontmatter YAML :

---
name: code-reviewer
description: Review code for security vulnerabilities, performance issues,
  and best practice violations. Use when examining code changes, reviewing
  PRs, analyzing code quality, or when asked to review, audit, or check code.
allowed-tools: Read, Grep, Glob
---

# Code Review Expertise

## Security Checks
When reviewing code, verify:

### Input Validation
- All user input sanitized before database operations
- Parameterized queries (no string interpolation in SQL)
- Output encoding for rendered HTML content

### Authentication
- Session tokens validated on every protected endpoint
- Permission checks before data mutations
- No hardcoded credentials or API keys in source

Référence du frontmatter

Le champ Description est essentiel

Au démarrage de la session, Claude Code extrait le name et la description de chaque skill et les injecte dans le contexte de Claude. Lorsque vous envoyez un message, Claude utilise le raisonnement du modèle de langage pour décider si un skill est pertinent. Une analyse indépendante du code source de Claude Code confirme le mécanisme : les descriptions des skills sont injectées dans une section available_skills du prompt système, et le modèle utilise sa compréhension standard du langage pour sélectionner les skills pertinents.¹⁰

Mauvaise description :

description: Helps with code

Description efficace :

description: Review code for security vulnerabilities, performance issues,
  and best practice violations. Use when examining code changes, reviewing
  PRs, analyzing code quality, or when asked to review, audit, or check code.

La description efficace indique : ce qu’elle fait (réviser du code pour des types de problèmes spécifiques), quand l’utiliser (examiner des modifications, des PR, analyser la qualité) et des expressions déclencheuses (review, audit, check) que les utilisateurs saisissent naturellement.

L’auto-activation est un réglage, pas une règle immuable : depuis la v2.1.215, Claude n’invoque plus lui-même les skills /verify et /code-review fournis — ils ne s’exécutent que sur invocation explicite, un recul délibéré de l’activation pilotée par la description pour des skills de revue lourds dont les exécutions non sollicitées coûtaient plus qu’elles ne rapportaient.⁷⁴

Budget de contexte

Toutes les descriptions de skills partagent un budget de contexte qui s’adapte dynamiquement à 1 % de la fenêtre de contexte, avec une valeur de repli de 8 000 caractères.⁴ Si vous avez de nombreux skills, gardez chaque description concise et placez le principal cas d’usage en premier. Vous pouvez remplacer ce budget via la variable d’environnement SLASH_COMMAND_TOOL_CHAR_BUDGET,¹¹ mais une meilleure solution consiste à écrire des descriptions plus courtes et plus précises. Exécutez /context pendant une session pour vérifier si des skills sont exclus.

Fichiers de support et organisation

Les skills peuvent référencer des fichiers supplémentaires dans le même dossier :

~/.claude/skills/code-reviewer/
├── SKILL.md                    # Required: frontmatter + core expertise
├── SECURITY_PATTERNS.md        # Referenced: detailed vulnerability patterns
└── PERFORMANCE_CHECKLIST.md    # Referenced: optimization guidelines

Référencez-les depuis SKILL.md avec des liens relatifs. Claude lit ces fichiers à la demande lorsque le skill s’active. Gardez SKILL.md sous 500 lignes et déplacez les documents de référence détaillés dans des fichiers de support.¹²

Partager des skills via Git

Les skills de projet (.claude/skills/ à la racine du dépôt) sont partagés via le contrôle de version :⁴

mkdir -p .claude/skills/domain-expert
# ... write SKILL.md ...
git add .claude/skills/
git commit -m "feat: add domain-expert skill for payment processing rules"
git push

Lorsque vos collègues récupèrent les modifications, ils obtiennent automatiquement le skill. Aucune installation, aucune configuration. C’est la manière la plus efficace de standardiser l’expertise au sein d’une équipe.

Les skills comme bibliothèque de prompts

Au-delà des skills à usage unique, la structure des dossiers sert de bibliothèque de prompts organisée :

~/.claude/skills/
├── code-reviewer/          # Activates on: review, audit, check
├── api-designer/           # Activates on: design API, endpoint, schema
├── sql-analyst/            # Activates on: query, database, migration
├── deploy-checker/         # Activates on: deploy, release, production
└── incident-responder/     # Activates on: error, failure, outage, debug

Chaque skill encode une facette différente de votre expertise. Ensemble, ils forment une base de connaissances dont Claude se sert automatiquement selon le contexte. Un développeur junior reçoit des conseils de niveau senior sans avoir à les demander.

Les skills se composent avec les hooks

Les skills peuvent définir leurs propres hooks dans le frontmatter, qui ne s’activent que pendant l’exécution du skill. Cela crée un comportement propre au domaine qui ne pollue pas les autres sessions :²

---
name: deploy-checker
description: Verify deployment readiness. Use when preparing to deploy,
  release, or push to production.
hooks:
  PreToolUse:
    - matcher: Bash
      hooks:
        - type: command
          command: "bash -c 'INPUT=$(cat); CMD=$(echo \"$INPUT\" | jq -r \".tool_input.command\"); if echo \"$CMD\" | grep -qE \"deploy|release|publish\"; then echo \"DEPLOYMENT COMMAND DETECTED. Running pre-flight checks.\" >&2; fi'"
---

Les skills de philosophie s’auto-activent via des hooks SessionStart, injectant des contraintes de qualité dans chaque session sans invocation explicite. Le skill constitue la connaissance. Le hook constitue l’application. Ensemble, ils forment une couche de politique.

Erreurs courantes avec les skills

Descriptions trop larges. Un skill git-rebase-helper qui s’active sur n’importe quel prompt lié à git (rebases, merges, cherry-picks, voire git status) pollue le contexte dans 80 % des sessions. La solution consiste soit à resserrer la description, soit à ajouter disable-model-invocation: true et à exiger une invocation explicite avec /skill-name.⁴

Trop de skills en concurrence pour le budget. Davantage de skills signifie davantage de descriptions en concurrence pour les 1 % du budget de contexte. Si vous constatez que des skills ne s’activent pas, vérifiez /context pour ceux qui sont exclus. Privilégiez un nombre réduit de skills bien décrits plutôt que de nombreux skills vagues.

Informations critiques enfouies dans des fichiers de support. Claude lit SKILL.md immédiatement, mais n’accède aux fichiers de support qu’en cas de besoin. Si des informations critiques se trouvent dans un fichier de support, Claude risque de ne pas les trouver. Placez directement les informations essentielles dans SKILL.md.⁴

Surface des skills SDK (8 mai 2026)

Les harness auto-hébergés sur claude-agent-sdk-python v0.1.77+ doivent utiliser l’option skills de ClaudeAgentOptions pour déclarer les skills disponibles, et non l’ancienne valeur "Skill" dans allowed_tools.³⁷ Le raccourci "Skill" est obsolète et l’option dédiée fournit à Claude Code des informations plus structurées sur les skills disponibles. Le CLI fourni dans la v0.1.77 est v2.1.133.

Convergence des plugins et des skills dans .claude/skills/ (29 mai 2026)

Les skills ont toujours été chargés depuis le dossier .claude/skills/ d’un projet. Claude Code v2.1.157 étend ce dossier aux plugins : un plugin placé dans .claude/skills/ se charge désormais automatiquement, sans inscription à une marketplace, et claude plugin init <name> y génère une nouvelle structure avec le manifest et SKILL.md déjà reliés.⁵⁸ Cela comble l’écart entre les deux formes d’outillage de projet qui vivaient auparavant à des endroits différents — un skill seul, validé directement dans le dépôt, et un plugin qui regroupe un skill, des hooks et un serveur MCP, mais nécessitait auparavant une marketplace pour être installé. L’effet pratique pour la conception de harnesses : les outils limités à un projet n’ont plus besoin d’un détour par un registre pour être livrés — écrivez-les, validez-les, et vos collègues obtiennent la même surface avec git pull. Les plugins conservent leur rôle pour les cas d’installation groupée (hooks + skills + serveurs MCP + agents dans un ZIP) ; le changement est qu’un projet n’a plus besoin de mettre en place une marketplace pour en charger un depuis son propre arbre. Cette convergence repose désormais sur une base inter-fournisseurs : Agent Plugins 1.0.0 (publié le 6 août 2026) standardise la même forme de package — un manifest plugin.json, des dossiers skills/ contenant des dossiers SKILL.md, un mcp.json facultatif — comme « format de package portable pour les agents IA », adopté dès son lancement par VS Code, Cursor, GitHub Copilot, ChatGPT & Codex et Kiro. Il s’agit explicitement d’une couche de packaging autour d’Agent Skills et de MCP, et non d’un remplacement ; notez que Anthropic, auteur de la spécification Agent Skills, ne fait pas encore partie de la coalition — considérez donc la portabilité de Claude vers l’extérieur de Code comme une compatibilité au niveau du format, et non comme un contrat bidirectionnel officiel.⁸⁹

Masquer la surface fournie comme mesure de gouvernance (8 juin 2026)

Les skills sont des capacités, et les capacités constituent une surface d’attaque. Claude Code v2.1.169 ajoute un paramètre disableBundledSkills (ainsi que la variable d’environnement correspondante CLAUDE_CODE_DISABLE_BUNDLED_SKILLS) qui masque entièrement au modèle les skills fournis, les workflows et les slash commands intégrées.⁶⁰ Pour un harness renforcé ou réglementé, il s’agit d’une réduction délibérée de la surface d’attaque : un opérateur qui a audité et approuvé un ensemble précis de skills de projet et personnels peut supprimer tout ce que Anthropic fournit par défaut, afin que le modèle ne raisonne que sur la surface validée par l’opérateur. Traitez cela comme une allowlist d’outils — la configuration par défaut offre de larges capacités, et la désactiver est une décision de gouvernance, non un simple réglage de confort.

.claude/skills imbriqués et résolution « le plus proche l’emporte » (16 juin 2026)

Claude Code v2.1.178 a rendu l’outillage de projet sensible à l’emplacement. Les skills dans des dossiers .claude/skills imbriqués se chargent désormais lorsque vous travaillez sur des fichiers sous ce dossier, et non plus seulement depuis la racine du dépôt ; en cas de conflit de nom, le skill imbriqué apparaît sous la forme <dir>:<name> afin que les deux restent accessibles.⁶³ La même version a fait résoudre le reste de la surface de projet au plus près du répertoire de travail : lorsqu’un nom d’agent, de workflow ou de style de sortie entre en collision dans plusieurs dossiers .claude/ imbriqués, celui qui est le plus proche du répertoire de travail l’emporte, et l’enregistrement d’un workflow de portée projet cible le dossier .claude/workflows/ existant le plus proche plutôt que systématiquement la racine.⁶³ Pour un monorepo ou un dépôt de dépôts, cela fait toute la différence entre une surface globale et plate et des outils par package qui s’activent selon le contexte — un services/api/.claude/skills/ peut contenir des skills spécifiques à API qui n’apparaissent que lorsque vous travaillez dans cet arbre, sans entrer en collision avec un skill services/web/ du même nom.

Architecture des hooks

Les hooks sont des commandes shell déclenchées par des événements de cycle de vie Claude Code.³ Ils s’exécutent hors du LLM sous forme de scripts simples, et non comme des prompts interprétés par le modèle. Le modèle veut exécuter rm -rf / ? Un script bash de 10 lignes vérifie la commande par rapport à une liste de blocage et la rejette avant même que le shell ne la voie. Le hook se déclenche, que le modèle le veuille ou non.

Événements disponibles

Claude Code expose 31 événements de cycle de vie documentés, répartis en huit catégories, à la date de mise à jour de ce guide. La liste des événements s’allonge au fil des versions : considérez donc la documentation de référence comme source de vérité et consultez l’aide-mémoire pour obtenir le tableau complet à jour avant de configurer des hooks en production :¹³

DirectoryAdded (v2.1.219) comble la lacune liée aux espaces de travail ajoutés en cours de session. La liste des événements est restée stable depuis l’arrivée de MessageDisplay dans la v2.1.152 ; DirectoryAdded est le premier nouvel événement de cycle de vie depuis lors, et il se déclenche après que /add-dir — ou la requête de contrôle register_repo_root du SDK — enregistre un nouveau répertoire de travail au cours d’une session.⁸⁴ La lacune qu’il comble est réelle : jusqu’à présent, un harness pouvait valider exhaustivement un espace de travail à SessionStart, puis voir un deuxième dépôt y être ajouté sans qu’aucun hook ne se déclenche. Toute assertion concernant l’espace de travail au démarrage — vérifications de confiance, analyses de secrets, règles de restriction des chemins dérivées de l’arborescence, chargement de politiques par dépôt — doit être réexécutée ici, car l’ensemble des répertoires d’une session n’est plus fixe au lancement. L’événement est informatif plutôt que bloquant : considérez-le comme un déclencheur pour recalculer l’état et enregistrer la provenance, et non comme un garde-fou ; si un répertoire ne doit jamais pouvoir être ajouté, refusez-le dans les paramètres plutôt que d’essayer d’y opposer un veto depuis un hook. La partie SDK est arrivée dans la même version (TypeScript v0.3.219 ajoute DirectoryAdded aux événements de cycle de vie du protocole de contrôle) : les harnesses hébergés par SDK le voient donc au même niveau que ceux de CLI.⁸⁵

Sémantique des codes de sortie

Les codes de sortie déterminent si les hooks bloquent des actions :³

Configuration des hooks

Les hooks sont définis dans des fichiers de paramètres. Au niveau du projet (.claude/settings.json) pour les hooks partagés. Au niveau utilisateur (~/.claude/settings.json) pour les hooks personnels :

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/validate-bash.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'if [[ \"$FILE_PATH\" == *.py ]]; then black --quiet \"$FILE_PATH\" 2>/dev/null; fi'"
          }
        ]
      }
    ]
  }
}

Le champ matcher filtre une valeur propre à l’événement. Pour les événements d’outil, il correspond aux valeurs de tool_name telles que Bash, Edit, Write, Read, Glob, Grep, aux noms d’outils MCP tels que mcp__server__tool, ou à * pour tous les outils. Les noms simples et les listes séparées par | sont des correspondances exactes ; les valeurs contenant d’autres caractères sont des expressions régulières JavaScript. Certains événements ne prennent pas en charge les matchers et se déclenchent toujours lorsqu’ils sont configurés.¹³ Depuis Claude Code v2.1.195, les matchers contenant des identifiants avec trait d’union (code-reviewer, mcp__brave-search) appliquent une correspondance exacte au lieu d’une correspondance accidentelle par sous-chaîne : un hook ciblant un agent ou serveur ne se déclenche plus pour chaque nom contenant simplement cette chaîne ; pour couvrir tous les outils d’un serveur MCP avec trait d’union, écrivez le modèle explicite mcp__brave-search__.*.⁶⁶ La v2.1.214 a appliqué la même rigueur aux modèles de chemin : une condition if: de hook utilisant un modèle à segment unique dir/** ne correspond désormais qu’à <cwd>/dir, et non à chaque répertoire nommé dir n’importe où dans l’arborescence — écrivez **/dir/** lorsque vous visez réellement toutes les profondeurs.⁷⁴ Comme pour le changement de la v2.1.195, la correction remplace une étendue accidentelle par une intention déclarée ; auditez toutes les conditions de hook qui dépendaient silencieusement de l’ancien comportement à toute profondeur.

Protocole d’entrée/sortie des hooks

Les hooks reçoivent du JSON sur stdin avec tout le contexte :

{
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test",
    "description": "Run test suite"
  },
  "session_id": "abc-123",
  "agent_id": "main",
  "agent_type": "main"
}

Pour un contrôle avancé, les hooks PreToolUse peuvent produire du JSON afin de modifier l’entrée de l’outil, injecter du contexte ou prendre des décisions d’autorisation. Utilisez l’enveloppe hookSpecificOutput — l’ancien format decision/reason au niveau supérieur est déconseillé pour PreToolUse :

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",
    "permissionDecisionReason": "Command validated and modified",
    "updatedInput": {
      "command": "npm test -- --coverage --ci"
    },
    "additionalContext": "Note: This database has a 5-second query timeout."
  }
}

Trois types de garanties

Avant d’écrire un hook, posez-vous la question : de quel type de garantie ai-je besoin ?¹⁴

Les garanties de formatage assurent la cohérence après coup. Les hooks PostToolUse sur Write/Edit exécutent votre formateur après chaque modification de fichier. La sortie du modèle n’a pas d’importance, car le formateur normalise tout.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'if [[ \"$FILE_PATH\" == *.py ]]; then black --quiet \"$FILE_PATH\" 2>/dev/null; elif [[ \"$FILE_PATH\" == *.js ]] || [[ \"$FILE_PATH\" == *.ts ]]; then npx prettier --write \"$FILE_PATH\" 2>/dev/null; fi'"
          }
        ]
      }
    ]
  }
}

Les garanties de sécurité empêchent les actions dangereuses avant leur exécution. Les hooks PreToolUse sur Bash inspectent les commandes et bloquent les modèles destructeurs avec le code de sortie 2 :

#!/bin/bash
# validate-bash.sh — block dangerous commands
INPUT=$(cat)
CMD=$(echo "$INPUT" | jq -r '.tool_input.command')

if echo "$CMD" | grep -qE "rm\s+-rf\s+/|git\s+push\s+(-f|--force)\s+(origin\s+)?main|git\s+reset\s+--hard|DROP\s+TABLE"; then
    echo "BLOCKED: Dangerous command detected: $CMD" >&2
    exit 2
fi

Les garanties de qualité valident l’état aux points de décision. Les hooks PreToolUse sur les commandes git commit exécutent votre linter ou votre suite de tests et bloquent le commit si les contrôles qualité échouent :

#!/bin/bash
# quality-gate.sh — lint before commit
INPUT=$(cat)
CMD=$(echo "$INPUT" | jq -r '.tool_input.command')

if echo "$CMD" | grep -qE "^git\s+commit"; then
    if ! LINT_OUTPUT=$(ruff check . --select E,F,W 2>&1); then
        echo "LINT FAILED -- fix before committing:" >&2
        echo "$LINT_OUTPUT" >&2
        exit 2
    fi
fi

Types de hooks au-delà des commandes shell

Claude Code prend en charge cinq types de hooks :¹³ Hooks de commande (type: "command") exécutent des scripts shell. Rapides, déterministes, sans coût en tokens.

Hooks d’outil MCP (type: "mcp_tool") appellent un outil sur un serveur MCP déjà connecté. Utilisez-les lorsque la logique de validation existe déjà derrière une frontière MCP et ne nécessite pas de script shell distinct.

Hooks de prompt (type: "prompt") envoient un prompt à un seul tour à un modèle Claude rapide. Le modèle renvoie { "ok": true } pour autoriser ou { "ok": false, "reason": "..." } pour bloquer. Utilisez-les pour une évaluation nuancée qu’une regex ne peut pas exprimer.

Hooks d’agent (type: "agent") lancent un subagent ayant accès aux outils (Read, Grep, Glob) afin d’effectuer une vérification sur plusieurs tours. Ils sont expérimentaux ; privilégiez les hooks de commande pour les gates de production et réservez les hooks d’agent aux contrôles qui nécessitent réellement d’inspecter des fichiers ou des résultats de test :

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "Verify all unit tests pass. Run the test suite and check results. $ARGUMENTS",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

Depuis Claude Code v2.1.140, l’entrée des hooks d’agent inclut subagent_type, ce qui permet à un hook partagé de distinguer une exécution security-reviewer d’un explorer ou d’un worker générique sans devoir le déduire du texte du prompt.⁴⁹

Hooks HTTP (type: "http") envoient l’entrée JSON de l’événement sous forme de requête POST vers une URL et reçoivent JSON en retour. Utilisez-les pour les webhooks, les services de notification externes ou la validation basée sur API (v2.1.63+). Ils ne sont pas pris en charge pour les événements SessionStart :

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "http",
            "url": "https://your-webhook.example.com/hook",
            "headers": { "Authorization": "Bearer $WEBHOOK_TOKEN" },
            "allowedEnvVars": ["WEBHOOK_TOKEN"],
            "timeout": 10
          }
        ]
      }
    ]
  }
}

Hooks asynchrones

Les hooks peuvent s’exécuter en arrière-plan sans bloquer l’exécution. Ajoutez async: true pour les opérations non critiques telles que les notifications et la journalisation :¹³

{
  "type": "command",
  "command": ".claude/hooks/notify-slack.sh",
  "async": true
}

Utilisez l’asynchrone pour les notifications, la télémétrie et les sauvegardes. Ne l’utilisez jamais pour le formatage, la validation ou toute autre opération qui doit se terminer avant l’action suivante.

Dispatchers plutôt que hooks indépendants

Exécuter sept hooks qui se déclenchent tous sur le même événement et lisent chacun stdin indépendamment crée des conditions de concurrence. Deux hooks écrivant simultanément dans le même fichier d’état JSON tronqueront ce dernier JSON. Chaque hook en aval qui analyse ce fichier échoue.²

La solution : un dispatcher par événement, qui exécute les hooks séquentiellement à partir de stdin mis en cache :

#!/bin/bash
# dispatcher.sh — run hooks sequentially with cached stdin
INPUT=$(cat)
HOOK_DIR="$HOME/.claude/hooks/pre-tool-use.d"

for hook in "$HOOK_DIR"/*.sh; do
    [ -x "$hook" ] || continue
    echo "$INPUT" | "$hook"
    EXIT_CODE=$?
    if [ "$EXIT_CODE" -eq 2 ]; then
        exit 2  # Propagate block
    fi
done

Déboguer les hooks

Cinq techniques pour déboguer des hooks qui échouent silencieusement :¹⁴

1. Testez les scripts indépendamment. Injectez un exemple de JSON : echo '{"tool_input":{"command":"git commit -m test"}}' | bash your-hook.sh
2. Utilisez stderr pour la sortie de débogage. Le stderr associé au code de sortie 2 est renvoyé à Claude sous forme de message d’erreur. Le stderr non bloquant (sortie 1, 3, etc.) n’apparaît qu’en mode verbeux (Ctrl+O).
3. Surveillez les échecs de jq. Des chemins JSON erronés renvoient silencieusement null. Testez les expressions jq avec de véritables entrées d’outil.
4. Vérifiez les codes de sortie. Un hook PreToolUse qui utilise exit 1 n’applique aucune contrainte, tout en donnant l’impression de fonctionner.
5. Gardez les hooks rapides. Les hooks s’exécutent de manière synchrone. Gardez tous les hooks sous les 2 secondes, idéalement sous les 500 ms.

Streaming d’événements de hook côté SDK

Les harnesses auto-hébergés construits sur claude-agent-sdk-python (v0.1.74+, 6 mai 2026) peuvent s’abonner directement aux événements de hook depuis le flux de messages, plutôt que de passer par des callbacks de scripts shell.³⁶ Définissez include_hook_events=True dans ClaudeAgentOptions ; les objets HookEventMessage (PreToolUse, PostToolUse, Stop et autres) sont alors produits par le même itérateur que les messages de l’assistant et les résultats d’outil. Cela reproduit l’option includeHookEvents du SDK TypeScript ; le CLI intégré est passé à v2.1.129 dans la même version.

Le modèle de flux d’événements convient lorsque votre harness se trouve déjà dans Python et que vous souhaitez gérer les signaux de hook dans le même flux de contrôle que la sortie du modèle. Le contrat de hook par script shell (codes de sortie, stdin JSON, dispatchers) reste la meilleure réponse pour les harnesses qui composent plusieurs outils, partagent des hooks entre Claude Code et Codex, ou nécessitent la sémantique des codes de sortie pour bloquer.

La série de juillet 2026 du SDK TypeScript (v0.3.205–v0.3.208) a rendu le protocole de streaming lui-même plus contractuel.⁷⁰ Les interruptions renvoient désormais des reçus typés : une interruption confirme quels messages placés en file d’attente le restent, via les UUID still_queued, et les sessions annoncent la capacité interrupt_receipt_v1 dans system/init. Un coordinateur peut ainsi distinguer « l’interruption a été prise en compte » de « l’interruption est arrivée après le départ d’un message déjà en cours ». Les frames command_lifecycle indiquent l’état queued/started/completed/cancelled/discarded de chaque message — la première réponse first-party à « qu’est-il arrivé au message que j’ai envoyé ? » sans inférence à partir de la transcription. Des surfaces plus modestes ont également été ajoutées : un type AgentToolCompletedOutput pour les payloads de fin de subagent, et les callbacks canUseTool peuvent désormais renvoyer {behavior: 'allow'} sans champ updatedInput.

Une ligne de cette série constitue un plancher de sécurité, non une fonctionnalité : la v0.3.208 a corrigé la conversion en succès de hook d’une annulation de l’appelant survenant alors qu’un hook était en attente — ce qui signifiait qu’un outil contrôlé par un hook PreToolUse pouvait s’exécuter après l’annulation par l’appelant.⁷⁰ Si votre harness utilise des hooks côté SDK comme gate d’autorisation et s’appuie sur l’annulation pour interrompre le travail en cours, considérez v0.3.208 comme la version minimale ; en dessous, « annulé » ne signifiait pas de manière fiable « bloqué ». Python v0.2.127 (24 juillet 2026) constitue le deuxième contournement de cette forme en un mois : query() fermait stdin dès la première frame result alors que des subagents en arrière-plan étaient encore actifs. Leurs appels d’outil SDK-MCP échouaient donc avec "Stream closed" et contournaient entièrement les hooks PreToolUse.⁸⁵ Nommez ce schéma et surveillez-le : l’application des hooks côté SDK échoue en mode permissif aux frontières du cycle de vie — annulation, démontage, fermeture du flux — lorsque le transport meurt avant que le verdict du hook soit recueilli. Elle échoue silencieusement, car un hook contourné ressemble exactement à un hook qui a autorisé l’action. Épinglez les deux versions minimales de SDK et conservez la couche de hooks shell comme mécanisme d’application que vous pouvez prouver.

Effort et provenance de session (7-8 mai 2026)

Deux ajouts dans Claude Code v2.1.132 et v2.1.133 donnent aux hooks et aux sous-processus davantage de signal sur leur contexte d’exécution :³⁸³⁹

• effort.level dans l’entrée de hook. Les hooks reçoivent désormais un champ JSON effort.level dans la même entrée que tool_input et session_id. La même valeur est exportée comme variable d’environnement $CLAUDE_EFFORT, afin que les commandes Bash puissent la lire sans analyser JSON. Utilisez-la pour adapter le coût des hooks au niveau d’effort : ignorez les validations coûteuses sur low, exécutez le gate de sécurité complet sur xhigh ou max.
• Variable d’environnement CLAUDE_CODE_SESSION_ID dans les sous-processus Bash. Les sous-processus de l’outil Bash voient désormais la même valeur session_id que les hooks, exposée sous le nom CLAUDE_CODE_SESSION_ID. Cela comble le manque de provenance pour les outils qui journalisent un état par session et ne pouvaient auparavant pas corréler les événements des sous-processus avec les événements de hook.

Les deux signaux sont disponibles sans modification du code ; les hooks existants qui ignorent les nouveaux champs continuent de fonctionner.

autoMode.hard_deny et correctifs de hooks/plugins v2.1.136 (8 mai 2026)

Claude Code v2.1.136 a ajouté un nouveau niveau de refus strict au mode automatique et corrigé un ensemble de problèmes de plugin et MCP qui affectaient les harnesses de longue durée :⁴⁰ - settings.autoMode.hard_deny. Règles du classifieur du mode automatique qui bloquent sans condition, quelles que soient l’intention de l’utilisateur ou les exceptions d’autorisation. Elles se placent au-dessus des matchers allow/deny existants comme levier de gouvernance non négociable. Utilisez-les pour les règles qui ne doivent jamais être contournées (force-push vers main, fichiers contenant des secrets, accès à la base de données de production), même lorsqu’un opérateur a approuvé la catégorie plus large dans ses paramètres personnels. - autoMode.classifyAllShell (v2.1.193). Par défaut, le classifieur du mode automatique n’examine que les commandes shell correspondant à des schémas d’exécution de code arbitraire. Ce paramètre envoie chaque commande Bash/PowerShell au classifieur — la posture de couverture maximale pour un harness gouverné — et la même version affiche les raisons de refus dans la transcription, la notification et /permissions, ce qui transforme des blocages silencieux en décisions auditables. Codex a renforcé la surface équivalente dans la v0.142.2 : les commandes PowerShell comportant des régions AST exécutables que son classifieur de sécurité ne peut pas inspecter nécessitent désormais une approbation au lieu de passer silencieusement.⁶⁶ - Hook ask impose un plancher au classifieur (v2.1.211). La question de préséance entre hooks et mode automatique est désormais tranchée : un hook PreToolUse qui renvoie une décision de permission ask fixe le résultat final à une demande — le mode automatique ne peut pas l’élever à allow pour des commandes Bash non sandboxées.⁶⁹ Pour un harness gouverné, c’est le niveau de garantie qui manquait : un ask de hook est un arrêt déterministe avec intervention humaine, qui persiste même avec des postures de permission entièrement automatiques. Utilisez ask (et pas seulement des blocages exit-2) pour les opérations où vous souhaitez une décision humaine plutôt qu’un refus. - Le modèle du classifieur est épinglé par session (v2.1.210). Le classifieur du mode automatique utilise Sonnet 5 par défaut et est épinglé pour la session ; les changements de modèle en cours de session ne modifient donc plus le modèle qui effectue les classifications de permissions.⁶⁹ La cohérence des classifications est une propriété de gouvernance ; cela élimine une source discrète de dérive. - Les serveurs MCP ne disparaissent plus après /clear. Les serveurs configurés dans .mcp.json, les plugins et les connecteurs claude.ai disparaissaient silencieusement de l’ensemble actif après un /clear dans l’extension VS Code, le plugin JetBrains et Agent SDK. Le correctif arrive dans la v2.1.136. Si vous avez constaté que « MCP server X went missing mid-session », c’en était la cause. - Perte du refresh token MCP OAuth lors d’un rafraîchissement simultané. Les utilisateurs disposant de plusieurs serveurs MCP distants ne devraient plus avoir besoin de se réauthentifier quotidiennement. Les écritures de rafraîchissement simultanées s’écrasaient mutuellement. - Le mode Plan bloque désormais correctement les écritures de fichiers. Une règle allow Edit(...) correspondante contournait la protection contre les écritures du mode Plan. Le mode Plan est maintenant appliqué indépendamment des règles allow. - Les hooks Stop et UserPromptSubmit de plugins n’échouent plus en cours de session. Le nettoyage du cache supprimait des fichiers de version de plugin encore utilisés par la session en cours, ce qui cassait spécifiquement ces deux événements de hook. Le correctif conserve les versions utilisées épinglées. - Entrée skills dans plugin.json. Définir skills masquait le dossier skills/ par défaut du plugin. Désormais, l’entrée se compose correctement, et la faire pointer vers un chemin de fichier déclenche une erreur explicite au lieu d’échouer silencieusement. - Variables d’environnement du hook SessionStart CLAUDE_ENV_FILE devenant obsolètes. Les variables exportées par les hooks SessionStart via CLAUDE_ENV_FILE devenaient obsolètes après /resume ou /clear. Corrigé dans la v2.1.136. Les sessions rechargent maintenant le fichier d’environnement lors de ces événements.

Pour les harnesses de gouvernance, les éléments opérationnellement intéressants sont autoMode.hard_deny (nouveau levier) et le correctif de disparition de MCP (échec silencieux qui cassait les longues sessions). Tout le reste relève d’un nettoyage de confort.

Arguments de hook structurés et poursuite après blocage (11 mai 2026)

Claude Code v2.1.139 a ajouté deux détails de hooks importants pour les harnesses de production : une forme d’exécution args: string[] pour les hooks de commande, et continueOnBlock pour les hooks PostToolUse.⁴²⁴⁴ Préférez args lorsqu’un hook nécessite des valeurs dynamiques ou des placeholders de chemin. La commande est lancée directement, sans shell, ce qui élimine toute une catégorie d’erreurs de quoting et d’injection.

Utilisez continueOnBlock lorsqu’un hook PostToolUse doit renvoyer sa raison de rejet à Claude et poursuivre le tour au lieu de mettre fin au flux. Considérez-le comme une fonctionnalité d’expérience opérateur, et non comme un contournement de sécurité. Une gate bloquante doit toujours bloquer le résultat non sûr.

La même version transmet CLAUDE_PROJECT_DIR aux serveurs stdio MCP et permet aux configurations de plugins de référencer ${CLAUDE_PROJECT_DIR} dans les commandes.⁴² Les outils MCP doivent résoudre les chemins relatifs au projet à partir de cette valeur plutôt que du répertoire de travail du processus qui a lancé le serveur. Les versions du début juillet 2026 (v2.1.203–v2.1.206) ont étendu le même principe au niveau du protocole : roots/list de MCP inclut désormais les répertoires de travail supplémentaires de la session, avec des notifications roots/list_changed lorsqu’ils changent — ainsi, un serveur qui respecte les roots MCP suit la véritable structure de l’espace de travail multi-répertoires au lieu de supposer un seul répertoire de projet.⁶⁸

Claude Code v2.1.140 est principalement une version de fiabilité pour les opérateurs de harnesses : elle corrige les hooks ConfigChange qui ne se déclenchaient pas lors de modifications des paramètres, ferme des cas limites où disableAllHooks et allowManagedHooksOnly ne se composaient pas correctement entre les niveaux de paramètres, et empêche les dialogues de permission d’exposer des variables d’environnement non intentionnelles renvoyées par les résultats de hook.⁴⁹ Cela rend les modèles de gouvernance existants de cette section plus fiables ; aucune nouvelle architecture de hook n’est nécessaire.

Claude Code v2.1.141 ajoute un champ terminalSequence dans la sortie de hook pour les notifications de bureau, les titres de fenêtre et les alertes sonores sans terminal de contrôle.⁵⁰ Considérez-le comme une signalisation opérateur, et non comme un mécanisme d’application. Les gates de sécurité et de qualité doivent toujours communiquer les échecs via le contrat de blocage normal : sortie de hook structurée et comportement de sortie qui empêche l’action non sûre. La même version ajoute claude agents --cwd <path> pour limiter Agent View à un répertoire, CLAUDE_CODE_PLUGIN_PREFER_HTTPS pour les installations de plugins dans les environnements sans clés GitHub SSH, et ANTHROPIC_WORKSPACE_ID pour les règles de fédération d’identité de charge de travail couvrant plus d’un espace de travail.⁵⁰ Ce sont des détails d’architecture pour les harnesses d’équipe : vues opérationnelles plus étroites, moins d’hypothèses sur l’installation des plugins et délimitation explicite des tokens d’entreprise.

Claude Code v2.1.142 est plus important pour l’orchestration des sessions en arrière-plan que pour la sémantique des hooks.⁵¹ claude agents peut désormais dispatcher des sessions en arrière-plan avec des flags explicites de répertoire, paramètres, MCP, plugin, permission, modèle et effort, au lieu de dépendre de l’état d’un wrapper. Le mode Fast utilisait Opus 4.7 par défaut dans cette version, avec CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE=1 comme épinglage pour un harness dont le comportement dépend de manière mesurée d’Opus 4.6 — à compter de la v2.1.219, Opus 4.7 n’est plus du tout en mode Fast et /fast s’applique à Opus 5 et Opus 4.8.⁸⁴ La découverte de SKILL.md à la racine des plugins et la visibilité LSP fournie par les plugins réduisent l’ambiguïté de packaging. Les correctifs apportés à MCP_TOOL_TIMEOUT, aux worktrees de sessions en arrière-plan préexistants, à la mise en veille/réveil des daemons et au nettoyage post-mise à niveau, ainsi qu’au nettoyage du cache des plugins, comblent des lacunes de fiabilité qui ressemblent autrement à des bugs d’orchestration.

Pilotage par hook Stop, autorité inter-session et multi-agent v2 (juin 2026)

Quatre changements du début juin sont importants pour la conception des harnesses et du multi-agent.⁵⁹

Les hooks Stop/SubagentStop ont acquis un canal de pilotage. À partir de Claude Code v2.1.163, un hook Stop ou SubagentStop peut renvoyer hookSpecificOutput.additionalContext afin de transmettre un retour à Claude et de poursuivre le tour, sans que la réponse soit étiquetée comme une erreur de hook. Auparavant, le seul véritable levier d’un hook Stop était le blocage exit-2, qui est interprété comme une erreur et compte dans le plafond des blocages consécutifs. Pour un harness de gate qualité, c’est la primitive la plus propre : un hook Stop qui détecte « vous avez déclaré avoir terminé mais les tests sont en échec » peut désormais injecter « voici ce qui échoue encore, poursuivez » au lieu de bloquer durement. Utilisez le blocage pour les véritables conditions d’arrêt et additionalContext pour « pas encore terminé, voici pourquoi ».

La messagerie inter-session ne transporte plus d’autorité empruntée. La v2.1.166 a renforcé le cas multi-session : les messages relayés via SendMessage depuis une autre session Claude ne transportent plus l’autorité de l’utilisateur d’origine ; une session destinataire refuse donc les demandes de permission relayées et le mode automatique les bloque. Si votre orchestration fait communiquer des agents entre eux, traitez un message entrant comme des données non fiables, et non comme une instruction authentifiée. C’est le même principe que la section sécurité applique à la sortie des outils, étendu à la messagerie inter-agents. À partir de la v2.1.199, Claude Code détecte et avertit également lorsqu’un SendMessage est mal routé parce que deux agents partagent le même nom — un complément de fiabilité à cette limite d’autorité, puisqu’un message qui atteint le mauvais agent portant le même nom constitue sa propre catégorie de bug d’orchestration. Les sessions sont désormais des pairs de premier rang (v2.1.224+). La messagerie intersessions est passée du renforcement du relais à une surface complète : SendMessage/ListAgents permettent à vos sessions de se découvrir et de s’envoyer des messages entre vos machines (macOS/Linux), avec des contrôles crossSessionInbound accepter/mettre en attente/refuser côté réception — et les self-hosted runners permettent aux sessions web et mobiles de Claude Code de s’exécuter sur le matériel que vous contrôlez. Pour l’architecture de harness, cela transforme « une session » en nœud adressable : la découverte, la politique entrante et la limite d’autorité ci-dessus sont désormais des primitives de plateforme, et non des scripts de boîte aux lettres (le guide Claude Code documente le contrat complet).⁸⁷ Un changement de posture l’accompagne : le mode auto devient le mode d’autorisation par défaut pour les forfaits Pro, Max et Team le 14 août 2026 — un harness qui compte sur les sollicitations du mode Manual comme filet de sécurité humain dans la boucle doit définir explicitement defaultMode plutôt que de le supposer.⁸⁷

La résilience des modèles est devenue un paramètre de premier rang. Le paramètre fallbackModel enchaîne désormais jusqu’à trois modèles de secours, essayés dans l’ordre lorsque le modèle principal est surchargé ou indisponible, et un tour réessaie automatiquement une fois avec le modèle de secours en cas d’erreurs API inattendues et non réessayables. Pour un harness autonome de longue durée, cela transforme une indisponibilité transitoire du modèle principal en dégradation gracieuse plutôt qu’en exécution abandonnée. claude agents --json a également ajouté un champ waitingFor (v2.1.162) qui indique ce qu’attend une session en arrière-plan bloquée, comme une demande d’autorisation — un gain d’observabilité pour tout coordinateur qui interroge une flotte d’agents.

Mode sans échec pour la gouvernance en environnement isolé et le dépannage. Claude Code v2.1.169 ajoute un flag --safe-mode (et la variable d’environnement CLAUDE_CODE_SAFE_MODE correspondante) qui démarre une session avec toutes les personnalisations désactivées simultanément : CLAUDE.md, plugins, skills, hooks et serveurs MCP.⁶⁰ C’est l’inverse du harness — un environnement isolé délibéré. Utilisez-le pour répondre à la question que tout opérateur finit par se poser : « ce comportement vient-il du modèle, ou de ce que j’ai configuré ? » Lorsqu’un hook se déclenche mal, qu’un skill s’active alors qu’il ne devrait pas, ou qu’un serveur MCP empoisonne le contexte, --safe-mode vous offre une base connue et vide à comparer. C’est aussi une primitive de gouvernance : une manière d’exécuter le modèle nu sans aucune de l’autorité persistante que votre harness accorde habituellement, ce qui importe lorsque vous devez reproduire un résultat sans qu’aucun échafaudage défini par l’opérateur ne l’influence.

Note sur les niveaux de modèles. Depuis Claude Code v2.1.197 (30 juin 2026), Claude Sonnet 5 est le modèle par défaut livré pour les nouvelles sessions — contexte natif de 1M, tarif promotionnel de 2 $/10 $ par MTok jusqu’au 31 août — remplaçant Opus 4.8 comme choix prêt à l’emploi. Ce guide considère Opus 5 (claude-opus-5) comme le choix agentique recommandé par défaut : le modèle sur lequel exécuter des harnesses autonomes, sauf choix délibéré contraire, car les boucles d’agents à long horizon et à forts enjeux sont précisément celles où la profondeur de raisonnement d’Opus justifie son coût. Opus 5 est sorti le 24 juillet 2026 comme nouvel Opus par défaut dans Claude Code v2.1.219 — contexte de 1M, 5 $/25 $ par MTok (le même prix que l’Opus 4.8 qu’il remplace), mode rapide à 10 $/50 $ pour une vitesse environ 2,5× supérieure à celle par défaut — et Anthropic indique qu’il fait plus que doubler Opus 4.8 sur Frontier-Bench v0.1 tout en se situant à moins de 0,5 % du score CursorBench 3.2 de Fable 5, pour la moitié du coût.⁸⁴⁹¹ Même prix, davantage de capacités, et un modèle que Anthropic qualifie de « beaucoup plus performant pour vérifier son travail et itérer avec soin » : c’est la rare mise à niveau qui n’exige aucun argument de coût pour le travail sur les harnesses ; la migration depuis 4.8 se résume à un changement d’identifiant. Passez à Sonnet 5 pour les travaux sensibles au coût ou à très haut débit, lorsque son ratio vitesse/intelligence l’emporte. Au-dessus d’Opus se trouve Claude Fable 5 (claude-fable-5), lancé le 9 juin 2026 — un nouveau niveau décrit comme le modèle le plus puissant de Anthropic, un système de « classe Mythos » rendu sûr pour un usage général, sélectionnable dans Claude Code v2.1.170 via /model claude-fable-5.⁶⁰ Optez délibérément pour ce niveau supérieur, pour les décisions où la profondeur brute de raisonnement justifie le coût, et non comme paramètre général pour une flotte. Le basculement vers Opus 5 entraîne deux conséquences d’entretien : Opus 4.7 n’est plus disponible en mode rapide (/fast s’applique désormais à Opus 5 et Opus 4.8), et le repli Fable-5 du classificateur du mode auto — « le meilleur modèle Opus disponible » depuis la v2.1.176 — se résout désormais vers Opus 5.⁸⁴

Codex a livré le multi-agent v2. Codex CLI v0.137.0 conserve le choix d’exécution avec chaque thread, expose des valeurs par défaut plus propres pour les suivis et les métadonnées des agents générés (hide_spawn_agent_metadata est désormais défini sur true par défaut), et propage les événements bruts du parent aux écouteurs enfants. Son modèle de subagents reste explicite : types d’agents intégrés default/worker/explorer, agents personnalisés définis en TOML et contrôles de concurrence (agents.max_threads par défaut à 6, agents.max_depth par défaut à 1). La même version ajoute une extension de skills v1 avec résolution du catalogue de skills à chaque tour et de nouveaux événements contributeurs de cycle de vie de démarrage de thread/d’erreur de tour, réduisant l’écart avec la surface hooks/skills de Claude Code tout en conservant la posture de sandbox du kernel comme limite par défaut. Codex v0.138.0–v0.139.0 a ensuite renforcé le multi-agent v2 pour la production : les charges utiles des messages inter-agents sont désormais chiffrées, un catalogue de configuration d’agents v2 ainsi qu’un LRU de résidence des agents gèrent quels agents restent résidents, et la concurrence est comptée selon l’exécution active plutôt que selon les threads générés, afin que les agents inactifs ne consomment plus de slot.⁶¹ Le cycle de vie API a également mûri : close_agent a été renommé interrupt_agent (v0.139.0) afin de refléter qu’il interrompt un agent en cours d’exécution plutôt que de simplement fermer un handle — et les avertissements de démarrage MCP levés par un subagent restent désormais limités au thread propriétaire au lieu de remonter en double dans la transcription du parent.⁶¹ Pour quiconque construit une orchestration côté Codex, ces éléments font la différence entre une démo et une flotte : transport de messages chiffré, résidence limitée, concurrence comptée par exécution et avertissements qui ne franchissent pas la limite du thread. Codex v0.140.0 a ensuite ouvert une jonction inter-outil : /import récupère sélectivement la configuration, la config de projet et les discussions récentes de Claude Code dans Codex, et les sessions sont devenues supprimables de manière permanente (codex delete / /delete, avec garde-fous de confirmation).⁶⁴ /import est la première reconnaissance officielle que les opérateurs passent d’un harness à l’autre — la configuration que vous construisez pour l’un n’y est plus enfermée.

Mémoire et contexte

Chaque conversation avec une IA fonctionne dans une fenêtre de contexte limitée. À mesure que la conversation s’allonge, le système compresse les tours précédents pour libérer de la place pour le nouveau contenu. Cette compression est avec perte. Des décisions architecturales documentées au tour 3 peuvent ne pas survivre jusqu’au tour 15.⁹

Les trois mécanismes d’effondrement sur plusieurs tours

L’étude MSR/Salesforce a identifié trois mécanismes indépendants, chacun nécessitant une intervention différente :⁹

Stratégie 1 : le système de fichiers comme mémoire

La mémoire la plus fiable au-delà des frontières du contexte réside dans le système de fichiers. Claude Code lit CLAUDE.md et les fichiers de mémoire au début de chaque session et après chaque compaction.⁶

~/.claude/
├── configs/           # 14 JSON configs (thresholds, rules, budgets)
│   ├── deliberation-config.json
│   ├── recursion-limits.json
│   └── consensus-profiles.json
├── hooks/             # 95 lifecycle event handlers
├── skills/            # 44 reusable knowledge modules
├── state/             # Runtime state (recursion depth, agent lineage)
├── handoffs/          # 49 multi-session context documents
├── docs/              # 40+ system documentation files
└── projects/          # Per-project memory directories
    └── {project}/memory/
        └── MEMORY.md  # Always loaded into context

Le fichier MEMORY.md consigne les erreurs, les décisions et les modèles récurrents entre les sessions. Lorsque vous découvrez que ((VAR++)) échoue avec set -e dans bash lorsque VAR vaut 0, vous le consignez. Trois sessions plus tard, lorsque vous rencontrez un cas limite similaire sur les entiers dans Python, l’entrée de MEMORY.md fait ressortir ce modèle.¹⁵

Mémoire automatique (v2.1.32+) : Claude Code enregistre et rappelle automatiquement le contexte du projet. Pendant votre travail, Claude écrit des observations dans ~/.claude/projects/{project-path}/memory/MEMORY.md. La mémoire automatique charge les 200 premières lignes dans votre prompt système au début de la session. Gardez ce fichier concis et liez des fichiers thématiques distincts pour les notes détaillées.⁶ Depuis la v2.1.210, une écriture dans MEMORY.md qui dépasse la limite de taille échoue au lieu d’être silencieusement tronquée⁶⁹ — l’échec apparaît au moment de l’écriture plutôt que sous la forme d’entrées mémoire disparues sans bruit. Si votre harness automatise les écritures de mémoire, gérez cette erreur ; la plateforme vous indique que le fichier doit être entretenu, et non qu’il faut réessayer.

Curation de la mémoire plutôt que volume de mémoire (mai 2026) : une récente prépublication arXiv sur la coopération entre agents LLM présente l’augmentation du rappel comme un mode d’échec possible : dans les expériences des auteurs, un historique visible plus long a dégradé la coopération dans 18 des 28 configurations de jeux de modèles.⁴⁸ Considérez cela comme un avertissement de conception, et non comme une loi établie. La règle de production est déjà suffisamment claire : gardez MEMORY.md court, renvoyez vers les détails et placez des synthèses prêtes à la décision dans les handoffs. Les exports bruts de transcriptions, les journaux d’outils et les longs flux de rappel doivent rester dans un stockage interrogeable, pas être automatiquement injectés dans le prompt actif.

Stratégie 2 : compaction proactive

La commande /compact de Claude Code résume la conversation et libère de l’espace de contexte tout en préservant les décisions clés, le contenu des fichiers et l’état de la tâche.¹⁵

Quand compacter : - Après avoir achevé une sous-tâche distincte (fonctionnalité implémentée, bug corrigé) - Avant de commencer une nouvelle zone de la base de code - Lorsque Claude commence à répéter ou à oublier le contexte antérieur - Environ toutes les 25 à 30 minutes pendant les sessions intensives

Instructions de compaction personnalisées dans CLAUDE.md :

# Summary Instructions
When using compact, focus on:
- Recent code changes
- Test results
- Architecture decisions made this session

La compaction protège la conversation ; la commande /cd (Claude Code v2.1.169) protège le cache de prompt. Elle déplace une session vers un nouveau répertoire de travail en cours de route sans casser le cache accumulé au fil des tours.⁶⁰ Auparavant, changer de répertoire impliquait une nouvelle session et un cache froid. Pour une session longue qui bascule d’un dépôt à un dépôt frère — situation courante dans les monorepos et le travail multi-services — /cd conserve intact le préfixe coûteux mis en cache tout en redirigeant le contexte du système de fichiers.

Stratégie 3 : handoffs de session

Pour les tâches qui s’étendent sur plusieurs sessions, créez des documents de handoff qui capturent l’état complet :

## Handoff: Deliberation Infrastructure PRD-7
**Status:** Hook wiring complete, 81 Python unit tests passing
**Files changed:** hooks/post-deliberation.sh, hooks/deliberation-pride-check.sh
**Decision:** Placed post-deliberation in PostToolUse:Task, pride-check in Stop
**Blocked:** Spawn budget model needs inheritance instead of depth increment
**Next:** PRD-8 integration tests in tests/test_deliberation_lib.py

La structure Statut/Fichiers/Décision/Bloqué/Suivant fournit à la session suivante tout le contexte avec un coût minimal en tokens. Démarrer une nouvelle session avec claude -c (continuer) ou lire le document de handoff permet de passer directement à l’implémentation.¹⁵

Stratégie 4 : itération à contexte neuf (la boucle Ralph)

Pour les sessions dépassant 60 à 90 minutes, lancez une nouvelle instance de Claude par itération. L’état persiste via le système de fichiers, et non via la mémoire conversationnelle. Chaque itération bénéficie de l’intégralité du budget de contexte :¹⁶

Iteration 1: [fresh context] -> writes code, creates files, updates state
Iteration 2: [fresh context] -> reads state from disk, continues
Iteration 3: [fresh context] -> reads updated state, continues
...
Iteration N: [fresh context] -> reads final state, verifies criteria

Comparez avec une seule session longue :

Minute 0:   [fresh context]        -> productive
Minute 30:  [context filling]      -> somewhat productive
Minute 60:  [mostly consumed]      -> degraded
Minute 90:  [compaction pending]   -> significantly degraded
Minute 120: [compressed, lossy]    -> errors accumulate

L’approche à contexte neuf pour chaque itération échange un surcoût de 15 à 20 % pour l’étape d’orientation (lecture des fichiers d’état, analyse de l’historique git) contre des ressources cognitives complètes à chaque itération.¹⁶ Le calcul coût-bénéfice est le suivant : pour les sessions de moins de 60 minutes, une seule conversation est plus efficace. Au-delà de 90 minutes, un contexte neuf produit des résultats de meilleure qualité malgré ce surcoût.

Stratégie 5 : curation gérée de la mémoire (Dreaming)

Les Managed Agents de Anthropic et Claude ont ajouté Dreaming en tant que Research Preview le 6 mai 2026.³⁵ Selon Anthropic : « Dreaming est un processus planifié qui examine vos sessions d’agent et vos espaces de stockage de mémoire, en extrait des modèles et organise les mémoires afin que vos agents s’améliorent au fil du temps. »³⁵

Dreaming s’exécute en arrière-plan entre les sessions, et non sur le chemin critique. Il complète plutôt qu’il ne remplace le modèle du système de fichiers comme mémoire : votre fichier MEMORY.md reste la surface porteuse ; Dreaming écrit des entrées de mémoire sélectionnées dans l’espace mémoire des Managed Agents, que l’agent lit au début de la session. Les deux modèles coexistent pour les harnesses qui associent un état de système de fichiers auto-hébergé à une curation côté service géré.

Dreaming est en Research Preview, son comportement peut donc évoluer. Les modèles de handoffs de session et de CLAUDE.md documentés ci-dessus restent le mécanisme de mémoire de référence pour les harnesses auto-hébergés.

Les anti-modèles

Lire des fichiers entiers lorsque vous avez besoin de 10 lignes. La lecture d’un seul fichier de 2 000 lignes consomme 15 000 à 20 000 tokens. Utilisez des décalages de lignes : Read file.py offset=100 limit=20 économise la grande majorité de ce coût.¹⁵

Conserver une sortie d’erreur détaillée dans le contexte. Après le débogage d’un bug, votre contexte contient plus de 40 traces de pile provenant d’itérations échouées. Un seul /compact après la correction du bug libère ce poids mort.

Commencer chaque session en lisant chaque fichier. Laissez les outils glob et grep de Claude Code trouver les fichiers pertinents à la demande, ce qui évite plus de 100 000 tokens de préchargement inutile.¹⁵

Modèles de subagents

Les subagents sont des instances spécialisées de Claude qui prennent en charge des tâches complexes de manière autonome. La plupart démarrent avec un contexte vierge (sans pollution issue de la conversation principale) — à l’exception du type fork ci-dessous, qui hérite délibérément de l’intégralité du contexte —, utilisent les outils spécifiés et renvoient leurs résultats sous forme de synthèses. Les résultats de l’exploration n’alourdissent pas votre conversation principale ; seules les conclusions y sont renvoyées.⁵

Types de subagents intégrés

Création de subagents personnalisés

Définissez les subagents dans .claude/agents/ (projet) ou ~/.claude/agents/ (personnel) :

---
name: security-reviewer
description: Expert security code reviewer. Use PROACTIVELY after any code
  changes to authentication, authorization, or data handling.
tools: Read, Grep, Glob, Bash
model: opus
permissionMode: plan
---

You are a senior security engineer reviewing code for vulnerabilities.

When invoked:
1. Identify the files that were recently changed
2. Analyze for OWASP Top 10 vulnerabilities
3. Check for secrets, hardcoded credentials, SQL injection
4. Report findings with severity levels and remediation steps

Focus on actionable security findings, not style issues.

Champs de configuration des subagents

Isolation par worktree

Les subagents peuvent travailler dans des git worktrees temporaires, qui leur fournissent une copie complète et isolée du dépôt :⁵

---
name: experimental-refactor
description: Attempt risky refactoring in isolation
isolation: worktree
tools: Read, Write, Edit, Bash, Grep, Glob
---

You have an isolated copy of the repository. Make changes freely.
If the refactoring succeeds, the changes can be merged back.
If it fails, the worktree is discarded with no impact on the main branch.

L’isolation par worktree est essentielle pour les travaux expérimentaux susceptibles de casser la base de code.

L’isolation n’en est réellement une que si elle tient. La v2.1.210 de Claude Code a corrigé un bug qui permettait aux subagents isolés dans un worktree de modifier le checkout principal — précisément la défaillance que ce mécanisme est censé empêcher.⁶⁹ Si vous utilisez isolation: worktree comme frontière de sécurité plutôt que comme simple commodité, considérez la v2.1.210 comme la version minimale. La modification associée des autorisations va dans l’autre sens : depuis la v2.1.211, les règles « always allow » persistent à la racine du dépôt dans tous les worktrees ; une règle acceptée dans l’un d’eux s’applique donc aux worktrees frères du même dépôt.⁶⁹ Cette ergonomie convient aux agents travaillant en parallèle dans des worktrees, mais elle signifie qu’une autorisation accordée pendant une expérience jetable survit à celle-ci — accordez-la en pensant à l’ensemble du dépôt, pas seulement au worktree qui se trouve devant vous.

La v2.1.216 a achevé le travail, faisant passer l’isolation par worktree du stade de correction de bug à celui de mécanisme robuste.⁷⁴ Le correctif de la v2.1.210 empêchait les subagents de worktree de modifier le checkout principal au moyen d’une invocation git ordinaire, mais git permet lui-même une redirection explicite — git -C <path>, --git-dir et les variables d’environnement GIT_DIR/GIT_WORK_TREE —, et un subagent isolé dans un worktree pouvait encore les pointer vers le checkout partagé. Toutes ces échappatoires sont désormais fermées. La même version a corrigé les sessions de worktree qui aboutissaient parfois dans le worktree résiduel d’un autre projet, empêché les écritures de workflows et de tâches planifiées de suivre un lien symbolique placé dans .claude vers une cible extérieure au projet, et fait en sorte que /rewind refuse de traverser les liens symboliques et les liens physiques. Ces quatre correctifs suivent le même principe : une frontière d’isolation doit résister aux redirections délibérées — remplacement des variables d’environnement de git, implantation de liens symboliques —, pas seulement au comportement par défaut. Si isolation: worktree constitue une frontière de sécurité dans votre harness plutôt qu’une commodité, la v2.1.216 est la nouvelle version minimale.

Subagents parallèles

Utilisez des subagents parallèles pour les tâches de recherche indépendantes qui n’ont pas besoin de se coordonner entre elles :⁵

> Have three explore agents search in parallel:
> 1. Authentication code
> 2. Database models
> 3. API routes

Chaque agent s’exécute dans sa propre fenêtre de contexte, trouve le code pertinent et renvoie une synthèse. Le contexte principal reste propre.

Le garde-fou contre la récursion

Sans limites de lancement, les agents délèguent à des agents qui délèguent à leur tour à d’autres agents, chacun perdant du contexte et consommant des tokens. Le modèle de garde-fou contre la récursion impose des budgets :¹⁶

#!/bin/bash
# recursion-guard.sh — enforce spawn budget
CONFIG_FILE="${HOME}/.claude/configs/recursion-limits.json"
STATE_FILE="${HOME}/.claude/state/recursion-depth.json"

MAX_DEPTH=2
MAX_CHILDREN=5
DELIB_SPAWN_BUDGET=2
DELIB_MAX_AGENTS=12

# Read current depth
current_depth=$(jq -r '.depth // 0' "$STATE_FILE" 2>/dev/null)

if [[ "$current_depth" -ge "$MAX_DEPTH" ]]; then
    echo "BLOCKED: Maximum recursion depth ($MAX_DEPTH) reached" >&2
    exit 2
fi

# Increment depth using safe arithmetic (not ((VAR++)) with set -e)
new_depth=$((current_depth + 1))
jq --argjson d "$new_depth" '.depth = $d' "$STATE_FILE" > "${STATE_FILE}.tmp"
mv "${STATE_FILE}.tmp" "$STATE_FILE"

Leçon essentielle : utilisez des budgets de lancement, pas seulement des limites de profondeur. Les limites fondées sur la profondeur suivent les chaînes parent-enfant (bloquées à une profondeur de 3), mais ignorent la largeur : 23 agents à une profondeur de 1 restent à une « profondeur de 1 ». Un budget de lancement comptabilise le nombre total d’enfants actifs par parent, avec un maximum configurable. Le modèle budgétaire correspond au mode de défaillance réel (trop d’agents au total), plutôt qu’à une mesure indirecte (trop de niveaux d’imbrication).⁷

La profondeur d’imbrication par défaut a changé trois fois ; ne bâtissez rien dessus. La v2.1.172 de Claude Code (10 juin 2026) a permis aux subagents de lancer leurs propres subagents, avec une imbrication pouvant atteindre 5 niveaux — alors que la délégation était auparavant limitée, dans les faits, à un seul niveau.⁶² Ce comportement a perduré de la v2.1.172 à la v2.1.216. La v2.1.217 (21 juillet 2026) a ramené cette profondeur à 1, désactivant par défaut les lancements imbriqués. Puis la v2.1.219 (24 juillet 2026) a choisi un compromis : « Subagents can now spawn nested subagents up to depth 3 by default (was 1); set CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1 to disable nesting. »⁸⁴ Cinq, puis un, puis trois — les deux derniers changements en l’espace de trois jours.

Il ne faut pas en conclure que l’un de ces nombres est le bon. Cela montre plutôt que la plateforme cherche encore le réglage par défaut adéquat, ce qui fait de « ce qui est livré » un mauvais comportement à laisser votre harness hériter. Considérez la profondeur d’imbrication comme une ligne budgétaire explicite : définissez CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH sur la profondeur réellement nécessaire à votre architecture — 1 ou 2 dans la plupart des orchestrations — afin qu’une mise à niveau ne puisse pas modifier discrètement la profondeur de délégation de votre parc. Malgré tous ces changements, l’argument de fond reste le même : les chaînes d’agents déléguant à d’autres agents consomment contexte et tokens plus vite qu’elles ne produisent de résultats, et la profondeur est un risque à budgéter, pas une capacité à rechercher. Le garde-fou contre la récursion ci-dessus empêche un arbre profond de se déployer en centaines d’agents actifs, quelle que soit la prochaine évolution de la valeur par défaut ; seule une limite que vous définissez vous-même conservera le sens que vous lui donnez après la prochaine version.

Le mode automatique évalue désormais les lancements avant leur exécution. La v2.1.178 de Claude Code a comblé la lacune correspondante en matière de gouvernance : en mode automatique, les lancements de subagents sont évalués par le classificateur d’autorisations avant le démarrage du subagent, et non plus seulement lorsqu’il commence à agir.⁶³ Auparavant, un subagent pouvait être lancé pour demander une action que la session parente n’aurait pas été autorisée à effectuer — le lancement lui-même constituait le contournement. L’évaluation au moment du lancement fait enfin converger le garde-fou contre la récursion et le modèle d’autorisations : un enfant ne peut plus servir d’intermédiaire pour blanchir une action interdite par la politique.

La plateforme fournit désormais un budget de lancement natif. La v2.1.212 de Claude Code (juillet 2026) a ajouté des garde-fous natifs contre les boucles incontrôlées : les sessions sont limitées par défaut à 200 lancements de subagents (CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION pour ajuster cette valeur, /clear pour réinitialiser le compteur), et WebSearch est limité à 200 appels par session (CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION).⁶⁹ Le modèle de budget de lancement que cette section documentait sous forme de script utilisateur depuis la v1.0 est désormais fourni par la plateforme — ce qui valide le modèle budgétaire au détriment du modèle fondé sur la profondeur. Notez toutefois le calibrage : 200 lancements représentent un ordre de grandeur supérieur au budget de 12 agents de la configuration ci-dessus. Les plafonds natifs sont des fusibles contre une boucle réellement incontrôlée, pas des budgets adaptés à votre architecture. Conservez le garde-fou utilisateur pour les budgets par parent, le suivi de la profondeur et les limites correspondant au fonctionnement attendu de votre orchestration ; laissez le plafond de la plateforme intercepter ce qui lui échapperait.

Les garde-fous natifs couvrent désormais quatre axes. Trois d’entre eux renforcent précisément ce que suit le garde-fou utilisateur de cette section : le nombre total de lancements par session (v2.1.212, plafond de 200, CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION), la profondeur d’imbrication (CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH, actuellement fixée par défaut à 3 et manifestement instable) et l’exécution simultanée (v2.1.217, valeur par défaut de 20, CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS — un seul message ne peut plus déployer sans limite des agents en arrière-plan).⁷⁸⁸⁴ La v2.1.219 en ajoute un quatrième, généralement absent des garde-fous utilisateur : la largeur de l’orchestration, c’est-à-dire le nombre d’agents qu’un workflow planifié est autorisé à contenir, livrée sous la forme d’une recommandation par défaut visant « moins de 15 agents » et configurable dans n’importe quel fichier de paramètres avec workflowSizeGuideline (voir la section Workflow Tool ci-dessous). Le modèle de budget de lancement bénéficie désormais d’un garde-fou sur chacun des axes pour lesquels il a été conçu, plus un autre qui ne l’était pas.

La remarque sur le calibrage reste valable, mais de manière inégale. Les plafonds de 200 lancements et de 20 agents simultanés sont des fusibles — un ordre de grandeur au-dessus du budget de délibération de 12 agents dans la configuration ci-dessus, dimensionnés pour détecter une boucle incontrôlée plutôt que pour façonner une architecture. La recommandation sur la largeur est la première valeur native du même ordre qu’un véritable budget : 15 agents par workflow se situent juste à côté des 12 de ce guide, suffisamment près pour que l’adoption de la valeur par défaut de la plateforme ne vous coûte rien et que tout désaccord exige une véritable justification. Définissez les trois fusibles sur des valeurs que vous pouvez défendre ; adaptez la recommandation de largeur à la forme de l’orchestration que vous vouliez construire.

Agent Teams (aperçu de recherche)

Les Agent Teams coordonnent plusieurs instances de Claude Code qui travaillent de manière indépendante, communiquent au moyen d’une boîte aux lettres et d’une liste de tâches partagées, et peuvent remettre en question les conclusions des autres :⁵

Activez avec : export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Quand utiliser les Agent Teams plutôt que les subagents :

Agent View et boucles d’objectifs (mai 2026)

La v2.1.139 de Claude Code a ajouté Agent View, une interface en aperçu de recherche lancée avec claude agents, qui affiche sur un seul écran les sessions Claude Code en cours, bloquées et terminées.⁴²⁴³ La documentation officielle la présente comme un moyen de répartir et de gérer de nombreuses sessions, de voir ce que chacune accomplit et de repérer celles qui nécessitent l’intervention de l’opérateur.⁴³ Le travail multi-agent bénéficie ainsi d’une vue opérationnelle que les synthèses finales ne peuvent pas fournir.

Utilisez Agent View lorsque vous faites évoluer un modèle de subagent ou d’équipe : examinez les sessions bloquées, celles qui sont encore en cours et vérifiez si la répartition du travail correspond à l’architecture prévue. Ne considérez pas cette vue comme une preuve de qualité. Elle assure l’observabilité ; les tests, les portes de validation et les rapports de preuves déterminent toujours si le travail est fiable.

La même version a ajouté /goal, qui définit une condition d’achèvement et permet à Claude de poursuivre son travail sur plusieurs tours jusqu’à ce que cette condition soit remplie, y compris en mode interactif, avec -p et via Remote Control.⁴² Considérez /goal comme une boucle d’achèvement limitée à la session, et non comme un substitut aux portes déterministes. Cette commande aide l’agent à rester concentré sur un objectif, mais les tests, les vérifications de citations et de déploiement ainsi que les hooks de sécurité doivent rester adossés à des commandes ou des scripts lorsque leur échec doit être bloquant.

Workflow Tool (v2.1.147+)

Les workflows dynamiques de Claude Code constituent une interface livrée et disponible par défaut : depuis la v2.1.154, ils orchestrent des dizaines à des centaines d’agents en arrière-plan, surveillés au moyen de /workflows, avec un réglage « Dynamic workflow size » dans /config (v2.1.202) et une clé de paramètres workflowSizeGuideline dont la recommandation par défaut est moyenne — visez moins de 15 agents sauf instruction contraire (v2.1.219). Cette interface avait fait ses débuts une version plus tôt sous la forme du Workflow tool de la v2.1.147, désactivé par défaut derrière CLAUDE_CODE_WORKFLOWS=1 ; l’époque de ce flag appartient désormais au passé, mais le principe architectural qu’il révélait demeure.⁵² Il fournit à Claude Code une primitive d’orchestration native pour des flux qui nécessitaient auparavant des scripts de répartition personnalisés, un état de boîte aux lettres et des conventions de coordination entre subagents.

Ne supprimez pas le harness qui l’entoure. Un Workflow peut structurer l’exécution, mais il ne remplace pas votre modèle de sécurité. Conservez les hooks PreToolUse et PostToolUse comme couche de blocage, les budgets de lancement ou de nombre d’étapes du workflow pour éviter une largeur incontrôlée, un état du système de fichiers vérifiable et les rapports de preuves finaux en dehors de l’auto-évaluation du modèle. En pratique : utilisez Workflow pour structurer l’orchestration ; utilisez les hooks, les tests et les portes de revue pour établir la vérité.

Les workflows dynamiques proposent désormais une recommandation sur la largeur (v2.1.219). Par défaut, les workflows dynamiques utilisent une recommandation de taille moyenne — « visez moins de 15 agents » —, avec d’autres tailles et une option sans restriction accessibles sous Dynamic workflow size dans /config ; la recommandation actuelle apparaît également dans la ligne d’état du workflow en cours.⁸⁴ Cette valeur est indicative, non contraignante : elle oriente le planificateur sans bloquer un plan large. Son mécanisme de diffusion justifie sa configuration : la nouvelle clé de paramètres workflowSizeGuideline peut être définie dans n’importe quel fichier de paramètres — notamment dans les paramètres gérés et ceux du projet, et elle figure dans les types de paramètres du TypeScript SDK depuis la v0.3.219 —, ce qui permet à une équipe ou à une organisation de normaliser la largeur de l’orchestration au lieu de laisser chaque opérateur la redécouvrir.⁸⁵ Définissez-la au niveau du projet afin de refléter la manière dont le travail se décompose réellement dans votre base de code. Deux remarques pour les opérateurs : la ligne correspondante de /config disparaît lorsqu’un fichier de paramètres impose cette valeur, ce qui est le comportement correct mais peut donner l’impression qu’un paramètre manque si vous n’en connaissez pas la raison ; et puisque la recommandation oriente le planificateur sans bloquer l’exécution, elle relève de la forme, pas de la sécurité. Le plafond de lancements reste chargé d’endiguer une largeur incontrôlée.

L’idée à retenir est qu’il s’agit d’un quatrième axe de garde-fou natif — la largeur de l’orchestration, aux côtés du nombre de lancements, de la profondeur d’imbrication et de l’exécution simultanée — et du premier que Anthropic ait calibré à une échelle de travail plausible plutôt que comme un fusible contre les dérives. Quinze agents par workflow appartiennent au même ordre de grandeur que le budget de délibération de 12 agents utilisé par ce guide depuis la v1.0. Lorsque la valeur par défaut de la plateforme et votre propre budget convergent depuis des directions opposées, cela se rapproche autant que possible d’une corroboration indépendante pour ce type de nombre.

Fork de session et MCP automatiquement placés en arrière-plan (juillet 2026)

La v2.1.212 de Claude Code a remodelé deux primitives d’orchestration.⁶⁹ /fork crée désormais une nouvelle session en arrière-plan à partir de l’état actuel de la conversation — la branche issue du fork s’exécute indépendamment tandis que la session d’origine continue de travailler —, et l’ancien comportement au sein de la session a été renommé /subtask. Cette distinction compte dans la conception de l’orchestration : /subtask est un détour circonscrit dans le cycle de vie d’une session ; /fork est un moyen peu coûteux de créer une session parallèle en arrière-plan qui hérite de tout le contexte, plus proche d’un lancement de boucle Ralph que d’un subagent. Si vos scripts de harness supposaient que /fork restait dans la session, ils répartissent désormais le travail en arrière-plan.

La même version place automatiquement en arrière-plan les appels MCP lents : tout appel d’outil MCP dépassant deux minutes est automatiquement transféré vers une exécution en arrière-plan (ajustez ce seuil avec CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS).⁶⁹ Un serveur MCP lent ne bloque donc plus la boucle agentique — mais cela signifie aussi que « l’outil a renvoyé son résultat » et « le tour s’est poursuivi » ne correspondent plus au même événement ; les hooks ou scripts qui supposaient l’exécution synchrone de MCP doivent donc se déclencher sur le résultat de l’outil, et non sur la limite du tour.

Pour l’orchestration headless, la v2.1.211 a ajouté --forward-subagent-text (variable d’environnement : CLAUDE_CODE_FORWARD_SUBAGENT_TEXT), qui transmet le texte produit par l’assistant du subagent dans la sortie stream-json.⁶⁹ Un processus coordinateur qui consomme le flux du parent peut désormais observer directement la progression des subagents au lieu d’interroger leurs transcriptions ou d’attendre la synthèse finale — le complément d’observabilité des subagents exécutés par défaut en arrière-plan. La v2.1.219 a étendu ce mécanisme au-delà du premier niveau : les subagents lancés à une profondeur de 2 ou plus apparaissent désormais eux aussi dans le flux transmis, associés à l’identifiant tool_use de l’Agent qui les a lancés.⁸⁴ C’est sur cet identifiant qu’il faut vous appuyer. L’imbrication étant de nouveau activée par défaut, un flux linéaire de textes de subagents est ambigu — l’identifiant indique au coordinateur quel parent a produit quel enfant, de sorte que l’arbre de délégation peut être reconstruit à partir du flux au lieu d’être déduit. Si votre consommateur de flux a été conçu pour un seul niveau de subagents, il verra désormais le texte d’agents dont il ignorait l’existence ; regroupez les éléments selon l’identifiant tool_use de l’agent qui les a lancés au lieu de supposer que chaque ligne transmise appartient à un enfant direct.

Orchestration multi-agent

Les systèmes d’IA à agent unique présentent un angle mort structurel : ils ne peuvent pas remettre en question leurs propres hypothèses.⁷ La délibération multi-agent impose une évaluation indépendante selon plusieurs perspectives avant qu’une décision ne soit arrêtée.

Orchestration inter-outils (avril 2026) : Google a publié Scion en open source le 7 avril — un hyperviseur multi-agent qui exécute Claude Code, Gemini CLI et d’autres « deep agents » comme processus concurrents, chacun disposant de son conteneur isolé, de son git worktree et de ses identifiants. Fonctionne en local, avec hub ou sur Kubernetes. Philosophie explicite : « l’isolation plutôt que les contraintes » — les agents opèrent avec une grande autonomie à l’intérieur de limites appliquées au niveau de l’infrastructure, et non dans le prompt.²⁵ Cela étend directement l’argument en faveur de l’isolation des subagents à travers différents fournisseurs d’outils. Si votre workflow couvre Claude et des modèles OpenAI, Scion constitue la première véritable implémentation de référence de subagents inter-outils avec isolation par agent du worktree et des identifiants.

Le débat n’est pas une solution miracle : le cluster de recherche M3MAD-Bench (début 2026) a constaté que le débat multi-agent atteint un plateau et peut être détourné par un consensus trompeur — des arguments valides l’emportent difficilement lorsque d’autres agents affirment avec assurance la mauvaise réponse.²⁶ Tool-MAD améliore cela en donnant à chaque agent un accès hétérogène aux outils et en utilisant des scores de Fidélité/Pertinence à l’étape de jugement. Si vous construisez une orchestration de type débat, investissez dans (a) l’hétérogénéité des outils par agent et (b) une notation quantitative du juge plutôt que de supposer que davantage d’agents = de meilleures réponses.

Orchestration multi-agent gérée et Outcomes (bêta publique)

Si vous ne souhaitez pas construire l’infrastructure de délibération décrite ci-dessous, Multiagent Orchestration est entré en bêta publique dans Claude Managed Agents le 6 mai 2026.³⁵ Selon Anthropic : « Lorsqu’il y a trop de travail pour qu’un seul agent puisse bien le réaliser, l’orchestration multi-agent permet à un agent principal de découper le travail et de déléguer chaque partie à un spécialiste disposant de son propre modèle, prompt et outils. »³⁵ Les spécialistes « travaillent en parallèle sur un système de fichiers partagé et contribuent au contexte global de l’agent principal ». ³⁵

La traçabilité est incluse. Selon Anthropic : « vous pouvez également suivre chaque étape dans la Claude Console : quel agent a fait quoi, dans quel ordre et pourquoi, ce qui vous donne une visibilité complète sur la manière dont votre tâche a été déléguée et exécutée. »³⁵

La fonctionnalité complémentaire en bêta publique est Outcomes. Selon Anthropic : « vous rédigez une grille d’évaluation décrivant à quoi ressemble la réussite, et l’agent s’y emploie. Un évaluateur distinct examine le résultat selon vos critères dans sa propre fenêtre de contexte, afin de ne pas être influencé par le raisonnement de l’agent. »³⁵ Il s’agit de la version de service géré du modèle de validation à deux portes documenté plus loin dans cette section : la grille remplace la porte écrite manuellement, l’évaluateur distinct remplace le validateur de consensus.

La délibération auto-hébergée reste la bonne réponse lorsque la validation doit s’intégrer à votre propre surface de hooks (blocage PreToolUse, sémantique des codes de sortie, dispatchers personnalisés), ou lorsque le harness doit fonctionner sans dépendances externes. Multiagent géré est la bonne réponse lorsque la délégation standard assortie d’une évaluation par grille est le contrat dont vous avez réellement besoin.

Délibération minimale viable

Commencez avec 2 agents et 1 règle : les agents doivent évaluer indépendamment avant de voir le travail des autres.⁷

Decision arrives
  |
  v
Confidence check: is this risky, ambiguous, or irreversible?
  |
  +-- NO  -> Single agent decides (normal flow)
  |
  +-- YES -> Spawn 2 agents with different system prompts
             Agent A: "Argue FOR this approach"
             Agent B: "Argue AGAINST this approach"
             |
             v
             Compare findings
             |
             +-- Agreement with different reasoning -> Proceed
             +-- Genuine disagreement -> Investigate the conflict
             +-- Agreement with same reasoning -> Suspect herding

Ce pattern couvre 80 % de la valeur. Tout le reste apporte une amélioration progressive.

Le déclencheur de confiance

Chaque tâche ne nécessite pas de délibération. Un module de notation de confiance évalue quatre dimensions :¹⁷

1. Ambiguïté - La requête admet-elle plusieurs interprétations valides ?
2. Complexité du domaine - Exige-t-elle des connaissances spécialisées ?
3. Enjeux - La décision est-elle réversible ?
4. Dépendance au contexte - Exige-t-elle de comprendre le système dans son ensemble ?

Le score correspond à trois niveaux :

Le seuil s’adapte au type de tâche. Les décisions de sécurité exigent un consensus de 0,85. Les modifications de documentation ne nécessitent que 0,50. Cela évite de sur-ingénier les tâches simples tout en garantissant que les décisions risquées soient examinées avec attention.⁷

La machine à états

Sept phases, chacune conditionnée par la précédente :⁷

IDLE -> RESEARCH -> DELIBERATION -> RANKING -> PRD_GENERATION -> COMPLETE
                                                                    |
                                                              (or FAILED)

RESEARCH : Des agents indépendants étudient le sujet. Chaque agent reçoit un persona distinct (architecte technique, analyste sécurité, ingénieur performance, entre autres). L’isolation du contexte garantit que les agents ne peuvent pas voir les résultats des autres pendant la recherche.

DELIBERATION : Les agents voient tous les résultats de recherche et génèrent des alternatives. L’agent Debate identifie les conflits. L’agent Synthesis combine les résultats non contradictoires.

RANKING : Chaque agent note chaque approche proposée selon 5 dimensions pondérées :

L’architecture de validation à deux portes

Deux portes de validation détectent les problèmes à des étapes différentes :⁷

Porte 1 : validation du consensus (hook PostToolUse). S’exécute immédiatement après la fin de chaque agent de délibération : 1. La phase doit avoir atteint au moins RANKING 2. Au moins 2 agents ont terminé (configurable) 3. Le score de consensus atteint le seuil adapté à la tâche 4. Si un agent a exprimé un désaccord, les préoccupations doivent être documentées

Porte 2 : Pride Check (hook Stop). S’exécute avant que la session puisse se fermer : 1. Méthodes diversifiées : plusieurs personas uniques sont représentés 2. Transparence des contradictions : les désaccords comportent des raisons documentées 3. Gestion de la complexité : au moins 2 alternatives ont été générées 4. Confiance du consensus : classée comme forte (au-dessus de 0,85) ou modérée (0,70-0,84) 5. Preuve d’amélioration : la confiance finale dépasse la confiance initiale

Deux hooks à différents moments du cycle de vie correspondent à la manière dont les échecs surviennent réellement : certains sont instantanés (mauvais score), d’autres progressifs (faible diversité, absence de documentation des désaccords).⁷

Pourquoi l’accord est dangereux

Charlan Nemeth a étudié le désaccord minoritaire de 1986 jusqu’à son livre de 2018 In Defense of Troublemakers. Les groupes comportant des contradicteurs prennent de meilleures décisions que ceux qui parviennent rapidement à un accord. Le contradicteur n’a pas besoin d’avoir raison. Le fait même du désaccord force la majorité à examiner des hypothèses qu’elle aurait autrement ignorées.¹⁸

Wu et al. ont cherché à savoir si les agents LLM peuvent réellement débattre et ont constaté que, sans incitations structurelles au désaccord, les agents convergent vers la réponse initiale qui semble la plus assurée, quelle que soit son exactitude.¹⁹ Liang et al. ont identifié la cause première comme une « Degeneration-of-Thought » : lorsqu’un LLM établit sa confiance dans une position, l’autoréflexion ne peut pas générer de nouveaux contre-arguments, ce qui rend l’évaluation multi-agent structurellement nécessaire.²⁰

L’indépendance est la contrainte de conception essentielle. Deux agents évaluant la même stratégie de déploiement tout en voyant les résultats de l’autre ont produit des scores de 0,45 et 0,48. Les mêmes agents sans visibilité : 0,45 et 0,72. L’écart entre 0,48 et 0,72 représente le coût du comportement grégaire.⁷

Détecter les faux accords

Un module de détection du conformisme suit les patterns suggérant que les agents s’accordent sans véritable évaluation :⁷

Regroupement des scores : Chaque agent attribuant un score dans un intervalle de 0,3 point sur une échelle de 10 signale une contamination du contexte partagé plutôt qu’une évaluation indépendante. Lorsque cinq agents évaluant une refactorisation de l’authentification ont tous estimé le risque de sécurité entre 7,1 et 7,4, une nouvelle exécution avec une isolation fraîche du contexte a réparti les scores de 5,8 à 8,9.

Désaccord passe-partout : Des agents copient le langage des préoccupations des autres plutôt que de générer des objections indépendantes.

Absence de perspectives minoritaires : Approbation unanime de personas aux priorités contradictoires (un analyste sécurité et un ingénieur performance sont rarement d’accord sur tout).

Le détecteur de conformisme identifie les cas évidents (environ 10-15 % des délibérations où les agents convergent trop vite). Pour les 85-90 % restants, les portes de consensus et de pride check fournissent une validation suffisante.

Ce qui n’a pas fonctionné dans la délibération

Des tours de débat libres. Trois tours d’échanges textuels pour une discussion sur l’indexation d’une base de données ont produit 7 500 tokens de débat. Tour 1 : véritable désaccord. Tour 2 : positions reformulées. Tour 3 : arguments identiques avec des mots différents. La notation structurée par dimension a remplacé le débat libre, réduisant le coût de 60 % tout en améliorant la qualité du classement.⁷

Une seule porte de validation. La première implémentation exécutait un hook de validation à la fin de la session. Un agent a terminé une délibération avec un score de consensus de 0,52 (inférieur au seuil), puis a continué sur des tâches sans rapport pendant 20 minutes avant que le hook de fin de session ne signale l’échec. La division en deux portes (l’une à la fin de la tâche, l’autre à la fin de la session) a détecté les mêmes problèmes à différents moments du cycle de vie.⁷

Coût de la délibération

Chaque agent de recherche traite environ 5 000 tokens de contexte et génère 2 000-3 000 tokens de résultats. Avec 3 agents, cela représente 15 000-24 000 tokens supplémentaires par décision. Avec 10 agents, environ 50 000-80 000 tokens.⁷

Aux tarifs actuels d’Opus 5 (5 $/25 $ par MTok), une délibération à 3 agents coûte environ 0,23-0,30 $. Une délibération à 10 agents coûte 0,75-1,00 $. Le système déclenche une délibération pour environ 10 % des décisions, de sorte que le coût amorti sur l’ensemble des décisions est de 0,08-0,10 $ par session. (Les éditions précédentes indiquaient des chiffres trois fois supérieurs, calculés selon l’ancien tarif d’Opus 4.x de 15 $/75 $.) La pertinence de ce coût dépend de celui d’une mauvaise décision.

Quand délibérer

Conception de CLAUDE.md

CLAUDE.md constitue une politique opérationnelle pour un agent d’IA, et non un README destiné aux humains.²¹ L’agent n’a pas besoin de comprendre pourquoi vous utilisez des commits conventionnels. Il doit connaître la commande exacte à exécuter et savoir précisément à quoi ressemble un travail « terminé ».

Hiérarchie de préséance

Les fichiers de règles se chargent automatiquement et fournissent un contexte structuré sans encombrer CLAUDE.md.⁶

Ce qui est ignoré

Ces formulations n’entraînent systématiquement aucun changement observable dans le comportement de l’agent :²¹

Paragraphes explicatifs sans commandes. « Nous accordons de l’importance à un code propre et bien testé » relève de la documentation, pas des opérations. L’agent le lit, puis écrit du code sans tests, car aucune instruction exploitable ne lui a été donnée.

Directives ambiguës. « Soyez prudent avec les migrations de base de données » n’est pas une contrainte. « Exécutez alembic check avant d’appliquer les migrations. Abandonnez si le chemin de rétrogradation est absent. » en est une.

Priorités contradictoires. « Avancez vite et livrez rapidement », « Assurez une couverture de tests complète », « Maintenez la durée d’exécution sous 5 minutes » et « Exécutez tous les tests d’intégration avant chaque commit. » L’agent ne peut pas satisfaire simultanément ces quatre exigences et finit par ignorer la vérification.²¹

Guides de style sans mécanisme de contrôle. « Suivez le guide de style Google pour Python » sans ruff check --select D ne fournit à l’agent aucun moyen de vérifier sa conformité.

Ce qui fonctionne

Instructions commençant par les commandes :

## Build and Test Commands
- Install: `pip install -r requirements.txt`
- Lint: `ruff check . --fix`
- Format: `ruff format .`
- Test: `pytest -v --tb=short`
- Type check: `mypy app/ --strict`
- Full verify: `ruff check . && ruff format --check . && pytest -v`

Définitions des critères de clôture :

## Definition of Done
A task is complete when ALL of the following pass:
1. `ruff check .` exits 0
2. `pytest -v` exits 0 with no failures
3. `mypy app/ --strict` exits 0
4. Changed files have been staged and committed
5. Commit message follows conventional format: `type(scope): description`

Sections organisées par tâche :

## When Writing Code
- Run `ruff check .` after every file change
- Add type hints to all new functions

## When Reviewing Code
- Check for security issues: `bandit -r app/`
- Verify test coverage: `pytest --cov=app --cov-fail-under=80`

## When Releasing
- Update version in `pyproject.toml`
- Run full suite: `pytest -v && ruff check . && mypy app/`

Règles d’escalade :

## When Blocked
- If tests fail after 3 attempts: stop and report the failing test with full output
- If a dependency is missing: check `requirements.txt` first, then ask
- Never: delete files to resolve errors, force push, or skip tests

Ordre de rédaction

Si vous partez de zéro, ajoutez les sections dans l’ordre de priorité suivant :²¹

1. Commandes de compilation et de test (l’agent en a besoin avant de pouvoir faire quoi que ce soit d’utile)
2. Définition du travail terminé (évite les faux achèvements)
3. Règles d’escalade (empêche les solutions de contournement destructrices)
4. Sections organisées par tâche (réduit l’analyse d’instructions non pertinentes)
5. Délimitation par répertoire (monorepos : maintient les instructions de chaque service isolées)

Ignorez les préférences de style tant que les quatre premières catégories ne fonctionnent pas.

La plateforme audite désormais votre CLAUDE.md à votre place. Depuis les versions du début juillet 2026 (v2.1.203–v2.1.206), /doctor analyse CLAUDE.md et propose de supprimer le contenu que le modèle peut déduire lui-même du codebase : arborescences de répertoires reformulées, conventions de framework déjà visibles dans le code et listes de commandes qui dupliquent les scripts des packages.⁶⁸ Cela confirme directement la thèse de cette section : les instructions méritent les tokens qu’elles consomment lorsqu’elles encodent ce que l’agent ne peut pas déduire (politiques, seuils, définitions des critères de clôture), et non ce qu’il peut lire sur le disque. Exécutez /doctor après tout enrichissement conséquent de CLAUDE.md et considérez ses propositions d’élagage comme un point de départ — conservez toutefois les règles opérationnelles qu’il pourrait qualifier de « déductibles » lorsqu’elles constituent des contraintes essentielles plutôt que de simples descriptions.

Importation de fichiers

Référencez d’autres fichiers dans CLAUDE.md :

See @README.md for project overview
Coding standards: @docs/STYLE_GUIDE.md
API documentation: @docs/API.md
Personal preferences: @~/.claude/preferences.md

Syntaxe d’importation : chemin relatif (@docs/file.md), absolu (@/absolute/path.md) ou depuis le répertoire personnel (@~/.claude/file.md). Profondeur maximale : 5 niveaux d’importation.⁶

Compatibilité des instructions entre les outils

AGENTS.md est une norme ouverte reconnue par tous les principaux outils de programmation assistée par IA.²¹ Si votre équipe utilise plusieurs outils, faites d’AGENTS.md la source canonique et reproduisez les sections pertinentes dans les fichiers propres à chaque outil :

Les modèles employés dans AGENTS.md (commandes en premier, critères de clôture définis, organisation par tâche) fonctionnent dans n’importe quel fichier d’instructions, quel que soit l’outil. N’entretenez pas plusieurs jeux d’instructions parallèles susceptibles de diverger. Rédigez une source faisant autorité et reproduisez-la.

Notes sur la parité avec Codex

Codex dispose désormais d’équivalents natifs pour les principales couches du harness, mais la migration consiste à transposer des modèles, pas à copier des fichiers. Codex lit AGENTS.md avant de commencer le travail, en superposant les directives globales de ~/.codex, celles du projet et celles des répertoires imbriqués du dépôt.³¹ Les skills Codex reposent sur le même modèle mental SKILL.md, avec divulgation progressive : Codex commence par le nom, la description et le chemin du fichier de la skill, puis charge l’intégralité de celle-ci uniquement lorsqu’il décide de l’utiliser.³² Codex propose également des hooks natifs, des hooks intégrés à des plugins, des hooks gérés, la prise en charge de MCP et des workflows explicites pour les subagents.³³³⁴

Codex v0.138.0–v0.139.0 a renforcé cette découverte d’AGENTS.md dans les espaces de travail complexes : le chargement passe désormais par l’abstraction du système de fichiers de l’environnement et conserve les chemins logiques pendant le parcours de découverte, afin de sélectionner le bon fichier même si l’espace de travail repose sur un système de fichiers distant ou une arborescence de liens symboliques.⁶¹ Cela compte chaque fois que votre fichier canonique AGENTS.md fait autorité et que l’agent travaille sur un checkout monté, matérialisé dans un conteneur ou relié par des liens symboliques — autant de situations où un parcours naïf des chemins sélectionne silencieusement le mauvais fichier d’instructions, voire aucun. Si vous reproduisez un unique fichier AGENTS.md faisant autorité dans plusieurs services, considérez cette version comme le minimum requis pour avoir confiance dans le fait que le fichier réellement chargé par l’agent est bien celui que vous avez écrit.

Codex v0.141.0 a ensuite renforcé le chemin d’exécution distante lui-même : les exécuteurs distants se connectent désormais au moyen de canaux de relais Noise authentifiés et chiffrés de bout en bout (le plan de contrôle et l’exécuteur ne font plus confiance au relais qui les relie), l’exécution distante multiplateforme conserve le répertoire de travail et le shell natifs de l’exécuteur, et TLS accepte les signatures de certificats P-521 pour les proxys d’entreprise.⁶⁵ Si votre orchestration pilote des exécuteurs Codex au-delà d’une frontière réseau, c’est ce qui distingue l’hypothèse d’un relais de confiance d’un chiffrement de bout en bout — considérez cette version comme la référence minimale pour toute topologie d’exécuteurs distants.

La série de juillet 2026 montre les deux environnements d’exécution converger vers les mêmes primitives depuis des directions opposées.⁷² Codex v0.143.0 charge par défaut les outils MCP au moyen de la recherche d’outils : les schémas d’outils sont différés et récupérés à la demande au lieu d’être chargés d’emblée dans le contexte. C’est le même modèle de chargement différé des outils que Claude Code propose par l’intermédiaire de son interface ToolSearch, et la bonne réponse, dans les deux environnements d’exécution, à l’engorgement du contexte lorsque le nombre d’outils MCP est élevé. Codex v0.144.0 ajoute un mode d’approbation des applications writes : les actions en lecture seule s’exécutent sans demander de confirmation, tandis que les écritures nécessitent une approbation. Il s’agit d’une véritable nouvelle primitive de gestion des autorisations, située entre la lecture seule et l’approbation automatique, que la liste des modes de Claude Code n’exprime pas directement (son équivalent le plus proche est le mode plan, qui bloque entièrement les écritures au lieu de demander une confirmation pour chacune). La même version fait passer l’authentification interactive de MCP en disponibilité générale. Enfin, la v0.144.5 étend la détection des commandes dangereuses, à l’image des garde-fous contre les commandes destructrices introduits par Claude Code dans les versions v2.1.183 et v2.1.208. Pour concevoir un harness compatible avec plusieurs environnements d’exécution, l’essentiel réside dans cette convergence : le chargement différé des outils, l’approbation graduée des écritures et le blocage des commandes dangereuses au niveau de l’intention deviennent des prérequis plutôt que des facteurs de différenciation entre fournisseurs.

Codex v0.145.0 approfondit cette convergence sur deux fronts.⁷⁶ L’interface facultative multi-agent V2 s’est stabilisée : les modèles des subagents, les niveaux de raisonnement et la concurrence sont désormais configurables, tandis que les rôles d’agents précédemment supprimés ont été rétablis — la réponse de Codex à la configuration du modèle et du niveau d’effort par subagent dans le frontmatter de .claude/agents/. Par ailleurs, /import est devenu un véritable outil de migration entre harness : au-delà de l’importation des paramètres de Claude Code introduite avec la v0.140.0, il migre désormais les paramètres de Claude Code et de Cursor, y compris les serveurs MCP, les plugins, les sessions, les commandes et les mémoires propres aux projets. Pour les équipes qui utilisent les deux environnements d’exécution, le coût de migration entre eux continue de diminuer dans un sens ; les couches du harness que vous construisez sur Claude Code — serveurs, skills sous forme de commandes, mémoire — constituent de plus en plus un état portable plutôt qu’un enfermement propriétaire.

Correspondances pratiques :

Différence importante : les subagents de Claude peuvent être sélectionnés automatiquement à partir de leurs descriptions, tandis que Codex documente actuellement les workflows de subagents comme explicites. Les skills et hooks constituent donc le meilleur choix par défaut pour les comportements permanents du harness dans Codex ; réservez les subagents aux tâches parallèles, aux revues et aux explorations délibérées.

Tester vos instructions

Vérifiez que l’agent lit et suit réellement vos instructions :

# Check active instructions
claude --print "What instructions are you following for this project?"

# Verify specific rules are active
claude --print "What is your definition of done?"

Le test décisif : demandez à l’agent d’expliquer vos commandes de compilation. S’il ne peut pas les reproduire mot pour mot, les instructions sont soit trop longues (leur contenu a été évincé du contexte), soit trop vagues (l’agent ne peut pas en extraire d’instructions exploitables), soit introuvables. L’analyse de 2 500 dépôts menée par GitHub a montré que le manque de précision est à l’origine de la plupart des échecs.²¹

Modèles de production

Modèles à long horizon d’Opus 4.7 (avril 2026)

Claude Opus 4.7 (16 avril 2026) a été livré avec des capacités spécifiques qui modifient les risques contre lesquels un harness doit se prémunir :²⁹

• Résilience aux échecs d’outils : Opus 4.7 continue malgré des échecs d’outils qui arrêtaient les sessions Opus 4.6. Vous pouvez réduire — sans les éliminer — les wrappers défensifs de nouvelle tentative dans le code des subagents. Conservez les garde-fous au niveau des hooks ; allégez l’échafaudage dans le prompt du type « si l’outil échoue, réessayez trois fois ».
• Niveau d’effort xhigh : Introduit avec Opus 4.7 et désormais pris en charge par les modèles Opus actuels (Opus 4.8 l’a livré sous la forme de /effort xhigh dans la v2.1.154 ; Opus 5 en hérite). Il se situe entre high et max. C’est la valeur par défaut recommandée pour les charges de travail de programmation et agentiques. Pour les subagents de longue durée, xhigh surpasse sensiblement high pour un coût en tokens sous-proportionnel. max reste le bon choix pour un raisonnement difficile ponctuel ; xhigh est préférable pour les tâches soutenues.
• Plafond de budget de tokens : Configurable pour chaque exécution d’agent via output_config.task_budget (en-tête bêta task-budgets-2026-03-13). Le modèle voit un décompte en cours et adapte progressivement le périmètre du travail au budget, au lieu de s’épuiser de façon inattendue. Utilisez-le pour les boucles agentiques lorsque vous souhaitez des dépenses de tokens prévisibles sans sacrifier la qualité sur les prompts courts.
• Conscience des besoins implicites : Premier modèle Claude à réussir les tests de « besoins implicites » — en reconnaissant que la demande littérale de l’utilisateur ne précise pas suffisamment ce dont il a réellement besoin. Cela rend moins nécessaire la section « règles de clarification » de CLAUDE.md. Si votre CLAUDE.md contient 200 lignes de garde-fous du type « prendre également X en compte lorsque l’utilisateur demande Y », supprimez ceux qui sont désormais couverts nativement.

Base de worktree, chemins du sandbox et paramètres d’administration (7 mai 2026)

Claude Code v2.1.133 ajoute quatre paramètres de niveau administrateur à connaître pour les harnesses de production :³⁹

Le retour de worktree.baseRef est celui qu’il faut signaler aux utilisateurs : les agents qui s’appuyaient sur le comportement des v2.1.128 à v2.1.132 (des worktrees créés depuis le HEAD local) perdent l’accès au travail non poussé dans les nouveaux worktrees, sauf s’ils réactivent ce comportement.

Enquête de feedback OTel pour l’observabilité en entreprise (8 mai 2026)

Claude Code v2.1.136 a ajouté CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL afin de réactiver l’enquête de qualité en session pour les entreprises qui capturent les réponses via OpenTelemetry.⁴⁰ Si votre organisation envoie les événements OTel vers une pile d’observabilité centralisée, cette variable d’environnement remet l’enquête dans le chemin de données afin que le signal de qualité circule dans le même pipeline que les métriques de latence et d’erreurs. Considérez-la comme une option à activer explicitement : par défaut, l’enquête reste supprimée, ce qui convient aux déploiements sans OTel.

Lanceurs d’entreprise et performances à l’échelle de MCP (juillet 2026)

Deux changements de la v2.1.207 comptent pour les déploiements de production.⁶⁸ CLAUDE_CODE_PROCESS_WRAPPER permet aux environnements gérés de lancer le processus Claude Code via un binaire wrapper d’entreprise — le point d’intégration pour les agents de terminaux, les vérifications de politiques au lancement et les environnements où chaque processus doit s’exécuter sous un superviseur imposé. Si votre entreprise simulait auparavant cela avec des alias shell ou des scripts de lancement forkés, voici l’interface prise en charge.

La même version a réduit la surcharge d’exécution là où les harnesses la ressentent le plus : jusqu’à 7× plus rapide pour les cycles d’utilisation d’outils dans les sessions comptant beaucoup d’outils MCP, et des transcriptions de session 79× plus petites.⁶⁸ Cela assouplit — sans l’inverser — la recommandation Le coût comme architecture : CLI-first reste gagnant pour les opérations ponctuelles sans état, mais un harness transportant des dizaines d’outils MCP ne paie plus la pénalité par cycle qu’il payait au printemps, et le stockage des transcriptions cesse d’être un coût caché des longues exécutions autonomes.

La boucle de qualité

Un processus de revue obligatoire pour toute modification non triviale :

1. Implémenter - Écrivez le code
2. Réviser - Relisez chaque ligne. Repérez les fautes de frappe, les erreurs de logique et les sections peu claires
3. Évaluer - Exécutez l’evidence gate. Vérifiez les modèles, les cas limites et la couverture de tests
4. Affiner - Corrigez chaque problème. Ne reportez jamais à « plus tard »
5. Prendre du recul - Vérifiez les points d’intégration, les imports et le code adjacent afin de détecter les régressions
6. Répéter - Si un critère de l’evidence gate échoue, revenez à l’étape 4
7. Rapporter - Indiquez ce qui a changé, comment cela a été vérifié et citez des preuves précises

L’evidence gate

« Je pense » et « cela devrait » ne sont pas des preuves. Citez des chemins de fichiers, des sorties de tests ou du code précis.

Si vous ne pouvez pas fournir de preuve pour une ligne, revenez à Affiner.²²

Autorité humaine de fusion

Une étude arXiv de mai 2026 portant sur 29 585 cycles de vie de pull requests d’agents IA distingue l’autonomie opérationnelle de la gouvernance des fusions.⁴⁷ La leçon d’architecture utile est simple : les agents peuvent commencer le travail, faire progresser des branches, ouvrir des PR, examiner le travail et résumer les risques, tandis que l’autorité de fusion demeure une limite de gouvernance distincte.

Rendez cette limite explicite dans le harness. Laissez les agents préparer les PR et recueillir les preuves ; exigez une approbation humaine pour les fusions, les versions et les opérations destructrices sur le dépôt, à moins que l’organisation ne dispose d’une politique d’automatisation auditée séparément. Lorsqu’une automatisation effectue une fusion, conservez des journaux qui distinguent l’exécutant de la personne ou de la politique qui l’a autorisée.

Modèles de gestion des erreurs

Écritures de fichiers atomiques. Plusieurs agents écrivant simultanément dans le même fichier d’état corrompent JSON. Écrivez dans des fichiers .tmp, puis utilisez mv de façon atomique. Le système d’exploitation garantit que mv est atomique sur le même système de fichiers.¹⁷

# Atomic state update
jq --argjson d "$new_depth" '.depth = $d' "$STATE_FILE" > "${STATE_FILE}.tmp"
mv "${STATE_FILE}.tmp" "$STATE_FILE"

Récupération après corruption d’état. Si l’état est corrompu, le modèle de récupération le recrée à partir de valeurs par défaut sûres plutôt que de provoquer un arrêt :¹⁶

if ! jq -e '.depth' "$RECURSION_STATE_FILE" &>/dev/null; then
    # Corrupted state file, recreate with safe defaults
    echo '{"depth": 0, "agent_id": "root", "parent_id": null}' > "$RECURSION_STATE_FILE"
    echo "- Recursion state recovered (was corrupted)"
fi

Le piège bash ((VAR++)). ((VAR++)) renvoie le code de sortie 1 lorsque VAR vaut 0, car 0++ s’évalue à 0, ce que bash considère comme faux. Avec set -e activé, cela arrête le script. Utilisez plutôt VAR=$((VAR + 1)).¹⁶

Classification du rayon d’impact

Classez chaque action d’agent selon son rayon d’impact et appliquez le contrôle correspondant :²

Remote Control (connexion à Claude Code local depuis n’importe quel navigateur ou application mobile) transforme le contrôle « Externe » d’une attente bloquante en notification asynchrone. L’agent continue de travailler sur la tâche suivante pendant que vous examinez la précédente depuis votre téléphone.²

Spécification des tâches pour les exécutions autonomes

Les tâches autonomes efficaces comportent trois éléments : objectif, critères de finalisation et pointeurs de contexte :¹⁶

OBJECTIVE: Implement multi-agent deliberation with consensus validation.

COMPLETION CRITERIA:
- All tests in tests/test_deliberation_lib.py pass (81 tests)
- post-deliberation.sh validates consensus above 70% threshold
- recursion-guard.sh enforces spawn budget (max 12 agents)
- No Python type errors (mypy clean)

CONTEXT:
- Follow patterns in lib/deliberation/state_machine.py
- Consensus thresholds in configs/deliberation-config.json
- Spawn budget model: agents inherit budget, not increment depth

Les critères doivent être vérifiables par machine : réussite/échec des tests, sortie du linter, codes d’état HTTP, vérifications de l’existence de fichiers. Une première tâche demandant à l’agent d’« écrire des tests qui réussissent » a produit assert True et assert 1 == 1. Techniquement correct. Concrètement inutile.¹⁶

Modes d’échec à surveiller

Trace de session concrète

Une trace de session issue d’une exécution autonome traitant un PRD avec 5 stories :²

1. SessionStart se déclenche. Le dispatcher injecte : date actuelle, détection de projet, contraintes philosophiques, initialisation du suivi des coûts. Cinq hooks, 180 ms au total.

2. L’agent lit le PRD, planifie la première story. UserPromptSubmit se déclenche. Le dispatcher injecte : contexte du projet actif, base de référence de la dérive de session.

3. L’agent appelle Bash pour exécuter les tests. PreToolUse:Bash se déclenche. Vérification des identifiants, validation du sandbox, détection de projet. 90 ms. Les tests s’exécutent. PostToolUse:Bash se déclenche : pulsation d’activité journalisée, vérification de dérive.

4. L’agent appelle Write pour créer un fichier. PreToolUse:Write se déclenche : vérification du périmètre de fichier. PostToolUse:Write se déclenche : contrôle de lint, suivi des commits.

5. L’agent termine la story. Stop se déclenche. Le contrôle qualité vérifie : l’agent a-t-il cité des preuves ? Utilisé un langage hésitant ? Laissé des commentaires TODO dans le diff ? Si une vérification échoue, sortie 2 et l’agent continue.

6. Vérification indépendante : un agent neuf exécute la suite de tests sans faire confiance à l’auto-évaluation de l’agent précédent.

7. Trois agents de revue de code sont lancés en parallèle. Chacun examine le diff indépendamment. Si un reviewer signale CRITICAL, la story retourne dans la file d’attente.

8. La story réussit. La story suivante se charge. Le cycle se répète pour les 5 stories.

Nombre total de hooks déclenchés sur 5 stories : ~340. Temps total passé dans les hooks : ~12 secondes. Cette surcharge a empêché trois fuites d’identifiants, une commande destructive et deux implémentations incomplètes lors d’une seule exécution nocturne.

Étude de cas : traitement nocturne de PRD

Un harness de production a traité 12 PRDs (47 stories) sur 8 sessions nocturnes. Les métriques comparent les 4 premiers PRDs (harness minimal : CLAUDE.md uniquement) aux 8 derniers (harness complet : hooks, skills, quality gates, revue multi-agent).

Les deux fuites d’identifiants ont nécessité la rotation de clés API et l’audit de services en aval : environ 4 heures de réponse à incident. La surcharge du harness qui a empêché l’équivalent était de 2,4 secondes de bash par story. Le taux de fausse finalisation est passé de 35 % à 4 % parce que le hook Stop exécutait indépendamment les tests avant d’autoriser l’agent à signaler la fin.

Considérations de sécurité

Les cinq principes d’agents dignes de confiance (Anthropic, avril 2026)

Anthropic a publié un cadre formel pour la fiabilité des agents le 9 avril 2026.²⁷ Les cinq principes font écho à la réflexion sur l’Evidence Gate de ce guide — tout en l’étendant :

Anthropic a également fait don de MCP à l’Agentic AI Foundation de la Linux Foundation, rejoignant AGENTS.md (désormais géré conjointement avec OpenAI, Google, Cursor, Factory et Sourcegraph). Les standards d’interopérabilité des agents sont désormais indépendants des fournisseurs.²⁷

Le tour sans état et l’identité auto-déclarée de MCP. La spécification MCP a achevé sa transition vers un cœur sans état (SEP-2575) avec la révision du 28 juillet 2026, désormais la spécification actuelle, qui supprime la poignée de main initialize avec état qui transportait auparavant l’identité du serveur. Une modification de la spécification provisoire fusionnée le 16 juillet (PR #3002) rétablit l’identité comme surface facultative : les serveurs peuvent inclure un objet io.modelcontextprotocol/serverInfo dans _meta de la réponse, et clientInfo devient facultatif dans les requêtes.⁷¹ L’élément pertinent pour la sécurité est ce que la spécification indique sur la confiance : cette identité est auto-déclarée et non vérifiée — uniquement pour l’affichage et la journalisation — et NE DEVRAIT PAS guider les décisions de sécurité. Si votre harness fonde des listes d’autorisation, des règles de permission ou un audit fondé sur les journaux sur le nom déclaré d’un serveur MCP, ce nom est une affirmation, pas un identifiant ; ancrez la confiance dans le transport et la configuration (le serveur que vous avez configuré à tel endpoint), jamais dans ce que le serveur prétend être. La révision sans état a été publiée comme prévu le 28 juillet 2026 (server/discover obligatoire, négociation de la version du protocole via _meta, en-tête Streamable HTTP) — les recommandations de confiance ci-dessus décrivent le comportement publié.

Outil de sandbox pour skills : Pour les équipes qui considèrent les skills comme une surface d’attaque, SandyClaw de Permiso (lancé le 2 avril 2026) exécute les skills dans un sandbox dédié et fournit des verdicts étayés par des preuves issues de détections Sigma/YARA/Nova/Snort. Premier produit de la catégorie des sandbox pour skills.²⁸

Le sandbox

Claude Code prend en charge un mode sandbox facultatif (activé via settings.json ou la commande /sandbox) qui restreint l’accès réseau et les opérations du système de fichiers grâce à une isolation au niveau du système d’exploitation (seatbelt sur macOS, bubblewrap sur Linux). Lorsqu’il est activé, le sandbox empêche le modèle d’effectuer des requêtes réseau arbitraires ou d’accéder à des fichiers en dehors du répertoire du projet. Sans sandboxing, Claude Code utilise un modèle fondé sur les permissions, dans lequel vous approuvez ou refusez chaque appel d’outil.¹³

Niveau de sécurité minimal de mai 2026. Claude Code v2.1.149 a corrigé un contournement de permission du répertoire de travail PowerShell, plusieurs lacunes de l’analyse des permissions liées aux règles d’autorisation PowerShell et aux variables obsolètes, ainsi qu’un bug de liste d’autorisation d’écriture du sandbox dans les git-worktrees qui couvrait toute la racine du dépôt principal au lieu des seuls éléments internes git partagés.⁵³ Si votre harness autorise PowerShell ou des agents isolés par worktree, considérez v2.1.149+ comme le minimum et gardez des règles shell étroites. Les exceptions larges PowerShell(*) et les autorisations d’écriture sur l’ensemble du dépôt sont des raccourcis d’orchestration, pas des frontières de sécurité.

Verrouillage du sandbox OpenAI Agents SDK (v0.17.0, 8 mai 2026). Côté OpenAI, openai-agents-python v0.17.0 a renforcé une frontière parallèle : LocalFile.src et LocalDir.src sont désormais limités à l’intérieur du base_dir de matérialisation (le répertoire de travail courant du processus SDK lors de l’application du manifeste), sauf si la source est explicitement accordée via Manifest.extra_path_grants avec SandboxPathGrant.⁴¹ Les sources locales relatives sont résolues à partir de base_dir ; les chemins absolus doivent déjà s’y trouver ou disposer d’une autorisation. Cela corrige un problème de frontière des artefacts locaux : les versions antérieures permettaient aux manifestes d’importer des chemins hôte arbitraires dans un espace de travail sandbox. Migration : déclarez les racines hôte de confiance au niveau du manifeste avec SandboxPathGrant(path=..., read_only=True) pour les montages en lecture seule. Considérez extra_path_grants comme une configuration applicative de confiance ; ne renseignez jamais ces autorisations à partir de la sortie du modèle ou d’une entrée de manifeste non fiable.

Niveau minimal de suivi pour OpenAI Agents SDK (v0.17.3). La série 0.17.1-0.17.3 a ajouté d’autres renforcements du sandbox et des sessions : limites d’extraction d’archives, validation des sous-chemins GitRepo, erreurs plus claires du fournisseur de sandbox, identifiants de point de montage exclus des commandes du sandbox, rejet des racines relatives d’espace de travail sandbox et gestion des états terminaux de Vercel-sandbox.⁵⁴ Si vous utilisez des sandbox hébergés par OpenAI ou soutenus par un fournisseur plutôt que seulement des hooks Claude Code, considérez 0.17.3 comme le minimum actuel pour les modèles de cette section.

Trois modèles de confinement entre les produits (Anthropic, mai 2026)

L’article d’ingénierie de Anthropic « How we contain Claude across products » (25 mai 2026) formule, du point de vue du fournisseur, les principes que cette section enseigne par fragments — le sandbox au niveau des paramètres ci-dessus, le niveau minimal d’isolation par worktree, la posture consistant à traiter chaque élément comme non fiable.⁸¹ Son geste central consiste à associer la force du confinement à la surface produit, et cette association est elle-même la leçon : il n’existe pas une conception d’isolation unique et correcte, seulement une isolation adaptée à qui supervise et à ce qui peut mal tourner.

• Conteneurs gVisor éphémères (claude.ai). L’exécution côté serveur s’effectue dans des conteneurs gVisor sur une infrastructure isolée avec un système de fichiers éphémère par session. Le modèle de menace concerne l’isolation de l’infrastructure et des tenants — la machine de l’utilisateur n’est jamais accessible, donc rien de local n’a besoin d’être protégé.
• Sandboxing du système d’exploitation avec humain dans la boucle (Claude Code). Le modèle décrit dans le paragraphe sur le sandbox ci-dessus, exprimé comme politique : Seatbelt sur macOS et bubblewrap sur Linux, avec lectures autorisées, écritures limitées au workspace et réseau refusé par défaut — l’humain approuve ce que la frontière ne couvre pas. Anthropic a publié le runtime en open source (sandbox-runtime), afin que la frontière soit auditable. L’article est franc sur le maillon faible : environ 93 % des demandes de permission sont approuvées, et le classificateur du mode auto — qui intercepte environ 83 % des comportements trop zélés avant l’exécution tout en réduisant les demandes d’approbation de 84 % — existe précisément parce que la fatigue d’approbation est une propriété de sécurité, pas une plainte d’UX. C’est la posture de couche de vérification que ce guide suit depuis v2.1.193.
• VM scellées (Claude Cowork). Des machines virtuelles complètes sur des hyperviseurs de plateforme — Apple Virtualization framework sur macOS, HCS sur Windows — avec uniquement le workspace sélectionné et le dossier .claude montés ; rien d’autre de l’hôte n’est visible. Les identifiants n’entrent jamais dans la VM : ils restent dans le keychain de l’hôte, et chaque session reçoit un jeton limité et révocable indépendamment. Un proxy MITM défensif à l’intérieur de la VM l’applique, en ne laissant passer que les requêtes portant le propre jeton de session provisionné de la VM — une clé intégrée par un attaquant est rejetée à la frontière, car seule la VM connaît sa provenance.

Les principes de conception sous-jacents à cette taxonomie constituent la partie transférable. Confinez d’abord au niveau de l’environnement, orientez ensuite au niveau du modèle : toute défense probabiliste possède un taux d’échec non nul, donc des frontières déterministes doivent intercepter ce que l’orientation au niveau du prompt manque — l’argument de ce guide selon lequel les hooks garantissent l’exécution, reformulé par le fournisseur. Adaptez la force d’isolation à la capacité de supervision de l’utilisateur : un développeur peut évaluer une commande bash avant de l’approuver ; un travailleur du savoir ne le peut pas — c’est pourquoi Code reçoit une boîte de dialogue de permission et Cowork une VM scellée. Préférez des primitives éprouvées au code d’isolation personnalisé : les hyperviseurs, seccomp et runtimes de conteneurs ont mieux résisté à l’examen adversarial que les propres proxys de listes d’autorisation et analyseurs de configuration personnalisés de Anthropic. Traitez la configuration locale au projet et les sorties d’outils comme non fiables : l’instruction de l’article est de traiter l’ouverture du projet et le chargement de configuration comme toute requête entrante depuis Internet, et la sortie d’un outil comme une surface d’attaque même lorsque l’outil est fiable — la même posture que ce guide applique aux messages inter-agents, au contenu lu par les subagents et à l’identité MCP auto-déclarée. Gardez les identifiants hors du sandbox : des jetons limités, révocables et par session plutôt que des clés ambiantes que l’agent pourrait divulguer.

La surface des paramètres rattrape le premier principe (v2.1.219). Il est facile d’adhérer à « Confinez d’abord au niveau de l’environnement » et cela a été difficile à configurer concrètement, car le sandbox de Claude Code résolvait ce que ses règles ne couvraient pas en demandant — et une demande de permission est une défense probabiliste déguisée en mécanisme déterministe, comme le reconnaît le taux d’approbation de 93 % ci-dessus. sandbox.network.strictAllowlist supprime la question pour les sorties réseau : lorsqu’il est défini, la requête d’une commande sandboxée vers un hôte absent de la liste d’autorisation est refusée directement au lieu de déclencher une demande.⁸⁴ Associez-le à sandbox.filesystem.disabled de v2.1.216 et les deux paramètres composent une posture plutôt qu’un empilement de bascules — le confinement du système de fichiers et du réseau est sélectionnable indépendamment, et le confinement réseau peut désormais être rendu déterministe. Pour un harness sans surveillance, c’est le plus important des deux, car la sortie réseau est l’endroit où une instruction injectée devient une exfiltration, et le cas limite de la fatigue d’approbation est qu’il n’y a personne au clavier pour être fatigué. Le coût est le coût ordinaire d’une frontière déterministe : la liste d’autorisation doit être correcte, et un hôte oublié échoue par un refus opaque plutôt que par une question. Énumérez les hôtes dont vos agents ont légitimement besoin, puis supprimez la demande.

Rien de cela ne remplace la couche de hooks ; cela se situe en dessous. Les modèles de confinement constituent le socle déterministe, et l’historique d’application des worktrees dans ce guide est la même leçon en miniature : une frontière ne compte que si elle résiste à une redirection délibérée, et les primitives les plus susceptibles de tenir sont celles qui n’ont pas été écrites pour l’occasion.

Frontières de permission

Le système de permissions contrôle les opérations à plusieurs niveaux :

Règles de permission au niveau des paramètres (juin 2026)

Claude Code v2.1.178 a étendu les règles de permission du niveau de l’outil au niveau des paramètres : Tool(param:value) est comparé aux paramètres d’entrée d’un outil, avec * comme joker. L’exemple canonique est Agent(model:opus) — une règle qui empêche de lancer des subagents sur un niveau de modèle spécifique.⁶³ Sur le plan architectural, cela comble une lacune que le tableau à quatre niveaux ci-dessus ne pouvait pas exprimer : auparavant, vous autorisiez ou refusiez un outil dans son ensemble, sans pouvoir contraindre la façon dont il était appelé. Une politique de gouvernance peut désormais dire « les subagents peuvent être lancés, mais pas sur le niveau Fable 5 » ou « Bash est autorisé, mais pas avec ce flag » comme règle déterministe plutôt que comme demande au niveau du prompt.

Un paramètre géré associé, enforceAvailableModels (v2.1.175), contraint le choix du modèle de haut en bas : il fixe le modèle Default et empêche les paramètres à portée utilisateur ou projet d’élargir la liste d’autorisation availableModels gérée.⁶³ Les deux se composent — la liste d’autorisation définit les niveaux qui existent pour la session, et les règles au niveau des paramètres contraignent la manière dont les subagents y puisent. Depuis v2.1.196, les administrateurs peuvent également définir un modèle par défaut à l’échelle de l’organisation depuis la console d’organisation, affiché sous le nom « Org default » dans /model, afin qu’une flotte hérite d’une valeur par défaut gouvernée sans que chaque opérateur en fixe une — un plancher pour compléter le plafond de la liste d’autorisation.

Les règles d’autorisation limitées aux chemins s’ancrent dans le répertoire de travail (juillet 2026)

Claude Code v2.1.214 a corrigé une surcorrespondance discrète dans les règles de permission limitées aux chemins : une règle d’autorisation avec un motif dir/** à un seul segment — par exemple Edit(src/**) — approuvait automatiquement les modifications de tout dossier nommé src, à n’importe quelle profondeur, y compris vendor/some-package/src/ et tout autre src/ imbriqué que l’auteur de la règle n’avait jamais voulu autoriser. Ces règles s’ancrent désormais uniquement à <cwd>/dir ; si vous souhaitez réellement une correspondance à toute profondeur, déclarez-la avec **/dir/**.⁷⁴ Les règles de refus et de demande conservent délibérément l’ancienne correspondance à toute profondeur. Cette asymétrie est une conception de sûreté correcte : une règle d’autorisation qui correspond trop étroitement échoue de manière sûre (vous obtenez une demande), alors qu’une règle de refus qui correspond trop étroitement échoue de manière ouverte (un chemin bloqué passe à travers) — les autorisations sont donc devenues plus strictes et les refus sont restés larges. Si vos paramètres reposent sur des motifs d’autorisation à un seul segment pour couvrir des chemins imbriqués, ils ont silencieusement cessé de le faire avec v2.1.214 ; c’est le correctif qui fonctionne comme prévu, mais cela mérite de revoir vos listes d’autorisation afin de redéclarer l’étendue que vous souhaitez réellement.

Garde-fous des commandes destructrices en mode Auto (juin 2026)

Claude Code v2.1.183 a réduit le rayon d’impact du mode auto pour les opérations qui font perdre du travail ou détruisent des environnements sans bruit. Le mode auto bloque désormais fermement, sauf si vous les avez explicitement demandées dans la session : les opérations git destructrices (git reset --hard, git checkout -- ., git clean -fd, git stash drop) ; git commit --amend lorsque le commit n’a pas été créé par l’agent au cours de cette session ; et la suppression d’infrastructure (terraform destroy, pulumi destroy, cdk destroy) à moins que vous n’ayez nommé la stack précise.⁶⁵ Sur le plan architectural, cela complète les règles de vérification au lancement et au niveau des paramètres ci-dessus : au lieu de contrôler quel outil ou comment il est lancé, cela contrôle un petit ensemble de commandes irréversibles précises par l’intention — l’agent peut toujours les exécuter, mais uniquement sur instruction explicite, pas de sa propre initiative. Pour un harness autonome, encodez le même principe dans vos propres hooks PreToolUse : les commandes qui détruisent l’état méritent une règle de refus par défaut que seul un signal explicite de l’opérateur lève.

Juillet 2026 : le mode auto passe à l’entreprise, et une demande devient impossible à ignorer. Le mode auto a atteint la disponibilité générale sur Amazon Bedrock, Google Vertex AI et Microsoft Foundry dans v2.1.207, avec un paramètre géré disableAutoMode comme option de désactivation pour les entreprises — la posture du classificateur comme couche de vérification est désormais disponible sur toutes les plateformes d’entreprise first-party, et sa désactivation relève d’une décision de gouvernance explicite plutôt que d’une lacune de plateforme.⁶⁸ v2.1.208 a ensuite rendu la protection contre les suppressions catastrophiques absolue : les demandes de confirmation pour les suppressions catastrophiques s’appliquent à la fois à --dangerously-skip-permissions et au mode auto.⁶⁸ C’est un précédent notable — la première confirmation dans Claude Code qu’aucune posture de permission, y compris le flag explicite de contournement, ne peut ignorer. Les conceptions de harness autonome qui supposaient que --dangerously-skip-permissions signifiait littéralement zéro demande devraient tenir compte de cette exception ; elle se déclenche précisément là où une boucle sans surveillance peut causer les dommages les plus irrécupérables.

Garde-fous anti-fabrication (juillet 2026)

Les versions v2.1.203–v2.1.206 ont fermé deux voies par lesquelles un agent pouvait fabriquer sa propre piste d’audit.⁶⁸ Premièrement, une règle du mode auto bloque désormais la falsification des fichiers de transcription — l’enregistrement de la session n’est plus quelque chose que les propres appels d’outils de la session peuvent réécrire. Deuxièmement, les notifications de tâches en arrière-plan indiquent désormais explicitement qu’aucune entrée humaine n’est survenue pendant l’exécution de la tâche. La seconde vise une défaillance subtile : un modèle résumant une tâche en arrière-plan pouvait auparavant présenter (ou inventer) une « approbation » dans la transcription qui n’avait jamais eu lieu, et rien dans la notification ne le contredisait. Désormais, la notification elle-même constitue la contre-preuve.

La leçon architecturale se généralise à l’Evidence Gate : les transcriptions, notifications et journaux sont des surfaces d’audit, et les surfaces d’audit ne doivent pas être inscriptibles par ce qu’elles auditent. La plateforme l’applique désormais à sa propre transcription ; appliquez la même règle à votre harness — les rapports de preuves, sorties de tests et comptes rendus de délibération doivent se trouver hors du chemin inscriptible du modèle.

Défense contre l’injection de prompt

Les skills et hooks assurent une défense en profondeur contre l’injection de prompt :

Les skills avec restrictions d’outils empêchent qu’un prompt compromis obtienne un accès en écriture :

allowed-tools: Read, Grep, Glob

Les hooks PreToolUse valident chaque appel d’outil, quelle que soit la manière dont le modèle a été sollicité :

# Block credential file access regardless of prompt
if echo "$FILE_PATH" | grep -qE "\.(env|pem|key|credentials)$"; then
    echo "BLOCKED: Sensitive file access" >&2
    exit 2
fi

L’isolation des subagents limite le rayon d’impact. Un subagent avec permissionMode: plan ne peut pas effectuer de modifications, même si son prompt est compromis.

Le niveau minimal de la plateforme a augmenté en juillet 2026. Claude Code v2.1.210 a renforcé l’Agent tool contre l’injection indirecte de prompt transportée dans le contenu lu par un subagent — un fichier, une page web ou un résultat d’outil empoisonné récupéré par un subagent peut moins orienter la surface de délégation elle-même.⁶⁹ Et v2.1.211 a renforcé le maillon humain de la chaîne : les aperçus de permissions neutralisent désormais les caractères Unicode de remplacement bidirectionnel, de largeur nulle et ressemblants, afin qu’une commande ne puisse plus être conçue pour s’afficher comme anodine dans la boîte de dialogue d’approbation tout en exécutant autre chose.⁶⁹ Le second correctif est particulièrement important pour les harnesses où un humain approuve des aperçus affichés sous pression temporelle — l’affichage était lui aussi une surface d’injection. Aucun de ces changements ne remplace les défenses au niveau des hooks ci-dessus ; ils élèvent le niveau minimal sous-jacent.

Les journaux d’agents et les garde-fous sont des surfaces de sécurité

Deux avis de mai 2026 renforcent un schéma : l’infrastructure des agents crée de nouveaux endroits où du contenu sensible et des politiques exécutables peuvent fuiter ou s’échapper. L’avis GHSA-f3jg-756w-gm35 de GitHub couvre un problème de filtre de payload Gryph Agents où le contenu sensible des payloads d’outils pouvait rester dans des journaux SQLite locaux avec le comportement de journalisation par défaut.⁴⁵ OSV GHSA-wxxx-gvqv-xp7p couvre une évasion du sandbox des garde-fous de code personnalisé LiteLLM dans un endpoint proxy protégé par administrateur.⁴⁶

La règle de production : traitez les transcriptions d’agents, payloads d’outils, journaux SQLite et exécution des garde-fous comme une infrastructure sensible. Supprimez les informations sensibles avant la persistance, appliquez des limites de rétention et maintenez le code personnalisé des garde-fous sandboxé et révisable. Une règle au niveau du prompt telle que « ne pas journaliser les secrets » ne suffit pas ; le chemin de journalisation et de garde-fou nécessite des tests déterministes.

Sécurité des hooks

Les hooks HTTP qui interpolent des variables d’environnement dans les en-têtes nécessitent une liste explicite allowedEnvVars afin d’empêcher l’exfiltration arbitraire de variables d’environnement :¹³

{
  "type": "http",
  "url": "https://api.example.com/notify",
  "headers": {
    "Authorization": "Bearer $MY_TOKEN"
  },
  "allowedEnvVars": ["MY_TOKEN"]
}

La répartition des responsabilités entre humains et agents

La sécurité des architectures d’agents exige une répartition claire entre les responsabilités humaines et celles des agents :¹⁷

Le modèle : les humains possèdent les décisions qui exigent un contexte organisationnel, un jugement éthique ou une orientation stratégique. Les agents possèdent les décisions qui exigent une recherche computationnelle dans de vastes espaces de possibilités. Les hooks appliquent cette frontière.

Application récursive des hooks

Les hooks se déclenchent aussi pour les actions des subagents.¹³ Si Claude lance un subagent via l’Agent tool, vos hooks PreToolUse et PostToolUse s’exécutent pour chaque outil utilisé par le subagent. Sans application récursive des hooks, un subagent pourrait contourner vos garde-fous de sécurité. L’événement SubagentStop vous permet d’exécuter un nettoyage ou une validation lorsqu’un subagent termine.

Ce n’est pas facultatif. Un agent qui lance un subagent sans vos hooks de sécurité est un agent qui peut effectuer un force-push vers main, lire des fichiers d’identifiants ou exécuter des commandes destructrices pendant que vos garde-fous regardent la conversation principale sans rien faire.

Le coût comme architecture

Le coût est une décision architecturale, pas une réflexion opérationnelle après coup.² Trois niveaux :

Niveau des tokens. Compression du prompt système. Supprimez les exemples de code tutoriels (le modèle connaît les APIs), regroupez les règles dupliquées entre les fichiers et remplacez les explications par des contraintes. « Refuser les appels d’outils correspondant à des chemins sensibles » accomplit le même travail qu’une explication de 15 lignes expliquant pourquoi les identifiants ne doivent pas être lus.

Niveau des agents. Lancements neufs plutôt que longues conversations. Chaque story d’une exécution autonome reçoit un nouvel agent avec un contexte propre. Le contexte ne gonfle jamais, car chaque agent repart à zéro. Briefing plutôt que mémoire : les modèles exécutent mieux un briefing clair qu’ils ne naviguent dans 30 étapes de contexte accumulé.

Niveau de l’architecture. CLI-first plutôt que MCP lorsque l’opération est sans état. Un appel claude --print pour une évaluation ponctuelle coûte moins cher et n’ajoute aucune surcharge de connexion. MCP a du sens lorsque l’outil nécessite un état persistant ou du streaming.

Cadre décisionnel

Quand utiliser chaque mécanisme :

Skills vs Hooks vs Subagents

FAQ

Combien de hooks est-ce trop ?

La contrainte est la performance, pas le nombre. Chaque hook s’exécute de manière synchrone ; le temps total d’exécution des hooks s’ajoute donc à chaque appel d’outil correspondant. 95 hooks répartis entre les paramètres utilisateur et projet s’exécutent sans latence perceptible lorsque chacun se termine en moins de 200 ms. Le seuil à surveiller : si un hook PostToolUse ajoute plus de 500 ms à chaque modification de fichier, la session devient lente. Analysez vos hooks avec time avant de les déployer.¹⁴

Les hooks peuvent-ils empêcher Claude Code d’exécuter une commande ?

Oui. Les hooks PreToolUse bloquent toute action d’outil en quittant avec le code 2. Claude Code annule l’action en attente et affiche la sortie stderr du hook au modèle. Claude voit la raison du rejet et propose une alternative plus sûre. Le code de sortie 1 correspond à un avertissement non bloquant, l’action se poursuit donc.³

Où placer les fichiers de configuration des hooks ?

Les configurations de hooks se placent dans .claude/settings.json pour les hooks au niveau projet (committés dans votre dépôt et partagés avec votre équipe) ou dans ~/.claude/settings.json pour les hooks au niveau utilisateur (personnels, appliqués à chaque projet). Les hooks au niveau projet sont prioritaires lorsque les deux existent. Utilisez des chemins absolus pour les fichiers de script afin d’éviter les problèmes de répertoire de travail.¹⁴

Chaque décision nécessite-t-elle une délibération ?

Non. Le module de confiance évalue les décisions selon quatre dimensions (ambiguïté, complexité, enjeux, dépendance au contexte). Seules les décisions dont le score de confiance global est inférieur à 0,70 déclenchent une délibération, soit environ 10 % de l’ensemble des décisions. Les corrections de documentation, les renommages de variables et les modifications de routine ignorent entièrement la délibération. L’architecture de sécurité, les changements de schéma de base de données et les déploiements irréversibles la déclenchent systématiquement.⁷

Comment tester un système conçu pour produire des désaccords ?

Testez à la fois les parcours de réussite et les parcours d’échec. Réussite : les agents sont en désaccord de manière productive et atteignent un consensus. Échec : les agents convergent trop vite, ne convergent jamais ou dépassent les budgets de lancement. Les tests de bout en bout simulent chaque scénario avec des réponses déterministes des agents, en vérifiant que les deux portes de validation détectent chaque mode d’échec documenté. Un système de délibération de production exécute 141 tests répartis sur trois couches : 48 tests d’intégration Bash, 81 tests unitaires Python et 12 simulations de pipeline de bout en bout.⁷

Quel est l’impact de la délibération sur la latence ?

Une délibération à 3 agents ajoute 30 à 60 secondes de temps écoulé (cette conception de délibération exécute ses agents séquentiellement via l’Agent tool ; la plateforme elle-même exécute les subagents simultanément en arrière-plan depuis la v2.1.198). Une délibération à 10 agents ajoute 2 à 4 minutes. Les hooks de consensus et de pride check s’exécutent chacun en moins de 200 ms. Le principal goulot d’étranglement est le temps d’inférence de LLM par agent, et non la surcharge d’orchestration.⁷

Quelle doit être la longueur d’un fichier CLAUDE.md ?

Limitez chaque section à moins de 50 lignes et le fichier total à moins de 150 lignes. Les fichiers longs sont tronqués par les fenêtres de contexte ; placez donc les instructions les plus essentielles en tête : les commandes et les définitions de clôture avant les préférences de style.²¹

Cela peut-il fonctionner avec des outils autres que Claude Code ?

Les principes architecturaux (hooks comme portes déterministes, skills comme expertise de domaine, subagents comme contextes isolés, système de fichiers comme mémoire) s’appliquent conceptuellement à tout système agentique. L’implémentation spécifique utilise les événements de cycle de vie, les modèles de correspondance et l’Agent tool de Claude Code. AGENTS.md transpose les mêmes modèles vers Codex, Cursor, Copilot, Amp et Windsurf.²¹ Le modèle de harness est indépendant de l’outil, même si les détails d’implémentation sont propres à chaque outil.

Fiche de référence rapide

Configuration des hooks

{
  "hooks": {
    "PreToolUse": [{"matcher": "Bash", "hooks": [{"type": "command", "command": "script.sh"}]}],
    "PostToolUse": [{"matcher": "Write|Edit", "hooks": [{"type": "command", "command": "format.sh"}]}],
    "Stop": [{"matcher": "", "hooks": [{"type": "agent", "prompt": "Verify tests pass. $ARGUMENTS"}]}],
    "SessionStart": [{"matcher": "", "hooks": [{"type": "command", "command": "setup.sh"}]}]
  }
}

Frontmatter de Skill

---
name: my-skill
description: What it does and when to use it. Include trigger phrases.
allowed-tools: Read, Grep, Glob
---

Définition de subagent

---
name: my-agent
description: When to invoke. Include PROACTIVELY for auto-delegation.
tools: Read, Grep, Glob, Bash
model: opus
permissionMode: plan
---

Instructions for the subagent.

Codes de sortie

Commandes clés

Emplacements des fichiers

Journal des modifications

Références