# Tâches et contexte

Créer une tâche Task Guard active par session d'agent, récupérer son contrat actuel au début de chaque cycle de travail, enregistrer des jalons significatifs, et terminer ou la transition explicitement.

### Démarrer une tâche

Utilisation `POST /v1/task-guard/tasks`. `POST /v1/task-guard/sessions` est un pseudonyme avec la même demande et la même réponse.

Nécessaire `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`, et soit `idempotency_key` ou `direct_user_event_id` sont nécessaires. Réutiliser la même clé d'événement avec une requête différente renvoie un conflit.

```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."
}
```

Le lancement d'un nouvel objectif dans une session existante remplace la tâche active antérieure. Une tâche ultérieure ou une révision de contrat nécessite une `direct_user_event_id`C'est vrai. Dans `ENFORCED` mode, les transitions de tâches doivent utiliser le paramètre utilisateur-événement d'hôte de confiance ci-dessous.

### Récupérer le contexte actif

Utiliser l'un ou l'autre des critères suivants :

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

Tous les deux nécessitent `task_guard:tasks:read` et retourne la tâche courante, version du contrat, ancre, mode hôte, et `next_action`.

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

Rafraîchir le contexte au début d'un nouveau cycle de travail, après compactage ou redémarrage du contexte, et chaque fois qu'une vérification d'alignement revient `CONTEXT_REFRESH_REQUIRED`.

### Enregistrement des progrès accomplis

Utilisation `POST /v1/task-guard/tasks/{taskId}/progress` après un jalon significatif.

Nécessaire `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 réponse renvoie le nouveau `contract_version`, l'étape actuelle, l'identification des tâches et la prochaine action. Vérifiez chaque élément dans `new_dependencies` avec le paramètre d'alignement avant d'agir sur celui-ci.

### Pause, reprise ou annulation

Ces paramètres du cycle de vie nécessitent `task_guard:tasks:write` et aucun organisme de demande:

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

L'abandon ou l'annulation des subventions d'alignement actives. Reprise retourne la tâche à `active`C'est vrai. Chaque réponse contient `task_id`, `status`et `updated_at`.

### Terminer la tâche

Utilisation `POST /v1/task-guard/tasks/{taskId}/complete` une fois l'objectif et les critères de succès satisfaits.

Nécessaire `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"
}
```

### Événements d'utilisateurs d'hôtes de confiance

`POST /v1/task-guard/sessions/{sessionId}/user-events` commence une tâche ultérieure ou révise la tâche active à partir d'une instruction d'utilisateur direct vérifiée. Il accepte les mêmes champs que la demande de démarrage et nécessite en outre `direct_user_event_id`.

Ce critère d'évaluation exige:

* `task_guard:confirmations:write`
* une clé API marquée comme un justificatif de confirmation Task Guard de confiance
* a `session_ref` correspondant à la session Task Guard référencée

Utilisez ce paramètre pour les démarrages et les transitions des tâches `ENFORCED` les intégrations.