Hooks System

Relevant source files

The following files were used as context for generating this wiki page:

• src/hooks/AGENTS.md
• src/AGENTS.md
• src/plugin/AGENTS.md
• CONTRIBUTING.md
• src/agents/prometheus/gpt.ts

The Hooks System in OhMyOpenCode is a robust lifecycle management framework comprising 52 distinct hooks distributed across specialized modules. These hooks are integrated into the plugin's execution pipeline to handle session events, tool execution guards, message transformations, and task continuations. The system follows a modular "tier" architecture, allowing for clean separation of concerns and maintainable extensions of the agent's behavior.

The system is orchestrated through the createHooks function, which aggregates five tiers of hooks into the PluginInterface. This interface maps internal logic to OpenCode's specific lifecycle events, such as chat.message, tool.execute.before, and experimental.chat.messages.transform.

Sources: src/hooks/AGENTS.md:1-10, src/AGENTS.md:20-25, src/plugin/AGENTS.md:5-15

Architecture and Composition

The Hooks System is organized into a five-tier hierarchy. This structure ensures that different functional requirements—ranging from basic session management to complex background task orchestration—are handled by dedicated subsystems.

Hook Tiers

Tier	Category	Count	Focus Areas
Tier 1	Session	24	Context window monitoring, session recovery, and model fallbacks.
Tier 2	Tool Guard	14	Validation of tool inputs/outputs, AI slop prevention, and file access guards.
Tier 3	Transform	5	Message stream modifications, keyword detection, and prompt injection.
Tier 4	Continuation	7	"Boulder" mechanisms (todo enforcement) and background task orchestration.
Tier 5	Skill	2	Slash command detection and skill-specific reminders.

Sources: src/hooks/AGENTS.md:14-110, src/AGENTS.md:27-35

Data Flow and Registration

Hooks are implemented using a factory pattern: createXXXHook(deps) → HookFunction. These factories receive plugin dependencies (like managers or configuration) and return event handlers.

This diagram illustrates the initialization and routing of hooks from the central aggregator to specific OpenCode lifecycle events.
Sources: src/hooks/AGENTS.md:6-10, src/plugin/AGENTS.md:20-30

Key System Hooks

Several hooks provide complex logic essential for the stability and autonomy of the agents.

The "Boulder" Mechanism (Continuation)

The todo-continuation-enforcer is a critical Tier 4 hook that implements the "Boulder" mechanism. It monitors the session.idle event to determine if todos remain incomplete. If incomplete work is detected, it triggers a 2-second countdown toast and injects a continuation prompt to force the agent to keep working. It uses an exponential backoff strategy (starting at 30s) to prevent infinite loops during failures.

Sources: src/hooks/AGENTS.md:130-135

Context Recovery and Management

• anthropic-context-window-limit-recovery: A sophisticated recovery hook that activates on session.error. It employs multiple strategies—including truncation, compaction, and summarization—to resolve context limit issues.
• prometheus-md-only: A specialized guard for the Prometheus planner agent. It enforces a strict constraint where the agent can only write to .md files in specific directories (like .sisyphus/plans/), preventing accidental source code modification.

Sources: src/hooks/AGENTS.md:65-75, src/agents/prometheus/gpt.ts:40-50

Tool Execution Guards

The create-tool-guard-hooks.ts module handles pre- and post-execution logic for tools:

• write-existing-file-guard: Requires a Read operation before a Write to ensure the agent has current context.
• comment-checker: Blocks AI-generated comment patterns to prevent "AI slop" in the codebase.
• rules-injector: Evaluates conditions to inject specific instructions from AGENTS.md or system configs before a tool runs.

Sources: src/hooks/AGENTS.md:85-105, src/plugin/AGENTS.md:12-18

Integration with OpenCode Handlers

The system maps hooks to OpenCode-specific hooks through individual handler files in src/plugin/.

Handler File	OpenCode Hook Target	Primary Responsibility
chat-message.ts	chat.message	Session setup and keyword detection.
tool-execute-before.ts	tool.execute.before	Pre-tool guards and label truncation.
messages-transform.ts	experimental.chat.messages.transform	Context injection and thinking block validation.
event.ts	event	Handling session lifecycle (created, idle, error).

Sources: src/plugin/AGENTS.md:7-18

This sequence shows how hooks wrap around the tool execution lifecycle to provide safety and context.
Sources: src/plugin/AGENTS.md:7-18, src/hooks/AGENTS.md:80-110

Implementation Guide

To add a new hook to the system, developers must follow the standardized factory pattern and registration process:

1. Creation: Create a directory in src/hooks/{name}/ and implement createXXXHook(deps).
2. Registration: Export the factory from src/hooks/index.ts.
3. Tier Assignment: Add the hook to the relevant tier file (e.g., src/plugin/hooks/create-tool-guard-hooks.ts).
4. Schema: Update the HookNameSchema in the configuration system to allow the hook to be enabled/disabled via JSON config.

Sources: CONTRIBUTING.md:155-165, src/hooks/AGENTS.md:145-155

Code Example: Hook Factory

// src/hooks/my-hook/index.ts
import type { PluginInput } from "@opencode-ai/plugin";

export function createMyHook(input: PluginInput) {
  return {
    onSessionStart: async () => {
      // Logic executed when a session begins
    },
    onToolExecuteBefore: async (toolCall) => {
      // Guard logic before a tool runs
    }
  };
}

Sources: CONTRIBUTING.md:166-175

Conclusion

The Hooks System is the primary mechanism for extending agent capabilities and enforcing safety protocols in OhMyOpenCode. By leveraging 52 specialized hooks across five tiers, it ensures that every interaction—from user messages to file system writes—is validated, contextualized, and tracked for successful autonomous completion.