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

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

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)
• skills — skill allowlist; empty means all discovered skills from the child session loader
• visable — 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, but Chimera discovery and execution still can

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: []
visable: 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

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 use no extension, prompt-template, or theme discovery.
• YAML definitions specialize the child via model selection, thinking effort, system prompt replacement, prompt prefixing, built-in tool allowlists, skill allowlists, and optional Vera-side visibility control through visable.
• The child session uses SessionManager.inMemory() and does not persist its own conversation.
• 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 agent/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.