> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bricks.tools/llms.txt
> Use this file to discover all available pages before exploring further.

# Sub-agents

> Create specialized agents for focused tasks

Sub-agents are specialized AI agents that handle scoped tasks within your project. The main agent can delegate work to sub-agents, each with their own tools and instructions.

## Built-in sub-agents

CTOR includes two built-in sub-agents:

| Name      | Description                                                                  | Tools                                     |
| --------- | ---------------------------------------------------------------------------- | ----------------------------------------- |
| `general` | General-purpose agent for research, multi-step edits, commands, and analysis | All built-in tools (except `spawn_agent`) |
| `explore` | Read-only codebase search and exploration                                    | `read_file`, `glob`, `grep`               |

Built-in sub-agents cannot be edited or deleted.

## Managing sub-agents

Click the **Sub-Agents** button in the sidebar toolbar to open the management panel.

### Scopes

Sub-agents are organized into two scopes:

* **Global** — available across all open projects. Stored in `~/.bricks-project-desktop/agents/`.
* **Project** — available only within a specific project. Stored in your project's `.bricks/agents/` directory.

Project-scoped agents override global agents with the same name. Custom global agents override built-in agents with the same name.

### Create a sub-agent

1. Open the **Sub-Agents** panel
2. Select the **Global** scope
3. Click **New Agent**
4. Edit the agent's frontmatter and instructions in the editor
5. Click **Save**

### Agent file format

Sub-agents are markdown files with YAML frontmatter:

```markdown theme={null}
---
name: my-agent
description: Describe when to use this agent
thinking_level: low
tools:
  - read_file
  - glob
  - grep
---

You are a specialized agent. Describe your purpose and instructions here.
```

**Frontmatter fields:**

| Field            | Required | Description                                                                                                                               |
| ---------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `name`           | Yes      | Unique identifier for the agent                                                                                                           |
| `description`    | No       | When to use this agent (shown in the agent card)                                                                                          |
| `model`          | No       | AI model override (e.g., `anthropic/claude-haiku-4-5-20251001`). See [model resolution](#model-resolution)                                |
| `thinking_level` | No       | Thinking level override (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`). See [thinking level resolution](#thinking-level-resolution) |
| `tools`          | No       | List of tools available to the agent                                                                                                      |

When no `tools` list is specified (or set to `null`), the agent receives all built-in tools except `spawn_agent`. To restrict tools, list only the ones you need:

**Commonly used tools:** `read_file`, `glob`, `grep`

### Edit a sub-agent

Click the **edit** button on an agent card to open the editor. Modify the frontmatter or instructions, then click **Save**.

### Delete a sub-agent

Click the **remove** button on an agent card, then click again to confirm. The agent file is permanently deleted.

<Info>
  Changes to agent files on disk are detected automatically. If you edit agent files with an external editor, the panel updates in real time.
</Info>

## Instructions file

Skills can drive a sub-agent (typically `general`) with their own bundled instruction files. When spawning an agent, the main agent can pass an optional `instructions_file` path — a Markdown file whose body is appended to the sub-agent's system prompt under a **Task-Specific Instructions** header.

### How it works

1. The skill bundles an instruction file (e.g. `agents/grader.md`) alongside its `SKILL.md`
2. The main agent spawns a sub-agent with `instructions_file` pointing to that file
3. CTOR strips the file's frontmatter and appends the body verbatim — no templating or variable substitution
4. Any input values the instructions reference (e.g. file paths, configuration) are passed by the caller in the task prompt

### Path resolution

* **Relative paths** resolve against the project root
* **Absolute paths** must live inside one of these allowed directories:
  * The project directory
  * Project or global skill directories
  * Project or global agent directories
  * Bundled skill directories

Paths outside these directories are rejected for security.

### Example

A skill that includes an `agents/grader.md` instruction file:

```
my-skill/
├── SKILL.md
├── agents/
│   └── grader.md       # Instructions for the general sub-agent
└── rules/
    └── conventions.md
```

The `grader.md` file uses standard agent file format:

```markdown theme={null}
---
name: grader
---

Grade the outputs found in the directory specified in the task.
Compare each output against the expectations provided.
Write a summary report to the outputs directory.
```

The main agent spawns the `general` sub-agent with this file, passing concrete values in the task.

## Model resolution

When a sub-agent runs, its model is resolved in this order:

1. **Agent file `model` field** — if the agent file specifies a model, it is used
2. **Settings default** — the default sub-agent model configured in settings
3. **Provider-specific default** — a cost-efficient model for the current provider: `claude-haiku-4-5-20251001` for Anthropic, `gpt-5.4-mini` for OpenAI Codex and GitHub Copilot, `gemini-3.5-flash` for Google, `minimax-m2.5` for OpenCode Zen, `minimax-m2.7` for OpenCode Go
4. **Session model** — the model selected for the current session

This means sub-agents automatically use a cost-efficient model for the active provider, without requiring per-agent configuration.

## Thinking level resolution

When a sub-agent runs, its thinking level is resolved in this order:

1. **Agent file `thinking_level` field** — if the agent file specifies a thinking level, it is used
2. **Settings default** — the default sub-agent thinking level configured in settings
3. **Model-specific fallback** — for reasoning models on the OpenAI Responses API, defaults to `low`