Interaction Hooks
Relevant source files
The following files were used as context for generating this wiki page:
Interaction Hooks constitute the behavioral layer of the Oh-My-OpenCode plugin, enabling multi-model agent orchestration and lifecycle management within the OpenCode environment. These hooks intercept system events to apply constraints, trigger specialized agent behaviors, and manage task continuation across 34 distinct lifecycle stages.
Sources: AGENTS.md:121-125, src/index.ts:788
Architecture and Integration
The hook system is integrated into the main plugin entry point via the OhMyOpenCodePlugin class. Hooks are created using factory functions following the createXXXHook(input: PluginInput) pattern. This structure allows the plugin to respond to user input, session transitions, and tool usage in real-time.
Hook Categories
The system utilizes diverse hook types to manage different aspects of agent interaction:
- Orchestration Hooks: Manage the primary flow between models (e.g., Atlas, Sisyphus).
- Safety & Constraint Hooks: Enforce non-negotiable rules, such as the
prometheus-md-onlyhook which restricts file writes to Markdown. - Continuity Hooks: Manage task and session state persistence, often referenced as system reminders for TODO or Task continuation.
Sources: src/index.ts, src/agents/prometheus/identity-constraints.ts:89-91, src/agents/sisyphus.ts:161-163
Data Flow Diagram
The following diagram illustrates how interaction hooks intercept user requests and orchestrate subagent tasks.
Specialized Interaction Logic
Prometheus Planning Hooks
The Prometheus agent utilizes specific hooks to enforce its identity as a planner rather than an implementer. It operates under a "Strategic Planning Consultant" persona where user requests for direct work (e.g., "build X") are intercepted and re-interpreted as requests for a work plan.
| Feature | Enforcement Logic | Source |
|---|---|---|
| Identity Constraint | re-interprets "do X" as "plan X" | identity-constraints.ts:12-25 |
| Path Enforcement | Restricts writes to .sisyphus/plans/ | identity-constraints.ts:93-100 |
| Single Plan Mandate | Consolidates all tasks into one .md file | identity-constraints.ts:111-120 |
Sisyphus Execution Hooks
The Sisyphus agent serves as the primary orchestrator, utilizing hooks to manage parallel execution and background tasks. It employs an "Intent Gate" at Phase 0 for every message to classify requests before acting.
Task and Session Management
A critical component of the interaction hooks is the management of TODOs and Tasks to provide user visibility and enable recovery.
- Todo Discipline: Mandatory for multi-step tasks. Agents must use
todowrite(orTaskCreate) to plan atomic steps before implementation. - Status Tracking: Hooks track transitions between
pending,in_progress, andcompleted. - Session Continuity: Every delegation hook returns a
session_id, which must be reused to preserve full context and save tokens during follow-up interactions.
Sources: src/agents/hephaestus.ts:12-40, src/agents/sisyphus.ts:311-325
Verification Hooks
Verification is a non-negotiable phase in the interaction lifecycle. Hooks ensure that agents run lsp_diagnostics and project-specific build/test commands before reporting a task as complete.
Sources: src/agents/hephaestus.ts:250-270, src/agents/prometheus/plan-template.ts:70-85
Summary
Interaction Hooks serve as the nervous system of Oh-My-OpenCode, providing the logic required to orchestrate multiple LLM models (Claude Opus, GPT-5.2, etc.) while enforcing strict architectural and safety boundaries. By managing the lifecycle from intent classification through to automated verification, these hooks ensure deterministic and high-quality software engineering outcomes.