Architecture des agents : créer des environnements de développement alimentés par l’IA

En bref : Claude Code n’est pas une boîte de dialogue ayant accès aux fichiers. C’est un environnement d’exécution programmable doté de 30 événements documentés du cycle de vie, chacun pouvant être associé à des scripts shell que le modèle ne peut pas ignorer. Empilez les hooks dans des dispatchers, les dispatchers dans des skills, les skills dans des agents et les agents dans des workflows : vous obtenez alors un harness de développement autonome qui impose des contraintes, délègue le travail, conserve la mémoire d’une session à l’autre et orchestre une délibération multi-agent. Claude Code v2.1.147 a ajouté l’outil Workflow, désactivé par défaut (CLAUDE_CODE_WORKFLOWS=1), faisant évoluer l’orchestration multi-agent déterministe de simples scripts userland vers une primitive d’exécution native ; la v2.1.149 confirme cette même leçon sur le plan de la sécurité, avec des correctifs empêchant le contournement des autorisations PowerShell et un correctif de la liste d’autorisation du sandbox pour git-worktree. Les hooks et les evidence gates restent garants de la fiabilité.⁵²⁵³ Ce guide couvre chaque couche de cet ensemble : du simple hook à un système de consensus réunissant 10 agents. Aucun framework requis. Entièrement en bash et JSON.

Andrej Karpathy a inventé un terme pour désigner ce qui se développe autour d’un agent LLM : les claws. Il s’agit des hooks, des scripts et de l’orchestration qui permettent à l’agent d’agir sur le monde au-delà de sa fenêtre de contexte.¹ La plupart des développeurs considèrent les agents de programmation fondés sur l’IA comme des assistants interactifs. Ils saisissent une instruction, regardent l’agent modifier un fichier, puis passent à autre chose. Cette conception limite la productivité à ce que vous pouvez personnellement superviser.

Le modèle mental de l’infrastructure est différent : un agent de programmation fondé sur l’IA est un environnement d’exécution programmable doté d’un noyau LLM. Chaque action entreprise par le modèle passe par des hooks que vous contrôlez. Vous définissez des politiques, pas des prompts. Le modèle fonctionne au sein de votre infrastructure comme un serveur web fonctionne selon les règles de nginx. Vous ne restez pas devant nginx à saisir des requêtes. Vous le configurez, le déployez et le surveillez.

Cette distinction est importante, car les avantages de l’infrastructure se cumulent. Un hook qui bloque les identifiants dans les commandes bash protège chaque session, chaque agent et chaque exécution autonome. Une skill qui formalise votre grille d’évaluation s’applique de manière cohérente, que vous l’invoquiez vous-même ou qu’un agent le fasse. Un agent chargé d’examiner la sécurité du code effectue les mêmes vérifications, que vous le surveilliez ou non.²

Points essentiels

• Les hooks garantissent l’exécution ; les prompts ne le peuvent pas. Utilisez des hooks pour le linting, le formatage, les contrôles de sécurité et tout ce qui doit s’exécuter systématiquement, quel que soit le comportement du modèle. Le code de sortie 2 bloque les actions. Le code de sortie 1 se contente d’émettre un avertissement.³
• Les skills formalisent une expertise métier qui s’active automatiquement. Le champ description détermine tout. Claude s’appuie sur le raisonnement LLM — et non sur une correspondance de mots-clés — pour décider quand appliquer une skill.⁴
• Les subagents évitent de surcharger le contexte. Des fenêtres de contexte isolées pour l’exploration et l’analyse permettent de préserver la légèreté de la session principale. Exécutez en parallèle les subagents indépendants et faites appel à des équipes d’agents lorsque les intervenants doivent se coordonner durablement.⁵
• La mémoire réside dans le système de fichiers. Les fichiers persistent d’une fenêtre de contexte à l’autre. CLAUDE.md, MEMORY.md, les dossiers de règles et les documents de transmission constituent un système structuré de mémoire externe.⁶
• La délibération multi-agent révèle les angles morts. Un agent seul ne peut pas remettre en question ses propres hypothèses. Deux agents indépendants dotés de priorités d’évaluation différentes détectent les défaillances structurelles que les quality gates ne peuvent pas corriger.⁷
• Le harness pattern constitue le système. CLAUDE.md, les hooks, les skills, les agents et la mémoire ne sont pas des fonctionnalités indépendantes. Ensemble, ils forment entre vous et le modèle une couche déterministe qui évolue à mesure que l’automatisation progresse.

Comment utiliser ce guide

Chaque section s’appuie sur la précédente. Le cadre de décision présenté à la fin fournit un tableau de correspondance permettant de choisir le mécanisme adapté à 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 pattern harness

Le harness n’est pas un framework. C’est un pattern : un ensemble composable de fichiers, de scripts et de conventions qui enveloppe un agent de codage IA dans une infrastructure déterministe. Ses 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 dossiers 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. Ils constituent la mémoire architecturale à long terme de l’agent.

Couche d’extension : les skills apportent une expertise métier qui s’active automatiquement selon le contexte. Les hooks fournissent des contrôles 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 spécialisées de subagents.

Couche d’orchestration : les patterns multi-agents coordonnent des agents indépendants pour la recherche, la revue et la délibération. Les budgets de génération empêchent toute récursion incontrôlée. La validation par consensus garantit la qualité.

L’idée clé : la plupart des utilisateurs travaillent exclusivement dans la couche centrale, tandis que le contexte enfle et que les coûts grimpent. 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 gérés ou auto-hébergés (avril 2026)

Jusqu’au début de l’année 2026, la seule véritable option consistait à « construire son propre harness ». La situation a changé en avril 2026. Anthropic a lancé la bêta publique de Claude Managed Agents le 8 avril : boucle du harness + exécution des outils + conteneur sandbox + persistance de l’état sous forme d’API REST, facturées au tarif standard des tokens avec un supplément de 0,08 $ par heure de session. La mise à jour Agents SDK d’OpenAI du 16 avril a formalisé la même séparation : le harness et le calcul constituent des couches distinctes, avec des fournisseurs de sandbox natifs (Blaxel, Cloudflare, Daytona, E2B, Modal, Runloop, Vercel) ainsi qu’un mécanisme de snapshot/réhydratation permettant de résister à la perte d’un conteneur.²³²⁴

Côté OpenAI, l’interface SDK plus complète est arrivée dans Python v0.14.0 d’openai-agents (publiée le 15 avril 2026 et annoncée le 16 avril) : une sous-classe SandboxAgent d’Agent avec default_manifest, des instructions de sandbox et des capacités ; un Manifest décrivant le contrat d’un espace de travail neuf (fichiers, dossiers, fichiers locaux, dépôts Git, environnement, utilisateurs, montages) ; et un SandboxRunConfig permettant de configurer, pour chaque exécution, le client sandbox, l’injection d’une session active, les remplacements du manifeste, les snapshots et les limites de concurrence lors de la matérialisation. Les capacités intégrées couvrent l’accès au shell, la modification du système de fichiers, l’inspection d’images, les skills, la mémoire de la sandbox et la compaction. La mémoire de la sandbox conserve les enseignements extraits entre les exécutions et les dévoile progressivement ; les espaces de travail prennent en charge les fichiers locaux, les entrées de dépôts Git et les montages distants (S3, R2, GCS, Azure Blob, S3 Files) ; les snapshots sont portables d’un fournisseur à l’autre. Backends : UnixLocalSandboxClient, DockerSandboxClient et clients hébergés pour Blaxel, Cloudflare, Daytona, E2B, Modal, Runloop et Vercel au moyen d’extras facultatifs.²⁴

Pour les projets Python qui souhaitent intégrer le runtime Claude Code sous forme de bibliothèque — entre « lancer claude depuis le shell » et « appeler Managed Agents via l’API REST » — claude-agent-sdk-python constitue une troisième option. La série de versions publiées les 28 et 29 avril (v0.1.69 → v0.1.71) a mis à niveau le CLI fourni vers la v2.1.123, relevé la version minimale de la dépendance mcp à >=1.19.0 (les versions antérieures ignoraient silencieusement les retours CallToolResult des outils MCP exécutés dans le processus, ne laissant au modèle qu’un bloc d’erreur de validation) et aligné le schéma de SandboxNetworkConfig sur celui de l’SDK TypeScript (allowedDomains, deniedDomains, allowManagedDomainsOnly, allowMachLookup).³⁰ Au 2026-08-01, le package en est à la v0.2.128 sur PyPI (avec Claude CLI v2.1.220 et une version minimale de mcp désormais fixée à >=1.23.0), tandis que l’SDK TypeScript en est à la v0.3.220 ; la branche 0.2.x améliore progressivement l’interface 0.1.x décrite ici — les options include_hook_events, skills et de configuration de la sandbox ci-dessous restent d’actualité —, les versions récentes s’étant concentrées sur le nettoyage des sous-processus et la fiabilité des flux NDJSON.⁸⁶

Si votre harness comprend une couche vocale ou temps réel, openai-agents-python v0.17.0 (8 mai 2026) a défini gpt-realtime-2 comme modèle par défaut de RealtimeAgent.⁴¹ 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 à des fins d’évaluation.

En juillet 2026, l’offre gérée s’est également enrichie d’une solution multi-agents chez OpenAI : openai-agents-python v0.18.2 (11 juillet) et openai-agents-js v0.13.2 (10 juillet) ajoutent la prise en charge multi-agents hébergée en bêta — une orchestration de plusieurs agents gérée par OpenAI sous forme de service hébergé, pendant direct de la bêta publique de Managed Multiagent Orchestration de Anthropic, présentée dans la section Orchestration multi-agents.⁷³ Les deux fournisseurs proposent désormais, au niveau multi-agents, le même compromis que celui décrit ci-dessous pour les agents individuels : le fournisseur exécute la boucle de délégation, mais vous renoncez à l’interface des hooks.

La bifurcation architecturale est désormais bien réelle :

Comment choisir : l’auto-hébergement reste adapté aux équipes qui disposent déjà de solides compétences en infrastructure, souhaitent maîtriser leurs skills et leurs hooks, ou optimisent en profondeur un workflow précis. Un harness géré convient aux équipes dépourvues d’ingénieurs plateforme dédiés, lorsque la rapidité de mise en œuvre prime sur la personnalisation ou lorsque les exécutions d’agents doivent résister de manière fiable à la fermeture d’un ordinateur portable sans que vous ayez à construire 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 son 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/ constitue une infrastructure personnelle qui s’applique à tous les projets. L’arborescence .claude/ de chaque dépôt est propre 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 en fonction du 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 à fournir des connaissances toujours accessibles à Claude. Les commandes slash 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, de la portée la plus large à la plus restreinte :⁴

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 de description est essentiel

Au début de la session, Claude Code extrait les champs name et description de chaque skill et les injecte dans le contexte de Claude. Lorsque vous envoyez un message, Claude s’appuie sur le raisonnement du modèle de langage pour déterminer si un skill est pertinent. Une analyse indépendante du code source de Claude Code confirme ce mécanisme : les descriptions des skills sont injectées dans une section available_skills du prompt système, puis le modèle utilise sa compréhension habituelle 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 que fait le skill (examiner le code à la recherche de types de problèmes précis), quand l’utiliser (examen de modifications, de PR ou analyse de la qualité) et les expressions déclencheuses (review, audit, check) que les utilisateurs saisissent naturellement.

Notez que l’activation automatique est un réglage, pas une règle absolue : depuis la v2.1.215, Claude n’invoque plus de lui-même les skills /verify et /code-review fournis — ils ne s’exécutent que sur invocation explicite. Il s’agit d’un recul délibéré par rapport à l’activation fondée sur la description pour les 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’ajuste dynamiquement à 1 % de la fenêtre de contexte, avec une valeur de repli de 8 000 caractères.⁴ Si vous avez de nombreux skills, veillez à ce que chaque description reste concise et placez le cas d’usage principal en premier. Vous pouvez remplacer ce budget à l’aide de la variable d’environnement SLASH_COMMAND_TOOL_CHAR_BUDGET,¹¹ mais mieux vaut raccourcir les descriptions et les rendre plus précises. Exécutez /context pendant une session pour vérifier si certains skills sont exclus.

Fichiers complémentaires et organisation

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

~/.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 à l’aide de liens relatifs. Claude lit ces fichiers à la demande lorsque le skill s’active. Limitez SKILL.md à moins de 500 lignes et placez la documentation de référence détaillée dans des fichiers complémentaires.¹²

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 coéquipiers récupèrent les modifications, ils obtiennent automatiquement le skill. Aucune installation, aucune configuration. C’est le moyen le 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 répertoires fait office 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 dans laquelle Claude puise automatiquement selon le contexte. Un développeur junior bénéficie ainsi de conseils de niveau senior sans avoir à les demander.

Les skills se combinent avec les hooks

Les skills peuvent définir dans leur frontmatter leurs propres hooks, qui ne s’activent que pendant leur exécution. Vous obtenez ainsi 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 philosophiques s’activent automatiquement via les hooks SessionStart, injectant des contraintes de qualité dans chaque session sans invocation explicite. Le skill apporte les connaissances. Le hook en impose l’application. Ensemble, ils forment une couche de politique.

Erreurs courantes avec les skills

Descriptions trop générales. Un skill git-rebase-helper qui s’active pour n’importe quel prompt lié à git (rebases, fusions, cherry-picks et même git status) pollue le contexte dans 80 % des sessions. Pour y remédier, rendez la description plus précise ou ajoutez disable-model-invocation: true afin d’exiger une invocation explicite via /skill-name.⁴

Trop de skills en concurrence pour le budget. Plus vous avez de skills, plus leurs descriptions se disputent le budget de contexte de 1 %. Si vous remarquez que certains skills ne s’activent pas, consultez /context pour repérer ceux qui sont exclus. Privilégiez un nombre réduit de skills bien décrits plutôt qu’une multitude de skills vagues.

Informations critiques enfouies dans les fichiers complémentaires. Claude lit immédiatement SKILL.md, mais n’accède aux fichiers complémentaires qu’en cas de besoin. Si une information critique se trouve dans un fichier complémentaire, Claude risque de ne pas la trouver. Placez directement les informations essentielles dans SKILL.md.⁴

Surface des skills de SDK (8 mai 2026)

Les harnesses auto-hébergés qui reposent 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, tandis que l’option dédiée fournit à Claude Code des informations plus structurées sur les skills disponibles. La version de CLI incluse dans la v0.1.77 est la v2.1.133.

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

Les skills ont toujours été chargés depuis le répertoire .claude/skills/ d’un projet. Claude Code v2.1.157 étend désormais ce répertoire aux plugins : un plugin placé dans .claude/skills/ se charge automatiquement sans aucun enregistrement sur une marketplace, et claude plugin init <name> y génère la structure d’un nouveau plugin avec le manifeste et SKILL.md déjà raccordés.⁵⁸ Cela comble l’écart entre les deux formes d’outillage de projet qui résidaient auparavant à des emplacements différents — d’un côté, un skill autonome directement versionné dans le dépôt ; de l’autre, un plugin regroupant un skill, des hooks et un serveur MCP, mais qui nécessitait auparavant une marketplace pour être installé. Conséquence pratique pour la conception d’un harness : l’outillage limité au projet n’a plus besoin de passer par un registre pour être distribué — écrivez-le, versionnez-le, et vos coéquipiers obtiendront la même surface avec git pull. Les plugins restent adaptés aux installations groupées (hooks + skills + serveurs MCP + agents dans un même ZIP) ; ce qui change, c’est qu’un projet n’a plus besoin de mettre en place une marketplace simplement pour charger un plugin depuis sa propre arborescence.

Masquer la surface intégrée comme mesure de gouvernance (8 juin 2026)

Les skills constituent des capacités, et toute capacité représente 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, workflows et commandes slash intégrés.⁶⁰ 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 ayant 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 cette option comme une liste d’autorisation d’outils : la configuration par défaut offre de vastes capacités, et la désactiver relève d’une décision de gouvernance, pas d’un simple réglage pratique.

.claude/skills imbriqués et résolution par proximité (16 juin 2026)

Claude Code v2.1.178 a rendu l’outillage de projet sensible à l’emplacement. Les skills présents dans des répertoires .claude/skills imbriqués se chargent désormais lorsque vous travaillez sur des fichiers situés sous ce répertoire, et plus seulement depuis la racine du dépôt ; en cas de conflit de noms, le skill imbriqué apparaît sous la forme <dir>:<name>, afin que les deux restent accessibles.⁶³ La même version a appliqué au reste de la surface du projet une résolution selon la proximité avec le répertoire de travail : lorsqu’un nom d’agent, de workflow ou de style de sortie entre en conflit entre plusieurs répertoires .claude/ imbriqués, celui qui se trouve le plus près du répertoire de travail l’emporte. Par ailleurs, l’enregistrement d’un workflow à la portée du projet cible le répertoire .claude/workflows/ existant le plus proche, au lieu de toujours viser la racine.⁶³ Dans un monorepo ou un dépôt composé de plusieurs dépôts, c’est ce qui distingue une surface globale unique et uniforme d’un outillage par package qui s’active en contexte : un répertoire services/api/.claude/skills/ peut contenir des skills propres à API, qui n’apparaissent que lorsque vous travaillez dans cette arborescence, sans entrer en conflit avec un skill du même nom dans services/web/.

Architecture des hooks

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

Événements disponibles

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

DirectoryAdded (v2.1.219) comble l’angle mort lié à l’ajout d’un espace de travail en cours de session. La liste des événements était restée stable depuis l’arrivée de MessageDisplay dans la v2.1.152 ; DirectoryAdded est le premier nouvel événement du cycle de vie depuis lors. Il se déclenche après que /add-dir — ou la requête de contrôle register_repo_root de SDK — a enregistré un nouveau répertoire de travail en cours de session.⁸⁴ L’angle mort qu’il comble était bien réel : jusqu’ici, un harness pouvait valider exhaustivement un espace de travail lors de SessionStart, puis voir un second dépôt s’y greffer sans qu’aucun hook ne se déclenche. Toute vérification effectuée sur l’espace de travail au démarrage — contrôles de confiance, recherches de secrets, règles de restriction des chemins dérivées de l’arborescence, chargement des politiques propres à chaque dépôt — doit être relancée ici, car l’ensemble des répertoires d’une session n’est plus figé au lancement. Cet événement est informatif et non bloquant : utilisez-le pour recalculer l’état et consigner la provenance, non comme un evidence gate ; si l’ajout d’un répertoire doit être absolument interdit, refusez-le dans les paramètres au lieu d’essayer d’y opposer un veto depuis un hook. La prise en charge côté SDK est arrivée dans la même version (TypeScript v0.3.219 ajoute DirectoryAdded aux événements du cycle de vie du protocole de contrôle), si bien que les harnesses hébergés par SDK le reçoivent au même titre que ceux de CLI.⁸⁵

Sémantique des codes de sortie

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

Configuration des hooks

Les hooks résident dans les fichiers de paramètres. Utilisez le niveau projet (.claude/settings.json) pour les hooks partagés et le 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 tool_name telles que Bash, Edit, Write, Read, Glob, Grep, aux noms d’outils MCP comme mcp__server__tool, ou à * pour tous les outils. Les noms simples et les listes séparées par | produisent 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 systématiquement 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) produisent une correspondance exacte au lieu d’établir accidentellement une correspondance avec une sous-chaîne : un hook ciblant un agent ou un serveur précis ne se déclenche donc plus pour chaque nom qui contient simplement cette chaîne ; pour couvrir tous les outils d’un serveur MCP dont le nom comporte un trait d’union, écrivez explicitement le motif mcp__brave-search__.*.⁶⁶ La v2.1.214 a appliqué la même rigueur aux motifs de chemins : dans une condition if: de hook, un motif dir/** à segment unique correspond désormais uniquement à <cwd>/dir, et non à chaque répertoire nommé dir dans toute l’arborescence ; écrivez **/dir/** si vous souhaitez réellement cibler n’importe quelle profondeur.⁷⁴ Comme pour le changement de la v2.1.195, ce correctif remplace une portée accidentellement large par une intention explicite ; auditez toutes les conditions de hooks qui dépendaient implicitement de l’ancien comportement à profondeur quelconque.

Protocole d’entrée/sortie des hooks

Les hooks reçoivent sur stdin du JSON contenant le contexte complet :

{
  "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, d’injecter du contexte ou de prendre des décisions d’autorisation. Utilisez l’enveloppe hookSpecificOutput : l’ancien format de premier niveau decision/reason est obsolète 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, demandez-vous : de quel type de garantie ai-je besoin ?¹⁴

Les garanties de formatage assurent la cohérence a posteriori. Les hooks PostToolUse sur Write/Edit exécutent votre outil de formatage après chaque modification de fichier. La sortie du modèle importe peu, puisque l’outil de formatage 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 l’exécution préalable d’actions dangereuses. Les hooks PreToolUse sur Bash examinent les commandes et bloquent les motifs 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 autres que les commandes shell

Claude Code prend en charge cinq types de hooks :¹³

Les hooks de commande (type: "command") exécutent des scripts shell. Ils sont rapides, déterministes et n’entraînent aucun 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.

Prompt hooks (type: "prompt") envoient un prompt à tour unique à un modèle Claude rapide. Le modèle renvoie { "ok": true } pour autoriser l’action ou { "ok": false, "reason": "..." } pour la bloquer. Utilisez-les pour les évaluations nuancées qu’une expression régulière ne peut pas exprimer.

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

{
  "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, les données d’entrée des agent hooks incluent subagent_type, ce qui permet à un hook partagé de distinguer l’exécution d’un security-reviewer de celle d’un explorer ou d’un worker générique sans devoir le déduire du texte du prompt.⁴⁹

HTTP hooks (type: "http") envoient les données d’entrée JSON de l’événement à une URL au moyen d’une requête POST et reçoivent une réponse JSON. 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 comme les notifications et la journalisation :¹³

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

Utilisez le mode asynchrone pour les notifications, la télémétrie et les sauvegardes. Ne l’utilisez jamais pour le formatage, la validation ou toute opération qui doit être terminée avant l’action suivante.

Des dispatchers plutôt que des hooks indépendants

Exécuter 7 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 qui écrivent simultanément dans le même fichier d’état JSON tronqueront le contenu JSON. Tous les hooks en aval qui analysent ce fichier cesseront alors de fonctionner.²

La solution : un dispatcher par événement, qui exécute les hooks séquentiellement à partir des données stdin mises 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ébogage des hooks

Voici 5 techniques pour déboguer les hooks qui échouent silencieusement :¹⁴

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

Diffusion des événements de hook côté SDK

Les harnesses auto-hébergés reposant 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 au lieu 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 des outils. Ce fonctionnement reflète l’option includeHookEvents du SDK TypeScript ; la version de CLI intégrée est passée à v2.1.129 dans la même mise à jour.

Le modèle fondé sur le flux d’événements convient lorsque votre harness s’exécute déjà dans Python et que vous souhaitez intégrer les signaux de hook au même flux de contrôle que la sortie du modèle. Le contrat des hooks de scripts shell — codes de sortie, données JSON sur stdin et dispatchers — reste la solution adaptée aux harnesses qui combinent plusieurs outils, partagent des hooks entre Claude Code et Codex, ou ont besoin de la sémantique des codes de sortie pour effectuer un blocage.

La série de juillet 2026 du SDK TypeScript (v0.3.205–v0.3.208) a renforcé le caractère contractuel du protocole diffusé lui-même.⁷⁰ Les interruptions renvoient désormais des reçus typés : une interruption indique quels messages de la file d’attente sont encore en attente au moyen des UUID still_queued, tandis que les sessions annoncent la capacité interrupt_receipt_v1 dans system/init. Un coordinateur peut ainsi distinguer une « interruption prise en compte » d’une « interruption arrivée trop tard pour un message déjà en cours de traitement ». Les frames command_lifecycle signalent pour chaque message les états queued/started/completed/cancelled/discarded — première réponse native à la question « qu’est-il arrivé au message que j’ai envoyé ? », sans devoir l’inférer à partir de la transcription. Des surfaces plus modestes ont également été ajoutées : un type AgentToolCompletedOutput pour les payloads d’achèvement des subagents, et les callbacks canUseTool peuvent désormais renvoyer {behavior: 'allow'} sans champ updatedInput.

Une ligne de cette série constitue un seuil minimal de sécurité, et non une fonctionnalité : la v0.3.208 a corrigé un problème où l’abandon demandé par l’appelant pendant l’attente d’un hook était interprété comme une réussite du hook — ce qui signifiait qu’un outil soumis à un hook PreToolUse pouvait s’exécuter après l’abandon par l’appelant.⁷⁰ Si votre harness utilise des hooks côté SDK comme permission gate et s’appuie sur l’abandon pour annuler le travail en cours, considérez la v0.3.208 comme la version minimale ; dans les versions antérieures, « aborted » ne signifiait pas nécessairement « blocked ». La v0.2.127 de Python (24 juillet 2026) constitue le deuxième contournement de ce type en un mois : query() fermait stdin dès la première frame result alors que des subagents continuaient de s’exécuter en arrière-plan. 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 ouvert aux limites du cycle de vie — abandon, arrêt, fermeture du flux — lorsque le transport disparaît avant la réception du verdict du hook. Cet échec reste silencieux, car un hook contourné ressemble exactement à un hook qui a donné son accord. Épinglez les versions minimales des 2 SDK et conservez la couche de hooks shell comme mécanisme d’application dont vous pouvez démontrer l’efficacité.

Effort et provenance des sessions (7-8 mai 2026)

Deux ajouts aux versions v2.1.132 et v2.1.133 de Claude Code fournissent aux hooks et aux sous-processus de meilleurs signaux sur leur contexte d’exécution :³⁸³⁹

• effort.level dans les données d’entrée du hook. Les hooks reçoivent désormais un champ JSON effort.level dans les mêmes données d’entrée que tool_input et session_id. Cette valeur est également exportée dans la variable d’environnement $CLAUDE_EFFORT, ce qui permet aux commandes Bash de la lire sans analyser les données JSON. Utilisez-la pour ajuster le coût des hooks en fonction du niveau d’effort : ignorez les validations coûteuses avec low et exécutez l’intégralité du security gate avec xhigh ou max.
• Variable d’environnement CLAUDE_CODE_SESSION_ID dans les sous-processus Bash. Les sous-processus de l’outil Bash ont désormais accès à la même valeur session_id que les hooks, exposée sous le nom CLAUDE_CODE_SESSION_ID. Cela comble le déficit 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 ceux des hooks.

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

autoMode.hard_deny et correctifs des hooks/plugins dans la v2.1.136 (8 mai 2026)

La v2.1.136 de Claude Code a ajouté un nouveau niveau hard-deny au mode automatique et corrigé un ensemble de problèmes liés aux plugins et à MCP qui affectaient les harnesses exécutés sur de longues périodes :⁴⁰ - settings.autoMode.hard_deny. Règles du classificateur du mode automatique qui bloquent sans condition, indépendamment de l’intention de l’utilisateur ou des exceptions d’autorisation. Elles se placent au-dessus des mécanismes existants de correspondance d’autorisation et de refus, 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 générale dans ses paramètres personnels. - autoMode.classifyAllShell (v2.1.193). Par défaut, le classificateur du mode automatique examine uniquement les commandes shell correspondant à des motifs d’exécution de code arbitraire. Ce paramètre fait passer chaque commande Bash/PowerShell par le classificateur — la posture de couverture maximale pour un harness gouverné — et la même version affiche les raisons du refus dans la transcription, la notification et /permissions, transformant ainsi les blocages silencieux en décisions auditables. Codex a renforcé le mécanisme équivalent dans la version v0.142.2 : les commandes PowerShell contenant des régions AST exécutables que son classificateur de sécurité ne peut pas inspecter nécessitent désormais une approbation au lieu d’être autorisées silencieusement.⁶⁶ - Le ask d’un hook impose un seuil minimal au classificateur (v2.1.211). La question de la priorité entre les hooks et le mode automatique est désormais tranchée : lorsqu’un hook PreToolUse renvoie une décision d’autorisation ask, le résultat final ne peut pas être moins restrictif qu’une demande de confirmation — le mode automatique ne peut pas la transformer en autorisation pour les commandes Bash exécutées hors sandbox.⁶⁹ Pour un harness gouverné, il s’agit du niveau de garantie qui manquait : le ask d’un hook constitue un arrêt déterministe avec intervention humaine, qui subsiste même avec des postures d’autorisation entièrement automatiques. Utilisez ask (et pas seulement les blocages avec un code de sortie 2) pour les opérations qui nécessitent une décision humaine plutôt qu’un refus. - Le modèle du classificateur est épinglé pour chaque session (v2.1.210). Le classificateur du mode automatique utilise Sonnet 5 par défaut et reste épinglé pendant toute la session ; changer de modèle en cours de session ne modifie donc plus celui qui effectue les classifications d’autorisation.⁶⁹ La cohérence des classifications est une propriété de gouvernance ; ce changement é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 est inclus dans la version v2.1.136. Si vous avez constaté que « le serveur MCP X a disparu en cours de session », c’en était la cause. - Perte du refresh-token OAuth de MCP lors d’actualisations simultanées. Les utilisateurs disposant de plusieurs serveurs MCP distants ne devraient plus avoir à s’authentifier de nouveau chaque jour. Les écritures simultanées lors de l’actualisation s’écrasaient mutuellement. - Le mode plan bloque désormais correctement les écritures de fichiers. Une règle d’autorisation Edit(...) correspondante contournait la protection contre l’écriture du mode plan. Celui-ci est désormais appliqué indépendamment des règles d’autorisation. - Les hooks Stop et UserPromptSubmit des plugins n’échouent plus en cours de session. Le nettoyage du cache supprimait des fichiers de versions de plugins encore utilisés par la session en cours, ce qui interrompait spécifiquement ces deux événements de hook. Le correctif maintient épinglées les versions en cours d’utilisation. - Entrée skills dans plugin.json. Définir skills masquait le dossier skills/ par défaut du plugin. L’entrée se combine désormais correctement, et la faire pointer vers un chemin de fichier déclenche une erreur explicite au lieu d’échouer silencieusement. - Obsolescence des variables d’environnement du hook SessionStart dans CLAUDE_ENV_FILE. Les variables exportées par les hooks SessionStart via CLAUDE_ENV_FILE devenaient obsolètes après /resume ou /clear. Ce problème est corrigé dans la version v2.1.136. Les sessions rechargent désormais le fichier d’environnement lors de ces événements.

Pour les harnesses de gouvernance, les éléments importants sur le plan opérationnel sont autoMode.hard_deny (nouveau levier) et le correctif de disparition de MCP (une défaillance silencieuse qui interrompait les longues sessions). Tout le reste relève d’améliorations de confort.

Arguments structurés des hooks et poursuite après un blocage (11 mai 2026)

La version v2.1.139 de Claude Code a ajouté deux détails concernant les hooks qui comptent 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 liées à l’échappement et aux injections.

Utilisez continueOnBlock lorsqu’un hook PostToolUse doit transmettre le motif de son rejet à Claude et poursuivre l’itération au lieu d’interrompre le flux. Considérez-le comme une fonctionnalité améliorant l’expérience de l’opérateur, et non comme un moyen de contourner la sécurité. Une gate bloquante doit toujours empêcher le résultat dangereux.

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, et non du répertoire de travail du processus ayant 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 — un serveur respectant les roots de MCP suit ainsi la véritable structure d’un espace de travail multirépertoire au lieu de supposer l’existence d’un unique répertoire de projet.⁶⁸

La version v2.1.140 de Claude Code est principalement une mise à jour 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, résout les cas limites où disableAllHooks et allowManagedHooksOnly ne se combinaient pas correctement entre les différents niveaux de paramètres, et empêche les boîtes de dialogue d’autorisation d’exposer des variables d’environnement non prévues renvoyées par les résultats des hooks.⁴⁹ Les modèles de gouvernance existants de cette section deviennent ainsi plus fiables ; aucune nouvelle architecture de hooks n’est nécessaire.

La version v2.1.141 de Claude Code ajoute un champ terminalSequence à la sortie des hooks pour les notifications du bureau, les titres de fenêtres et les alertes sonores en l’absence de terminal de contrôle.⁵⁰ Considérez cela comme un mécanisme de signalement destiné à l’opérateur, et non comme un moyen d’application des règles. Les gates de sécurité et de qualité doivent toujours communiquer les échecs par le contrat de blocage habituel : une sortie structurée du hook associée au comportement de sortie qui empêche l’action dangereuse. La même version ajoute claude agents --cwd <path> pour limiter Agent View à un seul répertoire, CLAUDE_CODE_PLUGIN_PREFER_HTTPS pour l’installation de plugins dans les environnements dépourvus de clés GitHub SSH, et ANTHROPIC_WORKSPACE_ID pour les règles de fédération d’identité des workloads couvrant plusieurs espaces de travail.⁵⁰ Ce sont des détails d’architecture pour les harnesses d’équipe : des vues opérationnelles plus ciblées, moins d’hypothèses concernant l’installation des plugins et un périmètre explicite pour les tokens d’entreprise.

La version v2.1.142 de Claude Code est plus importante pour l’orchestration des sessions en arrière-plan que pour la sémantique des hooks.⁵¹ claude agents peut désormais lancer des sessions en arrière-plan avec des flags explicites pour le répertoire, les paramètres, MCP, les plugins, les autorisations, le modèle et l’effort, sans dépendre de l’état d’un wrapper. Lors de cette version, Opus 4.7 est devenu le modèle par défaut du mode rapide, avec CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE=1 pour épingler Opus 4.6 dans un harness dont la dépendance à son comportement a été mesurée — depuis la version v2.1.219, Opus 4.7 n’est plus disponible en mode rapide et /fast s’applique à Opus 5 et Opus 4.8.⁸⁴ La découverte de SKILL.md à la racine des plugins et la visibilité des LSP fournis par les plugins réduisent les ambiguïtés de packaging. Les correctifs apportés à MCP_TOOL_TIMEOUT, aux worktrees préexistants des sessions en arrière-plan, à la mise en veille et au réveil du daemon, au nettoyage après mise à niveau et au cache des plugins comblent des lacunes de fiabilité qui, autrement, pourraient passer pour des bugs d’orchestration.

Pilotage par les hooks Stop, autorité intersessions et multi-agent v2 (juin 2026)

Quatre changements du début juin comptent pour la conception des harnesses et des systèmes multi-agents.⁵⁹

Les hooks Stop/SubagentStop disposent désormais d’un canal de pilotage. Depuis la version v2.1.163 de Claude Code, un hook Stop ou SubagentStop peut renvoyer hookSpecificOutput.additionalContext pour transmettre un retour à Claude et poursuivre l’itération, sans que la réponse soit signalée comme une erreur de hook. Auparavant, le seul véritable levier d’un hook Stop était le blocage avec un code de sortie 2, qui apparaît comme une erreur et compte dans la limite des blocages consécutifs. Pour un harness doté d’une quality loop, il s’agit d’un mécanisme plus propre : lorsqu’un hook Stop détecte que « vous avez déclaré avoir terminé, mais les tests échouent », il peut désormais injecter « voici ce qui échoue encore, continuez » au lieu de provoquer un blocage ferme. Réservez le blocage aux véritables conditions d’arrêt et utilisez additionalContext pour indiquer « ce n’est pas encore terminé, voici pourquoi ».

Les messages intersessions ne véhiculent plus une autorité empruntée. La version v2.1.166 a renforcé le cas multisession : les messages relayés via SendMessage depuis une autre session Claude ne véhiculent plus l’autorité de l’utilisateur d’origine. La session destinataire refuse donc les demandes d’autorisation relayées, et le mode automatique les bloque. Si votre orchestration permet aux agents de communiquer entre eux, traitez chaque message entrant comme une donnée non fiable, et non comme une instruction authentifiée. Il s’agit du même principe que celui appliqué par la section sur la sécurité aux sorties des outils, étendu aux échanges inter-agents. Depuis la version v2.1.199, Claude Code détecte également les erreurs d’acheminement de SendMessage dues au partage d’un même nom par deux agents et émet un avertissement — un complément de fiabilité à cette limite d’autorité, car l’envoi d’un message au mauvais agent portant le même nom constitue une catégorie distincte de bug d’orchestration. La résilience des modèles est devenue un paramètre de premier plan. Le paramètre fallbackModel permet désormais d’enchaîner jusqu’à trois modèles de secours, essayés dans l’ordre lorsque le modèle principal est surchargé ou indisponible. En cas d’erreur API inattendue et normalement non réessayable, un tour est automatiquement relancé une fois avec le modèle de secours. Pour un harness autonome de longue durée, une panne temporaire du modèle principal entraîne ainsi une dégradation progressive plutôt que l’abandon de l’exécution. claude agents --json s’est également enrichi d’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 progrès en matière d’observabilité pour tout coordinateur qui interroge régulièrement une flotte d’agents.

Un mode sécurisé pour la gouvernance en environnement isolé et le dépannage. Claude Code v2.1.169 ajoute un flag --safe-mode (ainsi que la variable d’environnement correspondante CLAUDE_CODE_SAFE_MODE) qui lance une session en désactivant simultanément toutes les personnalisations : CLAUDE.md, plugins, skills, hooks et serveurs MCP.⁶⁰ C’est l’inverse du harness — un environnement volontairement vierge. Utilisez-le pour répondre à la question que finit par se poser tout opérateur : « ce comportement vient-il du modèle ou d’un élément que j’ai configuré ? » Lorsqu’un hook se déclenche à tort, qu’un skill s’active alors qu’il ne le devrait pas ou qu’un serveur MCP empoisonne le contexte, --safe-mode vous fournit une base de référence vide et connue avec laquelle comparer les résultats. Il s’agit également d’un mécanisme de gouvernance : un moyen d’exécuter le modèle brut, sans aucune des autorisations persistantes que votre harness lui accorde habituellement, ce qui compte lorsque vous devez reproduire un résultat sans que la moindre structure définie par l’opérateur ne l’influence.

Remarque sur les niveaux de modèles. Depuis Claude Code v2.1.197 (30 juin 2026), Claude Sonnet 5 est le modèle livré par défaut pour les nouvelles sessions — contexte natif de 1 million de tokens, tarif promotionnel de 2 $/10 $ par million de tokens jusqu’au 31 août — en remplacement d’Opus 4.8 comme choix prêt à l’emploi. Ce guide considère Opus 5 (claude-opus-5) comme le modèle agentique recommandé par défaut : celui sur lequel exécuter les harnesses autonomes, sauf choix contraire délibéré, car les boucles d’agents de longue durée et à fort enjeu sont précisément les situations où la profondeur de raisonnement d’Opus justifie son coût. Opus 5 est sorti le 24 juillet 2026 en tant que nouvel Opus par défaut dans Claude Code v2.1.219 — contexte de 1 million de tokens, 5 $/25 $ par million de tokens (le même prix que l’Opus 4.8 qu’il remplace), mode rapide à 10 $/50 $ pour une vitesse environ 2,5 fois supérieure à celle du mode par défaut — et Anthropic indique qu’il fait plus que doubler le score d’Opus 4.8 sur Frontier-Bench v0.1, tout en se situant à moins de 0,5 % du score de Fable 5 sur CursorBench 3.2 pour la moitié du coût.⁸⁴⁸⁷ Même prix, capacités accrues et un modèle que Anthropic décrit comme « bien meilleur pour vérifier son travail et procéder à des itérations minutieuses » : cette rare mise à niveau n’a besoin d’aucun argument économique pour les tâches de harness ; la migration depuis la version 4.8 se résume à modifier un identifiant. Passez à Sonnet 5 pour les tâches sensibles aux coûts ou à haut débit, lorsque son rapport vitesse-intelligence l’emporte. Au-dessus d’Opus se trouve Claude Fable 5 (claude-fable-5), lancé le 9 juin 2026 — un nouveau niveau présenté 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.⁶⁰ Réservez délibérément ce niveau supérieur aux décisions pour lesquelles la profondeur brute du raisonnement justifie son coût, plutôt que d’en faire le paramètre général de toute une flotte. Le passage à Opus 5 entraîne deux changements pratiques : Opus 4.7 n’est plus disponible en mode rapide (/fast s’applique désormais à Opus 5 et Opus 4.8), et le modèle de secours Fable 5 du classificateur en mode automatique — « le meilleur modèle Opus disponible » depuis v2.1.176 — correspond désormais à Opus 5.⁸⁴

Codex a lancé multi-agent v2. Codex CLI v0.137.0 laisse à chaque thread le choix du runtime, propose des valeurs par défaut plus propres pour les relances et les métadonnées des agents créés (hide_spawn_agent_metadata vaut désormais true par défaut) et transmet 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 vaut 6 par défaut, agents.max_depth vaut 1 par défaut). La même version ajoute une extension v1 des skills, avec résolution du catalogue de skills à chaque tour et nouveaux événements contributeurs du cycle de vie au démarrage d’un thread et en cas d’erreur pendant un tour. Elle réduit ainsi l’écart avec la surface de hooks et de skills de Claude Code, tout en conservant par défaut la posture de sécurité fondée sur l’isolation du kernel. Codex v0.138.0 à v0.139.0 a ensuite renforcé multi-agent v2 pour la production : les charges utiles des messages entre agents sont désormais chiffrées, un catalogue v2 de configurations d’agents associé à un LRU de résidence gère les agents qui restent en mémoire, et la concurrence est calculée selon les exécutions actives plutôt que le nombre de threads créés, si bien que les agents inactifs n’occupent plus d’emplacement.⁶¹ Le cycle de vie API a également gagné en maturité : close_agent a été renommé interrupt_agent (v0.139.0) pour indiquer qu’il interrompt un agent en cours d’exécution au lieu de simplement fermer un handle. Par ailleurs, les avertissements de démarrage MCP émis par un subagent restent désormais limités au thread propriétaire au lieu d’être dupliqués dans la transcription du parent.⁶¹ Pour quiconque développe une orchestration côté Codex, ces éléments font toute la différence entre une démonstration et une flotte : transport chiffré des messages, résidence limitée, concurrence fondée sur les exécutions et avertissements qui ne franchissent pas la frontière des threads. Codex v0.140.0 a ensuite ouvert une interface entre les outils : /import importe sélectivement la configuration initiale, la configuration du projet et les conversations récentes de Claude Code dans Codex, tandis que les sessions peuvent désormais être supprimées définitivement (codex delete / /delete, avec des protections de confirmation).⁶⁴ /import constitue la première reconnaissance officielle du fait que les opérateurs passent d’un harness à l’autre — la configuration créée pour l’un d’eux n’y est désormais plus enfermée.

Mémoire et contexte

Toute conversation avec une IA s’inscrit dans une fenêtre de contexte limitée. À mesure que la conversation s’allonge, le système compresse les échanges précédents pour faire place au nouveau contenu. Cette compression entraîne des pertes. Les décisions architecturales consignées au 3e échange peuvent avoir disparu au 15e.⁹

Les trois mécanismes d’effondrement des conversations à plusieurs échanges

L’étude de 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 limites 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 schémas récurrents d’une session à l’autre. Lorsque vous découvrez que ((VAR++)) échoue avec set -e dans bash lorsque VAR vaut 0, vous le consignez. Trois sessions plus tard, face à un cas limite similaire sur un entier dans Python, l’entrée de MEMORY.md fait ressortir ce schéma.¹⁵

Auto Memory (v2.1.32+) : Claude Code enregistre et rappelle automatiquement le contexte du projet. Pendant que vous travaillez, Claude écrit ses observations dans ~/.claude/projects/{project-path}/memory/MEMORY.md. Au début de la session, Auto Memory charge les 200 premières lignes dans votre prompt système. Veillez à rester concis et ajoutez des liens vers des fichiers thématiques distincts pour les notes détaillées.⁶ Depuis la v2.1.210, toute écriture dans MEMORY.md qui dépasse la limite de taille déclenche une erreur au lieu d’être silencieusement tronquée⁶⁹ : l’échec apparaît au moment de l’écriture, au lieu de se traduire par des entrées de mémoire disparues sans avertissement. Si votre harness automatise l’écriture dans la mémoire, gérez cette erreur ; la plateforme vous indique que le fichier doit être réorganisé, et non qu’il faut réessayer.

Privilégier la sélection de la mémoire à son volume (mai 2026) : un récent préprint arXiv sur la coopération entre agents LLM présente l’élargissement du rappel comme une source potentielle d’échec : dans les expériences des auteurs, un historique visible plus long a dégradé la coopération dans 18 des 28 configurations de modèles et de jeux.⁴⁸ Considérez ce résultat comme un avertissement de conception, et non comme une loi établie. La règle de production est déjà suffisamment claire : gardez MEMORY.md concis, renvoyez vers les détails au moyen de liens et placez dans les transmissions des synthèses directement exploitables pour prendre des décisions. Les transcriptions brutes, les journaux d’outils et les longs flux de rappel doivent résider dans un stockage interrogeable, sans ê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 dans le contexte tout en préservant les décisions clés, le contenu des fichiers et l’état de la tâche.¹⁵

Quand effectuer une compaction : - Après avoir terminé une sous-tâche distincte (fonctionnalité implémentée, bug corrigé) - Avant de commencer à travailler sur une nouvelle partie de la base de code - Lorsque Claude commence à se répéter ou à oublier le contexte antérieur - Environ toutes les 25 à 30 minutes lors des 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 du prompt. Elle déplace une session vers un nouveau répertoire de travail en cours d’exécution sans rompre le cache accumulé au fil de l’échange.⁶⁰ Auparavant, changer de répertoire imposait de lancer une nouvelle session avec un cache froid. Lorsqu’une longue session passe d’un dépôt à un dépôt voisin — une situation courante dans les monorepos et les environnements multiservices — /cd préserve l’intégralité du coûteux préfixe mis en cache tout en réorientant le contexte du système de fichiers.

Stratégie 3 : transmissions entre sessions

Pour les tâches réparties sur plusieurs sessions, créez des documents de transmission qui consignent l’intégralité de l’état :

## 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 Status/Files/Decision/Blocked/Next fournit à la session suivante l’intégralité du contexte pour un coût minimal en tokens. En démarrant une nouvelle session avec claude -c (continue) ou en lisant le document de transmission, vous pouvez passer directement à l’implémentation.¹⁵

Stratégie 4 : itérations avec un contexte neuf (la boucle Ralph)

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

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

Comparaison avec une seule longue session :

Minute 0:   [200K tokens available] -> productive
Minute 30:  [150K tokens available] -> somewhat productive
Minute 60:  [100K tokens available] -> degraded
Minute 90:  [50K tokens available]  -> significantly degraded
Minute 120: [compressed, lossy]     -> errors accumulate

L’approche consistant à renouveler le contexte à chaque itération entraîne un surcoût de 15 à 20 % pour l’étape d’orientation (lecture des fichiers d’état, analyse de l’historique git), mais offre l’intégralité des ressources cognitives à chaque itération.¹⁶ Voici le bilan coûts-avantages : 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 : sélection gérée de la mémoire (Dreaming)

Les Managed Agents de Claude proposés par Anthropic ont ajouté Dreaming en Research Preview le 6 mai 2026.³⁵ Selon Anthropic : « Dreaming est un processus planifié qui examine les sessions et les espaces de mémoire de votre agent, en extrait des schémas récurrents et sélectionne les souvenirs afin que vos agents s’améliorent au fil du temps. »³⁵

Dreaming s’exécute en arrière-plan entre les sessions, sans intervenir dans le chemin critique. Il complète le système de fichiers comme mémoire au lieu de le remplacer : votre fichier MEMORY.md reste le support essentiel ; Dreaming écrit des entrées de mémoire sélectionnées dans l’espace de mémoire des Managed Agents, que l’agent lit au début de la session. Les deux modèles coexistent dans les harnesses qui combinent un état autohébergé dans le système de fichiers avec une sélection gérée côté service.

Dreaming étant en Research Preview, son comportement peut évoluer. Les modèles de transmission entre sessions et de CLAUDE.md décrits ci-dessus restent le mécanisme de mémoire faisant autorité pour les harnesses autohébergés.

Les anti-patterns

Lire des fichiers entiers lorsque vous n’avez besoin que de 10 lignes. La lecture d’un seul fichier de 2 000 lignes consomme entre 15 000 et 20 000 tokens. Utilisez des décalages de lignes : Read file.py offset=100 limit=20 permet d’économiser l’immense majorité de ce coût.¹⁵

Conserver des sorties d’erreur détaillées dans le contexte. Après le débogage d’un bug, votre contexte contient plus de 40 traces de pile issues des tentatives infructueuses. Une seule commande /compact après la correction du bug permet de supprimer ce poids mort.

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

Patterns de subagents

Les subagents sont des instances spécialisées de Claude qui gèrent des tâches complexes de manière autonome. Ils démarrent avec un contexte vierge (sans pollution provenant de la conversation principale), 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 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 d’endommager la base de code.

L’isolation n’existe que si la frontière 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 doit 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 connexe 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 un worktree s’applique donc aux worktrees voisins 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 à cette expérience — 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 bugs à celui de mécanisme réellement applicable.⁷⁴ La correction de la v2.1.210 empêchait les subagents de worktree de modifier le checkout principal par une invocation git ordinaire, mais git propose lui-même des redirections explicites — git -C <path>, --git-dir et les variables d’environnement GIT_DIR/GIT_WORK_TREE — qu’un subagent isolé dans un worktree pouvait encore 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 des workflows et des tâches planifiées de suivre un lien symbolique placé dans .claude vers une cible extérieure au projet, et contraint /rewind à refuser de traverser les liens symboliques et les liens physiques. Ces quatre corrections suivent le même principe : une frontière d’isolation doit résister aux redirections délibérées — substitutions de l’environnement git, implantation de liens symboliques — et pas seulement aux comportements 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 Recursion Guard

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 pattern du recursion guard 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 à la profondeur 3), mais ne tiennent pas compte de la largeur : 23 agents à la profondeur 1 restent à la « profondeur 1 ». Un budget de lancement comptabilise le nombre total d’enfants actifs par parent, plafonné à une valeur maximale configurable. Le modèle budgétaire correspond au véritable mode de défaillance (un nombre total excessif d’agents), plutôt qu’à une mesure indirecte (un nombre excessif 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 allant jusqu’à 5 niveaux — alors que la délégation était auparavant limitée de fait à un seul niveau.⁶² Ce comportement s’est maintenu 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 adopté un compromis : « Les subagents peuvent désormais lancer par défaut des subagents imbriqués jusqu’à une profondeur de 3 (contre 1 auparavant) ; définissez CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1 pour désactiver l’imbrication. »⁸⁴ Cinq, puis un, puis trois — les deux derniers changements en l’espace de trois jours.

La bonne conclusion n’est pas que l’un de ces nombres serait juste. C’est que la plateforme cherche encore la bonne valeur par défaut, ce qui fait de « la valeur livrée » un mauvais choix à hériter pour un harness. Traitez 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 pour la plupart des orchestrations — afin qu’une mise à niveau ne puisse pas modifier discrètement la profondeur de délégation de votre parc d’agents. Malgré ces revirements, l’argument de fond reste inchangé : les chaînes d’agents déléguant à d’autres agents consomment du contexte et des tokens plus vite qu’elles ne produisent de résultats. La profondeur est un risque à budgétiser, pas une fonctionnalité à rechercher. Le recursion guard ci-dessus empêche un arbre profond de s’étendre 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 faille de gouvernance correspondante : 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. Grâce à cette évaluation préalable, le recursion guard et le modèle d’autorisations se rejoignent enfin : un enfant ne peut pas 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 permet d’ajuster cette valeur, /clear réinitialise le compteur), et WebSearch est limité à 200 appels par session (CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION).⁶⁹ Le pattern du budget de lancement, documenté dans cette section sous forme de scripts utilisateur depuis la v1.0, est désormais fourni par la plateforme — ce qui valide le modèle budgétaire face au 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 limites natives sont des fusibles destinés aux boucles réellement incontrôlées, 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 comportement réel attendu de votre orchestration ; laissez la limite de la plateforme arrêter ce qui parvient à lui échapper.

L’ensemble des garde-fous natifs couvre désormais quatre axes. Trois d’entre eux renforcent exactement 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 ajoute un quatrième axe généralement absent des garde-fous utilisateur : la largeur d’orchestration, c’est-à-dire le nombre d’agents qu’un même workflow planifié peut contenir. Elle est livrée sous forme d’une recommandation par défaut visant « moins de 15 agents » et peut être configurée depuis n’importe quel fichier de paramètres au moyen de workflowSizeGuideline (voir la section Workflow Tool ci-dessous). Le pattern du budget de lancement est désormais renforcé sur chacun des axes pour lesquels il a été conçu, plus un autre qui ne faisait pas partie de sa conception initiale.

La remarque sur le calibrage s’applique toujours, mais de manière inégale. Les limites 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 arrêter une boucle incontrôlée plutôt que pour structurer une architecture. La recommandation de largeur est le premier nombre natif comparable à un véritable budget : 15 agents par workflow se trouvent juste à côté des 12 de ce guide. Adopter la valeur par défaut de la plateforme ne vous coûte donc rien, tandis que la contester suppose d’avoir une véritable raison. Définissez les trois fusibles sur des valeurs que vous pouvez défendre ; définissez la recommandation de largeur en fonction de la forme de l’orchestration que vous aviez l’intention de construire.

Agent Teams (Research Preview)

Les Agent Teams coordonnent plusieurs instances de Claude Code qui travaillent de façon indépendante, communiquent grâce à une boîte aux lettres et à une liste de tâches partagées, et peuvent remettre en question les conclusions des autres :⁵

Activez cette fonctionnalité 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 Research Preview lancée avec claude agents, qui affiche sur un même écran les sessions Claude Code en cours, bloquées et terminées.⁴²⁴³ La documentation officielle la présente comme un moyen de lancer et gérer de nombreuses sessions, de voir ce que fait chacune d’elles et de repérer celles qui nécessitent l’intervention d’un opérateur.⁴³ Le travail multi-agent bénéficie ainsi d’une vue opérationnelle que les synthèses finales ne peuvent pas offrir.

Utilisez Agent View lorsque vous faites évoluer un pattern de subagent ou d’équipe : vérifiez quelles sessions sont bloquées, lesquelles sont encore actives et si la répartition du travail correspond à l’architecture prévue. Ne considérez pas cette interface comme une preuve de qualité. Elle fournit de l’observabilité ; les tests, les review gates 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, pas comme un substitut aux contrôles déterministes. Cette commande aide un 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 appuyés sur des commandes ou des scripts lorsque leur échec doit être bloquant.

Workflow Tool (v2.1.147+)

La v2.1.147 de Claude Code ajoute un Workflow tool désactivé par défaut pour l’orchestration multi-agent déterministe. Activez-le avec CLAUDE_CODE_WORKFLOWS=1.⁵² Sur le plan architectural, cette évolution est importante, car elle fournit à Claude Code une primitive d’orchestration native pour des flux qui nécessitaient auparavant des scripts de dispatch 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 ne remplace pas votre modèle de sécurité. Conservez les hooks PreToolUse et PostToolUse comme couche de blocage, maintenez des budgets de lancement ou d’étapes de workflow pour empêcher une largeur incontrôlée, gardez l’état du système de fichiers auditable et placez les rapports de preuves finaux en dehors de l’auto-évaluation du modèle. En pratique : utilisez Workflow pour définir la forme de l’orchestration ; utilisez les hooks, les tests et les review gates pour établir la vérité.

Les workflows dynamiques intègrent désormais une recommandation concernant leur largeur (v2.1.219). Par défaut, les workflows dynamiques adoptent une recommandation de taille moyenne — « viser moins de 15 agents » — tandis que d’autres tailles et une option sans restriction sont disponibles sous Dynamic workflow size dans /config. La recommandation actuelle apparaît dans la ligne d’état du workflow en cours.⁸⁴ Ce nombre est indicatif et non contraignant ; il oriente le planificateur sans bloquer un plan large. Son mécanisme de distribution justifie sa configuration : la nouvelle clé de paramètres workflowSizeGuideline peut être définie depuis n’importe quel fichier de paramètres — y compris les paramètres gérés et ceux du projet — et figure dans les types de paramètres TypeScript SDK depuis la v0.3.219. La largeur d’orchestration peut ainsi être normalisée par une équipe ou une organisation, au lieu d’être redécouverte par chaque opérateur.⁸⁵ Définissez-la au niveau du projet pour refléter la décomposition réelle du travail dans votre base de code. Deux remarques pour les opérateurs : la ligne correspondante de /config se masque lorsqu’un fichier de paramètres impose la valeur. C’est le comportement approprié, mais il peut donner l’impression que le paramètre manque si vous n’en connaissez pas la raison. Par ailleurs, puisque la recommandation oriente le planificateur plutôt qu’elle ne bloque l’exécution, elle relève de la forme, pas de la sécurité. Le plafond de lancement reste chargé de contenir une largeur incontrôlée.

Le cadre à retenir est qu’il s’agit d’un quatrième axe de garde-fou natif — la largeur d’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 a calibré sur une taille de travail plausible plutôt que comme un fusible contre les emballements. Quinze agents par workflow représentent le même ordre de grandeur que le budget de délibération de 12 agents utilisé dans 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, vous obtenez ce qui se rapproche le plus d’une confirmation indépendante pour ce type de nombres.

Fork de sessions et mise en arrière-plan automatique de MCP (juillet 2026)

La v2.1.212 de Claude Code a redéfini 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 créée s’exécute indépendamment tandis que l’originale poursuit son travail — et l’ancien comportement au sein de la session a été renommé /subtask. Cette distinction importe pour la conception de l’orchestration : /subtask est un détour délimité au sein du cycle de vie d’une session ; /fork est un moyen économique de créer une session parallèle en arrière-plan qui hérite du contexte complet, plus proche du lancement d’une boucle Ralph que d’un subagent. Si vos scripts de harness supposaient que /fork restait au sein de la session, ils envoient désormais le travail en arrière-plan.

La même version place automatiquement en arrière-plan les appels MCP lents : tout appel à un outil MCP qui dure plus de deux minutes est automatiquement transféré vers une exécution en arrière-plan (réglez 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 a continué » ne désignent plus le même événement. Les hooks ou scripts qui supposaient l’achèvement 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 les transcriptions ou d’attendre la synthèse finale — le complément d’observabilité des subagents en arrière-plan par défaut. La v2.1.219 a étendu cette fonctionnalité au-delà du premier niveau : les subagents lancés à la profondeur 2 ou davantage 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 cette clé qu’il faut vous appuyer. Avec l’imbrication de nouveau activée par défaut, un flux linéaire de texte provenant des subagents devient ambigu — l’identifiant permet à un coordinateur de déterminer quel parent a produit quel enfant, afin de reconstruire l’arbre de délégation depuis le flux plutôt que de le déduire. Si votre consommateur de flux a été conçu pour un seul niveau de subagents, il recevra désormais du texte provenant d’agents dont il ignorait l’existence ; regroupez les données selon l’identifiant tool_use de l’Agent à l’origine du lancement, au lieu de supposer que chaque ligne transmise appartient à un enfant direct.

Orchestration multi-agents

Les systèmes d’IA mono-agent ont un angle mort structurel : ils ne peuvent pas remettre en question leurs propres hypothèses.⁷ La délibération multi-agents impose une évaluation indépendante depuis plusieurs perspectives avant qu’une décision ne soit verrouillée.

Orchestration inter-outils (avril 2026) : Google a publié Scion en open source le 7 avril — un hyperviseur multi-agents qui exécute Claude Code, Gemini CLI et d’autres « deep agents » comme processus concurrents, chacun avec un conteneur, un git worktree et des identifiants isolés. S’exécute en local, sur hub ou Kubernetes. Philosophie explicite : « isolation over constraints » — les agents fonctionnent avec une grande autonomie à l’intérieur de limites imposées au niveau de l’infrastructure, pas dans le prompt.²⁵ Cela étend directement l’argument de l’isolation des subagents à différents fournisseurs d’outils. Si votre flux de travail couvre Claude et les modèles OpenAI, Scion est la première véritable implémentation de référence pour des subagents inter-outils avec isolation worktree + identifiants par agent.

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-agents plafonne et peut être subverti par un consensus trompeur — des arguments valides perdent 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 Faithfulness/Relevance dans la phase 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) un score quantitatif du juge plutôt que de supposer que plus d’agents = meilleures réponses.

Orchestration multi-agents managée et Outcomes (Public Beta)

Si vous ne voulez pas construire l’infrastructure de délibération décrite ci-dessous, Multiagent Orchestration est entré en Public Beta dans Claude Managed Agents le 6 mai 2026.³⁵ Selon Anthropic : « Lorsqu’il y a trop de travail pour qu’un seul agent le fasse bien, l’orchestration multi-agents permet à un agent principal de découper le travail en morceaux et de déléguer chacun à un spécialiste avec 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. »³⁵

Le tracing est inclus d’origine. Selon Anthropic : « vous pouvez également tracer chaque étape dans la Claude Console : quel agent a fait quoi, dans quel ordre et pourquoi, vous donnant une visibilité complète sur la manière dont votre tâche a été déléguée et exécutée. »³⁵

La fonctionnalité Public Beta complémentaire est Outcomes. Selon Anthropic : « vous écrivez une rubrique décrivant à quoi ressemble le succès et l’agent travaille à l’atteindre. Un évaluateur séparé évalue la sortie par rapport à vos critères dans sa propre fenêtre de contexte, de sorte qu’il n’est pas influencé par le raisonnement de l’agent. »³⁵ Il s’agit de la version managée du modèle de validation à deux portes documenté plus loin dans cette section : la rubrique remplace la porte écrite à la main, l’évaluateur séparé 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 managé est la bonne réponse lorsque la délégation standard plus l’évaluation par rubrique est le contrat dont vous avez réellement besoin.

Délibération minimum viable

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

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 modèle couvre 80 % de la valeur. Tout le reste apporte une amélioration incrémentale.

Le déclencheur de confiance

Toutes les tâches n’ont pas besoin de délibération. Un module de notation de confiance évalue quatre dimensions :¹⁷

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

Le score correspond à trois niveaux :

Le seuil s’adapte selon le type de tâche. Les décisions de sécurité requièrent un consensus de 0,85. Les modifications de documentation n’en requièrent que 0,50. Cela évite la sur-ingénierie des tâches simples tout en garantissant que les décisions à risque sont scrutées.⁷

La machine à états

Sept phases, chacune contrôlée par la précédente :⁷

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

RESEARCH : Des agents indépendants examinent le sujet. Chaque agent reçoit un persona différent (Technical Architect, Security Analyst, Performance Engineer, et d’autres). L’isolation du contexte garantit que les agents ne peuvent pas voir les conclusions des autres pendant la recherche.

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

RANKING : Chaque agent évalue toutes les approches proposées selon 5 dimensions pondérées :

L’architecture de validation à deux portes

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

Porte 1 : Validation du consensus (hook PostToolUse). S’exécute immédiatement après que chaque agent de délibération a terminé : 1. La phase doit avoir atteint au moins RANKING 2. Au minimum 2 agents ont terminé (configurable) 3. Le score de consensus atteint le seuil adaptatif à la tâche 4. Si un agent a exprimé son 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 représentés 2. Transparence des contradictions : les désaccords ont des raisons documentées 3. Gestion de la complexité : au moins 2 alternatives 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 points du cycle de vie correspondent à la manière dont les défaillances surviennent réellement : certaines sont instantanées (mauvais score) et d’autres sont graduelles (faible diversité, documentation des désaccords manquante).⁷

Pourquoi l’accord est dangereux

Charlan Nemeth a étudié la dissidence minoritaire de 1986 jusqu’à son livre de 2018 In Defense of Troublemakers. Les groupes avec des dissidents prennent de meilleures décisions que les groupes qui parviennent rapidement à un accord. Le dissident n’a pas besoin d’avoir raison. L’acte de désaccord force la majorité à examiner les hypothèses qu’elle aurait autrement passées sous silence.¹⁸

Wu et al. ont testé 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, indépendamment de son exactitude.¹⁹ Liang et al. ont identifié la cause profonde comme la « Degeneration-of-Thought » : une fois qu’un LLM établit sa confiance dans une position, l’auto-réflexion ne peut pas générer de nouveaux contre-arguments, rendant l’évaluation multi-agents structurellement nécessaire.²⁰

L’indépendance est la contrainte de conception critique. Deux agents évaluant la même stratégie de déploiement avec visibilité sur les conclusions 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 est le coût du suivisme.⁷

Détecter le faux accord

Un module de détection de la conformité suit les schémas suggérant que les agents sont d’accord sans véritable évaluation :⁷

Regroupement des scores : Tous les agents notant à 0,3 points près sur une échelle de 10 points signalent une contamination du contexte partagé plutôt qu’une évaluation indépendante. Lorsque cinq agents évaluant un refactoring d’authentification ont tous noté le risque de sécurité entre 7,1 et 7,4, une nouvelle exécution avec une isolation de contexte fraîche a étalé les scores entre 5,8 et 8,9.

Désaccords standardisés : Des agents copient le langage de préoccupation des autres plutôt que de générer des objections indépendantes.

Perspectives minoritaires absentes : Approbation unanime de personas aux priorités contradictoires (un Security Analyst et un Performance Engineer sont rarement d’accord sur tout).

Le détecteur de conformité attrape les cas évidents (environ 10-15 % des délibérations où les agents convergent trop rapidement). 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

Tours de débat libre. Trois tours d’allers-retours textuels pour une discussion sur l’indexation de 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 formulés différemment. Le scoring structuré par dimension a remplacé le débat libre, réduisant le coût de 60 % tout en améliorant la qualité du classement.⁷

Porte de validation unique. La première implémentation exécutait un seul hook de validation à la fin de la session. Un agent a terminé une délibération avec un score de consensus de 0,52 (en dessous du 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. Le découpage en deux portes (une à la fin de la tâche, une à la fin de la session) a détecté les mêmes problèmes à différents points 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 conclusions. 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 Opus actuels, une délibération à 3 agents coûte environ 0,68 à 0,90 $. Une délibération à 10 agents coûte 2,25 à 3,00 $. Le système déclenche la délibération sur environ 10 % des décisions, donc le coût amorti sur l’ensemble des décisions est de 0,23 à 0,30 $ par session. Que cela en vaille la peine dépend de ce que coûte 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 terme d’Opus 4.7 (avril 2026)

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

• Résilience aux défaillances des outils : Opus 4.7 poursuit son travail malgré des défaillances d’outils qui interrompaient les sessions d’Opus 4.6. Vous pouvez réduire — sans toutefois les supprimer — les wrappers défensifs de nouvelle tentative dans le code des subagents. Conservez les protections au niveau des hooks ; allégez les instructions intégrées aux prompts du type « si l’outil échoue, réessayez trois fois ».
• Niveau d’effort xhigh (Opus-4.7 uniquement) : Se situe entre high et max. C’est le niveau par défaut recommandé pour les charges de travail de programmation et agentiques. Sur les subagents de longue durée, xhigh surpasse sensiblement high, avec une augmentation moins que proportionnelle du coût en tokens. max reste le bon choix pour un raisonnement complexe en une seule passe ; xhigh convient mieux aux tâches prolongées.
• Plafond du 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 compte à rebours actualisé et adapte progressivement la portée de son travail au budget, au lieu de l’épuiser de manière inattendue. Utilisez cette option pour les boucles agentiques lorsque vous souhaitez une consommation prévisible de tokens sans sacrifier la qualité sur les prompts courts.
• Détection des besoins implicites : Premier modèle Claude à réussir les tests d’« implicit-need » — il reconnaît lorsque la demande littérale de l’utilisateur ne précise pas suffisamment son besoin réel. La section « clarifying rules » de CLAUDE.md devient ainsi moins nécessaire. Si votre CLAUDE.md comporte 200 lignes de garde-fous du type « pensez également à X lorsque l’utilisateur demande Y », supprimez ceux que le modèle prend désormais en charge nativement.

Base des worktrees, chemins de sandbox et paramètres administrateur (7 mai 2026)

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

Le rétablissement de worktree.baseRef est le changement à signaler aux utilisateurs : les agents qui dépendaient du comportement des versions v2.1.128 à v2.1.132 — création des worktrees à partir du HEAD local — perdent l’accès aux travaux non poussés dans les nouveaux worktrees, sauf s’ils réactivent explicitement ce comportement.

Enquête 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 cours de session pour les entreprises qui collectent les réponses via OpenTelemetry.⁴⁰ Si votre organisation envoie les événements OTel vers une plateforme centrale d’observabilité, cette variable d’environnement réintègre l’enquête au flux de données afin que les indicateurs de qualité empruntent le même pipeline que les métriques de latence et d’erreur. Considérez-la comme une option à activer explicitement : par défaut, l’enquête reste désactivé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 sont importants pour les déploiements en production.⁶⁸ CLAUDE_CODE_PROCESS_WRAPPER permet aux environnements gérés de lancer le processus Claude Code par l’intermédiaire d’un binaire wrapper d’entreprise — le point d’intégration pour les agents de terminaux, les contrôles de stratégie au lancement et les environnements dans lesquels chaque processus doit s’exécuter sous la supervision imposée. Si votre entreprise simulait auparavant ce comportement à l’aide d’alias shell ou de scripts de lancement dérivés, voici désormais le point d’intégration officiellement pris en charge.

La même version a réduit la surcharge d’exécution là où les harnesses la subissent le plus : des cycles d’utilisation d’outils jusqu’à 7 fois plus rapides dans les sessions comportant un nombre élevé d’outils MCP, et des transcriptions de session 79 fois plus petites.⁶⁸ Cela nuance — sans l’inverser — la recommandation de la section Le coût comme choix architectural : l’approche CLI-first reste préférable pour les opérations ponctuelles sans état, mais un harness qui embarque des dizaines d’outils MCP ne subit plus la pénalité par cycle observée au printemps, tandis que le stockage des transcriptions cesse d’être un coût caché des longues exécutions autonomes.

La quality loop

Un processus de révision obligatoire pour toutes les modifications non triviales :

1. Implémenter - Écrivez le code
2. Relire - Relisez chaque ligne. Repérez les fautes de frappe, les erreurs de logique et les passages peu clairs
3. Évaluer - Exécutez l’evidence gate. Vérifiez les modèles, les cas limites et la couverture des 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 d’éventuelles régressions
6. Répéter - Si un critère de l’evidence gate échoue, revenez à l’étape 4
7. Rendre compte - Énumérez les modifications, expliquez comment elles ont été vérifiées et citez des preuves précises

L’evidence gate

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

Si vous ne pouvez produire aucune preuve pour une ligne, revenez à l’étape Affiner.²²

Autorité humaine sur les fusions

Une étude arXiv de mai 2026 portant sur le cycle de vie de 29 585 pull requests d’agents IA distingue l’autonomie opérationnelle de la gouvernance des fusions.⁴⁷ La leçon architecturale utile est simple : les agents peuvent commencer le travail, faire progresser les branches, ouvrir des PR, relire 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. Autorisez les agents à préparer des PR et à recueillir des preuves ; exigez une approbation humaine pour les fusions, les mises en production et les opérations destructrices sur le dépôt, sauf si l’organisation dispose d’une stratégie d’automatisation auditée séparément. Lorsqu’une automatisation exécute une fusion, conservez des journaux qui distinguent l’exécutant de la personne ou de la stratégie qui l’a autorisée.

Modèles de gestion des erreurs

Écritures atomiques dans les fichiers. Lorsque plusieurs agents écrivent simultanément dans le même fichier d’état, ils corrompent JSON. Écrivez d’abord dans des fichiers .tmp, puis utilisez mv de manière atomique. Le système d’exploitation garantit que mv est atomique sur un 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 de l’état. Si l’état est corrompu, le modèle de récupération le recrée à partir de valeurs par défaut sûres au lieu de provoquer un plantage :¹⁶

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 de ((VAR++)). ((VAR++)) renvoie le code de sortie 1 lorsque VAR vaut 0, car 0++ est évalué à 0, valeur que Bash considère comme fausse. Lorsque set -e est activé, cela interrompt le script. Utilisez plutôt VAR=$((VAR + 1)).¹⁶

Classification du rayon d’impact

Classez chaque action de l’agent selon son rayon d’impact et appliquez les contrôles correspondants :²

Remote Control — qui permet de se connecter à Claude Code en local depuis n’importe quel navigateur ou application mobile — transforme le contrôle « Externe » : l’attente bloquante devient une notification asynchrone. L’agent poursuit 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 : un objectif, des critères d’achèvement et des références contextuelles :¹⁶

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 pouvoir être vérifiés par une machine : réussite ou échec des tests, résultat du linter, codes d’état HTTP, vérification 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 concrète d’une session

Trace d’une exécution autonome traitant un PRD comportant 5 récits :²

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

2. L’agent lit le PRD et planifie le premier récit. UserPromptSubmit se déclenche. Le dispatcher injecte : contexte du projet actif, référence initiale de dérive de la 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 du projet. 90 ms. Les tests s’exécutent. PostToolUse:Bash se déclenche : signal d’activité enregistré, contrôle de la dérive.

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

5. L’agent termine le récit. Stop se déclenche. La quality gate vérifie : l’agent a-t-il cité des preuves ? A-t-il employé des formulations évasives ? Le diff contient-il des commentaires TODO ? Si un contrôle échoue, le hook renvoie le code 2 et l’agent poursuit son travail.

6. Vérification indépendante : Un nouvel agent exécute la suite de tests sans se fier au rapport 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 un problème CRITICAL, le récit retourne dans la file d’attente.

8. Le récit est validé. Le suivant est chargé. Le cycle se répète pour les 5 récits.

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

Étude de cas : traitement nocturne de PRD

Un harness de production a traité 12 PRDs — soit 47 récits — au cours de 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 et revue multi-agent.

Les deux fuites d’identifiants ont nécessité la rotation des clés API et l’audit des services en aval : environ 4 heures de réponse à incident. La surcharge du harness qui a empêché un incident équivalent représentait 2,4 secondes de Bash par récit. Le taux de faux achèvements est passé de 35% à 4%, car le hook Stop exécutait les tests de manière indépendante avant d’autoriser l’agent à déclarer son travail terminé.

Considérations de sécurité

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

Le 9 avril 2026, Anthropic a publié un cadre formel définissant la fiabilité des agents.²⁷ Ses cinq principes reprennent — et approfondissent — la réflexion sur l’evidence gate présentée dans ce guide :

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

Tour sans état et identité autodéclarée de MCP (juillet 2026). La spécification MCP évolue actuellement vers un cœur sans état (SEP-2575), qui abandonne l’ancien échange d’initialisation avec état servant à transmettre l’identité du serveur. Une modification du projet de spécification, fusionnée le 16 juillet (PR #3002), rétablit l’identité en tant qu’interface facultative : les serveurs peuvent inclure un objet io.modelcontextprotocol/serverInfo dans le champ _meta de leur réponse, tandis que clientInfo devient facultatif dans les requêtes.⁷¹ Sur le plan de la sécurité, l’essentiel tient à ce que dit la spécification au sujet de la confiance : cette identité est autodéclarée et non vérifiée — destinée uniquement à l’affichage et à la journalisation — et NE DEVRAIT PAS guider les décisions de sécurité. Si votre harness fonde ses listes d’autorisation, ses règles de permission ou ses audits basés sur les journaux sur le nom déclaré d’un serveur MCP, ce nom constitue une affirmation, pas un justificatif d’identité ; ancrez la confiance dans le transport et la configuration (quel serveur vous avez configuré à quel point de terminaison), jamais dans ce que le serveur prétend être. La révision finale de la spécification sans état est prévue pour le 28 juillet 2026 — les détails de cette section relatifs au protocole devraient donc se stabiliser lors de la prochaine mise à jour.

Outils de sandbox pour les 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 une sandbox dédiée et fournit des verdicts étayés par des preuves issues des mécanismes de détection Sigma/YARA/Nova/Snort. Il s’agit du premier produit de la catégorie des sandbox pour skills.²⁸

La sandbox

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

Seuil de sécurité de mai 2026. Claude Code v2.1.149 a corrigé un contournement des permissions relatives au dossier de travail dans PowerShell, plusieurs lacunes d’analyse des permissions liées aux règles d’autorisation et aux variables obsolètes de PowerShell, ainsi qu’un défaut de la liste d’autorisation d’écriture de la sandbox pour les worktrees Git, qui couvrait toute la racine du dépôt principal au lieu des seuls éléments internes partagés de Git.⁵³ Si votre harness autorise PowerShell ou des agents isolés dans des worktrees, considérez la version v2.1.149 ou ultérieure comme le minimum requis et conservez des règles de shell strictes. Les règles générales PowerShell(*) et les exceptions d’écriture portant sur l’intégralité du dépôt sont des raccourcis d’orchestration, pas des frontières de sécurité.

Verrouillage de la sandbox SDK d’OpenAI Agents (v0.17.0, 8 mai 2026). Du côté d’OpenAI, la version v0.17.0 d’openai-agents-python 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 dossier de travail courant du processus SDK au moment de l’application du manifeste), sauf si la source est explicitement autorisée au moyen de Manifest.extra_path_grants avec SandboxPathGrant.⁴¹ Les sources locales relatives sont résolues à partir de base_dir ; les chemins absolus doivent déjà se trouver à l’intérieur de celui-ci ou bénéficier d’une autorisation. Cette mesure corrige un problème de frontière concernant les artefacts locaux : les versions antérieures permettaient aux manifestes d’importer des chemins hôtes arbitraires dans l’espace de travail d’une sandbox. Pour effectuer la migration, déclarez les racines hôtes de confiance au niveau du manifeste avec SandboxPathGrant(path=..., read_only=True) afin de créer des montages en lecture seule. Considérez extra_path_grants comme une configuration d’application de confiance ; ne renseignez jamais les autorisations à partir de la sortie du modèle ou d’une entrée de manifeste non fiable.

Seuil de suivi pour SDK d’OpenAI Agents (v0.17.3). Les versions 0.17.1 à 0.17.3 ont apporté d’autres renforcements de la sandbox et des sessions : limites d’extraction des archives, validation des sous-chemins GitRepo, erreurs plus explicites des fournisseurs de sandbox, exclusion des identifiants des points de montage des commandes de la sandbox, rejet des racines relatives d’espace de travail de sandbox et gestion de l’état terminal des sandbox Vercel.⁵⁴ Si vous utilisez des sandbox hébergées par OpenAI ou adossées à un fournisseur, plutôt que les seuls hooks de Claude Code, considérez la version 0.17.3 comme le seuil actuel pour les modèles décrits dans cette section.

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

L’article technique de Anthropic intitulé « How we contain Claude across products » (25 mai 2026) expose, du point de vue du fournisseur, les principes que cette section présente séparément — la sandbox configurée au niveau des paramètres décrite plus haut, le seuil d’isolation par worktree et le principe consistant à ne faire confiance à rien.⁸¹ Son idée centrale consiste à adapter la robustesse du confinement à l’interface du produit. Cette correspondance constitue en elle-même la leçon : il n’existe pas de conception d’isolation universellement correcte, mais uniquement une isolation adaptée à la personne qui supervise et aux incidents susceptibles de se produire.

• 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 propre à chaque session. Le modèle de menace porte sur l’isolation de l’infrastructure et des locataires — la machine de l’utilisateur n’est jamais accessible, si bien qu’aucune ressource locale n’a besoin d’être protégée.
• Sandbox du système d’exploitation avec intervention humaine (Claude Code). Le modèle décrit dans le paragraphe précédent consacré à la sandbox, ici formulé comme une politique : Seatbelt sous macOS et bubblewrap sous Linux, avec lecture autorisée, écriture limitée à l’espace de travail et réseau refusé par défaut — l’humain approuve ce que la frontière ne couvre pas. Anthropic a publié le code source de l’environnement d’exécution (sandbox-runtime) afin que cette frontière puisse être auditée. L’article reconnaît sans détour le maillon faible : environ 93 % des demandes de permission sont approuvées. Le classificateur du mode automatique — qui intercepte environ 83 % des comportements trop entreprenants avant leur exécution tout en réduisant de 84 % les demandes d’approbation — existe précisément parce que la lassitude face aux approbations constitue une propriété de sécurité, et non un simple défaut d’ergonomie. C’est la posture de couche de contrôle que ce guide suit depuis la version v2.1.193.
• Machines virtuelles hermétiques (Claude Cowork). Des machines virtuelles complètes fonctionnent sur les hyperviseurs de la plateforme — framework Apple Virtualization sous macOS, HCS sous Windows — et seuls l’espace de travail sélectionné et le dossier .claude y sont montés ; rien d’autre provenant de l’hôte n’est visible. Les identifiants ne pénètrent jamais dans la machine virtuelle : ils restent dans le trousseau de l’hôte et chaque session reçoit un jeton délimité pouvant être révoqué indépendamment. Un proxy MITM défensif situé dans la machine virtuelle applique cette règle en ne laissant passer que les requêtes contenant le jeton de session attribué à cette machine virtuelle — une clé intégrée par un attaquant est rejetée à la frontière, car seule la machine virtuelle connaît sa provenance.

Les principes de conception sous-jacents à cette taxonomie sont la partie transposable. Confinez d’abord au niveau de l’environnement, orientez ensuite au niveau du modèle : toute défense probabiliste présente un taux d’échec non nul ; des frontières déterministes doivent donc intercepter ce que l’orientation par prompt laisse passer — autrement dit, l’argument de ce guide selon lequel les hooks garantissent l’exécution, reformulé par le fournisseur. Adaptez la robustesse de l’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 — voilà pourquoi Code affiche une boîte de dialogue de permission, tandis que Cowork utilise une machine virtuelle hermétique. Préférez les primitives éprouvées au code d’isolation personnalisé : les hyperviseurs, seccomp et environnements d’exécution de conteneurs ont mieux résisté à l’examen contradictoire que les proxies à liste d’autorisation et les analyseurs de configuration personnalisés de Anthropic. Considérez la configuration locale du projet et les sorties d’outils comme non fiables : l’article recommande de traiter l’ouverture d’un projet et le chargement d’une configuration comme toute requête entrante provenant d’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é autodéclarée de MCP. Conservez les identifiants hors de la sandbox : utilisez des jetons délimités, révocables et propres à chaque session plutôt que des clés ambiantes que l’agent pourrait divulguer.

L’interface de paramétrage rattrape le premier principe (v2.1.219). Il est facile d’approuver l’idée de « confiner d’abord au niveau de l’environnement », mais sa configuration concrète est longtemps restée malaisée, car la sandbox de Claude Code traitait ce que ses règles ne couvraient pas en posant une question — or une demande de permission est une défense probabiliste déguisée en défense déterministe, comme le reconnaît le taux d’approbation de 93 % mentionné plus haut. sandbox.network.strictAllowlist élimine cette question pour le trafic sortant : une fois ce paramètre activé, la requête d’une commande exécutée dans la sandbox vers un hôte absent de la liste d’autorisation est immédiatement refusée au lieu de déclencher une demande.⁸⁴ Associez-le au paramètre sandbox.filesystem.disabled introduit par la version v2.1.216 : ensemble, ces deux réglages forment une véritable posture plutôt qu’un empilement d’options — les confinements du système de fichiers et du réseau peuvent être sélectionnés indépendamment, et le confinement réseau peut désormais devenir déterministe. Pour un harness sans surveillance, ce dernier est le plus important des deux, car c’est par le trafic sortant qu’une instruction injectée se transforme en exfiltration ; dans le cas extrême de la lassitude face aux approbations, personne ne se trouve devant le clavier pour éprouver cette lassitude. Le prix à payer est celui de toute frontière déterministe : la liste d’autorisation doit être correcte, et l’oubli d’un hôte provoque un refus opaque plutôt qu’une question. Recensez les hôtes dont vos agents ont légitimement besoin, puis supprimez la demande.

Rien de tout cela ne remplace la couche de hooks ; ces mécanismes se situent en dessous. Les modèles de confinement constituent le socle déterministe, et l’historique de l’application des worktrees présenté dans ce guide illustre la même leçon à petite échelle : 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é conçues spécialement 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 jusqu’au niveau de ses paramètres : Tool(param:value) établit une correspondance avec les paramètres d’entrée d’un outil, * servant de joker. L’exemple canonique est Agent(model:opus) — une règle qui empêche la création de subagents sur un niveau de modèle particulier.⁶³ Sur le plan architectural, cette nouveauté 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 limiter la manière dont il était appelé. Une politique de gouvernance peut désormais stipuler « les subagents peuvent être créés, mais pas sur le niveau Fable 5 » ou « Bash est autorisé, sauf avec cet indicateur » sous la forme d’une règle déterministe plutôt que d’une consigne formulée dans un prompt.

Un paramètre administré complémentaire, enforceAvailableModels (v2.1.175), limite la sélection des modèles depuis le niveau supérieur : il fixe le modèle par défaut et empêche les paramètres propres à l’utilisateur ou au projet d’élargir la liste d’autorisation administrée availableModels.⁶³ Les deux mécanismes se combinent — la liste d’autorisation définit les niveaux disponibles pour toute la session, tandis que les règles au niveau des paramètres limitent la façon dont les subagents les utilisent. Depuis la version v2.1.196, les administrateurs peuvent également définir un modèle par défaut à l’échelle de l’organisation depuis la console de l’organisation. Celui-ci apparaît sous la forme « Org default » dans /model, afin qu’un parc entier hérite d’une valeur par défaut gouvernée sans que chaque opérateur ait à en fixer une — un plancher qui complète le plafond de la liste d’autorisation.

Les règles d’autorisation limitées à un chemin s’ancrent dans le dossier de travail (juillet 2026)

Claude Code v2.1.214 a corrigé une correspondance excessive discrète dans les règles de permission limitées à un chemin : une règle d’autorisation contenant un modèle dir/** à un seul segment — par exemple Edit(src/**) — approuvait automatiquement les modifications de tout dossier nommé src, quelle que soit sa profondeur, notamment vendor/some-package/src/ et chaque autre dossier src/ imbriqué que l’auteur de la règle n’avait jamais voulu autoriser. Ces règles s’ancrent désormais uniquement dans <cwd>/dir ; si vous souhaitez réellement une correspondance à n’importe quelle profondeur, déclarez-la avec **/dir/**.⁷⁴ Les règles de refus et de demande conservent délibérément l’ancienne correspondance à toutes les profondeurs. Cette asymétrie constitue la bonne conception à sûreté intégrée : une règle d’autorisation trop restrictive échoue de manière sûre (vous obtenez une demande), tandis qu’une règle de refus trop restrictive échoue de manière ouverte (un chemin censé être bloqué passe entre les mailles) — les autorisations sont donc devenues plus strictes et les refus sont restés généraux. Si vos paramètres s’appuient sur des modèles d’autorisation à un seul segment pour couvrir des chemins imbriqués, ils ont discrètement cessé de le faire avec la version v2.1.214 ; c’est le correctif qui fonctionne comme prévu, mais il est utile de vérifier vos listes d’autorisation afin de redéclarer l’étendue réellement souhaitée.

Garde-fous du mode automatique contre les commandes destructrices (juin 2026)

Claude Code v2.1.183 a réduit le rayon d’impact du mode automatique pour les opérations susceptibles de supprimer silencieusement du travail ou de démanteler des environnements. Sauf demande explicite de votre part pendant la session, le mode automatique bloque désormais fermement 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, ainsi que le démantèlement d’infrastructures (terraform destroy, pulumi destroy, cdk destroy) si vous n’avez pas désigné la pile concernée.⁶⁵ Sur le plan architectural, ce dispositif complète le contrôle de création et les règles au niveau des paramètres présentés plus haut : au lieu de contrôler quel outil est utilisé ou comment il est créé, il contrôle un petit ensemble de commandes irréversibles précises en fonction de l’intention — l’agent peut toujours les exécuter, mais uniquement sur instruction explicite, et non de sa propre initiative. Pour un harness autonome, encodez le même principe dans vos propres hooks PreToolUse : les commandes qui détruisent un état méritent une règle de refus par défaut que seul un signal explicite de l’opérateur peut lever.

Juillet 2026 : le mode automatique arrive en entreprise, et une demande devient impossible à contourner. Le mode automatique a atteint la disponibilité générale sur Amazon Bedrock, Google Vertex AI et Microsoft Foundry dans la version v2.1.207, avec un paramètre administré disableAutoMode permettant aux entreprises de le désactiver — la posture du classificateur comme couche de contrôle est désormais disponible sur toutes les plateformes d’entreprise propriétaires, et sa désactivation relève d’une décision explicite de gouvernance plutôt que d’une lacune de la plateforme.⁶⁸ La version v2.1.208 a ensuite rendu absolu le garde-fou contre les suppressions catastrophiques : les demandes de confirmation relatives aux suppressions catastrophiques passent désormais outre à la fois --dangerously-skip-permissions et le mode automatique.⁶⁸ Ce précédent est notable — il s’agit de la première confirmation de Claude Code qu’aucune posture de permission, y compris l’indicateur explicite de contournement, ne permet d’éviter. Les conceptions de harness autonomes qui supposaient que --dangerously-skip-permissions signifiait littéralement l’absence totale de demandes doivent tenir compte de cette exception ; elle se déclenche précisément lorsqu’une boucle sans surveillance risque de causer les dégâts les plus irréversibles.

Garde-fous contre la fabrication (juillet 2026)

Les versions v2.1.203 à v2.1.206 ont fermé deux voies permettant à un agent de fabriquer sa propre piste d’audit.⁶⁸ Premièrement, une règle du mode automatique bloque désormais la falsification des fichiers de transcription — les appels d’outils de la session ne peuvent plus réécrire le registre de cette même session. Deuxièmement, les notifications des tâches en arrière-plan indiquent maintenant explicitement qu’aucune intervention humaine n’a eu lieu pendant l’exécution de la tâche. Cette seconde mesure cible 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, sans que rien dans la notification ne la contredise. La notification constitue désormais elle-même la contre-preuve.

La leçon architecturale s’étend à l’evidence gate : les transcriptions, notifications et journaux sont des surfaces d’audit, et les surfaces d’audit ne doivent pas être modifiables par l’élément qu’elles contrôlent. La plateforme applique maintenant cette règle à ses propres transcriptions ; faites de même dans votre harness — les rapports de preuves, résultats de tests et comptes rendus de délibération doivent se trouver hors du chemin accessible en écriture au modèle.

Défense contre l’injection de prompts

Les skills et les hooks offrent une défense en profondeur contre l’injection de prompts :

Les skills assortis de restrictions d’outils empêchent un prompt compromis d’obtenir 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 doté de permissionMode: plan ne peut apporter aucune modification, même si son prompt est compromis.

Le socle de la plateforme a été renforcé en juillet 2026. Claude Code v2.1.210 a renforcé l’Agent tool contre l’injection indirecte de prompts véhiculée par le contenu lu par un subagent — un fichier piégé, une page web ou un résultat d’outil récupéré par un subagent peut plus difficilement détourner l’interface de délégation elle-même.⁶⁹ La version v2.1.211 a également renforcé le maillon humain de la chaîne : les aperçus de permissions neutralisent désormais les caractères Unicode de substitution bidirectionnelle, les caractères de largeur nulle et les caractères visuellement similaires, de sorte qu’une commande ne peut plus être conçue pour paraître inoffensive dans la boîte de dialogue d’approbation tout en exécutant autre chose.⁶⁹ Cette seconde correction importe tout particulièrement pour les harness où un humain approuve des aperçus affichés sous la pression du temps — l’affichage constituait lui aussi une surface d’injection. Aucune de ces modifications ne remplace les défenses au niveau des hooks présentées plus haut ; elles renforcent le socle sur lequel celles-ci reposent.

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

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

La règle en production est la suivante : considérez les transcriptions des agents, les payloads d’outils, les journaux SQLite et l’exécution des garde-fous comme une infrastructure sensible. Expurgez les données avant leur conservation, appliquez des limites de rétention et maintenez le code personnalisé des garde-fous dans une sandbox afin qu’il puisse être examiné. Une consigne de prompt telle que « ne pas journaliser les secrets » ne suffit pas ; le parcours 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 allowedEnvVars explicite afin d’empêcher l’exfiltration de variables d’environnement arbitraires :¹³

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

Répartition des responsabilités entre l’humain et l’agent

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

Le modèle est le suivant : les humains prennent en charge les décisions qui exigent un contexte organisationnel, un jugement éthique ou une orientation stratégique. Les agents prennent en charge celles qui nécessitent une recherche computationnelle dans de vastes espaces de possibilités. Les hooks font respecter cette frontière.

Application récursive des hooks

Les hooks se déclenchent également pour les actions des subagents.¹³ Si Claude crée un subagent au moyen de 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 barrières de sécurité. L’événement SubagentStop vous permet d’effectuer un nettoyage ou une validation lorsqu’un subagent termine son travail.

Ce mécanisme n’est pas facultatif. Un agent qui crée un subagent sans vos hooks de sécurité est un agent capable d’effectuer un force-push vers main, de lire des fichiers d’identifiants ou d’exécuter des commandes destructrices pendant que vos barrières observent la conversation principale ne rien faire.

Le coût comme choix architectural

Le coût est une décision architecturale, pas une considération opérationnelle tardive.² Il se décline en trois niveaux :

Niveau des tokens. Compression du prompt système. Supprimez les exemples de code didactiques (le modèle connaît les APIs), regroupez les règles dupliquées entre plusieurs 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 justifiant pourquoi les identifiants ne doivent pas être lus.

Niveau des agents. Préférez de nouvelles instances aux longues conversations. Chaque story d’une exécution autonome reçoit un nouvel agent doté d’un contexte vierge. Le contexte ne gonfle jamais, car chaque agent repart de zéro. Privilégiez un briefing à la mémoire : les modèles exécutent mieux un briefing clair qu’ils ne parcourent 30 étapes de contexte accumulé.

Niveau de l’architecture. Préférez CLI à MCP lorsque l’opération est sans état. Un appel claude --print pour une évaluation ponctuelle coûte moins cher et n’ajoute aucun surcoût de connexion. MCP se justifie lorsque l’outil nécessite un état persistant ou du streaming.

Cadre de décision

Quand utiliser chaque mécanisme :

Skills vs Hooks vs Subagents

FAQ

Combien de hooks est-ce trop ?

La contrainte vient des performances, pas du nombre. Chaque hook s’exécute de façon synchrone, donc le temps total d’exécution des hooks s’ajoute à chaque appel d’outil correspondant. 95 hooks répartis entre les paramètres utilisateur et projet s’exécutent sans latence perceptible lorsque chaque hook se termine en moins de 200 ms. Seuil à surveiller : si un PostToolUse hook ajoute plus de 500 ms à chaque modification de fichier, la session paraît lente. Profilez vos hooks avec time avant de les déployer.¹⁴

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

Oui. Les PreToolUse hooks 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 le motif du rejet et propose une alternative plus sûre. Le code de sortie 1 correspond à un avertissement non bloquant : l’action continue tout de même.³

Où dois-je placer les fichiers de configuration des hooks ?

Les configurations de hooks vont dans .claude/settings.json pour les hooks au niveau projet (committés dans votre dépôt, 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 scripts afin d’éviter les problèmes de répertoire de travail.¹⁴

Chaque décision nécessite-t-elle une deliberation ?

Non. Le module de confiance note les décisions selon quatre dimensions (ambiguïté, complexité, enjeux, dépendance au contexte). Seules les décisions dont la confiance globale est inférieure à 0,70 déclenchent une deliberation, soit environ 10 % des décisions totales. Les corrections de documentation, renommages de variables et modifications courantes sautent entièrement la deliberation. 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 du désaccord ?

Testez les chemins de réussite comme les chemins d’échec. Réussite : les agents sont en désaccord de façon productive et atteignent un consensus. Échec : les agents convergent trop vite, ne convergent jamais ou dépassent les budgets de spawn. Les tests de bout en bout simulent chaque scénario avec des réponses d’agents déterministes, en vérifiant que les deux portes de validation détectent chaque mode d’échec documenté. Un système de deliberation en production exécute 141 tests 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 deliberation sur la latence ?

Une deliberation à 3 agents ajoute 30 à 60 secondes de temps réel (les agents s’exécutent séquentiellement via l’Agent tool). Une deliberation à 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 LLM par agent, et non la surcharge d’orchestration.⁷

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

Gardez chaque section sous 50 lignes et l’ensemble du fichier sous 150 lignes. Les fichiers longs sont tronqués par les fenêtres de contexte ; placez donc les instructions les plus critiques en premier : commandes et 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 matcher et l’Agent tool de Claude Code. AGENTS.md transporte 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