vera-subagents

Purpose

Provide an in-process SDK-based subagent tool for Vera. The current version runs delegated work in an isolated in-memory Pi AgentSession, returns the final answer to the parent agent, and exposes execution details in the tool's expandable TUI view.

Registered tools

• subagent — run one delegated task in an isolated SDK subagent session; supports foreground and background execution with expandable TUI details
• subagent_status — inspect queued, running, and recently completed background subagent jobs
• subagent_cancel — cancel one background subagent job or all active background jobs
• subagent_inspect — inspect a persisted subagent run by runId

Registered commands / UI

• /subagents — show a Vera-style detailed status report for the subagent system, including registry discovery, runtime surface, and background jobs
• /subagents cancel <jobId|all> — cancel one background job or all active jobs, then show the updated detailed report
• TUI session status entry subagents — compact live indicator for queued/running/finished background jobs
• TUI subagent cards above the editor — live foreground/background run cards with Alt+1…9 focus overlays for details

YAML-defined subagents

Subagent definitions are loaded from:

• ~/.pi/agent/subagents/*.yaml
• nearest .pi/subagents/*.yaml walking up from the current cwd

Supported YAML fields:

• name — unique subagent name; duplicates are rejected
• model — child model in provider/model format; empty means inherit the current parent model
• effort — child thinking strength (off, minimal, low, medium, high, xhigh); empty means inherit the current parent thinking level
• description — shown to the parent LLM so it knows when this subagent is appropriate
• system — fully replaces the subagent base system prompt when present
• Prompt or prompt — prepended before the delegated task text
• tools — built-in tool allowlist; empty means all built-in tools (read, bash, edit, write, grep, find, ls)
• extensionTools — extension tool allowlist; empty means extension discovery stays disabled in child sessions
• skills — skill allowlist; empty means all discovered skills from the child session loader
• visible — optional boolean; defaults to true. When false, Vera does not see the definition in its subagent catalog and cannot call it through the subagent tool

Example:

name: scout
model: anthropic/claude-sonnet-4-5
effort: medium
description: Fast repository reconnaissance for code lookup and evidence gathering
system: |
  You are a focused reconnaissance subagent.
  Gather evidence and answer concisely.
prompt: |
  Prefer quick inspection over broad rewrites.
tools:
  - read
  - grep
  - find
  - ls
skills: []
visible: true

Current scope

• single subagent execution per tool call
• in-process SDK session, not subprocess execution
• named YAML-defined subagents or generic ad-hoc delegation
• background: true on the tool call to let a child keep running asynchronously
• completion notification injected back into the main session when a background job finishes
• cancellation for queued/running background jobs
• /subagents command and TUI status indicator for quick inspection
• custom expandable TUI renderer for execution details

Tool-call overrides

• model — optional model override in provider/id form; takes precedence over the YAML definition's model field.
• thinkingLevel — optional effort override (off|minimal|low|medium|high|xhigh); takes precedence over both YAML effort and the inherited main-agent level.
• Omitting either parameter preserves the existing YAML/inherited fallback behavior.

Persistence & resume

Each run persists a compact run.json plus its SDK session file under the agent home, independent of the project working directory:

• Location: ~/.pi/agent/state/subagents/<runId>/. The root is the resolved Pi agent directory (PI_AGENT_DIR override, then module-path discovery, then ~/.pi/agent), never the current project cwd. The subagent's own working directory is a separate concern and is unaffected.
• run.json records phase, task, selected agent config, usage, and timeline, alongside the session file path; the SDK session file holds the conversation needed to reopen the run.
• Resume an interrupted run with the subagent tool's resumeRunId (mutually exclusive with task/agent/model/thinkingLevel/systemPrompt/cwd). The working directory is restored from the persisted run, not the caller's cwd.
• Inspect a persisted run with subagent_inspect (runId). Both accept an optional resumeArtifactsDir / artifactsDir override for runs stored outside the default path.
• A startup sweep removes completed runs after 7 days and interrupted runs after 30 days.

Non-goals

• parallel or chained subagents
• session focus switching into a fully separate child TUI
• project/user agent markdown discovery
• memory writeback from child sessions

Design notes

• Child sessions always disable theme and prompt-template discovery. Extension discovery is disabled by default; when a definition lists extensionTools, only those named extension tools are re-enabled and passed into createAgentSession alongside the selected built-in tools.
• When hashline.enabled is set in vera-theme.json, child sessions install the same hash-anchored read/edit pair as the main agent, passed via customTools to createAgentSession, so LINE#ID anchors stay consistent across parent and delegated agents. The implementation lives in vera-theme and is imported through its public barrel.
• YAML definitions specialize the child via model selection, thinking effort, system prompt replacement, prompt prefixing, built-in tool allowlists, extension tool allowlists, skill allowlists, and optional Vera-side visibility control through visible.
• Initial runs persist through SessionManager.create(...), writing the SDK session file into the run's artifacts directory so an interrupted run can be reopened with SessionManager.open(...) on resume. See "Persistence & resume" for the on-disk layout.
• The parent tool stores a compact execution timeline in details so the current TUI can render it in collapsed and expanded states.

Smoke

• npm run smoke
• from project root: node scripts/smoke-all.mjs

Debugging

1. Verify the tool is registered from ./packages/vera-subagents.
2. Place a simple YAML file in ~/.pi/agent/subagents/ and reload.
3. Run subagent with agent: "name" and a bounded task.
4. Use background: true when the child should continue asynchronously while the main agent proceeds.
5. Run subagent_status for a compact tool response, or /subagents for a fuller Vera-style system status report.
6. Run subagent_cancel or /subagents cancel <jobId|all> to stop background work that is no longer wanted.
7. Watch the subagents TUI status entry for a compact live job indicator.
8. Expand the tool result or background notification in the TUI to inspect task, cwd, selected tools, selected skills, timeline, and final output.
9. If execution fails, inspect details.error and YAML parse/duplicate warnings first.

Loaded through agent/settings.json as ./packages/vera-subagents.