Agents & subagents

An agent is a named worker the main agent can delegate a task to via a run_agent tool call. Each dispatch builds a fresh graph — its own system prompt, its own tool set, empty history. Isolation is total: the subagent only ever sees the task text it was handed, and only its final answer returns to the caller. Multiple run_agent calls in one turn execute concurrently, so fan-out search and parallel review happen naturally.

Roster — three layers, later wins on name

built-ins                              explore · general — always available
~/.visvoai/agents/<name>.md            global: personal agents, everywhere
<project>/.visvoai/agents/<name>.md    project: shareable, may be checked in

A definition file is markdown with frontmatter; the body is the system prompt:

---
description: Reviews a diff for bugs and style issues
tools: read-only            # read-only | full | comma-separated tool names
model: gemini:gemini-3.1-flash   # optional — omit to use the session model
---
You are a meticulous code reviewer. ...

Built-ins

• explore — read-only, parallel-friendly reconnaissance. Its shell refuses write-classified commands and its reads run inside the same OS no-write sandbox as the top level — it needs zero approval prompts to do its job. The system prompt explicitly tells it to work breadth-first (list_tree, grep/rg/find via shell) and return a dense, self-contained final answer: concrete paths, line numbers, names, conclusion — no preamble.
• general — the full tool set, edits and shell included. Its mutations go through the same approve() gate as the top level, so you still see every prompt; it just gets to act instead of only reading.

Tool tiers are fixed at graph build time

read-only → read/list/tree/web + a shell that REFUSES write-classified
            commands and runs reads inside the OS no-write sandbox. No
            approval prompts — nothing it can do mutates.
full      → the standard tool set; mutating tools go through the SAME
            approve() gate as the top level (the user still sees prompts).

Neither tier includes run_agent itself — delegation depth is capped at 1. A subagent can't spin up its own subagents, and a read-only agent can't talk itself into more capability mid-run; the tier is baked into the graph before the first token generates.

Trust

A project-defined agent's prompt drives tool use on your machine — same threat model as a project MCP server. It gets one-time approval, recorded outside the repo as a hash of the full definition (~/.visvoai/projects/<project-id>/agent_trust.toml); any change to the file re-prompts you. Global agents (the ones you wrote in ~/.visvoai/) are implicitly trusted.

Watching delegated work

• A live side panel streams every running agent's tool steps as they happen.
• /runs gives full logs per dispatch, with the ability to stop one run without killing the parent turn.

• Every dispatch persists a JSONL trace — tokens, cost, duration — so you can audit what a subagent actually did after the fact.
• Internally, every subagent run is tagged visvoai_subagent:<name>:<dispatch_id> so its events are attributed to exactly one dispatch (parallel dispatches of the same agent are otherwise indistinguishable) and its private messages never leak into main-conversation history.