# Хуки
URL: /ru/docs/customize/hooks

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



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

## События [#события]

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

Возврат `ask` из `preToolUse` всё равно запрашивает подтверждение даже при [автоодобрении или обходе](../agent/approvals.mdx).

## Где они находятся [#где-они-находятся]

| Область         | Конфигурация                     | Скрипты                      |
| --------------- | -------------------------------- | ---------------------------- |
| Пользователь    | `{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`     |

## Пример [#пример]

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