Subagent delegation

The pi-subagents extension gives Selesai focused child agents that run in the same workspace. You can ask for reviews, exploration, implementation, parallel audits, or background work in plain language; Selesai translates that into subagent tool calls or slash commands.

Bundled with Selesai

Loaded automatically with Selesai; no per-extension npm install is required.

Manifest entry

./pi-subagents

Runtime surface

Mixed (commands, tools, shortcuts)

Setup and prerequisites

• This extension is bundled with Selesai. It is loaded automatically; you do not need to install it separately.
• The Selesai model must have a valid API key.
• Optional: for the researcher agent’s web searches, install web search tooling; otherwise the agent falls back to available tools.
• Optional: a permission-system integration works when both pi-subagents and @gotgenes/pi-permission-system are installed.

What it sets up

• Registers the subagent tool for single, parallel, and chain runs.
• Registers a family of slash commands: /run, /chain, /parallel, /run-chain, /subagents, /subagent-cost, /subagents-doctor, /subagents-stop, /subagents-models, /subagents-profiles, /subagents-load-profile, /subagents-refresh-provider-models, /subagents-generate-profiles, /subagents-check-profile, plus prompt-workflow shortcuts such as /parallel-review.
• Registers inline agent invocation: #agent-name anywhere in a message (start, middle, or end) runs that agent directly, and typing # in the editor autocompletes installed agents.
• Creates lifecycle artifacts for async runs under the Selesai subagent results directory; run artifacts default to the session directory instead of the project checkout (.pi-subagents/).
• Sets SELESAI_SUBAGENT_PARENT_SESSION in child processes for permission-system forwarding.

What you can configure

Subagent delegation supports extension-level config plus user/project settings that override default agents, models, thinking, extensions, and runtime budgets.

Configuration locations and precedence

1. Extension config
   ~/.selesai/agent/extensions/subagent/config.json
   Lowest; applies unless overridden by user/project settings or an explicit call argument.
2. User settings
   ~/.selesai/agent/settings.json
   Overrides extension defaults; overridden by project settings.
3. Project settings
   .selesai/settings.json
   Highest persistent layer for settings-backed agent values.
4. Per-call precedence
   tool/slash arguments and agent frontmatter
   Explicit call arguments and agent frontmatter beat all config layers.

Settings

Key / path	Type, default, and values	Description
asyncByDefault	boolean Default: false	Run single subagent calls in the background by default.
forceTopLevelAsync	boolean Default: false	Force top-level subagent invocations to run asynchronously.
fleetView	boolean Default: true	Show the Claude Code-style navigable fleet panel below the editor.
asyncWidget	boolean Default: true when fleetView disabled, otherwise false	Show the legacy above-editor async runs widget.
toolDescriptionMode	string Default: "compact" Allowed values: "full", "compact", "custom"	Variant of the parent-facing subagent tool description. Defaults to compact.
waitTool	boolean | object Default: (not configured)	Register a wait/notify tool for subagents. Pass true or { enabled: true }.
defaultSessionDir	string Default: (system temp or session path)	Base directory used for subagent sessions when no explicit path is given.
singleRunOutputBaseDir	string Default: (not configured)	Base directory used for single-run output artifacts.
maxSubagentDepth	number Default: 2	Maximum nested subagent depth for this session.
maxSubagentSpawnsPerSession	number Default: unlimited	Optional cumulative cap on subagent spawns across a session. 0 means unlimited.
maxWorkflowAutoRelaunches	number Default: 12	How many times an async scripted workflow may auto-relaunch with a fresh fan-out budget after exhausting it before the goal is clean. 0 means unlimited.
globalConcurrencyLimit	number Default: 20	Global cap on simultaneously-running subagent tasks within a run.
control	object Default: (disabled)	Lifecycle control notifications: enabled, thresholds (ms/turns/tokens), failed-tool count, channels (event/async/intercom), and notifyOn events.
completionBatch	object Default: (disabled)	Smart completion batching: enabled, debounceMs, maxWaitMs, stragglerDebounceMs, stragglerMaxWaitMs, stragglerWindowMs.
turnBudget	object Default: (not configured)	Turn budget: maxTurns, optional graceTurns.
toolBudget	object Default: (not configured)	Tool budget: hard limit, optional soft limit, and optional block list or "*".
parallel.maxTasks	number Default: 8	Default maximum parallel tasks for top-level parallel runs.
parallel.concurrency	number Default: 4	Default concurrency for top-level parallel runs.
chain.dynamicFanout.maxItems	number Default: (not configured)	Maximum number of dynamic items generated by a chain fan-out step.
worktreeSetupHook	string Default: (not configured)	Path to a shell command run when preparing parallel/chain worktrees.
worktreeSetupHookTimeoutMs	number Default: (not configured)	Timeout for the worktree setup hook.
worktreeBaseDir	string Default: (system temp)	Base directory for parallel/chain worktrees.
artifactDir	string Default: "project" (cwd/.pi-subagents) Allowed values: "project", "session", "temp"	Where subagent artifact files are stored.
intercomBridge	object Default: (off)	Intercom bridge mode: off, fork-only, or always; plus optional instructionFile.
proactiveSkillSubagents	object | false Default: (disabled)	Recommend skill-backed subagents: enabled, minReferences, maxRecommendations, preferredAgent. Set to false to disable.
subagents.defaultModel	string Default: (not configured)	Default model applied to built-in agents that do not declare a model. Project overrides user.
subagents.defaultThinking	string Default: (not configured)	Default thinking suffix applied to built-in agents without an explicit thinking value.
subagents.defaultExtensions	string[] Default: (not configured)	Default extensions added to agents that do not declare extensions.
subagents.disableBuiltins	boolean Default: false	Disable loading of built-in agent definitions.
subagents.disableThinking	boolean Default: false	Disable thinking suffix defaults for built-in agents.
subagents.modelScope	object Default: (not configured)	Enforce an allow-list of model patterns when enforce is true. allow is an array of glob-style patterns (only * is special).
subagents.agentOverrides.<agent>	object Default: (not configured)	Per-agent overrides for built-in agents: model, thinking, fallbackModels, tools, mcpDirectTools, extensions, subagentOnlyExtensions, skills, systemPromptMode, defaultAsync, defaultTimeoutMs, defaultTurnBudget, defaultAcceptance, acceptanceRole, output, defaultReads, defaultProgress, interactive, maxSubagentDepth, completionGuard, toolBudget, memory, disabled.

Environment variables

Key / path	Description
SELESAI_SUBAGENT_MAX_DEPTH	Runtime override for the current maximum subagent depth.
SELESAI_SUBAGENT_MAX_SPAWNS_PER_SESSION	Runtime override for max spawns per session. Use 0 for unlimited.
SELESAI_SUBAGENT_DEPTH	Incremented automatically for nested subagent runs; do not set manually.
SELESAI_SUBAGENT_PARENT_SESSION	Forwarded to child sessions so async subagents can locate their parent.

Command, tool, and shortcut controls

Key / path	Description
subagent({ ... })	Foreground or async subagent tool call.
/run, /chain, /parallel, /run-chain	Slash commands for common run modes.
/subagents-doctor, /subagents-stop, /subagent-cost, /subagents-models, /subagents-profiles, /parallel-review	Management and monitoring commands.
/subagents-watchdog [status|on|off|model ...]	Runtime watchdog status and controls.
subagent({ action: "status" })	Inspect live run status and child activity.

Source evidence

• src/extensions/pi-subagents/src/shared/types.ts
• src/extensions/pi-subagents/src/agents/agents.ts
• src/extensions/pi-subagents/src/runs/shared/model-scope.ts

What you can do

• Ask in plain language: Ask reviewer to review this diff.
• Run a single agent: /run reviewer "review this plan".
• Invoke a single agent inline: #worker Turn this plan into a step-by-step implementation plan. — #agent-name anywhere in a message (start, middle, or end) runs that agent directly (like /run). Unknown or ambiguous agent names only produce a notification and consume the input when the mention is at the start of the message; mid-message mentions (e.g. issue #42) pass through untouched.
• Run agents in sequence: /chain scout "scan auth" -> oracle "design refactor" -> worker "implement it".
• Run agents in parallel: /parallel reviewer "check correctness" -> reviewer "check tests".
• Use inline group syntax: /chain scout -> (reviewer "A" | reviewer "B") -> worker "fix".
• Run in the background: append --bg. Start from a forked session: append --fork.
• Inspect active runs: subagent({ action: "status" }).
• Stop a run: /subagents-stop <run-id> or subagent({ action: "stop", id: "..." }).
• Restrict launches with session-scoped allowedAgents, add chain approval checkpoints, or cap aggregate usage with usageBudget.
• Discover the runtime delegation catalog: subagent({ action: "list" }) shows executable and capability-restricted agents with source, aliases, role, context, tools, and description, and returns the same catalog as versioned machine metadata in details.catalog.
• Get compact capability rows: subagent({ action: "list", capabilities: true }) returns concise prompt-free rows (executable/restricted status, restriction sources, runner, tools/model/execution/output/extensions snapshot) as human text plus versioned details.catalog machine metadata.
• Get task-aware routing advice: subagent({ action: "list", task: "..." }) appends a recommendation for one canonical agent (implementation or read-only) for that task, or explains why none is safe. It is advisory only and never launches work — execute the recommended agent explicitly.
• Ask a child to contact the supervisor: contact_supervisor({ reason: "need_decision", message: "..." }).

Commands, tools, and shortcuts

Command / shortcut	Description
subagent({ agent, task, async?, context?, model?, ... })	Run one agent.
subagent({ tasks: [...] })	Run agents in parallel.
subagent({ chain: [...] })	Run agents in sequence with {previous} output.
subagent({ action: "list" })	Show the runtime delegation catalog: executable/restricted agents (source, aliases, role, context, tools, description), chains, and versioned machine metadata.
subagent({ action: "list", capabilities: true })	Same catalog as compact capability rows: executable/restricted status, runner, tools/model/execution/output/extensions snapshot, restriction sources.
subagent({ action: "list", task? })	Same catalog, plus optional task-aware routing advice; only recommends and never launches.
subagent({ action: "status" })	Show async run status.
subagent({ action: "steer", id, message, index? })	Send guidance to a live top-level async child.
subagent({ action: "stop", id })	Stop an async run.
subagent({ action: "approve-checkpoint", id }) / reject-checkpoint	Resolve an explicit chain checkpoint.
/run <agent> [task] [--bg] [--fork]	Slash form of a single-agent run.
#<agent> [task]	Inline form of a single-agent run: #agent-name anywhere in a message runs that agent directly.
/chain ...	Slash form of a sequential chain.
/parallel ...	Slash form of a parallel run.
/run-chain <chainName> -- <task>	Run a saved .chain.md or .chain.json.
/subagents-doctor	Show setup diagnostics.
subagent({ action: "status" })	Inspect live run status and child activity.
Ctrl+Alt+F	Open the fleet inspector even while a foreground turn is active.
/subagents-stop [<run-id>]	Stop async runs.
/subagent-cost	Show parent and child usage cost for the session.
/subagents-models [<builtin-agent>]	Show runtime-loaded builtin model mapping.
/subagents-watchdog [status|on|off|model ...]	Configure the opt-in watchdog.
/parallel-review, /review-loop, /parallel-research, etc.	Prompt-workflow shortcuts.

Builtin agents

Agent	Use
advisor	Consult on plans and designs; give focused guidance.
delegate	General-purpose delegation for a defined piece of work.
oracle	Answer questions with high-trust sources and reasoning.
researcher	Web/docs research with sources.
reviewer	Review code, plans, and diffs; catch drift and recommend fixes.
scout	Fast local codebase reconnaissance.
worker	Implement approved work and validate results.

Limits and safety

• Child agents run in the same host environment as the parent; trust boundaries are the same.
• Spawned children do not receive the bundled pi-subagents skill by default, and their tool visibility is controlled by the agent’s tools frontmatter. A child only gets a child-safe subagent tool if its resolved tools includes subagent.
• Forked children get filtered context that removes parent-only subagent artifacts.
• Model, tool, usage, and spawn budgets; allowed-agent ceilings; depth limits; checkpoints; and watchdog settings are enforced by the runtime.
• Normal delegated results are reference-first: completion returns saved-output references plus status/lifecycle information; inspect full output through the saved output path, async status/transcript, or resume. outputMode: "inline" restores legacy inline delivery, and output: false disables durable output persistence.
• Task-aware routing advice is advisory and heuristic: it never launches or schedules work, and launch-time preflight remains the enforcement point.
• The bundled pi-subagents extension ships only the built-in agents listed above (plus researcher); custom agent files you add under your own agent directories still work and override builtins of the same name. External CLI agents (Claude Code, Codex, Cursor) are no longer bundled.
• The pi-subagents skill is documentation/prompt guidance, not an independently installed extension entrypoint. It ships both inside the extension and as a top-level bundled skill (src/skills/pi-subagents/) that loads from the package at boot and seeds into the agent dir on first run.

Source evidence

Selesai version: 0.10.0

• Extension source
• README mention