Files

T

YeonGyu-Kim 9f6d0d2281 docs(agents-md): refresh hierarchical knowledge base for v4.1.2

- Bump root AGENTS.md header: 2026-05-14 → 2026-05-15, commit 5ffbe0e24 → 53a740636, release v4.1.1 → v4.1.2
- Update file counts: 2034 (1337+697) → 2041 (1340+701), LOC ~292k → ~294k
- Fix STRUCTURE: openclaw lives at src/openclaw/ (not src/features/); list more accurate feature modules in the parenthetical
- Clarify interactive_bash gate: tmux binary on PATH via isInteractiveBashEnabled() (not 'tmux enabled')
- Fix docs/reference/features.md hook counts: Tool Guard 14→16, Total base 52→54, total with team-mode 59→61
- Bump 'Generated' date on all 43 subdir AGENTS.md files to 2026-05-15
- Preserve promptAsync injection cautions verbatim (per request)

2026-05-15 13:48:11 +09:00

2.8 KiB

Raw Blame History

src/hooks/atlas/ — Master Boulder Orchestrator

Generated: 2026-05-15

OVERVIEW

17 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.

WHAT ATLAS DOES

Atlas is the "keeper of sessions" — it tracks every session and decides:

Should this session be forced to continue? (if boulder session with incomplete todos)
Should write/edit be blocked? (policy enforcement for certain session types)
Should a verification reminder be injected? (after tool execution)

DECISION GATE (session.idle)

session.idle event
  → Is this a boulder/ralph/atlas session? (session-last-agent.ts)
  → Is there an abort signal? (is-abort-error.ts)
  → Failure count < max? (state.promptFailureCount)
  → No running background tasks?
  → Agent matches expected? (recent-model-resolver.ts)
  → Plan complete? (todo status)
  → Cooldown passed? (5s between injections)
  → Inject continuation prompt (boulder-continuation-injector.ts)

KEY FILES

File	Purpose
`atlas-hook.ts`	`createAtlasHook()` — composes event + tool handlers, maintains session state
`event-handler.ts`	`createAtlasEventHandler()` — decision gate for session.idle events
`boulder-continuation-injector.ts`	Build + inject continuation prompt into session
`system-reminder-templates.ts`	Templates for continuation reminder messages
`tool-execute-before.ts`	Block write/edit based on session policy
`tool-execute-after.ts`	Inject verification reminders post-tool
`write-edit-tool-policy.ts`	Policy: which sessions can write/edit?
`verification-reminders.ts`	Reminder content for verifying work
`session-last-agent.ts`	Determine which agent owns the session
`recent-model-resolver.ts`	Resolve model used in recent messages
`subagent-session-id.ts`	Detect if session is a subagent session
`sisyphus-path.ts`	Resolve `.sisyphus/` directory path
`is-abort-error.ts`	Detect abort signals in session output
`types.ts`	`SessionState`, `AtlasHookOptions`, `AtlasContext`

STATE PER SESSION

interface SessionState {
  promptFailureCount: number  // Increments on failed continuations
  // Resets on successful continuation
}

Max consecutive failures before 5min pause: 5 (exponential backoff in todo-continuation-enforcer).

RELATIONSHIP TO OTHER HOOKS

atlasHook (Continuation Tier): Master orchestrator, handles boulder sessions
todoContinuationEnforcer (Continuation Tier): "Boulder" mechanism for main Sisyphus sessions
Both inject into session.idle but serve different session types

2.8 KiB Raw Blame History