state-hub/dashboard/src/docs/interventions.md

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 wait, todo, or progress 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 (wait → progress → todo). Each card shows:

Element	Meaning
Priority badge	critical / high / medium / low
Status chip	Current task status
Domain	Source domain slug
Workplan	Parent workplan 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 / Canceled 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 workplan

list_human_interventions(workstream_id="<uuid>") via MCP returns only interventions for a specific workplan — 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.