AGENTS.md

1# src/hooks/atlas/ — Master Boulder Orchestrator
2 
3**Generated:** 2026-05-15
4 
5## OVERVIEW
6 
717 files (~1976 LOC). The `atlasHook` — Continuation Tier hook that monitors session.idle events and forces continuation when boulder sessions (ralph-loop, task-spawned agents) have incomplete work. Also enforces write/edit policies for subagent sessions.
8 
9## WHAT ATLAS DOES
10 
11Atlas is the "keeper of sessions" — it tracks every session and decides:
121. Should this session be forced to continue? (if boulder session with incomplete todos)
132. Should write/edit be blocked? (policy enforcement for certain session types)
143. Should a verification reminder be injected? (after tool execution)
15 
16## DECISION GATE (session.idle)
17 
18```
19session.idle event
20  → Is this a boulder/ralph/atlas session? (session-last-agent.ts)
21  → Is there an abort signal? (is-abort-error.ts)
22  → Failure count < max? (state.promptFailureCount)
23  → No running background tasks?
24  → Agent matches expected? (recent-model-resolver.ts)
25  → Plan complete? (todo status)
26  → Cooldown passed? (5s between injections)
27  → Inject continuation prompt (boulder-continuation-injector.ts)
28```
29 
30## KEY FILES
31 
32| File | Purpose |
33|------|---------|
34| `atlas-hook.ts` | `createAtlasHook()` — composes event + tool handlers, maintains session state |
35| `event-handler.ts` | `createAtlasEventHandler()` — decision gate for session.idle events |
36| `boulder-continuation-injector.ts` | Build + inject continuation prompt into session |
37| `system-reminder-templates.ts` | Templates for continuation reminder messages |
38| `tool-execute-before.ts` | Block write/edit based on session policy |
39| `tool-execute-after.ts` | Inject verification reminders post-tool |
40| `write-edit-tool-policy.ts` | Policy: which sessions can write/edit? |
41| `verification-reminders.ts` | Reminder content for verifying work |
42| `session-last-agent.ts` | Determine which agent owns the session |
43| `recent-model-resolver.ts` | Resolve model used in recent messages |
44| `subagent-session-id.ts` | Detect if session is a subagent session |
45| `omo-path.ts` | Resolve `.omo/` directory path |
46| `is-abort-error.ts` | Detect abort signals in session output |
47| `types.ts` | `SessionState`, `AtlasHookOptions`, `AtlasContext` |
48 
49## STATE PER SESSION
50 
51```typescript
52interface SessionState {
53  promptFailureCount: number  // Increments on failed continuations
54  // Resets on successful continuation
55}
56```
57 
58Max consecutive failures before 5min pause: 5 (exponential backoff in todo-continuation-enforcer).
59 
60## RELATIONSHIP TO OTHER HOOKS
61 
62- **atlasHook** (Continuation Tier): Master orchestrator, handles boulder sessions
63- **todoContinuationEnforcer** (Continuation Tier): "Boulder" mechanism for main Sisyphus sessions
64- Both inject into session.idle but serve different session types
65