# Hooks
URL: /es/docs/customize/hooks

Ejecuta scripts en eventos de sesión, herramienta y subagente. Pueden permitir, denegar o preguntar.



Los hooks son scripts que Spirit ejecuta en puntos fijos. Pueden permitir una herramienta, denegarla o forzar un aviso de aprobación (`ask`).

## Eventos [#eventos]

* `sessionStart`
* `sessionEnd`
* `submitPrompt`
* `preToolUse`
* `postToolUse`
* `subagentStart`
* `subagentEnd`

`preToolUse` que devuelve `ask` aún te solicita incluso en [auto-aprobación o bypass](../agent/approvals.mdx).

## Dónde se encuentran [#dónde-se-encuentran]

| Alcance            | Config                           | Scripts                      |
| ------------------ | -------------------------------- | ---------------------------- |
| Usuario            | `{spiritDataDir}/hooks.json`     | `{spiritDataDir}/hooks/`     |
| Espacio de trabajo | `{workspace}/.spirit/hooks.json` | `{workspace}/.spirit/hooks/` |

En el mismo evento, las entradas de usuario y las del espacio de trabajo se concatenan en ese orden. No se sobrescriben entre sí.

Gestionarlos en **Configuración → Hooks**. Valida desde la CLI con `spirit hooks list` y `spirit hooks validate`. La Skill integrada `create-hook` redacta un hook.

## Campos del archivo [#campos-del-archivo]

El objeto raíz debe incluir `version` y `hooks`. `version` actualmente solo acepta `1`.

| Campo     | Descripción                                                                                             |
| --------- | ------------------------------------------------------------------------------------------------------- |
| `version` | Requerido. Debe ser `1`                                                                                 |
| `hooks`   | Requerido. Objeto. Las claves son nombres de eventos; los valores son arreglos de hooks para ese evento |

### Cada hook [#cada-hook]

| Campo        | Descripción                                                                                                                                                               |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `command`    | Requerido. Ruta del script. Una ruta relativa se resuelve contra el directorio de configuración y debe permanecer dentro de él                                            |
| `timeout`    | Opcional. Tiempo de espera en segundos. Debe ser un número positivo. Por defecto es `30`                                                                                  |
| `failClosed` | Opcional. Si bloquear cuando el script se bloquea, expira o escribe JSON no válido en la salida estándar. Por defecto no bloquea                                          |
| `matcher`    | Opcional. Expresión regular no vacía. Coincide con el nombre de la herramienta en `preToolUse` / `postToolUse`, o el tipo de subagente en `subagentStart` / `subagentEnd` |

## Ejemplo [#ejemplo]

```json
{
  "version": 1,
  "hooks": {
    "preToolUse": [
      {
        "command": "hooks/guard.sh",
        "timeout": 10,
        "failClosed": true,
        "matcher": "^shell$"
      }
    ],
    "sessionEnd": [
      {
        "command": "hooks/log.sh"
      }
    ]
  }
}
```