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

sessionStart
sessionEnd
submitPrompt
preToolUse
postToolUse
subagentStart
subagentEnd

preToolUse que devuelve ask aún te solicita incluso en auto-aprobación o bypass.

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

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

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

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