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 Dev Tools → Polygent Code → Subagents. Select a subagent card to edit it, or use its switch and actions menu independently.

Permission	Capability
subagents.view	View subagent definitions.
subagents.manage	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. The Custom subagents by default User Setting must also permit exposure. Bots use their fixed read-only delegation behavior and do not 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, edit, command, search, and permitted web access.
editor	Edit-capable helper for environments where command execution is unavailable.	Read, edit, and search without Bash.
explorer	Read-only helper for research and repository discovery.	Read and search only.

Built-in definitions cannot be deleted. Their editable model and MCP settings remain subject to the parent session's effective capabilities. Automatic assignment chooses a helper appropriate to the session; a helper must not receive a capability unavailable to its parent.

Create a custom subagent

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

1. Open Dev Tools → Polygent Code → 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. Select a model or inherit the parent 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.
System prompt	Role, constraints, expected result, and escalation conditions.
Model	Fixed model or inheritance from the parent session.
Allowed tools	File, search, command, web, and other direct capabilities.
Allowed MCP servers	External MCP connections available to the helper.
Allowed Polygent MCP tools	Built-in Polygent operations available to the helper.
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.

Security boundary

A subagent is a separate capability boundary, not a way to bypass parent-session restrictions.

• 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 temporary identity, workspace boundary, and effective tool grants. A subagent cannot widen those server-enforced limits by calling /mcp directly. Keep the endpoint reachable only from trusted workers as defense in depth. See MCP Server security.

Troubleshooting

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

Symptom	Resolution
Custom subagent is not listed	Confirm it is enabled, selected by the session source, allowed by User Settings, and permitted by workspace limits. 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.