> ## Documentation Index
> Fetch the complete documentation index at: https://docs.seriora.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Subagents

> Built-in roles with their own context window, and agent files you write yourself.

A subagent is a second model run with its own context window, its own tool grant and its own
task. It reports back in text. The point is that a long, noisy piece of work, reading forty files
to answer one question, does not have to spend the main conversation's context to do it.

## The built-in roles

| Role      | Tools                                   | Job                                               |
| --------- | --------------------------------------- | ------------------------------------------------- |
| `explore` | read only                               | read the codebase and report what it finds        |
| `plan`    | read only                               | reason toward a change and describe it            |
| `code`    | everything                              | read, write and run commands to make the change   |
| `test`    | read only, plus `bash` and `powershell` | run the project's own checks and report a verdict |
| `oracle`  | read only                               | advise as a senior engineer                       |

`explore`, `plan` and `oracle` cannot write, and that is structural rather than an instruction
they are asked to follow. Their tool set does not contain a write tool.

<Warning>
  `test` is not in that group. It holds `bash` and `powershell` so it can run your checks, and both
  of those can change the filesystem. A `test` agent is told to report a verdict rather than fix
  what fails, but that is an instruction, not a structural limit. Only `code` can call `write_file`.
</Warning>

## Running one

Two things work, and they are the same two for every agent.

**You run it.** `/explore where does the permission gate live` dispatches immediately, with no
round trip through the main model to decide whether to.

**The model runs it.** Each agent's description is what the model reads when it decides whether
to delegate, so "have someone check this before I push" can reach the right agent on its own.

## Limits that are structural

* **A subagent can never dispatch further subagents.** The dispatch tool is not in any child's
  tool set, so recursion is unrepresentable rather than forbidden.
* **Three tasks per dispatch.** Tasks past the third in one call come back as not-run rows, so
  the model can re-dispatch the rest deliberately.
* **Twenty-five turns per child.** A child does not inherit the session's much larger
  `--max-turns` budget, which would multiply tokens across three concurrent children.
* **A child runs at the parent's permission mode.** Its `bash` re-enters the same gate you are
  sitting behind.

## Writing your own

Drop a Markdown file in `.seri/agents/` for this project, or in your profile root for every
project. seri picks it up at the next start. No source change, no registration step.

```markdown theme={null}
---
name: reviewer                  # optional. The filename without .md is the default.
description: Grades a diff against the plan. Read-only. Never edits code.
tools: Read, Grep, Glob         # seri names (read_file, grep, …) work too, case-insensitively
model: inherit                  # or a concrete id. `some-model[effort=high]` is understood.
effort: high
---

You are a senior reviewer in a FRESH context. Report CRITICAL/HIGH/MEDIUM/LOW findings
with file:line. Do NOT modify any file.
```

`/reviewer grade the diff on this branch` then runs it, and the model can reach it too.

### The frontmatter rules

* **Tool grant precedence.** An explicit `tools` list wins. Otherwise `readonly: true` gives the
  read-only set. Otherwise the agent gets every tool seri has, the same grant `code` holds.
* **Names.** Lowercase letters, digits and `-`. A file that takes the name of a slash command or
  of any routable role is skipped with a warning at startup rather than failing the session. That
  covers the five built-ins and `archivist`, which is a role you cannot dispatch but cannot
  shadow either.
* **Models.** `inherit` or a concrete catalog id. An id the catalog does not carry warns and
  inherits the session model rather than failing.
* **Unknown keys are ignored,** so frontmatter written for another harness does not break here.

The format is the one Cursor and Claude Code already use, so existing agent files work when you
copy them in. seri does not read `.cursor/agents/` or `.claude/agents/` itself. An agent written
for another harness's toolset auto-loading here is a surprise, not a convenience.

[Where files live](/reference/files) covers project scope against profile scope.