Capabilities and presets

What a capability is

A capability is one name, domain.grade, such as shell.full or git.commit. A preset declares a set of them, and ivralo attaches the tools that answer to each one. So "which tools does this specialist have" is one line of data.

A grant is never a bypass. Holding shell.full means a specialist carries the shell tool at all; the shell policy still judges every command. Capabilities decide what is attached; the tools decide what is permitted, and a person still approves what asks.

Each capability has three properties that matter in practice:

• Gate. Some are effective only while a setting supports them, such as a key being set or the workspace being a git repository. The write grades of Google and GitHub also need a person there to approve.
• Approval. Who says yes per use: nobody (none), the shell policy's answer for that command (verdict), a person on each call who may lift it for the session (call), or a person on each call with no way to lift it (always).
• Strict. Whether the strict profile removes it.

The registry

ivralo doctor prints this table, each specialist's grants as your configuration leaves them, and what the main agent holds.

The baseline

Every specialist gets eight capabilities without declaring them:

A preset may give up baseline names. The Incident Investigator gives up Python, writing, asking a colleague, the databases and photos, so it carries no tool an instruction planted in the evidence could act through.

The strict profile

IVRALO_PROFILE=strict, or --profile strict on a command, takes away everything that reaches outside the workspace or changes your repository: shell.full, network.web, mail.send, message.send, google.write, github.write, code.edit, git.commit and git.push. MCP servers are not attached either. code.read stays, so a strict team still reads the code.

The profile is applied after implied grants are added, name by name, so dropping google.write keeps the google.read it implied. It only ever narrows. A specialist left with nothing to do leaves the team, as the Courier does under strict.

database.read and photos.fetch cannot be dropped yet, because they are part of the baseline.

Unattended runs and server mode

A run nobody attends, such as a pipe, a schedule, a job or an API request sent unattended, is granted nothing that would have to ask. The mode decides the exceptions:

allow_tools in permissions.json lifts named edit and git tools for unattended runs too. See Server mode.

Presets

A preset is what a specialist is built from: a key, a display name, the capabilities it holds beyond the baseline, one sentence on what it is for, and a tool-call limit. It has no prompt of its own. Every specialist is built with the whole skill shelf; the skills it owns come first and are where /skill <name> sends a request.

A tool-call limit of 20 is IVRALO_TOOL_CALL_LIMIT's default; IVRALO_TOOL_CALL_LIMIT_<KEY> sets one specialist's, and IVRALO_MODEL_<KEY> its model. The Code Engineer's Python cannot write files: its changes go through the edit tools, which show each change and ask.

A specialist that declares gated capabilities is on the team only while at least one of them is effective; an ungated one such as shell.full does not keep it there. So the Librarian leaves when the index and the web are both off, the Courier without a mail backend or a chat, the Secretary without a Google service, the GitHub Clerk without a token, and the Code Engineer outside a git repository.

The main agent

You talk to the main agent. It is built like a specialist, from the main preset, with the same toolkits, approvals and limits. It does most of the work itself: it reads files and code, runs Python that only reads, changes code through the edit tools that ask, and runs the project's checks. It hands work to a specialist when a fresh context or a narrower grant is worth it.

Its grants are declared, not inherited. It may hold the union of everything the presets declare, plus the baseline, except:

• every grant that reads one of your accounts: google.read, google.write, github.read, github.write and database.read. Those stay with the specialist you approved;
• team.ask, because it hands work off instead of asking;
• incident.read and incident.report, because only the Investigator files an incident report.

That leaves: python.run, filesystem.read, filesystem.write, user.ask, team.run, photos.fetch, shell.full, index.search, network.web, mail.send, message.send, code.read, code.edit, git.commit and git.push, each still under its gate, the profile and its approval.

IVRALO_MAIN_GRANTS narrows that set: a list of capability names separated by commas or spaces, or none. A name outside the declared set, or one that does not exist, never widens it; ivralo doctor says which names were ignored. However far it is narrowed, the main agent keeps team.run, so it can always hand work to a specialist.

# The main agent only reads; specialists do the writing.
IVRALO_MAIN_GRANTS="filesystem.read code.read python.run"

ivralo incident and POST /incident build a main agent that holds nothing but its hand-offs, so the Investigator does the investigation.