Sub-Agents

Sub-agents are specialized agents that the main agent can spawn to handle complex, multi-step tasks. Each sub-agent runs with its own prompt, tool set, and optional model override.

Persistent, interactive subagents

For an agent you want to watch, talk to directly, and revisit later, use /term. Ante can launch another Ante instance, Claude Code, or Codex in a named terminal, send it work, read its output, and follow up. You can join the same terminal at any time, detach while it keeps running, and reconnect after restarting the main Ante.

Each terminal agent has its own conversation and process lifetime. Use its native fork command to branch a saved conversation, or ask Ante to hand the task and relevant context to a fresh session. The TUI walkthrough shows both approaches. The built-in Agent tool described below handles delegated tasks that return a result to the parent; /term sessions are managed through the terminal picker and the program running inside them.

Built-in sub-agents

Ante ships with two built-in sub-agents:

general

A general-purpose agent for researching complex questions, searching for code, and executing multi-step tasks. The main agent delegates to this when it needs to perform a search it isn't confident about completing in a few tries.

explorer

A fast agent specialized for codebase exploration. It can quickly find files by patterns, search code for keywords, and answer structural questions about the codebase.

Questions about Ante itself are handled by the bundled ante-guide skill, not a sub-agent.

Creating custom sub-agents

Create a markdown file in ~/.ante/agents/ (user-level) or any of the project-level locations below with YAML frontmatter:

---
name: security-reviewer
description: Reviews code for security vulnerabilities and OWASP top 10 issues
tools:
  - Read
  - Grep
  - Glob
---

You are a security-focused code reviewer. Analyze the provided code for:

- Injection vulnerabilities (SQL, command, XSS)
- Authentication and authorization flaws
- Sensitive data exposure
- Security misconfiguration
- Known vulnerable dependencies

Provide findings with severity ratings and remediation steps.

Frontmatter fields

Field	Required	Description
name	Yes	Unique identifier for the agent
description	Yes	What this agent does (shown to the main agent for delegation decisions)
model	No	Override the LLM model for this agent
tools	No	Restrict which tools this agent can use

Frontmatter is read the same way as skill frontmatter: common unquoted-scalar mistakes are repaired when they can be interpreted unambiguously, and the block is capped at 16 KB and 32 levels of nesting. Past either limit, or on YAML that cannot be repaired, the agent fails to load with an explicit error.

How sub-agents work

When the main agent encounters a task that matches a sub-agent's description, it uses the Agent tool to spawn the sub-agent:

1. The main agent evaluates available sub-agents and their descriptions
2. It delegates the task via the Agent tool with a detailed prompt, optionally specifying a per-call model override
3. The sub-agent runs independently with its own context
4. The sub-agent’s final answer and deliverables are returned directly to the main agent

Watch sub-agents work

While sub-agents run, the footer lists each one with its task, runtime, and token count. With the composer empty, press ↓ to select one and Enter to open its live transcript. Inside, ↑/↓ and Enter switch to another agent, PgUp/PgDn scroll, and Esc returns to the chat.

A sub-agent inherits the skills equipped in the parent session, so skill-driven workflows keep working inside delegated tasks. Delegation is one level deep: a sub-agent never carries the Agent tool, so it cannot spawn further sub-agents, and does not receive the AskUser tool.

A custom definition supplies task-specific instructions. Sub-agents complete a single unattended task and cannot ask you follow-up questions, so include the required inputs and expected output in the delegated task.

Subtasks can specify an individual model parameter on the Agent tool call. If omitted, the subtask falls back to the agent definition's model if configured, and then to the current session model.

Each sub-agent runs in auto permission mode under an unattended policy. Safe calls proceed without prompting; a call that would require approval is denied immediately, and commands classified as destructive are never admitted. The child does not inherit the parent's permission mode or saved allow rules, because there is no visible prompt where a person could approve or persist a grant.

Token and cache usage from a sub-agent is forwarded into the parent session's totals and appears in /usage. Its context-window snapshot stays private, so delegated work does not overwrite the root session's context indicator.

┌────────────┐     Agent     ┌──────────────┐
│ Main Agent │ ────────────▶ │  Sub-Agent   │
│            │ ◀──────────── │  (Explorer)  │
│            │    Result     └──────────────┘
│            │
│            │     Agent     ┌──────────────┐
│            │ ────────────▶ │  Sub-Agent   │
│            │ ◀──────────── │  (General)   │
└────────────┘    Result     └──────────────┘

Concurrency limit

Set max_concurrent_subagents in ~/.ante/settings.json, a named profile, or project settings to cap running subagents per session. For example, for a local model that handles one request at a time:

{ "max_concurrent_subagents": 1 }

Omitted, null, or 0 means unlimited. Calls beyond the cap report waiting for a subagent slot and wait before opening a model stream, so queue time does not consume the provider idle timeout. Interrupting the parent turn cancels the wait. The setting is read when a session starts or resumes; it has no CLI flag or SessionRequest field.

Discovery

Sub-agents are discovered in precedence order (later overrides earlier by name):

1. Built-in agents (general, explorer)
2. ~/.ante/agents/ (user-level)
3. .agents/agents/ (project-level)
4. .ante/agents/ (project-level)
5. .claude/agents/ (project-level, Claude Code compatibility)

User and project agents are loaded alongside the built-in ones when a session starts. Ante tells the main agent which sub-agents are available for delegation.