# update\_task

Change a task's slug, title, goal or notes, by `task_id` or `task_slug`.

writes · idempotent · MCP tool · [Task](https://komrad.dev/latest/api/task.md)

Fields left unset keep their values. The task's writer takes a new slug as its name. Changing the notes needs the [`notes_updated_at`](https://komrad.dev/latest/api/task/update-task.md#komrad-task-v1-UpdateTaskRequest-notes_updated_at) they were read with, and fails with `failed_precondition` when they changed since. Agents see the change the next time they read the task.

## Calling it

```bash
curl -X POST http://127.0.0.1:8787/komrad.task.v1.TaskService/UpdateTask \
  -H 'Content-Type: application/json' \
  -d '{
  "task_id": "<task_id>"
}'
```

```bash
komrad rpc update-task \
  --task-id '<uuid>'
```

```json
{
  "name": "update_task",
  "arguments": {
    "task_id": "<task_id>"
  }
}
```

Offered by the komrad MCP server to orchestrator agents.

## Request

### UpdateTaskRequest

| Field | Type | Description |
| --- | --- | --- |
| [one of](https://komrad.dev/latest/api/task/update-task.md#komrad-task-v1-UpdateTaskRequest-task)\* |  | The task to update. |
| [`task_id`](https://komrad.dev/latest/api/task/update-task.md#komrad-task-v1-UpdateTaskRequest-task_id) | uuid | The task, by id. |
| [`task_slug`](https://komrad.dev/latest/api/task/update-task.md#komrad-task-v1-UpdateTaskRequest-task_slug) | string not empty | The task, by slug. |
| [`slug`](https://komrad.dev/latest/api/task/update-task.md#komrad-task-v1-UpdateTaskRequest-slug) | string not empty at most 80 characters matching ^\[a-z0-9\]+(-\[a-z0-9\]+)\*$ | The new slug. No other task may have used it. Unchanged when unset. |
| [`title`](https://komrad.dev/latest/api/task/update-task.md#komrad-task-v1-UpdateTaskRequest-title) | string not empty at most 200 characters must not contain control characters | The new title. Unchanged when unset. |
| [`goal`](https://komrad.dev/latest/api/task/update-task.md#komrad-task-v1-UpdateTaskRequest-goal) | string at most 50000 characters | The new goal, in markdown. Unchanged when unset. |
| [`notes`](https://komrad.dev/latest/api/task/update-task.md#komrad-task-v1-UpdateTaskRequest-notes) | string at most 100000 characters | The new notes in full, in markdown. Unchanged when unset. |
| [`notes_updated_at`](https://komrad.dev/latest/api/task/update-task.md#komrad-task-v1-UpdateTaskRequest-notes_updated_at) | timestamp | The [`notes_updated_at`](https://komrad.dev/latest/api/task/update-task.md#komrad-task-v1-UpdateTaskRequest-notes_updated_at) that [`get_task`](https://komrad.dev/latest/api/task/get-task.md) returned with the notes, needed whenever [`notes`](https://komrad.dev/latest/api/task/update-task.md#komrad-task-v1-UpdateTaskRequest-notes) is set. |

## Response

### UpdateTaskResponse

| Field | Type | Description |
| --- | --- | --- |
| [`task`](https://komrad.dev/latest/api/task/update-task.md#komrad-task-v1-UpdateTaskResponse-task) | [Task](https://komrad.dev/latest/api/task/update-task.md#komrad-task-v1-Task) | The task as updated. |

## Types

### Task

Task is one piece of work that agents do.

| Field | Type | Description |
| --- | --- | --- |
| [`id`](https://komrad.dev/latest/api/task/update-task.md#komrad-task-v1-Task-id) | uuid\* | The task's id. |
| [`workflow_id`](https://komrad.dev/latest/api/task/update-task.md#komrad-task-v1-Task-workflow_id) | uuid\* | The id of the workflow the task belongs to. |
| [`slug`](https://komrad.dev/latest/api/task/update-task.md#komrad-task-v1-Task-slug) | string | The task's slug, such as `fix-login`. No two tasks ever share one. |
| [`title`](https://komrad.dev/latest/api/task/update-task.md#komrad-task-v1-Task-title) | string | The task's title. |
| [`goal`](https://komrad.dev/latest/api/task/update-task.md#komrad-task-v1-Task-goal) | string | What the task is meant to achieve, in markdown. |
| [`created_at`](https://komrad.dev/latest/api/task/update-task.md#komrad-task-v1-Task-created_at) | timestamp | When the task was created. |
| [`updated_at`](https://komrad.dev/latest/api/task/update-task.md#komrad-task-v1-Task-updated_at) | timestamp | When the task last changed. |
| [`archived_at`](https://komrad.dev/latest/api/task/update-task.md#komrad-task-v1-Task-archived_at) | timestamp | When the task was archived. Unset while the task is live. |
| [`cwd`](https://komrad.dev/latest/api/task/update-task.md#komrad-task-v1-Task-cwd) | string | The directory of the task's checkout. Unset while the task has no checkout. |
| [`branch`](https://komrad.dev/latest/api/task/update-task.md#komrad-task-v1-Task-branch) | string | The git branch of the task's checkout. Unset when the task has no checkout or git cannot read the branch. |
| [`repository_url`](https://komrad.dev/latest/api/task/update-task.md#komrad-task-v1-Task-repository_url) | string | The canonical web address of the repository the task's checkout pushes to, such as `https://github.com/harrisoncramer/komrad`. Unset when the checkout is gone or origin is not on a forge. |
| [`head_sha`](https://komrad.dev/latest/api/task/update-task.md#komrad-task-v1-Task-head_sha) | string | The commit checked out in the task's checkout. Unset when the checkout is gone or git cannot read it. |
| [`worktree_removal_reason`](https://komrad.dev/latest/api/task/update-task.md#komrad-task-v1-Task-worktree_removal_reason) | [WorktreeRemovalReason](https://komrad.dev/latest/api/task/update-task.md#komrad-task-v1-WorktreeRemovalReason) | Why the task's worktree is no longer on disk. Unspecified while it is. |
| [`sequence`](https://komrad.dev/latest/api/task/update-task.md#komrad-task-v1-Task-sequence) | [Sequence](https://komrad.dev/latest/api/task/update-task.md#komrad-task-v1-Sequence) | The git operation stopped part way in the task's checkout. |
| [`moved_since_snapshot`](https://komrad.dev/latest/api/task/update-task.md#komrad-task-v1-Task-moved_since_snapshot) | string | The commit of the task's newest snapshot, set while the checkout has changed since that snapshot. Empty otherwise. |
| [`diff_stat`](https://komrad.dev/latest/api/task/update-task.md#komrad-task-v1-Task-diff_stat) | [DiffStat](https://komrad.dev/latest/api/task/update-task.md#komrad-task-v1-DiffStat) | How many lines the task's checkout adds and removes since it left the base branch. Unset when there is no base branch to measure against. |
| [`adopted_branch`](https://komrad.dev/latest/api/task/update-task.md#komrad-task-v1-Task-adopted_branch) | string | The existing branch the task was put on. Unset when komrad created the branch. |
| [`failure_reason`](https://komrad.dev/latest/api/task/update-task.md#komrad-task-v1-Task-failure_reason) | string | Why the task's last delete failed to remove its checkout. Empty unless a delete failed. |
| [`notes`](https://komrad.dev/latest/api/task/update-task.md#komrad-task-v1-Task-notes) | string | The task's notes, in markdown, written by its agents and the person. |
| [`notes_updated_at`](https://komrad.dev/latest/api/task/update-task.md#komrad-task-v1-Task-notes_updated_at) | timestamp | When the task's notes were last written, or when the task was created if they never were. |
| [`parent`](https://komrad.dev/latest/api/task/update-task.md#komrad-task-v1-Task-parent) | [Parent](https://komrad.dev/latest/api/task/update-task.md#komrad-task-v1-Parent) | The task this task depends on. Unset for a task on the workflow's base branch. |
| [`snapshots`](https://komrad.dev/latest/api/task/update-task.md#komrad-task-v1-Task-snapshots) | int32 | How many snapshots komrad has taken of the task's checkout. |
| [`guides`](https://komrad.dev/latest/api/task/update-task.md#komrad-task-v1-Task-guides) | int32 | How many guides agents have written for the task. [`list_guides`](https://komrad.dev/latest/api/guide/list-guides.md) returns them. |

### DiffStat

DiffStat counts the lines a checkout adds and removes, committed or not.

| Field | Type | Description |
| --- | --- | --- |
| [`added`](https://komrad.dev/latest/api/task/update-task.md#komrad-task-v1-DiffStat-added) | int32 | How many lines the checkout adds. |
| [`removed`](https://komrad.dev/latest/api/task/update-task.md#komrad-task-v1-DiffStat-removed) | int32 | How many lines the checkout removes. |

### Parent

Parent is the task a child depends on, and the fork point where the child's own commits begin on the parent's branch. Snapshots and line counts measure from [`fork_point`](https://komrad.dev/latest/api/task/update-task.md#komrad-task-v1-Parent-fork_point).

| Field | Type | Description |
| --- | --- | --- |
| [`task_id`](https://komrad.dev/latest/api/task/update-task.md#komrad-task-v1-Parent-task_id) | uuid\* | The id of the parent task. |
| [`fork_point`](https://komrad.dev/latest/api/task/update-task.md#komrad-task-v1-Parent-fork_point) | string | The commit of the parent's branch the child's own commits sit on. |
| [`pull_request_id`](https://komrad.dev/latest/api/task/update-task.md#komrad-task-v1-Parent-pull_request_id) | uuid | The id of the parent's pull request, which komrad reads for the parent's newest commit and its merge. Empty until the parent has one. |
| [`blocked`](https://komrad.dev/latest/api/task/update-task.md#komrad-task-v1-Parent-blocked) | [CascadeBlock](https://komrad.dev/latest/api/task/update-task.md#komrad-task-v1-CascadeBlock) | Why the cascade cannot rebase the child onto its parent. |

### WorktreeRemovalReason

WorktreeRemovalReason is why a task's worktree is no longer on disk.

| Value | Description |
| --- | --- |
| [`deleted`](https://komrad.dev/latest/api/task/update-task.md#komrad-task-v1-WorktreeRemovalReason-deleted) | A delete removed the worktree. Komrad never makes it again. |
| [`gone`](https://komrad.dev/latest/api/task/update-task.md#komrad-task-v1-WorktreeRemovalReason-gone) | Komrad found the worktree's directory gone without a delete. |

### Sequence

Sequence is a git operation stopped part way in a task's checkout.

| Value | Description |
| --- | --- |
| [`none`](https://komrad.dev/latest/api/task/update-task.md#komrad-task-v1-Sequence-none) | No git operation is stopped part way. |
| [`rebase`](https://komrad.dev/latest/api/task/update-task.md#komrad-task-v1-Sequence-rebase) | A rebase stopped on a commit it could not replay. |
| [`am`](https://komrad.dev/latest/api/task/update-task.md#komrad-task-v1-Sequence-am) | A `git am` stopped on a patch it could not apply. |
| [`merge`](https://komrad.dev/latest/api/task/update-task.md#komrad-task-v1-Sequence-merge) | A merge stopped on conflicts. |
| [`cherry_pick`](https://komrad.dev/latest/api/task/update-task.md#komrad-task-v1-Sequence-cherry_pick) | A cherry-pick stopped on conflicts or paused between commits. |
| [`revert`](https://komrad.dev/latest/api/task/update-task.md#komrad-task-v1-Sequence-revert) | A revert stopped on conflicts or paused between commits. |

### CascadeBlock

CascadeBlock is why the cascade cannot rebase a child onto its parent.

| Value | Description |
| --- | --- |
| [`conflicted`](https://komrad.dev/latest/api/task/update-task.md#komrad-task-v1-CascadeBlock-conflicted) | Rebasing the child's own commits onto its parent stopped on conflicts. |
| [`orphaned`](https://komrad.dev/latest/api/task/update-task.md#komrad-task-v1-CascadeBlock-orphaned) | The child is orphaned: its branch holds neither its fork point nor any of its parent's own commits. |
| [`parent_closed`](https://komrad.dev/latest/api/task/update-task.md#komrad-task-v1-CascadeBlock-parent_closed) | The parent's pull request closed without merging. |
