Lifecycle Hooks System

Relevant source files

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

• src/hooks/index.ts
• src/hooks/AGENTS.md
• src/create-hooks.ts
• src/agents/prometheus/identity-constraints.ts
• src/agents/prometheus/plan-generation.ts
• AGENTS.md

Introduction

The Lifecycle Hooks System is a core architectural component of the Oh My OpenCode plugin, providing over 40 distinct hooks that intercept and augment the behavior of the OpenCode environment. These hooks are designed to coordinate complex multi-model agent orchestration, handle state transitions, and enforce critical system constraints throughout the application's execution lifecycle.

The system acts as an integration layer between the OpenCode SDK and specialized features such as background agents, skill-based workflows, and automated planning. By leveraging these hooks, the project achieves "oh-my-zsh" style extensibility for AI-assisted coding, allowing for automated task continuation, safety checks, and parallel execution management.

Sources: AGENTS.md, src/hooks/AGENTS.md

Architecture and Coordination

The system is managed through a central coordination layer that initializes and registers various categories of hooks. This coordination ensures that different functional domains—such as core plugin logic, task continuation, and skill-specific triggers—interact predictably within the OpenCode event loop.

Hook Categories

Hooks are organized by their functional responsibility within the system:

Hook Category	Responsibility
Core Hooks	Basic plugin initialization and state management.
Continuation Hooks	Tracking and resuming TODO/Task states across sessions.
Skill Hooks	Triggering specialized logic (e.g., git-master, playwright) based on user intent.
Atlas Orchestrator	High-level coordination for multi-agent task execution.
Prometheus Guards	Enforcing identity constraints and planning protocols.

Sources: src/create-hooks.ts, AGENTS.md

Execution Flow

The lifecycle hooks intercept specific events provided by the OpenCode plugin API. For example, the prometheus-md-only hook acts as a guard during file write operations to enforce strict markdown-only access for planning agents.

The diagram shows the standard flow of a request passing through the hook system, from initial intent classification to constraint enforcement and tool execution.
Sources: src/agents/prometheus/identity-constraints.ts:80-95, src/agents/prometheus/plan-generation.ts:15-35

Specialized Hooks and Constraints

Planning Protocol Enforcement

The Prometheus agent utilizes specific hooks to enforce the "Planning ≠ Doing" constraint. These hooks ensure that the agent interprets implementation requests (e.g., "build X") exclusively as requests to "create a work plan for X."

• Markdown-Only Enforcement: A specific hook (prometheus-md-only) blocks any attempts to write to non-markdown files, ensuring the planning agent remains isolated from the source code.
• Path Enforcement: Hooks restrict file writes to allowed directories such as .sisyphus/plans/ and .sisyphus/drafts/.

Sources: src/agents/prometheus/identity-constraints.ts:80-110

Task and TODO Continuation

Continuation hooks are responsible for the persistence and recovery of task states. They ensure that if an agent session is interrupted, the "execution backbone" (tasks/todos) remains intact for the next turn.

This diagram illustrates how continuation hooks facilitate state recovery by loading incomplete tasks at the start of a new session.
Sources: src/create-hooks.ts, src/agents/sisyphus.ts:35-60

Implementation Patterns

Hook implementation follows a factory pattern where a createXXXHook() function receives the PluginInput and returns a set of event handlers.

Key Event Handlers

The system leverages various SDK events to implement logic:

• onSessionStart: Used to initialize state, load task contexts, and trigger initial research via background agents.
• preToolUse: A critical "Intent Gate" where hooks check for skill triggers or enforce identity blocks before a tool is actually executed.
• onSessionEnd: Used for cleanup, such as canceling background tasks and updating persistent task storage.

Sources: src/hooks/index.ts, sisyphus-prompt.md:350-365

// Example of a hook implementation structure
// Sources: [src/hooks/index.ts](https://github.com/marlon-costa-dc/oh-my-opencode/blob/781e389885ff76422c6495fefa21337ad99a6acf/src/hooks/index.ts)
export function createMyHook(input: PluginInput) {
  return {
    onSessionStart: async () => {
      // Hook logic for session initialization
    },
    preToolUse: async (toolCall) => {
      // Logic to intercept tool calls (e.g., MD-only enforcement)
    }
  };
}

Summary

The Lifecycle Hooks System is the engine of the Oh My OpenCode plugin, providing the necessary infrastructure for multi-agent coordination and safe execution. By segregating responsibilities into core, continuation, and skill hooks, the system maintains a high degree of extensibility while strictly enforcing architectural boundaries, such as the separation of planning and implementation phases.