# Portability: UNIVERSAL
# Last validated: 2026-05-17
# Next review: 2027-05-17

BACH HOOK-FRAMEWORK
===================

По состоянию на 13 февраля 2026 г.

Hooks — это расширяемая система событий для жизненного цикла BACH.
Они позволяют вам привязывать свою собственную логику к центральным системным событиям.
БЕЗ изменения существующего кода.

ВАЖНО: КРЮКИ != ИНЖЕКТОРЫ
-----------------------------
  Хуки = техническая основа (события жизненного цикла, интеграция плагинов)
  Инжекторы = когнитивная подсистема (симуляция мышления, когнитивное облегчение)

Крюки и инжекторы работают независимо друг от друга.
Форсунки остаются как независимая подсистема.

ДОСТУПНЫЕ СОБЫТИЯ (17)
------------------------
  Событие, когда контекстные клавиши
  ---------------------- ---------------------------- ------------------------
  before_startup Перед запуском протокола партнера, режим, быстрый
  after_startup После успешного запуска партнера, режим, успех
  before_shutdown Перед выключением партнера по протоколу, режим
  after_shutdown После завершения работы партнера, режима, успеха
  before_command Перед каждым обработчиком команды CLI, операцией, аргументами
  after_command После каждого обработчика команды CLI, операции, успеха, аргументов
  after_task_create После создания задачи идентификатор задачи, заголовок
  after_task_done После завершения задачи идентификатор_задачи, заголовок
  after_task_delete После удаления задачи идентификатор задачи
  after_memory_write После типа записи в памяти, содержимое
  after_lesson_add После создания урока идентификатор урока, название, категория, серьезность
  after_skill_create Имя, тип и путь после создания навыка
  after_skill_reload После горячей перезагрузки handler_count
  after_plugin_load Имя, версия, хуки, обработчики после загрузки плагина
  after_plugin_unload Имя после выгрузки плагина
  after_capability_denied Плагин возможностей, возможность, причина
  after_email_send После отправки электронного письма Draft_id, получатель

КОМАНДЫ CLI
-----------
  bach hooks status            Состояние всех перехватчиков и прослушивателей
  bach hooks events            Перечислить все события с описанием
  bach hooks log               Показать последние выполненные перехватчики
  bach hooks test <event>      Выдать тестовое событие (отладка)

  Краткая форма:
  bach hook status             (Псевдоним: крючок -> крючки)

ИСПОЛЬЗОВАНИЕ API
-----------
  из core.hooks импортные хуки

  # Регистрация слушателей
  защита my_handler (контекст):
      print(f"Задача создана: {context['task_id']}")
      return "обработано" # Необязательно

  ooks.on('after_task_create', my_handler, name='my_plugin')

  # Прослушиватель с приоритетом (ниже = раньше, по умолчанию = 50)
  ooks.on('after_startup', check_updates, Priority=10, name='updater')

  # Удаление слушателей
  ooks.off('after_task_create', name='my_plugin')

  # Генерируем событие вручную
  результаты =ooks.emit('after_task_create', {'task_id': 42, 'title': 'Test'})

  # Статус запроса
  print(hooks.status())

  # Проверяем, есть ли у события слушатели
  еслиooks.has_listeners('after_startup'):
      print("Запуск контролируется")

РЕГИСТРАЦИЯ СОБСТВЕННЫХ Крючков
--------------------------
ИИ-партнеры могут регистрировать свои собственные перехватчики для расширения BACH:

  из core.hooks импортные хуки

  # Пример: автоматическое резервное копирование после завершения каждой задачи.
  защита auto_backup_nach_task(ctx):
      из резервной копии импорта bach_api
      резервное копирование.создать()
      return f"Резервное копирование после задачи #{ctx['task_id']}"

  ooks.on('after_task_done', auto_backup_nach_task, name='auto_backup')

  # Пример: уведомление о запуске
  защита start_notification (ctx):
      из bach_api импортировать сообщение
      msg.send("user", f"Сеанс начат ({ctx['partner']})")

  ooks.on('after_startup', start_notification, name='notify')

БЕЗОПАСНОСТЬ
----------
  - Хуки инкапсулированы в try/Exception: сломанный прослушиватель.
    НИКОГДА не блокирует фактическую операцию
  - Слушатели получают только контекст чтения (dict), но не доступ на запись.
  - Расстановка приоритетов предотвращает конфликты заказов
  - Журнал хуков (журнал хуков Баха) для отладки

АРХИТЕКТУРА
-----------
core/hooks.py Singleton HookRegistry (фреймворк)
  Обработчик CLIhub/hooks.py (хуки Баха...)
  core/app.py Выдает before/after_command
  Hub/startup.py Выдает до/после_запуска
  Hub/shutdown.py Выдает до/после_shutdown
  Hub/task.py выдаёт after_task_create/done
  Hub/memory.py Выдает after_memory_write
  Hub/lesson.py выдает after_lesson_add
  Hub/skills.py Выдает after_skill_create/reload
  core/plugin_api.py Выдает after_plugin_load/unload
  core/capabilities.py Создается after_capability_denied

СМОТРИ ТАКЖЕ
----------
  bach help cli              Соглашения CLI
  bach help skills           Система навыков
  bach help self-extension   Рабочий процесс с саморасширением
  bach --inject status       Система инжекторов (отдельная подсистема)
