AGENTS.md

1# src/hooks/goal/ -- Persistent Per-Session Goal
2 
3**Generated:** 2026-07-17
4 
5## OVERVIEW
6 
715 files (8 impl + 7 tests). The `goal` Session Tier hook (event-based). Replaces the user-facing `ralph-loop` wiring (PR #6184 "goal-replaces-ralph"): `ralphLoop` was removed from `HookNameSchema` and `create-session-hooks.ts`, and `ralph_loop` is now a deprecated config passthrough. The `ralph-loop/` dir + `createRalphLoopHook` factory remain for migration only.
8 
9A goal is a per-session persistent objective. While `status: active`, each `session.idle` re-injects a continuation prompt that drives the agent toward the objective and forbids marking complete without a completion audit. The continuation prompt surfaces `tokensUsed` / `timeUsedSeconds` from the goal record.
10 
11Opt-in: requires `goal.enabled: true` (config) AND the `goal` hook enabled. Wired in [`create-session-hooks.ts`](../../plugin/hooks/create-session-hooks.ts); event dispatched via `event-hook-dispatcher.ts`; tools registered in `tool-registry-core-tools.ts`; `/goal` command parsed in `command-execute-before.ts` and `chat-message/loop-commands.ts`.
12 
13## KEY FILES
14 
15| File | Purpose |
16|------|---------|
17| `index.ts` | `createGoalHook(ctx, options) -> GoalHook`. `event` handler for `session.idle` (continuation) and `session.deleted` (clear). Re-entry guarded by `inFlightContinuations` Set |
18| `controller.ts` | `createGoalController({projectDir})`. CRUD: set/get/pause/resume/clear/markComplete + `accountUsage` (token/time accrual, controller-only) + `updateTui`. Writes TUI mirror |
19| `store.ts` | File persistence. Atomic write (tmp + rename). `readGoal` returns null on ENOENT or parse/schema failure. `STORE_VERSION = 1` |
20| `types.ts` | Zod schemas: `GoalSchema`, `GoalStatusSchema` (`active|paused|complete`), `GoalFileSchema` (v1), tool snapshot/response schemas |
21| `prompt.ts` | `buildContinuationPrompt` / `buildResumePrompt`. Objective wrapped in `<untrusted_objective>` (XML-escaped). Enforces completion audit before `update_goal status:complete` |
22| `tools.ts` | `createGoalTools` -> `create_goal`, `update_goal`, `get_goal` ToolDefinitions. `session_id` optional (defaults to current session) |
23| `validation.ts` | `validateObjective`: trim, non-empty, max 2000 chars. `InvalidObjectiveError` |
24| `command-arguments.ts` | `parseGoalCommand` -> `show | clear | setStatus(active|paused) | setObjective` |
25 
26## STATE
27 
28- Primary: `.omo/goal/{encodeURIComponent(sessionID)}.json` (atomic).
29- TUI mirror: `.omo/ulw-loop/{sessionID}/goals.json` (`TuiLoopSnapshot` v1), rewritten on every mutation.
30- `session.deleted` clears the goal file.
31 
32## INTERFACE
33 
34```typescript
35interface GoalHook {
36  setGoal(sessionID, objective): Goal
37  getGoal(sessionID): Goal | null
38  pauseGoal(sessionID): Goal | null
39  resumeGoal(sessionID): Goal | null
40  clearGoal(sessionID): boolean
41  markComplete(sessionID): Goal | null
42  event(input): Promise<void>   // session.idle + session.deleted
43}
44```
45 
46## CONTINUATION DISPATCH
47 
48`session.idle` -> `buildContinuationPrompt(goal)` -> `dispatchInternalPrompt` (async gate, `settleMs: 150`, `queueBehavior: "defer"`, source `goal:idle-continuation`). Dispatch failures log via `console.warn` only; the prompt may still be accepted by another route. `inFlightContinuations` prevents re-entrant dispatches per session.
49 
50## NOTES
51 
52- `default_mode.goal: true` auto-creates a goal from the first main-session message (`chat-message/loop-commands.ts`).
53- `accountUsage` accrues only while `status === active`; paused goals keep their accumulated totals.
54- Ralph Loop behavioral parity preserved via `default_max_iterations` (default 100).
55