# panto-subagents

Delegation and workflows for [Pantograph](https://github.com/travisp/pantograph).
The `subagents` extension lets a primary agent start specialized child agents,
run several at once, and continue their conversations later.

## Install

```toml
[extensions]
rocks = ["panto-subagents"]
```

For a local checkout, use `paths = ["/path/to/panto-subagents"]` instead.

## Agent profiles

Agents are Markdown files with YAML frontmatter:

```markdown
---
name: reviewer
description: Reviews changes for correctness and missing tests
model: anthropic:sonnet
reasoning: high
---

You are a focused code reviewer. Report only concrete findings.
```

Profiles are loaded recursively from:

- `${XDG_CONFIG_HOME:-$HOME/.config}/panto/agents/`
- `.panto/agents/` in the current project

Project profiles override user profiles with the same name. `name` defaults to
the filename. `model` and `reasoning` are optional; each value follows the same
precedence: tool call, then profile, then the primary agent. Models use full
`provider:model` names.

## Delegation

The primary uses `subagents.run` to start a child from a profile:

```lua
subagents.run {
  agent = "reviewer",
  prompt = "Review the authentication changes.",
}
```

Every started child returns an ID. Passing it back resumes the same
conversation, including after restarting Panto and resuming the primary:

```lua
subagents.run {
  id = "0198...",
  prompt = "Now focus on the missing tests.",
}
```

Children receive the primary's system and project context plus their own
profile prompt, but not the primary's conversation. They share its workspace
and tools except for `subagents.*`.

Multiple calls in one tool batch run concurrently. Their tagged assistant and
tool activity is visible in the TUI while they work. Child conversations are
stored as normal JSONL sessions beneath their owning primary session, so they
remain resumable without appearing in the user's `/resume` picker. A child ID
cannot be resumed from another primary conversation.

`subagents.models` provides bounded search and validation for configured
providers, models, and model-specific reasoning levels without placing the
entire model catalog in every tool prompt.

## Workflows

TOML workflows define fixed dependency graphs. They are loaded from
`${XDG_CONFIG_HOME:-$HOME/.config}/panto/workflows/` and
`.panto/workflows/`, then exposed as `/workflow:<name>` commands. Ready steps
run concurrently; each dependent step receives its predecessors' labeled
outputs.

The Lua workflow API handles dynamic branching and fan-out. It can await one
job or a group, and supports one-turn workers whose validated tool input is
their structured result. Panto extensions can use this API directly, while
`subagents.lua` runs model-authored one-off workflows in a restricted Lua
environment.

See [DESIGN.md](DESIGN.md) for the runtime and persistence design.