{"meta":{"title":"GitHub Copilot-Hooks-Referenz","intro":"Suchen Sie Hook-Ereignisse, Konfigurationsformate und Eingabenutzlasten für Hooks in Copilot CLI und Copilot cloud agent.","product":"GitHub Copilot","breadcrumbs":[{"href":"/de/enterprise-cloud@latest/copilot","title":"GitHub Copilot"},{"href":"/de/enterprise-cloud@latest/copilot/reference","title":"Verweis"},{"href":"/de/enterprise-cloud@latest/copilot/reference/hooks-reference","title":"Hooks-Referenz"}],"documentType":"article"},"body":"# GitHub Copilot-Hooks-Referenz\n\nSuchen Sie Hook-Ereignisse, Konfigurationsformate und Eingabenutzlasten für Hooks in Copilot CLI und Copilot cloud agent.\n\n## Einführung\n\nHooks sind externe Befehle, die während einer Sitzung an bestimmten Lebenszykluspunkten ausgeführt werden und benutzerdefinierte Automatisierung, Sicherheitssteuerelemente und Integrationen ermöglichen.\n\nHooks 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.\n\nIn 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.\n\n## Hooks-Positionen\n\nDie Speicherorte, an denen Hooks ausgeführt werden und wo Sie Hook-Konfigurationsdateien speichern können, hängen von der Oberfläche ab:\n\n* **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.\n\n Hooks werden aus den folgenden Quellen in der Reihenfolge geladen (Richtlinie, dann Benutzer, dann Projekt, dann Plug-Ins) und kombiniert. Wenn dasselbe Ereignis in mehreren Quellen angezeigt wird, werden alle Hook-Einträge aus allen Quellen ausgeführt.\n\n * **Hookdateien auf Richtlinienebene – JSON-Dateien** im plattformgerechten Richtlinienverzeichnis, geladen in alphabetischer Reihenfolge. Richtlinienhooks gelten systemweit und werden vor allen anderen Hooks geladen. Sie können durch `disableAllHooks` nicht deaktiviert werden und sind unabhängig vom Vertrauensstatus des Ordners verfügbar. Siehe unten [Policy-Hooks](#policy-hooks).\n * **Hookdateien auf Repositoryebene** – `.github/hooks/*.json` im Repositorystamm.\n * **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/`.\n * **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.\n * **Inline-Block `hooks` in der Konfiguration auf Benutzerebene** – das `hooks` Feld auf der obersten Ebene von `~/.copilot/settings.json`.\n * **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.\n\n* **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.\n\n Die Hook-Konfiguration wird aus `.github/hooks/*.json` Dateien im geklonten Repository geladen.\n\n### Richtlinienhooks\n\n> \\[!NOTE]\n> **Copilot CLI Nur.** Policy Hooks werden unter Copilot cloud agent nicht unterstützt.\n\nPolicy-Hooks sind systemweite Hooks, die von Administratoren geladen werden. Sie laden vor allen anderen Hooks und können nicht durch `disableAllHooks`deaktiviert werden.\n\nRichtlinienhooks werden aus zwei Quellen ermittelt:\n\n* **Dateisystem**: JSON-Dateien im plattformgerechten Richtlinienverzeichnis, geladen in alphabetischer Reihenfolge:\n * Linux/macOS: `/etc/github-copilot/policy.d/*.json`\n * Fenster: `C:\\ProgramData\\GitHub\\Copilot\\policy.d\\*.json`\n* **Windows Registry**: Werte unter `HKLM\\Software\\Policies\\GitHub\\Copilot` (jeder Unterschlüssel enthält einen `Policy` REG\\_SZ-Wert, der ein JSON-Richtliniendokument enthält).\n\nPolicy-Hook-Dateien verwenden dasselbe Hook-Konfigurationsformat wie Benutzer- und Projekt-Hooks (`{ \"version\": 1, \"hooks\": { ... } }`). Auf POSIX-Systemen müssen Richtliniendateien dem Stammbenutzer gehören und dürfen weder für Gruppen noch umfassend beschreibbar sein.\n\nPolicy-Hooks sind zur Verwendung durch Unternehmens-IT-Administratoren vorgesehen und erfordern zur Installation erhöhte Berechtigungen. Endbenutzer können sie nicht ändern.\n\n## Cloud-Agent-Ausführungsumgebung\n\nDieser Abschnitt gilt nur für**Copilot 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.\n\n| Eigenschaft | Wert |\n| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 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. |\n| Arbeitsverzeichnis | |\n| `/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. | |\n| 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. |\n| 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. |\n| Verfügbare Umgebungsvariablen | |\n| `GITHUB_COPILOT_API_TOKEN` und `GITHUB_COPILOT_GIT_TOKEN` werden im Sandkasten gesetzt. | |\n| `COPILOT_AGENT_PROMPT` enthält die Aufforderung, mit der der Job aufgerufen wurde. | |\n| `HOME` ist auf `/root` festgelegt, sodass jedes Hook-Skript, das `~/...` Pfade verarbeitet, in die temporäre Sandbox schreibt. | |\n| `GITHUB_TOKEN` ist nicht festgelegt. | |\n| 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. |\n| Ermittlung von Konfigurationen | In einem Cloud-Agent-Auftrag ist `.github/hooks/*.json` die einzige Hook-Konfiguration, die standardmäßig im geklonten Repository existiert. Die Sandbox wird nicht mit Hook-Dateien auf Benutzerebene, `settings.json`, `config.json` oder installierten Plugins ausgeliefert. |\n\n## Hook-Konfigurationsformat\n\nHook-Konfigurationsdateien verwenden JSON-Format mit Version `1`.\n\n> \\[!NOTE]\n> Wenn eine aus einem Verzeichnis geladene Hook-Konfigurationsdatei (zum Beispiel `.github/hooks/`) ein fehlerhaftes Hook-Element enthält, wird nur dieses Element verworfen und protokolliert – andere gültige Hooks in derselben Datei werden weiterhin geladen. Strukturelle Fehler (ungültiger JSON-Code, ungültiger `version`JSON-Code oder eine Nicht-Array-Ereignisliste) lehnen die gesamte Datei weiterhin ab. Hooks, die inline in `settings.json` definiert sind, bleiben strikt: Jeder Validierungsfehler auf Elementebene führt zur Ablehnung des gesamten `hooks`-Felds. Andere Konfigurationsdateien werden immer unabhängig geladen.\n\n### Befehlshaken\n\nBefehlshaken führen Shellskripts aus und werden für alle Hooktypen unterstützt.\n\n> \\[!NOTE]\n> **Cloud-Agent nur.** Cloud-Agent führt Hooks in einer Linux-Sandbox aus. Nur das `bash` Feld wird berücksichtigt. `powershell` Einträge werden ignoriert. Das plattformübergreifende `command` Feld wird als Fallback berücksichtigt.\n\n```json\n{\n \"version\": 1,\n \"hooks\": {\n \"preToolUse\": [\n {\n \"type\": \"command\",\n \"bash\": \"YOUR_BASH_COMMAND\",\n \"powershell\": \"YOUR_POWERSHELL_COMMAND\",\n \"cwd\": \"OPTIONAL/WORKING/DIRECTORY\",\n \"env\": { \"VAR\": \"VALUE\" },\n \"timeoutSec\": 30\n }\n ]\n }\n}\n```\n\n| Feld | Typ | Erforderlich | Description |\n| ------------ | ------------ | -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `bash` | Zeichenfolge | Einer der folgenden Werte: `bash`, `powershell` oder `command` | Shell-Befehl für Unix. |\n| `command` | Zeichenfolge | Einer der folgenden Werte: `bash`, `powershell` oder `command` | Plattformübergreifende Ausweichlösung. Wird sowohl in `bash` als auch in `powershell` kopiert, falls diese Felder fehlen; explizite `bash`- oder `powershell`-Einträge haben auf den jeweiligen Plattformen Vorrang. |\n| `cwd` | Zeichenfolge | Nein | Arbeitsverzeichnis für den Befehl (relativ zum Repositorystamm oder absolut). |\n| `env` | Objekt | Nein | Festzulegende Umgebungsvariablen (unterstützt variable Erweiterung). |\n| `powershell` | Zeichenfolge | Einer der folgenden Werte: `bash`, `powershell` oder `command` | Shellbefehl für Windows. |\n| `timeout` | Zahl | Nein | Alias für `timeoutSec`, in Sekunden. Wird nur verwendet, wenn `timeoutSec` nicht vorhanden ist; `timeoutSec` hat Vorrang, wenn beide vorhanden sind. |\n| `timeoutSec` | Zahl | Nein | Timeout in Sekunden. Standardwert: `30`. |\n| `type` | `\"command\"` | Nein | Hakentyp. Wird standardmäßig auf `\"command\"` festgelegt, wenn nichts angegeben wird. |\n\n#### Statusmeldungen\n\nCommand-Hooks können während der Ausführung Statuszeilen in der CLI-Zeitleiste ausgeben. Schreiben Sie ein `{\"type\": \"progress\", \"message\": \"...\"}` JSON-Objekt in stdout, bevor Sie die endgültige Ausgabe schreiben:\n\n```bash\necho '{\"type\": \"progress\", \"message\": \"Checking policy...\"}'\n# ... perform work ...\necho '{\"permissionDecision\": \"allow\"}'\n```\n\nLegen Sie `\"temporary\": true` fest, dass eine vorübergehende Statuszeile ausgegeben wird. Eine temporäre Zeile ersetzt die vorherige temporäre Zeile und wird gelöscht, wenn der Assistent antwortet, anstatt sich in der Zeitleiste anzusammeln:\n\n```bash\necho '{\"type\": \"progress\", \"message\": \"Routing...\", \"temporary\": true}'\necho '{\"type\": \"progress\", \"message\": \"Thinking...\", \"temporary\": true}'\n# ... perform work ...\necho '{\"permissionDecision\": \"allow\"}'\n```\n\nStatusmeldungen werden nur angezeigt und wirken sich nicht auf die Hookausgabe oder Entscheidungslogik aus.\n\n**Wie Stdout analysiert wird, wenn Statusmeldungen gemischt werden.** – Die CLI durchsucht die stdout-Standardausgabe Zeile für Zeile, während der Hook ausgeführt wird. Jede Zeile, die nach dem Trimmen ein einzelnes vollständiges JSON-Objekt mit `\"type\": \"progress\"` ist, wird als Fortschrittsereignis verarbeitet und **aus dem Ausgabestream des Hooks entfernt**. Alle anderen Zeilen – Leere Zeilen, Nur-Text- und JSON-Objekte, die keine Statusmeldungen sind – bleiben erhalten. Wenn der Hook beendet wird, werden die beibehaltenen Linien verkettet, gekürzt und mit einem einzelnen `JSON.parse`-Aufruf analysiert: Das Ergebnis ist die Ausgabe des Hooks (das „Hook-Ausgabe-JSON“, auf das an anderer Stelle in diesem Artikel verwiesen wird). Dies bedeutet Folgendes:\n\n* Das Ausstellen von Statuslinien neben einem endgültigen Entscheidungsobjekt (wie in den obigen Beispielen) ist sicher und das beabsichtigte Muster – die Fortschrittslinien erreichen nie den JSON-Parser.\n* Jede Fortschrittsmeldung muss in einer eigenen Zeile stehen und in dieser einzelnen Zeile gültiges JSON sein. Mehrzeilige bzw. formatierte Fortschrittsobjekte werden nicht als Fortschrittsanzeige erkannt und verbleiben im Ausgabedatenstrom, wo sie wahrscheinlich dazu führen, dass das abschließende `JSON.parse` fehlschlägt.\n* Das endgültige Entscheidungsobjekt kann sich dagegen über mehrere Zeilen erstrecken – nur die Fortschritts-*Erkennung* ist zeilenorientiert; was nach dem Entfernen der Fortschrittsinformationen übrig bleibt, wird als ein einziges JSON-Dokument analysiert, nicht als zeilengetrenntes JSON.\n* Wenn die verbleibende Ausgabe leer ist oder nicht als JSON geparst werden kann, wird der Hook so behandelt, als hätte er keine Ausgabe erzeugt, und es wird auf das Standardverhalten zurückgegriffen. Zwei oder mehr JSON-Objekte, die keine Fortschrittsobjekte sind, auf stdout (z. B. zwei `echo '{\"permissionDecision\": ...}'`-Aufrufe) ergeben dadurch ungültiges JSON und werden ignoriert – geben Sie genau ein abschließendes Entscheidungsobjekt aus.\n\n### HTTP-Hooks\n\nHTTP-Hooks senden die Eingabenutzlast als JSON `POST` an eine URL.\n\n> \\[!NOTE]\n>\n> * Standardmäßig sind nur `https://` URLs zulässig. Nicht-TLS-`http://`-Anforderungen werden abgelehnt, mit Ausnahme von `http://localhost`, `http://127.*` und `http://[::1]`, wenn `COPILOT_HOOK_ALLOW_LOCALHOST=1` gesetzt ist.\n> *\n\n**Cloud-Agent nur.** Ausgehendes Netzwerk aus der Sandbox ist durch die Cloud-Agent-Firewall eingeschränkt, muss daher `url` auf einen zugelassenen Host ausgerichtet sein.\n\n```json\n{\n \"version\": 1,\n \"hooks\": {\n \"postToolUse\": [\n {\n \"type\": \"http\",\n \"url\": \"https://hooks.example.com/copilot\",\n \"headers\": { \"X-Source\": \"copilot-cli\" },\n \"allowedEnvVars\": [\"GITHUB_TOKEN\"],\n \"timeoutSec\": 30\n }\n ]\n }\n}\n```\n\n| Feld | Typ | Erforderlich | Description |\n| ---------------- | ------------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `allowedEnvVars` | string\\[] | Nein | Namen von Umgebungsvariablen, die innerhalb von `headers` Werten erweitert werden können. Wenn festgelegt, muss `url``https://` verwenden. |\n| `headers` | Objekt | Nein | Anforderungsheader enthalten Folgendes: |\n| `timeout` | Zahl | Nein | Alias für `timeoutSec`, in Sekunden. Wird nur verwendet, wenn `timeoutSec` nicht vorhanden ist; `timeoutSec` hat Vorrang, wenn beide vorhanden sind. |\n| `timeoutSec` | Zahl | Nein | Timeout in Sekunden. Standardwert: `30`. |\n| `type` | `\"http\"` | Ja | Muss `\"http\"`lauten. |\n| `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. |\n\n### Prompt-Hooks\n\nPrompt-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.\n\n> \\[!NOTE]\n> **Copilot CLI Nur.** Prompt-Hooks werden nur bei **neuen interaktiven Sitzungen** ausgelöst. Sie werden beim Fortsetzen nicht ausgelöst, und sie werden nicht im nicht interaktiven Promptmodus (`-p`) ausgelöst.\n\n> \\[!NOTE]\n> **Cloud-Agent.** Cloud-Agent-Aufträge werden nicht interaktiv ausgeführt (ähnlich `-p`), sodass `prompt` Hook-Einträge möglicherweise nicht ausgelöst werden. Bestätigen Sie das Verhalten in Ihrer Umgebung, bevor Sie darauf vertrauen.\n\n```json\n{\n \"version\": 1,\n \"hooks\": {\n \"sessionStart\": [\n {\n \"type\": \"prompt\",\n \"prompt\": \"YOUR_PROMPT_TEXT_OR_SLASH_COMMAND\"\n }\n ]\n }\n}\n```\n\n| Feld | Typ | Erforderlich | Description |\n| -------- | ------------ | ------------ | -------------------------------------------------------------------------------------------- |\n| `type` | `\"prompt\"` | Ja | Muss `\"prompt\"`lauten. |\n| `prompt` | Zeichenfolge | Ja | Text zum Einreichen – kann eine Nachricht in natürlicher Sprache oder ein Slash-Befehl sein. |\n\n## Hook-Ereignisse\n\nIn 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.\n\n| Veranstaltung | Wird ausgelöst, wenn | Verarbeitete Ausgabe | Cloud-Agent |\n| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `agentStop` | Der Hauptagent beendet eine Runde. | Ja – kann die Fortsetzung blockieren und erzwingen. | Feuer. |\n| `decision: \"block\"` erzwingt eine weitere Wendung, die immer noch gegen das Timeout des Auftrags zählt. | | | |\n| `errorOccurred` | Während der Ausführung tritt ein Fehler auf. | Nein | Feuer. |\n| `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 ein `matcher` regex-Muster (den Wert des `matcher` Felds) für `notification_type`. | Optional — kann `additionalContext` in die Sitzung einfügen. | |\n| **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). | | | |\n| `permissionRequest` | Wird ausgelöst, bevor der Berechtigungsdienst ausgeführt wird (Regelmodul, Sitzungsgenehmigungen, automatische Genehmigung/Automatische Ablehnung und Benutzeraufforderung). Wenn die Ausgabe des zusammengeführten Hooks `behavior: \"allow\"` oder `\"deny\"` zurückgibt, setzt diese Entscheidung den normalen Berechtigungsablauf außer Kraft – außer bei einer Anfrage zur Umgehung der Sandbox (`requestSandboxBypass: true`), bei der ein `allow` den Ausbruch nicht vorab genehmigt und nur `deny` weitergegeben wird (siehe die Ausnahme zur Sandbox-Umgehung für die Entscheidungssteuerung [`permissionRequest`](#permissionrequest-decision-control)). Unterstützt ein `matcher` regex-Muster (den Wert des `matcher` Felds) für `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. |\n| `postToolUse` | Nachdem jedes Tool erfolgreich abgeschlossen hat. | Ja – kann das Toolergebnis ändern oder zusätzlichen Kontext für das Modell einfügen. | Feuer. |\n| `postToolUseFailure` | Nachdem ein Werkzeug mit einem Fehler abgeschlossen wurde. | Ja – kann Anleitungen zur Wiederherstellung über `additionalContext` (Exit-Code `2` für Befehlshaken) bereitstellen. | Feuer. |\n| `preCompact` | Die Kontextkomprimierung beginnt (manuell oder automatisch). Unterstützt ein `matcher` regex-Muster (den Wert des `matcher` Felds), um nach Trigger (`\"manual\"` oder `\"auto\"`) zu filtern. | Nein – nur Benachrichtigung. | Feuert nur mit `trigger: \"auto\"`. Es gibt keinen Benutzer, um eine manuelle Komprimierung anzufordern. |\n| `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. |\n| `sessionEnd` | Die Sitzung wird beendet. | Nein | Wird einmal pro Auftrag ausgelöst. |\n| `reason` ist in der Regel `\"complete\"`, `\"error\"`oder `\"timeout\"`; `\"abort\"` und `\"user_exit\"` wird nicht erwartet, weil kein Benutzer vorhanden ist. | | | |\n| `sessionStart` | Eine neue oder fortgesetzte Sitzung beginnt. | Optional — kann `additionalContext` in die Sitzung einfügen. | Löst einmal pro Auftrag als neue Sitzung (keine Wiederaufnahme) aus. Informationen zum Verhalten von `prompt` Einträgen unter dem Cloud-Agent finden Sie oben in der Anmerkung zu den Prompt-Hooks. |\n| `subagentStart` | Ein Unteragent wird erzeugt (bevor er ausgeführt wird). Unterstützt ein `matcher` regex-Muster (den Wert des `matcher` Felds), um nach Agentnamen zu filtern. | Optional – kann die Erstellung nicht verhindern, jedoch wird `additionalContext` der Prompt des Subagents vorangestellt. | Feuer. |\n| `subagentStop` | Ein Subagent schließt ab. | Ja – kann die Fortsetzung blockieren und erzwingen. | Feuer. |\n| `userPromptSubmitted` | Der Benutzer sendet eine Eingabeaufforderung. | Optional—`modifiedPrompt` wird nur von programmatischen SDK-Hooks unterstützt. | Wird höchstens einmal ausgelöst, um den dem Auftrag bereitgestellten Prompt anzuzeigen. Es gibt keine Nachverfolgung von Benutzereingaben. |\n| `userPromptTransformed` | Wird ausgelöst, nachdem die Laufzeit einen übermittelten Prompt in den für das Modell bestimmten Inhalt umgewandelt hat, unmittelbar bevor dieser Inhalt ausgegeben und im Sitzungsverlauf gespeichert wird. Wird für die primäre Nachricht und für jede vorherige Nachricht in einer Batchübermittlung ausgeführt. Nur Mutation – es kann den Inhalt umschreiben, den das Modell erhält, aber die Interaktion nicht blockieren oder verarbeiten. Systembenachrichtigungen lösen sie nie aus. | Ja – kann den modellorientierten Inhalt neu schreiben. | Feuer. |\n\n## Hook-Ereignis-Eingabe-Nutzdaten\n\nJedes 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:\n\n* **camelCase-Format** – Konfigurieren Sie den Ereignisnamen in camelCase (z. B `sessionStart`. ). Felder verwenden camelCase.\n* **VS Code kompatibles Format** – Konfigurieren Sie den Ereignisnamen in PascalCase (z. B `SessionStart`. ). Felder verwenden snake\\_case, um dem Erweiterungsformat VS CodeCopilot zu entsprechen.\n\n### `sessionStart` / `SessionStart`\n\n**camelCase-Eingabe:**\n\n```typescript\n{\n sessionId: string;\n timestamp: number; // Unix timestamp in milliseconds\n cwd: string;\n source: \"startup\" | \"resume\" | \"new\";\n initialPrompt?: string;\n}\n```\n\n\\*\\*\nVS Code kompatible Eingabe:\\*\\*\n\n```typescript\n{\n hook_event_name: \"SessionStart\";\n session_id: string;\n timestamp: string; // ISO 8601 timestamp\n cwd: string;\n source: \"startup\" | \"resume\" | \"new\";\n initial_prompt?: string;\n}\n```\n\n### `sessionEnd` / `SessionEnd`\n\n**camelCase-Eingabe:**\n\n```typescript\n{\n sessionId: string;\n timestamp: number;\n cwd: string;\n reason: \"complete\" | \"error\" | \"abort\" | \"timeout\" | \"user_exit\";\n}\n```\n\n\\*\\*\nVS Code kompatible Eingabe:\\*\\*\n\n```typescript\n{\n hook_event_name: \"SessionEnd\";\n session_id: string;\n timestamp: string; // ISO 8601 timestamp\n cwd: string;\n reason: \"complete\" | \"error\" | \"abort\" | \"timeout\" | \"user_exit\";\n}\n```\n\n### `userPromptSubmitted` / `UserPromptSubmit`\n\n**camelCase-Eingabe:**\n\n```typescript\n{\n sessionId: string;\n timestamp: number;\n cwd: string;\n prompt: string;\n}\n```\n\n\\*\\*\nVS Code kompatible Eingabe:\\*\\*\n\n```typescript\n{\n hook_event_name: \"UserPromptSubmit\";\n session_id: string;\n timestamp: string; // ISO 8601 timestamp\n cwd: string;\n prompt: string;\n}\n```\n\n**Ausgabe:**\n\n```typescript\n{\n modifiedPrompt?: string; // Replaces the prompt for the rest of the turn (SDK programmatic hooks only)\n}\n```\n\n`{}` oder einen leeren Wert zurückgeben, um den Prompt unverändert zu lassen.\n\n> \\[!NOTE]\n> \\*\n> `modifiedPrompt` wird nur von programmgesteuerten SDK-Hooks berücksichtigt. Befehls- und HTTP-Konfigurationsdatei-Hooks `userPromptSubmitted` haben ihre Ausgabe gelöscht, einschließlich `modifiedPrompt`. Die leichtgewichtigere Runtime für die Hooks-Verarbeitung, die auch von gehosteten oder Steuerungssitzungen Copilot cloud agent verwendet wird, ignoriert diese ebenfalls. Dies ist dieselbe Laufzeitteilung wie `preToolUse`.\n>\n> * Ein Wert, der keine Zeichenfolge ist, `modifiedPrompt`, `modifiedTransformedPrompt` oder ein behandelter `responseContent`-Wert wird ignoriert, anstatt die Sitzung zu korrumpieren – stattdessen wird eine Typwarnung protokolliert, die den Feldnamen nennt, und als `session.warning`-Ereignis ausgegeben. Eine Überschreibung mit einem leeren String wird abgelehnt, statt den für das Modell bestimmten Inhalt zu leeren. Ein `null``additionalContext` Wert wird als nicht vorhanden behandelt, anstatt als Literaltext `null`eingefügt zu werden. Die Hook-Ausgabe (Stdout für Befehlshaken, der Antworttext für HTTP-Hooks) ist an 10 MiB pro Aufruf gebunden – eine größere Antwort wird abgeschnitten, anstatt Speicher zu erschöpfen.\n\n### `userPromptTransformed`\n\nWird ausgelöst, nachdem die Laufzeit einen übermittelten Prompt in den für das Modell bestimmten Inhalt umgewandelt hat, unmittelbar bevor dieser Inhalt ausgegeben und im Sitzungsverlauf gespeichert wird. Wird für die primäre Nachricht und für jede vorherige Nachricht in einer Batchübermittlung ausgeführt. Nur Mutation – es kann den Inhalt, den das Modell empfängt, umschreiben, aber den Turn nicht blockieren oder verarbeiten. Systembenachrichtigungen lösen sie nie aus.\n\n**Eingabe:**\n\n```typescript\n{\n sessionId: string;\n timestamp: number; // epoch-ms integer\n cwd: string;\n prompt: string; // user prompt after userPromptSubmitted hooks have run\n transformedPrompt: string; // runtime-transformed content the model will receive\n}\n```\n\n**Ausgabe:**\n\n```typescript\n{\n modifiedTransformedPrompt?: string; // Replaces the model-facing content\n}\n```\n\nGeben Sie `{}` oder einen leeren Wert zurück, um den umgewandelten Inhalt unverändert zu lassen.\n`modifiedTransformedPrompt` Ersetzt nur den an das Modell gesendeten Inhalt und wird im Sitzungsverlauf gespeichert – die in der Zeitachse angezeigte Eingabeaufforderung ist nicht betroffen – und der Ersatz wird unverändert wiedergegeben, wenn die Sitzung fortgesetzt wird.\n\n### `preToolUse` / `PreToolUse`\n\n**camelCase-Eingabe:**\n\n```typescript\n{\n sessionId: string;\n timestamp: number;\n cwd: string;\n toolName: string;\n toolArgs: unknown;\n}\n```\n\n\\*\\*\nVS Code kompatible Eingabe:\\*\\*\n\nBei der Konfiguration mit dem Namen des PascalCase-Ereignisses `PreToolUse`verwendet die Nutzlast snake\\_case Feldnamen, um dem Erweiterungsformat VS CodeCopilot zu entsprechen:\n\n```typescript\n{\n hook_event_name: \"PreToolUse\";\n session_id: string;\n timestamp: string; // ISO 8601 timestamp\n cwd: string;\n tool_name: string;\n tool_input: unknown; // Tool arguments (parsed from JSON string when possible)\n}\n```\n\n**Claude-format matchers (PascalCase `PreToolUse`):** Hooks, die mit dem Namen des PascalCase-Ereignisses `PreToolUse`konfiguriert sind ( wie in Claude Code Plug-Ins und dem Open Plugins-Format verwendet ), wenden Claudes Matchersemantik anstelle der systemeigenen regex-Regel an:\n\n* `*`, `**` oder ein leerer `matcher`-Wert wird für jedes Tool ausgelöst.\n* Ein Literalname oder eine durch `|` getrennte Alternativenliste (z. B. `Bash` oder `Edit|Write`) greift, wenn ein beliebiges Token dem Namen des Laufzeit-Tools oder seinem Claude-Toolnamen aus der folgenden Tabelle entspricht.\n* Jeder andere Wert wird als Regex unter Berücksichtigung der Groß-/Kleinschreibung behandelt, die als `^(?:PATTERN)$` verankert ist und anhand des Claude-Toolnamens (oder des Laufzeitnamens bei Tools ohne Claude-Äquivalent) geprüft wird.\n\nPayloads für PascalCase `PreToolUse` geben `tool_name` als Claude-Tool-Namen an (zum Beispiel `Bash` statt `bash`).\n\n| Laufzeittool | Claude-Toolname |\n| ------------------------------------------------------ | ----------------- |\n| `bash`, `powershell` | `Bash` |\n| `view` | `Read` |\n| `create` | `Write` |\n| `edit`, `str_replace_editor``apply_patch` | `Edit` |\n| `grep`, `rg` | `Grep` |\n| `glob` | `Glob` |\n| `web_fetch` | `WebFetch` |\n| `web_search` | `WebSearch` |\n| `ask_user` | `AskUserQuestion` |\n| `update_todo` | `TodoWrite` |\n| `task` | |\n| `Agent` (das Literal `Task` wird ebenfalls akzeptiert) | |\n\nTools, die kein Äquivalent in Claude haben, behalten ihre Laufzeitnamen bei.\n\n> \\[!IMPORTANT]\n> **Fehlerverhalten von Befehlen vs. HTTP für `preToolUse`:** Command-Hooks `preToolUse` sind bei Fehlern **fail-closed** – ein Absturz oder ein Exit-Code ungleich null (einschließlich Exit `2`) führt zur Verweigerung des Tool-Aufrufs, auch wenn das stdout-JSON des Hooks `permissionDecision: \"allow\"` meldet. **Zeitüberschreitungen von Befehls-Hooks sind immer fail-open, auch für `preToolUse` und von Administratoren bereitgestellte Policy-Hooks** – ein Hook mit Zeitüberschreitung gibt eine Warnung aus und lässt den Tool-Aufruf den normalen Berechtigungsablauf durchlaufen, anstatt ihn zu verweigern. HTTP-`preToolUse`-Hooks sind **fail-open**– ein Netzwerkfehler, ein Timeout oder eine Nicht-2xx-Antwort fällt in den Standardberechtigungsfluss. Wählen Sie die Variante aus, die Ihren Sicherheitsanforderungen entspricht.\n\n### `postToolUse` / `PostToolUse`\n\n**camelCase-Eingabe:**\n\n```typescript\n{\n sessionId: string;\n timestamp: number;\n cwd: string;\n toolName: string;\n toolArgs: unknown;\n toolResult: {\n resultType: \"success\";\n textResultForLlm: string;\n }\n}\n```\n\n\\*\\*\nVS Code kompatible Eingabe:\\*\\*\n\n```typescript\n{\n hook_event_name: \"PostToolUse\";\n session_id: string;\n timestamp: string; // ISO 8601 timestamp\n cwd: string;\n tool_name: string;\n tool_input: unknown;\n tool_result: {\n result_type: \"success\";\n text_result_for_llm: string;\n }\n}\n```\n\n### `postToolUseFailure` / `PostToolUseFailure`\n\n**camelCase-Eingabe:**\n\n```typescript\n{\n sessionId: string;\n timestamp: number;\n cwd: string;\n toolName: string;\n toolArgs: unknown;\n error: string;\n}\n```\n\n\\*\\*\nVS Code kompatible Eingabe:\\*\\*\n\n```typescript\n{\n hook_event_name: \"PostToolUseFailure\";\n session_id: string;\n timestamp: string; // ISO 8601 timestamp\n cwd: string;\n tool_name: string;\n tool_input: unknown;\n error: string;\n}\n```\n\n### `agentStop` / `Stop`\n\n**camelCase-Eingabe:**\n\n```typescript\n{\n sessionId: string;\n timestamp: number;\n cwd: string;\n transcriptPath: string;\n stopReason: \"end_turn\";\n stop_hook_active: boolean; // true when this turn was already forced to continue by a prior \"block\" decision from this hook\n}\n```\n\n\\*\\*\nVS Code kompatible Eingabe:\\*\\*\n\n```typescript\n{\n hook_event_name: \"Stop\";\n session_id: string;\n timestamp: string; // ISO 8601 timestamp\n cwd: string;\n transcript_path: string;\n stop_reason: \"end_turn\";\n stop_hook_active: boolean;\n}\n```\n\n### `subagentStart`\n\n> \\[!NOTE]\n> Der integrierte `general-purpose` Agent sendet keine `subagentStart`- oder `subagentStop`-Ereignisse. Alle anderen integrierten YAML-basierten Agenten – einschließlich `explore`, `task`, `code-review`, `rubber-duck`, `research` und `security-review` – sowie benutzerdefinierte Agenten geben diese Ereignisse aus.\n\n**Eingabe:**\n\n```typescript\n{\n sessionId: string;\n timestamp: number;\n cwd: string;\n transcriptPath: string;\n agentName: string;\n agentDisplayName?: string;\n agentDescription?: string;\n}\n```\n\n### `subagentStop` / `SubagentStop`\n\nWird ausgelöst, wenn ein Subagent ordnungsgemäß abgeschlossen ist, bevor Ergebnisse an die übergeordnete Instanz zurückgegeben werden.\n`stopReason` ist derzeit immer `\"end_turn\"`. Dieser Hook wird vor der Spill-Verarbeitung großer Antworten ausgeführt, sodass `response` (oder `last_assistant_message` im mit VS Code kompatiblen Format) den vollständigen endgültigen Antworttext des Subagenten enthält.\n\n**camelCase-Eingabe:**\n\n```typescript\n{\n sessionId: string;\n timestamp: number;\n cwd: string;\n transcriptPath: string;\n agentId: string;\n agentType: string;\n agentName: string;\n agentDisplayName?: string;\n response: string; // Full final subagent response text\n stopReason: \"end_turn\";\n}\n```\n\n\\*\\*\nVS Code kompatible Eingabe:\\*\\*\n\n```typescript\n{\n hook_event_name: \"SubagentStop\";\n session_id: string;\n timestamp: string; // ISO 8601 timestamp\n cwd: string;\n transcript_path: string;\n agent_id: string;\n agent_type: string;\n agent_name: string;\n agent_display_name?: string;\n last_assistant_message: string; // The `response` text\n stop_reason: \"end_turn\";\n}\n```\n\n### `errorOccurred` / `ErrorOccurred`\n\n**camelCase-Eingabe:**\n\n```typescript\n{\n sessionId: string;\n timestamp: number;\n cwd: string;\n error: {\n message: string;\n name: string;\n stack?: string;\n };\n errorContext: \"model_call\" | \"tool_execution\" | \"system\" | \"user_input\";\n recoverable: boolean;\n}\n```\n\n\\*\\*\nVS Code kompatible Eingabe:\\*\\*\n\n```typescript\n{\n hook_event_name: \"ErrorOccurred\";\n session_id: string;\n timestamp: string; // ISO 8601 timestamp\n cwd: string;\n error: {\n message: string;\n name: string;\n stack?: string;\n };\n error_context: \"model_call\" | \"tool_execution\" | \"system\" | \"user_input\";\n recoverable: boolean;\n}\n```\n\n### `preCompact` / `PreCompact`\n\n**camelCase-Eingabe:**\n\n```typescript\n{\n sessionId: string;\n timestamp: number;\n cwd: string;\n transcriptPath: string;\n trigger: \"manual\" | \"auto\";\n customInstructions: string;\n}\n```\n\n\\*\\*\nVS Code kompatible Eingabe:\\*\\*\n\n```typescript\n{\n hook_event_name: \"PreCompact\";\n session_id: string;\n timestamp: string; // ISO 8601 timestamp\n cwd: string;\n transcript_path: string;\n trigger: \"manual\" | \"auto\";\n custom_instructions: string;\n}\n```\n\n## `preToolUse` Entscheidungssteuerung\n\nDer `preToolUse` Hook kann die Toolausführung steuern, indem ein JSON-Objekt in stdout geschrieben wird.\n\n| Feld | Werte | Description |\n| -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |\n| `permissionDecision` | | |\n| `\"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. | |\n| `permissionDecisionReason` | Zeichenfolge | Grund, der dem Agenten angezeigt wird. Erforderlich, wenn die Entscheidung lautet `\"deny\"`. |\n| `modifiedArgs` | Objekt | Ersetzen Sie Toolargumente, die anstelle der Originale verwendet werden sollen. |\n\nWenn Copilot CLI die Aufforderung zur Hook-Berechtigung anzeigen kann, kann der Benutzer zusammen mit der Verweigerung optionales Feedback eingeben. Dieses Feedback wird an die Nachricht angefügt, die der Agent erhält: `Denied by user via preToolUse hook prompt: . The user provided the following feedback: `.\n\n## `agentStop`/ `subagentStop` Entscheidungssteuerung\n\n| Feld | Werte | Description |\n| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------ | -------------------------------------------------------------------- |\n| `decision` | | |\n| `\"block\"`, `\"allow\"` | | |\n| `\"block\"` Setzt einen anderen Agent-Turn mittels `reason` als Prompt durch. | | |\n| `reason` | Zeichenfolge | Aufforderung für den nächsten Schritt, wenn `decision``\"block\"` ist. |\n| `modifiedResponse` | Zeichenfolge | |\n| \\*\\* | | |\n| `subagentStop` Nur.\\*\\* Ersetzt die Antwort, die an die übergeordnete Instanz zurückgegeben wird, wenn der Subagent seine Ausführung abschließen darf – nützlich zum Schwärzen oder Neuformatieren der Subagent-Ausgabe. Gilt nicht für `agentStop`. | | |\n\n`decision` und `reason` verhalten sich sowohl für `agentStop` als auch für `subagentStop` gleich.\n`modifiedResponse` gilt nur für `subagentStop`:\n\n* Eine `block` gültige Entscheidung hat Vorrang vor `modifiedResponse`: Falls ein Hook beides zurückgibt, setzt der Subagent seine Ausführung fort und die Umschreibung wird verworfen.\n* Neuschreibungen verfassen nicht über mehrere übereinstimmende Hooks hinweg. Jeder Hook erhält dasselbe ursprüngliche `response`, und der Hook, der zuletzt `modifiedResponse` zurückgibt, gewinnt – das Verketten eines Redaktors mit einem Formatierer übergibt den redigierten Text nicht an den Formatierer.\n* Die Ausgabefeldnamen (`decision`, `reason`, `modifiedResponse`) sind für die CamelCase- und VS Code kompatiblen Konfigurationen identisch.\n\n> \\[!NOTE]\n> **Runaway Guard.** Nach 8 aufeinanderfolgenden `block` Fortsetzungen setzt die CLI den Hook außer Kraft und beendet den Durchlauf trotzdem, um eine Endlosschleife zu verhindern. Verwenden Sie das Eingabefeld `stop_hook_active` auf `agentStop`, um zu erkennen, dass dieser Vorgang bereits zum Fortfahren gezwungen wurde, und sich selbst zu begrenzen, bevor die Obergrenze erreicht wird.\n\n## `postToolUse` Output\n\nDer `postToolUse` Hook kann das Toolergebnis ändern oder zusätzlichen Kontext für das Modell einfügen, indem ein JSON-Objekt in Stdout geschrieben wird.\n\n```typescript\n{\n modifiedResult?: {\n resultType: \"success\";\n textResultForLlm: string;\n };\n additionalContext?: string;\n}\n```\n\n| Feld | Typ | Description |\n| ------------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `modifiedResult` | Objekt | Ergebnis des Ersetzungstools. Muss `resultType: \"success\"` haben. Wenn mit `resultType: \"failure\"` zurückgegeben wird, wird der Fehler an nachgelagerte Fehlerpfade weitergeleitet und `postToolUseFailure` wird als Nächstes ausgelöst. |\n| `additionalContext` | Zeichenfolge | Zusätzliche Hinweise werden an `textResultForLlm` angehängt, damit das Modell sie nach der Tool-Ausgabe im selben Durchlauf sieht. Wenn mehrere Hooks `additionalContext` zurückgeben, werden die Ergebnisse mit einer doppelten Neuzeile verknüpft und mit 10 KB begrenzt. |\n\nGeben Sie `{}` oder eine leere Ausgabe zurück, um das ursprünglich erfolgreiche Ergebnis beizubehalten.\n\n> \\[!NOTE]\n> `modifiedResult` wird sowohl von programmgesteuerten SDK-Hooks als auch von Befehls-/HTTP-Konfigurationsdatei-Hooks `postToolUse` berücksichtigt.\n\n**Matcher:** Ein optionaler Regex, getestet gegen `toolName`. Das regex-Muster ist der Wert des `matcher` Felds, kompiliert als `^(?:PATTERN)$`, und muss mit dem gesamten Toolnamen übereinstimmen. Wenn das Muster kein gültiger regulärer Ausdruck ist, wird der Hook übersprungen. Lassen Sie `matcher` weg, um Ergebnisse aller Tools zu erhalten.\n\n```json\n{\n \"type\": \"command\",\n \"matcher\": \"bash|edit\",\n \"bash\": \"./scripts/log-tool.sh\"\n}\n```\n\n## `permissionRequest` Entscheidungssteuerung\n\n> \\[!NOTE]\n> **Copilot CLI Nur.** Der `permissionRequest` Hook gilt nicht unter Copilot cloud agent—Tool-Aufrufe sind bereits genehmigt (siehe die **Zeile \"Interaktivität\"** in der Tabelle der Cloud-Agent-Ausführungsumgebung). `preToolUse` wird verwendet, um Berechtigungsentscheidungen im Cloud-Agent zu treffen.\n\nDer `permissionRequest`-Hook wird ausgelöst, bevor der Berechtigungsdienst ausgeführt wird – vor Regelüberprüfungen, Sitzungsgenehmigungen, automatisches Zulassen/automatisches Verweigern und bevor Benutzer-Prompts 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.\n\nFü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.\n\n**Ausnahme für die Umgehung der Sandbox:** Bei jeder Anfrage, die darauf abzielt, die Sandbox zu verlassen (`requestSandboxBypass: true` in `toolInput`), darf ein Hook `allow` die Anfrage weder vorab genehmigen noch die Benutzerabfrage umgehen – das Verlassen der Sandbox ist eine Berechtigungseskalation, die der Benutzer immer interaktiv bestätigen muss. Dies umfasst einen Shell-Befehl, der verlangt, außerhalb der Sandbox ausgeführt zu werden, sowie ein `web_fetch`, dessen URL von der Netzwerkrichtlinie der Sandbox blockiert wird. Nur `deny` wird noch weitergereicht (sodass ein Policy-Hook das Escaping verhindern kann); ein `allow` (oder keine Entscheidung) führt zur normalen Eingabeaufforderung.\n\n**Matcher:** Ein optionaler Regex, getestet gegen `toolName`. Das regex-Muster ist der Wert des `matcher` Felds, verankert als `^(?:PATTERN)$`, und muss mit dem vollständigen Toolnamen übereinstimmen. Wenn diese Option gesetzt ist, wird der Haken nur bei übereinstimmenden Werkzeugnamen ausgelöst.\n\n> \\[!NOTE]\n> **Claude-format matchers (PascalCase `PermissionRequest`):** Hooks, die mit dem PascalCase-Ereignisnamen `PermissionRequest` konfiguriert sind, verwenden dieselbe Claude-Matchersemantik wie `PreToolUse`. Siehe [Claude-Format-Abgleicher (PascalCase PreToolUse)](#claude-format-matchers-pascalcase-pretooluse) für die Zuordnungsregeln und die Toolnamentabelle.\n\nAusgabe von JSON an stdout, um die Berechtigungsentscheidung zu steuern.\n\n| Feld | Werte | Description |\n| ------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------ |\n| `behavior` | | |\n| `\"allow\"`, `\"deny\"` | Gibt an, ob der Toolaufruf genehmigt oder verweigert werden soll. | |\n| `message` | Zeichenfolge | Die Begründung wird bei der Ablehnung an den LLM zurückgegeben. |\n| `interrupt` | Boolescher Wert | Wenn `true` mit `\"deny\"` kombiniert wird, wird der Agent vollständig gestoppt. |\n\nGeben Sie eine leere Ausgabe oder `{}` zurück, um zum normalen Berechtigungsfluss überzugehen. Bei Befehls-Hooks wird der Beendigungscode `2` als Verweigerung behandelt; stdout JSON (falls vorhanden) wird mit `{\"behavior\":\"deny\"}` zusammengeführt, und stderr wird ignoriert.\n\n## `notification` Haken\n\n> \\[!NOTE]\n> **Copilot CLI Nur.** Der `notification` Hook wird nicht unter Copilot cloud agent ausgelöst.\n\nDer `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.\n\n**Eingabe:**\n\n```typescript\n{\n sessionId: string;\n timestamp: number;\n cwd: string;\n hook_event_name: \"Notification\";\n message: string; // Human-readable notification text\n title?: string; // Short title (e.g., \"Permission needed\", \"Shell completed\")\n notification_type: string; // One of the types listed below\n}\n```\n\n**Benachrichtigungstypen:**\n\n| Typ | Bei Aktivierung |\n| -------------------------- | -------------------------------------------------------------------------------------------------------- |\n| `shell_completed` | Ein Shell-Befehl im Hintergrund (asynchron) wird beendet |\n| `shell_detached_completed` | Eine getrennte Shell-Sitzung ist beendet. |\n| `agent_completed` | Ein im Hintergrund ausgeführter Sub-Agent wird beendet (abgeschlossen oder fehlgeschlagen) |\n| `agent_idle` | Ein Hintergrund-Agent beendet einen Umlauf und wechselt in den Leerlaufmodus (wartend auf `write_agent`) |\n| `permission_prompt` | Der Agent fordert die Berechtigung zum Ausführen eines Tools an. |\n| `elicitation_dialog` | Der Agent fordert zusätzliche Informationen vom Benutzer an. |\n\n**Ausgabe:**\n\n```typescript\n{\n additionalContext?: string; // Injected into the session as a user message\n}\n```\n\nWenn 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.\n\n**Matcher:** Optionales Regex für `notification_type`. Das regex-Muster ist der Wert des `matcher` Felds, das als `^(?:PATTERN)$`verankert ist. Um alle Benachrichtigungstypen zu erhalten, lassen Sie `matcher` weg.\n\n## Abgleichsfilterung\n\nMehrere Ereignisse akzeptieren einen optionalen `matcher` Regex für jeden Hookeintrag, der festlegt, bei welchen Aufrufe der Hook ausgelöst wird. Sie wird als `^(?:PATTERN)$` kompiliert und muss mit dem vollständigen Wert übereinstimmen. Ungültige Regexes führen dazu, dass der Hook-Eintrag übersprungen wird.\n\n\\| Veranstaltung |\n`matcher` wird abgeglichen mit |\n\\|-------|------------------------------|\n\\| `notification` | `notification_type` |\n\\| `permissionRequest` | `toolName` |\n\\| `postToolUse` | `toolName` |\n\\| `preCompact` |\n`trigger` (`\"manual\"` oder `\"auto\"`) |\n\\| `preToolUse` | `toolName` |\n\\| `subagentStart` | `agentName` |\n\n## Toolnamen für Hookabgleich\n\n| Name des Tools | Description |\n| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| `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. |\n| `bash` | Ausführen von Shellbefehlen (Unix). |\n| `create` | Erstellen Sie neue Dateien. |\n| `edit` | Dateiinhalte ändern. |\n| `glob` | Suchen Sie Dateien nach Mustern. |\n| `grep` | Dateiinhalte durchsuchen. |\n| `powershell` | Ausführen von Shellbefehlen (Windows). Wird nicht unter Cloud-Agent (Linux-Sandkasten) angezeigt. |\n| `task` | Führen Sie Subagent-Aufgaben aus. |\n| `view` | Dateiinhalte lesen. |\n| `web_fetch` | Webseiten abrufen. |\n\nWenn 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. Für die meisten Ereignisse werden Hook-Fehler (Exitcodes ungleich null, mit Ausnahme von `2` oder Timeouts) protokolliert und ignoriert.\n**Ausnahme: `preToolUse` Command-Hooks sind bei Beendigung `2` und bei anderen Fehlern als Timeouts fail-closed** – ein Exit `2`, ein Absturz oder jeder andere Exitcode ungleich null (außer einem Timeout) verweigert den Toolaufruf, auch wenn das stdout-JSON des Hooks `permissionDecision: \"allow\"` meldet.\n**Timeouts sind immer Fail-open, einschließlich für `preToolUse` und von Administratoren bereitgestellte Policy-Hooks**: Es wird eine Warnung angezeigt, und der Toolaufruf durchläuft den normalen Berechtigungsablauf, statt abgelehnt zu werden.\n\n## Exit-Codes für Kommando-Hooks\n\n| Exitcode | Dies bedeutet |\n| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |\n| `0` | Erfolg. |\n| `stdout` wird als Hook-Ausgabe-JSON analysiert, falls vorhanden. | |\n| `2` | Wird standardmäßig als Warnung behandelt. |\n| `stderr` wird dem Benutzer angezeigt, aber die Ausführung wird fortgesetzt. Für `permissionRequest` und `preToolUse`, Exit `2` wird als Ablehnung behandelt: alle `stdout` JSON-Dateien werden mit der Ablehnungsentscheidung zusammengeführt, und der Toolaufruf wird verweigert, auch wenn dieser JSON-Bericht meldet `permissionDecision: \"allow\"`. Bei `postToolUseFailure` wird der Exit `2` als `additionalContext` behandelt, und `stdout` wird an die dem Agent angezeigte Fehlermeldung angehängt. | |\n| Andere ungleich null | Protokolliert als Hook-Fehler. Die Ausführung wird fortgesetzt (fail-open). |\n| **Ausnahme: `preToolUse` ist als „fail-closed“ konfiguriert** – ein Exit-Code ungleich null (außer Exit 2) lehnt den Tool-Aufruf mit `\"Denied by preToolUse hook (hook errored)\"` ab. | |\n| Timeout | Wurde nach `timeoutSec` beendet. Fehler protokolliert, Ausführung wird fortgesetzt. |\n| **Timeouts sind für jedes Ereignis, einschließlich `preToolUse` und vom Administrator implementierter Richtlinien-Hooks, auf „Fail-open“ gesetzt**—es wird eine Warnung ausgegeben, und die Verarbeitung wird fortgesetzt, als wäre der Hook nicht ausgeführt worden. Für `preToolUse` durchläuft der Tool-Aufruf den normalen Berechtigungsablauf, anstatt abgelehnt zu werden. Ein abgestürzter oder explizit verweigerter Hook schlägt immer noch fehl; Nur Timeouts sind ausgenommen. | |\n\nBei den meisten Ereignissen werden Exit-Codes ungleich null und Zeitüberschreitungen protokolliert und übersprungen – die Ausführung des Agents wird fortgesetzt. Bei `preToolUse` Command-Hooks werden Exit-Code 2, Abstürze und andere von null verschiedene Beendigungen stets als „fail-closed“ behandelt und der Toolaufruf wird verweigert – Exit-Code 2 verweigert immer, selbst wenn das `stdout`-JSON des Hooks `permissionDecision: \"allow\"` meldet – aber **Zeitüberschreitungen werden immer als „fail-open“ behandelt** – ein langsamer oder nicht erreichbarer Hook darf Toolaufrufe oder die Arbeit nicht stillschweigend blockieren, auch wenn der Hook von einem Administrator als Richtlinie eingerichtet wurde.\n\n## Alle Hooks deaktivieren\n\nVerwenden Sie `disableAllHooks`, wenn Sie die Hook-Konfiguration auf dem Datenträger beibehalten möchten, sie aber nicht mehr ausführen möchten, z. B.:\n\n* Wenn Sie ein Problem debuggen und bestätigen möchten, dass ein Hook die Ursache ist, ohne Ihre Konfiguration zu löschen.\n* Anhalten der Automatisierung während einer sensiblen Aufgabe (Codeüberprüfung, eine Veröffentlichungs-Verzweigung, Arbeiten mit Geheimnissen), ohne das Setup zu verlieren. (nur **Copilot CLI.**)\n* Senden einer Hooks-Datei in der Quellcodeverwaltung, die Mitwirkende lokal deaktivieren können, indem Sie die Option in ihrem Repository `settings.json` festlegen. (nur **Copilot CLI.**)\n* Vorübergehendes Stummschalten langsam arbeitender oder lauter Hooks während einer interaktiven Sitzung. (nur **Copilot CLI.**)\n\nLegen Sie `disableAllHooks` auf `true` auf oberster Ebene fest, um jeden Hook in der Datei zu überspringen, ohne ihn zu löschen.\n\n```json\n{\n \"version\": 1,\n \"disableAllHooks\": false,\n \"hooks\": {\n \"preToolUse\": [ /* hook entries */ ]\n }\n}\n```\n\nDas Verhalten hängt davon ab, wo Sie das Kennzeichen setzen.\n\n* **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.\n* **Auf der obersten Ebene des Repositorys `settings.json`** – nur **Copilot CLI.** Jeder Hook aus jeder Quelle (Repositorydateien, Benutzerdateien, Plug-Ins und Inline-Hook-Blöcke) wird für Sitzungen in diesem Repository übersprungen. Richtlinienhooks sind nicht betroffen und werden weiterhin ausgeführt. Der Cloud-Agent lädt nicht `settings.json`.\n\n## Weiterführende Lektüre\n\n* [Verwenden von Hooks mit GitHub Copilot CLI](/de/enterprise-cloud@latest/copilot/how-tos/copilot-cli/customize-copilot/use-hooks)\n* [GitHub Copilot-Hooks-Referenz](/de/enterprise-cloud@latest/copilot/reference/hooks-reference)\n* [GitHub Copilot CLI-Befehlsreferenz](/de/enterprise-cloud@latest/copilot/reference/copilot-cli-reference/cli-command-reference)\n* [Konzepte für GitHub Copilot Cloud-Agent](/de/enterprise-cloud@latest/copilot/concepts/agents/cloud-agent)"}