Hooks

Los hooks te permiten ejecutar lógica personalizada en respuesta a eventos del ciclo de vida del agente. Puedes usar hooks para aplicar políticas, agregar contexto, registrar acciones, modificar permisos o integrarlos con sistemas externos. Los hooks se configuran en formato JSON. Colócalos en el directorio .devin/ de tu proyecto (o en una configuración a nivel de usuario) y Devin CLI los ejecutará en los eventos del ciclo de vida que correspondan. Los hooks existentes en los directorios .claude/ también se detectan automáticamente — consulta Dónde se encuentran los hooks.

¿Qué pueden hacer los Hooks?

Aplicar políticas

Bloquear comandos peligrosos, exigir confirmación para acciones específicas o restringir el acceso a archivos.

Agregar contexto

Inyectar instrucciones o información adicional cuando se llaman herramientas específicas.

Ejecutar efectos secundarios

Ejecutar scripts, enviar notificaciones o registrar eventos cuando ocurren.

Modificar permisos

Otorgar o restringir permisos dinámicamente según la situación.

Ejemplo rápido

Crea .devin/hooks.v1.json en tu proyecto:

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

Esto ejecuta ./scripts/check-command.sh antes de ejecutar cada comando de shell. El script recibe los datos del evento por stdin y puede impedir la ejecución devolviendo un código de salida distinto de cero.

Eventos de hooks

Los hooks pueden responder a estos eventos del ciclo de vida:

Evento	Cuándo se activa
`PreToolUse`	Antes de que se ejecute una herramienta
`PostToolUse`	Después de que una herramienta termine
`PermissionRequest`	Cuando se requiere una decisión sobre permisos
`UserPromptSubmit`	Cuando el usuario envía un mensaje
`Stop`	Cuando el agente quiere detenerse
`SessionStart`	Cuando comienza una sesión
`SessionEnd`	Cuando termina una sesión

Consulta Hooks del ciclo de vida para obtener más información sobre cada evento y los datos disponibles.

Formato de los hooks

Cada hook tiene un tipo (command o prompt), un matcher opcional (una regex sobre el tool_name del evento del hook) y una configuración:

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

Campo	Descripción
`matcher`	Expresión regular que se compara con `tool_name` del evento del hook. Una cadena vacía o la omisión de `matcher` coincide con todos los nombres de herramientas.
`type`	`"command"` para ejecutar un comando de shell, o `"prompt"` para evaluar un prompt de LLM.
`command`	Comando de shell que se debe ejecutar (para el tipo `command`).
`prompt`	Prompt de LLM que se debe evaluar (para el tipo `prompt`).
`timeout`	Tiempo de espera en segundos (opcional).

Hooks de comando

Los hooks de comando ejecutan un comando de shell. Los datos del evento se envían como JSON a través de stdin, y el comando puede devolver JSON por stdout para controlar el resultado (consulta Formato de salida a continuación). Entrada (stdin):

{
  "hook_event_name": "PreToolUse",
  "tool_name": "exec",
  "tool_input": {
    "command": "rm -rf /"
  }
}

La variable de entorno DEVIN_PROJECT_DIR se establece automáticamente como el directorio raíz del proyecto. Consulta Cómo usar el Matcher para conocer los nombres de las herramientas integradas y el formato de nombre de herramienta de MCP con los que puedes hacer coincidencias.

Formato de salida

Un hook de comando puede imprimir un objeto JSON en stdout para controlar el resultado. Para aprobar o bloquear una acción, devuelve un decision en el nivel superior (con un reason opcional):

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

Para inyectar texto en el contexto del agente, devuelve additionalContext dentro de un objeto hookSpecificOutput identificado con el nombre del evento:

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

Para reescribir de forma transparente la entrada de una herramienta antes de que se ejecute, devuelve updatedInput dentro de un hookSpecificOutput de PreToolUse. Los campos de updatedInput se combinan con los argumentos de la herramienta, por lo que puedes actualizar un subconjunto (p. ej., solo command):

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

Campo de salida	Descripción
`decision`	`"approve"` para permitir la acción, o `"block"` para denegarla
`reason`	Explicación que se muestra al agente
`hookSpecificOutput.hookEventName`	Evento al que se aplica este resultado (p. ej., `UserPromptSubmit`, `SessionStart`, `PreToolUse`, `PostToolUse`)
`hookSpecificOutput.additionalContext`	Texto que se inyecta en el contexto del agente (para `UserPromptSubmit`, `SessionStart`, `PostToolUse`)
`hookSpecificOutput.updatedInput`	Objeto que se fusiona con los argumentos de la herramienta antes de la ejecución (para `PreToolUse`)

Códigos de salida

Código	Significado
0	Éxito — el hook continúa con normalidad
2	Bloqueo — la acción se deniega
Otro	Error — se registra, pero no bloquea

Dónde se encuentran los hooks

Devin CLI lee los hooks de las siguientes ubicaciones. Todos usan el mismo formato JSON.

Nivel de proyecto

Ubicación	Descripción
`.devin/hooks.v1.json`	Archivo de hooks independiente (recomendado)
`.devin/config.json`	clave `"hooks"` en el archivo de configuración
`.devin/config.local.json`	clave `"hooks"` (anulación local, incluida en `.gitignore`)
`.claude/settings.json`	clave `"hooks"` (formato de Claude Code)
`.claude/settings.local.json`	clave `"hooks"` (formato de Claude Code)

A nivel de usuario (global)

Ubicación	Descripción
`~/.config/devin/config.json` (`%APPDATA%\devin\config.json` en Windows)	clave `"hooks"` en la configuración del usuario
`~/.claude.json`	clave `"hooks"` (formato de Claude Code)
`~/.claude/settings.json`	clave `"hooks"` (formato de Claude Code)
`~/.claude/settings.local.json`	clave `"hooks"` (formato de Claude Code)

En .devin/hooks.v1.json, el objeto hooks es el archivo completo (no se necesita una clave contenedora). En todas las demás ubicaciones, hooks está anidado bajo la clave "hooks" dentro de un archivo de configuración.

Los hooks de las rutas .claude/ se cargan cuando read_config_from.claude está habilitado (de forma predeterminada). Si es necesario, puedes desactivarlo en tu configuración de usuario.

Verificar hooks

Usa el comando de barra diagonal /hooks para ver todos los hooks cargados actualmente y sus archivos de origen:

/hooks

¿Qué pueden hacer los Hooks?

Aplicar políticas

Agregar contexto

Ejecutar efectos secundarios

Modificar permisos

Ejemplo rápido

Eventos de hooks

Formato de los hooks

Hooks de comando

Formato de salida

Códigos de salida

Dónde se encuentran los hooks

Nivel de proyecto

A nivel de usuario (global)

Verificar hooks

Próximos pasos

Hooks del ciclo de vida

Configuración

​¿Qué pueden hacer los Hooks?

Aplicar políticas

Agregar contexto

Ejecutar efectos secundarios

Modificar permisos

​Ejemplo rápido

​Eventos de hooks

​Formato de los hooks

​Hooks de comando

​Formato de salida

​Códigos de salida

​Dónde se encuentran los hooks

​Nivel de proyecto

​A nivel de usuario (global)

​Verificar hooks

​Próximos pasos

Hooks del ciclo de vida

Configuración

¿Qué pueden hacer los Hooks?

Ejemplo rápido

Eventos de hooks

Formato de los hooks

Hooks de comando

Formato de salida

Códigos de salida

Dónde se encuentran los hooks

Nivel de proyecto

A nivel de usuario (global)

Verificar hooks

Próximos pasos