Hooks del ciclo de vida

Cada evento de hook se activa en un punto específico del ciclo de vida del agente. Usa el campo matcher (una expresión regular que se compara con el tool_name del evento de hook) para filtrar qué invocaciones de herramientas activan tu hook.

PreToolUse

Se activa antes de que se ejecute una herramienta. Úsalo para bloquear, modificar o agregar contexto a las llamadas a herramientas. Datos de stdin:

Campo	Descripción	Ejemplo
`tool_name`	Nombre de la herramienta invocada	`exec`, `edit`, `mcp__github__create_issue`
`tool_input`	Argumentos pasados a la herramienta	`{ "command": "rm -rf /", "shell_id": "main" }`

Ejemplo: bloquear comandos destructivos

{
  "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)\""
        }
      ]
    }
  ]
}

Ejemplo — Exigir confirmación para operaciones de escritura fuera de src/: Usa un script que inspeccione la entrada de la herramienta y devuelva una decisión:

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

Ejemplo — Reescribir comandos antes de ejecutarlos: Un hook puede reescribir de forma transparente la entrada de la herramienta imprimiendo hookSpecificOutput.updatedInput en stdout (consulta Formato de salida). Por ejemplo, un script de hook que redirige los comandos de shell a través de un wrapper:

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

Los argumentos reescritos se incorporan a la llamada a la herramienta antes de que se ejecute; el agente ejecuta el comando actualizado en lugar del original.

PostToolUse

Se activa después de que una herramienta termina de ejecutarse. Úsalo para registros, validación o para desencadenar acciones posteriores. Datos de stdin:

Campo	Descripción
`tool_name`	Nombre de la herramienta que se ejecutó
`tool_input`	Argumentos que se proporcionaron
`tool_response`	Objeto con `success` (boolean), `output` (string) y `error` (string o null)

Ejemplo — Registrar todos los comandos del shell:

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

PermissionRequest

Se activa cuando el agente necesita una decisión sobre permisos. Úsalo para implementar una lógica de aprobación personalizada. Datos de stdin:

Campo	Descripción
`tool_name`	Herramienta que solicita permiso
`tool_input`	Argumentos para la llamada a la herramienta

Ejemplo — Aprobar automáticamente comandos de git:

{
  "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

Se activa cuando el usuario envía un mensaje. Úsalo para agregar contexto o desencadenar flujos de trabajo. Datos de stdin:

Campo	Descripción
`prompt`	El texto del mensaje del usuario

Ejemplo — Inyectar contexto en cada prompt:

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

El comando imprime additionalContext dentro de un objeto hookSpecificOutput en stdout, con la etiqueta del nombre del evento. Ese texto se inyecta en el contexto del agente:

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

Detener

Se activa cuando el agente decide detenerse (finalizar su turno). Usa esto para agregar instrucciones de seguimiento o evitar que se detenga antes de tiempo. Datos de stdin:

Field	Description
`stop_hook_active`	Si ya hay un hook de detención activo

Ejemplo — Recordarle al agente que ejecute pruebas:

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

Ten cuidado con los hooks de detención que bloquean: pueden hacer que el agente se quede en un bucle si la condición no acaba cumpliéndose.

PostCompaction

Se activa después de que la compactación del contexto se complete correctamente. Úsalo para el registro, desencadenar acciones posteriores o volver a inyectar contexto que pueda haberse perdido durante la compactación. Datos de stdin:

Campo	Descripción
`summary`	Texto de resumen generado por el compactador (puede ser `null` si no se generó ningún resumen)

Ejemplo — Registrar eventos de compactación:

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

SessionStart

Se activa cuando comienza una nueva sesión. Úsalo para la inicialización, el registro o la configuración del entorno. Datos de stdin:

Campo	Descripción
`source`	Cómo se inició la sesión

Ejemplo — Ejecutar script de configuración:

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

Un comando SessionStart también puede inyectar contexto al imprimir additionalContext dentro de un objeto hookSpecificOutput en stdout:

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

SessionEnd

Se activa cuando finaliza una sesión. Úsalo para tareas de limpieza o para el registro final. Datos de stdin:

Campo	Descripción
`reason`	Motivo por el que finalizó la sesión

Coincidencia de múltiples eventos

Un único archivo de hooks puede definir hooks para múltiples eventos:

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

Cómo usar el matcher

El campo matcher es una regex que se hace coincidir con el tool_name del evento del hook. Está disponible para eventos relacionados con herramientas: PreToolUse, PostToolUse y PermissionRequest. En los eventos no relacionados con herramientas (UserPromptSubmit, Stop, PostCompaction, SessionStart y SessionEnd), no hay tool_name; usa "" u omite el matcher para ejecutar el hook en todos los eventos de ese tipo.

El matcher no es un glob de permisos. Patrones como mcp__github__* son útiles en los permisos, pero los matchers de hooks son regexes. Usa mcp__github__.* en un matcher de hook.

Matcher	Coincide con
`""` (vacío) u omitido	Todos los nombres de herramientas en eventos de herramientas
`"exec"`	Nombres de herramientas que contienen `exec`
`"^exec$"`	Solo la herramienta `exec`
`"^(exec\|edit)$"`	Solo `exec` o `edit`
`"^mcp__.*"`	Todas las herramientas MCP
`"^mcp__github__.*"`	Todas las herramientas del servidor MCP `github`
`"^mcp__github__create_issue$"`	La herramienta `create_issue` del servidor MCP `github`

Nombres de herramientas que puedes hacer coincidir

Los matchers de hooks se aplican a los mismos nombres de herramientas visibles externamente que los scripts de hook reciben por stdin como tool_name. Los nombres exactos de las herramientas disponibles pueden variar según el modo de CLI, el modelo y las integraciones habilitadas. Los nombres de herramientas core públicas más comunes son:

read
edit
grep
glob
exec

Las herramientas de servidor MCP aparecen como mcp__<server>__<tool>. Por ejemplo, una herramienta de servidor MCP de github llamada create_issue aparece como mcp__github__create_issue. Para otras herramientas, haz coincidir el tool_name exacto que se muestra en el stdin del hook. Para confirmar el conjunto completo disponible en tu sesión actual, agrega un hook PostToolUse temporal con matcher: "" y registra el payload de stdin.

​PreToolUse

​PostToolUse

​PermissionRequest

​UserPromptSubmit

​Detener

​PostCompaction

​SessionStart

​SessionEnd

​Coincidencia de múltiples eventos

​Cómo usar el matcher

​Nombres de herramientas que puedes hacer coincidir

PreToolUse

PostToolUse

PermissionRequest

UserPromptSubmit

Detener

PostCompaction

SessionStart

SessionEnd

Coincidencia de múltiples eventos

Cómo usar el matcher

Nombres de herramientas que puedes hacer coincidir