# Tareas y contexto

Crear una tarea activa de Task Guard por sesión de agente, recuperar su contrato actual al comienzo de cada ciclo de trabajo, registrar hitos significativos, y completar o transición explícitamente.

### Iniciar una tarea

Uso `POST /v1/task-guard/tasks`. `POST /v1/task-guard/sessions` es un alias con la misma solicitud y respuesta.

Requisitos `task_guard:tasks:write`.

```bash
curl -X POST "https://api.maetra.io/v1/task-guard/tasks" \
  -H "Authorization: Bearer $MAETRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "session_ref": "conversation_01JY8Q",
    "title": "Ship approval flow",
    "objective": "Add and verify the customer refund approval flow.",
    "constraints": ["Do not change billing provider configuration."],
    "in_scope": ["API route", "dashboard UI", "tests"],
    "out_of_scope": ["Production deployment"],
    "success_criteria": ["Lint and tests pass", "Approval can be completed end to end"],
    "agent_name": "release-agent",
    "host_type": "CUSTOM_API",
    "integration_mode": "ADVISORY",
    "confirmation_capable": true,
    "effect_reporting_capable": true,
    "idempotency_key": "task-start-01JY8Q"
  }'
```

`session_ref`, `objective`, y cualquiera `idempotency_key` o `direct_user_event_id` son necesarios. Reutilizar la misma clave del evento con una petición diferente devuelve un conflicto.

```json
{
  "ok": true,
  "session_id": "tgs_01JY8R",
  "session_ref": "conversation_01JY8Q",
  "task": {
    "id": "tgt_01JY8S",
    "sequence": 1,
    "status": "active",
    "title": "Ship approval flow",
    "completed_at": null
  },
  "contract_version": 1,
  "anchor": {
    "objective": "Add and verify the customer refund approval flow.",
    "constraints": ["Do not change billing provider configuration."],
    "in_scope": ["API route", "dashboard UI", "tests"],
    "out_of_scope": ["Production deployment"],
    "success_criteria": ["Lint and tests pass", "Approval can be completed end to end"],
    "decisions": [],
    "open_questions": [],
    "accepted_expansions": [],
    "anchor_hash": "sha256:…",
    "anchor_text": "…"
  },
  "host": {
    "type": "custom_api",
    "integration_mode": "advisory"
  },
  "next_action": "Call get_task_context after compaction and check_task_alignment before meaningful actions."
}
```

Iniciar un nuevo objetivo en una sesión existente supera la tarea activa anterior. Una revisión posterior de la tarea o del contrato requiere una `direct_user_event_id`. In `ENFORCED` mode, task transitions must use the reliable host user-event endpoint below.

### Recuperar el contexto activo

Usar el punto final:

```
GET /v1/task-guard/tasks/{taskId}
GET /v1/task-guard/tasks/{taskId}/context
```

Ambos requieren `task_guard:tasks:read` y devolver la tarea actual, la versión del contrato, el ancla, el modo anfitrión, y `next_action`.

```bash
curl "https://api.maetra.io/v1/task-guard/tasks/tgt_01JY8S/context" \
  -H "Authorization: Bearer $MAETRA_API_KEY"
```

Refresh context at the start of a new work cycle, after context compaction or restart, and every an alignment check returns `CONTEXT_REFRESH_REQUIRED`.

### Progresos registrados

Uso `POST /v1/task-guard/tasks/{taskId}/progress` después de un hito significativo.

Requisitos `task_guard:tasks:write`.

```json
{
  "summary": "API route and validation are complete.",
  "completed": ["Implemented the refund approval endpoint"],
  "next_steps": ["Connect the dashboard form", "Run integration tests"],
  "new_dependencies": [],
  "open_questions": [],
  "current_step": "Implement dashboard integration",
  "idempotency_key": "progress-01JY9A"
}
```

La respuesta devuelve el nuevo `contract_version`, paso actual, identificación de tareas y siguiente acción. Compruebe cada artículo en `new_dependencies` con el punto final de alineación antes de actuar en él.

### Pausa, reanudar o cancelar

Estos puntos finales del ciclo de vida requieren `task_guard:tasks:write` y ningún órgano de solicitud:

```
POST /v1/task-guard/tasks/{taskId}/pause
POST /v1/task-guard/tasks/{taskId}/resume
POST /v1/task-guard/tasks/{taskId}/cancel
```

Pausar o cancelar revoca las subvenciones activas de alineación. Resumir devuelve la tarea a `active`. Cada respuesta contiene `task_id`, `status`, y `updated_at`.

### Completar la tarea

Uso `POST /v1/task-guard/tasks/{taskId}/complete` después de que se cumplan los criterios objetivos y de éxito.

Requisitos `task_guard:tasks:write`.

```json
{
  "summary": "Refund approvals are implemented and verified end to end.",
  "completion_event_id": "complete-01JY9Z"
}
```

```json
{
  "ok": true,
  "task_id": "tgt_01JY8S",
  "status": "completed",
  "summary": "Refund approvals are implemented and verified end to end.",
  "completed_at": "2026-07-20T13:42:18.000Z"
}
```

### Eventos de usuarios de host con confianza

`POST /v1/task-guard/sessions/{sessionId}/user-events` inicia una tarea posterior o revisa la tarea activa de una instrucción verificada de usuario directo. Acepta los mismos campos que la solicitud de inicio y además requiere `direct_user_event_id`.

Este punto final requiere:

* `task_guard:confirmations:write`
* una clave de API marcada como una credencial de confirmación de Task Guard confiable
* a `session_ref` coincidiendo con la sesión de Task Guard referencia

Utilice este punto final para iniciar tareas y transiciones en `ENFORCED` integraciones.