Hooks
OMNI runs a production Hook runtime inagent-backend with config validation, scheduling, and execution controls.
Current Truth State
| Area | Status |
|---|---|
| Docs/API contract | Live |
| Runtime support | Live in @omni/agent-backend |
| Config file | hooks.json in agent data workspace |
| Event log | events.jsonl in agent data workspace |
| Runtime controls | REST (/api/hooks/*) + WebSocket (hooks:*) |
Hook Model
Hooks connect events to actions.Events currently wired
- Label add/remove
- Session status change
- Scheduled tick
- Tool lifecycle events
- User prompt submit
- Session start/end
- Permission request
- Stop (abort signal)
- Setup (runtime init)
Actions
- Command hooks with safety modes (
safe,ask,allow-all) - Prompt hooks that create autonomous sessions
Runtime Notes
- Prompt hooks are supported on app events, including scheduler ticks.
- Scheduler runs every minute and applies cron/timezone matching.
- Per-event rate limits are active to prevent runaway loops.
- Hook commands receive
OMNI_*runtime env vars.
Operator Guidance
Recommended production usage:- Use labels/status transitions for deterministic routing.
- Use prompt hooks for recurring briefings and autonomous research sessions.
- Use command hooks for trusted automation with explicit permission mode.