Subagents

Subagents let the Spectral coding agent delegate work to specialized sub-agents. Each sub-agent runs in an isolated context window with its own system prompt, filtered tool set, and optional model override — keeping the main conversation lean and focused.

How It Works

┌──────────────────────────────────────────┐
│            Main Agent Session             │
│                                          │
│   User: "Review all auth files"          │
│         │                                │
│         ▼                                │
│   subagent({ agent: "reviewer",          │
│              task: "Review src/auth/" }) │
│         │                                │
│         ▼ (isolated context)             │
│   ┌──────────────────────────┐          │
│   │  Sub-agent: reviewer     │          │
│   │  Tools: read, grep, ls   │          │
│   │  Model: claude-haiku-4-5 │          │
│   │  → reads auth files      │          │
│   │  → produces review       │          │
│   └──────────┬───────────────┘          │
│              │                           │
│              ▼                           │
│   Main agent receives review result     │
│   → continues with the output           │
└──────────────────────────────────────────┘

Defining an Agent

Agents come from two sources only:

1. Built-in system agents — compiled into the CLI (ghost orchestrator plus researcher, executor, reviewer, and fork subagents). Read-only.
2. Cloud agents — your team's agents, managed in Aexol Studio on the /agents page and synced to the CLI through the backend.

Local agent folders are not read. Files in ~/.spectral/agent/agents/ or .spectral/agents/ do not produce agents — create and manage agents in Studio (/agents) instead.

Example: Code Reviewer

Frontmatter Fields

Available Tools

Built-in tools: read, bash, apply_patch, bash_status, bash_kill.

Extension-registered tools (like recall, designer_*) are also resolved dynamically — any tool registered by loaded extensions is available, minus the subagent-excluded tools: subagent, compact_context, receive_agent_observations, and share_project_observation.

Execution Modes

The agent invokes subagents through the subagent tool with three modes:

Single Mode

Delegate one task to one agent:

{
  "agent": "reviewer",
  "task": "Review all route handlers in src/routes/ for missing error handling"
}

Parallel Mode

Run up to 8 tasks in parallel (max 4 concurrent):

{
  "tasks": [
    { "agent": "reviewer", "task": "Review src/auth/" },
    { "agent": "reviewer", "task": "Review src/api/" },
    { "agent": "doc-writer", "task": "Generate docs for packages/parser/" }
  ]
}

Chain Mode

Sequential execution where each step sees the previous output via {previous}:

{
  "chain": [
    { "agent": "investigator", "task": "Find all type errors in the project" },
    { "agent": "fixer", "task": "Fix the following errors: {previous}" }
  ]
}

If any step fails, the chain stops and returns the error.

Context Isolation

Each sub-agent invocation gets:

Agent Discovery

Discovery merges two layers — later layers override earlier ones on name collision (a cloud agent replaces a built-in system agent with the same name):

Cloud agents are always enabled — there is no agentScope parameter on the subagent tool anymore. Discovery never throws and never touches the network: offline or logged-out sessions simply get the built-in system agents.

Model Resolution

Sub-agents resolve their model in this order:

1. Session model (if available and has configured auth)
2. Agent-configured model (from the model frontmatter field)
3. Error — if neither is available

The model string supports two formats:

• Short: claude-sonnet-4-5 (fuzzy match by model ID)
• Fully qualified: anthropic/claude-sonnet-4-5 (exact provider + model ID)

Example Agents

Documentation Writer

---
name: doc-writer
description: Generates API documentation from source code
tools: read, grep, find, ls
model: claude-sonnet-4-5
---

You are a technical writer. When given a source file or directory:
1. Read the code thoroughly
2. Extract the public API surface (exports, functions, classes, types)
3. Write clear, concise documentation with examples
4. Output valid Markdown suitable for API references

Test Generator

---
name: test-gen
description: Generates unit tests for uncovered code paths
tools: read, grep, find, ls, bash, write
model: claude-sonnet-4-5
---

You are a test engineer. When given a source file:
1. Read the file and its existing tests (if any)
2. Identify uncovered branches and edge cases
3. Generate thorough unit tests following project conventions
4. Write the test file using the `write` tool

Agents vs. Extensions

Next Steps

• Extensions
• Observational Memory