# Goal Extension

Long-running task management for Catui. Set a goal with `/goal <objective>` and the
agent will auto-continue working on it across turns until the objective is achieved,
the token budget runs out, or you pause/clear it.

This extension mirrors the Codex `/goal` command semantics: a per-thread goal, persisted
to disk, with idle-continuation prompts, token accounting, and budget enforcement.

## Usage

```
/goal                  Show current goal summary menu
/goal <objective>      Set or replace the goal
/goal clear            Clear the goal
/goal edit             Open the editor to change the objective
/goal pause            Pause auto-continuation
/goal resume           Resume auto-continuation
/goal help             Show usage help
```

## LLM Tools

The extension registers three LLM-facing tools:

| Tool | Purpose | Who can call |
|------|---------|--------------|
| `GetGoal` | Read the current goal | LLM |
| `CreateGoal` | Create a new goal (only when the user explicitly asks) | LLM |
| `UpdateGoal` | Mark the goal `complete` or `blocked` | LLM |

The LLM is only allowed to set the goal's status to `complete` or `blocked`. Pause /
resume / budget limits are user-driven and happen exclusively through `/goal`.

## Lifecycle

The extension subscribes to `turn_start`, `turn_end`, `message_end`, `tool_execution_end`,
and `agent_end` to track token usage and time per turn. When a turn ends with an
`active` goal, the extension injects a follow-up user message containing the
continuation prompt so the agent keeps working on the objective.

When a turn causes the goal to cross its token budget, the extension injects a
budget-limit steering prompt and marks the goal `budget_limited`. Once budget-limited,
auto-continuation stops and the goal is terminal.

## Persistence

Goals are stored as JSON files under `<agentDir>/goals/<threadId>.json`. They survive
session restarts and are keyed by the active session ID.

## Status

`Status: active` shows in the footer while a goal is running.

## Architecture

| File | Responsibility |
|------|----------------|
| `goal-types.ts` | `ThreadGoalStatus`, `ThreadGoal`, helper predicates |
| `goal-store.ts` | Atomic JSON-file persistence (replace / insert / update / delete / account_usage) |
| `goal-format.ts` | Time/token formatting, summary lines, status indicator, validators |
| `goal-prompts.ts` | Continuation / budget-limit / objective-updated prompt templates |
| `goal-controller.ts` | Per-thread runtime: mutex, turn accounting, idle continuation |
| `goal-tools.ts` | `GetGoal`, `CreateGoal`, `UpdateGoal` LLM tool definitions |
| `goal-parser.ts` | `/goal` slash-command argument parsing |
| `goal-command.ts` | `/goal` slash-command handler (UI + controller dispatch) |
| `index.ts` | Extension entry: tools, command, lifecycle hooks, status indicator |