Ganchos de sessão

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 registro - acompanhe todas as interações para fins de conformidade

Para hooks de sistema de arquivos carregados de diretórios de inicialização adicionais em vez de callbacks do SDK registrados, consulte Trabalhando com ganchos.

Ganchos disponíveis

Gancho	Gatilho	Caso de uso
Gancho de uso de pré-ferramenta	Antes que uma ferramenta seja executada	Controle de permissão, validação de argumento
Gancho de uso pós-ferramenta	Após a execução de uma ferramenta (apenas em caso de sucesso)	Transformação de resultados, registro em log
Gancho de uso pós-ferramenta	Após uma execução de ferramenta cujo resultado foi uma falha	Inserir orientações para nova tentativa, registrar falhas
Gancho enviado pelo prompt do usuário	Quando o usuário envia uma mensagem	Modificação de prompt, filtragem
Gancho transformado do prompt do usuário	Depois da transformação do prompt em runtime	Inspecionar ou substituir o conteúdo voltado para o modelo
Ganchos de ciclo de vida de sessão	A sessão começa	Adicionar contexto, configurar sessão
Ganchos de ciclo de vida de sessão	Término da sessão	Limpeza, análise
Gancho de tratamento de erros	Erro ocorre	Tratamento de erros personalizados
Ganchos de ciclo de vida de sessão	O agente de nível superior para naturalmente	Validar a conclusão ou solicitar outra execução

Início rápido

Idiomas de código navigation

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." };
    },
  },
});

Python

from copilot import CopilotClient
from copilot.session import PermissionHandler

async def main():
    client = CopilotClient()
    await client.start()

    async def on_pre_tool_use(input_data, invocation):
        print(f"Tool called: {input_data['toolName']}")
        return {"permissionDecision": "allow"}

    async def on_post_tool_use(input_data, invocation):
        print(f"Tool result: {input_data['toolResult']}")
        return None

    async def on_session_start(input_data, invocation):
        return {"additionalContext": "User prefers concise answers."}

    session = await client.create_session(on_permission_request=PermissionHandler.approve_all, hooks={
            "on_pre_tool_use": on_pre_tool_use,
            "on_post_tool_use": on_post_tool_use,
            "on_session_start": on_session_start,
        })

package main

import (
    "context"
    "fmt"
    copilot "github.com/github/copilot-sdk/go"
)

func main() {
    client := copilot.NewClient(nil)

    session, _ := client.CreateSession(context.Background(), &copilot.SessionConfig{
        Hooks: &copilot.SessionHooks{
            OnPreToolUse: func(input copilot.PreToolUseHookInput, inv copilot.HookInvocation) (*copilot.PreToolUseHookOutput, error) {
                fmt.Printf("Tool called: %s\n", input.ToolName)
                return &copilot.PreToolUseHookOutput{
                    PermissionDecision: "allow",
                }, nil
            },
            OnPostToolUse: func(input copilot.PostToolUseHookInput, inv copilot.HookInvocation) (*copilot.PostToolUseHookOutput, error) {
                fmt.Printf("Tool result: %v\n", input.ToolResult)
                return nil, nil
            },
            OnSessionStart: func(input copilot.SessionStartHookInput, inv copilot.HookInvocation) (*copilot.SessionStartHookOutput, error) {
                return &copilot.SessionStartHookOutput{
                    AdditionalContext: "User prefers concise answers.",
                }, nil
            },
        },
    })
    _ = session
}

.NET

using GitHub.Copilot;

var client = new CopilotClient();

var session = await client.CreateSessionAsync(new SessionConfig
{
    Hooks = new SessionHooks
    {
        OnPreToolUse = (input, invocation) =>
        {
            Console.WriteLine($"Tool called: {input.ToolName}");
            return Task.FromResult<PreToolUseHookOutput?>(
                new PreToolUseHookOutput { PermissionDecision = "allow" }
            );
        },
        OnPostToolUse = (input, invocation) =>
        {
            Console.WriteLine($"Tool result: {input.ToolResult}");
            return Task.FromResult<PostToolUseHookOutput?>(null);
        },
        OnSessionStart = (input, invocation) =>
        {
            return Task.FromResult<SessionStartHookOutput?>(
                new SessionStartHookOutput { AdditionalContext = "User prefers concise answers." }
            );
        },
    },
});

Java

import com.github.copilot.*;
import com.github.copilot.rpc.*;
import java.util.concurrent.CompletableFuture;

try (var client = new CopilotClient()) {
    client.start().get();

    var hooks = new SessionHooks()
        .setOnPreToolUse((input, invocation) -> {
            System.out.println("Tool called: " + input.getToolName());
            return CompletableFuture.completedFuture(PreToolUseHookOutput.allow());
        })
        .setOnPostToolUse((input, invocation) -> {
            System.out.println("Tool result: " + input.getToolResult());
            return CompletableFuture.completedFuture(null);
        })
        .setOnSessionStart((input, invocation) -> {
            return CompletableFuture.completedFuture(
                new SessionStartHookOutput("User prefers concise answers.", null)
            );
        });

    var session = client.createSession(
        new SessionConfig()
            .setHooks(hooks)
            .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
    ).get();
}

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)}`,
      };
    },
  },
});

Guias de gancho

Gancho de uso de pré-ferramenta – Controlar permissões de execução da ferramenta
Gancho de uso pós-ferramenta – Transformar resultados da ferramenta
Gancho enviado pelo prompt do usuário – Modificar prompts do usuário
Gancho transformado do prompt do usuário – Substituir prompts voltados para modelo
Ganchos de ciclo de vida de sessão – Início e término da sessão
Ganchos de ciclo de vida de sessão – Validar a conclusão antes que o agente pare
Gancho de tratamento de erros – Tratamento de erros personalizado

Neste artigo