Acerca de los ganchos

Acerca de los ganchos

Los enlaces permiten ejecutar comandos de shell personalizados en puntos estratégicos del flujo de trabajo de un agente, como cuando se inicia o finaliza una sesión del agente, o antes y después de que se escriba un mensaje o se llame a una herramienta.

Los enlaces reciben información detallada sobre las acciones del agente a través de la entrada JSON, lo que habilita la automatización con reconocimiento del contexto. Por ejemplo, puede usar ganchos para:

• Aprobar o denegar ejecuciones de herramientas mediante programación.

• Use características de seguridad integradas, como el examen de secretos, para evitar pérdidas de credenciales.

• Implemente reglas de validación personalizadas y registro de auditoría para el cumplimiento.

          Copilot los agentes admiten ganchos almacenados en archivos JSON en tu repositorio en `.github/hooks/*.json`.
  

Los ganchos están disponibles para usar con:

•         Copilot cloud agent en GitHub
  

•         CLI de GitHub Copilot en el terminal
  

Tipos de enlaces

Están disponibles los siguientes tipos de hooks:

•         **sessionStart**: se ejecuta cuando comienza una nueva sesión del agente o al reanudar una sesión existente. Se puede usar para inicializar entornos, registrar el inicio de sesiones para auditar, validar el estado del proyecto y configurar recursos temporales.
  

•         **sessionEnd**: se ejecuta cuando la sesión del agente concluye o se termina. Se puede usar para limpiar recursos temporales, generar y archivar registros e informes de sesión, o enviar notificaciones sobre la finalización de la sesión.
  

•         **userPromptSubmitted**: se ejecuta cuando el usuario envía un mensaje al agente. Se puede usar para registrar las solicitudes de usuario para la auditoría y el análisis de uso.
  

•         **preToolUse**: ejecutado antes de que el agente use cualquier herramienta (como `bash`, `edit`, `view`). Este es el enlace más eficaz, ya que puede **aprobar o denegar ejecuciones de herramientas**. Use este enlace para bloquear comandos peligrosos, aplicar directivas de seguridad y estándares de codificación, requerir aprobación para operaciones confidenciales o el uso de herramientas de registro para el cumplimiento.
  

•         **postToolUse**: se ejecuta después de que una herramienta complete la ejecución (ya sea correcta o con errores). Se puede usar para registrar los resultados de la ejecución, realizar un seguimiento de las estadísticas de uso, generar seguimientos de auditoría, supervisar las métricas de rendimiento y enviar alertas de error.
  

•         **agentStop**: se ejecuta cuando el agente principal ha terminado de responder a la solicitud.
  

•         **subagentStop**: se ejecuta cuando se completa un subagente, antes de devolver los resultados al agente primario.
  

•         **errorOccurred**: se ejecuta cuando se produce un error durante la ejecución del agente. Se puede usar para registrar errores para depurar, enviar notificaciones, realizar un seguimiento de los patrones de error y generar informes.
  

Para ver una referencia completa de tipos de enlace con casos de uso de ejemplo, procedimientos recomendados y patrones avanzados, consulte Configuración de hooks.

Formato de configuración de gancho

Configura los hooks usando un formato JSON especial. El JSON debe contener un version campo con un valor de 1 y un hooks objeto que contenga matrices de definiciones de enlace.

{
  "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
      }
    ],
  }
}

El objeto de enlace puede contener las siguientes claves:

Archivo de configuración de enlace de ejemplo

Este es un archivo de configuración de ejemplo que reside en ~/.github/hooks/project-hooks.json dentro de un repositorio.

{
  "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
      }
    ]
  }
}

Consideraciones sobre el rendimiento

Los ganchos operan sincrónicamente y bloquean la ejecución del agente. Para garantizar una experiencia con capacidad de respuesta, tenga en cuenta las siguientes consideraciones:

•         **Minimizar el tiempo de ejecución**: mantenga el tiempo de ejecución del enlace en menos de 5 segundos cuando sea posible.
  

•         **Optimizar el registro**: use el registro asincrónico, como anexar a archivos, en lugar de E/S sincrónica.
  

•         **Usar el procesamiento en segundo plano**: para operaciones costosas, considere la posibilidad de procesar en segundo plano.
  

•         **Resultados de caché: almacene en caché** cálculos costosos cuando sea posible.
  

Consideraciones de seguridad

Para garantizar que la seguridad se mantiene al usar hooks, tenga en cuenta las siguientes consideraciones:

•         **Valide y corrija siempre la entrada procesada por enlaces**. La entrada que no es de confianza podría provocar un comportamiento inesperado.
  

•         **Utilice el escape adecuado del shell al construir comandos**. Esto evita vulnerabilidades de inyección de comandos.
  

•         **Nunca registre datos confidenciales, como tokens o contraseñas**.
  

•         **Asegúrese de que los scripts de gancho y los logs tengan los permisos adecuados**.
  

•         **Tenga cuidado con los enlaces que realizan llamadas de red externas**. Estos pueden introducir latencia, errores o exponer datos a terceros.
  

•         **Establezca los tiempos de espera adecuados para evitar el agotamiento de recursos**. Los enlaces de ejecución prolongada pueden bloquear la ejecución del agente y degradar el rendimiento.
  

Pasos siguientes

Para empezar a crear enlaces, consulte Using hooks with GitHub Copilot agents.