Lifecycle tools
These tools create threads and runs and keep Quaero current. With Claude Code or Codex hooks installed you rarely call them yourself; elsewhere the model calls them every turn. Which call is valid when is covered in Lifecycle. Every call returns a runtime snapshot (fields at the end of this section).
thread_begin
Call once at the start of a chat.
| Param | Type | |
|---|---|---|
request_id | string ≤256 | Required. New per attempt, reused on retry. |
new_thread | boolean | Rotate from an idle thread into a new chat on the same connection |
label | string | Shown for the thread |
metadata | object |
Returns ok, the server-minted thread_uuid, thread_resolution_source and runtime.
run_begin
Call when you start a task. task is what Quaero shows as the agent's activity, so make it specific ("Fix flaky login test", not "Working").
| Param | Type | |
|---|---|---|
task | string | Required |
request_id | string ≤256 | Defaults to the JSON-RPC id |
metadata | object |
run_step
Call at real milestones: a file done, tests passing, waiting on input. It updates Quaero and closes any telemetry gap.
| Param | Type | |
|---|---|---|
activity | string | Required. Replaces the activity text in Quaero. |
details | string | |
progress | number 0–100 | Drives the progress bar |
spend_usd | number ≥0 | Running spend estimate for the run |
request_id, metadata |
run_end
| Param | Type | |
|---|---|---|
outcome | completed | errored | interrupted | killed | Default completed. Use killed/interrupted after a stop. |
summary | string | |
result | any JSON | Final output payload |
request_id, metadata |
thread_close
Marks the whole chat finished; only valid between runs. Params: reason, request_id. Not needed after every task.
runtime snapshot
| Field | |
|---|---|
thread_state, thread_state_version | Current state and its version |
run_active, active_run_uuid | |
current_activity | What Quaero shows |
client_key, client_label | Detected client, e.g. claude-code |
stop_requested, stop_requested_at | Set when someone stops the agent |
last_run_begin_at, last_run_step_at, last_run_end_at | |
telemetry_gap_open, telemetry_gap_count | Whether the run currently looks stale |