Tasks and delegation
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.
"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
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.
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 taskIn a session, /task <url|id> sets it and /task off clears it.
Where the task comes from, first found wins:
venom --task <url|id>, or/taskduring the session;VENOM_TASK;- a resumed session's last task;
- 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; - with
tasks.lookup: gh,gh pr viewfor the branch; - the pull request the agent opens with
gh pr createorglab 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. |
tasks:
lookup: git
pr_footer: bodyA project file's tasks settings apply only once the project is trusted. Nothing here changes the prompt or the tool list.
The task 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 use the same child sessions from a script, and plan then execute runs each step on a worker.
Related
- Workflows
- Teams of agents: the board subagents share.