pi-subagents (Go port, partial)

A Go extension for PiG: delegate work to specialist agents defined in markdown files. It is a port of pi-subagents by Nico Bailon (see CREDITS.md), made with the extension porting Skill, and needs no Node.

Use

Define an agent in .pi/agents/<name>.md (the project) or ~/.pi/agent/agents/<name>.md (you), the original's format:

---
name: helper
description: Helps with things
model: provider/model
tools: read, grep
---

You help.

The model sees two tools. subagents_enable makes the subagent tool available (it is not offered until then, as in the original); then:

• subagent {action: "list"} lists the agents (agentScope: user, project or both), {action: "get", agent: "helper"} shows one;
• subagent {agent: "helper", task: "..."} runs one agent in a child pig --print process and returns its answer;
• /run-chain <chain> <task> runs a .chain.md chain (.pi/chains/ or ~/.pi/agent/chains/): each step's answer flows into the next as {previous}, the request as {task}.

Thirteen agents ship with the package (the original's scout, worker, reviewer, ...). PIG_SUBAGENT_PIG_BINARY names the pig to start for a child; otherwise the pig running this extension, then a pig beside this program, then PATH. A child gets the task on stdin, discovers extensions as the original's background child does (a model provider and its login come from one), and may itself delegate only to depth 2 (PI_SUBAGENT_MAX_DEPTH, as in the original); at most 4 children run at once, and a cancelled call (Escape) stops its child. An agent with systemPromptMode: replace cannot run in a Piglet Binary child (a Binary keeps its own system prompt).

An agent chooses its child's extensions as in the original. extensions: a, b loads only those (an empty extensions: loads none, not even a model provider), and subagentOnlyExtensions: c loads c in the child on top of the rest. Entries are what pig --extension takes: a path (./ and ../ are relative to the agent file), builtin:<name>, or an npm:/git: source. For agents that set neither, subagents.defaultExtensions and subagents.defaultSubagentOnlyExtensions in settings.json are the default: PiG's own files (.pig/settings.json in the cwd, ~/.pig/agent/settings.json) and the original's (.pi/settings.json at the project root, ~/.pi/agent/settings.json) are all read, project over user and PiG's over Pi's at each level:

{ "subagents": { "defaultSubagentOnlyExtensions": ["/path/to/child-only-extension"] } }

A child's model and thinking level come, strongest first, from the call's model, subagents.agentOverrides.<name>.model and .thinking (false clears the agent's own), the agent's frontmatter, then subagents.defaultModel and defaultThinking, read from the same files, each from the first file that sets it. Without any of them the child runs on the host's default model. Other agentOverrides fields, defaultProvider and modelScope are not read:

{ "subagents": { "defaultModel": "provider/small-model", "agentOverrides": { "oracle": { "model": "provider/large-model", "thinking": "high" } } } }

pig install ./components/subagents

What is ported

Frontmatter parsing, agent and chain definitions (discovery in the project, the user's directories and the builtin set, precedence project over user over builtin, packages, aliases, name resolution), markdown chain files (parse and write), the subagent tool's list and get, the subagents_enable loader, and running one agent or a chain through a child process (a Go addition: the original runs children through its own executor and scripted workflows).

Not ported, and refused: parallel, async and background runs, scripted workflows (workflow, workflowScript, workflowScriptPath) and the legacy tasks/chain inputs, council mode, worktree isolation, the fleet and status views, steering and the supervisor channel, the watchdog, missions, profiles, agentOverrides other than model and thinking, .chain.json chains, the management actions other than list and get. The tool honors agent, task, agentScope, cwd, model and async: false (the port always runs in the foreground) and, for list and get, action, agent and agentScope. Any other parameter or action, and the tools bg_wait and subagent_supervisor (declared so the model sees the original's tools), is refused with one message and nothing runs:

@pi-in-go/pigpen-subagents (Go port) does not support async (background) runs (async: true) yet. Install the original extension, npm:[email protected], which runs unchanged in PiG.

The original's slash commands other than the port's own /run-chain (/run, /subagents, /subagents-stop, /prompt-workflow, ...) are not registered, and neither are its skills and prompt templates. See port/PORT.md.