# Aufgaben und Kontext

Erstellen Sie eine aktive Task Guard-Task pro Agent-Sitzung, rufen Sie den aktuellen Vertrag zu Beginn jedes Arbeitszyklus ab, zeichnen Sie aussagekräftige Meilensteine auf und vervollständigen oder überführen Sie ihn explizit.

### Starten Sie eine Aufgabe

Verwendung `POST /v1/task-guard/tasks`. `POST /v1/task-guard/sessions` ist ein Alias mit der gleichen Anfrage und Antwort.

Benötigt `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`, und entweder `idempotency_key` oder `direct_user_event_id` erforderlich sind. Die Wiederverwendung des gleichen Ereignisschlüssels mit einer anderen Anforderung gibt einen Konflikt zurück.

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

Das Starten eines neuen Ziels in einer bestehenden Sitzung ersetzt die vorherige aktive Aufgabe. Eine nachfolgende Aufgaben- oder Vertragsrevision erfordert eine `direct_user_event_id`. In `ENFORCED` Modus, Task-Übergänge müssen den vertrauenswürdigen Host-Benutzerereignis-Endpunkt unten verwenden.

### Den aktiven Kontext abrufen

Verwenden Sie entweder den Endpunkt:

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

Beide erfordern `task_guard:tasks:read` und die aktuelle Aufgabe, Vertragsversion, Anker, Host-Modus zurückzugeben und `next_action`.

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

Kontextaktualisierung zu Beginn eines neuen Arbeitszyklus, nach Kontextkompaktierung oder Neustart und immer dann, wenn eine Ausrichtungsprüfung zurückkehrt `CONTEXT_REFRESH_REQUIRED`.

### Rekordfortschritte

Verwendung `POST /v1/task-guard/tasks/{taskId}/progress` Nach einem bedeutsamen Meilenstein.

Benötigt `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"
}
```

Die Antwort gibt das neue zurück `contract_version`, aktueller Schritt, Aufgaben-ID und nächste Aktion. Überprüfen Sie jeden Artikel in `new_dependencies` mit dem Ausrichtungsendpunkt, bevor auf ihn eingewirkt wird.

### Pause, Lebenslauf oder Abbrechen

Diese Lifecycle-Endpunkte erfordern `task_guard:tasks:write` und keine beantragende Stelle:

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

Pausieren oder Annullieren widerruft aktive Anpassungszuschüsse. Wiederaufnahme gibt die Aufgabe zurück an `active`. Jede Antwort enthält `task_id`, `status`, und `updated_at`.

### Abschluss der Aufgabe

Verwendung `POST /v1/task-guard/tasks/{taskId}/complete` wenn die Ziel- und Erfolgskriterien erfüllt sind.

Benötigt `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"
}
```

### Veranstaltungen für vertrauenswürdige Host-Benutzer

`POST /v1/task-guard/sessions/{sessionId}/user-events` Starten einer nachfolgenden Aufgabe oder Überarbeiten der aktiven Aufgabe aus einer verifizierten Direktbenutzeranweisung. Es akzeptiert die gleichen Felder wie die Startanforderung und erfordert zusätzlich `direct_user_event_id`.

Dieser Endpunkt erfordert:

* `task_guard:confirmations:write`
* ein API-Schlüssel, der als vertrauenswürdiger Task Guard-Bestätigungsnachweis gekennzeichnet ist
* a `session_ref` Übereinstimmung mit der referenzierten Task Guard-Sitzung

Verwenden Sie diesen Endpunkt für Task-Starts und Übergänge in `ENFORCED` Integrationen.