Subagents

A subagent is a separate agent the model starts to handle one bounded task in its own context, returning only a short result. For what a subagent is and why the model starts one, see Subagents. This page is about authoring the definition file.

A subagent definition lives in a Markdown file, much like a facet: the front matter declares what the subagent does, and the body is the system-prompt framing. The shared keys work as they do for a facet, so the sections below cover what is different.

Where definitions live

A subagent definition goes in .polytoken/subagents/ in your project, or in the subagents/ directory of your global Polytoken config for ones you want everywhere. The filename is the subagent’s name: triage.md defines a subagent named triage. The name key in the front matter must match the filename; Polytoken rejects the definition at load time when they differ.

What carries over from facets

The shared front-matter keys mean what they do for a facet. polytoken.model and polytoken.fallback_models pin the subagent to a model. polytoken.tools grants the subagent’s tools, with the same mcp__<server>, tag!ALL, and tag!ALL_MCP shorthands; polytoken.tools_deny removes from the granted set. polytoken.skills_allow and polytoken.skills_deny control skill access. polytoken.undeferred_tools lists the tools whose full definitions appear up front. Polytoken passes polytoken.autonomous_hint to the autonomous permissions classifier.

The body is your framing for the subagent, and Polytoken renders it as a template. You do not need to put tool-use guidance or base framing in it: Polytoken wraps every subagent in its shipped base prompt, which carries that guidance, then appends your body as a suffix. The transclude function is not available in a subagent body, so you cannot pull the base prompt in yourself, and you do not need to. Write the instructions specific to this subagent’s job.

What is specific to subagents

A few keys exist only on subagents.

When polytoken.inherit_tools is true, the subagent receives the calling facet’s tools alongside its own declared polytoken.tools at spawn time.

polytoken.allow_subagent_spawn, when true, lets this subagent start subagents of its own.

Polytoken registers an exit_tool for every subagent and rejects any definition that lists exit_tool in polytoken.tools. The model calls exit_tool to finish, and the payload becomes the result Polytoken returns to the parent conversation. The default payload is a success flag and a summary. To change its shape, declare a polytoken.exit_tool_schema: a JSON Schema describing the payload you want the subagent to return. The Template Reference gives the default.

Caution

polytoken.inherit_tools inherits tools, not skill access. A subagent compiles its skill access from its own polytoken.skills_allow and polytoken.skills_deny, never the caller’s. A subagent with polytoken.inherit_tools set to true and no polytoken.skills_allow can reach every skill, including skills the calling facet restricts. Set polytoken.skills_allow on a subagent that inherits tools.

A small subagent

A subagent named triage, in .polytoken/subagents/triage.md, that reads and classifies without the tools to change anything:

---
name: triage
description: Reads an issue and proposes a category and severity.
polytoken:
  model: your-smaller-model
  tools: [file_read, glob, grep]
  skills_allow: []
---
You triage incoming issues. Read what the caller points you at, then propose a
category and a severity with one sentence of reasoning each. Your tools are
read-only.

The name matches the filename. The polytoken.tools list grants reading and searching but no edit or shell tool, so the subagent cannot modify the project. The empty polytoken.skills_allow states that this subagent’s skill access is its own, not inherited.

Front-matter keys

The shared keys carry the meanings in the Facets key table. The keys below are the ones specific to subagents. The machine-readable schema is in the Template Reference.

Key	Type	Default	Meaning
polytoken.inherit_tools	boolean	false	Unions the calling facet’s tools into this subagent’s at spawn time. Does not inherit skill access.
polytoken.allow_subagent_spawn	boolean	false	Lets this subagent start subagents of its own.
polytoken.exit_tool_schema	JSON Schema	{success, summary}	The schema for the exit_tool payload the subagent returns to its caller.

Loading changes

Polytoken loads subagent definitions at startup and when you reload its configuration; an edit to a definition takes effect only on the next reload.