Introdução Rápida para Hooks

Os ganchos permitem interceptar e personalizar o comportamento das SDK do Copilot sessões em momentos-chave no ciclo de vida da conversa. Use ganchos para:

•         **Controlar a execução da ferramenta** — aprovar, negar ou modificar chamadas de ferramenta
  

•         **Transformar resultados** – modificar saídas de ferramenta antes de serem processadas
  

•         **Adicionar contexto** — injetar informações adicionais no início da sessão
  

•         **Manipular erros** — implementar o tratamento de erros personalizados
  

•         **Auditoria e log** – acompanhar todas as interações para garantir conformidade
  

Ganchos disponíveis

Gancho	Gatilho	Caso de uso
onPreToolUse	Antes que uma ferramenta seja executada	Controle de permissão, validação de argumento
onPostToolUse	Após a execução de uma ferramenta	Transformação de resultados, registro em log
onUserPromptSubmitted	Quando o usuário envia uma mensagem	Modificação de prompt, filtragem
onSessionStart	A sessão começa	Adicionar contexto, configurar sessão
onSessionEnd	Término da sessão	Limpeza, análise
onErrorOccurred	Erro ocorre	Tratamento de erros personalizados

Início rápido

O exemplo a seguir demonstra como registrar ganchos ao criar uma sessão em Node.js/TypeScript.

import { CopilotClient } from "@github/copilot-sdk";

const client = new CopilotClient();

const session = await client.createSession({
  hooks: {
    onPreToolUse: async (input) => {
      console.log(`Tool called: ${input.toolName}`);
      // Allow all tools
      return { permissionDecision: "allow" };
    },
    onPostToolUse: async (input) => {
      console.log(
        `Tool result: ${JSON.stringify(input.toolResult)}`
      );
      return null; // No modifications
    },
    onSessionStart: async (input) => {
      return {
        additionalContext:
          "User prefers concise answers.",
      };
    },
  },
});

Para obter exemplos em Python, Go e .NET, consulte o github/copilot-sdk repositório.

Contexto de invocação do gancho

Cada gancho recebe um invocation parâmetro com contexto sobre a sessão atual.

Campo	Tipo	Descrição
sessionId	cadeia	O ID da sessão atual

Isso permite que os ganchos mantenham o estado ou executem uma lógica específica da sessão.

Padrões comuns

Registrando todas as chamadas de ferramenta

const session = await client.createSession({
  hooks: {
    onPreToolUse: async (input) => {
      console.log(
        `[${new Date().toISOString()}] Tool: `
        + `${input.toolName}, `
        + `Args: ${JSON.stringify(input.toolArgs)}`
      );
      return { permissionDecision: "allow" };
    },
    onPostToolUse: async (input) => {
      console.log(
        `[${new Date().toISOString()}] `
        + `Result: ${JSON.stringify(input.toolResult)}`
      );
      return null;
    },
  },
});

Bloquear ferramentas perigosas

const BLOCKED_TOOLS = ["shell", "bash", "exec"];

const session = await client.createSession({
  hooks: {
    onPreToolUse: async (input) => {
      if (BLOCKED_TOOLS.includes(input.toolName)) {
        return {
          permissionDecision: "deny",
          permissionDecisionReason:
            "Shell access is not permitted",
        };
      }
      return { permissionDecision: "allow" };
    },
  },
});

Adicionar contexto do usuário

const session = await client.createSession({
  hooks: {
    onSessionStart: async () => {
      const userPrefs = await loadUserPreferences();
      return {
        additionalContext:
          `User preferences: `
          + `${JSON.stringify(userPrefs)}`,
      };
    },
  },
});

Próximas Etapas 

•         [AUTOTITLE](/copilot/how-tos/copilot-sdk/use-hooks/pre-tool-use)
  

•         [AUTOTITLE](/copilot/how-tos/copilot-sdk/use-hooks/post-tool-use)
  

•         [AUTOTITLE](/copilot/how-tos/copilot-sdk/use-hooks/user-prompt-submitted)
  

•         [AUTOTITLE](/copilot/how-tos/copilot-sdk/use-hooks/session-lifecycle)
  

•         [AUTOTITLE](/copilot/how-tos/copilot-sdk/use-hooks/error-handling)