---
title: Tasks and delegation
description: Count a session's spend toward a pull request, issue or tracker key with --task, /task and VENOM_TASK, and let the agent delegate work to subagents with the task tool.
section: automation
order: 110
audience: [user, operator, builder, agent]
sources: [packages/harness/src/extensions/task.ts, packages/harness/src/extensions/subagents.ts, docs/venom-config.schema.json, docs/configuration.md]
features: [automation.task]
---

"Task" means two things in venom: the work item a session's spend counts toward, and the `task` tool the agent uses to hand work to subagents.

## Cost per task {#cost}

Every request venom sends carries the session's task, a pull request, issue or tracker key, as the `x-venom-task` header. `venom cost --by task` totals it from your saved sessions, and Venom Cloud's Usage page totals it across the team: the session, its subagents, side requests and escalations.

```bash
venom --task https://github.com/acme/api/pull/128     # set it for this session
VENOM_TASK=ENG-142 venom -p "fix the login redirect in src/auth/callback.ts"
venom cost --by task
```

In a session, `/task <url|id>` sets it and `/task off` clears it.

Where the task comes from, first found wins:

1. `venom --task <url|id>`, or `/task` during the session;
2. `VENOM_TASK`;
3. a resumed session's last task;
4. the branch: the task remembered for it (written when venom opens its pull request), else a number or tracker key in its name (`123-fix-login`, `feature/ENG-142`), from git alone;
5. with `tasks.lookup: gh`, `gh pr view` for the branch;
6. the pull request the agent opens with `gh pr create` or `glab mr create`.

An explicit task (flag, command, env var) is never replaced by a detected one.

| Key | Type | Default | What it does |
|---|---|---|---|
| `tasks.lookup` | `git` \| `gh` | `git` | `git`: offline, from the branch. `gh`: also ask `gh pr view` which pull request the branch has (a call to GitHub). |
| `tasks.pr_footer` | `off` \| `body` \| `comment` | `off` | After a run that opened or updated a GitHub pull request, write the task's spend so far into it: one marked line in the body, replaced each time, or one comment when it is opened. |

```yaml
tasks:
  lookup: git
  pr_footer: body
```

A project file's `tasks` settings apply only once the project is trusted. Nothing here changes the prompt or the tool list.

## The task tool {#tool}

The `task` tool lets the agent delegate focused work to subagents. Each subagent starts with an empty context, so the prompt carries everything it needs, and returns a short report. Independent tasks in one call run in parallel. The agent stays responsible for edits.

| Field | What it sets |
|---|---|
| `tasks[].prompt` | Complete, self-contained instructions. |
| `tasks[].agent` | The subagent definition (default `explorer`; also `worker`, `reviewer`, `verifier` and your own `.claude/agents/*.md`). |
| `tasks[].description` | A 3 to 6 word label. |
| `tasks[].model` | `fast`, `smart`, `inherit` or a model id; usually unset. |
| `tasks[].context` | Up to 8 paths or tool-call ids shared read-only. |
| `tasks[].maxTurns` | A turn cap; a subagent that hits it returns a partial report. |
| `tasks[].isolation` | `worktree`: its own git worktree, with its changes returned as a note. |
| `tasks[].after` | 1-based numbers of tasks in the same call that must finish first. |
| `tasks[].resume` | A subagent id from an earlier report (`s1`) to continue it. |
| `background` | Return at once; reports arrive later. |
| `stop` | Cancel a background call by its id (`bg1`). |

One call takes 1 to 8 tasks. [Workflows](/docs/automation/workflows.md) use the same child sessions from a script, and [plan then execute](/docs/automation/plan-execute.md) runs each step on a `worker`.

## Related

- [Workflows](/docs/automation/workflows.md)
- [Teams of agents](/docs/automation/teams.md#board-tool): the board subagents share.
