Claude Code en automatisation : surveiller l'expiration de connexion et bloquer les hooks défaillants

Un cron lancé à 3 h du matin doit produire un rapport client. À 8 h, le fichier est là, mais vide. Personne n'a reçu d'erreur, le script n'a rien signalé, et la session Claude Code qui tournait derrière avait expiré dans la nuit. Si tu pilotes Claude Code depuis une routine automatisée, ce scénario est possible, et il se règle avec quelques réflexes simples que cet article détaille. Pour la vue d'ensemble de l'outil, le guide complet pour apprendre Claude pose les bases.

En bref :

• En mode non interactif (claude -p), personne ne peut se reconnecter à ta place : teste explicitement le code de sortie et la présence d'un résultat.
• Depuis la version 2.1.318 de Claude Code (4 novembre 2026), claude auth status affiche la date de fin de la connexion claude.ai (loginExpiresAt) et les résultats JSON de claude -p incluent credential_expires_at.
• Dès 10 jours avant l'expiration, claude -p écrit lui-même un avertissement sur stderr : il suffit de ne pas le jeter.
• Depuis la version 2.1.317 (3 novembre 2026), les hooks de l'Agent SDK acceptent onFailure: "block" : un callback en échec bloque l'action au lieu de la laisser passer.
• Fail-closed pour ce qui est irréversible, fail-open pour la journalisation, sinon une simple notification peut stopper tout le pipeline.

Pourquoi une automatisation Claude Code s'arrête-t-elle sans prévenir ?

Parce qu'en mode non interactif il n'y a personne pour se reconnecter ni pour lire un message d'erreur. Une connexion expirée ou un hook qui plante fait tomber la tâche, et si ton script n'inspecte ni le code de sortie ni stderr, il continue comme si de rien n'était : le rapport vide de 3 h du matin vient de là.

Deux risques distincts, donc, et l'article les traite dans cet ordre. Le premier est l'expiration de la connexion, prévisible si on la surveille. Le second est le hook silencieux : un contrôle censé protéger une action (écrire un fichier, envoyer un email, déployer) qui échoue sans rien bloquer, et l'action part quand même, sans le contrôle prévu. Le premier te laisse sans résultat, le second te laisse avec un résultat que personne n'a vérifié, ce qui est souvent pire.

Comment fonctionne claude -p quand la connexion expire ?

claude -p exécute une requête unique sans interface. Sans interface, il n'y a personne pour se reconnecter : c'est à ton script de tester le code de sortie et le contenu produit. Vérifie dans la documentation officielle de Claude Code le détail des codes de sortie de ta version avant de t'appuyer dessus.

Deux modes d'authentification coexistent. La connexion à ton compte claude.ai (abonnement) a une date de fin, c'est celle que la version 2.1.318 rend visible. Une clé API, elle, est facturée à la consommation, et ne dépend pas d'un cycle de session de ce type. Pour une routine qui tourne sans supervision, la clé API est en général le choix le plus stable, au prix d'une facture à l'usage au lieu des limites d'un abonnement (Claude Pro à partir de 20 € par mois par exemple). Si tu restes sur l'abonnement, la suite de l'article est faite pour toi.

Le minimum à faire dans un script : tester le code de sortie, journaliser stderr, et ne jamais enchaîner l'étape suivante sur une sortie vide.

#!/usr/bin/env bash
set -u
LOG="$HOME/logs/rapport-client.log"
mkdir -p "$(dirname "$LOG")"

claude -p "Génère le rapport client du jour" > rapport.md 2> erreurs.txt
CODE=$?

if [ "$CODE" -ne 0 ] || [ ! -s rapport.md ]; then
  echo "$(date -Iseconds) ECHEC code=$CODE" >> "$LOG"
  cat erreurs.txt >> "$LOG"
  # ici : envoi d'une alerte (email, Slack)
  exit 1
fi

Le test [ ! -s rapport.md ] attrape précisément le cas du fichier vide. Sans lui, un code de sortie à 0 combiné à une sortie vide passerait inaperçu.

Comment surveiller credential_expires_at avant que ça casse ?

En lisant la date de fin de ta connexion avant chaque exécution, puis en alertant sous un seuil que tu choisis (48 heures donne le temps de réagir un vendredi soir). Deux sources officielles, toutes deux ajoutées par la version 2.1.318 de Claude Code : la commande claude auth status, qui affiche la date de fin de la connexion claude.ai enregistrée (loginExpiresAt), et les résultats JSON de claude -p, qui incluent credential_expires_at.

Il y a aussi un filet de sécurité intégré : à partir de 10 jours avant l'expiration, claude -p écrit un avertissement sur stderr. Si ton script redirige stderr vers /dev/null, tu te prives d'une alerte gratuite. Mieux vaut le conserver dans un fichier et le surveiller.

Voici un contrôle à planifier avant le job principal. Il demande la sortie JSON de claude auth status, lit la date et alerte sous 48 heures. Je ne garantis ni le drapeau JSON de cette commande ni le nom exact du champ dans ta version : lance d'abord claude auth status à la main et adapte la ligne jq à ce que tu vois.

#!/usr/bin/env bash
SEUIL_HEURES=48

# À adapter : vérifie la sortie réelle de `claude auth status` sur ta version
FIN=$(claude auth status --json 2>/dev/null | jq -r '.loginExpiresAt // empty')

if [ -z "$FIN" ]; then
  echo "Date d'expiration introuvable : contrôle à revoir" >&2
  exit 2
fi

RESTE=$(( ( $(date -d "$FIN" +%s) - $(date +%s) ) / 3600 ))

if [ "$RESTE" -lt "$SEUIL_HEURES" ]; then
  echo "Connexion Claude Code : il reste ${RESTE} h" \
    | mail -s "Reconnexion Claude à prévoir" toi@exemple.fr
  exit 1
fi

L'option date -d suppose un système Linux ; sur macOS la syntaxe diffère. L'ordre compte : ce contrôle passe avant le job principal. Placé après, l'alerte arrive quand la tâche est déjà perdue.

Comment bloquer une action quand un hook échoue ?

En déclarant le hook en fail-closed : si le callback échoue, l'action est bloquée au lieu de s'exécuter. Depuis la version 2.1.317 de Claude Code (3 novembre 2026), les hooks de l'Agent SDK acceptent onFailure: "block" pour ça. Sans cette option, ne suppose pas qu'un hook en échec retient l'action : vérifie-le par un essai.

Un hook de type PreToolUse s'exécute avant l'outil. C'est l'endroit où l'on place un contrôle : refuser l'écriture hors du dossier du projet, valider un montant, vérifier qu'un fichier n'est pas déjà publié. Vérifie dans la documentation des hooks de Claude Code la syntaxe exacte de onFailure pour ta version : je n'ai pas validé de configuration réelle, donc je n'en propose pas ici. Retiens le principe : si le contrôle plante (script supprimé, dépendance manquante, délai dépassé), tu perds une exécution, mais tu ne laisses pas passer une action que personne n'a contrôlée. Et si tu veux limiter les écritures à ton projet sans écrire de hook, le réglage décrit dans cet article sur le blocage des écritures hors du projet couvre ce cas précis pour Write, Edit et NotebookEdit.

Autre point à connaître dans la même famille : la version 2.1.317 corrige deux bugs de claude -p. Il sortait avec le code 0 après des échecs d'écriture, et pouvait partager son identifiant de session avec le runner parent. Si ton script de supervision ne détectait pas certains échecs avant la mise à jour, c'est peut-être pour cette raison. Un réglage CLAUDE_CODE_DISABLE_NESTED_SESSION_ID existe pour les runners auto-hébergés.

Fail-open ou fail-closed : lequel choisir pour chaque type de hook ?

Fail-closed pour tout ce qui touche à l'irréversible (suppression, envoi, paiement, déploiement). Fail-open acceptable pour la journalisation et les notifications non critiques. Le critère à se poser : si ce hook disparaissait demain, que se passerait-il de grave ?

L'erreur inverse existe et elle est tout aussi pénible. Imagine un hook qui poste un message Slack à la fin de chaque tâche, réglé en fail-closed par prudence excessive : le jour où Slack a une panne, tout le pipeline s'arrête alors qu'aucune donnée n'était en danger. La correction est de reclasser ce hook en fail-open et de garder le blocage pour ceux qui protègent une action sensible. Un blocage à bon escient rassure, un blocage partout finit par te faire désactiver les hooks, ce qui ruine l'intérêt de la démarche.

Quelle checklist avant de lancer une automatisation Claude Code en production ?

Une liste courte, à valider dans l'environnement réel (pas sur ton poste de test) avant la première exécution non supervisée.

• L'authentification est testée là où la routine tournera : même machine, même utilisateur système, même variables d'environnement.
• Le contrôle d'expiration est planifié avant le job principal, avec un seuil d'alerte (48 heures proposé plus haut).
• Le code de sortie de claude -p est testé, et une sortie vide est traitée comme un échec.
• stderr est conservé dans un fichier de log, pas jeté, pour recevoir l'avertissement des 10 jours.
• Les hooks qui protègent une action irréversible sont en onFailure: "block" ; ceux qui ne font que notifier restent en fail-open.
• Un essai à blanc a été exécuté en provoquant volontairement un échec (identifiant invalide, script de hook renommé) pour voir si l'alerte part.
• Une personne précise reçoit l'alerte, avec un suppléant si elle est absente.

Le test d'échec volontaire est celui qu'on saute le plus souvent, et c'est lui qui prouve que le dispositif fonctionne. Une alerte jamais déclenchée en test est une alerte dont on ignore si elle marche.

Questions fréquentes

Passer à la pratique

Commence par deux gestes : ajouter le test du code de sortie à ta routine la plus critique, puis planifier le contrôle d'expiration avant elle. Le reste (hooks bloquants, checklist) peut suivre à ton rythme. Pour aller plus loin sur l'outil lui-même, la page Claude Code en détaille les usages, et la configuration et les abonnements Claude t'aident à choisir entre abonnement et clé API. Le jour où ton automatisation devient un vrai produit utilisé par d'autres, c'est l'objet de l'accompagnement Construire votre produit IA en 5 semaines.