---
title: Subagents and model tiers
description: 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.
section: harness
order: 60
audience: [builder, agent]
sources: [packages/harness/src/subagents/index.ts, packages/harness/src/subagents/tiers.ts, packages/harness/src/extensions/subagents.ts, packages/harness/src/workspaces/index.ts, packages/harness/builtin/agents]
features: [harness.subagents, harness.workspaces]
---

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 {#task}

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 {#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 {#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 |

```ts
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 {#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 {#worktrees}

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.

```ts
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](/docs/automation.md).

## Related {#related}

- [Sessions, events and cost](/docs/harness/sessions.md#events) (the `subagents` and `agent` events)
- [Model provider](/docs/harness/providers.md#aliases)
- [Claude Code compatibility](/docs/harness/claude-code-compat.md) (agent files)
