Sub-agents

What this accomplishes

The sub-agent system: a generic registry of named sub-agents invoked via @ mentions, running as background agent sessions with their own system prompts and tool access.

A sub-agent is a background agent session that runs while the main session continues. The sub-agent has its own system prompt, its own tool calls, and its own model. The sub-agent reports its output back to the main session when it finishes.

This page is the sub-agent system in detail. The high-level introduction is in the overview.

Current availability

This page documents behaviour verified in Miton development builds. Miton is still pre-release and is not publicly downloadable; invited beta users will receive a signed desktop build with automatic updates.

Before you start

• A Miton development build and an active project containing source code.
• A connected model. Trust the project before allowing file, terminal or Git actions.

The registry

Sub-agents are stored in a SubagentRegistry (packages/subagent/). Each sub-agent is a SubagentDefinition with a name, a display name, a description, a system prompt template, a set of allowed tools, and optional model and token-budget overrides.

The registry is populated at startup from bundled markdown files with YAML frontmatter. Users and plugins can register additional sub-agents at runtime.

The eight default sub-agents

Miton ships with eight default sub-agents. Each is a prompt template registered in the SubagentRegistry at startup.

Explorer

The Explorer reads the codebase to answer a question. The Explorer does not write files. The Explorer is the right choice when the user wants a quick map of the code or a specific question answered.

Tools: read, glob, grep. Model preference: fast.

Verifier

The Verifier runs the project’s tests, type-checker, and linter to verify code correctness. The Verifier does not write code.

Tools: read, glob, grep, bash. Model preference: fast.

Debugger

The Debugger investigates a failing test or a runtime error. The Debugger can run shell commands to reproduce the issue, form hypotheses, and propose a fix.

Tools: read, glob, grep, bash. Model preference: reasoning. Max output: 16,384 tokens.

Test Runner

The Test Runner runs the project’s tests, analyses failures, and suggests fixes for failing tests.

Tools: read, glob, grep, bash. Model preference: default. Max output: 8,192 tokens.

Orchestrator

The Orchestrator plans and coordinates multi-step tasks. It can read, write, run shell commands, and ask clarifying questions.

Tools: read, glob, grep, bash, write, question, todo. Model preference: reasoning. Max output: 32,768 tokens.

Researcher

The Researcher investigates one subtopic as one of several parallel research sub-tasks and returns a cited report — headline, source URLs, key quotes, data points, a confidence rating per claim, and any open questions. It sees only its own sub-task, not the other parallel sub-tasks’ findings, and never asks the user for clarification.

Tools: web_search, web_fetch, browser_panel_read, preview_screenshot. Model preference: default. Max output: 16,384 tokens.

Designer

The Designer critiques and improves visual designs, generates assets, and applies Canvas patches.

Tools: canvas_read, canvas_edit, image_generate, web_fetch, preview_screenshot, read. Model preference: reasoning. Max output: 16,384 tokens.

Analyst

The Analyst loads a data file, cleans it, runs exploratory analysis with pandas, generates matplotlib visualisations, and produces plain-language findings with confidence levels. Analysis code runs in a sandboxed Pyodide worker with no network access and a conservative blocklist (eval, exec, subprocess, raw sockets, and similar are rejected before execution); large downloads or scraping have to go through web_fetch first.

Tools: read, data_ingest, data_analyse, bash, write. Model preference: default. Max output: 16,384 tokens.

How to spawn a sub-agent

Sub-agents are spawned via @<name> mention dispatch. Type @explorer, @verifier, @debugger, @test-runner, @orchestrator, @researcher, @designer, or @analyst in the message composer (or in a chat message) followed by the task description. The mention parser resolves the name against the SubagentRegistry and spawns a background agent session.

Example: @explorer where is the user authentication code?

The sub-agent runs as a background session. The main session is not blocked. When the sub-agent finishes, its output is injected into the chat as a synthetic assistant message. The output is also stored in the subagentStore for the Specialists dashboard.

How sub-agents execute

A spawned sub-agent runs as a background agent session:

1. The system prompt template is populated with the task description ({{task}} replacement).
2. A agent loop is created with the sub-agent’s allowed tools and model.
3. The agent loop runs up to 15 turns (configurable per sub-agent).
4. Output is capped at the sub-agent’s maxOutputTokens limit (if set).
5. A hard USD cost ceiling can be enforced via the maxCost option.
6. When the loop finishes, the result is reported back via callbacks.

The sub-agent’s session is independent of the main session. The main session’s context, tools, and model are not affected.

The subagent review gate

By default, a stronger model checks each completed sub-agent’s output before it is added to the main conversation. If the reviewer approves the output, it goes through unchanged; if the reviewer rewrites it, the rewrite is what lands in the conversation and the original output is kept as evidence. The chat shows a “reviewed by <model>” (approved or rewritten) badge, or a “not reviewed (<reason>)” badge when review was skipped. You can turn this off in Settings → Sub-agents (“Review sub-agent output with a stronger model”).

The Specialists dashboard

The Specialists dashboard (titled Specialists in the app; implemented in components/agent/AgentManagerDashboard.tsx) shows all sub-agent runs for the current project. Each run displays:

• Status — running, completed, failed, or cancelled.
• Output — the sub-agent’s text output.
• Cost — the model cost (if reported by the provider).
• Duration — wall-clock time from start to finish.

The dashboard also sets the default cost ceiling ($0.10 / $0.50 / $2.00 / unlimited) and time ceiling (30s / 2min / 10min / unlimited) applied to new sub-agent runs. When a running sub-agent crosses either ceiling, Miton cancels that run automatically — there’s no pause-and-confirm step.

The dashboard is the audit trail for sub-agent work. The user can review what each sub-agent did, what it cost, and whether it succeeded.

Specialist teams (dynamic rosters)

Named sub-agents are a fixed roster. For a novel objective that doesn’t fit one of them, the agent can call a separate planner (the specialist_team tool) to design a task-specific team of temporary Specialists — as many distinct roles as the objective needs, each with its own responsibility, tools, and model route.

The planner’s proposal never runs on its own. Miton validates the roster, resolves a model route for each Specialist, and posts the proposal in Chat as a card you review. From that card you can:

• Accept team — run the roster as proposed.
• Remove a Specialist you don’t want.
• Edit a Specialist’s responsibility.
• Reduce limits — lower a Specialist’s cost ceiling.
• Request revision — send the planner back with a note on what to change.
• Cancel team — drop the whole proposal.

Once accepted, the Specialist team runs through the same worktree, permission, and cost-tracking path as any other sub-agent run, and reports back into the Specialists dashboard and the final build receipt (see Transparency and approvals).

What the sub-agent system does not cover

• Worktree isolation — a write-capable sub-agent takes an exclusive lease on the active worktree. When that lease is already held by another writer, Miton instead creates a linked git worktree under .miton/worktrees/<runId> on its own branch and opens an Apply / Discard / Keep review when the run finishes. Read-only sub-agents share the active checkout. See Git and worktrees for the full mechanism.
• Per-sub-agent permission gates — sub-agents use the same permission policy as the main session. There is no per-sub-agent policy override in the current implementation.
• User-defined sub-agent files — there is no .miton/subagents/ directory convention. Custom sub-agents are registered programmatically via the SubagentRegistry API or by plugins.

What success looks like

Sub-agents are background agent sessions you spawn with @<name> mentions. There are eight defaults: Explorer (code reading), Verifier (tests and lint), Debugger (failure investigation), Test Runner (continuous testing), Orchestrator (multi-step coordination), Researcher (cited web research), Designer (visual design and Canvas patches), and Analyst (data analysis and charts). For an objective that doesn’t fit any of these, the agent can propose a temporary Specialist team instead.

The sub-agent runs in the background; the main session continues. A stronger model reviews its output by default before that output reaches the conversation. When the run finishes, the output appears in the chat and in the Specialists dashboard. Write-capable sub-agents take a worktree lease (or an isolated .miton/worktrees/ checkout when the lease is busy); read-only agents share the active checkout.

Common failures and recovery

• Confirm the correct project and branch are active.
• Check the model connection and the permission request shown in Chat.
• Keep the exact error before retrying; use Code troubleshooting when the failure persists.

Related next action

Open Code troubleshooting for recovery steps and diagnostic paths.