AGENTS.md

1<!-- Parent: ../AGENTS.md -->
2<!-- Generated: 2026-01-28 | Updated: 2026-01-31 -->
3 
4# hooks
5 
631 event-driven hooks that power execution modes and behaviors.
7 
8## Purpose
9 
10Hooks intercept Claude Code events to enable:
11- **Execution modes**: autopilot, ultrawork, ralph, ultrapilot, swarm, pipeline (mode-registry)
12- **Validation**: thinking blocks, empty messages, comments
13- **Recovery**: edit errors, session recovery, context window
14- **Enhancement**: rules injection, directory READMEs, notepad
15- **Detection**: keywords, think mode, slash commands
16 
17## Key Files
18 
19| File | Description |
20|------|-------------|
21| `index.ts` | Re-exports all hooks |
22| `bridge.ts` | Shell script entry point - `processHook()` routes events to handlers |
23 
24## Subdirectories
25 
26### Execution Mode Hooks
27 
28| Directory | Purpose | Trigger |
29|-----------|---------|---------|
30| `autopilot/` | Full autonomous execution | "autopilot", "build me" |
31| `ultrawork/` | Maximum parallel execution | "ulw", "ultrawork" |
32| `ralph/` | Persistence until verified | "ralph", "don't stop" |
33| `ultrapilot/` | Parallel autopilot with file ownership | "ultrapilot" |
34| `swarm/` | N coordinated agents with task claiming | "swarm N agents" |
35| `ultraqa/` | QA cycling until goal met | test failures |
36| `mode-registry/` | Tracks active execution mode  | internal |
37| `persistent-mode/` | Maintains mode state across sessions | internal |
38 
39### Validation Hooks
40 
41| Directory | Purpose |
42|-----------|---------|
43| `thinking-block-validator/` | Validates thinking blocks in responses |
44| `empty-message-sanitizer/` | Handles empty/whitespace messages |
45| `comment-checker/` | Checks code comment quality |
46| `permission-handler/` | Handles permission requests and validation |
47 
48### Recovery Hooks
49 
50| Directory | Purpose |
51|-----------|---------|
52| `recovery/` | Edit error recovery, session recovery |
53| `preemptive-compaction/` | Prevents context overflow |
54| `pre-compact/` | Pre-compaction processing |
55 
56### Enhancement Hooks
57 
58| Directory | Purpose |
59|-----------|---------|
60| `rules-injector/` | Injects matching rule files |
61| `directory-readme-injector/` | Injects directory READMEs |
62| `notepad/` | Persists notes for compaction resilience |
63| `learner/` | Skill extraction from conversations |
64| `agent-usage-reminder/` | Reminds about agent delegation |
65 
66### Detection Hooks
67 
68| Directory | Purpose |
69|-----------|---------|
70| `keyword-detector/` | Magic keyword detection |
71| `think-mode/` | Extended thinking detection |
72| `auto-slash-command/` | Slash command expansion |
73| `non-interactive-env/` | Non-interactive environment detection |
74| `plugin-patterns/` | Plugin pattern detection |
75 
76### Coordination Hooks
77 
78| Directory | Purpose |
79|-----------|---------|
80| `todo-continuation/` | Enforces task completion |
81| `omc-orchestrator/` | Orchestrator behavior |
82| `subagent-tracker/` | Tracks spawned sub-agents |
83| `session-end/` | Session termination handling |
84| `background-notification/` | Background task notifications |
85 
86### Setup Hooks
87 
88| Directory | Purpose |
89|-----------|---------|
90| `setup/` | Initial setup and configuration |
91 
92## For AI Agents
93 
94### Working In This Directory
95 
96#### Hook Structure
97 
98Each hook follows a standard pattern:
99```
100hook-name/
101├── index.ts     # Main hook implementation
102├── types.ts     # TypeScript interfaces
103├── constants.ts # Configuration constants
104└── *.ts         # Supporting modules
105```
106 
107#### When Adding a New Hook
108 
1091. Create hook directory with `index.ts`, `types.ts`, `constants.ts`
1102. Export from `index.ts` (hook re-exports)
1113. Register handler in `bridge.ts` if needed
1124. Update `docs/REFERENCE.md` (Hooks System section) with new hook entry
1135. If execution mode hook, also create `skills/*/SKILL.md` and `commands/*.md`
114 
115#### Hook Implementation
116 
117```typescript
118// index.ts
119export interface HookConfig {
120  enabled: boolean;
121  // hook-specific config
122}
123 
124export function createHook(config: HookConfig) {
125  return {
126    name: 'hook-name',
127    event: 'UserPromptSubmit',  // or 'Stop', 'PreToolUse', 'PostToolUse'
128    handler: async (context) => {
129      // Hook logic
130      return { modified: false };
131    }
132  };
133}
134```
135 
136#### Key Hooks Explained
137 
138**autopilot/** - Full autonomous execution:
139- Validates goals and creates plans
140- Manages execution state
141- Handles cancellation
142- Enforces completion
143 
144**ralph/** - Persistence mechanism:
145- Tracks progress via PRD
146- Spawns architect for verification
147- Loops until verified complete
148- Supports structured PRD format
149 
150**ultrapilot/** - Parallel autopilot:
151- Decomposes tasks into subtasks
152- Assigns file ownership to workers
153- Coordinates parallel execution
154- Integrates results
155 
156**swarm/** - Coordinated multi-agent:
157- SQLite-based task claiming
158- 5-minute timeout per task
159- Atomic claim/release
160- Clean completion detection
161 
162**learner/** - Skill extraction:
163- Detects skill patterns in conversation
164- Extracts to local skill files
165- Auto-invokes matching skills
166- Manages skill lifecycle
167 
168### Common Patterns
169 
170#### State Management
171 
172```typescript
173import { readState, writeState } from '../features/state-manager';
174 
175const state = readState('autopilot-state');
176state.phase = 'executing';
177writeState('autopilot-state', state);
178```
179 
180#### Event Handling
181 
182```typescript
183// UserPromptSubmit - Before prompt is sent
184// Stop - Before session ends
185// PreToolUse - Before tool execution
186// PostToolUse - After tool execution
187```
188 
189### Testing Requirements
190 
191- Test specific hooks with `npm test -- --grep "hook-name"`
192- Test execution modes end-to-end with skill invocation
193- Verify state persistence in `.omc/state/`
194- For security hooks, follow `templates/rules/security.md` checklist
195 
196## Dependencies
197 
198### Internal
199- `features/state-manager/` for state persistence
200- `features/verification/` for verification protocol
201- `agents/` for spawning sub-agents
202 
203### External
204| Package | Purpose |
205|---------|---------|
206| `better-sqlite3` | Swarm task coordination |
207| `fs`, `path` | State file operations |
208 
209## Hook Events
210 
211| Event | When Fired | Common Uses |
212|-------|------------|-------------|
213| `UserPromptSubmit` | Before prompt processing | Keyword detection, mode activation |
214| `Stop` | Before session ends | Continuation enforcement |
215| `PreToolUse` | Before tool execution | Permission validation |
216| `PostToolUse` | After tool execution | Error recovery, rules injection |
217 
218### Stop Hook Output Contract
219 
220The persistent-mode stop hook uses **soft enforcement**:
221 
222```typescript
223// Stop hook ALWAYS returns continue: true
224// Enforcement is via message injection, not blocking
225return {
226  continue: true,
227  message: result.message || undefined  // Injected into context
228};
229```
230 
231**Why soft enforcement**: Hard blocking (`continue: false`) would prevent context compaction and could deadlock Claude Code.
232 
233**Bypass conditions** (checked first, allow stopping):
2341. `context-limit` - Context window exhausted, must allow compaction
2352. `user-abort` - User explicitly requested stop
236 
237**Mode priority** (checked after bypass, may inject continuation message):
2381. Ralph (explicit persistence loop)
2392. Autopilot (full orchestration)
2403. Ultrapilot (parallel workers)
2414. Swarm (coordinated agents)
2425. Pipeline (sequential stages)
2436. UltraQA (test cycling)
2447. Ultrawork (parallel execution)
245 
246**Session isolation**: Hooks only enforce for matching `session_id`. Stale states (>2 hours) are ignored.
247 
248**Mode completion criteria**: Hook blocks while `state.active === true && state.session_id === currentSession && !isStaleState()`. Running `/cancel` sets `active: false` and removes state files.
249 
250## State Files
251 
252| Hook | State File |
253|------|------------|
254| autopilot | `.omc/state/autopilot-state.json` |
255| ultrapilot | `.omc/state/ultrapilot-state.json` |
256| ralph | `.omc/state/ralph-state.json` |
257| swarm | `.omc/state/swarm-tasks.db` (SQLite) |
258| learner | `~/.claude/local-skills/` |
259 
260<!-- MANUAL: -->
261