Instances

What an instance is for

The main agent does most of the work itself (Working in a repository). It opens an instance when a fresh context or a narrower grant is worth it: research that would fill its own window, a review by an agent that changes nothing, or several jobs at once. A specialist can open instances too.

An instance is built from a preset (a specialist's definition: its grants, one line on what it is for, and a tool-call limit) exactly as the team member is built: its model, the whole skill shelf, its tools. It starts from the brief and the files it is pointed at, and nothing else of the conversation. The model chooses the specialist and writes the brief; it never chooses the tools.

The tools

run_instance(specialist, brief, paths=[], wait=True)
instance_report(handle, wait=True)
tell_instance(handle, text)
close_instance(handle)

For example, the main agent can open an Incident Investigator with "find which deploy broke the nightly job", a Code Engineer with "fix the off-by-one in jobs/nightly.py and add a test", and a second Investigator with "review the change and say what you did not verify", all with wait=False, then collect the three reports as they finish. The Investigator is the natural reviewer: it never edits.

In the session, each instance's calls stream under the call that opened it with its name in front, such as Code Engineer instance 2 ›, and fold into one line when it reports. The team panel (Ctrl+T) has a row for each.

What an instance may do

Its grants narrow. An instance holds the intersection of its specialist's grants and its opener's, checked in code before anything is built. A reader's instances read, all the way down. A git write (git.commit, git.push) never reaches an instance at any depth. A specialist whose job its opener holds none of is refused rather than opened with nothing to do it with, and the refusal names what is missing:

• the Incident Investigator cannot open a Librarian, because it holds no web access; it can open a Code Engineer that only reads code;
• the Code Engineer cannot open an Investigator or a Librarian; a coder that needs research says so in its report;
• the main agent holds no account read, so an instance of the Secretary (Google) or the GitHub Clerk it opens asks you first, and is refused unattended. Your yes is lifted into that instance, and its report says so.

An instance narrowed this way is told so in its first message, and its report says what it was without.

Its changes ask you. An instance's edits, commands and Python reach the same dialog as a member's, which names whose instance asks for whom and the brief. Where nobody can approve, as in ivralo ask, a schedule or a job, an instance only reads and its report says what it would have changed. A send asks every time.

A Code Engineer instance works in a worktree of its own, cut from HEAD beside the parallel coders, at <home>/worktrees/<slug>-<hash>/instance-<hex>. Your uncommitted changes are not in it, and it is told so. When it reports, its change comes back as one patch through the integration dialog (Editing and approvals), unless edits are accepted for the session or edit_file is in allow_tools. A refusal keeps the worktree and the report says where; remove it with git worktree remove <path> when you are done. A conflict leaves git's markers in your workspace for the caller to resolve. While a changeset is open, no Code Engineer instance that edits is opened.

The web taints. A run that has read the web, itself or through an instance's report or a colleague's answer, opens no further instance and asks no colleague.

The report

A report opens with one line ivralo writes: who, its run, its calls, the refused ones, its tokens and its time. Then come the instance's answer, one line per call it made, and what it changed. The instance's run is stored as a session of its own, never listed among your conversations, and ivralo why follows a claim through the report into it.

How long it lives

An instance belongs to the session, not the turn. A handle still works in the next turn. An instance ends when its report is collected, when it is closed, or when the session ends (exit, /new, or the end of an ivralo ask run); the turn summary says which ended how. Esc on a turn asks whether to stop its running instances or keep them.

/instances              the open instances, working or with a report ready
/instances stop 2       stop one, and everything it opened
/instances stop all     stop them all

Limits

Instances can open instances of their own: a research instance fans out to two readers, a coder instance opens its own reviewer.

The depth and the budget are what keep a small model from turning one task into thirty contexts. Every instance is a model stream of its own, and a Code Engineer instance is also a worktree and a worker process, so keep your machine in mind.

A coder instance opened by a coder instance is cut from its parent's checkout, and its patch lands in the parent's worktree without a second question; you are asked once, when the parent's patch reaches your workspace.

Asking a colleague instead

A specialist that needs one answer, not a whole job, can put a question to a colleague with ask_member, such as the Code Engineer asking the Librarian what a library's documentation says. The colleague answers from its own run. The transcript shows it as one step of the asker's, and opening it shows who answered, the answer, and one line per tool call the colleague made.

A question to a colleague that reads the workspace or the web opens no dialog. A question to one that reads an account (the Secretary for your mail, the GitHub Clerk) asks you first. If the colleague's run makes a call that asks, that call reaches the same dialog, headed with who is answering whom.

The main agent does not ask colleagues: it delegates or opens an instance. No instance carries ask_member either.