Goal System

Goals are persistent objectives that survive across sessions. They give the agent long-term direction, require evidence-backed checkpoints, and can trigger bounded continuation runs with budget tracking.

Agent pause gate

AI-initiated goal pause --agent --audit uses a two-tap audited gate. After the first audited pause attempt, the goal stays active but exposes derived pauseGate: { armed: true, reason: "pause_gate_pending" } on status/API surfaces. While armed, automatic goal continuation is suppressed (goal_pause_gate_pending SSE event). A productive checkpoint clears the gate; a second audited pause fully pauses the goal.

Goal Lifecycle

A goal moves through these states: plan-mode pending, active, paused, done, or cancelled. Goal state is durable -- restarting the server preserves it.

CLI Commands

# Set a new goal
jaw goal set "Migrate the auth module to JWT tokens"

# Start from a hint, then refine before checkpoints are accepted
jaw goal plan "Make the desktop release self-contained"
jaw goal refine "Ship self-contained Electron desktop artifacts with sidecar and CI evidence"

# Check goal status
jaw goal status

# Record evidence-backed progress
jaw goal update "Sidecar bundle implemented" --evidence "npm run sidecar:bundle passed"

# Pause or resume the current goal
jaw goal pause
jaw goal resume

# Mark goal as done
jaw goal done

# Cancel or reset goal state
jaw goal cancel
jaw goal reset

Slash Commands

Goal Run (Auto-Continuation)

The /goal run start command begins a bounded auto-continuation session. The agent works toward the goal objective, automatically continuing after each response until the goal is marked done or the run is stopped.

Goal Mode Rules

These rules are delivered to the agent exclusively by the goal-continuation prompt (src/goal/heartbeat.ts) on every goal-active turn. The boss system prompt keeps only the goal CLI command list plus a pointer (single-owner design, 2026-06-10 slim).

• Goal is the supreme rule. When a goal is active, it supersedes PABCD phase gates. The agent self-advances through all phases without waiting for user approval.
• Plan-mode guard. /goal plan and /goalplan store the user's hint as planHint; the agent must refine it into a specific objective before checkpoint updates count.
• Completion audit. Before /goal done, the agent must perform a requirement-by-requirement verification. Uncertain or indirect evidence is treated as "not achieved."
• Blocked audit. The agent can only declare "blocked" after the same blocking condition repeats for 3 consecutive goal turns. Hard/slow/uncertain work is never a valid reason to block.
• Evidence bundle. Development goals need documentation evidence, implementation evidence, and fresh verification output before completion.

API Endpoints

Runtime Events

Goal lifecycle changes emit runtime events. The Web UI receives them through GET /api/events SSE first, with WebSocket fallback on legacy servers:

• goal_done -- goal completed
• goal_done_rejected -- completion rejected because evidence is missing
• goal_cancel -- goal cancelled
• goal_continuation -- auto-continuation triggered
• goal_continuation_failed -- continuation attempt failed
• goal_continuation_limit -- continuation budget reached
• goal_pause_detected -- two-step pause gate detected
• goal_pause_gate_pending -- first audited pause armed; automatic goal continuation suppressed until productive checkpoint or second pause

Goal + PABCD Integration

Goals work alongside PABCD orchestration, but an active goal has priority over phase gates. In goal mode, PABCD transition commands still record state, but the agent does not stop at P/A/B/C/D boundaries unless it needs a real external decision or must pause after an independent blocked audit.