> ## 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 del ciclo de vida

> Comprender los eventos de hook y los datos disponibles en cada etapa

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.

***

<div id="pretooluse">
  ## PreToolUse
</div>

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

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

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

***

<div id="posttooluse">
  ## PostToolUse
</div>

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

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

***

<div id="permissionrequest">
  ## PermissionRequest
</div>

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

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

***

<div id="userpromptsubmit">
  ## UserPromptSubmit
</div>

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

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

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

***

<div id="stop">
  ## Detener
</div>

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

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

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

***

<div id="postcompaction">
  ## PostCompaction
</div>

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

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

***

<div id="sessionstart">
  ## SessionStart
</div>

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

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

```json theme={null}
{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "Session started. Project uses ESM imports only."
  }
}
```

***

<div id="sessionend">
  ## SessionEnd
</div>

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 |

***

<div id="matching-multiple-events">
  ## Coincidencia de múltiples eventos
</div>

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

```json theme={null}
{
  "PreToolUse": [
    {
      "matcher": "",
      "hooks": [
        { "type": "command", "command": "./scripts/audit.sh" }
      ]
    }
  ],
  "PostToolUse": [
    {
      "matcher": "",
      "hooks": [
        { "type": "command", "command": "./scripts/audit.sh" }
      ]
    }
  ]
}
```

<div id="using-the-matcher">
  ## Cómo usar el matcher
</div>

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.

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

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

<div id="tool-names-you-can-match">
  ### Nombres de herramientas que puedes hacer coincidir
</div>

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.