Referenz zu GitHub Copilot Hooks

Einführung

Hooks sind externe Befehle, die während einer Sitzung an bestimmten Lebenszykluspunkten ausgeführt werden und benutzerdefinierte Automatisierung, Sicherheitssteuerelemente und Integrationen ermöglichen.

Hooks werden in zwei Copilot Oberflächen unterstützt: Copilot CLI und Copilot-Cloud-Agent. Die meisten Konfigurationsformat- und Ereignisnutzlasten sind identisch, aber die Ausführungsumgebung und der Satz von Ereignissen, die ausgelöst werden können, unterscheiden sich.

In diesem Artikel wird das Verhalten, das sich zwischen den beiden Schnittstellen unterscheidet, durch die Hinweise "Nur CLI" und "Nur Cloud-Agent" gekennzeichnet. Alles, was nicht markiert ist, gilt für beides.

Hook-Positionen

Die Speicherorte, an denen Hooks ausgeführt werden und wo Sie Hook-Konfigurationsdateien speichern können, hängen von der Oberfläche ab:

• **Copilot CLI ** — Hooks werden auf dem lokalen Computer des Entwicklers in derselben Shell wie die CLI ausgeführt. Alle in diesem Artikel beschriebenen Hook-Ereignisse werden von der CLI unterstützt.

  Hooks werden aus den folgenden Quellen in Der Reihenfolge (Benutzer, dann Projekt, dann Plug-Ins) geladen und kombiniert. Wenn dasselbe Ereignis in mehreren Quellen angezeigt wird, werden alle Hook-Einträge aus allen Quellen ausgeführt.

  • Hookdateien auf Repositoryebene – .github/hooks/*.json im Repositorystamm.
  • Hookdateien auf Benutzerebene – *.json Dateien im Verzeichnis der Hooks auf Benutzerebene. Standardmäßig ist dies ~/.copilot/hooks/ unter macOS und Linux oder %USERPROFILE%\.copilot\hooks\ auf Windows. Wenn COPILOT_HOME festgelegt ist, ist es $COPILOT_HOME/hooks/.
  • Inline-Block hooks in Repositoryeinstellungen – das hooks Feld auf der obersten Ebene von .github/copilot/settings.json (Git-Commit) oder .github/copilot/settings.local.json (in der Regel git-ignored und benutzerspezifisch) im Repository. Werkzeugübergreifende .claude/settings.json und .claude/settings.local.json Dateien in Repositories werden ebenfalls gelesen.
  • Inline-Block hooks in der Konfiguration auf Benutzerebene — das hooks Feld auf der obersten Ebene von ~/.copilot/settings.json.
  • Von installierten Plug-Ins beigetragene Hooks - werden von jedem Plug-In in ihrem eigenen hooks.json (oder unter hooks/hooks.json) innerhalb des Installationsverzeichnisses des Plug-Ins deklariert.

• **Copilot-Cloud-Agent ** — Hooks werden innerhalb der kurzlebigen Linux-Sandbox ausgeführt, die der Cloud-Agent für jeden Auftrag vorgibt. Der Sandkasten ist nicht interaktiv, verfügt über ein eingeschränktes Netzwerk und wird zerstört, wenn der Auftrag endet. Eine Teilmenge von Ereignissen wird ausgelöst, und nur bash (oder command) Einträge werden berücksichtigt.

  Die Hook-Konfiguration wird aus .github/hooks/*.json Dateien im geklonten Repository geladen.

Cloud-Agent-Ausführungsumgebung

Dieser Abschnitt gilt nur fürCopilot-Cloud-Agent. Es beschreibt Einschränkungen, die sich darauf auswirken, wie Sie Hook-Skripts schreiben und Hook-Einträge für Cloud-Agent-Aufträge konfigurieren.

Eigenschaft	Wert
Betriebssystem	Linux. Nur das bash Feld für Befehlshaken wird berücksichtigt. powershell Einträge werden ignoriert. Das plattformübergreifende command Feld wird als Fallback berücksichtigt.
Arbeitsverzeichnis

          `/workspace` wenn ein Repository geklont wird, andernfalls `/root`. Verwenden Sie diesen Pfad beim Festlegen `cwd` eines Hook-Eintrags oder beim Verweisen auf Dateien aus einem Skript. |

| Filesystem | Flüchtig Dateien, die von Hooks (Protokolle, CSVs, Transkriptionen) geschrieben werden, gehen verloren, wenn die Aufgabe endet. Um die Hook-Ausgabe beizubehalten, senden Sie sie über einen http Hook-Eintrag. | | Ausgehendes Netzwerk | Eingeschränkt durch die Cloud-Agent-Firewall. Standardmäßig sind nur GitHub und Copilot Hostnamen erreichbar. Das Erreichen eines anderen Hosts (z. B. https://hooks.example.com) erfordert eine vom Administrator konfigurierte Firewall-Zulassungsregel. | | Verfügbare Umgebungsvariablen | GITHUB_COPILOT_API_TOKEN und GITHUB_COPILOT_GIT_TOKEN werden im Sandkasten gesetzt. COPILOT_AGENT_PROMPT enthält die Aufforderung, mit der der Job aufgerufen wurde. HOME ist auf /root festgelegt, sodass jedes Hook-Skript, das ~/... Pfade verarbeitet, in die temporäre Sandbox schreibt. GITHUB_TOKEN ist nicht festgelegt. | | Interaktivität | Vollständig nicht interaktiv. Der Agent wird mit allen vorab erteilten Toolberechtigungen ausgeführt, sodass keine Berechtigungsdialogflächen angezeigt werden und keine Benachrichtigungen für einen Benutzer angezeigt werden. | | Ermittlung von Konfigurationen | In einem Cloud-Agent-Auftrag befindet sich die einzige Hook-Konfiguration, die standardmäßig existiert.github/hooks/*.json, im geklonten Repository. Der Sandkasten wird nicht mit Hook-Dateien auf Benutzerebene, settings.json, config.json oder installierten Plugins ausgeliefert. |

Hook-Konfigurationsformat

Hook-Konfigurationsdateien verwenden JSON-Format mit Version 1.

Befehlshaken

Befehlshaken führen Shellskripts aus und werden für alle Hooktypen unterstützt.

{
  "version": 1,
  "hooks": {
    "preToolUse": [
      {
        "type": "command",
        "bash": "your-bash-command",
        "powershell": "your-powershell-command",
        "cwd": "optional/working/directory",
        "env": { "VAR": "value" },
        "timeoutSec": 30
      }
    ]
  }
}

Feld	Typ	Erforderlich	Description
bash	Zeichenfolge	Einer der folgenden Werte: bash, powershell oder command	Shell-Befehl für Unix.
command	Zeichenfolge	Einer der folgenden Werte: bash, powershell oder command	Plattformübergreifendes Fallback, das verwendet wird, wenn weder bash noch powershell für die aktuelle Plattform festgelegt ist.
cwd	Zeichenfolge	Nein	Arbeitsverzeichnis für den Befehl (relativ zum Repositorystamm oder absolut).
env	Objekt	Nein	Festzulegende Umgebungsvariablen (unterstützt variable Erweiterung).
powershell	Zeichenfolge	Einer der folgenden Werte: bash, powershell oder command	Shellbefehl für Windows.
timeoutSec	Zahl	Nein	Timeout in Sekunden. Standardwert: 30.
type	"command"	Ja	Muss "command" sein.

HTTP-Hooks

HTTP-Hooks senden die Eingabenutzlast als JSON POST an eine URL.

{
  "version": 1,
  "hooks": {
    "postToolUse": [
      {
        "type": "http",
        "url": "https://hooks.example.com/copilot",
        "headers": { "X-Source": "copilot-cli" },
        "allowedEnvVars": ["GITHUB_TOKEN"],
        "timeoutSec": 30
      }
    ]
  }
}

Feld	Typ	Erforderlich	Description
allowedEnvVars	string[]	Nein	Namen von Umgebungsvariablen, die innerhalb von headers Werten erweitert werden können. Wenn festgelegt, muss url``https:// verwenden.
headers	Objekt	Nein	Anforderungsheader zum Einschließen.
timeoutSec	Zahl	Nein	Timeout in Sekunden. Standardwert: 30.
type	"http"	Ja	Muss "http" sein.
url	Zeichenfolge	Ja	Ziel-URL. Es muss http: oder https: verwendet werden. Für preToolUse und permissionRequest muss https:// verwendet werden, da die Antwort Toolberechtigungen erteilen kann.

Eingabeaufforderungshaken

Prompt-Hooks senden automatisch Text, als hätte der Benutzer ihn selbst eingegeben. Sie werden ausschließlich auf sessionStart unterstützt. Der Text kann eine Aufforderung in natürlicher Sprache oder ein Slash-Befehl sein.

{
  "version": 1,
  "hooks": {
    "sessionStart": [
      {
        "type": "prompt",
        "prompt": "Your prompt text or /slash-command"
      }
    ]
  }
}

Feld	Typ	Erforderlich	Description
type	"prompt"	Ja	Muss "prompt" sein.
prompt	Zeichenfolge	Ja	Text zum Einreichen – kann eine Nachricht in natürlicher Sprache oder ein Slash-Befehl sein.

Hook-Ereignisse

In der folgenden Tabelle sind alle unterstützten Ereignisse aufgeführt. In der Spalte "Cloud-Agent " wird angezeigt, ob das Ereignis unter Cloud-Agent ausgelöst wird, und weist auf Verhaltensunterschiede hin.

Veranstaltung	Wird ausgelöst, wenn	Verarbeitete Ausgabe	Cloudagent
agentStop	Der Hauptagent beendet eine Runde.	Ja – kann die Fortsetzung blockieren und erzwingen.	Feuer.

          `decision: "block"` erzwingt eine weitere Wendung, die immer noch gegen das Timeout des Auftrags zählt. |

| errorOccurred | Während der Ausführung tritt ein Fehler auf. | Nein | Feuer. | | notification | Wird asynchron ausgelöst, wenn die CLI eine Systembenachrichtigung ausgibt (Shell-Abschluss, Agentabschluss oder Leerlauf, Berechtigungsaufforderungen, Elicitationsdialoge). Fire-and-Forget: blockiert die Sitzung nie. Unterstützt matcher regex bei notification_type. | Optional — kann additionalContext in die Sitzung einfügen. | Wird nicht ausgelöst. Der Cloud-Agent zeigt keine Benachrichtigungen an einen Benutzer an (siehe die Zeile "Interaktivität " in der Obigen Tabelle der Cloud-Agent-Ausführungsumgebung). | | permissionRequest | Wird ausgelöst, bevor der Berechtigungsdienst ausgeführt wird (Regelmodul, Sitzungsgenehmigungen, automatische Genehmigung/Automatische Ablehnung und Benutzeraufforderung). Wenn die zusammengeführte Hook-Ausgabe behavior: "allow" oder "deny" zurückgibt, wird der normale Berechtigungsfluss unterbrochen. Unterstützt matcher regex bei toolName. | Ja – kann programmgesteuert zulassen oder verweigern. | Toolaufrufe sind vorab genehmigt, sodass dieser Hook entweder nicht ausgelöst wird oder keine Auswirkung hat. Verwenden Sie preToolUse, um stattdessen Berechtigungsentscheidungen zu treffen. | | postToolUse | Nachdem jedes Tool erfolgreich abgeschlossen hat. | Nein | Feuer. | | postToolUseFailure | Nach Abschluss eines Tools mit einem Fehler. | Ja – kann Anleitungen zur Wiederherstellung über additionalContext (Exit-Code 2 für Befehlshaken) bereitstellen. | Feuer. | | preCompact | Die Kontextkomprimierung beginnt (manuell oder automatisch). Unterstützt matcher das Filtern nach Trigger ("manual" oder "auto"). | Nein – nur Benachrichtigung. | Feuert nur mit trigger: "auto". Es gibt keinen Benutzer, um eine manuelle Komprimierung anzufordern. | | preToolUse | Bevor jedes Tool ausgeführt wird. | Ja – kann zulassen, ablehnen oder ändern. | Feuer. Die Entscheidung, "ask" wird als "deny" betrachtet, weil kein Benutzer zur Beantwortung verfügbar ist. | | sessionEnd | Die Sitzung wird beendet. | Nein | Wird einmal pro Auftrag ausgelöst. reason ist in der Regel "complete", "error"oder "timeout"; "abort" und "user_exit" wird nicht erwartet, weil kein Benutzer vorhanden ist. | | sessionStart | Eine neue oder fortgesetzte Sitzung beginnt. | Optional — kann additionalContext in die Sitzung einfügen. | Löst einmal pro Auftrag als neue Sitzung (kein Lebenslauf) aus. Informationen zum Verhalten von prompt Einträgen unter dem Cloud-Agent finden Sie oben in der Anmerkung zu den Prompt Hooks. | | subagentStart | Ein Subagent wird erzeugt, bevor er ausgeführt wird. Unterstützt matcher zum Filtern nach Agentennamen. | Optional – kann die Erstellung nicht verhindern, jedoch wird additionalContext der Eingabeaufforderung des Subagents vorangestellt. | Feuer. | | subagentStop | Ein Subagent schließt ab. | Ja – kann die Fortsetzung blockieren und erzwingen. | Feuer. | | userPromptSubmitted | Der Benutzer sendet eine Eingabeaufforderung. | Nein | Wird höchstens einmal ausgelöst, um die dem Auftrag bereitgestellte Eingabeaufforderung anzuzeigen. Es gibt keine Nachverfolgung von Benutzereingaben. |

Hook-Ereigniseingabenutzlasten

Jedes Hook-Event liefert eine JSON-Nutzlast an den Hook-Handler. Zwei Nutzlastformate werden unterstützt, ausgewählt durch den Ereignisnamen, der in der Hook-Konfiguration verwendet wird:

• camelCase-Format – Konfigurieren Sie den Ereignisnamen in camelCase (z. B sessionStart. ). Felder verwenden camelCase.
• VS Code kompatibles Format – Konfigurieren Sie den Ereignisnamen in PascalCase (z. B SessionStart. ). Felder verwenden snake_case, um dem Erweiterungsformat VS CodeCopilot zu entsprechen.

sessionStart / SessionStart

          **camelCase-Eingabe:**

{
    sessionId: string;
    timestamp: number;      // Unix timestamp in milliseconds
    cwd: string;
    source: "startup" | "resume" | "new";
    initialPrompt?: string;
}

          **
          VS Code kompatible Eingabe:**

{
    hook_event_name: "SessionStart";
    session_id: string;
    timestamp: string;      // ISO 8601 timestamp
    cwd: string;
    source: "startup" | "resume" | "new";
    initial_prompt?: string;
}

sessionEnd / SessionEnd

          **camelCase-Eingabe:**

{
    sessionId: string;
    timestamp: number;
    cwd: string;
    reason: "complete" | "error" | "abort" | "timeout" | "user_exit";
}

          **
          VS Code kompatible Eingabe:**

{
    hook_event_name: "SessionEnd";
    session_id: string;
    timestamp: string;      // ISO 8601 timestamp
    cwd: string;
    reason: "complete" | "error" | "abort" | "timeout" | "user_exit";
}

userPromptSubmitted / UserPromptSubmit

          **camelCase-Eingabe:**

{
    sessionId: string;
    timestamp: number;
    cwd: string;
    prompt: string;
}

          **
          VS Code kompatible Eingabe:**

{
    hook_event_name: "UserPromptSubmit";
    session_id: string;
    timestamp: string;      // ISO 8601 timestamp
    cwd: string;
    prompt: string;
}

preToolUse / PreToolUse

          **camelCase-Eingabe:**

{
    sessionId: string;
    timestamp: number;
    cwd: string;
    toolName: string;
    toolArgs: unknown;
}

          **
          VS Code kompatible Eingabe:**

Bei der Konfiguration mit dem Namen des PascalCase-Ereignisses PreToolUseverwendet die Nutzlast snake_case Feldnamen, um dem Erweiterungsformat VS CodeCopilot zu entsprechen:

{
    hook_event_name: "PreToolUse";
    session_id: string;
    timestamp: string;      // ISO 8601 timestamp
    cwd: string;
    tool_name: string;
    tool_input: unknown;    // Tool arguments (parsed from JSON string when possible)
}

postToolUse / PostToolUse

          **camelCase-Eingabe:**

{
    sessionId: string;
    timestamp: number;
    cwd: string;
    toolName: string;
    toolArgs: unknown;
    toolResult: {
        resultType: "success";
        textResultForLlm: string;
    }
}

          **
          VS Code kompatible Eingabe:**

{
    hook_event_name: "PostToolUse";
    session_id: string;
    timestamp: string;      // ISO 8601 timestamp
    cwd: string;
    tool_name: string;
    tool_input: unknown;
    tool_result: {
        result_type: "success";
        text_result_for_llm: string;
    }
}

postToolUseFailure / PostToolUseFailure

          **camelCase-Eingabe:**

{
    sessionId: string;
    timestamp: number;
    cwd: string;
    toolName: string;
    toolArgs: unknown;
    error: string;
}

          **
          VS Code kompatible Eingabe:**

{
    hook_event_name: "PostToolUseFailure";
    session_id: string;
    timestamp: string;      // ISO 8601 timestamp
    cwd: string;
    tool_name: string;
    tool_input: unknown;
    error: string;
}

agentStop / Stop

          **camelCase-Eingabe:**

{
    sessionId: string;
    timestamp: number;
    cwd: string;
    transcriptPath: string;
    stopReason: "end_turn";
}

          **
          VS Code kompatible Eingabe:**

{
    hook_event_name: "Stop";
    session_id: string;
    timestamp: string;      // ISO 8601 timestamp
    cwd: string;
    transcript_path: string;
    stop_reason: "end_turn";
}

subagentStart

          **Eingabe:**

{
    sessionId: string;
    timestamp: number;
    cwd: string;
    transcriptPath: string;
    agentName: string;
    agentDisplayName?: string;
    agentDescription?: string;
}

subagentStop / SubagentStop

          **camelCase-Eingabe:**

{
    sessionId: string;
    timestamp: number;
    cwd: string;
    transcriptPath: string;
    agentName: string;
    agentDisplayName?: string;
    stopReason: "end_turn";
}

          **
          VS Code kompatible Eingabe:**

{
    hook_event_name: "SubagentStop";
    session_id: string;
    timestamp: string;      // ISO 8601 timestamp
    cwd: string;
    transcript_path: string;
    agent_name: string;
    agent_display_name?: string;
    stop_reason: "end_turn";
}

errorOccurred / ErrorOccurred

          **camelCase-Eingabe:**

{
    sessionId: string;
    timestamp: number;
    cwd: string;
    error: {
        message: string;
        name: string;
        stack?: string;
    };
    errorContext: "model_call" | "tool_execution" | "system" | "user_input";
    recoverable: boolean;
}

          **
          VS Code kompatible Eingabe:**

{
    hook_event_name: "ErrorOccurred";
    session_id: string;
    timestamp: string;      // ISO 8601 timestamp
    cwd: string;
    error: {
        message: string;
        name: string;
        stack?: string;
    };
    error_context: "model_call" | "tool_execution" | "system" | "user_input";
    recoverable: boolean;
}

preCompact / PreCompact

          **camelCase-Eingabe:**

{
    sessionId: string;
    timestamp: number;
    cwd: string;
    transcriptPath: string;
    trigger: "manual" | "auto";
    customInstructions: string;
}

          **
          VS Code kompatible Eingabe:**

{
    hook_event_name: "PreCompact";
    session_id: string;
    timestamp: string;      // ISO 8601 timestamp
    cwd: string;
    transcript_path: string;
    trigger: "manual" | "auto";
    custom_instructions: string;
}

preToolUse Entscheidungssteuerung

Der preToolUse Hook kann die Toolausführung steuern, indem ein JSON-Objekt in stdout geschrieben wird.

Feld	Werte	Description
permissionDecision

          `"allow"`, `"deny"`, `"ask"` | Gibt an, ob das Tool ausgeführt wird. Leere Ausgabe verwendet Standardverhalten. Unter dem Cloud-Agent wird `"ask"` als `"deny"` behandelt, da kein Benutzer zur Beantwortung verfügbar ist. |

| permissionDecisionReason | Zeichenfolge | Grund, der dem Agenten angezeigt wird. Erforderlich, wenn die Entscheidung lautet "deny". | | modifiedArgs | Objekt | Ersetzen Sie Toolargumente, die anstelle der Originale verwendet werden sollen. |

agentStop

           / 
          `subagentStop` Entscheidungssteuerung

Feld	Werte	Description
decision

          `"block"`, `"allow"` | 
          `"block"` erzwingt, dass ein anderer Agent die Verwendung `reason` als Eingabeaufforderung einfordert. |

| reason | Zeichenfolge | Aufforderung für den nächsten Schritt, wenn decision``"block" ist. |

permissionRequest Entscheidungssteuerung

Der permissionRequest Hook wird ausgelöst, bevor der Berechtigungsdienst ausgeführt wird – vor Regelüberprüfungen, Sitzungsgenehmigungen, automatisches Zulassen/automatisches Verweigern und bevor Benutzeraufforderungen erfolgen. Wenn Hooks behavior: "allow" oder "deny" zurückgeben, übergeht diese Entscheidung den normalen Berechtigungsfluss. Wenn nichts zurückgegeben wird, geht es in die normale Berechtigungsbehandlung über. Verwenden Sie es, um Toolaufrufe programmgesteuert zu genehmigen oder zu verweigern – besonders nützlich im CLI-Pipemodus (-p) und anderen CLI CI-Verwendungen, bei denen keine interaktive Eingabeaufforderung verfügbar ist. Sie gilt nicht für Cloud-Agent.

Für jede Anforderung werden alle konfigurierten permissionRequest Hooks ausgeführt (mit Ausnahme von read und hook Berechtigungsarten, die vor den Hooks kurzschließen). Spätere Hook-Ausgaben haben Vorrang vor früheren bei der Zusammenführung.

          **Matcher:** Ein optionaler Regex, getestet gegen `toolName`. Verankert als `^(?:pattern)$`; muss mit dem vollständigen Toolnamen übereinstimmen. Wenn festgelegt, wird der Hook nur bei übereinstimmenden Werkzeugnamen ausgelöst.

Ausgabe von JSON an stdout, um die Berechtigungsentscheidung zu steuern.

Feld	Werte	Description
behavior

          `"allow"`, `"deny"` | Gibt an, ob der Toolaufruf genehmigt oder verweigert werden soll. |

| message | Zeichenfolge | Grund, der beim Verweigern wieder zur LLM zurückgespeist wird. | | interrupt | Boolescher Wert | Wenn true mit "deny" kombiniert wird, stoppt der Agent vollständig. |

Geben Sie eine leere Ausgabe zurück oder {} gehen Sie in den normalen Berechtigungsfluss um. Bei Befehls-Hooks wird der Beendigungscode 2 als Verweigerung behandelt; stdout JSON (falls vorhanden) wird mit {"behavior":"deny"} zusammengeführt, und stderr wird ignoriert.

notification Haken

Der notification Hook wird asynchron ausgelöst, wenn die CLI eine Systembenachrichtigung ausgibt. Diese Hooks funktionieren nach dem Prinzip "fire-and-forget": Sie blockieren niemals die Sitzung, und alle Fehler werden protokolliert und übersprungen.

          **Eingabe:**

{
    sessionId: string;
    timestamp: number;
    cwd: string;
    hook_event_name: "Notification";
    message: string;           // Human-readable notification text
    title?: string;            // Short title (e.g., "Permission needed", "Shell completed")
    notification_type: string; // One of the types listed below
}

          **Benachrichtigungstypen:**

Typ	Wenn es ausgelöst wird
shell_completed	Ein Hintergrund-Shellbefehl (asynchron) wird beendet.
shell_detached_completed	Eine getrennte Shell-Sitzung ist beendet.
agent_completed	Ein Unteragent im Hintergrund wird abgeschlossen (abgeschlossen oder fehlgeschlagen)
agent_idle	Ein Hintergrund-Agent beendet einen Umlauf und wechselt in den Leerlaufmodus (wartend auf write_agent)
permission_prompt	Der Agent fordert die Berechtigung zum Ausführen eines Tools an.
elicitation_dialog	Der Agent fordert zusätzliche Informationen vom Benutzer an.

          **Ausgabe:**

{
    additionalContext?: string; // Injected into the session as a user message
}

Wenn der Text additionalContext zurückgegeben wird, wird er als vorangestellte Benutzernachricht in die Sitzung gespritzt. Dies kann die weitere Agentverarbeitung auslösen, wenn die Sitzung im Leerlauf ist. Geben Sie {} oder eine leere Ausgabe zurück, um keine Aktion auszuführen.

          **Matcher:** Optionales Regex für `notification_type`. Das Muster ist als `^(?:pattern)$`verankert. Um alle Benachrichtigungstypen zu erhalten, lassen Sie `matcher` weg.

Abgleichsfilterung

Mehrere Ereignisse akzeptieren einen optionalen matcher Regex für jeden Hookeintrag, der festlegt, bei welchen Aufrufe der Hook ausgelöst wird. Das Muster ist als ^(?:matcher)$ verankert und muss mit dem vollständigen Wert übereinstimmen. Ungültige Regexes führen dazu, dass der Hook-Eintrag übersprungen wird.

| Veranstaltung | matcher wird abgeglichen mit | |-------|------------------------------| | notification | notification_type | | permissionRequest | toolName | | preCompact | trigger ("manual" oder "auto") | | preToolUse | toolName | | subagentStart | agentName |

Toolnamen für den Hook-Abgleich

Toolname	Description
ask_user	Stellen Sie dem Benutzer eine klarstellende Frage. Unter dem Cloud-Agent gibt es keinen Benutzer, sodass ask_user kein nützliches Ergebnis entsteht.
bash	Ausführen von Shellbefehlen (Unix).
create	Erstellen Sie neue Dateien.
edit	Dateiinhalte ändern.
glob	Suchen Sie Dateien nach Mustern.
grep	Dateiinhalte durchsuchen.
powershell	Ausführen von Shellbefehlen (Windows). Wird nicht unter Cloud-Agent (Linux-Sandkasten) angezeigt.
task	Führen Sie Subagent-Aufgaben aus.
view	Dateiinhalte lesen.
web_fetch	Webseiten abrufen.

Wenn mehrere Hooks desselben Typs konfiguriert sind, werden sie in der reihenfolge ausgeführt. Wenn preToolUseirgendein Hook "deny"zurückgibt, wird das Tool blockiert. Hook-Fehler (andere Nicht-Null-Beendigungscodes als 2, oder Timeouts) werden protokolliert und übersprungen – sie blockieren niemals die Ausführung des Agents.

Exit-Codes für Kommando-Hooks

Exitcode	Dies bedeutet
0	Erfolg.

          `stdout` wird als HOOK-Ausgabe-JSON analysiert, falls vorhanden. |

| 2 | Wird standardmäßig als Warnung behandelt. stderr wird dem Benutzer angezeigt, aber die Ausführung wird fortgesetzt. Bei permissionRequest wird der Exit 2 als {"behavior":"deny"} behandelt, und alle stdout-JSON-Inhalte werden zusammengeführt. Bei postToolUseFailure, exit 2 wird behandelt als additionalContext und stdout wird an den Fehler angefügt, der dem Agent angezeigt wird. | | Andere Nicht-Null | Protokolliert als Hook-Fehler. Die Ausführung wird fortgesetzt (fail-open). |

Alle Hooks deaktivieren

Verwenden Sie disableAllHooks, wenn Sie die Hookkonfiguration auf dem Datenträger beibehalten möchten, sie aber nicht mehr ausführen möchten, z. B.:

• Wenn Sie ein Problem debuggen und bestätigen möchten, dass ein Hook die Ursache ist, ohne Ihre Konfiguration zu löschen.
• Anhalten der Automatisierung während einer sensiblen Aufgabe (Codeüberprüfung, eine Release-Branch, Arbeiten mit Geheimnissen), ohne das Setup zu verlieren. (Copilot CLI nur.)
• Senden einer Hooks-Datei in der Quellcodeverwaltung, die Mitwirkende lokal deaktivieren können, indem Sie die Option in ihrem Repository settings.jsonfestlegen. (Copilot CLI nur.)
• Vorübergehendes Stummschalten langsam arbeitender oder lauter Hooks während einer interaktiven Sitzung. (Copilot CLI nur.)

Legen Sie disableAllHooks auf true auf oberster Ebene fest, um jeden Hook in der Datei zu überspringen, ohne ihn zu löschen.

{
  "version": 1,
  "disableAllHooks": false,
  "hooks": {
    "preToolUse": [ /* hook entries */ ]
  }
}

Das Verhalten hängt davon ab, wo Sie das Kennzeichen setzen.

• Innerhalb einer einzelnen .github/hooks/*.json Datei – nur die in dieser Datei deklarierten Hooks werden übersprungen. Geehrt sowohl von Copilot CLI als auch von Copilot-Cloud-Agent.
• Auf der obersten Ebene des Repositorys settings.json****—Copilot CLI nur. Jeder Hook aus jeder Quelle (Repositorydateien, Benutzerdateien, Plug-Ins und Inline-Hook-Blöcke) wird für Sitzungen in diesem Repository übersprungen. Der Cloud-Agent lädt nicht settings.json.

Weiterführende Lektüre

• Verwenden von Hooks mit GitHub Copilot-CLI
• Referenz zu GitHub Copilot Hooks
• GitHub Copilot CLI-Befehlsreferenz
• Konzepte für GitHub Copilot Cloud-Agent