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.
What Task Guard controls#
- Start the task. Create an active task contract from a direct user instruction.
- Refresh context. Retrieve the current contract after a new turn, restart, or context compaction.
- Check actions. Evaluate whether each material action is aligned, supporting, ambiguous, a scope change, or unrelated.
- Resolve uncertainty. Explain a supporting relationship or ask the session user to confirm a material task change.
- Verify effects. Compare what an allowed action was expected to change with what actually happened.
- 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 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 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 and Alignment and effects.