> ## Documentation Index
> Fetch the complete documentation index at: https://docs.slaunt.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Lifecycle tools: thread_begin, run_begin, run_step, run_end

> Parameters and response fields for thread_begin, run_begin, run_step, run_end and thread_close.

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](https://docs.slaunt.ai/protocol/lifecycle.md). Every call returns a [`runtime` snapshot](#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 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.