# Task Guard API

Task Guard keeps connected AI agents aligned with the active user-authorized task. It turns the objective, constraints, scope, decisions, and success criteria into a versioned task contract, then evaluates material actions against that contract before they run.

Task Guard is available over both the REST API and the [Maetra MCP server](https://maetra.io/docs/mcp-server/tools-reference).

### What Task Guard controls

1. **Start the task.** Create an active task contract from a direct user instruction.
2. **Refresh context.** Retrieve the current contract after a new turn, restart, or context compaction.
3. **Check actions.** Evaluate whether each material action is aligned, supporting, ambiguous, a scope change, or unrelated.
4. **Resolve uncertainty.** Explain a supporting relationship or ask the session user to confirm a material task change.
5. **Verify effects.** Compare what an allowed action was expected to change with what actually happened.
6. **Record progress and complete.** Keep the task anchor current and close the task when its success criteria are met.

> **Important**
> Task Guard confirmation is not a Govern approval. Task Guard asks whether work belongs to the user's active task. [Govern](https://maetra.io/docs/govern-api) decides whether a consequential action requires policy evaluation or human approval. When both apply, satisfy both controls.


### Advisory and enforced integrations

| Mode | Behaviour |
| ---- | --------- |
| `ADVISORY` | The host calls Task Guard and follows the returned verdict and `next_action`. |
| `ENFORCED` | The host must use trusted user-event transitions and can require a short-lived alignment token to match the exact action before execution. |

Use `CUSTOM_API` for a custom REST integration, `CUSTOM_MCP` for your own MCP host, or the first-party `CODEX` / `CLAUDE` host types.

### Task Guard scopes

| Scope | Used for |
| ----- | -------- |
| `task_guard:tasks:write` | Start tasks, record progress, transition lifecycle state, and complete tasks. |
| `task_guard:tasks:read` | Retrieve task context. |
| `task_guard:checks:write` | Check alignment, explain relationships, and verify alignment tokens. |
| `task_guard:effects:write` | Report actual action effects. |
| `task_guard:confirmations:write` | Submit trusted host user events and user confirmations. |

See [Authentication](https://maetra.io/docs/getting-started/authentication) for wildcard scopes and trusted confirmation credentials.

### Usage and billing

Each authenticated Task Guard REST or MCP tool request consumes one Task Guard request from the workspace allowance. The free trial includes 50 requests; Go includes 1,500 per month; Starter includes 3,000; Team includes 15,000; and Business includes 60,000. Paid plans can enable pay-as-you-go usage billing after the included allowance is exhausted.

Retry a request with the same `Idempotency-Key` header, or the same body `idempotency_key` where supported, to avoid consuming another unit for an idempotent replay.

### REST resources

The REST API exposes purpose-built task, context, alignment, effect, confirmation, and lifecycle endpoints under:

```
https://api.maetra.io/v1/task-guard
```

The generic `POST /v1/task-guard/tools/{tool}` endpoint also accepts the same request body as any of the seven Task Guard tools:

```
start_task
get_task_context
check_task_alignment
explain_task_relationship
record_task_progress
record_action_effect
complete_task
```

For normal REST integrations, prefer the purpose-built endpoints documented in [Tasks and context](https://maetra.io/docs/task-guard-api/tasks-and-context) and [Alignment and effects](https://maetra.io/docs/task-guard-api/alignment-and-effects).