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

# Subagents

> Delegate focused work to built-in or custom subagents with separate context.

Use subagents when a task benefits from a separate agent with focused instructions, a different ACP server, or independent context. The main agent chooses a subagent, sends it a task, and incorporates its result into the current turn.

<Info>
  This documentation describes Poolside Agent CLI v1.0.16. Check your version with `pool --version`. To update, exit any active session and run `pool update` from your terminal. See [Poolside Agent CLI releases on GitHub](https://github.com/poolsideai/pool/releases) for release history.
</Info>

Poolside includes a general-purpose subagent named `general`. You can also define named subagents in `settings.yaml`.

The main agent can delegate without an explicit request. Ask it to use a named subagent when you want to control the choice.

## Delegate to the built-in subagent

The built-in `general` subagent is available without configuration.

**Steps**

1. Start `pool` in your project.

2. Ask the main agent to delegate a focused task:

   ```text theme={null}
   Delegate repository research to the general subagent. Find where authentication is configured and report the relevant file paths without editing files.
   ```

3. After the turn finishes, run `/usage`.

The main agent incorporates the subagent's findings into its response. The usage report lists `general` under **Sub-agents** when the subagent reports usage.

## Choose a subagent type

| Type           | What runs                                                          | When to use it                                                               |
| -------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------------- |
| `in_process`   | A Poolside agent in the current `pool` process                     | Create a named Poolside subagent without starting another ACP server process |
| `command`      | A command that starts an ACP server over standard input and output | Run a custom ACP-compatible agent                                            |
| `agent_server` | A command-based entry from the top-level `agent_servers` settings  | Reuse an ACP server definition that you also use with `pool --agent-server`  |

The reserved `general` subagent must use `in_process`. Other named subagents can also use `in_process`. An `agent_server` subagent must reference a command-based server. It cannot use a remote `url` entry.

Before you use `command` or `agent_server`, install the ACP server command you want the subagent to run.

## Configure a named subagent

Define subagents under the top-level `subagents` key in any supported `settings.yaml` file. For file locations and precedence, see [Settings file reference](/settings-file-reference#file-locations-and-precedence).

**Prerequisites**

* Decide whether the subagent belongs in personal defaults, shared project settings, or personal project settings.

**Steps**

1. Add each definition under `subagents.agents`.

   ```yaml title="Example: Configure a named in-process subagent" theme={null}
   subagents:
     default: reviewer
     agents:
       reviewer:
         type: in_process
         description: Reviews a completed change for correctness and test coverage.
         instructions: |
           Inspect the diff and relevant tests.
           Report findings without editing files.
   ```

2. Start a new agent session so the updated definitions are available.

3. Ask the main agent to delegate to the named subagent, or let it choose based on each description.

   ```text theme={null}
   Ask the reviewer subagent to inspect this diff for correctness.
   ```

Descriptions tell the main agent which subagent to choose. Every enabled custom subagent must have a description.

## Reuse an agent server definition

Set `type: agent_server` and reference a command-based entry from `agent_servers`:

```yaml title="Example: Reuse a configured ACP server" theme={null}
agent_servers:
  specialist-server:
    command: <acp-server-command>
subagents:
  agents:
    specialist:
      type: agent_server
      description: Handles tasks that need the specialist agent.
      agent_server: specialist-server
```

For the `agent_servers` schema, see [Agent servers](/settings-file-reference#agent-servers).

## Customize the built-in subagent

The built-in `general` subagent uses Poolside's agent in the current `pool` process. By default, it inherits the main session's model, agent configuration, available MCP servers, and repository configuration. It cannot ask you clarifying questions during its task or delegate again, so give it a self-contained request.

Add a `general` entry to change its instructions or turn it off. An enabled `general` entry must use `in_process`; any other `type` is a configuration error and the session fails to start:

```yaml title="Example: Customize the general subagent" theme={null}
subagents:
  agents:
    general:
      instructions: Focus on repository research and return concise evidence.
      inherit_agent_config: true
```

To remove it from the available subagents:

```yaml theme={null}
subagents:
  agents:
    general:
      disabled: true
```

If `general` is available and you do not set `subagents.default`, it is the default. If you turn it off and only one custom subagent remains, that subagent becomes the default. If multiple custom subagents remain, set `subagents.default` explicitly.

## Configuration reference

Subagent names must contain 1 to 64 letters, numbers, underscores, or hyphens. The name `general` is reserved for the built-in subagent.

| Key                                              | Type    | Description                                                                                                                                                                                                                            |
| ------------------------------------------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `subagents.default`                              | string  | Subagent to use when a delegation does not name one                                                                                                                                                                                    |
| `subagents.agents.<name>.type`                   | string  | Launch type: `in_process`, `command`, or `agent_server`                                                                                                                                                                                |
| `subagents.agents.<name>.description`            | string  | Description the main agent uses when choosing a subagent. Required for enabled custom subagents.                                                                                                                                       |
| `subagents.agents.<name>.instructions`           | string  | Instructions prepended to every task sent to the subagent                                                                                                                                                                              |
| `subagents.agents.<name>.command`                | string  | ACP server executable. Required for `type: command`.                                                                                                                                                                                   |
| `subagents.agents.<name>.args`                   | list    | Arguments passed to `command`                                                                                                                                                                                                          |
| `subagents.agents.<name>.env`                    | map     | Environment variables added to the command process                                                                                                                                                                                     |
| `subagents.agents.<name>.agent_server`           | string  | Top-level `agent_servers` entry. Required for `type: agent_server`.                                                                                                                                                                    |
| `subagents.agents.<name>.session_config_options` | map     | ACP session configuration IDs and values to apply to the subagent session. Supported IDs and values depend on the ACP server; unsupported IDs are ignored.                                                                             |
| `subagents.agents.<name>.inherit_agent_config`   | boolean | Send the main session's model, agent configuration, MCP servers, and repository configuration when the ACP server supports Poolside session configuration metadata. Defaults to `true` for `general` and `false` for custom subagents. |
| `subagents.agents.<name>.disabled`               | boolean | Remove the subagent from the available set when `true`                                                                                                                                                                                 |

Settings merge from personal defaults to shared project settings to personal project settings. A more specific definition overrides non-empty scalar values. The `env` and `session_config_options` maps combine by key. Changing `type` clears launch fields from the earlier type. Explicit `disabled` and `inherit_agent_config` values override earlier values.

## Permissions and agent mode

Poolside starts subagents in Build mode, so they can edit files and run tools subject to the active permissions. You review their approval requests in the parent session. Poolside's in-process subagents cannot delegate to another subagent.

The main agent can run multiple subagents at the same time. They share the workspace, so parallel changes to the same files can conflict.

Subagents normally receive the parent's approval mode. If the parent uses **Auto**, the subagent uses **Accept edits** instead, so its actions are not sent to the classifier. For Auto mode details, see [Auto mode](/permissions#auto-mode).

In an interactive terminal, `pool exec` prompts for subagent approvals like any other action. In a non-interactive run, actions that need confirmation are cancelled unless you pass `--unsafe-auto-allow`, which applies to the parent and its subagents.

## Review subagent usage

Run `/usage` to see separate totals for the parent agent, each subagent name, and the complete session. If a named subagent runs more than once, `pool` combines those runs into one total. The context tooltip also includes session cost with subagents when cost data is available.

Custom ACP servers can run their own nested subagents. Their usage is included only when the custom server reports it to `pool`. Poolside's in-process subagents cannot run nested subagents.

## Related resources

* [Work from the terminal](/cli/interactive-mode)
* [Permissions](/permissions)
* [Settings file reference](/settings-file-reference)
* [Use other agent servers](/cli/other-agent-servers)