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.

Os agentes Copilot permitem ganchos armazenados em arquivos JSON no seu repositório em .github/hooks/*.json.

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

Agente de codificação do 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, iniciar a sessão de log 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.

        **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.

JSON

{
  "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:

Propriedade	Obrigatório	Description
`type`	Yes	Precisa ser `"command"`
`bash`	Sim (em sistemas Unix)	Caminho para o script bash a ser executado
`powershell`	Sim (no Windows)	Caminho para o script do PowerShell a ser executado
`cwd`	Não	Diretório de trabalho para o script (relativo à raiz do repositório)
`env`	Não	Variáveis de ambiente adicionais que são mescladas com o ambiente existente
`timeoutSec`	Não	Tempo máximo de execução em segundos (padrão: 30)

Arquivo de configuração de gancho de exemplo

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

JSON

{
  "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 a codificação de escape de shell adequada 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 Uso de ganchos com agentes do GitHub Copilot.

Sobre ganchos

Quem pode usar esse recurso?

Neste artigo

Sobre ganchos

Tipos de ganchos

Formato de configuração do gancho

Arquivo de configuração de gancho de exemplo

Considerações sobre desempenho

Considerações de segurança

Próximas etapas