Lifecycle tools: thread_begin, run_begin, run_step, run_end

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.

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

Get started

Clients

Protocol

Tools

Guides

Reference

Help