# Tasks

> Browse external work items, bind one to an agent run, and make lifecycle changes through explicit
> provider-backed operations.

Tasks connects Clarvis to an external issue tracker or work-management system. Clarvis normalizes
the provider's items into one board and tool vocabulary, but it does not maintain a second task
database. The external provider remains the source of truth.

## Configure a task provider

Tasks uses a named MCP server that implements the `clarvis.tasks.v2` protocol. After declaring and
connecting that server, add the provider to global or workspace `settings.json`:

```json
{
  "tasks": {
    "provider": {
      "kind": "mcp",
      "server": "tracker:tasks",
      "protocol": "clarvis.tasks.v2"
    },
    "default_container": "engineering",
    "writes": "disabled"
  }
}
```

`default_container` is optional. Writes are disabled by default; set `writes` to `enabled` only
after reviewing the connected server and the agents that carry `tasks.*` grants. Provider setup,
plugin installation, and Extension Profile activation remain separate decisions.

## Browse the provider from Clarvis

Open `/tasks` to see provider health, switch between board and list views, filter by container or
search text, refresh, and open full task details. Clarvis keeps normalized stage, provider-native
state, assignee, and active claim separate so the interface does not pretend unsupported provider
semantics exist.

Read failures, conflicts, and uncertain mutation outcomes appear as explicit states rather than an
empty board. Returning from agent work refreshes the task from the external source of truth.

## Inspect a task or work on it

Selecting **Work on task** opens the normal Agent Profile picker and starts a run in the current
workspace bound to that external task. The task description enters the run as untrusted work data;
it cannot change the workspace, grant tools, disable safety controls, or select a provider.

Task access has two modes:

- `inspect` offers read operations only;
- `work` can offer supported writes when settings, the selected agent's grants, and the provider's
  advertised capabilities all allow them.

Opening a task in work mode does not mutate it. The agent must explicitly call `start_task`, and
finishing a Clarvis run never completes, reopens, or submits the external task automatically.

## Understand the write gates

A write tool is available only when all four conditions agree:

1. `tasks.writes` is `enabled`;
2. the bound run uses `work` mode;
3. the selected agent has the matching `tasks.*` grant;
4. the provider advertises that operation or lifecycle transition.

Clarvis serializes writes within a run and uses idempotency-bearing requests. If a network failure
makes the outcome uncertain, Clarvis re-reads the task, records the uncertainty, and refuses to
replay the write automatically. Inspect the external task before making an explicit retry.

## See also

- [Agents](/guide/agents)
- [MCP servers](/guide/mcp-servers)
- [Extension Profiles](/guide/extension-profiles)
- [Commands](/reference/commands)
- [Configuration](/reference/configuration)

---

[Canonical HTML](https://clarvis.dev/guide/tasks)

[Documentation index](https://clarvis.dev/llms.txt)