Hooks

Mit Hooks kannst du benutzerdefinierte Logik ausführen, wenn Ereignisse im Lebenszyklus des Agenten auftreten. Du kannst Hooks verwenden, um Richtlinien durchzusetzen, Kontext hinzuzufügen, Aktionen zu protokollieren, Berechtigungen zu ändern oder externe Systeme zu integrieren. Hooks werden im JSON-Format konfiguriert. Lege sie im .devin/-Verzeichnis deines Projekts ab (oder in einer Konfiguration auf Nutzerebene), und Devin CLI führt sie bei passenden Lifecycle-Ereignissen aus. Vorhandene Hooks in .claude/-Verzeichnissen werden ebenfalls automatisch erkannt — siehe Wo Hooks zu finden sind.

Was können Hooks tun?

Richtlinien durchsetzen

Gefährliche Befehle blockieren, für bestimmte Aktionen eine Bestätigung verlangen oder den Zugriff auf Dateien einschränken.

Kontext hinzufügen

Zusätzliche Anweisungen oder Informationen einfügen, wenn bestimmte Tools aufgerufen werden.

Folgeaktionen ausführen

Skripte ausführen, Benachrichtigungen senden oder Ereignisse protokollieren, wenn etwas geschieht.

Berechtigungen ändern

Berechtigungen je nach Situation dynamisch gewähren oder einschränken.

Kurzes Beispiel

Legen Sie .devin/hooks.v1.json in Ihrem Projekt an:

{
  "PreToolUse": [
    {
      "matcher": "exec",
      "hooks": [
        {
          "type": "command",
          "command": "./scripts/check-command.sh"
        }
      ]
    }
  ]
}

Dabei wird ./scripts/check-command.sh vor jeder Ausführung eines Shell-Befehls ausgeführt. Das Skript erhält Ereignisdaten über stdin und kann die Aktion blockieren, indem es sich mit Code 2 beendet (oder indem es ein JSON-Objekt mit "decision": "block" ausgibt); jeder andere Exit-Code ungleich null wird als Fehler protokolliert und blockiert nicht – siehe Exit-Codes.

Hook-Ereignisse

Hooks können auf diese Lifecycle-Ereignisse reagieren:

Ereignis	Wann es ausgelöst wird
`PreToolUse`	Bevor ein Tool ausgeführt wird
`PostToolUse`	Nachdem ein Tool beendet wurde
`PermissionRequest`	Wenn eine Berechtigungsentscheidung erforderlich ist
`UserPromptSubmit`	Wenn der Nutzer eine Nachricht absendet
`Stop`	Wenn der Agent stoppen möchte
`PostCompaction`	Nachdem die Kontextkomprimierung erfolgreich abgeschlossen wurde
`SessionStart`	Wenn eine Sitzung beginnt
`SessionEnd`	Wenn eine Sitzung endet

Unter Lifecycle Hooks finden Sie Details zu jedem Ereignis und den jeweils verfügbaren Daten.

Hook-Format

Jeder Hook hat einen Typ (command oder prompt), einen optionalen Matcher (Regex auf den tool_name des Hook-Ereignisses) und eine Konfiguration:

{
  "PreToolUse": [
    {
      "matcher": "exec",
      "hooks": [
        {
          "type": "command",
          "command": "./scripts/validate.sh",
          "timeout": 10
        }
      ]
    }
  ]
}

Feld	Beschreibung
`matcher`	Regex, die mit dem `tool_name` des Hook-Ereignisses abgeglichen wird. Eine leere Zeichenfolge oder ein weggelassener Matcher passt auf alle Tool-Namen.
`type`	`"command"` zum Ausführen eines Shell-Befehls oder `"prompt"` zum Auswerten eines LLM-Prompts.
`command`	Auszuführender Shell-Befehl (für den Typ `command`).
`prompt`	Auszuwertender LLM-Prompt (für den Typ `prompt`).
`timeout`	Timeout in Sekunden (optional).

Command-Hooks

Command-Hooks führen einen Shell-Befehl aus. Ereignisdaten werden als JSON über stdin übergeben, und der Befehl kann über stdout JSON zurückgeben, um das Ergebnis zu steuern (siehe Ausgabeformat unten). Eingabe (stdin):

{
  "hook_event_name": "PreToolUse",
  "tool_name": "exec",
  "tool_input": {
    "command": "rm -rf /"
  },
  "session_id": "3f8d1c2a-...",
  "prompt_id": "b71e9d40-..."
}

Jede Ereignis-Payload enthält zusätzlich zu den Ereignisfeldern auch zwei Korrelations-IDs:

Feld	Beschreibung
`session_id`	Stabile ID für die Agent-Sitzung. Verwenden Sie sie, um Hook-Aufrufe über eine gesamte Sitzung hinweg zu korrelieren.
`prompt_id`	ID pro Turn, die bei jeder Nutzer-Prompt wechselt. Alle Hooks, die während desselben Turns ausgelöst werden, teilen sich eine `prompt_id`. Fehlt bei Ereignissen, die vor der ersten Nutzer-Prompt ausgelöst werden (z. B. `SessionStart`).

Die Umgebungsvariable DEVIN_PROJECT_DIR wird automatisch auf das Projektstammverzeichnis gesetzt. Unter Using the Matcher finden Sie die integrierten Tool-Namen und das MCP-Tool-Namensformat, nach denen Sie abgleichen können.

Ausgabeformat

Ein Command-Hook kann ein JSON-Objekt an stdout ausgeben, um das Ergebnis zu steuern. Um eine Aktion zu genehmigen oder zu blockieren, gib ein decision-Feld auf oberster Ebene zurück (mit einem optionalen reason):

{
  "decision": "block",
  "reason": "Destructive command blocked by policy"
}

Um Text in den Kontext des Agenten einzuschleusen, geben Sie additionalContext in einem hookSpecificOutput-Objekt zurück, das mit dem Ereignisnamen versehen ist:

{
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "Remember: deploys require an approved change ticket."
  }
}

Um die Eingabe eines Tools vor der Ausführung transparent umzuschreiben, geben Sie updatedInput innerhalb eines PreToolUse-hookSpecificOutput zurück. Felder in updatedInput werden in die Argumente des Tools zusammengeführt, sodass Sie eine Teilmenge aktualisieren können (z. B. nur command):

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "updatedInput": {
      "command": "rtk git status"
    }
  }
}

Ausgabefeld	Beschreibung
`decision`	`"approve"`, um die Aktion zuzulassen, oder `"block"`, um sie zu blockieren
`reason`	Erklärung, die dem Agenten angezeigt wird
`hookSpecificOutput.hookEventName`	Ereignis, für das die Ausgabe gilt (z. B. `UserPromptSubmit`, `SessionStart`, `PreToolUse`, `PostToolUse`)
`hookSpecificOutput.additionalContext`	Text, der in den Kontext des Agenten eingefügt wird (für `UserPromptSubmit`, `SessionStart`, `PostToolUse`)
`hookSpecificOutput.updatedInput`	Objekt, das vor der Ausführung mit den Argumenten des Tools zusammengeführt wird (für `PreToolUse`)

Exit-Codes

Code	Bedeutung
0	Erfolg — Hook wird normal fortgesetzt
2	Blockiert — Aktion wird verweigert
Andere	Fehler — wird protokolliert, blockiert aber nicht

Wo Hooks zu finden sind

Devin CLI liest Hooks aus den folgenden Speicherorten. Alle verwenden dasselbe JSON-Format. Hook-Dateien auf Projektebene werden im Arbeitsverzeichnis und in dessen übergeordneten Verzeichnissen bis zum Root-Verzeichnis des Repositorys erkannt – entsprechend der Art und Weise, wie Skills und Rules geladen werden.

Auf Projektebene

Speicherort	Beschreibung
`.devin/hooks.v1.json`	Eigenständige Hooks-Datei (empfohlen)
`.devin/config.json`	`"hooks"`-Schlüssel in der Konfigurationsdatei
`.devin/config.local.json`	`"hooks"`-Schlüssel (lokale Überschreibung, gitignored)
`.claude/settings.json`	`"hooks"`-Schlüssel (Claude-Code-Format)
`.claude/settings.local.json`	`"hooks"`-Schlüssel (Claude-Code-Format)

Nutzerebene (global)

Pfad	Beschreibung
`~/.config/devin/config.json` (`%APPDATA%\devin\config.json` unter Windows)	`"hooks"`-Schlüssel in der Nutzerkonfiguration
`~/.claude.json`	`"hooks"`-Schlüssel (Claude Code-Format)
`~/.claude/settings.json`	`"hooks"`-Schlüssel (Claude Code-Format)
`~/.claude/settings.local.json`	`"hooks"`-Schlüssel (Claude Code-Format)

In .devin/hooks.v1.json ist das Hooks-Objekt die gesamte Datei (kein umschließender Schlüssel erforderlich). An allen anderen Speicherorten sind Hooks in einer Settings-Datei unter dem "hooks"-Schlüssel verschachtelt.

Hooks aus .claude/-Pfaden werden geladen, wenn read_config_from.claude aktiviert ist (Standardeinstellung). Bei Bedarf kannst du dies in deiner Nutzerkonfiguration deaktivieren.

Hooks überprüfen

Verwenden Sie den Slash-Befehl /hooks, um alle aktuell geladenen Hooks und ihre Quelldateien anzuzeigen:

/hooks

Erste Schritte

Editor-Integrationen

Erweiterbarkeit

Enterprise

Referenz

Changelog

Was können Hooks tun?

Richtlinien durchsetzen

Kontext hinzufügen

Folgeaktionen ausführen

Berechtigungen ändern

Kurzes Beispiel

Hook-Ereignisse

Hook-Format

Command-Hooks

Ausgabeformat

Exit-Codes

Wo Hooks zu finden sind

Auf Projektebene

Nutzerebene (global)

Hooks überprüfen

Nächste Schritte

Lifecycle Hooks

Konfiguration

​Was können Hooks tun?

Richtlinien durchsetzen

Kontext hinzufügen

Folgeaktionen ausführen

Berechtigungen ändern

​Kurzes Beispiel

​Hook-Ereignisse

​Hook-Format

​Command-Hooks

​Ausgabeformat

​Exit-Codes

​Wo Hooks zu finden sind

​Auf Projektebene

​Nutzerebene (global)

​Hooks überprüfen

​Nächste Schritte

Lifecycle Hooks

Konfiguration

Was können Hooks tun?

Kurzes Beispiel

Hook-Ereignisse

Hook-Format

Command-Hooks

Ausgabeformat

Exit-Codes

Wo Hooks zu finden sind

Auf Projektebene

Nutzerebene (global)

Hooks überprüfen

Nächste Schritte