Types de Hooks

Les Agent Hooks prennent en charge divers types de déclenchement, chacun conçu pour des scénarios d'automatisation précis. Comprendre ces types vous aide à choisir la bonne approche pour vos besoins de flux de travail.

Tous les déclencheurs de Hooks ne sont pas disponibles sur chaque surface. Certains déclencheurs sont spécifiques à l'IDE (exécution de tâche) ou au CLI (démarrage d'agent). Le tableau ci-dessous montre ce qui est pris en charge où.

Se déclenche lorsque l'utilisateur soumet une requête.

Cas d'utilisation :

• Fournir un contexte supplémentaire à l'agent en lien avec la requête
• Bloquer certaines requêtes selon leur contenu
• Consigner toutes les requêtes de l'utilisateur dans un emplacement central

Se déclenche lorsque l'agent a terminé son tour et fini de répondre à l'utilisateur.

Cas d'utilisation :

• Compiler le code et signaler tout échec à l'agent
• Formater ou réviser tout code généré par l'agent
• Réviser les changements effectués par l'agent et fournir des instructions supplémentaires

S'exécute lorsque l'agent est activé pour la première fois. Aucun contexte d'outil n'est fourni.

{
  "hook_event_name": "agentSpawn",
  "cwd": "/current/working/directory",
  "session_id": "abc123-def456-789"
}

Comportement du code de sortie :

• 0 : Le Hook a réussi, STDOUT est ajouté au contexte de l'agent
• Autre : Afficher l'avertissement STDERR à l'utilisateur

Cas d'utilisation :

• Configurer le contexte d'environnement au démarrage d'une session
• Charger la configuration propre au projet
• Initialiser les systèmes de journalisation ou d'audit

Se déclenche lorsque l'agent est sur le point d'invoquer un outil. Peut valider et bloquer l'utilisation de l'outil.

Cas d'utilisation :

• Bloquer certaines invocations d'outils
• Valider les entrées de l'outil avant l'exécution
• Fournir des instructions supplémentaires à l'agent avant qu'il invoque un outil

Se déclenche après que l'agent a invoqué un outil, avec accès aux résultats de l'outil.

Cas d'utilisation :

• Consigner les invocations d'outils à des fins d'audit
• Formater ou réviser tout fichier mis à jour après un appel à l'outil « write »
• Fournir des instructions supplémentaires à l'agent en plus de la réponse de l'outil

Se déclenche lorsque l'agent crée de nouveaux fichiers correspondant à des motifs précis dans votre espace de travail.

Cas d'utilisation :

• Générer du code passe-partout pour de nouveaux composants
• Ajouter des en-têtes de licence aux nouveaux fichiers
• Configurer des fichiers de test lors de la création de fichiers d'implémentation

Se déclenche lorsque l'agent enregistre ou modifie des fichiers correspondant à des motifs précis.

Cas d'utilisation :

• Exécuter le linting et le formatage
• Mettre à jour les fichiers connexes
• Générer de la documentation
• Exécuter les tests pour les fichiers modifiés

Se déclenche lorsque l'agent supprime des fichiers correspondant à des motifs précis.

Cas d'utilisation :

• Nettoyer les fichiers connexes
• Mettre à jour les références d'importation dans d'autres fichiers
• Maintenir l'intégrité du projet

Se déclenche avant qu'une tâche de Spec commence son exécution, lorsque son statut passe à in_progress.

Cas d'utilisation :

• Exécuter des scripts de configuration ou de préparation d'environnement avant l'exécution de la tâche
• Valider que les prérequis sont respectés avant le démarrage d'une tâche
• Consigner les événements de démarrage de tâche à des fins de suivi

Se déclenche après qu'une tâche de Spec a terminé son exécution, lorsque son statut passe à completed.

Cas d'utilisation :

• Exécuter les tests après la fin d'une tâche pour vérifier son exactitude
• Exécuter le linting ou le formatage sur les fichiers modifiés
• Générer de la documentation pour le travail terminé
• Notifier les systèmes externes de l'achèvement de la tâche

Exécuter manuellement un Hook à la demande.

Cas d'utilisation :

• Révisions de code à la demande
• Génération de documentation
• Analyse de sécurité
• Optimisation des performances

Pour les outils MCP, le nom de l'outil inclut le format complet avec espace de noms, y compris le nom du serveur MCP :

{
  "hook_event_name": "preToolUse",
  "cwd": "/current/working/directory",
  "session_id": "abc123-def456-789",
  "tool_name": "@postgres/query",
  "tool_input": {
    "sql": "SELECT * FROM orders LIMIT 10;"
  }
}

Cela s'applique aussi bien aux Hooks Pre Tool Use qu'aux Hooks Post Tool Use lorsqu'ils ciblent des outils de serveur MCP.