> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devin.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Hooks

> Ejecuta lógica personalizada cuando se produzcan eventos específicos durante una sesión

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](#where-hooks-live).

***

<div id="what-can-hooks-do">
  ## ¿Qué pueden hacer los Hooks?
</div>

<CardGroup cols={2}>
  <Card title="Aplicar políticas" icon="shield">
    Bloquear comandos peligrosos, exigir confirmación para acciones específicas o restringir el acceso a archivos.
  </Card>

  <Card title="Agregar contexto" icon="message">
    Inyectar instrucciones o información adicional cuando se llaman herramientas específicas.
  </Card>

  <Card title="Ejecutar efectos secundarios" icon="bolt">
    Ejecutar scripts, enviar notificaciones o registrar eventos cuando ocurren.
  </Card>

  <Card title="Modificar permisos" icon="lock">
    Otorgar o restringir permisos dinámicamente según la situación.
  </Card>
</CardGroup>

***

<div id="quick-example">
  ## Ejemplo rápido
</div>

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

```json theme={null}
{
  "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.

***

<div id="hook-events">
  ## Eventos de hooks
</div>

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](/es/cli/extensibility/hooks/lifecycle-hooks) para obtener más información sobre cada evento y los datos disponibles.

***

<div id="hook-format">
  ## Formato de los hooks
</div>

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:

```json theme={null}
{
  "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).                                                                                                                         |

<div id="command-hooks">
  ### Hooks de comando
</div>

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](#output-format) a continuación).

**Entrada** (stdin):

```json theme={null}
{
  "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](/es/cli/extensibility/hooks/lifecycle-hooks#using-the-matcher) para conocer los nombres de las herramientas integradas y el formato de nombre de herramienta de MCP con los que puedes hacer coincidencias.

<div id="output-format">
  ### Formato de salida
</div>

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):

```json theme={null}
{
  "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:

```json theme={null}
{
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "Remember: deploys require an approved change ticket."
  }
}
```

| 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`, `PostToolUse`)      |
| `hookSpecificOutput.additionalContext` | Texto que se inyecta en el contexto del agente (para `UserPromptSubmit`, `SessionStart`, `PostToolUse`) |

<div id="exit-codes">
  ### Códigos de salida
</div>

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

***

<div id="where-hooks-live">
  ## Dónde se encuentran los hooks
</div>

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

<div id="project-level">
  ### Nivel de proyecto
</div>

| 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)                    |

<div id="user-level-global">
  ### A nivel de usuario (global)
</div>

| 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)        |

<Note>
  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.
</Note>

<Note>
  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](/es/cli/reference/configuration/read-config-from).
</Note>

***

<div id="verifying-hooks">
  ## Verificar hooks
</div>

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

```
/hooks
```

***

<div id="next-steps">
  ## Próximos pasos
</div>

<CardGroup cols={2}>
  <Card title="Hooks del ciclo de vida" icon="rotate" href="/es/cli/extensibility/hooks/lifecycle-hooks">
    Profundiza en cada tipo de evento y en qué datos hay disponibles.
  </Card>

  <Card title="Configuración" icon="gear" href="/es/cli/reference/configuration/read-config-from">
    Controla de qué ubicaciones de configuración lee los hooks Devin CLI.
  </Card>
</CardGroup>