Aller au contenu

ADR 0003 — PowerShell pour les hooks

Contexte

Les hooks Claude Code (SessionStart, PreToolUse, PreCompact, Stop) sont de petits scripts exécutés à des moments précis. Ils reçoivent du JSON sur stdin, produisent du JSON sur stdout, et parfois des effets de bord (création de fichier, log). Le choix du langage a des conséquences sur :

  • La portabilité (Windows / macOS / Linux des équipes consommatrices).
  • La disponibilité du runtime (déjà installé ou à installer).
  • La facilité de manipulation JSON.
  • La lisibilité pour un admin système.

Options envisagées

  1. Bash — universel sur Linux/macOS, mais Git Bash sur Windows.
  2. Node.js — portable, JSON natif, mais dépendance déjà présente pour la CLI.
  3. Python — portable, verbose, nécessite une installation explicite.
  4. PowerShell 7 — multi-plateforme (pwsh), JSON natif, largement disponible en contexte entreprise.

Décision

Retenu : PowerShell 7 (pwsh).

Les 4 hooks sont écrits en PowerShell, à exécuter via pwsh -File <chemin>. PowerShell 7 est multi-plateforme (Windows, Linux, macOS) depuis 2020.

Conséquences

Positives :

  • Les projets consommateurs cibles sont majoritairement sous Windows (contexte entreprise) — PowerShell y est natif et bien connu.
  • Manipulation JSON native : ConvertFrom-Json / ConvertTo-Json sans dépendance tierce.
  • Signature Microsoft disponible pour environnements à sécurité stricte.
  • Verbosité modérée : plus lisible que Bash pour un non-sysadmin, moins que Python.

Négatives :

  • PowerShell 7 doit être installé sur macOS / Linux (non-natif).
  • La syntaxe est peu familière aux équipes full-Linux.
  • Les messages d'erreur peuvent être moins clairs que Node ou Python.

Neutres :

  • Les hooks restent très courts (< 100 lignes chacun). La courbe d'apprentissage est limitée, quelle que soit la familiarité initiale.

Alternatives conservées en option

Un projet consommateur qui voudrait réécrire les hooks en Node ou Bash peut le faire : seule la sémantique (lecture stdin JSON, écriture stdout JSON) est contractuelle. Les fichiers PowerShell fournis sont des implémentations de référence.

Références