Haken zur Verwendung vor Werkzeugen

Der onPreToolUse Hook wird aufgerufen , bevor ein Tool ausgeführt wird. Verwenden Sie es zu folgenden Zwecken:

• Genehmigen oder Verweigern der Toolausführung
• Ändern von Toolargumenten
• Hinzufügen von Kontext für das Tool
• Toolausgabe aus der Unterhaltung unterdrücken

Hook-Signatur

import type { PreToolUseHookInput, HookInvocation, PreToolUseHookOutput } from "@github/copilot-sdk";
type PreToolUseHandler = (
  input: PreToolUseHookInput,
  invocation: HookInvocation
) => Promise<PreToolUseHookOutput | null | undefined>;

Die Hook-Signaturen in Python, Go und .NET finden Sie im github/copilot-sdk Repository.

Eingabe

Feld	Typ	Beschreibung
timestamp	Zahl	Unix-Zeitstempel, zu dem der Hook ausgelöst wurde
cwd	Schnur	Aktuelles Arbeitsverzeichnis
toolName	Schnur	Name des aufgerufenen Tools
toolArgs	Objekt	An das Tool übergebene Argumente

Output

Geben Sie null oder undefined zurück, um das Tool ohne Änderungen auszuführen. Geben Sie andernfalls ein Objekt mit einem der folgenden Felder zurück.

Feld	Typ	Beschreibung
permissionDecision

          `"allow"`
          \|
          `"deny"`
          \|
          `"ask"`
         | Gibt an, ob der Toolaufruf zugelassen werden soll. |

| permissionDecisionReason | Schnur | Erläuterung, die dem Benutzer angezeigt wird (zur Ablehnung/Frage) | | modifiedArgs | Objekt | Geänderte Argumente, die an das Tool übergeben werden sollen | | additionalContext | Schnur | Zusätzlicher Kontext, der in die Unterhaltung eingefügt wurde | | suppressOutput | boolean | Wenn wahr, wird die Toolausgabe nicht in Unterhaltungen angezeigt. |

Berechtigungsentscheidungen

Entscheidung	Verhalten
"allow"	Das Tool wird normal ausgeführt
"deny"	Tool ist blockiert, Grund, der dem Benutzer angezeigt wird
"ask"	Der Benutzer wird aufgefordert, den Zugriff (im interaktiven Modus) zu genehmigen.

Beispiele

Alle Tools zulassen (nur Protokollierung)

const session = await client.createSession({
  hooks: {
    onPreToolUse: async (input, invocation) => {
      console.log(
        `[${invocation.sessionId}] `
        + `Calling ${input.toolName}`
      );
      console.log(
        `  Args: ${JSON.stringify(input.toolArgs)}`
      );
      return { permissionDecision: "allow" };
    },
  },
});

Beispiele in Python, Go und .NET finden Sie im github/copilot-sdk Repository.

Blockieren bestimmter Tools

const BLOCKED_TOOLS = [
  "shell", "bash", "write_file", "delete_file",
];

const session = await client.createSession({
  hooks: {
    onPreToolUse: async (input) => {
      if (BLOCKED_TOOLS.includes(input.toolName)) {
        return {
          permissionDecision: "deny",
          permissionDecisionReason:
            `Tool '${input.toolName}' `
            + `is not permitted in this environment`,
        };
      }
      return { permissionDecision: "allow" };
    },
  },
});

Ändern von Toolargumenten

const session = await client.createSession({
  hooks: {
    onPreToolUse: async (input) => {
      // Add a default timeout to all shell commands
      if (
        input.toolName === "shell" && input.toolArgs
      ) {
        const args = input.toolArgs as {
          command: string;
          timeout?: number;
        };
        return {
          permissionDecision: "allow",
          modifiedArgs: {
            ...args,
            timeout: args.timeout ?? 30000,
          },
        };
      }
      return { permissionDecision: "allow" };
    },
  },
});

Einschränken des Dateizugriffs auf bestimmte Verzeichnisse

const ALLOWED_DIRECTORIES = [
  "/home/user/projects", "/tmp",
];

const session = await client.createSession({
  hooks: {
    onPreToolUse: async (input) => {
      if (
        input.toolName === "read_file"
        || input.toolName === "write_file"
      ) {
        const args = input.toolArgs as {
          path: string;
        };
        const isAllowed =
          ALLOWED_DIRECTORIES.some((dir) =>
            args.path.startsWith(dir)
          );

        if (!isAllowed) {
          return {
            permissionDecision: "deny",
            permissionDecisionReason:
              `Access to '${args.path}' `
              + `is not permitted. `
              + `Allowed directories: `
              + ALLOWED_DIRECTORIES.join(", "),
          };
        }
      }
      return { permissionDecision: "allow" };
    },
  },
});

Ausführliche Toolausgabe unterdrücken

const VERBOSE_TOOLS = ["list_directory", "search_files"];

const session = await client.createSession({
  hooks: {
    onPreToolUse: async (input) => {
      return {
        permissionDecision: "allow",
        suppressOutput: VERBOSE_TOOLS.includes(input.toolName),
      };
    },
  },
});

Hinzufügen von Kontext basierend auf dem Tool

const session = await client.createSession({
  hooks: {
    onPreToolUse: async (input) => {
      if (input.toolName === "query_database") {
        return {
          permissionDecision: "allow",
          additionalContext:
            "Remember: This database uses "
            + "PostgreSQL syntax. "
            + "Always use parameterized queries.",
        };
      }
      return { permissionDecision: "allow" };
    },
  },
});

Bewährte Methoden

•         **Stellen Sie sicher, dass Sie immer eine Entscheidung zurückgeben.** Das Zurückgeben von `null` erlaubt es, das Tool zu verwenden, aber die explizite Angabe von `{ permissionDecision: "allow" }` ist klarer.
  

•         **Geben Sie hilfreiche Ablehnungsgründe an.** Erläutern Sie beim Verweigern, warum, damit Benutzer verstehen, was passiert ist.
  

•         **Achten Sie bei der Argumentänderung darauf.** Stellen Sie sicher, dass geänderte Argumente das erwartete Schema für das Tool beibehalten.
  

•         **Berücksichtigen Sie die Leistung.** Vortool-Hooks werden synchron vor jedem Toolaufruf ausgeführt. Halten Sie sie schnell bereit.
  

•         **Verwenden Sie `suppressOutput` sorgfältig.** Die Unterdrückung der Ausgabe bedeutet, dass das Modell das Ergebnis nicht sieht, was sich auf die Gesprächsqualität auswirken kann.
  

•         **Achten Sie auf vertrauliche Daten.** Toolargumente und Ergebnisse können geheime Schlüssel, Dateipfade oder persönlich identifizierbare Informationen enthalten. Vermeiden Sie das Protokollieren oder Verfügbarmachen dieser Daten in Produktionsumgebungen.
  

Weiterführende Lektüre

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

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

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