Skip to main content
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.
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 for release history.
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:
  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

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. Prerequisites
  • Decide whether the subagent belongs in personal defaults, shared project settings, or personal project settings.
Steps
  1. Add each definition under subagents.agents.
    Example: Configure a named in-process subagent
  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.
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:
Example: Reuse a configured ACP server
For the agent_servers schema, see 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:
Example: Customize the general subagent
To remove it from the available subagents:
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. 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. 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.