# Tasks and context

Create one active Task Guard task per agent session, retrieve its current contract at the start of each work cycle, record meaningful milestones, and complete or transition it explicitly.

### Start a task

Use `POST /v1/task-guard/tasks`. `POST /v1/task-guard/sessions` is an alias with the same request and response.

Requires `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`, and either `idempotency_key` or `direct_user_event_id` are required. Reusing the same event key with a different request returns a conflict.

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

Starting a new objective in an existing session supersedes the prior active task. A subsequent task or contract revision requires a `direct_user_event_id`. In `ENFORCED` mode, task transitions must use the trusted host user-event endpoint below.

### Retrieve the active context

Use either endpoint:

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

Both require `task_guard:tasks:read` and return the current task, contract version, anchor, host mode, and `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 whenever an alignment check returns `CONTEXT_REFRESH_REQUIRED`.

### Record progress

Use `POST /v1/task-guard/tasks/{taskId}/progress` after a meaningful milestone.

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

The response returns the new `contract_version`, current step, task ID, and next action. Check every item in `new_dependencies` with the alignment endpoint before acting on it.

### Pause, resume, or cancel

These lifecycle endpoints require `task_guard:tasks:write` and no request body:

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

Pausing or cancelling revokes active alignment grants. Resuming returns the task to `active`. Each response contains `task_id`, `status`, and `updated_at`.

### Complete the task

Use `POST /v1/task-guard/tasks/{taskId}/complete` after the objective and success criteria are satisfied.

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

### Trusted host user events

`POST /v1/task-guard/sessions/{sessionId}/user-events` starts a subsequent task or revises the active task from a verified direct-user instruction. It accepts the same fields as the start request and additionally requires `direct_user_event_id`.

This endpoint requires:

* `task_guard:confirmations:write`
* an API key marked as a trusted Task Guard confirmation credential
* a `session_ref` matching the referenced Task Guard session

Use this endpoint for task starts and transitions in `ENFORCED` integrations.