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.
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.
Related
- Sessions, events and cost (the
subagentsandagentevents) - Model provider
- Claude Code compatibility (agent files)