Skip to content

Agent operating model

Use this page when you write instructions for an agent that runs in Volli. A Session keeps the conversation and its local history. Its role sets where it works and which agent-control tools it can receive.

Role Working directory Scope
Board Session Project’s main checkout Plan and coordinate project work
Ticket Session Ticket’s worktree, or main checkout when isolation is off Work on one ticket
Subagent Session Parent Session’s working directory Answer a bounded task for its parent

Subagents share their parent’s files, so give each file one owner when you delegate edits. A Subagent Session keeps its own history and returns its answer to the parent. You can inspect children from the parent’s Activity Island.

Selecting Chat in the app opens a draft. The first message creates the Session and starts work. A saved Automation Run or an agent’s session_start call already has an opening instruction, so it creates the Session immediately.

Starting a Session and moving a ticket are separate actions. A deliberate move into a column can also trigger an Automation that is enabled and armed for that column.

Volli records a Session’s tools when it creates the Session. Later refreshes can add eligible tools without removing or renaming tools already recorded. Disabling a server or tool changes the selection for new Sessions; it does not remove that tool from an existing Session’s record. A disabled MCP server still refuses calls until you enable it again.

Tool declarations and the system prompt stay stable while the prompt cache is warm. Eligible additions become available at a cold turn, compaction, or a model switch. Selected tools that run only through Code Mode can become usable before the next program, without changing the warm prompt’s declarations. Volli records the additions and tells the agent when it can use them.

Reopening a Session preserves its recorded tools and additions. Start a new Session when you need a tool selection that excludes previously recorded tools. A delegated helper inherits its parent’s current recorded MCP tools, including refreshed additions.

A Board Session can receive project-management tools that a Ticket Session does not hold by default. New Ticket Sessions include session_send for steering the subagents they delegated; a Board Session can steer any Session in its project. Older Ticket Sessions do not gain this steering permission through a refresh. Subagent Sessions cannot start or steer other Sessions and cannot ask you a question through ask_user.

Run volli help inside the Session to see the tools it holds. Prompt instructions cannot grant a missing tool.

Host requests are checked against per-actor coordination, transcript disclosure, and awaitable policy. Unauthenticated socket callers are read-only by default. Workspace path checks and secret redaction remain independent of that policy. Ordinary tool calls do not go through a model permission judge. Delegation budgets and existing confirmations still use their normal question cards.

Action Effect
volli ticket move Changes the ticket’s board column; an armed Automation may run
volli ticket comment Adds an attributed comment to the ticket
volli ticket signal Records a verdict without moving the ticket
volli session done Records the Session’s completion without moving the ticket
volli session blocked Raises attention on the Session without moving the ticket

If the Session keeps a todo list, session done and session blocked also leave its final list as a comment on its ticket.

Give each delegated task a bounded goal and clear file ownership. Subagents share the parent’s working directory, but keep separate conversations. They have no fixed execution time limit; they finish by answering or when stopped.

The parent receives a notice with the subagent’s final message. Long answers can be truncated in the notice; volli session answer <handle> reads the full answer. An idle parent gets a new turn for the notice; a working parent reads it during its turn.

When available, the watch tool subscribes to Session and ticket changes and returns immediately. Starting or steering a Session also watches its next turn ending, completion or blocked signal, or stop. Use these notices instead of polling session list or parking a long-running shell command.

The volli CLI provides discovery and coordination commands. Agent-control operations, such as starting a Session or running a saved Automation, use named tools supplied to that Session. They have no shell equivalent. Archiving a ticket stays in the app.

The local socket derives attribution from Session authentication. Setting VOLLI_SESSION to an ID does not make a shell that Session. This is not a sandbox against other processes running as your macOS user.

See command effects, agent authority, and agent capability changes for details.