---
title: Tasks and runs
description: Create a task, follow its events live, steer it, answer its
  questions, pause, resume, retry or cancel it, and understand what the harness
  keeps.
url: https://hexelstudio.com/docs/harness/tasks
---

A **task** gives an agent a goal. It keeps going until it is done: it survives restarts, waits for people when it needs them and stops at its budget. Each attempt at a task, and each sub-agent it starts, is a **run**.

## Create a task

```bash
hexel harness task create "Audit the api repo" --agent auditor@prod \
  --input repo=acme/api --budget-usd 5 --follow
```

| Field | Description |
| --- | --- |
| `goal` | What the agent should do. Up to 64 KiB. |
| `agent` | `name` (its `prod` channel), `name@channel` or `name@v<n>`. |
| `inputs` | Optional JSON object, up to 256 KiB. The agent receives it with the goal. |
| `budget` | Optional limits: see [Budgets and estimates](https://hexelstudio.com/docs/harness/budgets-and-estimates). |
| `sandbox_template` | Optional. The sandbox template for the task's computer. |
| `after`, `inputs_from`, `checkin` | Optional. See [Task chains](https://hexelstudio.com/docs/harness/chains). |

A task belongs to the person who created it, in the workspace and environment of the request. Members see and act on their own tasks; Admins and Owners (`harness:task:admin`) on everyone's.

## States

| State | Meaning |
| --- | --- |
| `queued` | Admitted and waiting for the runtime to start it. |
| `running` | The agent is working. |
| `waiting` | The agent waits; `waiting_reason` says on what (below). |
| `paused` | Paused by a person. A paused task holds no capacity. |
| `succeeded` | Done. Its `outputs` hold the result. |
| `failed` | Ended without success; `end_reason` says why. |
| `budget_exhausted` | Stopped at its budget. Resume it with a new budget. |
| `cancelled` | Cancelled by a person. |

| `waiting_reason` | The task waits for |
| --- | --- |
| `question` | An answer to the agent's question. |
| `approval` | A Titan approval of one of its actions ([Approvals and autonomy](https://hexelstudio.com/docs/harness/approvals)). |
| `dependency` | The tasks it starts after ([Task chains](https://hexelstudio.com/docs/harness/chains)). |
| `parked` | An answer, for more than an hour (below). |
| `fork_worker` | A runtime that can start a forked run. |

**Parking.** A run that has waited an hour for an answer, with nothing in flight, is parked: it holds no runtime capacity and shows `waiting_reason: parked`. An answer or a steer wakes it, and it continues where it was. With nothing arriving, it is looked at again after 6 hours and parked again if it still waits. A parked task can be paused or cancelled.

## Follow a task

A task's events stream as [Server-Sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events): first the stored events, then live ones until the task ends, then an `end` event.

```bash
hexel harness tail -f tsk_123                          # follow until it ends
hexel harness tail tsk_123 --only message,tool         # only some event types
hexel harness tail tsk_123 --after 120                 # pick up after event 120
```

```bash
curl -N https://api.hexelstudio.com/v1/harness/tasks/tsk_123/events \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "X-Workspace-Id: $WORKSPACE_ID" -H "X-Environment-Id: $ENVIRONMENT_ID"
```

- Each SSE event's `event:` is its type and `data:` the event envelope. [Events](https://hexelstudio.com/docs/harness/events) lists every type.
- To resume after a dropped connection, send `Last-Event-ID` or `?after=<event id>`. The SDKs do this for you.
- `?types=` filters by type, `?run=` narrows a task's stream to one run, and `?follow=false` returns the history and stops.
- `GET /harness/runs/{id}/events` streams one run.

## Steer a task and answer it

```bash
hexel harness steer tsk_123 "Skip the vendored code"          # read at the agent's next step
hexel harness steer tsk_123 "Stop and summarise now" --now    # interrupts what it is doing
hexel harness answer call_456 "api and web"                      # answer a question
hexel harness answer call_456 --decline                          # decline to answer
```

The agent asks with `ask_user`; the question arrives as a `question.asked` event and in `GET /harness/tasks/{id}`. Through the API, steer with `POST /harness/tasks/{id}/messages` `{"text": "...", "mode": "queue" | "now"}` and answer with `POST /harness/questions/{id}/answer` `{"answer": "..."}` (`null` declines). A finished task takes no steer or answer.

## Control a task

| Command | API | What it does |
| --- | --- | --- |
| `hexel harness task pause` | `POST /tasks/{id}/pause` | The agent stops after its current step. |
| `hexel harness task resume` | `POST /tasks/{id}/resume` | Continue a paused task, or one out of budget with a new budget (`--budget-usd`). |
| `hexel harness task retry` | `POST /tasks/{id}/retry` | Start a failed, cancelled or out-of-budget task again. |
| `hexel harness task cancel` | `POST /tasks/{id}/cancel` | Cancel it. |
| `hexel harness task delete` | `DELETE /tasks/{id}` | Delete it and everything under it; its running agent is stopped. See [Data retention](https://hexelstudio.com/docs/harness/data-retention). |

Resume and retry are admitted like a new task: they are checked against your plan, balance and limits.

## Runs

```bash
hexel harness task runs tsk_123     # attempts and sub-agents
hexel harness run get run_789       # one run, with what Titan knows of its session
```

A retry starts a new attempt, a new root run. A sub-agent the agent starts is a child run with its own events. `GET /harness/runs/{id}` includes the run's Titan governance state: its Titan session and lifecycle.

## Content and history

The harness's control plane stores metadata: ids, states, costs, sizes and keyed digests (`hmac-sha256:...`). The content of an event (message text, tool arguments and results, questions and answers) stays in the runtime that ran the task.

- **Live.** An open stream receives the content as it happens, in `event.content` chunks that carry no id and are not stored. The SDKs and the CLI join them for you. At most 1 MiB is relayed per event.
- **History.** Events read back later (`?after=`, `Last-Event-ID`, `?follow=false`) carry metadata only: each content field is replaced by its digest and size.
- **Task fields.** A task's `outputs` show `{digest, size}`. Once a task has succeeded, its `goal` and `inputs` are emptied and their digests stay; a failed or cancelled task keeps them so that it can be retried.
- **Commands.** Steers, answers and decision reasons lose their content once applied or once the task ends.

Follow a task while it runs if you need its content, or have the agent export what matters as an [artifact](https://hexelstudio.com/docs/harness/artifacts).
