---
name: agent-os-hooks
description: Настроить хуки Agent OS — faq_cache, inject, escalate, memory, script_hook. Используй, когда просят добавить кэширование, память, эскалацию, впрыскивание сообщений или модерацию агенту.
---

# Agent OS — хуки

Хуки перехватывают жизненный цикл агента. Конфигурируются YAML-файлами в
`config/agents/<agent>/hooks/`, подключаются `hook_files:` в `agent.yaml`.
Полный справочник: `docs/06-hooks-reference.md`.

## Точки жизненного цикла

- `before_user_message` — впрыснуть, переписать, подавить или ответить самому.
- `after_turn` — после финального ответа (может выдать пост-ходовое уведомление).
- `after_loop` — при остановке цикла (`job_done`, `budget_exhausted`, …).

## Виды

| kind | Назначение |
|---|---|
| `faq_cache` | кэш (вопрос → ответ) в DuckDB; отдавать повторы, пропуская LLM |
| `inject` | декларативно впрыскивать системные/пользовательские сообщения |
| `escalate` | эскалация на человека, когда агент не может помочь |
| `memory` | долговременная память на пользователя (факты + сводка) |
| `script_hook` | скриптовый хук на JavaScript или Rhai (см. скилл `agent-os-scripts`) |

## `faq_cache` (кэш ответов, экономия токенов)

```yaml
kind: faq_cache
name: faq_cache
db_path: data/faq_cache_ngu.db   # запасной путь (в проде — общий messages.db)
max_candidates: 5
min_confidence: 0.7
short_circuit: true              # true = отвечать напрямую (пропустить LLM)
hit_notice: "⚡ Отвечено из кэша FAQ"
judge_instructions: |            # опциональный промпт судьи схожести
  You are a question similarity judge...
store:
  enabled: true
  min_question_chars: 8
  min_answer_chars: 8
```

## `inject` (добавить контекстные подсказки)

```yaml
kind: inject
name: city_hint
first_n: 1                       # сработать только на первые N сообщений
notice: "City context active"
messages:
  - role: system
    content: "Город пользователя — Москва."
```

## `escalate` (передача человеку)

```yaml
kind: escalate
name: escalate
message: "Если это не то — свяжитесь с поддержкой: ..."
off_topic_keywords: [iphone, "доставка"]
suppress_on_off_topic: true
empty_answer_patterns: ["не нашёл"]
min_answer_chars: 30
remind_next_turn: true
```

## `memory` (долгая память пользователя)

```yaml
kind: memory
name: user_memory
db_path: data/memory_ngu.db
max_candidates: 8
min_confidence: 0.6
notice: ""                    # опц. уведомление о воспоминании ({{count}})
inject_template: ""           # шаблон: {{facts}}, {{summaries}}, {{memories}}
judge_instructions: ""        # промпт судьи релевантности
judge_model: ""               # опц. более дешёвая модель для судьи
backfill: true                # false → пропускать кандидатов при слабом пересечении
max_memories_per_scope: 200
dedup_threshold: 0.8
store:
  enabled: true
  min_question_chars: 4
  min_answer_chars: 20
  extractor_instructions: ""  # промпт запоминателя
  memorizer_model: ""         # опц. более дешёвая модель для запоминателя
  memorize_every: 1           # запускать запоминатель каждые N ходов
  max_episodes_per_scope: 50
  summary_max_chars: 2000
```

Память скоупится на пользователя (`user_id`), с откатом к сессии → шаблону →
процессу. Инспекция — `GET /v1/memory/:scope`.

## Тестирование хука (без сервера)

```bash
hook_tool <hook.yaml> user "Привет, мир"
hook_tool <hook.yaml> turn "вопрос" "ответ"
hook_tool <hook.yaml> info
hook_tool <hook.yaml> user "..." --live      # реальный судья/запоминатель через LLM
```

## Подключение

```yaml
# config/agents/<agent>/agent.yaml
hook_files:
  - hooks/faq_cache.yaml
  - hooks/memory.yaml
```

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