Skip to content
Docs menu

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.

View .md

"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 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.
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

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.