Subagent Extension (local)

Delegate tasks to specialized subagents with isolated context windows.

Current Fornace roster

The packaged default roster uses Mantice routing aliases by task difficulty:

Agent	Purpose	Model	Thinking
quick	Mechanical edits, extraction, formatting and simple checks	mantice/fornace-flash	low
scout	Focused codebase reconnaissance	mantice/fornace-fast	low
planner	Plans and difficult synthesis	mantice/fornace-reasoning	high
researcher	Web and source synthesis	mantice/fornace-reasoning	high
builder	Substantial implementation and integration	mantice/fornace-max	high
critic	Adversarial review and ordinary debugging	mantice/fornace-max	high
operator	Server, deployment and operational work	mantice/fornace-max	high
astra-debugger	Explicitly requested Astra work	mantice/fornace-astra	max

Load the fornace-model-routing skill before choosing a delegation route. It lives at the user level (~/.pi/agent/skills/, distributed by pi-setup) and is not packaged here: a packaged copy would collide with the user-level skill on every Fornace machine and drift stale. The standard routes are Flash, Fast, Reasoning and Max. Astra requires an explicit user request, including for hard debugging, mathematics and recovery. Vision, image and other media work uses its matching specialized route.

Model aliases are resolved against Pi's registered provider catalog. An absent or default model inherits the dispatching agent. An explicit unresolvable model fails before spawning; it never inherits silently. Spawn/status receipts report the requested routing alias. Provider response attribution, when available, is a separate runtime identity and routing aliases must not be described as fixed backends.

Features

• Isolated context: Each subagent runs in a separate pi process
• Streaming output: See tool calls and progress as they happen
• Parallel streaming: All parallel tasks stream updates simultaneously
• Markdown rendering: Final output rendered with proper formatting (expanded view)
• Usage tracking: Shows turns, tokens, cost, and context usage per agent
• Abort support: Batch cancellation stops its subprocesses; cancelling agent_wait cancels only observation and leaves the managed child running.

Managed RPC waits use Pi's agent_settled event, not process exit or the intermediate agent_end event. The tested runtime baseline is Pi 0.84.4; older runtimes are not supported by this lifecycle contract. A settled worker remains reusable for follow-ups. Prompt rejection is reported without replay.

Structure

subagent/
├── README.md            # This file
├── index.ts             # The extension (entry point)
├── agents.ts            # Agent discovery logic
├── agents/              # Sample agent definitions
│   ├── quick.md         # Mechanical work on fornace-flash
│   ├── scout.md         # Focused recon on fornace-fast
│   ├── planner.md       # Planning on fornace-reasoning
│   ├── builder.md       # Implementation on fornace-max
│   ├── critic.md        # Review on fornace-max
│   ├── operator.md      # Operations on fornace-max
│   ├── researcher.md    # Research on fornace-reasoning
│   └── astra-debugger.md # Explicitly requested Astra review
└── prompts/             # Workflow presets (prompt templates)
    ├── implement.md     # scout -> planner -> builder
    ├── scout-and-plan.md    # scout -> planner (no implementation)
    └── implement-and-review.md  # builder -> critic -> builder

Installation

Pi package

pi install npm:pi-subagent-extension
# or from git
pi install git:github.com/Fornace/pi-subagent-extension

Local (development)

Sync the repo into the extensions directory:

rsync -a --delete --exclude node_modules --exclude .git --exclude graphify-out \
  ./ ~/.pi/agent/extensions/subagent/
cd ~/.pi/agent/extensions/subagent && npm install

Security Model

This tool executes a separate pi subprocess with a delegated system prompt and tool/model configuration.

Project-local agents (.pi/agents/*.md) are repo-controlled prompts that can instruct the model to read files, run bash commands, etc.

Default behavior: Only loads user-level agents from ~/.pi/agent/agents.

To enable project-local agents, pass agentScope: "both" (or "project"). Only do this for repositories you trust.

When running interactively, the tool prompts for confirmation before running project-local agents. Set confirmProjectAgents: false to disable.

Usage

Single agent

Use `quick` for a small mechanical task
Use `builder` for substantial implementation
Use `astra-debugger` only when the user explicitly requests Astra
Use `builder` with model `mantice/fornace-astra` only for an explicit Astra implementation request

Parallel execution

Run 2 scouts in parallel: one to find models, one to find providers

Chained workflow

Use a chain: first have scout find the read tool, then have planner suggest improvements

Workflow prompts

/implement add Redis caching to the session store
/scout-and-plan refactor auth to support OAuth
/implement-and-review add input validation to API endpoints

Tool Modes

Mode	Parameter	Description
Single	{ agent, task }	One agent, one task
Parallel	{ tasks: [...] }	Multiple agents run concurrently (max 8, 4 concurrent)
Chain	{ chain: [...] }	Sequential with {previous} placeholder

Output Display

Collapsed view (default):

• Status icon (✓/✗/⏳) and agent name
• Last 5-10 items (tool calls and text)
• Usage stats: 3 turns ↑input ↓output RcacheRead WcacheWrite $cost ctx:contextTokens model

Expanded view (Ctrl+O):

• Full task text
• All tool calls with formatted arguments
• Final output rendered as Markdown
• Per-task usage (for chain/parallel)

Parallel mode streaming:

• Shows all tasks with live status (⏳ running, ✓ done, ✗ failed)
• Updates as each task makes progress
• Shows "2/3 done, 1 running" status
• Returns each completed task's final output to the parent model, capped at 50 KB per task
• Returns failure diagnostics from stderr/error messages when a child exits before producing output

Tool call formatting (mimics built-in tools):

• $ command for bash
• read ~/path:1-10 for read
• grep /pattern/ in ~/path for grep
• etc.

Agent Definitions

Agents are markdown files with YAML frontmatter:

---
name: my-agent
description: What this agent does
tools: read, grep, find, ls
model: mantice/fornace-fast
thinking: low
---

System prompt for the agent goes here.

Locations:

• ~/.pi/agent/agents/*.md - User-level (always loaded)
• .pi/agents/*.md - Project-level (only with agentScope: "project" or "both")

Project agents override user agents with the same name when agentScope: "both".

Sample Agents

Agent	Purpose	Model	Tools
quick	Mechanical work	fornace-flash	focused local tools
scout	Focused codebase recon	fornace-fast	read/search
planner	Implementation plans	fornace-reasoning	read/search + planning artifacts
builder	Substantial implementation	fornace-max	unrestricted/default tools
critic	Adversarial review	fornace-max	read-only review tools
operator	Server operations	fornace-max	shell/server tools
researcher	Source and web synthesis	fornace-reasoning	web + shell + read/write
astra-debugger	Explicitly requested Astra work	fornace-astra	read-only evidence review

Workflow Prompts

Prompt	Flow
/implement <query>	scout → planner → builder
/scout-and-plan <query>	scout → planner
/implement-and-review <query>	builder → critic → builder

Error Handling

• Exit code != 0: Tool returns error with stderr/output
• stopReason "error": LLM error propagated with error message
• stopReason "aborted": User abort (Ctrl+C) kills subprocess, throws error
• Chain mode: Stops at first failing step, reports which step failed

Limitations

• Output truncated to last 10 items in collapsed view (expand to see all)
• Parallel model-visible output is capped at 50 KB per task; full results remain in tool details
• Agents discovered fresh on each invocation (allows editing mid-session)
• Parallel mode limited to 8 tasks, 4 concurrent