À propos des crochets

À propos des crochets

Les hooks vous permettent d’exécuter des commandes d’interpréteur de commandes personnalisées à des points stratégiques dans le flux de travail d’un agent, par exemple lorsqu’une session d’agent démarre ou se termine, ou avant et après qu’une invite est entrée ou qu’un outil est appelé.

Les hooks reçoivent des informations détaillées sur les actions de l’agent via une entrée JSON, ce qui active l’automatisation prenant en charge le contexte. Par exemple, vous pouvez utiliser des hooks pour :

• Approuvez ou refusez par programmation les exécutions d’outils.

• Utilisez des fonctionnalités de sécurité intégrées telles que l’analyse secrète pour empêcher les fuites d’informations d’identification.

• Implémentez des règles de validation personnalisées et la journalisation d’audit pour la conformité.

          Copilot les agents prennent en charge les hooks qui sont stockés dans des fichiers JSON de votre référentiel à l’adresse `.github/hooks/*.json`.
  

Les hooks peuvent être utilisés avec :

•         agent Copilot de cloud sur GitHub
  

•         CLI de GitHub Copilot dans le terminal
  

Types de crochets

Les types de crochets suivants sont disponibles :

•         **sessionStart** : exécuté lorsqu’une nouvelle session d’agent commence ou lors de la reprise d’une session existante. Peut être utilisé pour initialiser des environnements, enregistrer le démarrage des sessions pour l'audit, valider l'état du projet et configurer des ressources temporaires.
  

•         **sessionEnd** : exécuté lorsque la session de l’agent se termine ou est terminée. Peut être utilisé pour nettoyer les ressources temporaires, générer et archiver des rapports et des journaux de session, ou envoyer des notifications sur la fin de la session.
  

•         **userPromptSubmitted** : exécuté lorsque l’utilisateur envoie une invite à l’agent. Peut être utilisé pour consigner les demandes utilisateur pour l’audit et l’analyse de l’utilisation.
  

•         **preToolUse** : exécuté avant que l’agent utilise n’importe quel outil (par exemple, `bash`, `edit`, `view`). Il s’agit du hook le plus puissant, car il peut **approuver ou refuser les exécutions d’outils**. Utilisez ce hook pour bloquer les commandes dangereuses, appliquer des stratégies de sécurité et des normes de codage, exiger l’approbation des opérations sensibles ou l’utilisation de l’outil de journalisation pour la conformité.
  

•         **postToolUse** : exécuté après l’exécution d’un outil (réussite ou échec). Peut être utilisé pour consigner les résultats d’exécution, suivre les statistiques d’utilisation, générer des pistes d’audit, surveiller les métriques de performances et envoyer des alertes d’échec.
  

•         **agentStop** : exécuté lorsque l’agent principal a terminé de répondre à votre invite.
  

•         **subagentStop** : exécuté lorsqu’un sous-agent est terminé, avant de retourner les résultats à l’agent parent.
  

•         **errorOccurred** : exécuté lorsqu’une erreur se produit pendant l’exécution de l’agent. Peut être utilisé pour consigner les erreurs de débogage, d’envoi de notifications, de suivi des modèles d’erreurs et de générer des rapports.
  

Pour afficher une référence complète des types de crochets avec des exemples de cas d’usage, des bonnes pratiques et des modèles avancés, consultez Configuration des hooks.

Format de configuration des hooks

Vous configurez des hooks à l’aide d’un format JSON spécial. Le code JSON doit contenir un version champ avec une valeur et 1 un hooks objet contenant des tableaux de définitions de hook.

{
  "version": 1,
  "hooks": {
    "sessionStart": [
      {
        "type": "command",
        "bash": "string (optional)",
        "powershell": "string (optional)",
        "cwd": "string (optional)",
        "env": { "KEY": "value" },
        "timeoutSec": 30
      }
    ],
  }
}

{
  "version": 1,
  "hooks": {
    "sessionStart": [
      {
        "type": "command",
        "bash": "string (optional)",
        "powershell": "string (optional)",
        "cwd": "string (optional)",
        "env": { "KEY": "value" },
        "timeoutSec": 30
      }
    ],
  }
}

L’objet hook peut contenir les clés suivantes :

Exemple de fichier de configuration de hook

Il s’agit d’un exemple de fichier de configuration qui se trouve dans ~/.github/hooks/project-hooks.json dans un référentiel.

{
  "version": 1,
  "hooks": {
    "sessionStart": [
      {
        "type": "command",
        "bash": "echo \"Session started: $(date)\" >> logs/session.log",
        "powershell": "Add-Content -Path logs/session.log -Value \"Session started: $(Get-Date)\"",
        "cwd": ".",
        "timeoutSec": 10
      }
    ],
    "userPromptSubmitted": [
      {
        "type": "command",
        "bash": "./scripts/log-prompt.sh",
        "powershell": "./scripts/log-prompt.ps1",
        "cwd": "scripts",
        "env": {
          "LOG_LEVEL": "INFO"
        }
      }
    ],
    "preToolUse": [
      {
        "type": "command",
        "bash": "./scripts/security-check.sh",
        "powershell": "./scripts/security-check.ps1",
        "cwd": "scripts",
        "timeoutSec": 15
      },
      {
        "type": "command",
        "bash": "./scripts/log-tool-use.sh",
        "powershell": "./scripts/log-tool-use.ps1",
        "cwd": "scripts"
      }
    ],
    "postToolUse": [
      {
        "type": "command",
        "bash": "cat >> logs/tool-results.jsonl",
        "powershell": "$input | Add-Content -Path logs/tool-results.jsonl"
      }
    ],
    "sessionEnd": [
      {
        "type": "command",
        "bash": "./scripts/cleanup.sh",
        "powershell": "./scripts/cleanup.ps1",
        "cwd": "scripts",
        "timeoutSec": 60
      }
    ]
  }
}

{
  "version": 1,
  "hooks": {
    "sessionStart": [
      {
        "type": "command",
        "bash": "echo \"Session started: $(date)\" >> logs/session.log",
        "powershell": "Add-Content -Path logs/session.log -Value \"Session started: $(Get-Date)\"",
        "cwd": ".",
        "timeoutSec": 10
      }
    ],
    "userPromptSubmitted": [
      {
        "type": "command",
        "bash": "./scripts/log-prompt.sh",
        "powershell": "./scripts/log-prompt.ps1",
        "cwd": "scripts",
        "env": {
          "LOG_LEVEL": "INFO"
        }
      }
    ],
    "preToolUse": [
      {
        "type": "command",
        "bash": "./scripts/security-check.sh",
        "powershell": "./scripts/security-check.ps1",
        "cwd": "scripts",
        "timeoutSec": 15
      },
      {
        "type": "command",
        "bash": "./scripts/log-tool-use.sh",
        "powershell": "./scripts/log-tool-use.ps1",
        "cwd": "scripts"
      }
    ],
    "postToolUse": [
      {
        "type": "command",
        "bash": "cat >> logs/tool-results.jsonl",
        "powershell": "$input | Add-Content -Path logs/tool-results.jsonl"
      }
    ],
    "sessionEnd": [
      {
        "type": "command",
        "bash": "./scripts/cleanup.sh",
        "powershell": "./scripts/cleanup.ps1",
        "cwd": "scripts",
        "timeoutSec": 60
      }
    ]
  }
}

Considérations relatives aux performances

Les hooks s’exécutent de manière synchrone et bloquent l’exécution de l’agent. Pour garantir une expérience réactive, gardez à l’esprit les considérations suivantes :

•         **Réduire le temps d’exécution : conservez le temps d’exécution** du hook sous 5 secondes lorsque cela est possible.
  

•         **Optimiser la journalisation** : utilisez la journalisation asynchrone, comme l’ajout à des fichiers, plutôt que les E/S synchrones.
  

•         **Utilisez le traitement en arrière-plan** : pour les opérations coûteuses, envisagez le traitement en arrière-plan.
  

•         **Résultats du cache** : calculs coûteux en cache quand c’est possible.
  

Considérations relatives à la sécurité

Pour garantir que la sécurité est maintenue lors de l’utilisation de crochets, gardez à l’esprit les considérations suivantes :

•         **Validez et assainissez toujours l’entrée traitée par des hooks**. Une entrée non approuvée peut entraîner un comportement inattendu.
  

•         **Utilisez un échappement d’interpréteur de commandes approprié lors de la création des commandes**. Cela empêche les vulnérabilités d’injection de commandes.
  

•         **Ne journalise jamais les données sensibles, telles que les jetons ou les mots de passe**.
  

•         **Vérifiez que les scripts d'accrochage et les journaux disposent des autorisations appropriées**.
  

•         **Soyez prudent avec les hooks qui effectuent des appels réseaux externes**. Celles-ci peuvent introduire une latence, des défaillances ou exposer des données à des tiers.
  

•         **Définissez les délais d’expiration appropriés pour empêcher l’épuisement des ressources**. Les hooks de longue durée peuvent bloquer l’exécution de l’agent et dégrader les performances.
  

Étapes suivantes

Pour commencer à créer des hooks, consultez Utilisation de hooks avec les agents GitHub Copilot.