@zichuanlan/pi-subagents-lite

A streamlined Pi subagent package focused on execution and observability.

This fork keeps the parts needed to launch and monitor child agents—foreground/background execution, queues, FleetView, live conversations, steering, stopping, resuming, notifications, context inheritance, and transcripts—while removing unrelated orchestration subsystems.

Forked from @tintinweb/pi-subagents v0.14.2. See FORK_NOTES.md for the exact boundary.

Scope

Retained

• Foreground and background child agents
• Configurable background concurrency and queueing
• subagent, get_subagent_result, and steer_subagent tools
• /agents management UI
• Above-editor activity widget
• FleetView below the editor
• Live conversation viewer with inline steer and stop
• Session resume within the current Pi session
• Smart/group/async completion notifications
• Optional parent-context inheritance
• Per-agent output transcripts
• Custom agent types
• Lifecycle events for observation
• Minimal headless lifecycle bridge for waiting and shutdown

Removed

• Scheduled/cron agents
• Persistent agent memory
• Dedicated skill preloading
• Git worktree isolation
• Cross-extension spawn/stop RPC
• Enabled-model/model-scope enforcement

The package does not provide a sandbox. Child agents run with the same local-user privileges as Pi and can use every tool granted by their profile and active permission policy.

Install

Local development install:

pi install /home/lan/workspace/pi-subagents-lite

Pi records local package paths without copying them, so source edits are picked up after restarting or reloading Pi.

Pi 0.80.10 accepts a bare local path here; it does not accept npm-style file:/home/... package specs.

After publishing to an npm scope you control:

pi install npm:@zichuanlan/pi-subagents-lite

The repository can live anywhere, including a WSL path. Publishing depends on npm authentication and ownership of the package scope, not on the filesystem location.

Tools

subagent

subagent({
  subagent_type: "Explore",
  prompt: "Find the authentication flow and report the critical files.",
  description: "Trace auth flow",
  run_in_background: true
})

Important parameters:

Parameter	Meaning
subagent_type	Built-in or configured agent name
prompt	Self-contained task for the child
description	Short UI label
model	Optional provider/modelId or fuzzy model name
thinking	off, minimal, low, medium, high, xhigh, or max
max_turns	Optional positive turn limit
run_in_background	Return an agent ID immediately
inherit_context	Fork the parent conversation into the child
isolated	Disable extensions, MCP tools, and skill resources for the run
resume	Continue an existing current-session child agent

A value pinned in an agent JSON profile takes precedence over the same tool-call parameter. Tool-call parameters fill profile gaps.

get_subagent_result

get_subagent_result({
  agent_id: "<id>",
  wait: true,
  verbose: true
})

verbose: true includes the recorded child conversation when its session is still available.

steer_subagent

steer_subagent({
  agent_id: "<id>",
  message: "Stop exploring tests and focus on the production path."
})

The message is delivered after the child's current tool execution.

UI

Run /agents to inspect configured agent types, open running/completed conversations, and change operational settings.

FleetView appears below the editor while agents are available:

• At an empty prompt, press ↓ or ← to focus the fleet.
• Use ↑/↓ to select an agent.
• Press Enter to open its live conversation.
• In the conversation viewer, press Enter to compose a steer message.
• Press x, then x again, to stop a running agent.
• Press Esc to return.

The above-editor widget defaults to background agents only, avoiding duplicate foreground output. Set widgetMode to all, background, or off.

Configuration model

Operational settings and agent runtime profiles use JSON. Markdown files contain prompt bodies.

JSON locations

Priority	Path	Purpose
Higher	<cwd>/.pi/subagents.json	Project overrides
Lower	~/.pi/agent/subagents.json	Global defaults

Top-level operational fields use project-over-global replacement. agents profiles merge field-by-field by agent name, with project fields winning.

Example:

{
  "maxConcurrent": 4,
  "defaultMaxTurns": 0,
  "graceTurns": 3,
  "defaultJoinMode": "smart",
  "fleetView": true,
  "widgetMode": "background",
  "outputTranscript": true,
  "agents": {
    "reviewer": {
      "displayName": "Reviewer",
      "description": "Read-only implementation reviewer",
      "model": "sonnet",
      "thinking": "high",
      "maxTurns": 30,
      "tools": ["read", "grep", "find", "bash", "ext:mcp/search"],
      "extensions": ["mcp"],
      "excludeExtensions": ["pi-notify"],
      "disallowedTools": ["write", "edit"],
      "promptMode": "replace",
      "inheritContext": false,
      "runInBackground": true,
      "isolated": false,
      "outputTranscript": true,
      "enabled": true
    }
  }
}

Operational fields

Field	Accepted values	Default
maxConcurrent	Integer 1..1024	4
defaultMaxTurns	Integer 0..10000; 0 means unlimited	Unlimited
graceTurns	Integer 1..1000	Runtime default
defaultJoinMode	async, group, smart	smart
fleetView	Boolean	true
widgetMode	all, background, off	background
outputTranscript	Boolean	true
agents	Object keyed by agent name	{}

Agent profile fields

Field	Type	Purpose
displayName	String	UI label
description	String	Tool-description guidance
model	String	Model pin or fuzzy model name
thinking	String	Thinking level
maxTurns	Non-negative integer	Profile-level turn policy; 0 is unlimited
tools	"all", "none", or string array	Built-in and extension-tool allowlist
extensions	Boolean or string array	Which extensions load
excludeExtensions	String array	Extension denylist; exclusion wins
disallowedTools	String array	Final tool denylist
promptMode	replace or append	Standalone prompt or parent-prompt twin
inheritContext	Boolean	Default conversation inheritance
runInBackground	Boolean	Default execution mode
isolated	Boolean	Built-in tools only; no extensions/skills
outputTranscript	Boolean	Per-agent transcript override
enabled	Boolean	Show or disable the agent type

Tool selectors

tools accepts built-in names such as read, grep, find, bash, edit, and write.

Extension tools use selectors:

• ext:mcp exposes all tools registered by the mcp extension.
• ext:mcp/search exposes only the search tool from mcp.
• "*" inside an array means all built-in tools and (unless narrowed by ext:) all tools from loaded extensions.

An explicit array without * is closed: only the listed built-ins and listed ext: tools reach the child. extensions controls loading/handlers; tools controls what reaches the child model.

Prompt Markdown

Prompt discovery order, highest first:

1. <cwd>/.pi/agents/<name>.md
2. <cwd>/.agents/agents/<name>.md
3. ~/.pi/agent/agents/<name>.md
4. Embedded default prompt, when applicable

Example .pi/agents/reviewer.md:

You are a read-only implementation reviewer.

Report correctness, security, lifecycle, and configuration findings in priority order.
Include exact file paths and line references. Do not edit files.

The filename is the agent name. A Markdown file can override an embedded prompt such as Explore.md or Plan.md.

Legacy YAML frontmatter from the upstream package is still parsed as a migration fallback, but new configuration should use subagents.json. When both are present, JSON profile fields win and the Markdown body remains the prompt.

Built-in agents (lite roster)

Split only when tool/write boundaries differ. Checklists (security, debug, verify) merge into prompts — see docs/AGENT_ROSTER.md.

Type	Display	Tools	Turns	Use when
Explore	Explore	read/grep/find/ls	~8	Local files/symbols/paths only
Research	Research	local read-only + web_search/fetch_content/get_search_content	~10	Docs, versions, external APIs, OSS samples
Plan	Plan	read-only (+ optional pi-lens via JSON)	~12	Implementation design, not coding
Review	Review	read/grep/find/ls	~10	Correctness + security findings
general-purpose	Implement	all built-ins, isolated	~14	Only write/edit/shell for one task

Dispatch: locate → Explore · docs/web → Research · design → Plan · audit → Review · mutate → general-purpose.

Do not default every task to general-purpose. Debug/verify/security are not separate agents in lite; they are phases/checklists inside Implement or Review.

Config + docs you should keep in sync

Layer	Path	Owns
Runtime policy	~/.pi/agent/subagents.json or <cwd>/.pi/subagents.json	tools, extensions, model, maxTurns, isolated
Prompt body	~/.pi/agent/agents/<Name>.md or project .pi/agents/	persona, checklists, output shape
Merge rules	docs/AGENT_ROSTER.md	what to split vs merge

Create a JSON profile with the same name to override runtime fields. Create a Markdown file with the same name to override the prompt body. Set enabled: false in JSON to disable a type.

Single-level efficiency rules

• Children never inherit nested-agent tools (subagent, get_subagent_result, steer_subagent) or parent workflow tools (trellis_subagent, todo, advisor, goal tools, memory, skill_manage).
• An explicit tools: [...] list is a closed allowlist: only named built-ins and ext:<extension>/<tool> selectors surface. Loading an extension for handlers does not auto-expose its tools.
• tools: none exposes no tools. tools: "*" / tools: "all" is the open policy for all built-ins plus loaded extension tools (minus hard denials).
• Defaults use promptMode: replace and do not inherit the parent conversation unless inherit_context is set per call.
• Soft turn-limit wrap-up asks for current evidence immediately; default grace is 1 turn.

Permission compatibility

Each child prompt includes:

<active_agent name="reviewer"/>

Permission extensions can use that identity to apply agent-specific policies. After child extensions bind, this package re-applies only the intersection of:

1. the agent's configured allowlist, and
2. the tools that remain active after policy binding.

This prevents extension binding from re-enabling tools that a permission policy disabled.

Observation events

The extension emits observation events on pi.events:

• subagents:created
• subagents:started
• subagents:completed
• subagents:failed
• subagents:steered
• subagents:compacted
• subagents:settings_loaded
• subagents:settings_changed

These events are informational. Cross-extension spawning and stopping are intentionally not provided.

Development

npm install
npm run lint
npm run typecheck
npm test
npm run build
npm pack --dry-run

The package entry remains src/index.ts; Pi loads TypeScript extensions directly.

License and attribution

MIT licensed. Original implementation copyright remains with tintinweb. This fork preserves the upstream license and records its removals and compatibility changes in FORK_NOTES.md.