# Subagents

Delegate a self-contained task to an autonomous subagent with its own context window — it works in isolation and returns one tight report, so the main thread never fills up with exploration.

A **subagent** is a fresh agent that does one self-contained task on its own and sends back a short report. Use one for a big investigation, like "map how auth works across these 12 files". The subagent has its **own context window** and its own tools, so its reading and tool output never fill up your main conversation. Only the report comes back.

Subagents run through the built-in **`task` tool**. The model starts one by itself when a job is worth splitting off, and you can also ask for one ("spawn an explorer to map the render pipeline").

## Built-in agent types

Each type is a role with a tailored system prompt and a tool allowlist. `general` is the default.

| Type | Role | Access |
|------|------|--------|
| **`explorer`** | Map and explain a codebase region — trace call sites, cite exact file:line | read-only |
| **`reviewer`** | Critically review code/changes — bugs, edge cases, races, security; prioritised findings | read-only |
| **`tester`** | Reproduce, run, and diagnose — build/run tests, report root cause with the failing assertion | read + run (no prod edits) |
| **`coder`** | Implement a change end-to-end, verify it builds | read + write |
| **`general`** | Complete any delegated task with whatever tools fit (default) | full toolset |

Read-only types (`explorer`, `reviewer`) are physically prevented from writing files, running commands, or reaching the network — the sandbox rejects any tool with a write/exec/net effect, so a review can't accidentally mutate your tree.

:::tip
Fan out. Because each subagent is isolated, the model can launch several in parallel — three explorers over three subsystems — and merge their reports, without any of them polluting each other's or the parent's context.
:::

## Custom agent types

Drop a Markdown file in `.agentty/agents/` (project) or `~/.agentty/agents/` (all projects). The **body is the role's system prompt**; optional frontmatter configures its sandbox:

```markdown
---
description: Reviews SQL migrations for safety.   # shown in the catalog
tools: read grep glob list_dir                    # optional allowlist (space-separated)
read-only: true                                   # optional effect gate
---
Your role: MIGRATION REVIEWER. Check every migration for destructive
operations, missing transactions, and non-idempotent DDL. Report each
issue with the file and line and a safer rewrite.
```

| Field | Meaning |
|-------|---------|
| `description` | one-line summary for the subagents catalog and the `task` tool's type list |
| `tools` | space-separated allowlist — the agent may use only these tools (omit for all) |
| `read-only` | `true` blocks every write/exec/net tool, exactly like `explorer`/`reviewer` |
| *(body)* | the role prompt the subagent runs under |

The file name (without `.md`) is the type name you pass as `agent_type`. Search roots, project first: `.agentty/agents`, `.agents/agents`, `.claude/agents`, then the same three under your home directory. **Built-ins always win** — a `general.md` can't silently replace the built-in `general`. Files are picked up live (no restart); up to 32 custom agents, 32 KiB each.

:::note
A persona defined in a **project** `.agentty/agents/` can ride in on a cloned repo, and its role prompt steers a subagent that wields real (sandboxed) tools. That's a lower risk than a plugin — an agent names no command, its tools stay gated, and it runs only when invoked — so it isn't blocked, just **surfaced**: the task card tags a project-defined agent as `project agent` so an injected persona is never invisible. Built-in and your own `~/.agentty` agents show no tag. See [Plugin Trust](/docs/plugin-trust#a-related-case-project-defined-agents).
:::

## Managing subagents in the app

[[Ctrl+K]] → **Subagents** lists the built-in types and every custom agent it discovered, and can drop a starter template into `.agentty/agents/` to author from. Authoring is a file you edit; the panel is for browsing what's available.

## How a subagent runs

- **Isolated & autonomous.** It never sees the parent conversation and can't ask it questions — it works from the task prompt alone, makes a reasonable assumption on ambiguity (and notes it), then stops and writes a tight, evidence-cited report. The report is the *only* thing the parent receives.
- **Bounded, per role.** Each subagent runs a capped burst — 8 K output tokens, tool results clipped, and a turn budget sized to the work: **32 turns** for read-only roles (explorer, reviewer), **80** for write roles (coder, tester, general). A read sweep converges quickly; an implementation loop is read → edit → build → read the errors → fix → re-run, which is several turns per cycle and several cycles per task. These are ceilings, not quotas — an agent that finishes in five turns costs five. Everything stays comfortably inside the base 200 K window, so a fan-out stays cheap. It never uses the 1M-context beta.
- **Prompt-cached.** The heavy shared prefix (system prompt + tool schemas + accumulated results) is cached across the subagent's turns, keyed per role + task, so a long investigation doesn't re-pay for its prefix every turn.
- **Gated twice.** A role only sees the tools it's allowed, and a call to any other tool is refused when it arrives, so a read-only role can't write even if the model names a tool it wasn't offered.
- **Same prompt rules as the main turn.** On a model you run yourself (a local or LAN server), a subagent gets the short local-model prompt the main turn uses, with its "do the work with tools, don't refuse a big task" rules. See [Providers › The prompt local models get](/docs/providers#the-prompt-local-models-get).
- **Rate limits.** A short rate limit is retried up to 3 times, waiting what the provider asks for (at most 30 s). If the provider says to wait more than 15 minutes, that's a quota, and the subagent stops and reports it instead of waiting.

`agentty run` is this same loop with your prompt as the task, so everything here applies to it too. See [agentty run](/docs/cli#agentty-run).

## Model routing

By default, **read-only roles** (`explorer`, `reviewer`) are routed to the **cheapest capable model** your active provider offers — mapping, reading, and reviewing are grunt work a small model does well — while **write-capable roles** (`coder`, `tester`, `general`) keep the parent model so their edits match its quality. The router never routes *up* and never crosses providers, so a single-model or Opus-only account sees no change.

With [Smart Mode](/docs/smart-mode) subagent routing enabled, each worker's model is resolved by its **role** through your pinned model slots instead (explorer → Utility, reviewer → Strategic, coder/tester/general → Implementation).

## Related

- [Smart Mode](/docs/smart-mode) — role-based routing that decides which model each subagent runs on.
- [Tools](/docs/tools) — the tools a subagent can be allowed.
- [Sandboxing & permissions](/docs/sandboxing) — how read-only enforcement and tool gating work.
