# Security groups (what the assistant may do without asking)

A **security group** answers one question, tool by tool: *may the assistant do this on its own, must it ask first, or is it off the table entirely?* Three possible answers — **allow**, **require** (ask a human), **deny**.

It is worth being precise about what a group is **not**, because the shield icon invites the wrong guess:

- It is **not a personality or a mode.** Switching group does not change how the assistant talks, what it knows, or which agent is answering.
- It is **not a data boundary.** It never decides which files exist, which folders a person is a member of, or what the sandbox can reach. Those come from membership and the container ([files.md](files.md), [sandbox.md](sandbox.md)).
- It is **not advisory.** The check happens on the server, before the tool runs. A denied tool is not even shown to the model, which is why the assistant will say it cannot do something rather than trying and failing.

## Choosing one: the shield in the chat

The shield pill next to the model pill shows the group the current conversation is on, and switching is immediate — mid-conversation is fine.

**It only appears when the person's role allows more than one group.** For most members there is exactly one, so there is no pill and nothing to choose; that is not a missing feature. Admins always see every group.

The choice is **per conversation** and it sticks: a chat left on a wider group is still on it tomorrow. Every open window of that conversation re-syncs when it changes, so two tabs never disagree.

If a role later loses access to a group, conversations already sitting on it quietly fall back to that role's normal group — at once for open chats, and at the latest next time the conversation is opened. It never falls back to "no group", because that would be *wider*, not narrower.

## What the default group already does

A new instance ships with one group, **Default**, and its policy is *ask unless told otherwise*:

- Anything with no rule of its own → **ask**. This is the catch-all at the bottom, and it is why a brand-new instance asks about things nobody has configured yet.
- Running a shell command → **ask**, always.
- Reading and writing the person's **own** memory → allowed, no friction.
- **Reading** shared memory → allowed. **Writing** it → ask. This is the deliberate one: the assistant must never push one person's information into the shared space without a human saying yes.
- Project folders and the scratch data folder → allowed both ways.
- Reading skills → allowed (a skill is trusted when it is installed, not at each read); the whole tree is read-only anyway.
- Harmless plumbing (showing a file to the user, sending a notification, writing a todo list) → allowed.

So the honest summary for a user asking "what can it do by itself?" is: *read your things freely, work in your own space freely, and ask before running commands or touching anything shared.*

## Editing the rules (admin)

Sidebar → **Security** (admin only). The page lists the groups; a group opens onto its rules, arranged by how they are evaluated:

1. **Overrides** — evaluated first, for exceptions that must beat everything else.
2. **File System** — path-scoped rows: one path per row, with read and write decided separately. This is where "the assistant may write into `docs/` without asking" is expressed.
3. **Per-tool** — one row per known tool, set with a chip: *—* (no opinion), *Allow*, *Req*, *Deny*. Tools are grouped by kind (File System, Shell, Agents, Introspection, Config, and everything a connector or plugin has offered at least once).
4. **Low priority** — broad rules meant to apply only when nothing above matched.
5. **Default action** — what happens when no rule matched at all.

**The first matching rule wins**, and a group's own rules are checked before the Default group's, which sits underneath every group as the fallback tier. That is the practical reason to create a new group by **duplicating** an existing one and changing a few rows, rather than starting from an empty one: an empty group inherits Default and changes nothing.

New groups are created, renamed and deleted from the same page. Assigning them is a separate job, on the **role**: sidebar → **Roles** → edit a role → its default group, plus the additional groups its members may switch to ([access.md](access.md) covers the rest of what a role decides).

## Common questions

- *"Why does it keep asking me the same thing?"* — the rules say ask. The quick fix is the time-limited approval on the card itself ("15 min", "1 hour", "Session" — see [inbox.md](inbox.md)); the durable fix is an admin changing that tool's rule.
- *"Make it stop asking, permanently."* — possible, and worth stating plainly before doing it: allowing a tool means the assistant will use it unattended, including during background work nobody is watching. Shell commands and writes to shared places are the ones to think twice about.
- *"It says it cannot do X — is it broken?"* — check whether X is denied for this group. A denied tool is invisible to the assistant, so it reports an inability, not a refusal.
- *"There is no shield in my chat."* — the role allows one group. Nothing is hidden or broken.
- *"Can a child switch to a wider group?"* — only if their role lists it. The check is on the server: a request naming a group the role does not allow is refused, whatever the interface shows.