@amaster.ai/pi-goal

A Pi extension that lets Pi keep working until a goal is met. You don't have to write the completion condition yourself — run /goal with no argument and the extension derives a measurable condition from the conversation, shows it to you for a quick confirmation, then keeps the agent working (re-checking after each run) until the condition holds.

Modeled on Claude Code's stop-condition mechanism, with a token/iteration budget backstop borrowed from Codex's goal mode.

How it works

1. Set a goal. Either give an explicit condition (/goal all tests pass and lint is clean) or let the extension derive one from the conversation (/goal with no argument).
2. Derived goals are confirmed in interactive (TUI) mode before they start, so a mis-derived goal can't run off on its own. Non-interactive modes skip the confirmation.
3. After each agent run (agent_end), a small evaluator model judges whether the condition is met:
   • Met → the goal is marked achieved and cleared. Pi stops.
   • Not yet → Pi is nudged to continue, told what still remains.
   • Impossible → Pi stops and tells you why.
4. Backstops. Continuation stops after maxIterations rounds or once an optional tokenBudget is exceeded, so a bad goal can't loop forever.

Goal state is session-scoped and held in memory (no cross-session persistence), matching Claude Code's behavior.

Pi lifecycle (how the engine hooks in)

The goal engine is driven by Pi's lifecycle events. For one pi -p '<prompt>' run (non-interactive), events fire in this order:

session_start                                 ← session-level, once
  │   pi-goal: load config, read the --goal flag
  ▼
[ per user prompt — the "agent-level" block below repeats ]
  │
  before_agent_start  { prompt, systemPrompt } ← carries the user's input for this turn, once per prompt
  │
  agent_start         { }
  │
  ├─ [ per turn, may repeat ]
  │    turn_start       { turnIndex }
  │    message_start    { message (user) }
  │    message_end      { message (user) }
  │    message_start    { message (assistant) }
  │    message_end      { message (assistant) }
  │    turn_end         { turnIndex, message, toolResults }
  │
  agent_end           { messages: [...] }       ← engine evaluates + stops/continues, once per prompt
  │   If a goal is active: build a transcript from `messages`, ask the
  │   evaluator ok / impossible / not-yet. Not-yet → sendUserMessage(continue)
  │   → triggers a new agent run (back to before_agent_start).
  │
  agent_settled       { }                        ← this prompt is fully done
  ▼
[ interactive: wait for next input · print mode: process exits here ]

session_shutdown                               ← on exit/switch; pi-goal clears state

Events pi-goal uses:

The interactive /goal command (no argument) derives from the session's own history, read via ctx.sessionManager — not a buffer this extension maintains.

Note on derivation timing: a condition can only be derived once there is conversation to derive from. session_start is too early (no transcript yet); before_agent_start is the first point that carries the user's prompt for the turn, so auto-derivation keys off it rather than firing at startup.

Usage

/goal <condition>   Set an explicit completion condition.
/goal               No active goal → derive one from the conversation (with confirmation).
                    Active goal → show its status.
/goal clear         Clear the active goal (also: stop, off, reset, none, cancel).

The slash command is for interactive (TUI) use; print mode can't dispatch it. For the CLI / non-interactive runs, use the --goal flag instead:

pi --goal '<condition>' -p '<prompt>'   Set an explicit goal, then run the prompt.
pi --goal '' -p '<prompt>'              Derive the goal from the prompt (at before_agent_start).

Configuration

Settings key: pi-goal (in ~/.pi/agent/settings.json, agent dir, or project .pi/settings.json). Project settings are loaded only after project trust is accepted. Environment-variable interpolation is available in user and agent settings, but not in project settings.

{
  "pi-goal": {
    "model": { "provider": "anthropic", "model": "claude-haiku-4-5-20251001" },
    "maxIterations": 10,
    "tokenBudget": 200000,
    "transcriptMaxChars": 8000,
    "requireConfirmForDerived": true
  }
}

Prefer a small, cheap model for model — the evaluator runs after every agent run.

Relationship to Claude Code / Codex

• Engine (from Claude Code): goal = a stop condition; Pi keeps going until an evaluator judges it met. Passive — it drives continuation off agent_end, not a background scheduler.
• Prompts (from Claude Code): the evaluator and activation prompts are adapted almost verbatim from Claude Code's own stop-hook prompts — including the quote-the-evidence requirement, the "insufficient evidence in transcript" fallback, the impossible-judgment discipline (the assistant's claim is evidence, not proof), and the truncated-transcript note.
• Auto-derivation: you don't have to phrase the condition; it's inferred and confirmed. (No CC analogue — CC always takes an explicit condition.)
• Budget backstop (from Codex): token + iteration limits prevent runaway loops.
• Not included: Codex's idle auto-resume, pause/resume dialogs, file-backed objectives, and cross-session persistence.

Transcript limits include role labels and separators. An oversized newest message retains its beginning and conclusion within the configured limit and is reported as partially omitted evidence. If evaluation reports insufficient evidence, continuation asks the agent to recover original files or recorded results before rerunning unavailable checks.

Failure diagnostics

Evaluator failures keep the goal active and make the unavailable evaluation visible; they do not trigger continuation or mark the goal complete. The nullable completion API is preserved, with an optional onError callback carrying safe diagnostics on completeOnce, EvaluateOptions, and DeriveOptions.