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.
Session roles
Section titled “Session roles”| 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.
Drafts and starts
Section titled “Drafts and starts”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.
Tool availability and refresh
Section titled “Tool availability and refresh”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.
Deterministic boundaries
Section titled “Deterministic boundaries”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.
Commands and signals
Section titled “Commands and signals”| 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.
Delegation and notices
Section titled “Delegation and notices”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.
Shell commands and named tools
Section titled “Shell commands and named tools”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.