Skip to content
Docs menu

Subagents and model tiers

How the agent delegates work to subagents through the task tool, which built-in agents ship, how model tiers pick cheaper models, and how writers get their own git worktrees.

View .md

A session's agent can hand focused work to subagents: fresh sessions with an empty context that return a short report. Searches, long logs and independent changes go to them, so the main context stays small and cheap work runs on a cheap model. The harness runs them for you; your app configures limits, models and isolation.

The task tool

The model calls task with one to eight tasks. Independent tasks run in parallel; after orders dependent ones.

Field Meaning
prompt complete, self-contained instructions (required)
agent which agent; default explorer
description a 3 to 6 word label
model fast, smart, inherit or a model id; usually unset
context up to 8 paths or tool-call ids to share read-only
maxTurns turn cap (default 25, never below 15); a subagent that hits it returns a partial report
isolation worktree: its own git worktree
after 1-based numbers of tasks that must finish first
background, resume, stop (top level) return at once and report later; continue a finished subagent by id; cancel a background one

Subagents run under the parent harness's policy: a child gets the parent's mode or a stricter one (harness.childMode), and its permission asks go to the same approver, serialized, with parentToolCallId naming the parent's task call.

Built-in agents

Agent Aliases Mode and tier For
explorer Explore, explore read-only, fast searching and reading
worker general-purpose, general, build accept-edits, inherit a self-contained change
verifier accept-edits, fast, 15 turns running the project's tests, build or lint and reporting PASS or FAIL
planner Plan, plan read-only, fast writing a plan
reviewer read-only, fast reviewing a diff
security-reviewer read-only, fast a security review

Agents are Claude Code agent files. Your own go in .venom/agents/*.md or .claude/agents/*.md (frontmatter name, description, tools, model, isolation, mcpServers); one with a built-in's name replaces it. subagents.BUILTIN_AGENTS lists them; subagents.findAgent resolves names and aliases.

Model tiers

Agents and summaries name a tier instead of a model id:

Tier Runs Default
main (inherit) the session's own model the session's model
fast the explorer, model: fast agents (Claude's haiku), compaction summaries venom-fast when the server lists it, else the session's model
smart model: smart agents (Claude's opus) venom-smart when listed, else the session's model
createHarness({
  models: { fast: "qwen3:4b", smart: "venom-smart" },
  escalation: { max: 1, to: "smart" },          // a fast-tier subagent whose work fails a check re-runs once on smart
  agentModels: { reviewer: "venom-smart" },     // a model per agent name
  subagents: { concurrency: 4, maxReportChars: 6000, maxTurns: 25 },
});

subagents.modelTiersFromEnv(env) reads VENOM_FAST_MODEL and VENOM_SMART_MODEL. A tier the server does not list falls back to the session's model with one diagnostic, so a typo never sends a child to a model that 404s. harness.setModelTiers and harness.setAgentModels change them for subagents spawned afterwards.

Limits

Setting Default
subagents.concurrency 4 children at once per harness
subagents.maxReportChars 6000 characters per report
subagents.maxTurns 25 turns
runtime.quotas.maxProcs max(8, concurrency + 1) live processes per session
runtime.quotas.maxTokens, maxCost unlimited; a session-wide budget across all its agents

subagents: false removes the task tool.

Worktrees for writers

Two writing subagents editing the same checkout collide. With isolation: "worktree" (on the task, or isolation: worktree in the agent file), each child gets its own git worktree, created before any child starts; the parent's uncommitted changes are carried over as the base. When a child finishes, its work is committed on its branch, or the worktree is removed when nothing changed, and a note leads its report.

createHarness({ workspaces: { default: "subagents", dir: ".venom/worktrees", branchPrefix: "venom/" } });

workspaces.default is off (the default), session (the session itself runs in a worktree), subagents (every writing subagent gets one) or both; dir defaults to .venom/worktrees, branchPrefix to venom/, and copyIgnored (ignored files copied into a new worktree) to [".env.example"].

@venom/harness/workspaces is the same machinery as a library, no pi: createWorkspace, listWorkspaces, workspaceStatus (dirty, ahead, behind, in use), diffWorkspace, mergeWorkspace (refuses a dirty target or a conflict, found with git merge-tree), applyWorkspace, prWorkspace (push and gh pr create; its only network call, user-invoked), finishWorkspace, removeWorkspace. Errors are WorkspaceError with a code. The CLI's /workspace command and venom session worktrees use it; the user guide is in the automation section.