Goals in chat#

A Goal keeps an objective active across ordinary chat turns. The current agent does the work with the conversation's tools, model, permissions and history. At the end of a successful turn, the runtime continues an active Goal with another ordinary chat turn. Completion candidates receive a separate read-only verification turn; ordinary working turns do not each run a judge. There is no nested working agent.

Start and plan#

Enter /goal <objective>, or use Programs → Workflow → goal → Use. The form starts a chat Goal; it does not execute the Python Workflow. You can also explicitly ask the agent to create a Goal.

The agent uses todo_create, todo_update and todo_list to maintain a plan for multi-step work. New items created during Goal work are associated with the Goal and its revision. The Goal details refresh progress after each successful todo change and reconcile it again when a turn ends. Progress notification failures do not undo saved todos. The objective remains independent of the plan: checking every item does not by itself prove completion.

The agent must check current evidence against every requirement before calling update_goal(status="complete"). This short operation submits a candidate; it does not mark the Goal achieved. Unfinished associated todos prevent submission. A fully completed todo plan also triggers verification once per changed plan. A simple objective does not require an artificial todo list.

The badge displays Verifying while a distinct ordinary chat turn assesses the original objective and each todo requirement. Only trusted built-in inspection tools are available, under normal permissions. Shell commands, writes and Goal mutation tools are not verification tools. If tests or external queries are needed, the verifier returns missing evidence to the working agent, whose normal permissions and budgets still apply.

The verifier must provide a per-requirement assessment and recorded evidence references. Successful reads record file fingerprints; saved conversation evidence and the verifier's own result are versioned by digest. The runtime rechecks requirements, user controls, todo state, unfinished executions, unknown effects and referenced evidence before saving achieved. Pause, edit, cancellation, new user instructions or changed evidence prevent stale success. Missing evidence returns to ordinary work; a failed execution remains recoverable. Semantic verification is an independent model judgment, not a guarantee of perfect results. Completion describes the verification time and does not silently start ongoing monitoring.

Control execution#

Internal verification turns are not rendered as assistant replies. Starting, running, pausing and verifying a Goal do not add transcript cards. When a Goal ends, one compact card remains at its ending position. Click it to open the existing Goal details dialog with that Goal's saved result, progress and usage. Historical details are read-only and remain associated with the original Goal after a new Goal starts. Ordinary agent replies and original evidence remain unchanged.

The Goal details retain the objective, status, usage and progress after page reload. When there are no todos, the badge and details omit todo progress without a placeholder; the Goal status remains visible. Use the existing chat input to add instructions, following its normal queue or steering mode.

• /goal: read the current state.
• /goal pause: save a pause and request cancellation of the current execution.
• /goal resume: continue a paused Goal with cumulative usage.
• /goal verify: independently verify the latest finished work without marking it achieved directly.
• /goal edit <objective>: save a new revision and pause; resume explicitly when ready.
• /goal clear: cancel the Goal.
• /goal budget max_turns=10 max_tokens=10000: change limits; zero removes a limit.

Goals have no round limit by default. Only an explicit positive goal.max_turns or start-time round budget sets a cap; reaching it is not completion. The progress badge shows todo completion, not execution rounds. Existing Goals retain their saved budgets: use /goal budget max_turns=0 to remove an old round cap without resetting work or usage. Explicit token, active-time and cost limits use cumulative usage. A depleted budget must be increased or removed before resuming. Waiting time is excluded from active time. Automatic continuation does not expand tool permissions.

A failed or cancelled execution stops automatic continuation. Worker restart does not itself pause a chat Goal: compatible checkpoints resume under the automatic restart policy, and a successful turn completed during shutdown keeps a durable continuation notification. An abandoned ordinary chat with unknown external outcomes can continue in a distinct, restricted turn without replaying its old tool calls. User pause, cancellation, exhausted budgets and explicit restart limits still prevent automatic work. Legacy recoverable pauses and Goals missing saved continuation provenance require explicit Resume. General external-event wakeups remain a recovery limitation. A wait or unresolved execution is not evidence of Goal completion.

The state tools are short operations: create_goal, get_goal, and update_goal. They do not perform the task. The agent may mark blocked only after the same verified blocker recurs for at least three consecutive Goal turns with no independent work remaining. The runtime enforces the minimum turn count; the agent is responsible for verifying that it is the same blocker.

Recovery and metering#

Goal details use the backend's current action eligibility. Disabled Resume or Verify actions explain the unmet prerequisite; Refresh status retries a failed read without discarding your objective or draft. End remains available to stop the Goal intent even if an old operation's outcome is unknown. Unresolved operations show their saved identifiers, tool names, timestamps and status. Inspect execution opens that exact execution, including pending approvals and questions, rather than an unrelated activity selection.

Verify starts the same independent ordinary verification turn used for automatic candidates. It requires finished work, completed associated todos, available budget and no unresolved relevant work. Goal-owned background processes that are still running or have unknown outcomes prevent verification; unrelated resources do not. Pause, cancellation, changed versions and duplicate requests cannot bypass these prerequisites.

Active time retains already observed work across restart and excludes offline intervals. After abrupt worker loss, the last durable heartbeat provides a lower bound; the unobserved final interval is shown as unknown, not zero. Late usage receipts do not restart a paused timer. An explicit active-time ceiling blocks further work if that unknown interval prevents checking the limit; removing the optional ceiling allows continuation. No default time or round ceiling is added.

Goal distinguishes a terminal execution from permission to start a new chat turn. Once an ordinary chat has no owner, active descendants or pending questions, Resume can close its interrupted frame and start a restricted inspection turn. Unknown effects remain unknown; neither Resume nor a prior unconfirmed stop claims that an external operation was cancelled. A new admission has a durable identity, so a crash between admission and saving the Goal cannot create duplicate turns. Incompatible checkpoints use a new chat turn; temporary activation or credential errors do not authorize that fallback. Provider-only interrupted background Jobs retain their immutable input and resource admission. Child executions with unresolved effects still require inspection rather than automatic replay. Todo completion is not objective verification.

Provider requests repair incomplete tool-call history without rewriting saved records. Missing outputs receive an explicit unknown-outcome error placeholder, including a call at the end of history. Saved real outputs take precedence over placeholders; duplicate outputs are collapsed and paired with their call. Interrupted assistant text remains labelled as interrupted. Unpaired tool-result protocol entries remain in saved history but are omitted from the provider request. This repair does not prove that an operation failed, authorize a retry, or remove execution recovery restrictions.

When an ownerless interrupted execution still has an unknown external outcome, new operations in that conversation require exact, one-shot approval, including in bypass mode or with an existing allow rule. Actual built-in file inspection tools (read, grep, glob, list) can inspect state under their normal permissions; custom tools are not trusted solely because they use those names. The approval identifies prior uncertain operations and the new operation. Changed uncertainty requires a new approval; approval never marks the prior operation successful or failed. Non-interactive work cannot approve a new side effect. This guard also applies to restarted chat turns.

Chat provider requests capture their Goal identity, revision and price before dispatch. Their terminal usage receipts update that original Goal even after pause or edit; replacing the Goal does not transfer old charges to the new objective. Duplicate receipt delivery does not add usage twice. A started request without a usage receipt remains unknown, not free. The details show known subtotals alongside unknown request counts. Receipt projection can be rebuilt from the ledger after restart without repeating the provider request.

Older cursor-based totals are retained as a legacy subtotal on the next attributed request; past requests are not assigned guessed Goal identities. Metering failures display unknown rather than zero. Partial streaming counters are cumulative lower bounds, not additional charges; repeated snapshots are not added together. A final receipt replaces the partial subtotal.

Background Jobs admitted by an active Goal inherit its durable identity, including descendants and cross-session calls. An unrelated Goal in the destination session receives no charges. Existing Jobs without saved attribution remain unassigned. Goal and Job reservations start and settle in the same accounting transaction; a saved receipt can finish settlement after restart without repeating the request. Missing token or price information retains the corresponding reserved exposure.

Limits remain optional. Explicit token or cost limits reserve conservative exposure before credentials or provider calls, count parallel requests against the same Goal, and recheck at dispatch. Token limits can reduce the provider's output cap. Requests with an unsupported bound, unknown price or unpriced service tier cannot bypass a hard limit; the Goal pauses or reports budget exhaustion. An expired reservation that never started cannot dispatch; a started request never becomes free merely because time passes. These bounds require audited provider adapters and do not promise control over unaudited external billing behavior.

Python Workflow compatibility#

Direct Python and composed Workflow calls to goal() retain their existing work/refinement/judge contract. This compatibility path is distinct from chat Goals. It accepts context_mode, work/judge model settings and execution limits. Chat mode uses the conversation's work model and does not use those separate role settings.

The chat form preserves explicit round, token, active-time and cost limits. It rejects separate Workflow role options and isolated context; change the conversation's settings for chat work instead. In the Rich REPL, /goal starts a canonical chat execution and prints its execution ID.

See the engineering design for the migration and implementation evidence.