# Portabilität: UNIVERSAL
# Version: 1.0.0
# Zuletzt validiert: 2026-02-13 (Claude Opus 4.6)
# Nächste Prüfung: 2026-08-13

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

Stand: 2026-02-13

Hooks sind ein erweiterbares Event-System für BACHs Lifecycle.
Sie erlauben es, eigene Logik an zentrale System-Events anzuhaengen,
OHNE bestehenden Code zu ändern.

WICHTIG: HOOKS != INJEKTOREN
-----------------------------
  Hooks     = Technisches Framework (Lifecycle-Events, Plugin-Integration)
  Injektoren = Kognitives Subsystem (Denksimulation, kognitive Entlastung)

Hooks und Injektoren arbeiten unabhängig voneinander.
Injektoren bleiben als eigenständiges Subsystem erhalten.

VERFÜGBARE EVENTS (17)
------------------------
  Event                    Wann                            Kontext-Keys
  ----------------------   ----------------------------    -------------------------
  before_startup           Vor dem Startup-Protokoll       partner, mode, quick
  after_startup            Nach erfolgreichem Startup      partner, mode, success
  before_shutdown          Vor dem Shutdown-Protokoll       partner, mode
  after_shutdown           Nach dem Shutdown                partner, mode, success
  before_command           Vor jedem CLI-Befehl            handler, operation, args
  after_command            Nach jedem CLI-Befehl           handler, operation, success, args
  after_task_create        Nach Task-Erstellung            task_id, title
  after_task_done          Nach Task-Abschluss             task_id, title
  after_task_delete        Nach Task-Löschung             task_id
  after_memory_write       Nach Memory-Eintrag             type, content
  after_lesson_add         Nach Lesson-Erstellung          lesson_id, title, category, severity
  after_skill_create       Nach Skill-Erstellung           name, type, path
  after_skill_reload       Nach Hot-Reload                 handler_count
  after_plugin_load        Nach Plugin-Laden               name, version, hooks, handlers
  after_plugin_unload      Nach Plugin-Entladen            name
  after_capability_denied  Nach verweigerter Capability    plugin, capability, reason
  after_email_send         Nach E-Mail-Versand             draft_id, recipient

CLI-BEFEHLE
-----------
  bach hooks status            Status aller Hooks und Listener
  bach hooks events            Alle Events mit Beschreibung auflisten
  bach hooks log               Letzte Hook-Ausführungen anzeigen
  bach hooks test <event>      Test-Event emittieren (Debugging)

  Kurzform:
  bach hook status             (Alias: hook -> hooks)

API-NUTZUNG
-----------
  from core.hooks import hooks

  # Listener registrieren
  def mein_handler(context):
      print(f"Task erstellt: {context['task_id']}")
      return "verarbeitet"  # Optional

  hooks.on('after_task_create', mein_handler, name='mein_plugin')

  # Listener mit Priorität (niedriger = frueher, default=50)
  hooks.on('after_startup', check_updates, priority=10, name='updater')

  # Listener entfernen
  hooks.off('after_task_create', name='mein_plugin')

  # Event manuell emittieren
  results = hooks.emit('after_task_create', {'task_id': 42, 'title': 'Test'})

  # Status abfragen
  print(hooks.status())

  # Prüfen ob Event Listener hat
  if hooks.has_listeners('after_startup'):
      print("Startup wird überwacht")

EIGENE HOOKS REGISTRIEREN
--------------------------
AI-Partner können eigene Hooks registrieren um BACH zu erweitern:

  from core.hooks import hooks

  # Beispiel: Auto-Backup nach jedem Task-Abschluss
  def auto_backup_nach_task(ctx):
      from bach_api import backup
      backup.create()
      return f"Backup nach Task #{ctx['task_id']}"

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

  # Beispiel: Benachrichtigung bei Startup
  def startup_notification(ctx):
      from bach_api import msg
      msg.send("user", f"Session gestartet ({ctx['partner']})")

  hooks.on('after_startup', startup_notification, name='notify')

SICHERHEIT
----------
  - Hooks sind in try/except gekapselt: Ein fehlerhafter Listener
    blockiert NIEMALS die eigentliche Operation
  - Listener erhalten nur Lese-Kontext (dict), keinen Schreibzugriff
  - Priorisierung verhindert Reihenfolge-Konflikte
  - Hook-Log (bach hooks log) für Debugging

ARCHITEKTUR
-----------
  core/hooks.py        HookRegistry-Singleton (Framework)
  hub/hooks.py         CLI-Handler (bach hooks ...)
  core/app.py          Emittiert before/after_command
  hub/startup.py       Emittiert before/after_startup
  hub/shutdown.py      Emittiert before/after_shutdown
  hub/task.py          Emittiert after_task_create/done
  hub/memory.py        Emittiert after_memory_write
  hub/lesson.py        Emittiert after_lesson_add
  hub/skills.py        Emittiert after_skill_create/reload
  core/plugin_api.py   Emittiert after_plugin_load/unload
  core/capabilities.py Emittiert after_capability_denied

SIEHE AUCH
----------
  bach help cli              CLI-Konventionen
  bach help skills           Skill-System
  bach help self-extension   Selbsterweiterungs-Workflow
  bach --inject status       Injektor-System (separates Subsystem)
