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
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.
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.
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.
/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 covers project scope against profile scope. 
