Event & Hooks System
Relevant source files
The following files were used as context for generating this wiki page:
The Event & Hooks System in Oh-My-OpenCode serves as the primary mechanism for extending and intercepting the lifecycle of the OpenCode plugin. It allows for multi-model agent orchestration by leveraging 34 distinct lifecycle hooks that monitor, modify, and validate agent behavior in real-time. This system is the architectural "backbone" that enables the plugin to function as an "oh-my-zsh" equivalent for OpenCode, providing features like specialized agent constraints, automated task delegation, and strategic planning reinforcements.
Sources: AGENTS.md:144-149, AGENTS.md:155-156
System Architecture
The architecture is built around a centralized registration pattern where hooks are defined in specialized directories and registered through a main entry point. The system intercepts various lifecycle stages, such as session starts, tool usage, and agent transitions.
Hook Lifecycle and Registration
Hooks are created using factory functions (e.g., createXXXHook) that take a PluginInput object and return event handlers. These hooks are then aggregated in the main plugin entry point to respond to OpenCode events.
Sources: AGENTS.md:183-183, src/hooks/prometheus-md-only/constants.ts:5-23
The diagram shows how the OpenCode core triggers events that flow through the plugin entry point into specific hook implementations like Atlas and Prometheus.
Sources: AGENTS.md:158-160, src/hooks/prometheus-md-only/constants.ts:5-23
Specialized Hook Implementations
Prometheus MD-Only Hook
This specialized hook enforces strict read-only constraints on the Prometheus planning agent. It ensures that the planner cannot modify source code, restricting its file operations exclusively to the .sisyphus directory and .md file extensions.
- Allowed Path:
.sisyphus - Allowed Extensions:
.md - Blocked Tools:
Write,Edit(case-insensitive)
Sources: src/hooks/prometheus-md-only/constants.ts:9-15
Atlas Orchestrator Hook
The Atlas hook acts as the master orchestrator. It manages the full task lifecycle, from initial plan analysis to final verification. It handles complex logic involving 757 lines of code to coordinate multiple subagents and ensure that all tasks in a work plan are completed and verified.
Sources: AGENTS.md:200-200, AGENTS.md:213-213
Hook Event Types
The system supports various event handlers that correspond to the plugin lifecycle. While the full list includes 34 hooks, key event categories derived from the source files include:
| Event Type | Description |
|---|---|
onSessionStart | Triggered when a new agent session begins; used for initialization. |
PreToolUse | Intercepts tool calls before execution; used for validation and enforcement. |
onTaskComplete | Triggered when a delegated task finishes; used for result verification. |
Sources: src/hooks/prometheus-md-only/constants.ts:15-23, AGENTS.md:189-189
Execution and Safety Logic
The Event & Hooks System includes safety mechanisms to prevent slow-downs and maintain system integrity.
Performance Constraints
Heavy logic in PreToolUse hooks is identified as a "complexity hotspot" because it can slow down every tool call. The system guidelines advise against excessive logic in these hooks to maintain responsiveness.
Sources: AGENTS.md:189-189
Permission and Tool Restrictions
Hooks frequently interact with shared utilities to enforce tool restrictions, particularly for specialized agents like Prometheus and Oracle, which are restricted from performing implementation tasks like writing or editing code.
Sources: src/hooks/prometheus-md-only/constants.ts:15-15, src/agents/oracle.ts:121-126
The sequence diagram illustrates the validation logic of the MD-Only hook preventing unauthorized file writes by the planning agent.
Sources: src/hooks/prometheus-md-only/constants.ts:9-23
Summary
The Event & Hooks System is the primary control layer for Oh-My-OpenCode. By intercepting lifecycle events, it enables the orchestration of multiple AI models (Claude, GPT, Gemini) while enforcing the project's rigid "Planner vs. Executor" architecture. Through hooks like prometheus-md-only and atlas, the system ensures that strategic planning remains distinct from technical implementation, maintaining a safe and structured development workflow.
Sources: AGENTS.md:155-156, src/hooks/prometheus-md-only/constants.ts:25-50