Hooks im Lebenszyklus

Jedes Hook-Ereignis wird an einem bestimmten Punkt im Lebenszyklus des Agenten ausgelöst. Verwende das Feld matcher (einen Regex-Ausdruck, der mit dem tool_name des Hook-Ereignisses abgeglichen wird), um zu filtern, welche Tool-Aufrufe den Hook auslösen.

PreToolUse

Wird vor der Ausführung eines Tools ausgelöst. Verwenden Sie dies, um Tool-Aufrufe zu blockieren, zu ändern oder mit zusätzlichem Kontext zu versehen. Stdin-Daten:

Feld	Beschreibung	Beispiel
`tool_name`	Name des aufgerufenen Tools	`exec`, `edit`, `mcp__github__create_issue`
`tool_input`	An das Tool übergebene Argumente	`{ "command": "rm -rf /", "shell_id": "main" }`

Beispiel — Destruktive Befehle blockieren:

{
  "PreToolUse": [
    {
      "matcher": "exec",
      "hooks": [
        {
          "type": "command",
          "command": "python3 -c \"import sys, json; data = json.load(sys.stdin); cmd = data.get('tool_input', {}).get('command', ''); sys.exit(2 if 'rm -rf' in cmd else 0)\""
        }
      ]
    }
  ]
}

Beispiel — Bestätigung für Schreibvorgänge außerhalb von src/ anfordern: Verwende ein Skript, das die Tool-Eingabe prüft und eine Entscheidung zurückgibt:

{
  "PreToolUse": [
    {
      "matcher": "edit",
      "hooks": [
        {
          "type": "command",
          "command": "./scripts/check-edit-path.sh",
          "timeout": 5
        }
      ]
    }
  ]
}

Beispiel — Befehle vor der Ausführung umschreiben: Ein Hook kann die Tool-Eingabe transparent umschreiben, indem hookSpecificOutput.updatedInput auf stdout ausgegeben wird (siehe Output format). Zum Beispiel ein Hook-Skript, das Shell-Befehle über einen Wrapper leitet:

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

Die umgeschriebenen Argumente werden vor der Ausführung in den Tool-Aufruf eingefügt — der Agent führt den aktualisierten Befehl statt des ursprünglichen aus.

PostToolUse

Wird ausgelöst, nachdem ein Tool seine Ausführung beendet hat. Verwende dies zur Protokollierung, Validierung oder zum Auslösen von Folgeaktionen. Stdin-Daten:

Feld	Beschreibung
`tool_name`	Name des ausgeführten Tools
`tool_input`	Übergebene Argumente
`tool_response`	Objekt mit `success` (boolean), `output` (string) und `error` (string oder null)

Beispiel — Alle Shell-Befehle protokollieren:

{
  "PostToolUse": [
    {
      "matcher": "exec",
      "hooks": [
        {
          "type": "command",
          "command": "sh -c 'cat >> ~/.devin-command-log'"
        }
      ]
    }
  ]
}

PermissionRequest

Wird ausgelöst, wenn der Agent eine Entscheidung über eine Berechtigung benötigt. Damit können Sie benutzerdefinierte Genehmigungslogik implementieren. Stdin-Daten:

Feld	Beschreibung
`tool_name`	Tool, das eine Berechtigung anfordert
`tool_input`	Argumente für den Tool-Aufruf

Beispiel — Git-Befehle automatisch genehmigen:

{
  "PermissionRequest": [
    {
      "matcher": "exec",
      "hooks": [
        {
          "type": "command",
          "command": "python3 -c \"import sys, json; data = json.load(sys.stdin); cmd = data.get('tool_input', {}).get('command', ''); print(json.dumps({'decision': 'approve'})) if cmd.startswith('git ') else sys.exit(0)\""
        }
      ]
    }
  ]
}

UserPromptSubmit

Wird ausgelöst, wenn der Nutzer eine Nachricht absendet. Verwenden Sie dies, um Kontext hinzuzufügen oder Workflows auszulösen. Stdin-Daten:

Field	Description
`prompt`	Der Text der Nachricht des Nutzers

Beispiel — Kontext bei jedem Prompt hinzufügen:

{
  "UserPromptSubmit": [
    {
      "matcher": "",
      "hooks": [
        {
          "type": "command",
          "command": "echo '{\"hookSpecificOutput\": {\"hookEventName\": \"UserPromptSubmit\", \"additionalContext\": \"Deploys require an approved change ticket.\"}}'"
        }
      ]
    }
  ]
}

Der Befehl gibt additionalContext innerhalb eines hookSpecificOutput-Objekts auf stdout aus, versehen mit dem Ereignisnamen. Dieser Text wird in den Kontext des Agenten eingefügt:

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

Stop

Wird ausgelöst, wenn der Agent entscheidet, anzuhalten (seinen Zug zu beenden). Verwenden Sie dies, um nachfolgende Anweisungen hinzuzufügen oder ein vorzeitiges Anhalten zu verhindern. Stdin-Daten:

Field	Description
`stop_hook_active`	Ob bereits ein Stop-Hook aktiv ist

Beispiel — Agenten daran erinnern, Tests auszuführen:

{
  "Stop": [
    {
      "matcher": "",
      "hooks": [
        {
          "type": "command",
          "command": "echo '{\"decision\": \"block\", \"reason\": \"Please run the test suite before stopping.\"}'"
        }
      ]
    }
  ]
}

Vorsicht bei Stop-Hooks, die blockieren — sie können dazu führen, dass der Agent in eine Schleife gerät, wenn die Bedingung letztlich nicht erfüllt wird.

PostCompaction

Wird nach erfolgreichem Abschluss der Kontextkomprimierung ausgelöst. Verwenden Sie dies für die Protokollierung, das Auslösen nachgelagerter Aktionen oder das erneute Einfügen von Kontext, der während der Komprimierung verloren gegangen sein könnte. Stdin-Daten:

Feld	Beschreibung
`summary`	Vom Komprimierer erzeugter Zusammenfassungstext (kann null sein, wenn keine Zusammenfassung erzeugt wurde)

Beispiel — Komprimierungsereignisse protokollieren:

{
  "PostCompaction": [
    {
      "matcher": "",
      "hooks": [
        {
          "type": "command",
          "command": "sh -c 'cat >> ~/.devin-compaction-log'"
        }
      ]
    }
  ]
}

SessionStart

Wird ausgelöst, wenn eine neue Sitzung beginnt. Verwenden Sie es zur Initialisierung, Protokollierung oder für das Environment-Setup. Stdin-Daten:

Feld	Beschreibung
`source`	Wie die Sitzung gestartet wurde

Beispiel — Setup-Skript ausführen:

{
  "SessionStart": [
    {
      "matcher": "",
      "hooks": [
        {
          "type": "command",
          "command": "./scripts/dev-setup.sh",
          "timeout": 10
        }
      ]
    }
  ]
}

Ein SessionStart-Befehl kann auch Kontext hinzufügen, indem additionalContext in einem hookSpecificOutput-Objekt an stdout ausgegeben wird:

{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "Session started. Project uses ESM imports only."
  }
}

SessionEnd

Wird ausgelöst, wenn eine Sitzung endet. Verwenden Sie dieses Ereignis für Bereinigungen oder die abschließende Protokollierung. Stdin-Daten:

Feld	Beschreibung
`reason`	Grund für das Ende der Sitzung

Mehrere Ereignisse abgleichen

In einer einzelnen Hooks-Datei können Hooks für mehrere Ereignisse definiert werden:

{
  "PreToolUse": [
    {
      "matcher": "",
      "hooks": [
        { "type": "command", "command": "./scripts/audit.sh" }
      ]
    }
  ],
  "PostToolUse": [
    {
      "matcher": "",
      "hooks": [
        { "type": "command", "command": "./scripts/audit.sh" }
      ]
    }
  ]
}

Den Matcher verwenden

Das Feld matcher ist ein Regex, das mit dem tool_name des Hook-Ereignisses abgeglichen wird. Es ist für toolbezogene Ereignisse verfügbar: PreToolUse, PostToolUse und PermissionRequest. Bei Nicht-Tool-Ereignissen (UserPromptSubmit, Stop, PostCompaction, SessionStart und SessionEnd) gibt es kein tool_name; verwende "" oder lasse den Matcher weg, um den Hook für jedes Ereignis dieses Typs auszuführen.

Der Matcher ist kein Berechtigungs-Glob. Muster wie mcp__github__* sind für Berechtigungen nützlich, Hook-Matcher sind jedoch Regexe. Verwende in einem Hook-Matcher mcp__github__.*.

Matcher	Entspricht
`""` (leer) oder weggelassen	Alle Tool-Namen für Tool-Ereignisse
`"exec"`	Tool-Namen, die `exec` enthalten
`"^exec$"`	Nur das Tool `exec`
`"^(exec\|edit)$"`	Nur `exec` oder `edit`
`"^mcp__.*"`	Alle MCP-Tools
`"^mcp__github__.*"`	Alle Tools vom `github` MCP-Server
`"^mcp__github__create_issue$"`	Das Tool `create_issue` vom `github` MCP-Server

Tool-Namen, die Sie abgleichen können

Hook-Matcher werden anhand derselben extern sichtbaren Tool-Namen ausgeführt, die Hook-Skripte über stdin als tool_name erhalten. Welche Tool-Namen genau verfügbar sind, kann je nach CLI-Modus, Modell und aktivierten Integrationen variieren. Die gängigsten öffentlichen Core-Tool-Namen sind:

read
edit
grep
glob
exec

Tools auf einem MCP-Server erscheinen als mcp__<server>__<tool>. Zum Beispiel erscheint ein github-Tool auf einem MCP-Server mit dem Namen create_issue als mcp__github__create_issue. Bei anderen Tools gleichen Sie den exakten tool_name ab, der in Hook-stdin angezeigt wird. Um den in Ihrer aktuellen Sitzung vollständig verfügbaren Satz zu bestätigen, fügen Sie einen temporären PostToolUse-Hook mit matcher: "" hinzu und protokollieren Sie die stdin-Payload.

​PreToolUse

​PostToolUse

​PermissionRequest

​UserPromptSubmit

​Stop

​PostCompaction

​SessionStart

​SessionEnd

​Mehrere Ereignisse abgleichen

​Den Matcher verwenden

​Tool-Namen, die Sie abgleichen können

PreToolUse

PostToolUse

PermissionRequest

UserPromptSubmit

Stop

PostCompaction

SessionStart

SessionEnd

Mehrere Ereignisse abgleichen

Den Matcher verwenden

Tool-Namen, die Sie abgleichen können