@nklisch/pi-subagents

A pi extension that gives pi a focused, in-process sub-agent core — autonomous agents that run inside the same pi runtime (no spawned subprocesses), plus a typed API and lifecycle events other extensions build on. Spawn specialized agents that run in isolated sessions — each with its own tools, system prompt, model, and thinking level. Run them in foreground or background, steer them mid-run, resume completed sessions, and define your own custom agent types.

A maintained MIT fork of @gotgenes/pi-subagents, preserving its upstream execution core while adding a generic ordered lifecycle-interceptor provider seam. See Fork maintenance for provenance, qualification, and upstream-return policy.

https://github.com/user-attachments/assets/8685261b-9338-4fea-8dfe-1c590d5df543

Features

• In-process & native — agents run inside the same pi runtime (no spawned subprocesses), sharing tool names, calling conventions, and UI patterns (subagent, get_subagent_result, steer_subagent) — feels native
• Parallel background agents — spawn multiple agents that run concurrently with automatic queuing (configurable concurrency limit, default 4) and individual completion notifications
• Live widget UI — persistent above-editor widget with animated spinners, live tool activity, token counts, and colored status icons
• Session transcripts — open any subagent's full session transcript, including records whose heavy live session has been released, in pi's native read-only viewer via /subagents:sessions
• Custom agent types — define project agents in .pi/agents/<name>.md or the shared .agents/agents/<name>.md convention, with YAML frontmatter for prompts, models, thinking, and built-in tools
• Mid-run steering — inject messages into running agents to redirect their work without restarting
• Session resume — pick up where an agent left off, preserving full conversation context
• Graceful turn limits — agents get a "wrap up" warning before hard abort, producing clean partial results instead of cut-off output
• Policy-aware agent types — unambiguous names resolve case-insensitively. Unknown names default to general-purpose, can target another enabled fallback, or can fail closed via fallbackSubagent
• Fuzzy model selection — specify models by name ("haiku", "sonnet") instead of full IDs, with automatic filtering to only available/configured models
• Context inheritance — optionally fork the parent conversation into a sub-agent so it knows what's been discussed
• Styled completion notifications — background agent results render as themed, compact notification boxes (icon, stats, result preview) instead of raw XML. Expandable to show full output
• Event bus — lifecycle events (subagents:created, started, completed, failed, resumed, steered, compacted) emitted via pi.events, enabling other extensions to react to sub-agent activity

Install

This branch is locally qualified but unpublished, so it cannot be installed from npm yet. After an explicitly authorized publication, the package name will be @nklisch/pi-subagents and its immutable registry receipt will be recorded in Fork maintenance.

Load it directly for development:

pi -e ./src/index.ts

Quick Start

The parent agent spawns sub-agents using the subagent tool:

subagent({
  subagent_type: "Explore",
  prompt: "Find all files that handle authentication",
  description: "Find auth files",
  run_in_background: true,
})

Foreground agents block until complete and return results inline. Background agents return an ID immediately and notify you on completion.

UI

The extension renders a persistent widget above the editor showing active background agents (foreground runs are rendered inline by the subagent tool's progress stream):

● Agents
├─ ⠹ Agent  Refactor auth module · ⟳5≤30 · 5 tool uses · 33.8k token (62%) · 12.3s
│    ⎿  editing 2 files…
├─ ⠹ Explore  Find auth files · ⟳3 · 3 tool uses · 12.4k token (8%) · 4.1s
│    ⎿  searching…
├─ ⠹ Agent  Long-running task · ⟳42 · 38 tool uses · 91.0k token (84% · ↻2) · 2m17s
│    ⎿  reading…
└─ 2 queued

The token field is annotated with two optional signals inside parens:

• NN% — context-window utilization (color-coded: <70% dim, 70–85% warning, ≥85% error). Omitted when the model has no declared contextWindow, or briefly right after compaction.
• ↻N — number of times the session has compacted, when > 0. Stays dim; the percent's color carries urgency.

Individual agent results render inline in the conversation:

| State | Example | | -------------- | ---------------------------------------------------------------------------------------- | | Running | ⠹ ⟳3≤30 · 3 tool uses · 12.4k token (8%) / ⎿ searching, reading 3 files… | | Completed | ✓ ⟳8 · 5 tool uses · 33.8k token (62%) · 12.3s / ⎿ Done | | Wrapped up | ✓ ⟳50≤50 · 50 tool uses · 89.1k token (84% · ↻2) · 45.2s / ⎿ Wrapped up (turn limit) | | Stopped | ■ ⟳3 · 3 tool uses · 12.4k token (8%) / ⎿ Stopped | | Error | ✗ ⟳3 · 3 tool uses · 12.4k token (8%) / ⎿ Error: timeout | | Aborted | ✗ ⟳55≤50 · 55 tool uses · 102.3k token (95% · ↻3) / ⎿ Aborted (max turns exceeded) |

Completed results can be expanded (ctrl+o in pi) to show the full agent output inline.

Background agent completion notifications render as styled boxes:

✓ Find auth files completed
  ⟳3 · 3 tool uses · 12.4k token · 4.1s
  ⎿  Found 5 files related to authentication...
  transcript: .pi/output/agent-abc123.jsonl

The LLM receives structured <task-notification> XML for parsing, while the user sees the themed visual.

Default Agent Types

| Type | Tools | Model | Prompt Mode | Description | | ----------------- | -------------------------- | ----------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------ | | general-purpose | all 7 | inherit | append (parent twin) | Inherits the parent's full system prompt — same rules, CLAUDE.md, project conventions | | Explore | read, bash, grep, find, ls | haiku (falls back to inherit) | replace | Fast codebase exploration (read-only); inherits the parent prompt as a base |

The general-purpose agent is a parent twin — it receives the parent's entire system prompt plus a sub-agent context bridge, so it follows the same rules the parent does. Explore uses replace mode: the parent prompt is the cacheable base and its specialist read-only instructions are appended last, giving those instructions the final say.

Default agents can be overridden by creating a .md file with the same name (e.g. .pi/agents/general-purpose.md), or disabled per-project with enabled: false frontmatter.

Custom Agents

Define custom agent types by creating .md files. The filename becomes the agent type name. Any name is allowed — using a default agent's name overrides it.

Agents are discovered from three locations (higher priority wins):

| Priority | Location | Scope | | ----------- | -------------------------------------------------------------------------------- | -------------------------------------- | | 1 (highest) | .pi/agents/<name>.md | Pi project authority | | 2 | .agents/agents/<name>.md | Shared cross-tool project definitions | | 3 | $PI_CODING_AGENT_DIR/agents/<name>.md (default ~/.pi/agent/agents/<name>.md) | Global — available everywhere |

.agents/agents is read-only to this extension. .pi/agents overrides it and the global location on name collisions. The global location follows the upstream PI_CODING_AGENT_DIR env var — set it to relocate all pi-coding-agent state (agents, skills, settings) to a custom directory.

Example: .pi/agents/auditor.md

---
description: Security Code Reviewer
tools: read, grep, find, bash
model: anthropic/claude-opus-4-6
thinking: high
max_turns: 30
---

You are a security auditor.
Review code for vulnerabilities including:

- Injection flaws (SQL, command, XSS)
- Authentication and authorization issues
- Sensitive data exposure
- Insecure configurations

Report findings with file paths, line numbers, severity, and remediation advice.

Then spawn it like any built-in type:

subagent({ subagent_type: "auditor", prompt: "Review the auth module", description: "Security audit" })

Frontmatter Fields

All fields are optional — sensible defaults for everything.

| Field | Default | Description | | ------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | description | filename | Agent description shown in tool listings | | display_name | — | Display name for UI (e.g. widget, agent list) | | tools | all 7 | Comma-separated built-in tools: read, bash, edit, write, grep, find, ls. none denies all built-ins. Parent extension tools remain inheritable and are narrowed by extension policy | | model | inherit parent | Model — provider/modelId or fuzzy name ("haiku", "sonnet") | | thinking | inherit | off, minimal, low, medium, high, xhigh, max (actual support depends on host and model) | | max_turns | unlimited | Max agentic turns before graceful shutdown. 0 or omit for unlimited | | prompt_mode | append | replace: parent prompt is the cacheable base; body is appended last with full control (no <sub_agent_context> bridge, no <agent_instructions> wrapper). append: parent prompt is the base; body is wrapped in <agent_instructions> and a sub-agent context bridge is injected (agent acts as a "parent twin") | | inherit_context | false | Fork parent conversation into agent | | run_in_background | false | Run in background by default | | enabled | true | Set to false to disable an agent (useful for hiding a default agent per-project) |

Frontmatter is authoritative. If an agent file sets model, thinking, max_turns, inherit_context, or run_in_background, those values are locked for that agent. subagent tool parameters only fill fields the agent config leaves unspecified.

Tools

subagent

Launch a sub-agent.

| Parameter | Type | Required | Description | | ------------------- | ------------ | -------- | ---------------------------------------------------------------- | | prompt | string | yes | The task for the agent | | description | string | yes | Short 3-5 word summary (shown in UI) | | subagent_type | string | yes | Agent type (built-in or custom) | | model | string | no | Model — provider/modelId or fuzzy name ("haiku", "sonnet") | | thinking | string | no | Thinking level: off, minimal, low, medium, high, xhigh, max | | max_turns | number | no | Max agentic turns. Omit for unlimited (default) | | run_in_background | boolean | no | Run without blocking | | resume | string | no | Retained, finished agent ID to continue with the same history | | inherit_context | boolean | no | Fork parent conversation into agent |

Choosing the next action

• Let background agents finish normally. Completion automatically wakes the parent with a result preview; do not poll.
• Use steer_subagent to redirect an agent that is still running.
• Use resume after an agent finishes when it should continue with the same retained conversation history.
• Launch a new subagent without resume when prior conversation history is unnecessary.
• Use get_subagent_result only for full output, verbose conversation, an explicit status check or synchronization point, or recovery after a missed notification.

get_subagent_result

Inspect status or retrieve full results from a background agent. It is not the normal completion path because completion notifications wake the parent automatically.

| Parameter | Type | Required | Description | | ---------- | ------- | -------- | ----------------------------- | | agent_id | string | yes | Agent ID to check | | wait | boolean | no | Wait for completion | | verbose | boolean | no | Include full conversation log |

steer_subagent

Send a steering message to a running agent. The message interrupts after the current tool execution.

| Parameter | Type | Required | Description | | ---------- | ------ | -------- | ----------------------------------------- | | agent_id | string | yes | Agent ID to steer | | message | string | yes | Message to inject into agent conversation |

Commands

| Command | Description | | --------------------- | ------------------------------------------------------ | | /subagents:settings | Configure concurrency, turn limits, retention, interrupt behavior, and unknown-type fallback | | /subagents:sessions | View a subagent's session transcript (read-only) |

/subagents:settings

Interactive list to tune max concurrency, default/grace turns, consumed and unconsumed live-session retention, abort-all-on-ESC behavior, and unknown-agent fallback. Changes persist across pi restarts (see Persistent Settings).

/subagents:sessions

Pick any subagent — running, completed, or retained after its live session was released — and read its full session transcript in pi's native per-entry viewer. Read-only: no steering, no session takeover (steering lives in the steer_subagent tool and the background widget).

Creating and editing agent definitions is not a command — write an agent .md file in your editor, or ask a pi session to generate one (see Custom Agents).

Graceful Max Turns

Instead of hard-aborting at the turn limit, agents get a graceful shutdown:

1. At max_turns — steering message: "Wrap up immediately — provide your final answer now."
2. Up to 5 grace turns to finish cleanly
3. Hard abort only after the grace period

| Status | Meaning | Icon | | ----------- | ----------------------------- | ---------- | | completed | Finished naturally | ✓ green | | steered | Hit limit, wrapped up in time | ✓ yellow | | aborted | Grace period exceeded | ✗ red | | stopped | User-initiated abort | ■ dim |

Concurrency

Background agents are subject to a configurable concurrency limit (default: 4). Excess agents are automatically queued and start as running agents complete. The widget shows each queued agent with its effective model and queued state. Stopping a queued agent follows the normal terminal lifecycle and reports that no work started.

Foreground agents bypass the queue — they block the parent anyway. Completion nudges are held while the parent is running and flushed at the parent run boundary, preventing a pulled result from also arriving as a duplicate notification.

Persistent Settings

Runtime tuning values set via /subagents:settings persist across pi restarts. Terminal records remain available for the whole parent session. Their heavy live sessions are released after the consumed or unconsumed retention window; the result and persisted transcript pointer remain available. Two files, merged on load:

• Global: ~/.pi/agent/subagents.json — your machine-wide defaults. Edit by hand; the /subagents:settings command never writes here.
• Project: <cwd>/.pi/subagents.json — per-project overrides. Written by /subagents:settings.

Precedence: project overrides global on any field present in both. Missing fields use these defaults: max concurrency 4, max turns unlimited, grace turns 5, consumed-session retention 10 minutes, unconsumed-session retention 720 minutes, abort all on parent ESC enabled, and unknown-agent fallback general-purpose.

Example — global defaults for a beefy machine:

mkdir -p ~/.pi/agent
cat > ~/.pi/agent/subagents.json <<'EOF'
{
  "maxConcurrent": 16,
  "graceTurns": 10,
  "unconsumedSessionRetentionMinutes": 1440,
  "abortAllOnInterrupt": false,
  "fallbackSubagent": false
}
EOF

Every project now starts with concurrency 16, grace 10, a one-day unconsumed retention cap, background agents surviving parent ESC, and unknown agent types failing closed. Individual projects can still override via /subagents:settings.

Failure behavior: missing file is silent; malformed JSON logs a [pi-subagents] Ignoring malformed settings at … warning to stderr; invalid/out-of-range field values are dropped per-field; write failures downgrade the /subagents:settings toast to a warning with (session only; failed to persist).

Events

Agent lifecycle events are emitted via pi.events.emit() so other extensions can react:

| Event | When | Key fields | | ---------------------------- | ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | subagents:created | Background agent registered | id, type, description, isBackground | | subagents:started | Agent transitions to running (including queued→running) | id, type, description | | subagents:completed | Agent finished successfully | id, type, durationMs, tokens (lifetime { input, output, total }), toolUses, result | | subagents:resumed | A resumed turn reached a terminal state | completed-event shape plus status and error | | subagents:failed | Agent errored, stopped, or aborted | same as completed + error, status | | subagents:steered | Steering message sent | id, message | | subagents:compacted | Agent's session successfully compacted | id, type, description, reason ("manual" / "threshold" / "overflow"), tokensBefore, compactionCount | | subagents:settings_loaded | Persisted settings applied at extension init | settings (merged global + project) | | subagents:settings_changed | /subagents:settings mutation was applied | settings, persisted (boolean — false on write failure) |

tokens.total = input + output + cacheWrite. cacheRead is excluded — each turn's cacheRead is the cumulative cached prefix re-read on that one API call, so summing per-message would over-count it. Use contextUsage.percent (surfaced as (NN%) in the widget) for current context size.

Worktree Isolation

Worktree isolation lives in a companion package, not this core. Install @gotgenes/pi-subagents-worktrees and list the agent types you want isolated in its worktreeAgents config — opted-in agents run in a temporary git worktree, and their changes are saved to a branch on completion. The earlier isolation: "worktree" spawn flag and isolation: frontmatter key were removed from the core.

Removed: agent memory and skill preloading

Persistent agent memory (the memory: frontmatter key) and skill preloading (the skills: frontmatter key) were removed when the core was slimmed down. Children always inherit the parent's skills and extensions, so the isolated, extensions, and skills frontmatter keys no longer exist. Child creation uses a denylist rather than a registration-time allowlist: extension tools—including tools registered during lifecycle hooks—remain available, while disallowed built-ins and the three recursive orchestration tools stay excluded.

Migrating from disallowed_tools

The disallowed_tools frontmatter field has been removed. Use @gotgenes/pi-permission-system's permission: frontmatter instead — it provides richer semantics (allow/ask/deny vs. binary hide):

# Before (no longer supported)
disallowed_tools: bash

# After
permission:
  bash: deny

Permission System Integration

When @gotgenes/pi-permission-system is installed, this extension integrates automatically:

• Per-agent permission policies — define permission: in agent YAML frontmatter to set allow/ask/deny rules per agent type. The permission system resolves the agent name from the <active_agent> tag in the child system prompt.
• Tool filtering — the permission system's before_agent_start handler removes denied tools from the child session before the agent starts.
• ask-state forwarding — when a child session triggers an ask permission, the prompt forwards to the parent session's UI. The parent approves or denies, and the child resumes.
• Deterministic child detection — this extension publishes subagents:child:session-created before bindExtensions() fires; the permission system subscribes and registers the child session synchronously, so detection does not rely on env vars or filesystem heuristics.

No configuration is required. When @gotgenes/pi-permission-system is not installed, the lifecycle events have no subscriber — a harmless no-op.

For Extension Authors

This package exposes two public subpath exports for companion extensions to import from the published tarball.

@nklisch/pi-subagents — cross-extension service contract

Access the subagent service from another extension at runtime:

const { getSubagentsService } = await import("@nklisch/pi-subagents");
const svc = getSubagentsService();
svc?.spawn("Explore", "Check for stale TODOs");

Declare this package as an optional peer dependency. See src/service/service.ts for the full SubagentsService interface, the single WorkspaceProvider, and ordered lifecycle registration.

Ordered lifecycle interception

registerLifecycleInterceptor() is a generative provider seam for extensions that must replace or deny the exact child prompt, or accept, replace, abort, or continue a proposed child result before finalization. Callbacks receive immutable agent/session/run/parent identity and execution-path facts, never a manager or live session. Registrations are awaited in order; prompt and result replacements pipe to later providers; continuations stay in the same session and stop after three rounds. Existing lifecycle events remain observational and cannot substitute for this registration API.

const registration = svc?.registerLifecycleInterceptor({
  beforeStart: async ({ prompt }) => ({ action: "continue", prompt: `Context:\n${prompt}` }),
  beforeComplete: async ({ proposedResult }) => ({ action: "complete", result: proposedResult }),
});

await registration?.dispose();

@nklisch/pi-subagents/settings — layered config loader

Extensions that store configuration in JSON files can use the shared layered loader, which reads a global file (<agentDir>/<filename>) and a project file (<cwd>/.pi/<filename>) and merges them — project wins on conflicts, missing files are silent, malformed files warn and fall back:

import { loadLayeredSettings, type LayeredSettingsSource } from "@nklisch/pi-subagents/settings";

interface MyConfig { enabled?: boolean; limit?: number }

function sanitize(raw: unknown): Partial<MyConfig> {
  if (!raw || typeof raw !== "object") return {};
  const r = raw as Record<string, unknown>;
  const out: Partial<MyConfig> = {};
  if (typeof r.enabled === "boolean") out.enabled = r.enabled;
  if (typeof r.limit === "number") out.limit = r.limit;
  return out;
}

const config = loadLayeredSettings<MyConfig>({
  agentDir,          // Pi runtime agent home directory
  cwd,               // project root — project file lives at <cwd>/.pi/<filename>
  filename: "my-extension.json",
  sanitize,
  warnLabel: "my-extension",  // prefix for the malformed-file stderr warning
});

loadLayeredSettings returns Partial<T> (all fields optional); apply your defaults after the call. It never throws — all error conditions produce a console.warn and return {}.

Architecture

This extension is a minimal, composable core: it owns agent spawning, execution, and result retrieval, and exposes a typed SubagentsService plus lifecycle events that other extensions build on.

See docs/architecture/architecture.md for the full architecture document — design principles, domain decomposition, module dependency flow, Mermaid diagrams, and the improvement roadmap.

Relationship to upstream

This package is a maintained fork of @gotgenes/pi-subagents, itself an independently maintained hard fork of tintinweb/pi-subagents. It retains the minimal core and adds only the generic lifecycle-provider seam described above. The fork follows the rebase, security, and return-to-upstream policy in Fork maintenance.

License

MIT — tintinweb (upstream) and Chris Lasher (fork)