Operate a Goal from a session

A conversational Goal attaches a durable, judged convergence Run to one existing session. Start it through the session prompt surface, keep working in the same thread, and inspect the same Run through Web, CLI, HTTP/UDS, or native tools. The daemon remains the source of truth; closing a browser or disconnecting the prompt response does not cancel a committed Goal.

Start and inspect

Send a free-form objective to an active session:

compozy session prompt sess_123 '/goal Ship the requested change and keep make verify green.' -o json

The command returns a structured result. A successful start has outcome: started, the canonical snapshot, message_id, and idempotency_key. HTTP and UDS return the same Goal result inside the prompt envelope, which also reports replayed. Retrying the exact request with both original identities returns the stored result and preserves its original HTTP status without running the Goal command again. If the session already owns a visible Goal, CompozyOS returns goal_replace_required with the current snapshot instead of overwriting it. See Session events and safe retries.

Read the current Goal through any of these public surfaces:

• Web session header — status, turn meter, context state, Run link, active binding link, and valid controls.
• compozy session prompt <id> '/goal status' -o json — structured session command result.
• compozy__goal_get — session-scoped native read, including terminal state until clear.
• GET /api/workspaces/{workspace_id}/sessions/{session_id}/goal — canonical snapshot or { "goal": null }.

The snapshot includes run_id, node_id, objective, origin and bound session IDs, Goal and Run status, cause, turn counts, contract summary, latest nullable verdict, and context telemetry. A terminal newest Goal remains visible after restart until it is explicitly cleared. Clear returns the session projection to { "goal": null }; it does not delete the Run or expose an older Goal.

Command grammar

Reserved verbs accept only the arguments shown. Objectives are limited to 4,000 Unicode code points. Unknown text after /goal is the objective for the start form, not a command registry.

Replace safely

Use the run_id from the current snapshot as the expected ID:

compozy session prompt sess_123 \
  '/goal replace run_current Ship the narrower objective and keep make verify green.' \
  -o json

Replacement prepares the candidate before it stops the old Run. Invalid candidate configuration leaves the old Goal live. Concurrent valid replacements have one compare-and-swap winner; other callers receive goal_replace_stale with the newer snapshot.

Draft before activation

compozy session prompt sess_123 '/goal draft fix the flaky checks without broad rewrites'

Draft is the only /goal form that stays on the ordinary streaming response path. It is admitted only while the session prompt slot is idle. A busy or race-busy session returns goal_draft_requires_idle before stream headers and does not queue, steer, interrupt, or count a Goal turn. Review the generated objective and optional clauses, then submit the prefilled /goal command yourself.

Verification and constraints

The start and replace objectives accept line-oriented lowercase clauses:

/goal Ship the parser cleanup without changing unrelated packages.
verify: make verify remains green
verify: generated OpenAPI has no drift
constraints: preserve the public CLI shape

CompozyOS stores the non-clause lines as the objective. Each verify: and constraints: line must contain text. The synthetic Goal always uses one canonical agent-judge criterion. Verification text is added to that judge rubric; it is never executed as a shell command. To author an actual command criterion, use a goal node in a compozy.loop/v1 definition.

Context and recovery

The context gauge reports evidence from the active Goal checkpoint:

[goals].context_nudge_ratio is pinned when the Run starts. When known usage reaches that threshold, CompozyOS requests correlated compaction. Compaction is an operational prompt, not a user-authored human message and not a Goal work turn.

CompozyOS does not replay an ACP prompt after its durable start. A restart with exact terminal evidence reconciles that terminal result. Missing proof becomes an ambiguous turn and a typed approval boundary. A max_tokens recovery starts a new continuation turn that inspects current state; it is not a retry of the previous prompt.

Run-owned Goals may reseed automatically when compaction cannot recover the binding. A session-origin Goal requires explicit approval before it moves away from the user's conversation. After approval, origin_session_id remains the owner and bound_session_id points to the active successor session. Use the active-session link for ordinary messages; /goal controls remain on the origin session.

Pause and approval re-entry enqueue one successor segment under a new control epoch. Repeated resume/approve calls do not create multiple successors. A terminal blocked Run stays terminal; change the objective with expected-Run replacement or clear the projection instead of resuming it.

Audit turns

Every durably started work prompt consumes one monotonic Goal turn. Compaction does not. Read the run-wide total order with:

compozy loop turns --run run_123 --after-seq 42 --limit 50 -o json

Optional --node and --item filters narrow one Goal instance. result_status, reason, stop reason, verdict, evidence, token usage, and ended_at are nullable until the corresponding evidence exists. Settled turns also retain bounded criteria[] and aggregate warnings[]. Each criterion records its outcome and, when applicable, exit code, standard output, standard error, blockers, and warnings. The Web Run page shows the same diagnostics, so a continuation can act on the failed check instead of repeating completed work. The response returns next_after_seq for the next page. See the generated compozy loop turns reference.

List only conversational Goal Runs, or one origin session:

compozy loop runs --origin session --origin-session sess_123 -o json

The Web Run page merges persisted pages with the three Goal Run events without duplicating turns. Session discovery remains separate: persisted goal_snapshot_changed frames announce start, replace, status, clear, and reseed changes on the always-on transcript stream, including changes made through another public surface.

Prompt metadata and native reports

Persisted transcript events tag engine-owned prompts as goal-work, goal-continuation, or goal-compaction, with Run, node, generation, item, prompt attempt, prompt ID, and nullable turn. The tags survive reload; clients do not infer them from prompt prose.

Agents operating inside the active binding have three dedicated tools:

• compozy__goal_get reads the visible snapshot for the caller session and follows an active moved-binding alias.
• compozy__goal_report records complete or evidenced blocked intent for the current prompt binding.
• compozy__loop_turns reads the workspace-authorized Run audit with cursor and node/item filters, even after the binding is terminal.

compozy__goal_report is a durable boundary intent, not immediate completion or proof of provider-side effect uniqueness. It is available to the current bound Goal prompt whether the Run started from a session, the catalog, HTTP, or a native tool. The daemon revalidates workspace, Run, prompt, control, and binding epochs when invoked. Evidence is limited to 16 KiB; blocked requires evidence. Retries with the same payload deduplicate, while conflicting or revoked reports fail with stable reason codes. Resolve each live descriptor with compozy__tool_info before calling it.

Configure defaults

New conversational and authored Goals consume the resolved [goals] defaults where the public start path applies them. Active Runs keep their pinned values. See the [goals] config reference for precedence, mutable paths, bounds, and restart lifecycle.