Sobre ganchos

Sobre ganchos

Os ganchos permitem executar comandos de shell personalizados em pontos estratégicos no fluxo de trabalho de um agente, como quando uma sessão do agente é iniciada ou termina, ou antes e depois que um prompt é inserido ou uma ferramenta é chamada.

Os ganchos recebem informações detalhadas sobre as ações do agente por meio da entrada JSON, habilitando a automação com reconhecimento de contexto. Por exemplo, você pode usar ganchos para:

• Aprovar ou negar execuções de ferramentas programaticamente.

• Utilize recursos de segurança internos, como verificação secreta, para evitar vazamentos de credenciais.

• Implemente regras de validação personalizadas e log de auditoria para conformidade.

          Copilot os agentes suportam ganchos armazenados em arquivos JSON no seu repositório em `.github/hooks/*.json`.
  

Os ganchos estão disponíveis para uso com:

•         agente de nuvem Copilot em GitHub
  

•         CLI do GitHub Copilot no terminal
  

Tipos de ganchos

Os seguintes tipos de ganchos estão disponíveis:

•         **sessionStart**: Executado quando uma nova sessão de agente começa ou ao retomar uma sessão existente. Pode ser usado para inicializar ambientes, registrar o início de sessões para auditoria, validar o estado do projeto e configurar recursos temporários.
  

•         **sessionEnd**: executado quando a sessão do agente é concluída ou encerrada. Pode ser usado para limpar recursos temporários, gerar e arquivar relatórios e logs de sessão ou enviar notificações sobre a conclusão da sessão.
  

•         **userPromptSubmitted**: Executado quando o usuário envia um prompt para o agente. Pode ser usado para registrar solicitações de usuário para auditoria e análise de uso.
  

•         **preToolUse**: executado antes que o agente use qualquer ferramenta (como `bash`, , `edit`). `view` Esse é o gancho mais poderoso, pois pode **aprovar ou negar execuções de ferramentas**. Use esse gancho para bloquear comandos perigosos, impor políticas de segurança e padrões de codificação, exigir aprovação para operações confidenciais ou uso de ferramentas de log para conformidade.
  

•         **postToolUse**: executado depois que uma ferramenta conclui a execução (com êxito ou falha). Pode ser usado para registrar resultados de execução, acompanhar estatísticas de uso, gerar trilhas de auditoria, monitorar métricas de desempenho e enviar alertas de falha.
  

•         **agentStop**: Executado quando o agente principal terminar de responder ao prompt.
  

•         **subagentStop**: executado quando um subagente encerra, antes de retornar os resultados ao agente pai.
  

•         **errorOccurred**: executado quando ocorre um erro durante a execução do agente. Pode ser usado para registrar erros para depuração, enviar notificações, rastrear padrões de erro e gerar relatórios.
  

Para ver uma referência completa de tipos de gancho com casos de uso de exemplo, práticas recomendadas e padrões avançados, consulte Configuração de ganchos.

Formato de configuração do gancho

Você configura ganchos usando um formato JSON especial. O JSON deve conter um version campo com um valor 1 e um hooks objeto contendo matrizes de definições de gancho.

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

O objeto hook pode conter as seguintes chaves:

Arquivo de configuração de gancho de exemplo

Este é um arquivo de configuração de exemplo que reside em ~/.github/hooks/project-hooks.json em um repositório.

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

Considerações sobre desempenho

Os ganchos são executados de forma síncrona e bloqueiam a execução do agente. Para garantir uma experiência responsiva, tenha em mente as seguintes considerações:

•         **Minimizar o tempo de execução**: mantenha o tempo de execução do gancho em menos de 5 segundos, quando possível.
  

•         **Otimizar configurações**: utilize registro em log assíncrono, como adicionar informações a arquivos, em vez de E/S síncrona.
  

•         **Use o processamento em segundo plano**: para operações caras, considere o processamento em segundo plano.
  

•         **Resultados do cache**: armazenar em cache cálculos caros quando possível.
  

Considerações de segurança

Para garantir que a segurança seja mantida ao usar ganchos, tenha em mente as seguintes considerações:

•         **Valide e higienize sempre a entrada processada pelos ganchos**. A entrada não confiável pode levar a um comportamento inesperado.
  

•         **Use o escape de shell adequado ao construir comandos**. Isso impede vulnerabilidades de injeção de comando.
  

•         **Nunca registre dados confidenciais, como tokens ou senhas**.
  

•         **Verifique se os scripts e logs de hook têm as permissões apropriadas**.
  

•         **Tenha cuidado com ganchos que fazem chamadas de rede externas**. Elas podem introduzir latência, falhas ou expor dados a terceiros.
  

•         **Defina os tempos limite apropriados para evitar o esgotamento de recursos**. Ganchos de execução longa podem bloquear a execução do agente e prejudicar o desempenho.
  

Próximas Etapas 

Para começar a criar ganchos, consulte Usando hooks com agentes do GitHub Copilot.