tags:

• domain/skills
• artifact/workflow
• source/hooks

hooks

31 event-driven hooks that power execution modes and behaviors.

Purpose

Hooks intercept Claude Code events to enable:

• Execution modes: autopilot, ultrawork, ralph, ultrapilot, swarm, pipeline (mode-registry)
• Validation: thinking blocks, empty messages, comments
• Recovery: edit errors, session recovery, context window
• Enhancement: rules injection, directory READMEs, notepad
• Detection: keywords, think mode, slash commands

Key Files

Subdirectories

Execution Mode Hooks

Validation Hooks

Recovery Hooks

Enhancement Hooks

Detection Hooks

Coordination Hooks

Setup Hooks

For AI Agents

Working In This Directory

Hook Structure

Each hook follows a standard pattern:

hook-name/
├── index.ts     # Main hook implementation
├── types.ts     # TypeScript interfaces
├── constants.ts # Configuration constants
└── *.ts         # Supporting modules

When Adding a New Hook

1. Create hook directory with index.ts, types.ts, constants.ts
2. Export from index.ts (hook re-exports)
3. Register handler in bridge.ts if needed
4. Update docs/REFERENCE.md (Hooks System section) with new hook entry
5. If execution mode hook, also create skills/*/SKILL.md and commands/*.md

Hook Implementation

// index.ts
export interface HookConfig {
  enabled: boolean;
  // hook-specific config
}

export function createHook(config: HookConfig) {
  return {
    name: 'hook-name',
    event: 'UserPromptSubmit',  // or 'Stop', 'PreToolUse', 'PostToolUse'
    handler: async (context) => {
      // Hook logic
      return { modified: false };
    }
  };
}

Key Hooks Explained

autopilot/ - Full autonomous execution:

• Validates goals and creates plans
• Manages execution state
• Handles cancellation
• Enforces completion

ralph/ - Persistence mechanism:

• Tracks progress via PRD
• Spawns architect for verification
• Loops until verified complete
• Supports structured PRD format

ultrapilot/ - Parallel autopilot:

• Decomposes tasks into subtasks
• Assigns file ownership to workers
• Coordinates parallel execution
• Integrates results

swarm/ - Coordinated multi-agent:

• SQLite-based task claiming
• 5-minute timeout per task
• Atomic claim/release
• Clean completion detection

learner/ - Skill extraction:

• Detects skill patterns in conversation
• Extracts to local skill files
• Auto-invokes matching skills
• Manages skill lifecycle

Common Patterns

State Management

import { readState, writeState } from '../features/state-manager';

const state = readState('autopilot-state');
state.phase = 'executing';
writeState('autopilot-state', state);

Event Handling

// UserPromptSubmit - Before prompt is sent
// Stop - Before session ends
// PreToolUse - Before tool execution
// PostToolUse - After tool execution

Testing Requirements

• Test specific hooks with npm test -- --grep "hook-name"
• Test execution modes end-to-end with skill invocation
• Verify state persistence in .omc/state/
• For security hooks, follow templates/rules/security.md checklist

Dependencies

Internal

• features/state-manager/ for state persistence
• features/verification/ for verification protocol
• agents/ for spawning sub-agents

External

Hook Events

Stop Hook Output Contract

The persistent-mode stop hook uses soft enforcement:

// Stop hook ALWAYS returns continue: true
// Enforcement is via message injection, not blocking
return {
  continue: true,
  message: result.message || undefined  // Injected into context
};

Why soft enforcement: Hard blocking (continue: false) would prevent context compaction and could deadlock Claude Code.

Bypass conditions (checked first, allow stopping):

1. context-limit - Context window exhausted, must allow compaction
2. user-abort - User explicitly requested stop

Mode priority (checked after bypass, may inject continuation message):

1. Ralph (explicit persistence loop)
2. Autopilot (full orchestration)
3. Ultrapilot (parallel workers)
4. Swarm (coordinated agents)
5. Pipeline (sequential stages)
6. UltraQA (test cycling)
7. Ultrawork (parallel execution)

Session isolation: Hooks only enforce for matching session_id. Stale states (>2 hours) are ignored.

Mode completion criteria: Hook blocks while state.active === true && state.session_id === currentSession && !isStaleState(). Running /cancel sets active: false and removes state files.

State Files

🔗 Связи

• [[MOC - System]] — hooks
• [[000 - Map of Maps]] — Map of Maps