La meilleure méthode consiste à vérifier, dans cet ordre, le fichier de réglages réellement chargé, l’événement et son matcher, puis le compte distant, l’environnement du script et son résultat. Ne réinstallez pas Claude Code avant d’avoir isolé le maillon défaillant. Les Hooks peuvent automatiser des contrôles déterministes, mais ils ne remplacent ni les permissions macOS ni la validation CI.

Ce guide s’adresse aux développeurs qui ne voient plus leurs contrôles ou commandes s’exécuter sur un Mac distant. Il concerne aussi les ingénieurs DevOps qui doivent établir si un Hook fournit une preuve exploitable pour Xcode, et les responsables de plateforme qui gèrent plusieurs périmètres de réglages.

Établissez d’abord où le déclenchement s’interrompt

Un Hook absent ne signifie pas nécessairement que son script est défectueux. Il faut distinguer l’événement qui ne se produit pas, le matcher qui ne correspond pas, le processus qui ne démarre pas et le résultat qui ne produit pas l’effet attendu. Ces situations demandent des vérifications différentes.

Commencez par une action reproductible, sans toucher aux fichiers de configuration. Par exemple, utilisez un appel d’outil contrôlé dont vous connaissez l’événement attendu. Notez ce que vous avez demandé, le répertoire du dépôt et le compte ayant lancé Claude Code. Consultez ensuite les informations de débogage Hooks décrites dans la documentation officielle de Claude Code sur les Hooks et leur débogage.

Observation Ce qu’elle suggère Vérification suivante
Aucun indice d’exécution du Hook Événement non atteint, réglage non chargé ou matcher sans correspondance Contrôler le périmètre des réglages, puis l’événement
Le script démarre, mais une commande manque Environnement différent de celui du terminal habituel Comparer le compte, le PATH et les dépendances
Le script écrit une sortie, sans bloquer l’action Contrat de sortie ou décision non conforme à l’événement Vérifier la sortie standard, le code de retour et les champs attendus
Le Hook semble réussir, mais les tests échouent ensuite Résultat du Hook confondu avec celui d’une étape ultérieure Examiner séparément les journaux du Hook et ceux de la CI

Conservez cette observation de départ. Si vous changez simultanément les réglages, le script et le compte d’exécution, vous ne saurez plus quelle modification a résolu le problème. Pour diagnostiquer les Hooks de Claude Code sur un environnement de développement distant, la trace de l’action est plus utile qu’une réinstallation à l’aveugle.

Vérifiez les réglages chargés par le compte distant

Un poste local et un Mac distant ne partagent pas nécessairement les mêmes réglages. Claude Code distingue plusieurs périmètres : l’utilisateur, le projet, les réglages locaux du projet et les stratégies gérées. Leur disponibilité dépend notamment de l’emplacement des fichiers et du compte qui exécute le processus. La documentation officielle des fichiers de réglages décrit ces portées et leur usage.

Périmètre À contrôler sur le Mac distant Risque fréquent
Utilisateur Fichier associé au compte qui lance réellement Claude Code Le fichier du compte interactif n’est pas celui du compte CI
Projet Fichier versionné avec le dépôt et présent dans le répertoire utilisé Le processus démarre dans un autre dépôt ou répertoire
Projet local Fichier local non nécessairement partagé avec l’équipe La configuration présente sur votre poste n’existe pas sur le nœud
Stratégie gérée Configuration administrée pour l’environnement concerné Une politique contrôlée par la plateforme n’est pas modifiable comme un réglage utilisateur

Pour chaque essai, consignez le compte effectif et le répertoire de travail. Comparez une session SSH interactive avec le lancement par le service CI, sans supposer que les deux chargent les mêmes fichiers. Un service peut fonctionner sous un compte dédié et ne pas bénéficier des préférences ou des variables disponibles dans votre session.

Vérifiez aussi que le fichier attendu se trouve bien sur le nœud utilisé et que sa syntaxe est valide. Si l’équipe partage des réglages de projet, confirmez qu’ils sont présents dans la révision effectivement récupérée par le processus. Si un réglage local est indispensable, déterminez comment il est provisionné sur cette machine ; ne le traitez pas comme une configuration automatiquement transférée depuis votre Mac de travail.

Ne copiez pas tout votre répertoire de configuration utilisateur sur un nœud partagé pour « faire comme en local ». Vous pourriez transférer des préférences ou des secrets sans résoudre la différence de compte à l’origine du problème.

Faites correspondre l’action réelle à l’événement et au matcher

Le nom de l’événement décrit le moment auquel Claude Code appelle le Hook. Un contrôle avant un outil, un contrôle après son exécution et un contrôle de fin de session ne sont pas interchangeables. La référence officielle des événements et des matchers Hooks permet de vérifier cette association.

Besoin observé Point à vérifier Erreur de raisonnement à éviter
Contrôler un appel avant son exécution Événement prévu et outil auquel s’applique le matcher Attendre un événement de fin de session
Examiner le résultat d’un appel Événement qui intervient après l’outil et données reçues Utiliser un matcher prévu pour un autre outil
Contrôler la fin d’une session Événement de fin et contrat associé Le traiter comme une preuve de réussite d’un outil ou d’une suite de tests

Pour diagnostiquer un matcher PreToolUse, relevez l’outil effectivement invoqué plutôt que celui que vous aviez prévu dans votre scénario. Comparez ensuite son nom et les critères configurés. Un filtre trop précis, une valeur différente de celle attendue ou un événement choisi au mauvais moment peuvent suffire à expliquer l’absence de déclenchement.

Réduisez le test à un événement et un appel d’outil. Évitez d’ajouter en même temps plusieurs matchers, scripts et critères de filtrage : cela rend la trace difficile à interpréter. Une fois la correspondance confirmée, réintroduisez progressivement les conditions du cas réel. Si le Hook ne se déclenche pas, revenez à la question « réglage chargé ou événement atteint ? » avant d’accuser le script.

Comparez l’environnement du script à celui de la session SSH

Un script peut être exécutable et néanmoins échouer lorsqu’il est lancé par un service. La session SSH interactive et le processus CI peuvent avoir des comptes, des répertoires de travail, des variables PATH, des interpréteurs et des dépendances différents. Cette différence est particulièrement importante si le Hook appelle des outils installés par l’utilisateur, un environnement Python ou des outils Apple.

Procédez par vérifications ciblées :

  • Confirmez que le fichier du script existe à l’emplacement référencé et que le compte du service peut le lire et l’exécuter.
  • Vérifiez l’interpréteur indiqué par le script. Un chemin disponible dans votre session ne l’est pas nécessairement dans le contexte non interactif.
  • Affichez le PATH et le répertoire courant dans une sortie de diagnostic temporaire, sans y inclure de jeton, de clé ou de variable sensible.
  • Testez chaque dépendance avec le compte qui exécute Claude Code, plutôt qu’avec votre compte d’administration.
  • Vérifiez les droits d’accès aux fichiers que le Hook lit ou modifie, en particulier si le dépôt est partagé avec un autre service.

Si une commande est introuvable, préférez un chemin explicite ou configurez proprement l’environnement du service. Ajouter globalement des chemins ou élargir les permissions peut masquer la cause et rendre le nœud plus difficile à maintenir. Pour un environnement partagé, documentez le compte de service, ses dépendances nécessaires et la manière dont elles sont installées.

Un accès distant par SSH ne garantit pas que les commandes s’exécutent dans une session graphique macOS complète. Apple documente des précautions propres à l’automatisation des tests Xcode via SSH dans son guide d’automatisation des tests avec Xcode. Utilisez-le pour cadrer le contexte d’exécution, sans extrapoler son comportement à tous les services ou à toutes les configurations.

Vérifiez le contrat de sortie avant d’interpréter l’effet

Un Hook qui a démarré n’a pas nécessairement renvoyé une décision compréhensible. Claude Code transmet des informations au processus et interprète sa sortie selon les règles de l’événement. Vérifiez la documentation officielle avant de supposer qu’un texte affiché dans le terminal suffit à bloquer un outil. Les règles de sortie et de décision des Hooks précisent les comportements à respecter.

Séparez les éléments suivants dans votre diagnostic :

Résultat observé Interprétation à tester Suite du contrôle
Aucun processus visible Réglage, événement ou matcher possiblement en cause Revenir aux réglages et à la trace de l’événement
Processus démarré, échec signalé Erreur du script ou dépendance absente Lire la sortie d’erreur et reproduire sous le même compte
Sortie sans décision explicite attendue Le texte seul peut ne pas porter l’effet recherché Comparer la structure produite au contrat de l’événement
Décision explicite renvoyée, action toujours possible Champ ou mécanisme inadapté à l’événement, ou autre étape en cause Contrôler le format et distinguer l’action de la CI

Ne confondez pas un Hook non déclenché avec un Hook en erreur. Un processus peut échouer après son démarrage ; inversement, un script peut se terminer normalement sans exprimer la décision que vous attendiez. Les codes de sortie et les champs de décision ont une signification définie par l’événement et la documentation. Testez séparément un cas sans décision particulière et un cas où le résultat doit explicitement bloquer ou signaler une condition.

Lorsque vous ajustez le diagnostic, évitez d’écrire le contenu reçu ou les variables d’environnement sans filtrage. Les données d’entrée peuvent inclure des informations de travail sensibles. Une trace utile indique l’événement, le compte, le chemin du script, le code de retour et un résumé non sensible du résultat.

Séparez le contrôle Hook de la preuve Xcode et de la sécurité

Un Hook peut servir à lancer un contrôle déterministe, par exemple un formatage après une modification, ou une vérification quand une session se termine. Cela ne prouve pas, à lui seul, qu’un projet Xcode a été construit et testé avec succès. Un Stop Hook peut déclencher une commande de vérification, mais la preuve attendue doit venir de l’exécution et des résultats produits par Xcode.

Apple décrit la manière de lancer les tests et d’interpréter leurs résultats dans Xcode, ainsi que les commandes disponibles dans sa référence des outils en ligne de commande Xcode. Pour une étape CI, conservez les éléments permettant de vérifier ce qui a été lancé et ce qu’a produit le test. Ne remplacez pas ces résultats par un simple message du Hook.

Faites une recette d’acceptation distincte pour le contrôle local et pour la validation CI :

  • Déclenchez une action connue et vérifiez que le Hook prévu s’exécute.
  • Vérifiez un cas attendu comme valide, puis un cas qui doit être refusé ou signalé.
  • Confirmez que le résultat du contrôle est enregistré séparément des journaux de l’outil et des étapes CI suivantes.
  • Relancez le contrôle après un redémarrage du nœud pour vérifier que le compte et l’environnement restent adaptés.
  • Si le contrôle est obligatoire pour livrer, faites porter l’acceptation finale à une étape CI suivie et vérifiable.

La frontière de sécurité compte autant que la preuve technique. Les Hooks ne remplacent ni le modèle de permissions de Claude Code, ni les autorisations macOS, ni une revue humaine lorsque celle-ci est nécessaire. Consultez la documentation officielle sur les permissions Claude Code pour définir ce qui peut être autorisé ou demandé. Un script Hook ne doit pas être utilisé comme barrière unique contre un processus qui dispose déjà de droits système plus étendus.

Pour choisir la correction, utilisez cette règle : si le fichier ou le compte est incorrect, corrigez le provisionnement ; si l’événement ou le matcher est incorrect, ajustez la configuration ; si le processus échoue, corrigez son environnement ; si le résultat n’est pas une preuve suffisante, déplacez le contrôle obligatoire dans une étape CI avec des résultats conservés.

Questions fréquentes sur les Hooks sur Mac distant

Pourquoi un Hook reste-t-il silencieux sur un Mac distant ?

Vérifiez d’abord les réglages chargés sous le compte réel, puis l’événement et le matcher associés à l’action. Si le processus démarre, inspectez son environnement, son interpréteur et ses dépendances. Une réinstallation ne corrige ni un fichier absent pour le compte CI ni un filtre qui vise un autre outil. Utilisez une trace minimale et non sensible pour repérer le premier maillon défaillant.

Quel fichier de Hooks Claude Code faut-il contrôler ?

Cela dépend du périmètre recherché : utilisateur, projet, réglage local au projet ou stratégie gérée. Sur le Mac distant, identifiez le compte et le répertoire utilisés par la session SSH ou le Runner, puis vérifiez les fichiers accessibles dans ce contexte. Un réglage présent dans votre compte interactif peut ne pas être chargé par le compte de service.

Comment vérifier un matcher PreToolUse qui ne correspond pas ?

Comparez le nom de l’outil réellement invoqué et l’événement configuré, puis simplifiez temporairement le test pour n’observer qu’un seul appel. Consultez les informations de débogage Hooks et vérifiez les critères du matcher. Si l’événement n’est pas celui attendu, modifier les permissions du script ne changera pas le déclenchement.

Comment résoudre une commande introuvable dans un Hook lancé par SSH ?

Reproduisez la commande sous le compte qui exécute le Hook. Comparez son PATH à celui de votre terminal, vérifiez l’interpréteur et contrôlez les droits sur le script et ses dépendances. Déclarez les chemins nécessaires de manière explicite dans l’environnement du service. N’ajoutez pas de secrets aux traces et n’élargissez pas les permissions sans raison précise.

Un Stop Hook valide-t-il à lui seul les tests Xcode ?

Non. Il peut lancer une vérification ou signaler un état, mais la validation doit s’appuyer sur l’exécution des tests et les résultats Xcode attendus. Dans la CI, conservez les journaux et les résultats de test, puis faites échouer l’étape de validation selon une règle explicite. Le Hook n’est pas une preuve suffisante ni une frontière d’isolation du système.

Si le diagnostic révèle que le compte distant ou son environnement diffère de votre poste, une configuration reproductible compte davantage qu’un script plus permissif. Un Mac acheté et administré localement peut convenir si vous devez conserver un accès physique permanent ; une machine Linux ne remplace pas les outils macOS requis par votre flux Xcode. En revanche, ces solutions peuvent impliquer une gestion matérielle, un nœud dédié ou des limites de compatibilité. Pour reproduire le problème sur un environnement macOS réel sans acheter immédiatement une machine, vous pouvez examiner les options de Mac distant proposées par MACCOME et vérifier leur adéquation à la durée du projet. La page française de MACCOME permet ensuite d’examiner l’offre avant de choisir une formule.