Subagents

A subagent is a named helper to which Polygent Code delegates a self-contained task while keeping the parent session focused. For the controls that can further restrict a helper, see Harness tool and MCP scoping.

Access and scope

Subagents are managed centrally and are exposed according to User Settings, the session source, and workspace capability limits.

Open Developer Tools → PolygentCode → Subagents. Select a subagent card to edit it, or use its switch and actions menu independently.

Permission	Capability
View Subagents	View subagent definitions.
Manage Subagents	Create, edit, enable, disable, and delete custom subagents; edit permitted built-in settings.

Custom subagents must be enabled and selected by a supported non-bot session source, and the Custom subagents by default User Setting — off by default — must be turned on. Bots use only the built-in explorer; start-ticket templates cannot select custom subagents.

Built-in subagents

Built-in subagents provide safe defaults for common delegation modes.

Name	Characterization	Typical effective capability
general	General-purpose helper for implementation and verification.	Read, search, skills, edit, file management, Bash, web fetch, and task lists.
editor	Edit-capable helper for environments where command execution is unavailable.	Read, search, skills, edit, and file management; no Bash.
explorer	Read-only helper for research and repository discovery.	Read, search, and skills only.
advisor	Read-only helper that unblocks a stuck session.	Read, search, and skills only.

Built-in subagents cannot be deleted or disabled, and their name, prompt, and tools are fixed. Their model, MCP servers (all enabled servers by default), and skills can be edited and remain bounded by the parent session's capabilities. With the default Auto-assign by session type, a session that can edit files gets general and other sessions get explorer. A helper never receives a capability its parent lacks.

Create a custom subagent

A custom subagent packages one clear role with an explicit privilege boundary.

1. Open Developer Tools → PolygentCode → Subagents.
2. Select Create Subagent.
3. Enter a unique name and a description that tells the parent agent when to delegate.
4. Write the system prompt with the expected task, boundaries, and return format.
5. Choose Max (Challenges), High (Complex tasks), Default (Daily use), Instant, Inherit from parent, or a specific model. A default tier uses the model and reasoning effort currently configured for that tier when the subagent runs. Inherit from parent remains separate and uses the calling session's model.
6. Select only the required tools, MCP servers, and Polygent MCP tools.
7. Enable and save the subagent.
8. Select it in the intended session source and test it in a new session.

Setting	Operational effect
Name	Identifier used during delegation. Keep it stable after adoption.
Description	Discovery text used to decide when the helper applies.
Prompt (System Prompt)	Role, constraints, expected result, and escalation conditions.
Model	One of four system-wide default tiers, Inherit from parent, or a fixed model.
Allowed Tools	File, search, command, web, and other direct capabilities.
MCP Servers	External MCP servers the helper may connect to.
MCP Tools	Individual tools of those servers; empty allows every tool of the selected servers.
Polygent MCP Tools	Built-in Polygent operations available to the helper.
Skills	Skills the helper may load.
Enabled	Whether supported sessions may expose the custom subagent.

An explicit empty capability selection means none. Workspace capability limits and parent-session restrictions can only reduce the configured set.

Subagents cannot start further subagents. A delegated task is stopped after 30 minutes, and its model spend counts toward the parent session's cost and budgets. Every delegated conversation can be opened read-only from the parent session's chat.

Security boundary

A subagent is a separate capability boundary, not a way to bypass parent-session restrictions. It inherits the parent session's effective read/write guard, prompt-injection guard, and web-access behavior; its stored definition cannot relax them.

• Grant Bash and file writes only when the role requires them.
• Prefer explorer or a read-only custom subagent for broad research.
• Restrict write-capable MCP tools independently from read-only MCP tools.
• Treat external MCP output and web content as untrusted.
• Do not put secrets in system prompts.
• Review model and MCP changes to built-ins because they affect many sessions.

Built-in MCP calls inherit the parent run's credential, workspace, and tool grants; see MCP Server security.

Troubleshooting

Subagent troubleshooting compares the stored definition with the effective parent-session boundary.

Symptom	Resolution
Custom subagent is not listed	Turn on Custom subagents by default, confirm the subagent is enabled and selected by the session source, and check the capability ceiling. Start a new session.
Wrong built-in is available	Review Built-in subagent behavior and the parent session's file-write and Bash capabilities.
Tool is missing inside the subagent	Check the subagent selection, parent-session selection, workspace limits, and applicable User Settings. The most restrictive control wins.
MCP tool is missing	Confirm the server is selected and reachable, then explicitly grant the tool or whole server. For remote workers, verify the configured MCP URL from the worker network.
Delegation is repeatedly inappropriate	Tighten the description and system prompt so the role and trigger are explicit.
Delegated task lacks useful output	Require a concise conclusion, changed-file list when applicable, validation result, and blockers in the system prompt.