<!--
name: 'Tool Description: TaskUpdate'
description: Default SDK built-in tool description and input schema for TaskUpdate.
sdkPackage: '@anthropic-ai/claude-agent-sdk@0.3.168'
claudeCodeVersion: '2.1.168'
tool: "TaskUpdate"
-->
# Tool Description: TaskUpdate

## Metadata

- Request location: `tools[]`
- Tool name: `TaskUpdate`
- Input schema properties: `taskId`, `subject`, `description`, `activeForm`, `status`, `addBlocks`, `addBlockedBy`, `owner`, `metadata`

## Description

Use this tool to update a task in the task list.

## When to Use This Tool

**Mark tasks as resolved:**
- When you have completed the work described in a task
- When a task is no longer needed or has been superseded
- IMPORTANT: Always mark your assigned tasks as resolved when you finish them
- After resolving, call TaskList to find your next task

- ONLY mark a task as completed when you have FULLY accomplished it
- If you encounter errors, blockers, or cannot finish, keep the task as in_progress
- When blocked, create a new task describing what needs to be resolved
- Never mark a task as completed if:
  - Tests are failing
  - Implementation is partial
  - You encountered unresolved errors
  - You couldn't find necessary files or dependencies

**Delete tasks:**
- When a task is no longer relevant or was created in error
- Setting status to `deleted` permanently removes the task

**Update task details:**
- When requirements change or become clearer
- When establishing dependencies between tasks

## Fields You Can Update

- **status**: The task status (see Status Workflow below)
- **subject**: Change the task title (imperative form, e.g., "Run tests")
- **description**: Change the task description
- **activeForm**: Present continuous form shown in spinner when in_progress (e.g., "Running tests")
- **owner**: Change the task owner (agent name)
- **metadata**: Merge metadata keys into the task (set a key to null to delete it)
- **addBlocks**: Mark tasks that cannot start until this one completes
- **addBlockedBy**: Mark tasks that must complete before this one can start

## Status Workflow

Status progresses: `pending` → `in_progress` → `completed`

Use `deleted` to permanently remove a task.

## Staleness

Make sure to read a task's latest state using `TaskGet` before updating it.

## Examples

Mark task as in progress when starting work:
```json
{"taskId": "1", "status": "in_progress"}
```

Mark task as completed after finishing work:
```json
{"taskId": "1", "status": "completed"}
```

Delete a task:
```json
{"taskId": "1", "status": "deleted"}
```

Claim a task by setting owner:
```json
{"taskId": "1", "owner": "my-name"}
```

Set up task dependencies:
```json
{"taskId": "2", "addBlockedBy": ["1"]}
```


## Input Schema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "taskId": {
      "description": "The ID of the task to update",
      "type": "string"
    },
    "subject": {
      "description": "New subject for the task",
      "type": "string"
    },
    "description": {
      "description": "New description for the task",
      "type": "string"
    },
    "activeForm": {
      "description": "Present continuous form shown in spinner when in_progress (e.g., \"Running tests\")",
      "type": "string"
    },
    "status": {
      "description": "New status for the task",
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "pending",
            "in_progress",
            "completed"
          ]
        },
        {
          "type": "string",
          "const": "deleted"
        }
      ]
    },
    "addBlocks": {
      "description": "Task IDs that this task blocks",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "addBlockedBy": {
      "description": "Task IDs that block this task",
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "owner": {
      "description": "New owner for the task",
      "type": "string"
    },
    "metadata": {
      "description": "Metadata keys to merge into the task. Set a key to null to delete it.",
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {}
    }
  },
  "required": [
    "taskId"
  ],
  "additionalProperties": false
}
```

## Token Impact

<!-- TOKEN_COUNT_START -->
- Complete definition estimated tokens: **1,375**
- Measurement: captured tool object serialized independently as JSON text against the common baseline
- Additivity: independent, non-additive estimate
<!-- TOKEN_COUNT_END -->