Types de Hooks

Les Agent Hooks prennent en charge divers types de déclencheurs, chacun étant conçu pour des scénarios d'automatisation précis. Comprendre ces types vous aide à choisir la bonne approche selon les besoins de votre 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, début de session) ou à la CLI (création d'agent). Le tableau ci-dessous montre ce qui est pris en charge, et où.

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

Cas d'utilisation :

• Fournir un contexte supplémentaire à l'agent en fonction de 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 modifications apportées par l'agent et fournir des instructions supplémentaires

Se déclenche lorsqu'une nouvelle session de clavardage commence dans l'IDE.

Cas d'utilisation :

• Injecter des instructions propres à l'espace de travail dans le contexte de l'agent
• Exécuter des vérifications d'environnement (vérifier les dépendances, valider les identifiants)
• Charger la configuration propre au projet au début de la session

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, la sortie STDOUT est ajoutée au contexte de l'agent
• Autre : Afficher l'avertissement STDERR à l'utilisateur

Cas d'utilisation :

• Configurer le contexte d'environnement au début d'une session
• Charger la configuration propre au projet
• Initialiser des 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 d'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 de l'environnement avant l'exécution de la tâche
• Valider que les conditions préalables sont respectées avant le début d'une tâche
• Consigner les événements de début de tâche pour le 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 des tests après la fin d'une tâche pour en vérifier l'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

Les Hooks manuels créés dans l'IDE 0.x continuent d'apparaître dans le panneau des Agent Hooks avec une étiquette legacy. Les Hooks manuels legacy activés restent exécutables à l'aide du bouton de lecture à côté du nom du Hook ou de Start Hook dans la vue du Hook.

Les Hooks manuels legacy n'ont pas d'équivalent de déclencheur v1, et vous ne pouvez pas créer un nouveau Hook à déclenchement manuel. Pour un nouveau flux de travail à la demande, créez un fichier Steering à inclusion manuelle; il s'exécute comme une commande à barre oblique /<filename>.

Pour les outils MCP, le nom de l'outil comprend le format complet avec espace de noms, incluant 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;"
  }
}

Ceci s'applique aux Hooks Pre Tool Use et Post Tool Use lorsqu'ils ciblent des outils de serveur MCP.