Subagents

A subagent definition is a Markdown file that configures a bounded delegate. For runtime behavior, see Subagents.

A subagent definition lives in a Markdown file, much like a facet: the frontmatter 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 $XDG_CONFIG_HOME/polytoken/subagents/ (default: ~/.config/polytoken/subagents/) for ones you want everywhere. The filename is the subagent’s name: triage.md defines a subagent named triage. The name key in the frontmatter must match the filename; Polytoken rejects the definition at load time when they differ.

What carries over from facets

The shared frontmatter 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. You can use transclude to include shipped prompt fragments in the body when a subagent needs shared reference text. 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.

progress_update is a separate, lighter tool that signals the subagent is alive and making progress. It is not a results channel; findings and conclusions go through exit_tool.

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.

Frontmatter 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.