GitHub Copilot CLI-Hooks-Referenz

Hooks sind externe Befehle, die während einer Sitzung an bestimmten Lebenszykluspunkten ausgeführt werden und benutzerdefinierte Automatisierung, Sicherheitssteuerelemente und Integrationen ermöglichen. Hook-Konfigurationsdateien werden automatisch von .github/hooks/*.json in Ihrem Repository geladen.

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`	Schnur	Einer von `bash`/`powershell`	Shell-Befehl für Unix.
`cwd`	Schnur	No	Arbeitsverzeichnis für den Befehl (relativ zum Repositorystamm oder absolut).
`env`	Objekt	No	Festzulegende Umgebungsvariablen (unterstützt variable Erweiterung).
`powershell`	Schnur	Einer von `bash`/`powershell`	Shellbefehl für Windows.
`timeoutSec`	Zahl	No	Timeout in Sekunden. Standardwert: `30`.
`type`	`"command"`	Ja	Muss `"command"`lauten.

Eingabeaufforderungshaken

Prompt-Hooks senden automatisch Text, als hätte der Benutzer ihn selbst eingegeben. Sie werden nur auf sessionStart unterstützt und nur für neue interaktive Sitzungen ausgelöst. Sie werden beim Fortsetzen nicht ausgelöst, und sie werden nicht im nicht interaktiven Eingabeaufforderungsmodus (-p) ausgelöst. 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"`lauten.
`prompt`	Schnur	Ja	Text zum Einreichen – kann eine Nachricht in natürlicher Sprache oder ein Slash-Befehl sein.

Hook-Ereignisse

Event	Wird ausgelöst, wenn	Verarbeitete Ausgabe
`agentStop`	Der Hauptagent beendet eine Runde.	Ja – kann die Fortsetzung blockieren und erzwingen.
`errorOccurred`	Während der Ausführung tritt ein Fehler auf.	No
`notification`	Wird asynchron ausgelöst, wenn die CLI eine Systembenachrichtigung sendet (Shell-Abschluss, Agentenabschluss oder Leerlauf, Berechtigungsaufforderungen, Abfragedialoge). Fire-and-forget: blockiert niemals die Sitzung. Unterstützt `matcher` RegEx auf `notification_type`.	Optional — kann `additionalContext` in die Sitzung einfügen.
`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 auf `toolName`.	Ja – kann programmgesteuert zulassen oder verweigern.
`postToolUse`	Nachdem jedes Tool erfolgreich abgeschlossen hat.	Ja - kann das erfolgreiche Ergebnis ersetzen (nur programmgesteuerte SDK-Hooks).
`postToolUseFailure`	Nachdem ein Werkzeug mit einem Fehler abgeschlossen wurde.	Ja – kann Anleitungen zur Wiederherstellung über `additionalContext` (Exit-Code `2` für Befehlshaken) bereitstellen.
`preCompact`	Die Kontextkomprimierung beginnt (manuell oder automatisch). Unterstützt `matcher` das Filtern nach Trigger (`"manual"` oder `"auto"`).	Nein – nur Benachrichtigung.
`preToolUse`	Bevor jedes Tool ausgeführt wird.	Ja – kann zulassen, ablehnen oder ändern.
`sessionEnd`	Die Sitzung wird beendet.	No
`sessionStart`	Eine neue oder fortgesetzte Sitzung beginnt.	No
`subagentStart`	Ein Unteragent wird erzeugt (bevor er ausgeführt wird). Gibt `additionalContext` zurück, das der Eingabeaufforderung des Unteragenten vorangestellt wird. Unterstützt `matcher` zum Filtern nach Agentennamen.	Nein – die Erstellung kann nicht blockiert werden.
`subagentStop`	Ein Subagent schließt ab.	Ja – kann die Fortsetzung blockieren und erzwingen.
`userPromptSubmitted`	Der Benutzer sendet eine Eingabeaufforderung.	No

Hook-Ereignis-Eingabe-Nutzdaten

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" | "failure" | "denied" | "error";
        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. |

          `agentStop`
           / 
          `subagentStop` Entscheidungssteuerung

Feld	Werte	Description
`decision`

          `"block"`, `"allow"` |               `"block"` Setzt einen anderen Agent-Turn mittels `reason` als Prompt durch. |

| reason | Schnur | 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 sie, um Toolaufrufe programmgesteuert zu genehmigen oder zu verweigern – besonders nützlich im Pipemodus (-p) und CI-Umgebungen, in denen keine interaktive Eingabeaufforderung verfügbar ist.

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 diese Option gesetzt ist, wird der Haken 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. |

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` Hook

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	Bei Aktivierung
`shell_completed`	Ein Shell-Befehl im Hintergrund (asynchron) wird beendet
`shell_detached_completed`	Eine getrennte Shell-Sitzung ist beendet.
`agent_completed`	Ein Hintergrund-Unteragent wird beendet (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 eine weitere Verarbeitung durch den Agenten 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.

Toolnamen für Hookabgleich

Name des Tools	Description
`ask_user`	Stellen Sie dem Benutzer eine klarstellende Frage.
`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).
`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 in preToolUse ein Hook "deny" zurückgibt, wird das Tool blockiert. Bei postToolUseFailure-Befehlshooks führt das Beenden mit dem Code 2 dazu, dass stderr als Wiederherstellungsanleitung für den Assistenten zurückgegeben wird. Hookfehler (Nicht-Null-Beendigungscodes oder -Timeouts) werden protokolliert und übersprungen. Sie blockieren niemals die Agent-Ausführung.

In diesem Artikel