Claude Code 2.1.310 : erreurs de passerelle et hooks Windows

Si Claude Code échoue via une passerelle avec Unexpected value(s) mentionnant effort-2025-11-24, ou avec Unexpected role "system", passez à la version 2.1.310 ou ultérieure, puis réessayez dans la conversation concernée. Les équipes sous Windows doivent aussi vérifier qu’un échec de l’interpréteur d’un hook bloque effectivement l’appel à un outil. Si des images collées ont disparu alors que cleanupPeriodDays avait une valeur extrême, préservez les données restantes avant de modifier la durée de conservation.

Au 2026-10-25, les notes officielles de la version 2.1.310 confirment les corrections de ces problèmes de passerelle, de hooks Windows et de nettoyage. Les procédures suivantes traitent chaque défaillance séparément.

Vérifiez que l’exécutable actif est en version 2.1.310 ou ultérieure

Identifiez l’exécutable lancé par votre terminal, puis mettez-le à jour avec la méthode d’installation que vous utilisez déjà. Dans Bash, ou sans modification dans Windows PowerShell, exécutez :

claude --version
claude doctor

claude doctor fournit des diagnostics en lecture seule sur l’installation et les paramètres. Conservez la sortie indiquant la version pour pouvoir la comparer après la mise à jour.

Utilisez la commande adaptée, tirée des instructions d’installation et de mise à jour d’Anthropic :

Installation existante	Shell	Commande de mise à jour
Programme d’installation natif	Bash ou PowerShell	`claude update`
Cask stable de Homebrew	Bash	`brew upgrade claude-code`
Cask latest de Homebrew	Bash	`brew upgrade claude-code@latest`
WinGet	PowerShell	`winget upgrade Anthropic.ClaudeCode`
npm	Bash ou PowerShell	`npm install -g @anthropic-ai/claude-code@latest`

Les mises à jour natives suivent le canal de publication configuré. Le cask Homebrew claude-code suit stable, tandis que claude-code@latest suit latest : une mise à jour peut donc réussir tout en vous laissant sur une version inférieure à celle requise.

Pour une installation native existante, la CLI permet aussi d’installer une version précise avec claude install 2.1.310. Pour un déploiement géré par paquets, choisissez un paquet ou un canal qui fournit la version requise, en suivant le processus habituel de ce déploiement.

Exécutez de nouveau claude --version, puis démarrez une nouvelle session Claude Code. Si une ancienne version apparaît toujours, recherchez des installations en conflit avec which -a claude dans Bash ou where.exe claude dans PowerShell. Si vous utilisez le terminal d’un éditeur, il peut aussi être nécessaire de redémarrer l’éditeur pour qu’il prenne en compte la modification de PATH.

Associez l’erreur de passerelle au mécanisme de reprise prévu

Choisissez la correction d’après le texte de l’erreur reçue. Un simple 400 ne permet pas de savoir quelle capacité la passerelle a rejetée.

Le guide de compatibilité des passerelles d’Anthropic décrit les mécanismes de reprise suivants :

Signature de la réponse	Repli automatique	Point à vérifier
`400` commençant par `Unexpected value(s)` et mentionnant `effort-2025-11-24` pour `anthropic-beta`	Omet le champ effort et la beta pour ce modèle jusqu’à la fermeture de Claude Code.	Supprimez cette valeur si vous l’avez ajoutée manuellement à `ANTHROPIC_BETAS`.
`400` mentionnant `output_config.effort` avec `Extra inputs are not permitted`, ou indiquant qu’effort n’est pas pris en charge	Applique le mécanisme de repli sans effort.	Confirmez qu’effort est bien le champ rejeté.
`400`, par exemple `Unexpected role "system"`	Déplace le texte système inséré au milieu de la conversation dans des messages utilisateur ; conserve ce format jusqu’à `/clear` ou au compactage du contexte.	Réessayez dans la conversation concernée.

Ce mécanisme de repli modifie la requête. Le paramètre effort contrôle la manière dont le modèle dépense ses tokens : une nouvelle tentative réussie sans ce paramètre ne prouve donc pas que le niveau d’effort demandé a été respecté. De même, déplacer du texte système dans des messages utilisateur préserve le texte, mais change sa représentation.

Reproduisez le problème dans la même conversation

Conservez la même passerelle, la même source d’identifiants et le même modèle sélectionné pendant la vérification de la mise à jour. La comparaison sera ainsi exploitable : changer simultanément de fournisseur et de version laisserait la cause incertaine.

Commencez par lancer Claude Code et exécuter /status. Les instructions de connexion à une passerelle expliquent comment y confirmer l’URL de base active et la source des identifiants. Si la passerelle attendue n’apparaît pas, corrigez cette configuration avant d’examiner sa prise en charge de la beta.

Quittez ensuite la session et rouvrez la conversation concernée avec un journal de diagnostic local. Dans Bash :

claude --resume --debug-file ./claude-gateway-debug.log

Choisissez la session en échec dans le sélecteur et répétez la plus petite requête qui reproduit le problème. Ces options sont décrites dans la référence de la CLI.

La vérification immédiate consiste à obtenir une réponse exploitable de l’assistant là où la requête précédente échouait. Pour établir que le repli de compatibilité a permis cette reprise, examinez les diagnostics disponibles du client et, si vous y avez accès, ceux des requêtes de la passerelle : recherchez le rejet suivi d’une nouvelle tentative ajustée. La réussite du premier prompt d’une nouvelle conversation ne teste pas toutes les structures que la conversation pourra prendre ensuite.

Pour BetterToken, les instructions de configuration de Claude Code indiquent ANTHROPIC_BASE_URL=https://bettertoken.ai, sans /v1 ; conservez cette adresse documentée pendant la vérification de la mise à jour du client.

Si le client mis à jour échoue encore

Conservez le corps des erreurs renvoyées par le service en amont : remplacer un rejet reconnaissable par une erreur opaque de la passerelle peut empêcher le client de détecter le besoin de repli. Par ailleurs, CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 conserve effort et les entrées système au milieu de la conversation ; ce n’est donc pas un interrupteur universel pour résoudre ces échecs.

Choisissez la prochaine action selon les éléments observés :

Le même rejet reconnu se répète : vérifiez l’exécutable actif, les valeurs beta ajoutées manuellement et si la passerelle réécrit l’erreur du service en amont.
L’authentification échoue : suivez les instructions de la passerelle concernant les identifiants. Le guide de connexion distingue ANTHROPIC_AUTH_TOKEN pour l’authentification Bearer de ANTHROPIC_API_KEY pour x-api-key ; utilisez le mécanisme documenté par votre fournisseur.
L’erreur mentionne un autre champ : examinez les exigences de compatibilité de ce champ. N’attribuez pas tous les rejets de schéma au problème d’effort.
La connexion échoue avant l’arrivée d’une réponse de l’API : examinez l’endpoint, le proxy, DNS ou la connexion TLS.

Pour transmettre le problème au support, rassemblez la version du client, le système d’exploitation, l’ID du modèle sélectionné, l’heure ou l’ID de la requête, le statut HTTP et l’erreur exacte. Partagez un extrait de diagnostic dont les données sensibles ont été retirées, plutôt que des identifiants ou le journal complet de la conversation.

Vérifiez que les hooks Windows bloquent réellement les appels

Passez au minimum à 2.1.310, puis testez le comportement en cas d’échec des hooks sur lesquels repose l’application de vos politiques. Les deux versions consécutives corrigent des situations différentes :

La 2.1.309 corrige la gestion des codes de sortie des hooks PowerShell et les échecs liés à l’absence de Git lorsque les hooks sélectionnent explicitement PowerShell.
La 2.1.310 corrige le cas supplémentaire où Git Bash est absent et où la commande du hook ne contient que des chaînes entre guillemets.

Une erreur de hook ne constitue pas automatiquement un refus. La référence des hooks fournit onFailure: "block" pour les hooks de commande et HTTP qui doivent interrompre l’action déclenchante lorsqu’ils échouent.

Vérifiez la régression des commandes entre guillemets

Utilisez un environnement de test Windows natif que vous pourrez supprimer ensuite, sans Git Bash, avec une connexion Claude Code fonctionnelle et sans hooks ni plugins étrangers au test qui pourraient influencer le résultat. Vous vérifierez ainsi le cas où Git Bash est absent sans retirer Git de votre machine de travail.

Dans PowerShell, créez un nouveau répertoire de test et un fichier inoffensif :

$hookProbe = Join-Path $env:TEMP ("claude-hook-probe-" + [guid]::NewGuid().ToString("N"))
New-Item -ItemType Directory -Path (Join-Path $hookProbe '.claude') -Force | Out-Null
Set-Location $hookProbe
Set-Content -LiteralPath .\probe.txt -Value ([guid]::NewGuid().ToString())
Test-Path 'C:\__claude_hook_probe_missing__\python.exe'
claude --version

Test-Path doit renvoyer False, et la version doit être au moins 2.1.310.

Dans ce répertoire de test, créez .claude/settings.local.json avec le contenu suivant :

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read",
        "hooks": [
          {
            "type": "command",
            "command": "\"C:\\__claude_hook_probe_missing__\\python.exe\""
          }
        ]
      }
    ]
  }
}

L’absence des champs shell, args et onFailure est volontaire : cette phase examine le mécanisme de repli propre à la commande entre guillemets.

Démarrez la session dans PowerShell :

claude --tools Read --debug-file .\phase1.log

Acceptez de faire confiance à l’espace de travail pour ce répertoire temporaire, puis exécutez /hooks et confirmez que le hook PreToolUse correspond à Read. Demandez :

Utilise l’outil Read exactement une fois pour lire probe.txt. Si l’appel est bloqué, signale-le et arrête-toi. N’utilise aucune autre méthode.

Résultat attendu : l’appel à Read est bloqué, avec PowerShell started no program dans l’erreur ou les diagnostics. PowerShell évalue normalement un chemin entre guillemets comme une chaîne ; la documentation de Microsoft sur l’opérateur d’appel explique pourquoi l’exécution de ce chemin nécessite une autre syntaxe.

Si Read réussit effectivement à lire le fichier, le test a échoué. Si Claude ne tente jamais d’appeler Read, le résultat n’est pas concluant. Examinez le résultat de l’outil et le journal, sans considérer la description du modèle comme une preuve suffisante.

Si /hooks n’affiche pas la configuration, suivez les vérifications de chargement des hooks. Les paramètres sont normalement rechargés automatiquement, mais un redémarrage force leur relecture si la surveillance des fichiers a manqué la modification. Si une politique administrée n’autorise que les hooks administrés, ce test au niveau du projet n’a pas non plus été exécuté.

Vérifiez le cas d’un interpréteur réellement absent

Définissez explicitement la politique à appliquer en cas d’échec pour vérifier ce qui se passe lorsque l’interpréteur ne peut pas démarrer. Quittez la session de test et remplacez uniquement l’objet interne du hook par :

{
  "type": "command",
  "command": "C:\\__claude_hook_probe_missing__\\python.exe",
  "args": [],
  "onFailure": "block"
}

Ici, args sélectionne l’invocation directe de l’exécutable. L’absence de cet exécutable provoque désormais un véritable échec de lancement, au lieu de l’évaluation d’une expression contenant une chaîne entre guillemets.

Relancez la session dans PowerShell et répétez la même demande pour Read :

claude --tools Read --debug-file .\phase2.log

Résultat attendu : Read est bloqué parce que l’interpréteur n’a pas pu démarrer. Cette étape vérifie la gestion explicite des échecs indépendamment de la disponibilité de Git Bash ; elle est distincte du test de régression de la commande entre guillemets.

Après avoir examiné les résultats, supprimez la configuration de test. Dans les hooks qui appliquent vos politiques réelles, rétablissez l’interpréteur fonctionnel et conservez une politique explicite de blocage lorsqu’un contrôle en échec doit arrêter l’action.

Ces tests couvrent PreToolUse. Un hook PermissionRequest nécessite une vérification séparée avec une action qui atteint l’étape de demande d’autorisation. Son refus normal utilise hookSpecificOutput.decision.behavior avec la valeur "deny" ; le code de sortie 2 ne refuse pas, à lui seul, cet événement. Un échec réel avec onFailure: "block" refuse bien la demande.

Remplacez les valeurs extrêmes par une durée de conservation choisie

Utilisez la valeur par défaut documentée de 30 jours, sauf si votre équipe a un besoin précis de conservation, et archivez l’historique souhaité avant de raccourcir une durée existante.

La correction du nettoyage traite la suppression de fichiers récents associée à des valeurs extrêmement élevées de cleanupPeriodDays. Elle ne transforme pas ce paramètre en système d’archivage et ne restaure pas les fichiers déjà supprimés.

Préservez les données restantes avant de modifier la durée

Arrêtez les sessions actives et copiez les données dont vous avez encore besoin dans un emplacement extérieur aux répertoires gérés par Claude Code. Incluez les données pertinentes de ~/.claude, ou de %USERPROFILE%\.claude sous Windows, ainsi que les images jointes encore présentes.

La documentation actuelle sur les données de l’application place les nouvelles images collées dans des répertoires images/ propres à chaque session, sous la racine temporaire de Claude Code contrôlée par CLAUDE_CODE_TMPDIR. Sauvegarder uniquement ~/.claude ne permet donc pas d’établir que les copies actuelles des images ont été préservées.

Une fois les données sauvegardées, ajoutez ce paramètre au fichier de configuration approprié :

{
  "cleanupPeriodDays": 30
}

Pour définir votre valeur par défaut personnelle, ce fichier est ~/.claude/settings.json, ou %USERPROFILE%\.claude\settings.json sous Windows. Préservez les autres clés.

D’après la documentation au 2026-10-25, le minimum est 1 ; 0 échoue à la validation. Réduire la durée rend les données plus anciennes susceptibles d’être supprimées lors du nettoyage, d’où la nécessité de les préserver au préalable.

Exécutez claude doctor pour vérifier la validité des paramètres. Si la valeur souhaitée ne s’applique pas, examinez la priorité des paramètres : les paramètres administrés et les paramètres de session ou de projet de priorité supérieure peuvent prévaloir sur votre fichier personnel. /status affiche les sources chargées, pas la valeur effective de chaque clé.

Récupérez séparément les pièces jointes manquantes

Restaurez une image manquante depuis son fichier d’origine ou une sauvegarde existante du système de fichiers, puis joignez cette copie récupérée à la conversation. Vérifiez que le fichier s’ouvre localement et que Claude peut de nouveau utiliser la pièce jointe.

Changer la durée de conservation ne peut pas reconstruire les octets supprimés. Ne supposez pas non plus que /rewind récupérera une pièce jointe : les instantanés des points de contrôle expirent également, et la restauration peut échouer si les instantanés nécessaires ont disparu.

Si votre équipe exporte déjà la télémétrie, examinez un événement claude_code.retention_sweep terminé. La référence de supervision documente result: "complete" et un period_days de type chaîne ; "30" confirme que cette exécution précise du nettoyage utilisait une durée de 30 jours.

Un bref redémarrage ne suffit pas à prouver que le nettoyage a eu lieu. Celui-ci s’exécute en arrière-plan au maximum une fois par session, et une exécution au cours des 24 heures précédentes retarde d’au moins 10 minutes celle de la session suivante. Considérez la possibilité d’ouvrir les pièces jointes et la preuve d’un nettoyage terminé comme deux observations distinctes.

La disponibilité de Monitor constitue un changement séparé

La version 2.1.310 étend aussi l’outil Monitor et les moniteurs de plugins à Bedrock, Vertex et Foundry, y compris lorsque la télémétrie ou le trafic non essentiel sont désactivés. Les notes de version indiquent également que les longues attentes au premier plan sont bloquées dans ces environnements.

Si Monitor était absent dans l’un de ces déploiements, vérifiez la version en cours d’exécution avant de modifier la politique de télémétrie. Ce changement de disponibilité est indépendant de l’acceptation, par une passerelle donnée, des paramètres effort ou des entrées système au milieu de la conversation.