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.

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. See what the classifier sees for the complete input context.

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.

Launch metadata

The model’s subagent call supplies the task prompt. Polytoken renders that task as a template first, then renders the definition body with the rendered task available as prompt. Both sources render once for each clone in a counted batch (several copies requested with the count input to the subagent tool). Use a raw block when the task must contain literal {{ ... }} or {% ... %} text; see Templating.

The caller’s current working directory supplies the launch directory unless the call supplies cwd. A supplied directory must exist, and an external directory requires chdir approval. The subagent cannot move above its launch directory.

If a definition uses polytoken.model with a model group (an ordered failover list of models; see Model groups and failover), Polytoken starts each clone at a different group candidate. In a counted batch, Polytoken launches all copies together, but every clone gets its own job handle and lifecycle. Polytoken keeps the rendered launch metadata fixed for each clone and retries the current provider before moving to the next group candidate. The route remains on a successful candidate until you or the model explicitly selects a group again or the provider fails and the route advances.

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 records a brief status snapshot. In a subagent, the snapshot signals progress to the parent, and when Polytoken compacts the subagent’s context it carries the latest snapshot through as a reminder, so the subagent resumes from recorded progress. Subagent findings and conclusions go through exit_tool. During an exec run, Polytoken echoes each snapshot to the terminal’s stderr as exec: progress {…}. Exec results go through the structured-output completion tool. progress_update is not a results channel in either context.

@skill: references in the spawn prompt

A subagent spawn prompt can include @skill:<name>. Polytoken resolves each reference against the subagent definition’s polytoken.skills_allow and polytoken.skills_deny, not the parent facet’s lists. A denied, polytoken.disable_model_invocation: true, or unresolvable reference returns an error before the subagent starts. Forked subagents keep the skills referenced by the fork prompt.

message_subagent validates @skill: references against the same subagent policy before queueing a delivery. A failed reference prevents the message from entering the inbox. Polytoken caches referenced skills in the subagent context, so the skills survive the subagent’s own compaction.

A referenced skill reaches the subagent, not the parent conversation: Polytoken injects the skill body into the subagent’s context ahead of its first instruction. The reference shapes what the subagent reads; it does not choose the model the subagent runs on. Pin the model in the definition with polytoken.model and polytoken.fallback_models.

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.