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

En bref : Claude Code n’est pas une boîte de dialogue avec accès aux fichiers. C’est un runtime programmable avec 29 événements de cycle de vie documentés, chacun pouvant être relié à des hooks via 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, les agents dans des workflows, et vous obtenez un harness de développement autonome qui impose des contraintes, délègue le travail, conserve la mémoire entre les sessions et orchestre la 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 passer l’orchestration multi-agent déterministe de scripts purement userland vers une primitive runtime de première partie ; la v2.1.149 renforce la même leçon côté sécurité, avec des correctifs de contournement des permissions PowerShell et un correctif d’allowlist pour le sandbox git-worktree. Les hooks et les evidence gates restent responsables de la correction.⁵²⁵³ Ce guide couvre chaque couche de cette pile : d’un hook unique à un système de consensus à 10 agents. Aucun framework requis. Tout en bash et JSON.

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

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

Cette distinction compte, car l’infrastructure produit des effets composés. Un hook qui bloque les identifiants dans les commandes bash protège chaque session, chaque agent, chaque exécution autonome. Un skill qui encode votre grille d’évaluation s’applique de façon cohérente, que vous l’invoquiez vous-même ou qu’un agent le fasse. Un agent qui relit le code sous l’angle de la sécurité exécute les mêmes contrôles, que vous soyez en train de regarder ou non.²

Points clés

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

Comment utiliser ce guide

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

Chemin d’or en cinq minutes

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

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

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

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

Branchez-le dans .claude/settings.json :

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

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

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

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

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

Étape 3 : Lancer un subagent (30 secondes)

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

Ce que vous avez maintenant

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

Pourquoi l’architecture d’agents est importante

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

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

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

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

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

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

Le pattern du harness

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

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

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

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

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

L’idée clé : la plupart des utilisateurs travaillent entièrement dans la couche centrale, voyant le contexte gonfler et les coûts grimper. Les utilisateurs avancés configurent les couches d’instruction et d’extension, puis n’utilisent la couche centrale que pour l’orchestration et les décisions finales.²

Harness gérés vs auto-hébergés (avril 2026)

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

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

Pour les projets Python qui veulent embarquer le runtime Claude Code comme bibliothèque — entre « shell out vers claude » et « API REST vers Managed Agents » — claude-agent-sdk-python est la troisième option. La série du 28-29 avril (v0.1.69 → v0.1.71) a fait passer le CLI embarqué à v2.1.123, relevé le plancher de la dépendance mcp à >=1.19.0 (les versions plus anciennes supprimaient silencieusement les retours CallToolResult des outils MCP in-process, laissant le modèle avec un blob d’erreur de validation), et amené SandboxNetworkConfig à la parité de schéma avec le SDK TypeScript (allowedDomains, deniedDomains, allowManagedDomainsOnly, allowMachLookup).³⁰

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

La bifurcation architecturale est désormais réelle :

Quand choisir lequel : l’auto-hébergé reste pertinent pour les équipes qui disposent déjà d’une force d’infrastructure, qui veulent des skills/hooks qu’elles contrôlent, ou qui optimisent un workflow spécifique en profondeur. Le géré convient aux équipes sans ingénieurs plateforme dédiés, lorsque le délai de mise en valeur compte plus que la personnalisation, ou lorsque les exécutions d’agents doivent survivre de manière fiable aux fermetures d’ordinateurs portables sans que vous ayez à construire cette couche de persistance. Les deux 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 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 un rôle. L’arborescence ~/.claude/ est l’infrastructure personnelle qui s’applique à tous les projets. L’arborescence .claude/ dans chaque dépôt est spécifique au projet et partagée via git. Ensemble, elles forment le harness complet.

Système de skills

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

Quand créer un skill

Les skills servent à représenter des connaissances que Claude a toujours à disposition. Les slash commands servent aux actions que vous déclenchez explicitement. Si vous hésitez entre les deux, posez-vous la question : « Claude doit-il appliquer cela automatiquement, ou dois-je décider quand l’exécuter ? »

Créer un skill

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

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

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

# Code Review Expertise

## Security Checks
When reviewing code, verify:

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

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

Référence du frontmatter

Le champ Description est déterminant

Au démarrage de la session, Claude Code extrait le name et la description de chaque skill et les injecte dans le contexte de Claude. Lorsque vous envoyez un message, Claude utilise le raisonnement du modèle de langage pour décider si un skill est pertinent. Une analyse indépendante de la source de Claude Code confirme le mécanisme : les descriptions des skills sont injectées dans une section available_skills du prompt système, et le modèle utilise la compréhension du langage standard 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 inclut : ce qu’elle fait (examiner le code pour des types de problèmes spécifiques), quand l’utiliser (examen de changements, PRs, analyse qualité), et les expressions déclencheuses (review, audit, check) que les utilisateurs tapent naturellement.

Budget de contexte

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

Fichiers de support et organisation

Les skills peuvent référencer des fichiers supplémentaires 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 avec des liens relatifs. Claude lit ces fichiers à la demande lorsque le skill s’active. Gardez SKILL.md sous 500 lignes et déplacez les éléments de référence détaillés vers des fichiers de support.¹²

Partager des skills via Git

Les skills de projet (.claude/skills/ à la racine du repo) 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 les coéquipiers pull, ils obtiennent automatiquement le skill. Aucune installation, aucune configuration. C’est la façon la plus efficace de standardiser l’expertise dans une équipe.

Les skills comme bibliothèque de prompts

Au-delà des skills à objectif unique, la structure de dossiers fonctionne comme une 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 reçoit des conseils de niveau senior sans avoir à les demander.

Les skills se composent avec les hooks

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

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

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

Erreurs courantes avec les skills

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

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

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

Surface de skill SDK (8 mai 2026)

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

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

Les skills ont toujours été chargés depuis le dossier .claude/skills/ d’un projet. Claude Code v2.1.157 étend ce dossier aux plugins : un plugin placé dans .claude/skills/ se charge désormais automatiquement sans enregistrement marketplace, et claude plugin init <name> y échafaude un nouveau plugin avec le manifest et SKILL.md déjà câblés.⁵⁸ Cela comble l’écart entre les deux formes de project-tooling qui vivaient auparavant à des endroits différents : un skill nu commité directement dans le repo, contre un plugin qui regroupe un skill, des hooks et un serveur MCP, mais nécessitait auparavant une marketplace pour être installé. Effet pratique pour la conception de harness : les outils limités au projet n’ont plus besoin d’un détour par un registre pour être livrés : écrivez-les, commitez-les, et les coéquipiers obtiennent la même surface avec git pull. Les plugins conservent le cas d’usage de l’installation groupée (hooks + skills + serveurs MCP + agents dans un seul ZIP) ; ce qui change, c’est qu’un projet n’a plus besoin de monter une marketplace simplement pour en charger un depuis son propre arbre.

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

Les skills sont une capacité, et toute capacité est une surface d’attaque. Claude Code v2.1.169 ajoute un paramètre disableBundledSkills (et la variable d’environnement correspondante CLAUDE_CODE_DISABLE_BUNDLED_SKILLS) qui masque entièrement au modèle les skills intégrés, les workflows et les slash commands intégrées.⁶⁰ Pour un harness durci ou réglementé, c’est une réduction volontaire de la surface d’attaque : un opérateur qui a audité et approuvé un ensemble précis de skills de projet et personnels peut supprimer tout ce que Anthropic fournit par défaut, de sorte que le modèle ne raisonne jamais que sur la surface validée par l’opérateur. Traitez cela comme une allowlist d’outils : par défaut, la capacité est large, et désactiver ce défaut relève d’une décision de gouvernance, pas d’un simple réglage de confort.

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

Claude Code v2.1.178 a rendu le project tooling sensible à l’emplacement. Les skills dans des dossiers .claude/skills imbriqués se chargent désormais lorsque vous travaillez sur des fichiers sous ce dossier, et plus seulement depuis la racine du repo ; en cas de conflit de nom, le skill imbriqué apparaît sous la forme <dir>:<name>, ce qui permet aux deux de rester accessibles.⁶³ La même version a fait en sorte que le reste de la surface projet se résolve au plus proche du dossier de travail : lorsqu’un nom d’agent, de workflow ou de style de sortie entre en collision entre plusieurs dossiers .claude/ imbriqués, celui qui est le plus proche du dossier de travail l’emporte, et l’enregistrement d’un workflow à périmètre projet cible le dossier .claude/workflows/ existant le plus proche au lieu de toujours viser la racine.⁶³ Pour un monorepo ou un repo-de-repos, c’est la différence entre une surface globale plate et un outillage par package qui s’active en contexte : un services/api/.claude/skills/ peut porter des skills spécifiques à API qui n’apparaissent que lorsque vous travaillez dans cet arbre, sans entrer en collision avec un skill services/web/ du même nom.

Architecture des hooks

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

Événements disponibles

Claude Code expose 29 événements de cycle de vie documentés dans huit catégories à la date de cette mise à jour du guide. La liste des événements s’enrichit au fil des versions ; considérez donc la documentation de référence comme la source de vérité et consultez la fiche mémo pour le tableau complet actuel avant de câbler des hooks de production :¹³

Sémantique des codes de sortie

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

Critique : chaque hook de sécurité doit utiliser exit 2, pas exit 1. Exit 1 est un avertissement non bloquant. La commande dangereuse s’exécute quand même. C’est l’erreur de hook la plus fréquente dans les équipes.¹⁴

Configuration des hooks

Les hooks vivent dans des fichiers de paramètres. Niveau projet (.claude/settings.json) pour les hooks partagés. 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 de tool, il correspond à des valeurs tool_name comme Bash, Edit, Write, Read, Glob, Grep, des noms de tools MCP comme mcp__server__tool, ou * pour tous les tools. Les noms simples et les listes séparées par | sont des correspondances exactes ; les valeurs contenant d’autres caractères sont des expressions régulières JavaScript. Certains événements ne prennent pas en charge les matchers et se déclenchent toujours lorsqu’ils sont configurés.¹³

Protocole d’entrée/sortie des hooks

Les hooks reçoivent du JSON sur stdin avec 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 du tool, injecter du contexte ou prendre des décisions de permission. Utilisez l’enveloppe hookSpecificOutput — l’ancien format de premier niveau decision/reason est déprécié 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 formateur après chaque changement de fichier. La sortie du modèle importe peu, puisque le formateur normalise tout.

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

Les garanties de sécurité empêchent les actions dangereuses avant leur exécution. Les hooks PreToolUse sur Bash inspectent les commandes et bloquent les 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 au-delà des commandes shell

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

Les command hooks (type: "command") exécutent des scripts shell. Rapides, déterministes, sans coût en tokens.

Les hooks de tool MCP (type: "mcp_tool") appellent un tool 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 séparé.

Les prompt hooks (type: "prompt") envoient un prompt à tour unique à un modèle Claude rapide. Le modèle renvoie { "ok": true } pour autoriser ou { "ok": false, "reason": "..." } pour bloquer. À utiliser pour les évaluations nuancées qu’une regex ne peut pas exprimer.

Les agent hooks (type: "agent") lancent un subagent avec accès aux tools (Read, Grep, Glob) pour une vérification multi-tour. 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 une sortie de test :

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

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

Les HTTP hooks (type: "http") envoient l’entrée JSON de l’événement sous forme de requête POST vers une URL et reçoivent du JSON en retour. À utiliser pour les webhooks, les services de notification externes ou la validation basée sur API (v2.1.63+). Non 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 l’asynchrone pour les notifications, la télémétrie et les sauvegardes. N’utilisez jamais l’asynchrone pour le formatage, la validation ou quoi que ce soit qui doit se terminer avant l’action suivante.

Dispatchers plutôt que hooks indépendants

Lancer sept hooks qui se déclenchent tous sur le même événement, chacun lisant stdin indépendamment, crée des conditions de concurrence. Deux hooks écrivant simultanément dans le même fichier d’état JSON tronqueront le JSON. Chaque hook aval qui analyse ce fichier casse.²

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

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

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

Déboguer les hooks

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

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

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

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

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

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

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

• effort.level dans l’entrée de hook. Les hooks reçoivent maintenant un champ JSON effort.level sur la même entrée qui transporte tool_input et session_id. La même valeur est exportée comme variable d’environnement $CLAUDE_EFFORT, ce qui permet aux commandes Bash de la lire sans analyser le JSON. Utilisez cela pour adapter le coût des hooks au niveau d’effort : ignorer la validation coûteuse sur low, exécuter le gate de sécurité complet sur xhigh ou max.
• Variable d’environnement CLAUDE_CODE_SESSION_ID sur les sous-processus Bash. Les sous-processus du tool Bash voient maintenant la même valeur session_id que les hooks, exposée sous CLAUDE_CODE_SESSION_ID. Cela comble l’écart de provenance pour les tools qui journalisent l’état par session et ne pouvaient auparavant pas corréler les événements de sous-processus avec les événements de hook.

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

autoMode.hard_deny et correctifs hook/plugin v2.1.136 (8 mai 2026)

Claude Code v2.1.136 a ajouté un nouveau niveau de refus strict à l’auto mode et corrigé un groupe de problèmes de plugins et de MCP qui affectaient les harnesses longue durée :⁴⁰

• settings.autoMode.hard_deny. Règles de classificateur d’auto mode qui bloquent inconditionnellement, indépendamment de l’intention utilisateur ou des exceptions d’autorisation. Cela se place au-dessus des matchers allow/deny existants comme levier de gouvernance non négociable. Utilisez-le pour les règles qui ne doivent jamais être contournées (force-push vers main, fichiers contenant des secrets, accès à la base de données de production), même lorsqu’un opérateur a approuvé la catégorie plus large dans ses paramètres personnels.
• 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 le SDK Agent. Le correctif arrive dans v2.1.136. Si vous avez vu « serveur MCP X disparu en pleine session », c’était la cause.
• Perte de refresh-token OAuth MCP lors d’un rafraîchissement concurrent. Les utilisateurs ayant plusieurs serveurs MCP distants ne devraient plus avoir besoin de se réauthentifier tous les jours. Les écritures de rafraîchissement concurrentes s’écrasaient mutuellement.
• Le mode plan bloque maintenant correctement les écritures de fichiers. Une règle d’autorisation Edit(...) correspondante contournait la protection d’écriture du mode plan. Le mode plan est maintenant appliqué indépendamment des règles d’autorisation.
• Les hooks Stop et UserPromptSubmit de plugin n’échouent plus en pleine session. Le nettoyage du cache supprimait des fichiers de version de plugin encore utilisés par la session en cours, ce qui cassait spécifiquement ces deux événements de hook. Le correctif garde les versions en cours d’utilisation épinglées.
• Entrée skills dans plugin.json. Définir skills masquait le dossier skills/ par défaut du plugin. Désormais, l’entrée se compose correctement, et la faire pointer vers un chemin de fichier génère une erreur explicite au lieu d’échouer silencieusement.
• Variables d’environnement de hook SessionStart CLAUDE_ENV_FILE qui devenaient obsolètes. Les variables exportées par les hooks SessionStart via CLAUDE_ENV_FILE devenaient obsolètes après /resume ou /clear. Corrigé dans v2.1.136. Les sessions re-sourcent maintenant le fichier d’environnement lors de ces événements.

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

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

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

Utilisez continueOnBlock lorsqu’un hook PostToolUse doit renvoyer sa raison de rejet à Claude et continuer le tour au lieu d’arrêter le flux. Considérez-le comme une fonctionnalité d’expérience opérateur, pas comme un contournement de sécurité. Un gate bloquant doit toujours bloquer le résultat dangereux.

La même version transmet CLAUDE_PROJECT_DIR aux serveurs stdio MCP et permet aux configurations de plugin de référencer ${CLAUDE_PROJECT_DIR} dans les commandes.⁴² Les tools MCP devraient résoudre les chemins relatifs au projet depuis cette valeur plutôt que depuis le répertoire de travail du processus qui a lancé le serveur.

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

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

Claude Code v2.1.142 est plus importante pour l’orchestration de sessions en arrière-plan que pour la sémantique des hooks.⁵¹ claude agents peut maintenant lancer des sessions en arrière-plan avec des flags explicites de dossier, paramètres, MCP, plugin, permission, modèle et effort au lieu de dépendre de l’état d’un wrapper. Le mode rapide utilise désormais Opus 4.7 par défaut ; épinglez CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE=1 uniquement si un harness a mesuré une dépendance au comportement d’Opus 4.6. La découverte de SKILL.md au niveau racine des plugins et la visibilité LSP fournie par les plugins réduisent l’ambiguïté de packaging. Les correctifs de MCP_TOOL_TIMEOUT, des worktrees de session en arrière-plan préexistants, du sommeil/réveil du daemon et du nettoyage post-mise à niveau, ainsi que du nettoyage du cache de plugins, ferment des lacunes de fiabilité qui ressemblent autrement à des bugs d’orchestration.

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

Quatre changements de début juin comptent pour la conception de harness et de multi-agent.⁵⁹

Les hooks Stop/SubagentStop ont gagné un canal de pilotage. Depuis Claude Code v2.1.163, un hook Stop ou SubagentStop peut renvoyer hookSpecificOutput.additionalContext pour donner du feedback à Claude et poursuivre le tour, sans que la réponse soit étiquetée comme une erreur de hook. Avant cela, le seul vrai levier d’un Stop hook était le blocage exit-2, qui apparaît comme une erreur et compte dans le plafond de blocages consécutifs. Pour un harness de quality gate, c’est une primitive plus propre : un Stop hook qui détecte « vous dites terminé, mais les tests sont rouges » peut maintenant injecter « voici ce qui échoue encore, continuez » au lieu de bloquer durement. Utilisez le blocage pour les véritables conditions d’arrêt et additionalContext pour « pas encore terminé, voici pourquoi ».

La messagerie inter-session ne transporte plus d’autorité empruntée. v2.1.166 a renforcé le cas multi-session : les messages relayés via SendMessage depuis une autre session Claude ne transportent plus l’autorité de l’utilisateur d’origine, de sorte qu’une session réceptrice refuse les demandes de permission relayées et que l’auto mode les bloque. Si votre orchestration fait s’envoyer des messages entre agents, traitez un message entrant comme des données non fiables, pas comme une instruction authentifiée. C’est le même principe que la section sécurité applique aux sorties de tools, étendu à la messagerie inter-agent.

La résilience du modèle est devenue un paramètre de premier ordre. Le paramètre fallbackModel enchaîne maintenant jusqu’à trois modèles de secours, essayés dans l’ordre lorsque le primaire est surchargé ou indisponible, et un tour réessaie automatiquement une fois sur le fallback en cas d’erreurs API inattendues non réessayables. Pour un harness autonome longue durée, cela transforme une panne transitoire du modèle primaire en dégradation progressive plutôt qu’en exécution abandonnée. claude agents --json a aussi ajouté un champ waitingFor (v2.1.162) qui expose ce qu’une session en arrière-plan bloquée attend, par exemple un prompt de permission — un gain d’observabilité pour tout coordinateur qui sonde une flotte d’agents.

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

Note sur les niveaux de modèles. Ce guide traite Opus 4.8 comme le défaut agentique de Claude Code — le modèle qui exécute les harnesses autonomes sauf choix contraire. Au 9 juin 2026, Anthropic a lancé Claude Fable 5 (claude-fable-5), un nouveau niveau au-dessus d’Opus décrit comme son modèle le plus puissant — un système « Mythos-class » rendu sûr pour un usage général — sélectionnable dans Claude Code v2.1.170 via /model claude-fable-5.⁶⁰ Opus 4.8 reste le défaut agentique ; utilisez le niveau supérieur délibérément, pour les décisions où la profondeur brute de raisonnement justifie le coût, pas comme paramètre global pour une flotte.

Codex a livré multi-agent v2. Codex CLI v0.137.0 conserve le choix du runtime avec chaque thread, expose des valeurs par défaut plus propres pour les suivis et les métadonnées des agents lancés (hide_spawn_agent_metadata vaut désormais true par défaut), et propage les événements parents bruts aux listeners enfants. Son modèle de subagent reste explicite : types d’agents intégrés default/worker/explorer, agents personnalisés définis en TOML, et contrôles de concurrence (agents.max_threads par défaut 6, agents.max_depth par défaut 1). La même version ajoute une extension skills v1 avec résolution du catalogue de skills à chaque tour et de nouveaux événements contributeurs de cycle de vie thread-start/turn-error, ce qui réduit l’écart avec la surface hook/skill de Claude Code tout en gardant la posture de sandbox noyau comme frontière par défaut. Codex v0.138.0–v0.139.0 a ensuite durci multi-agent v2 pour la production : les payloads de messages inter-agents sont maintenant chiffrés, un catalogue de configuration d’agents v2 plus un LRU de résidence d’agents gèrent quels agents restent résidents, et la concurrence est comptée par exécution active plutôt que par threads lancés, de sorte que les agents inactifs ne consomment plus de slot.⁶¹ Le cycle de vie API a mûri lui aussi — close_agent a été renommé interrupt_agent (v0.139.0) pour refléter qu’il interrompt un agent en cours d’exécution plutôt que de simplement fermer un handle — et les avertissements de démarrage MCP émis par un subagent restent maintenant limités au thread propriétaire au lieu de se dupliquer dans le transcript du parent.⁶¹ Pour toute personne qui construit une orchestration côté Codex, c’est la différence entre une démo et une flotte : transport de messages chiffré, résidence bornée, concurrence comptée par exécution, et avertissements qui ne fuient pas au-delà de la frontière du thread. Codex v0.140.0 a ensuite ouvert un passage inter-tool : /import importe sélectivement la configuration initiale, la configuration de projet et les chats récents depuis Claude Code vers Codex, et les sessions sont devenues supprimables définitivement (codex delete / /delete, avec protections de confirmation).⁶⁴ /import est la première reconnaissance officielle que les opérateurs passent d’un harness à l’autre — la configuration que vous construisez pour l’un n’y est plus enfermée.

Mémoire et contexte

Chaque conversation d’IA fonctionne dans une fenêtre de contexte finie. À mesure que la conversation s’allonge, le système compresse les tours précédents pour faire de la place au nouveau contenu. Cette compression entraîne des pertes. Des décisions d’architecture documentées au tour 3 peuvent ne pas survivre jusqu’au tour 15.⁹

Les trois mécanismes de l’effondrement multi-tours

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

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

La mémoire la plus fiable au-delà des limites de contexte se trouve 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 capture les erreurs, décisions et patterns d’une session à l’autre. Lorsque vous découvrez que ((VAR++)) échoue avec set -e dans bash quand VAR vaut 0, vous le consignez. Trois sessions plus tard, lorsque vous rencontrez un cas limite similaire sur un entier dans Python, l’entrée MEMORY.md fait remonter le pattern.¹⁵

Auto Memory (v2.1.32+) : Claude Code enregistre et rappelle automatiquement le contexte du projet. Pendant que vous travaillez, Claude écrit des observations dans ~/.claude/projects/{project-path}/memory/MEMORY.md. Auto memory charge les 200 premières lignes dans votre prompt système au démarrage de la session. Gardez-le concis et liez des fichiers thématiques séparés pour les notes détaillées.⁶

Curation de la mémoire plutôt que volume de mémoire (mai 2026) : une prépublication arXiv récente sur la coopération entre agents LLM présente le rappel élargi comme un mode de défaillance possible : dans les expériences des auteurs, un historique visible plus long a dégradé la coopération dans 18 des 28 configurations modèle-jeu.⁴⁸ Considérez cela comme un avertissement de conception, pas comme une loi définitive. La règle de production est déjà assez claire : gardez MEMORY.md court, créez des liens vers les détails et mettez des synthèses prêtes pour la décision dans les handoffs. Les dumps de transcriptions brutes, les journaux d’outils et les longs flux de rappel doivent rester dans un stockage consultable, pas être automatiquement injectés dans le prompt actif.

Stratégie 2 : compaction proactive

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

Quand compacter : - Après avoir terminé une sous-tâche distincte (fonctionnalité implémentée, bug corrigé) - Avant de commencer une nouvelle zone du codebase - Lorsque Claude commence à se répéter ou à oublier le contexte précédent - Environ toutes les 25 à 30 minutes pendant les sessions intensives

Instructions de compaction personnalisées dans CLAUDE.md :

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

La compaction protège la conversation ; la commande /cd (Claude Code v2.1.169) protège le prompt cache. Elle déplace une session vers un nouveau répertoire de travail en cours de route sans casser le cache accumulé pendant le tour.⁶⁰ Avant cela, changer de répertoire impliquait une nouvelle session et un cache froid. Pour une session longue qui pivote d’un dépôt vers un dépôt voisin — cas fréquent dans les monorepos et le travail multi-services — /cd conserve intact le préfixe coûteux mis en cache tout en repointant le contexte du système de fichiers.

Stratégie 3 : handoffs de session

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

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

La structure Status/Files/Decision/Blocked/Next fournit à la session suivante un contexte complet avec un coût minimal en tokens. Démarrer une nouvelle session avec claude -c (continue) ou lire le document de handoff mène directement à l’implémentation.¹⁵

Stratégie 4 : itération en contexte frais (la Ralph Loop)

Pour les sessions dépassant 60 à 90 minutes, lancez une nouvelle instance Claude à chaque itération. L’état persiste via le système de fichiers, pas via la mémoire conversationnelle. Chaque itération obtient le budget de contexte complet :¹⁶

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

Comparez 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 d’un contexte frais par itération échange 15 à 20 % de surcharge pour l’étape d’orientation (lecture des fichiers d’état, analyse de l’historique git) contre des ressources cognitives complètes à chaque itération.¹⁶ Le calcul coût-bénéfice : pour les sessions de moins de 60 minutes, une seule conversation est plus efficace. Au-delà de 90 minutes, le contexte frais produit une sortie de meilleure qualité malgré la surcharge.

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

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

Dreaming s’exécute en arrière-plan entre les sessions, pas sur le chemin critique. Il complète le pattern du système de fichiers comme mémoire plutôt que de le remplacer : votre fichier MEMORY.md reste la surface porteuse ; Dreaming écrit des entrées de mémoire organisées dans le store de mémoire des Managed Agents, que l’agent lit au démarrage de la session. Les deux patterns coexistent pour les harnesses qui combinent un état de système de fichiers auto-hébergé avec une curation côté managed.

Dreaming est en Research Preview, donc son comportement peut changer. Les patterns de handoffs de session et de CLAUDE.md documentés ci-dessus restent le mécanisme de mémoire faisant autorité pour les harnesses auto-hébergés.

Les anti-patterns

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

Garder une sortie d’erreur verbeuse dans le contexte. Après avoir débogué un bug, votre contexte contient plus de 40 stack traces issues d’itérations échouées. Un seul /compact après correction du bug libère ce poids mort.

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

Patterns de subagents

Les subagents sont des instances Claude spécialisées qui gèrent des tâches complexes de manière autonome. Ils démarrent avec un contexte propre (sans pollution issue de la conversation principale), fonctionnent avec des outils spécifiés et renvoient leurs résultats sous forme de résumés. Les résultats d’exploration ne gonflent pas votre conversation principale ; seules les conclusions reviennent.⁵

Types de subagents intégrés

Créer des 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 fonctionner dans des git worktrees temporaires, ce qui fournit une copie complète et isolée du dépôt :⁵

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

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

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

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 un résumé. Le contexte principal reste propre.

Le garde-fou de récursion

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

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

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

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

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

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

Leçon critique : 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 ignorent la largeur : 23 agents à la profondeur 1 restent à la « profondeur 1 ». Un budget de lancement suit le nombre total d’enfants actifs par parent, plafonné à un maximum configurable. Le modèle de budget correspond au mode d’échec réel (trop d’agents au total) plutôt qu’à une métrique indirecte (trop de niveaux d’imbrication).⁷

La délégation récursive est désormais une profondeur first-party. Depuis Claude Code v2.1.172 (10 juin 2026), les sub-agents peuvent lancer leurs propres sub-agents, avec une imbrication jusqu’à 5 niveaux — alors que la délégation était auparavant, en pratique, limitée à un seul niveau.⁶² Cela rend le garde-fou de récursion ci-dessus plus important, pas moins : la plateforme permet désormais exactement les chaînes d’agents qui délèguent à des agents et consomment contexte et tokens, de sorte que le budget de lancement et le plafond de profondeur sont ce qui empêche un arbre à 5 niveaux de s’étendre à des centaines d’agents actifs. Traitez les 5 niveaux comme un plafond autorisé par la plateforme, pas comme une valeur par défaut à viser.

Le mode auto évalue désormais les lancements avant leur démarrage. Claude Code v2.1.178 a comblé la faille de gouvernance correspondante : en mode auto, les lancements de subagents sont évalués par le classificateur d’autorisations avant le lancement du subagent, et non seulement une fois qu’il commence à agir.⁶³ Auparavant, un subagent pouvait être lancé pour demander une action que la session parente aurait été empêchée d’effectuer — le lancement lui-même servait de contournement. L’évaluation au moment du lancement signifie que le garde-fou de récursion et le modèle d’autorisations se rejoignent enfin : un enfant ne peut pas être utilisé comme étape de blanchiment pour une action interdite par la politique.

Agent Teams (aperçu de recherche)

Les Agent Teams coordonnent plusieurs instances Claude Code qui travaillent indépendamment, communiquent via une boîte aux lettres et une liste de tâches partagées, et peuvent contester les conclusions des autres :⁵

Activez avec : export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Quand utiliser les agent teams plutôt que les subagents :

Agent View et boucles de goal (mai 2026)

Claude Code v2.1.139 a ajouté Agent View, une interface en aperçu de recherche lancée avec claude agents, qui affiche depuis un seul écran les sessions Claude Code en cours, bloquées et terminées.⁴²⁴³ La documentation officielle la présente comme un moyen de répartir et gérer de nombreuses sessions, de voir ce que fait chaque session et d’identifier celles qui nécessitent l’intervention d’un opérateur.⁴³ Cela donne au travail multi-agent une vue opérationnelle que les résumés finaux ne peuvent pas fournir.

Utilisez Agent View lorsque vous promouvez un pattern de subagent ou d’équipe : inspectez quelles sessions sont bloquées, lesquelles sont encore en cours et si la distribution du travail correspond à l’architecture prévue. Ne le traitez pas comme une preuve de qualité. C’est de l’observabilité ; les tests, review gates et rapports de preuves décident toujours si le travail est solide.

La même version a ajouté /goal, qui définit une condition d’achèvement et permet à Claude de continuer sur plusieurs tours jusqu’à ce que la condition soit remplie, y compris en utilisation interactive, -p et Remote Control.⁴² Traitez /goal comme une boucle d’achèvement limitée à la session, pas comme un substitut aux gates déterministes. C’est utile pour garder un agent concentré sur une cible, mais les tests, vérifications de citations, contrôles de déploiement et security hooks doivent rester adossés à des commandes ou scripts lorsque l’échec doit bloquer.

Outil Workflow (v2.1.147+)

Claude Code v2.1.147 ajoute un outil Workflow, désactivé par défaut, pour l’orchestration multi-agent déterministe. Activez-le avec CLAUDE_CODE_WORKFLOWS=1.⁵² Sur le plan architectural, c’est important parce que cela donne à Claude Code une primitive d’orchestration first-party 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 autour. Un Workflow peut structurer l’exécution, mais il ne remplace pas votre modèle de sécurité. Conservez les hooks PreToolUse et PostToolUse comme couche bloquante, gardez des budgets de lancement ou des budgets d’étapes de workflow pour éviter une largeur incontrôlée, maintenez l’état du système de fichiers auditable et gardez les rapports de preuves finaux en dehors de l’auto-évaluation du modèle. En pratique : utilisez Workflow pour la forme de l’orchestration ; utilisez les hooks, les tests et les review gates pour la vérité.

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 est une politique opérationnelle pour un agent IA, pas un README destiné aux humains.²¹ L’agent n’a pas besoin de comprendre pourquoi vous utilisez les commits conventionnels. Il doit connaître la commande exacte à exécuter et savoir à quoi ressemble un état « terminé ».

La hiérarchie de précédence

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

Ce qui est ignoré

Ces schémas ne produisent de façon fiable aucun changement observable dans le comportement de l’agent :²¹

Paragraphes en prose sans commandes. « Nous valorisons un code propre et bien testé » relève de la documentation, pas de l’opérationnel. L’agent le lit puis écrit du code sans tests, car il n’y a aucune instruction actionnable.

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 downgrade est manquant. » en est une.

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

Guides de style sans application. « Suivez le Google Python Style Guide » sans ruff check --select D ne donne à l’agent aucun mécanisme pour vérifier la conformité.

Ce qui fonctionne

Instructions centrées sur 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 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 cet ordre de priorité :²¹

1. Commandes de build et de test (l’agent en a besoin avant de pouvoir faire quoi que ce soit d’utile)
2. Définition de terminé (évite les fausses déclarations d’achèvement)
3. Règles d’escalade (évite les contournements destructeurs)
4. Sections organisées par tâche (réduit l’analyse d’instructions non pertinentes)
5. Portée par répertoire (monorepos : garde les instructions de service isolées)

Ignorez les préférences de style jusqu’à ce que les quatre premières fonctionnent.

Imports 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’import : relative (@docs/file.md), absolue (@/absolute/path.md) ou répertoire personnel (@~/.claude/file.md). Profondeur maximale : 5 niveaux d’imports.⁶

Compatibilité des instructions entre outils

AGENTS.md est un standard ouvert reconnu par tous les grands outils de codage IA.²¹ Si votre équipe utilise plusieurs outils, rédigez AGENTS.md comme source canonique et répliquez les sections pertinentes dans les fichiers propres à chaque outil :

Les schémas dans AGENTS.md (centrés sur les commandes, définis par clôture, organisés par tâche) fonctionnent dans n’importe quel fichier d’instructions, quel que soit l’outil. Ne maintenez pas des jeux d’instructions parallèles qui divergent. Rédigez une source faisant autorité et répliquez-la.

Notes de parité Codex

Codex dispose désormais d’équivalents de premier ordre pour les principales couches de harness, mais la migration est une traduction de schémas, pas une copie de fichiers. Codex lit AGENTS.md avant le début du travail, en superposant les consignes globales de ~/.codex avec les instructions du projet et des dépôts imbriqués.³¹ Les skills Codex utilisent 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 ne charge la skill complète que lorsqu’il décide de l’utiliser.³² Codex dispose aussi de hooks natifs, de hooks inclus dans des plugins, de hooks gérés, de la prise en charge de MCP et de workflows explicites de subagents.³³³⁴

Codex v0.138.0–v0.139.0 a renforcé cette découverte d’AGENTS.md pour les espaces de travail non triviaux : le chargement passe désormais par l’abstraction du système de fichiers de l’environnement et préserve les chemins logiques pendant le parcours de découverte, afin que le bon fichier soit sélectionné même lorsque l’espace de travail est un système de fichiers distant ou une arborescence liée par symlink.⁶¹ C’est important chaque fois que votre AGENTS.md canonique est la source faisant autorité et que l’agent opère sur un checkout monté, matérialisé dans un conteneur ou lié par symlink — les cas où un parcours naïf des chemins choisit silencieusement le mauvais fichier d’instructions, ou aucun. Si vous répliquez un AGENTS.md faisant autorité entre plusieurs services, considérez cela comme le minimum requis pour avoir confiance dans le fait que le fichier réellement chargé par l’agent est 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 via des canaux Noise-relay authentifiés et chiffrés de bout en bout (le plan de contrôle et l’exécuteur ne font plus confiance au relais entre eux), l’exécution distante multiplateforme préserve le répertoire de travail et le shell natifs de l’exécuteur, et TLS accepte les signatures de certificat P-521 pour les proxys d’entreprise.⁶⁵ Si votre orchestration pilote des exécuteurs Codex à travers une frontière réseau, c’est la différence entre une hypothèse de relais de confiance et une hypothèse chiffrée de bout en bout : traitez-le comme la base de toute topologie d’exécuteur distant.

La correspondance pratique :

La différence importante : les subagents Claude peuvent être sélectionnés automatiquement à partir des descriptions, tandis que Codex documente actuellement les workflows de subagents comme explicites. Cela fait des skills et des hooks le choix par défaut adapté au comportement de harness toujours actif dans Codex ; les subagents conviennent au travail parallèle, à la review et à l’exploration délibérés.

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 build. S’il ne peut pas les reproduire mot pour mot, les instructions sont soit trop verbeuses (contenu repoussé hors du contexte), soit trop vagues (l’agent ne peut pas extraire d’instructions actionnables), soit non découvertes. L’analyse de GitHub portant sur 2 500 dépôts a montré que le flou cause la plupart des échecs.²¹

Patterns de production

Patterns à long horizon d’Opus 4.7 (avril 2026)

Claude Opus 4.7 (16 avril 2026) a été livré avec des capacités spécifiques qui changent ce contre quoi un harness doit se défendre :²⁹

• Résilience aux échecs d’outils : Opus 4.7 continue malgré des échecs d’outils qui interrompaient les sessions Opus 4.6. Vous pouvez réduire — sans les supprimer — les wrappers de relance défensive dans le code des subagents. Conservez les protections au niveau des hooks ; allégez l’échafaudage dans le prompt du type « si l’outil échoue, réessayez trois fois ».
• Niveau d’effort xhigh (Opus-4.7 uniquement) : Se situe entre high et max. Recommandé comme valeur par défaut pour les charges de travail de codage et agentiques. Sur les subagents de longue durée, xhigh surpasse nettement high avec un coût en tokens moins que proportionnel. max reste le bon choix pour un raisonnement difficile en une seule passe ; xhigh convient mieux aux tâches soutenues.
• Plafond de budget en tokens : Configurable par 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 en cours et cadre élégamment le travail en fonction du budget au lieu de tomber à court de manière inattendue. À utiliser pour les boucles agentiques où vous voulez des dépenses en tokens prévisibles sans sacrifier la qualité sur les prompts courts.
• Conscience des besoins implicites : Premier modèle Claude à réussir les tests « implicit-need » — reconnaître quand la demande littérale de l’utilisateur ne précise pas assez ce dont il a réellement besoin. Cela rend la section « règles de clarification » de CLAUDE.md moins nécessaire. Si votre CLAUDE.md contient 200 lignes de garde-fous du type « envisager aussi X quand l’utilisateur demande Y », élaguez ceux qui sont désormais couverts nativement.

Base de worktree, chemins de sandbox et paramètres admin (7 mai 2026)

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

Le retour en arrière de worktree.baseRef est celui à signaler aux utilisateurs : les agents qui dépendaient du comportement v2.1.128-v2.1.132 (worktrees branchés depuis le HEAD local) perdent l’accès au travail non poussé dans les nouveaux worktrees, sauf s’ils réactivent explicitement ce comportement.

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

Claude Code v2.1.136 a ajouté CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL pour réactiver l’enquête qualité en session pour les entreprises qui capturent les réponses via OpenTelemetry.⁴⁰ Si votre organisation envoie les événements OTel vers une pile d’observabilité centrale, cette variable d’environnement remet l’enquête dans le chemin de données afin que le signal qualité passe par le même pipeline que les métriques de latence et d’erreur. Traitez-la comme opt-in : par défaut, l’enquête reste supprimée, ce qui est correct pour les déploiements non OTel.

Le quality loop

Un processus de revue obligatoire pour tous les changements non triviaux :

1. Implémenter - Écrire le code
2. Relire - Relire chaque ligne. Repérer les fautes, les erreurs de logique, les sections peu claires
3. Évaluer - Exécuter l’evidence gate. Vérifier les patterns, les cas limites, la couverture de tests
4. Affiner - Corriger chaque problème. Ne jamais remettre à « plus tard »
5. Prendre du recul - Vérifier les points d’intégration, les imports et le code adjacent pour détecter les régressions
6. Répéter - Si un critère de l’evidence gate échoue, revenir à l’étape 4
7. Rapporter - Lister ce qui a changé, comment cela a été vérifié, citer des preuves précises

L’evidence gate

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

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

Autorité humaine de merge

Une étude arXiv de mai 2026 portant sur 29 585 cycles de vie de pull requests d’agents IA distingue l’agence opérationnelle de la gouvernance de merge.⁴⁷ La leçon d’architecture utile est simple : les agents peuvent démarrer le travail, faire avancer des branches, ouvrir des PR, relire le travail et résumer les risques, tandis que l’autorité de merge reste une frontière de gouvernance distincte.

Rendez cette frontière explicite dans le harness. Laissez les agents préparer les PR et collecter les preuves ; exigez une approbation humaine pour les merges, releases et opérations destructrices sur le dépôt, sauf si l’organisation dispose d’une politique d’automatisation auditée séparément. Lorsqu’une automatisation exécute un merge, conservez des journaux qui distinguent l’exécuteur de l’humain ou de la politique qui l’a autorisé.

Patterns de gestion des erreurs

Écritures de fichiers atomiques. Plusieurs agents écrivant simultanément dans le même fichier d’état corrompent JSON. Écrivez dans des fichiers .tmp, puis faites un mv atomique. L’OS garantit que mv est atomique sur le même système de fichiers.¹⁷

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

Récupération après corruption d’état. Si l’état est corrompu, le pattern de récupération recrée depuis des valeurs par défaut sûres au lieu de planter :¹⁶

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

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

Classification du rayon d’impact

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

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

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

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

OBJECTIVE: Implement multi-agent deliberation with consensus validation.

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

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

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

Modes d’échec à surveiller

Trace de session concrète

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

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

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

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

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

5. L’agent termine la story. Stop se déclenche. Les quality gates vérifient : l’agent a-t-il cité des preuves ? Langage de couverture ? Commentaires TODO dans le diff ? Si une vérification échoue, sortie 2 et l’agent continue.

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

7. Trois agents de revue de code apparaissent en parallèle. Chacun relit le diff indépendamment. Si un reviewer signale CRITICAL, la story revient dans la file.

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

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

Étude de cas : traitement nocturne de PRD

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

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

Considérations de sécurité

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

Anthropic a publié un cadre formel pour la fiabilité des agents le 9 avril 2026.²⁷ Ces cinq principes rejoignent — et prolongent — la logique d’Evidence Gate présentée dans ce guide :

Anthropic a également donné MCP à l’Agentic AI Foundation de la Linux Foundation, rejoignant AGENTS.md (désormais cogéré avec OpenAI, Google, Cursor, Factory, Sourcegraph). Les standards d’interopérabilité des agents sont maintenant neutres vis-à-vis des fournisseurs.²⁷

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

Le sandbox

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

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

Verrouillage du sandbox OpenAI Agents SDK (v0.17.0, 8 mai 2026). Côté OpenAI, openai-agents-python v0.17.0 a renforcé une frontière parallèle : LocalFile.src et LocalDir.src sont désormais limités au base_dir de matérialisation (le répertoire de travail courant du processus SDK lorsque le manifeste est appliqué), sauf si la source est explicitement accordée via Manifest.extra_path_grants avec SandboxPathGrant.⁴¹ Les sources locales relatives se résolvent depuis base_dir ; les chemins absolus doivent déjà s’y trouver ou disposer d’un grant. Cela ferme un problème de frontière d’artefact local : les versions précédentes permettaient aux manifestes d’importer des chemins hôtes arbitraires dans un espace de travail sandbox. Migration : déclarez les racines hôtes de confiance au niveau du manifeste avec SandboxPathGrant(path=..., read_only=True) pour les montages en lecture seule. Traitez extra_path_grants comme une configuration applicative de confiance ; ne renseignez jamais les grants à partir de la sortie du modèle ou d’une entrée de manifeste non fiable.

Plancher de suivi OpenAI Agents SDK (v0.17.3). La série 0.17.1-0.17.3 a ajouté davantage de durcissement du sandbox et des sessions : limites d’extraction d’archives, validation des sous-chemins GitRepo, erreurs de fournisseur de sandbox plus claires, credentials de point de montage tenus hors des commandes sandbox, rejet des racines relatives d’espace de travail sandbox et gestion de l’état terminal Vercel-sandbox.⁵⁴ Si vous utilisez des sandboxes hébergés par OpenAI ou adossés à un fournisseur, et pas seulement les hooks Claude Code, considérez 0.17.3 comme le plancher actuel pour les modèles de cette section.

Limites de permission

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

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

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

Un paramètre géré associé, enforceAvailableModels (v2.1.175), contraint la sélection de modèles de haut en bas : il fixe le modèle Default et empêche les paramètres définis au niveau utilisateur ou projet d’élargir l’allowlist gérée availableModels.⁶³ Les deux se composent : l’allowlist définit les paliers disponibles pour toute la session, et les règles au niveau des paramètres contraignent la manière dont les subagents y puisent.

Garde-fous d’Auto Mode pour les commandes destructrices (juin 2026)

Claude Code v2.1.183 a réduit le rayon d’impact d’auto mode pour les opérations qui peuvent perdre du travail en silence ou démanteler des environnements. Auto mode bloque désormais strictement, sauf si vous les avez explicitement demandées dans la session : les opérations git destructrices (git reset --hard, git checkout -- ., git clean -fd, git stash drop) ; git commit --amend lorsque le commit n’a pas été fait par l’agent dans cette session ; et les destructions d’infrastructure (terraform destroy, pulumi destroy, cdk destroy) sauf si vous avez nommé la stack précise.⁶⁵ Sur le plan architectural, c’est le complément du contrôle de lancement et des règles au niveau des paramètres ci-dessus : plutôt que de contrôler quel outil ou comment il est lancé, cela contrôle un petit ensemble de commandes irréversibles spécifiques par l’intention — l’agent peut toujours les exécuter, mais uniquement sur instruction explicite, pas de sa propre initiative. Pour un harness autonome, encodez le même principe dans vos propres hooks PreToolUse : les commandes qui détruisent l’état méritent une règle deny-by-default que seul un signal explicite de l’opérateur peut lever.

Défense contre l’injection de prompt

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

Les skills avec 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é prompté :

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

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

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

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

La règle de production : traitez les transcriptions d’agents, les tool payloads, les journaux SQLite et l’exécution des guardrails comme une infrastructure sensible. Expurgez avant la persistance, appliquez des limites de rétention et gardez le code de guardrail personnalisé sandboxé et révisable. Une règle au niveau du prompt du type « ne journalisez pas les secrets » ne suffit pas ; le chemin de journalisation et de guardrail a besoin de tests déterministes.

Sécurité des hooks

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

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

La répartition des responsabilités entre humain et agent

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

Le modèle : les humains possèdent les décisions qui nécessitent un contexte organisationnel, un jugement éthique ou une direction stratégique. Les agents possèdent les décisions qui nécessitent une recherche computationnelle dans de vastes espaces de possibilités. Les hooks font respecter la frontière.

Application récursive des hooks

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

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

Le coût comme architecture

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

Niveau tokens. Compression du prompt système. Supprimez les exemples de code didactiques (le modèle connaît les APIs), fusionnez les règles dupliquées entre fichiers et remplacez les explications par des contraintes. « Rejeter les appels d’outils correspondant à des chemins sensibles » fait le même travail qu’une explication de 15 lignes sur les raisons pour lesquelles les credentials ne doivent pas être lus.

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

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

Cadre de décision

Quand utiliser chaque mécanisme :

Skills vs Hooks vs Subagents

FAQ

Combien de hooks, est-ce trop ?

La contrainte, c’est la performance, pas le nombre. Chaque hook s’exécute de manière synchrone ; le temps total d’exécution des hooks s’ajoute donc à chaque appel d’outil correspondant. 95 hooks répartis entre paramètres utilisateur et paramètres projet s’exécutent sans latence perceptible lorsque chaque hook se termine en moins de 200 ms. Le seuil à surveiller : si un PostToolUse hook ajoute plus de 500 ms à chaque modification de fichier, la session semble 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 la raison du refus et suggère une alternative plus sûre. La sortie 1 est 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 à tous les projets). 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 délibération ?

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 délibération, soit environ 10 % du total des décisions. Les corrections de documentation, renommages de variables et modifications courantes ignorent entièrement la délibération. L’architecture de sécurité, les changements de schéma de base de données et les déploiements irréversibles la déclenchent systématiquement.⁷

Comment tester un système conçu pour produire du désaccord ?

Testez à la fois les chemins de réussite et 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 délibération 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 délibération sur la latence ?

Une délibération à 3 agents ajoute 30 à 60 secondes de temps réel (les agents s’exécutent séquentiellement via l’Agent tool). Une délibération à 10 agents ajoute 2 à 4 minutes. Les hooks de consensus et de pride check s’exécutent chacun en moins de 200 ms. Le principal goulot d’étranglement est le temps d’inférence LLM par agent, pas le surcoût d’orchestration.⁷

Quelle longueur doit faire un fichier CLAUDE.md ?

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

Carte 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 de fichiers

Journal des modifications

Références