# State Hub Tool Signatures

Load this reference when a session needs exact REST fallback paths or batched
write payloads.

## Orientation

```text
MCP: get_domain_summary(domain_slug)
REST: GET /state/summary then filter by topic/domain when MCP is unavailable
```

Use `get_domain_summary("custodian")` inside State Hub work. It returns the
domain topic, active workstreams, blocking decisions, recent progress, repos,
and compact capability hints.

## Agent Messages

```text
MCP: get_messages(to_agent?, from_agent?, unread_only?, limit?)
REST: GET /messages/?to_agent=<repo>&unread_only=true

MCP: send_message(from_agent, to_agent, subject, body, thread_id?)
REST: POST /messages/

MCP: mark_message_read(message_id)
REST: PATCH /messages/{message_id}/read
```

Use repo slugs as agent names. Use `broadcast` only for genuinely shared
coordination.

## Workstreams and Tasks

```text
MCP: create_workstream(topic_id, title, slug?, description?, owner?, due_date?, repo_id?, planning_priority?, planning_order?)
REST: POST /workstreams/

MCP: create_task(workstream_id, title, priority="medium", description?, assignee?, due_date?)
REST: POST /tasks/

MCP: update_task_status(task_id, status, blocking_reason?, tokens_in?, tokens_out?, workplan_tokens_in?, workplan_tokens_out?, note?, model?, agent?, session_id?)
REST: PATCH /tasks/{task_id}
```

Canonical task statuses are `wait`, `todo`, `progress`, `done`, and `cancel`.
Legacy aliases are accepted during migration, but do not emit new workplan files
with old vocabulary.

## Bulk Task Status Sync

```text
MCP: bulk_update_task_statuses(updates, author?, session_id?)
REST: POST /tasks/bulk-status-sync
```

Payload:

```json
{
  "updates": [
    {"task_id": "uuid-1", "status": "progress"},
    {"task_id": "uuid-2", "status": "done"},
    {"task_id": "uuid-3", "status": "wait", "blocking_reason": "needs approval"}
  ],
  "author": "codex",
  "session_id": "optional-session-id"
}
```

Response:

```json
{
  "updated": [
    {"id": "uuid-1", "status": "progress", "...": "..."}
  ],
  "progress_event_ids": ["event-uuid-1"]
}
```

The endpoint rejects duplicate task ids with `400` and missing task ids with
`404` before changing any task. Each successful item emits one
`task_status_changed` progress event with `detail.bulk_status_sync = true`.

## Progress and Decisions

```text
MCP: add_progress_event(summary, event_type="note", topic_id?, workstream_id?, task_id?, detail?)
REST: POST /progress/

MCP: record_decision(title, decision_type="pending", topic_id?, workstream_id?, description?, rationale?, decided_by?, deadline?)
REST: POST /decisions/
```

Prefer one progress event per checkpoint. A useful close event says what changed,
which tests ran, whether consistency sync passed, and what remains.
