---
title: Interventions — Reference
---

# Interventions — Reference

The Interventions page lists every task that has been flagged `needs_human=true` — actions that only a human can take. It polls the API every 15 seconds and organises tasks into **Open** and **Completed / Cancelled** sections.

---

## What is a human intervention?

A human intervention is a task that an agent has determined cannot proceed without direct human action — for example, approving a financial decision, confirming a legal commitment, or resolving a sensitive ambiguity. Flagging a task does not change its work status; the task continues to be `todo`, `in_progress`, or `blocked` while awaiting attention.

---

## KPI sidebar card

| Metric | Meaning |
|---|---|
| **open** | Number of tasks currently flagged and not yet resolved |
| **critical / high** | Subset with `critical` or `high` priority — shown in red when non-zero |
| **by domain** | Top-3 domains by open intervention count |

---

## Open section

Tasks are sorted by priority (critical → high → medium → low), then by status (blocked → in_progress → todo). Each card shows:

| Element | Meaning |
|---|---|
| Priority badge | `critical` / `high` / `medium` / `low` |
| Status chip | Current task status |
| Domain | Source domain slug |
| Workstream | Parent workstream title |
| Action note | The `intervention_note` — what the human needs to do |
| Task detail | Expandable `<details>` with the task title and description (shown when different from the action note) |

---

## Marking an intervention as done

Click **Mark done** on any open card. An inline form appears requiring a **resolution comment** — a short note describing what was done. The comment is mandatory; clicking **Confirm** without entering text highlights the field in red and does nothing.

Once confirmed, the API call sets `status = done`, `needs_human = false`, and replaces the action note with your resolution comment. The card moves to the **Completed / Cancelled** section on the next poll.

Click **Cancel** to dismiss the form without making changes.

---

## Flagging and clearing interventions via MCP

```
flag_for_human(
  task_id = "<uuid>",
  note    = "Approve the Q2 budget allocation before the 15th"
)
```

```
clear_human_flag(task_id = "<uuid>")
```

`clear_human_flag` sets `needs_human = false` and preserves the `intervention_note` as a historical record. It does **not** change the task's work status. Use the dashboard's **Mark done** button when you also want to advance the status to `done`.

---

## Filtering by workstream

`list_human_interventions(workstream_id="<uuid>")` via MCP returns only interventions for a specific workstream — useful for scoped reviews in agent sessions.

---

## REST endpoints

| Method | Path | Effect |
|---|---|---|
| `GET` | `/tasks/?needs_human=true` | List all flagged tasks |
| `PATCH` | `/tasks/{id}/` | Update status, needs_human, intervention_note |

---

*Interventions are never created from the dashboard — they are raised by agents during task execution and resolved by the human.*