@dreki-gg/pi-subagent

Run full prompts that the caller supplies in isolated Pi subprocesses.

Install

pi install npm:@dreki-gg/pi-subagent

subagent tool

The only LLM-facing surface is the prompt-native subagent tool. It does not discover named agents, load persona prompts, or add hidden instructions. Supply the full child prompt and execution controls explicitly.

{
  "label": "auth-recon",
  "prompt": "Inspect the authentication flow. Return verified findings with file references. Do not edit files.",
  "model": "openai-codex/gpt-5.6-luna",
  "thinking": "low",
  "tools": ["read", "grep", "find", "ls"],
  "cwd": "/path/to/repository"
}

label is optional display metadata only. It never chooses a prompt, model, tools, or other behavior.

Modes

• Single: { prompt, label?, model?, thinking?, tools?, cwd? }
• Parallel: { tasks: [{ prompt, label?, model?, thinking?, tools?, cwd? }], model?, thinking?, tools?, cwd? }
• Chain: { chain: [{ prompt, label?, model?, thinking?, tools?, cwd? }], model?, thinking?, tools?, cwd? }

Child item controls override call-level defaults. Every prompt must be non-empty. Parallel runs support at most eight items and execute at most four at a time. An explicit empty tools array disables all child tools.

A chain replaces each {previous} occurrence with the preceding child's final raw text. The engine does not parse or format that output. To bound context growth, it caps it at 64 KiB and appends [previous output truncated by pi-subagent] when truncation occurs.

Execution behavior

Pi children run in JSON print mode with no persisted session and --no-prompt-templates. The engine sends the full prompt to stdin exactly as supplied. It does not add a Task: prefix or a hidden system prompt. The engine forwards explicit model, thinking, tools, and cwd controls. It excludes orchestration tools from children.

Spawned children are leaves. They receive PI_AGENT_LEAF=1, do not register this extension, and cannot delegate again. Other trusted Pi context files, skills, and extensions remain Pi-controlled child resources.

Progress, final output, usage, cancellation, and child errors are rendered in the parent tool result.

Workflow RPC bridge

Extensions can launch reviewed declarative workflows through the process-local subagents:rpc:v2:* event contract. The bridge supports lifecycle methods, bound phases, JSON fan-out, output templates, and optional snapshot files. The lifecycle methods are ping, spawn, status, stop, and restart-as-resume.

Workflow steps are prompt-native:

{
  "version": 2,
  "requestId": "inspect-then-plan-1",
  "method": "spawn",
  "params": {
    "workflow": {
      "name": "inspect-then-plan",
      "task": "Review the requested change",
      "chain": [
        { "label": "inspect", "prompt": "Inspect {task}. Return evidence only.", "tools": ["read", "grep", "find"] },
        { "label": "plan", "prompt": "Create a plan using this prior output:\n\n{previous}" }
      ]
    }
  }
}

Workflow prompt steps support prompt, optional inert label, as, model, thinking, tools, and cwd. Workflow templates preserve {task}, {previous}, {outputs.name}, and fan-out item placeholders. {previous} uses the same neutral 64 KiB cap as tool chains, and workflow parallelism is limited to four child runs.

Breaking migration

This release removes named agents and personas. Replace legacy { agent, task } calls with a full { prompt } call. Add the previous persona instructions to the prompt. Pass model, thinking, and tools explicitly when necessary. The release removes list_agents, /create-agent, /run-agent, agent scopes, project-agent confirmation, package prompt discovery, bundled prompts, and the Cursor ACP backend. User and project Pi prompt templates remain Pi resources, but this package ignores them.