Hooks — référence

Événements hooks

Les deux manifestes du plugin portent les mêmes entrées, et chaque entrée exécute src/cli/hook.mjs (src/cli/housekeeping.mjs pour SessionStart). Copilot CLI envoie ses propres noms d’outils (bash, create, str_replace, view, …) ; adapters/api/hooks/harness-input.mjs les traduit vers les noms ci-dessus avant toute garde.

G7 et G8 lisent une commande shell à sa forme : redirections, tee, verbes qui réécrivent ou copient, sed et perl en place, scripts en ligne node -e ou python -c, derrière des affectations VAR=valeur et des enveloppes comme sudo ou env. Une écriture cachée derrière bash -c, une variable, un sous-shell ou find -delete n’est pas reconnue.

Porte de phase (CLI d’état, G4/G5)

La complétude d’une phase n’est pas un hook. L’orchestrateur enregistre artefacts et verdicts après le retour d’un sous-agent ; le contrôle a donc lieu à la clôture de la phase : state.mjs transition et state.mjs close-phase refusent avec PHASE_GATE sauf si

• G4 — chaque sortie suivie requise de la phase est enregistrée et présente sur disque ;
• G5 — l’artefact de revue décisif est enregistré et présent, son verdict égale le verdict enregistré, et une phase DELIVER qui se clôt a un commit depuis son démarrage.

La porte échoue fermée : une phase qui ne peut pas être contrôlée ne se clôt pas.

Statut de vérification

Chaque garde ci-dessus est couverte par des tests unitaires et d’acceptation sous tests/skraft-framework/. Une exécution sur un harness réel est une preuve distincte : scripts/copilot-hook-smoke.mjs et scripts/claude-plugin-smoke.mjs pilotent une vraie session avec une commande shell autorisée et un refus G7. Le dernier passage enregistré est Copilot CLI 1.0.83 pour ces deux sondes ; les autres gardes n’ont aucune preuve en session réelle, et les évaluations Vally ne chargent pas les hooks du plugin.

Types de décision (vocabulaire interne)

Les handlers retournent l’une des quatre décisions construites par plugins/skraft-framework/src/adapters/api/hooks/decision.mjs :

allow()                                  // { decision: 'allow' }
deny('Raison du refus')                  // { decision: 'deny', message: … }
block('Raison du blocage')               // { decision: 'block', message: … }
additionalContext('Information ajoutée') // { decision: 'additionalContext', context: … }

Ce vocabulaire n’atteint jamais le harness. C’est le langage propre au framework, traduit à la frontière du CLI par plugins/skraft-framework/src/adapters/api/hooks/harness-output.mjs.

Format de fil harness (ce qui est réellement écrit sur stdout)

Les deux harnesses typent la clé racine decision comme "approve" | "block". Écrire {"decision":"allow"} ou {"decision":"deny"} invalide le payload entier — Claude Code journalise Hook JSON output validation failed — (root): Invalid input, jette la sortie et laisse l’outil s’exécuter. Une garde qui émet le vocabulaire interne est donc inerte.

Une seule enveloppe satisfait les deux runtimes : Claude Code lit hookSpecificOutput et retire les clés racine inconnues, Copilot CLI lit les clés racine et ignore hookSpecificOutput.

// deny / block sur PreToolUse — seul l'outil est refusé, la session continue
{
  "permissionDecision": "deny",
  "permissionDecisionReason": "Raison du refus",
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Raison du refus"
  }
}

// deny / block sur tout autre événement
{ "decision": "block", "reason": "Raison du blocage" }

// additionalContext
{
  "additionalContext": "Information ajoutée",
  "hookSpecificOutput": { "hookEventName": "PostToolUse", "additionalContext": "Information ajoutée" }
}

hookSpecificOutput.hookEventName doit correspondre à l’événement en cours, sinon Claude Code rejette le bloc. Un block sur PreToolUse est mappé sur permissionDecision: "deny" et jamais sur continue: false : un bug de hook ne doit pas figer le pipeline.

Si le hook n’écrit rien ou exit 0 sans output, les deux runtimes interprètent comme allow.

Normalisation du payload

Tous les payloads entrants sont normalisés en camelCase avant routage :

Implémenté dans plugins/skraft-framework/src/adapters/api/hooks/payload.mjs.

Variables d’environnement

Les hooks et les CLI lisent ces variables ; aucune n’est obligatoire.

src/application/config-loader.mjs implémente une cascade env → ~/.skraft/config.json → .skraftrc.json, mais aucun hook ni CLI ne la lit.

Fichiers source

Voir aussi

• Garde-fous (hooks) — pourquoi les hooks existent
• Clean Architecture — couches du framework