Sub-Agents

The subagents server lets one agent delegate work to other configured agents. Each sub-agent resolves its own model, prompts, MCP sources, and tool filters from settings.json.

Configuration

.aether/mcp.json

{
  "servers": {
    "subagents": {
      "type": "in-memory",
      "args": ["--project-root", "."]
    }
  }
}

--project-root loads .aether/settings.json from that directory. --dir is accepted as an alias. When omitted, the server uses ..

Available sub-agents

Only agents with agentInvocable: true can be spawned. The server advertises available sub-agents in its MCP instructions so the parent agent can choose from the registered names.

.aether/settings.json

{
  "agents": [
    {
      "name": "Coder",
      "description": "General coding agent",
      "model": "anthropic:claude-sonnet-4-5-20250929",
      "userInvocable": true,
      "agentInvocable": true,
      "prompts": [".aether/CODER.md"],
      "mcps": [".aether/mcp.json"]
    },
    {
      "name": "Explorer",
      "description": "Read-only codebase exploration agent",
      "model": "deepseek:deepseek-chat",
      "agentInvocable": true,
      "prompts": [".aether/agents/explorer/EXPLORER.md"],
      "mcps": [".aether/agents/explorer/mcp.json"],
      "tools": {
        "allow": [
          "coding__read_file",
          "coding__find",
          "coding__grep",
          "coding__lsp_*"
        ]
      }
    }
  ]
}

Tool filters use exact tool names or a trailing * prefix match. For example, coding__lsp_* is valid.

Tools

Tool	Description
spawn_subagent	Spawn one or more sub-agent tasks in parallel and return all results.

Example

spawn_subagent

{
  "tasks": [
    {
      "agentName": "Explorer",
      "prompt": "Find all public API routes and summarize the routing structure."
    },
    {
      "agentName": "Explorer",
      "prompt": "Read the settings loader and document merge behavior."
    }
  ]
}

The output contains one result per input task, in input order:

{
  "results": [
    {
      "taskId": "task_0",
      "agentName": "Explorer",
      "status": "success",
      "output": "...",
      "error": null
    }
  ],
  "successCount": 1,
  "errorCount": 0
}

agent_name is accepted as an input alias for agentName.

Structured handoff

Aether appends structured-output instructions to each sub-agent prompt. Agents are asked to return JSON with:

Field	Description
summary	Brief summary of what the agent accomplished.
artifacts	Files or resources read, modified, discovered, or relevant.
decisions	Key findings, decisions, or conclusions.
nextSteps	Recommended follow-up tasks.
details	Optional expanded detail.

The tool currently returns the sub-agent’s raw final output string. Parent agents should parse or summarize that output before continuing.

Failure modes

• If no agentInvocable agents are registered and tasks are requested, the tool returns an error and should not be retried until configuration changes.
• If a named agent is missing or not agentInvocable, that task result is returned with status: "error".
• Empty tasks returns an empty result set.