Хуки

Запускайте скрипты при событиях сеанса, инструмента и сабагента. Они могут разрешать, запрещать или запрашивать.

Хуки — это скрипты, которые Spirit запускает в фиксированных точках. Они могут разрешить инструмент, запретить его или принудительно показать запрос на подтверждение (ask).

События

sessionStart
sessionEnd
submitPrompt
preToolUse
postToolUse
subagentStart
subagentEnd

Возврат ask из preToolUse всё равно запрашивает подтверждение даже при автоодобрении или обходе.

Где они находятся

Область	Конфигурация	Скрипты
Пользователь	`{spiritDataDir}/hooks.json`	`{spiritDataDir}/hooks/`
Рабочая область	`{workspace}/.spirit/hooks.json`	`{workspace}/.spirit/hooks/`

При одном и том же событии пользовательские и рабочие записи объединяются в этом порядке. Они не перезаписывают друг друга.

Управляйте ими в Настройки → Хуки. Проверяйте из CLI с помощью spirit hooks list и spirit hooks validate. Встроенный навык create-hook создаёт черновик хука.

Поля файла

Корневой объект должен содержать version и hooks. В version в настоящее время принимается только 1.

Поле	Описание
`version`	Обязательно. Должно быть `1`
`hooks`	Обязательно. Объект. Ключи — имена событий; значения — массивы хуков для этого события

Каждый хук

Поле	Описание
`command`	Обязательно. Путь к скрипту. Относительный путь разрешается относительно каталога конфигурации и должен оставаться внутри него
`timeout`	Необязательно. Тайм-аут в секундах. Должен быть положительным числом. По умолчанию — `30`
`failClosed`	Необязательно. Блокировать ли, когда скрипт аварийно завершается, истекает по тайм-ауту или записывает недопустимый JSON в стандартный вывод. По умолчанию не блокирует
`matcher`	Необязательно. Непустое регулярное выражение. Соответствует имени инструмента на `preToolUse` / `postToolUse` или типу сабагента на `subagentStart` / `subagentEnd`

Пример

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