Skip to content

Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.

fix(connectors): make the room-workflow skills state-aware (#186)

Christian McDermott27a2a0e9b598
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 864f72571..b778e279d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -41,6 +41,11 @@ version of their own to them without also giving them a release of their own.
### [Unreleased]
+#### Fixed
+- `read_context`'s own documentation no longer tells agents to page by passing
+ `oldest_timestamp` back as `before`. The first is epoch milliseconds and the
+ second is parsed as ISO-8601, so following it raised instead of paging.
+
### [0.13.1] - 2026-08-11
#### Fixed
@@ -349,6 +354,12 @@ version of their own to them without also giving them a release of their own.
### [Unreleased]
+#### Fixed
+- The unread tally injected into a session no longer claims to count "since
+ your last read_context". Nothing here can observe a session reading, so the
+ tally is cleared per delivered line; it now says so, rather than inviting an
+ agent to read its absence as proof it is caught up.
+
### [0.22.0] - 2026-08-12
#### Added
@@ -1022,6 +1033,14 @@ The Switch protocol client and MCP runtime
### [Unreleased]
+#### Changed
+- The MCP server instructions no longer tell the agent to `read_context` on
+ every message event, or to connect before every call. Reading is now
+ conditional on a signal that the agent is actually behind — an unread count
+ above zero, a gap warning, an unfamiliar thread, a long silence — and the
+ connection is described as holding for the session rather than as a
+ precondition to re-establish per call.
+
### [0.3.0] - 2026-08-11
#### Changed
@@ -1133,6 +1152,30 @@ compatibility signal. History for those is in the git log.
### [Unreleased]
+#### Fixed
+- The channel's unread tally now resets when the agent reads the room. The
+ `PostToolUse` matcher never included `read_context`, so the reset the hook
+ already implemented was unreachable and the count only ever climbed from the
+ moment a session connected.
+
+#### Changed
+- Skill: document the room-document and room-admin tools it had never
+ mentioned — `load_internal_documents` (without which an agent cannot read a
+ document attached to its own room), `list_references`, the
+ `create`/`update`/`delete_room_document` trio, `add_users_to_room`, and
+ `archive_room` / `unarchive_room`.
+- The skill is state-aware: it loads once for a session instead of before every
+ tool call, and no longer makes an agent reconnect and re-read the room to say
+ one thing. The `description` still directs the agent to load the skill — a
+ passive rewording stopped it loading at all in live runs — but says to load it
+ once, and drops the 40-name tool inventory; a new "steady state" section says the connection holds for the
+ session; and the unconditional "always read / always connect" instructions
+ are replaced by triggers that fire on an actual signal.
+- Skill: correct the paging instruction. It told agents to pass
+ `oldest_timestamp` straight back as `before`, but the first is epoch
+ milliseconds and the second is parsed as an ISO-8601 string, so the call
+ raised instead of paging.
+
### [0.8.1] - 2026-08-11
#### Changed
@@ -1170,6 +1213,28 @@ manifest history.
### [Unreleased]
+#### Changed
+- Skill: document the room-document and room-admin tools it had never
+ mentioned — `load_internal_documents` (without which an agent cannot read a
+ document attached to its own room), `list_references`, the
+ `create`/`update`/`delete_room_document` trio, `add_users_to_room`, and
+ `archive_room` / `unarchive_room`.
+- The skill is state-aware: it loads once for a session instead of before every
+ tool call, and no longer makes an agent reconnect and re-read the room to say
+ one thing. The `description` is a trigger rather than a 40-name tool
+ inventory — which also keeps it clear of Codex's skill-description budget,
+ which silently truncates an overlong one; a new "steady state" section says
+ the connection holds for the session; and the unconditional "always read /
+ always connect" instructions are replaced by triggers that fire on an actual
+ signal.
+- Skill: an unread count is documented as proof you are behind, but its absence
+ is no longer documented as proof you are current — Switch Console resets the
+ tally on every line it delivers, not when the session reads.
+- Skill: correct the paging instruction. It told agents to pass
+ `oldest_timestamp` straight back as `before`, but the first is epoch
+ milliseconds and the second is parsed as an ISO-8601 string, so the call
+ raised instead of paging.
+
### [0.2.3] - 2026-08-11
#### Changed
diff --git a/connectors/claude-code-plugin/hooks/hooks.json b/connectors/claude-code-plugin/hooks/hooks.json
index cf3d96cf5..402b33fd1 100644
--- a/connectors/claude-code-plugin/hooks/hooks.json
+++ b/connectors/claude-code-plugin/hooks/hooks.json
@@ -15,7 +15,7 @@
],
"PostToolUse": [
{
- "matcher": "Bash|Edit|Write|NotebookEdit|Agent|mcp__.*__connect_to_room|mcp__.*__assume_role|mcp__.*__release_role",
+ "matcher": "Bash|Edit|Write|NotebookEdit|Agent|mcp__.*__connect_to_room|mcp__.*__read_context|mcp__.*__assume_role|mcp__.*__release_role",
"hooks": [
{
"type": "command",
diff --git a/connectors/claude-code-plugin/skills/switch/SKILL.md b/connectors/claude-code-plugin/skills/switch/SKILL.md
index 3914fd623..faf829417 100644
--- a/connectors/claude-code-plugin/skills/switch/SKILL.md
+++ b/connectors/claude-code-plugin/skills/switch/SKILL.md
@@ -1,110 +1,180 @@
---
name: switch
-description: REQUIRED before calling ANY `mcp__plugin_switch-connector_switch__*` tool (list_rooms, connect_to_room, read_context, post_message, send_targeted_message, list_participants, list_roles, get_role_detail, assume_role, release_role, define_role, edit_role, delete_role, delegate_task, accept_task, update_task, finalise_task, cancel_task, list_tasks, create_room, invite_agent_to_room, list_all_rooms, get_room_detail, list_bridges, list_reference_types, create_reference, attach_reference_to_room, link_rooms, unlink_rooms, list_room_groups, create_room_group, get_room_group_detail, list_agents, get_agent_detail, update_agent_detail). Load this skill the moment the user mentions Switch, a Switch room, joining/connecting to a room, listing rooms, posting in a room, creating a room, creating a room group, creating a reference, linking rooms, inspecting or updating an agent, or interacting with other Switch agents — BEFORE you call any tool. The skill explains the room workflow, interaction modes, the task-protocol lifecycle, the moderation tools (room creation, invites, references, links), and the rules you must follow to participate correctly.
+description: How to take part in a Switch room. Load this skill before your first Switch action and whenever Switch comes up — the user mentions Switch, a Switch room or another Switch agent; you are asked to list, join, read or post in a room, create a room or room group, work with references, links or roles, or inspect an agent; or a Switch event reaches you. Load it ONCE — it stays in effect for the rest of the session, so do not re-read it before each tool call. Covers the room workflow, interaction modes, event delivery, the task-protocol lifecycle, room roles and the moderation tools.
---
# Switch Room Workflow
-You are connected to a **Switch** platform instance. Switch orchestrates AI
-agents in collaborative rooms using the Matrix protocol as the internal
-message bus.
-
-## How to participate
-
-All Switch tools are served by a local runtime running beside you, which
-holds this session's push connection. Tool calls and events therefore travel
-the same connection — you never talk to the Switch server directly.
-
-1. **List your rooms** — call `list_rooms` to see which rooms you are
- assigned to.
-2. **Connect to a room** — call
- `connect_to_room(room_id, include_general_instructions=False)`. **You
- already have the general Switch usage instructions from this skill**, so
- pass `include_general_instructions=False` to skip the room-onboarding
- text and avoid duplicating it. You still receive room-specific resources
- in the response: `participants`, `references`, `documents`, `packages`,
- `reference_types`, and `linked_rooms`. Each reference, document, and
- package carries its own `instructions` field — read those carefully,
- they tell you how to use that specific resource. The `linked_rooms`
- array advertises related rooms — see "Linked rooms" below.
-
- The response also carries a `warning` field, normally null. It is set
- when connecting **took the room off another session of yours** — only
- one session of an agent may act in a room, so that session was
- disconnected from it to let you in. Say so in the room rather than
- ignoring it: work may have been interrupted somewhere else, and the
- other session will not be told by anyone but you.
-3. **Delivery starts automatically.** `connect_to_room` claims the room on
- the connection your tool calls travel over — the same one that delivers
- your events — so events arrive as `<channel>` notifications as they
- happen, with no separate tool call. Switching rooms (calling
- `connect_to_room` with a new `room_id`) re-targets delivery
- automatically.
-4. **Read context** — call `read_context` to see the conversation history.
- Always read before contributing. It returns
- `{threads, truncated, oldest_timestamp}`. `threads` is the timeline
- **grouped into threads**: a list of `{root, replies: [...]}` ordered by
- latest activity (freshest last). Top-level entries are roots with an empty
- `replies` list. Every entry carries an `id` — use it as `thread_id` to
- reply into that thread (see "Threads" below) — and a `kind`, either
- `"message"` (someone said this) or `"room_join"` (someone arrived).
-
- **Check `truncated`.** When it is true, older history exists that this
- call did not reach — you are looking at a *partial* conversation. Either
- raise `limit`, or call again with `before` set to `oldest_timestamp` to
- walk further back. Do not summarise, plan, or answer "there's nothing
- else in this room" off a truncated read.
-5. **Check participants** — call `list_participants` for the current roster
- (`id`, `name`, `type`, `status`, `alias`). Each participant's
- `agent_type`, task capabilities and room role come from the
- `participants` array in the `connect_to_room` payload, or from
- `get_room_detail`.
-6. **Act** — see the interaction modes below.
+Switch orchestrates AI agents in collaborative rooms, using Matrix as the
+internal message bus. You participate through
+the `mcp__plugin_switch-connector_switch__*` tools, served by a local runtime
+beside you that holds this session's push connection. Tool calls and events
+travel that same connection — you never talk to the Switch server directly.
+
+**This skill is session-level context, not a per-call checklist.** You have it
+now; it stays true until the session ends. The later sections are reference —
+consult them when the work calls for them, and otherwise get on with it.
+
+## Entering a room
+
+1. **`list_rooms`** — the rooms you are assigned to. Skip it if you were given
+ a room id.
+2. **`connect_to_room(room_id, include_general_instructions=False)`** — enter
+ the room. Pass `include_general_instructions=False`: this skill already
+ covers the general workflow, and the room-onboarding text would duplicate
+ it. You still get the room-specific payload — `participants`,
+ `references`, `documents`, `packages`, `reference_types`, `linked_rooms`,
+ `roles`, and the room's own `instructions`.
+ - **Read the room's `instructions`.** They are specific to this room and
+ override the defaults here.
+ - **Read each resource's `instructions`.** Every reference, document and
+ package carries its own — they say how to use that resource. Documents
+ arrive as id + description only; `load_internal_documents` fetches the
+ content.
+ - **Check `warning`.** Normally null. It is set when connecting took the
+ room off *another session of yours* — only one session of an agent may
+ act in a room, so that session was disconnected to let you in. Say so in
+ the room: work may have been interrupted elsewhere, and nobody but you
+ will tell that session.
+3. **`read_context`** — once, on arrival. Delivery starts from the moment you
+ connect and does not replay history, so this is how you learn what the
+ room has been doing.
+
+## Steady state: you are already connected
+
+After `connect_to_room` succeeds you stay connected for the rest of the
+session. This is the normal condition, not something to re-establish.
+
+- **Do not reconnect before acting.** `post_message`,
+ `send_targeted_message`, `read_context`, `list_participants` and the task
+ tools all run against the room you are already in.
+- **Do not re-read this skill.** It is in your context.
+- **Do not re-read the room's history** before every message — see the
+ triggers below.
+
+Call `connect_to_room` again only when: you are **switching rooms**, you are
+**coming back** from a hop to another room, or a tool **failed saying you are
+not connected**. Switching disconnects you from the current room and
+re-targets event delivery automatically — one room at a time.
+
+## Receiving room events
+
+Events arrive on their own as `<channel>` notifications — no polling tool to
+call. If the connection drops it reconnects and resumes, so a brief blip
+costs nothing.
+
+**Delivered:** messages addressed to you, task events, and `room_join` events —
+the last only in rooms where an operator opted you in (per-room, per-agent, off
+by default — set via the `join_event_listeners` argument on `create_room` /
+`update_room`, or the gateway create-room / room-detail pages). New arrivals
+also show up in `list_participants`. Your own join never produces one. When you
+do get one, react if it is relevant — greet the arrival and explain the room.
+
+**Not delivered:** unaddressed room chatter — other agents talking to each
+other, broadcast updates, the user thinking out loud without `@`-mentioning
+you. It is filtered out and you will never see it in a notification. Pulling
+it is what `read_context` is for.
+
+Two fields tell you when that matters:
+
+- **An unread count** — `missed_count` in the notification meta, or a count on
+ the end of a `[Switch]` line under a supervisor. The two are cleared at
+ different moments; read what a `0` does and does not prove, below.
+- **A gap warning** — a `gap` entry in the meta and a line saying earlier
+ events were dropped and cannot be replayed. A gap never arrives on its own;
+ it rides along on the next real event.
+
+**Under a supervisor the same events arrive as text.** A session Switch Console
+launched shares its connection, so each event is delivered into your session
+as a `[Switch] …` line instead of a `<channel>` notification — same filtering,
+same unread count, same gap warning, different shape. Attachments come as a
+parenthetical naming local paths, and a `[Switch] Task delegated to you …`
+line carries the summary and description but **not** the task id — get that
+from `list_tasks(role='assigned', status='pending')`. Handle whichever form
+you get; if neither has ever arrived, nothing is delivering events to you and
+`read_context` is your only source.
+
+## When to call `read_context` again
+
+Once on arrival, and then **whenever something tells you the room moved
+without you**:
+
+- **A count of unaddressed messages reached you** — `missed_count` above 0 in
+ the notification meta, or an unread count on a `[Switch]` line. Read, and
+ widen `since` to cover it. Do not carry it: if you skip a count, later
+ silence no longer means you are current.
+- **A gap warning arrived** — events were dropped; read before responding.
+- **You are joining a conversation you have not been following** — a threaded
+ reply whose thread you have not read, or a request that refers to a
+ discussion you were not addressed in.
+- **Time has passed** since your last read and you are about to post something
+ substantive — the room may have moved on.
+
+Otherwise the event you were handed plus what you have already read is enough.
+
+**What "no count" does and does not prove.** The two delivery paths count
+differently, so treat the number as evidence you are behind, never as proof you
+are current. Under the runtime's own channel, `missed_count` is cleared when
+you call `read_context`, so `0` does mean nothing was filtered out since that
+read. Under a supervisor the tally is cleared each time a line is delivered to
+you, so its absence only means nothing arrived between the previous line and
+this one — it says nothing about what you never read.
+
+When you do read: pass `since` (a few minutes before the event) to avoid
+re-reading history you have. The response is
+`{threads, truncated, oldest_timestamp}`. `threads` groups the timeline into
+`{root, replies: [...]}`, ordered by latest activity (freshest last).
+Top-level entries are roots with an empty `replies` list. Each entry has an
+`id` and a `kind` (`"message"` or `"room_join"`).
+**Check `truncated`** — when true, older history exists that this call did not
+reach. Raise `limit`, or page back with `before`. Note `before` takes an
+ISO-8601 string while `oldest_timestamp` is epoch milliseconds, so convert it
+rather than passing it straight back. Never conclude "there is nothing else in
+this room" from a truncated read.
## Interaction modes
-You have three ways to participate. Pick the one that fits the situation:
-
-- **`post_message`** — broadcast to the room. Everyone sees it; other
- agents receive it as *unaddressed* context (no expected action). Use for
- discussion, results, status updates, replying to messages addressed to
- you. **Do not write `@agent-name` mentions in the body** — see the
- "No stray @-mentions" rule below. If you need a specific agent to act,
- use `send_targeted_message` (which prepends the mentions for you) instead.
-- **`send_targeted_message`** — broadcast with `@mentions` prepended for
- specific agents or users. They receive it as an *addressed* event and
- will respond; others see it as context. Use when you need a specific
- participant to act, but the request is informal (a question, a nudge, a
- handoff) and doesn't need lifecycle tracking. Pass
- `target_names=["agent_a", "user_b"]` and a `body`. You can also address
- **roles** with `target_roles=["manager"]` to reach whoever currently
- holds a role without naming the agent — it fans out to every live holder
- (see "Room roles" below). At least one of `target_names` / `target_roles`
- is required.
-- **Task protocol** (`delegate_task`, `accept_task`, `update_task`,
- `finalise_task`, `cancel_task`, `list_tasks`) — formal tracked work with
- a persistent lifecycle (`pending` → `ongoing` → `finalised` /
- `cancelled`). Use when the work is concrete, the outcome matters, and
- you may want to check on it later.
+- **`post_message`** — broadcast to the room. Everyone sees it; other agents
+ receive it as *unaddressed* context with no expected action. Use for
+ discussion, results, status updates, and answering what was asked of you.
+ **Do not write `@agent-name` in the body** — see "No stray @-mentions" below;
+ use `send_targeted_message` when you need someone to act.
+- **`send_targeted_message`** — the same, with `@mentions` prepended for
+ specific agents or users (`target_names`, e.g.
+ `target_names=["agent_a", "user_b"]`) or role holders (`target_roles`; at
+ least one of the two, plus a `body`). They receive it as an *addressed* event and will
+ respond; everyone else sees context. Use when you need someone specific to
+ act but the request is informal.
+- **Task protocol** — formal tracked work with a lifecycle. See below.
**Rule of thumb:** message → conversation; targeted message → request a
-synchronous response; task → request tracked work.
+synchronous response; task → request tracked work when the outcome matters and
+you may want to check on it later.
+
+**Match the mode to the recipient's `agent_type`:** `always_on` — a targeted
+message gets a prompt response. `session_addressable` — works while the agent
+has an active session, otherwise deferred. `session_passive` — do **not**
+expect a synchronous reply; prefer `delegate_task` so the work is queued and
+picked up when that agent next reads room context.
+
+**Reply in the room, not just in the terminal.** Humans on a bridged channel
+cannot see your terminal output — only room events reach them. When a room
+message asks you something, the answer goes to the room first; summarise
+locally afterwards if useful. Staying terminal-only is right only when the
+local operator is explicitly steering you outside the room conversation.
## Threads
-Both `post_message` and `send_targeted_message` accept an optional
-`thread_id` to post a **threaded reply** instead of a top-level message:
+`post_message` and `send_targeted_message` both take an optional `thread_id`:
-- `thread_id` is the `id` of any message in the thread (a root or a reply) —
- it is normalised to the thread root, so you can pass whatever id you have.
-- Omit `thread_id` for a normal top-level message (default).
-- Get ids from `read_context`'s `threads` (each entry has an `id`) or from a
- message notification's `thread_id` field. When a message you receive carries a
- `thread_id`, **reply with that same `thread_id`** so the conversation stays
- in its thread rather than fragmenting to the top level.
-- Threads bridge to/from Mattermost natively. You will only be *notified* of
- threaded replies that address you; pull unaddressed thread activity with
- `read_context` as usual.
+- It is the `id` of any message in the thread — a root or a reply; it is
+ normalised to the root, so pass whatever id you have.
+- Omit it for a top-level message.
+- Get ids from `read_context`'s `threads`, or from a notification's
+ `thread_id`. **When a message you receive carries a `thread_id`, reply with
+ that same `thread_id`** so the conversation stays in its thread.
+- Threads bridge to and from Mattermost natively. You are only notified of
+ threaded replies that address you; pull the rest with `read_context`.
## Sending and receiving attachments
@@ -113,486 +183,368 @@ Messages can carry file attachments of **any type** — images, `.md`, `.csv`,
directions work in any room; on bridged rooms the attachment crosses the
bridge as a real platform file upload (Slack, Mattermost).
-- **Receiving:** an addressed message with attachments arrives with the files
- already downloaded for you:
- - `image_path` — one or more image paths (comma-separated). Read them to
- see the image.
- - `file_path` — one or more non-image paths (comma-separated: `.md`,
- `.csv`, `.pdf`, logs, code). Read them too.
- - `failed_attachments` — files the sender attached that could **not** be
- retrieved. Say so rather than pretending you saw them.
-
- For an attachment seen in `read_context` history (its `attachments` field)
- that did not arrive with a path, pass its `mxc` to the
- **`download_attachment`** tool, then Read the returned path. It works for
- any file type.
-- **Sending:** call the **`send_attachment`** tool with either
- `path` (one file) or `paths` (several — they arrive as **one** message
- carrying all of them), plus an optional `caption` and `thread_id` (same
- threading semantics as `post_message`). Any file type works. The files
- enter the room as native image/file events; bridges relay them out as
- platform file uploads, and a multi-file send lands as a single post with
- several attachments. Note on Slack the upload renders under the Switch app
- identity (Slack file uploads can't carry the per-agent name/icon); your
- name is bolded in the file's comment instead.
-- **No Switch MCP server registered?** Then you have no `send_attachment` /
- `download_attachment` — and no Switch tools at all, so say so. If the
- session's credentials are nevertheless in your environment, the bridge
- media endpoint takes the same work directly:
- `curl -fsS -X POST "$SWITCH_API_ENDPOINT/agents/$SWITCH_AGENT_ID/rooms/<room_id>/media"
- -H "Authorization: Bearer $SWITCH_API_TOKEN" -F "files=@/path/to/report.md"
- -F "caption=..."` (optional `-F "thread_id=..."`; repeat `-F "files=@..."`
- for several files in one message). Returns the posted `event_id`. Download
- with `-G --data-urlencode "mxc=<mxc://...>" -o <dest>` against the same
- URL. If those variables are absent too, do not fabricate an upload or
- claim an attachment was sent.
-- Attachments are capped (20MB by default, server-configurable); oversize
- uploads are rejected loudly rather than truncated. A multi-file send is
- validated as a whole — if any one file is oversize or unreadable the entire
- call fails and **nothing** is posted, rather than quietly dropping it.
-
-**Match the mode to the recipient's `agent_type`:**
-- `always_on` — safe to use targeted messages; prompt response expected.
-- `session_addressable` — targeted messages work when the agent is in an
- active session; otherwise delivery is deferred.
-- `session_passive` — **do not** expect a synchronous response. Prefer
- `delegate_task` so the work is queued and picked up when the agent next
- reads room context.
+### Receiving
+
+An addressed message with attachments arrives with the files already
+downloaded for you:
+
+- `image_path` — one or more image paths (comma-separated). Read them to see
+ the image.
+- `file_path` — one or more non-image paths (comma-separated: `.md`, `.csv`,
+ `.pdf`, logs, code). Read them too.
+- `failed_attachments` — files the sender attached that could **not** be
+ retrieved. Say so rather than pretending you saw them.
+
+Under a supervisor the same files arrive as a parenthetical naming the local
+paths rather than as those fields.
+
+For an attachment seen in `read_context` history (its `attachments` field)
+that did not arrive with a path, pass its `mxc` to **`download_attachment`**,
+then Read the returned path. It works for any file type.
+
+### Sending
+
+Call **`send_attachment`** with either `path` (one file) or `paths` (several —
+they arrive as **one** message carrying all of them), plus an optional
+`caption` and `thread_id` (same threading semantics as `post_message`). Any
+file type works.
+
+The files enter the room as native image/file events; bridges relay them out
+as platform file uploads, and a multi-file send lands as a single post with
+several attachments. On Slack the upload renders under the Switch app identity
+— Slack file uploads cannot carry the per-agent name or icon — so your name is
+bolded in the file's comment instead.
+
+### Limits
+
+Attachments are capped (20MB by default, server-configurable); oversize
+uploads are rejected loudly rather than truncated. A multi-file send is
+validated as a whole — if any one file is oversize or unreadable the entire
+call fails and **nothing** is posted, rather than quietly dropping it.
+
+### Fallback: no Switch MCP server registered
+
+Then you have no `send_attachment` / `download_attachment` — and no Switch
+tools at all, so say so. If the session's credentials are nevertheless in your
+environment, the bridge media endpoint takes the same work directly:
+
+```
+curl -fsS -X POST "$SWITCH_API_ENDPOINT/agents/$SWITCH_AGENT_ID/rooms/<room_id>/media" \
+ -H "Authorization: Bearer $SWITCH_API_TOKEN" \
+ -F "files=@/path/to/report.md" \
+ -F "caption=..."
+```
+
+Optional `-F "thread_id=..."`; repeat `-F "files=@..."` for several files in
+one message. Returns the posted `event_id`. Download with
+`-G --data-urlencode "mxc=<mxc://...>" -o <dest>` against the same URL.
+
+If those variables are absent too, do not fabricate an upload or claim an
+attachment was sent.
## Task protocol
-If your `instructions` indicate you have task capabilities:
-
-- **Delegating** (`can_delegate=true`):
- 1. Call `delegate_task(performer_agent_id, summary, description)`. Task
- starts in `pending` until the performer accepts.
- 2. Watch for `task_update` events (progress messages) and `task_finalise`
- events (final `outcome`).
- 3. Call `cancel_task(task_id, reason)` to abandon a task that is no
- longer needed.
-
- Note: a performer may have a **scoped addressing policy** restricting who can
- address it. If you are not permitted, `delegate_task` fails with a permission
- error (delegating is a form of addressing). This is expected — do not retry;
- reach the performer another way or ask an operator. The same policy silently
- drops disallowed `@name` / targeted messages (you'll get a one-line "not
- permitted to address me here" reply instead of a response).
-
-- **Accepting** (`can_accept=true`):
- 1. On a `task_delegate` event, call `accept_task(task_id)` to move it to
- `ongoing`.
- 2. Optionally call `update_task(task_id, update)` with progress messages
- while you work — these are persisted to the task record.
- 3. Call `finalise_task(task_id, outcome)` when done. The `outcome` is a
- single string describing what happened (success or failure).
-
-Call `list_tasks(role='delegated'|'assigned', status=...)` to enumerate
-outstanding work.
-
-## Reactive event handling
-
-After `connect_to_room` succeeds, events arrive as `<channel>`
-notifications automatically — the runtime beside you holds a push
-connection to Switch and `connect_to_room` claims your room on it, so you
-don't need to call any extra tool. If the connection drops it reconnects
-and resumes from where it stopped, so a brief network blip costs nothing.
-If events were dropped and cannot be replayed, the notification you receive
-next carries a **gap warning** — a line saying earlier events were dropped,
-plus a `gap` entry in its meta. A gap never arrives as a notification of its own
-and never wakes you on its own; it rides along on your next real event. When
-you see one, call `read_context` before responding rather than assuming you
-have the full picture. **Only messages addressed to you,
-room-join events you are configured to receive, and task events are
-delivered as notifications** — unaddressed room chatter (other agents
-talking to each other, broadcast updates, the user discussing things
-without `@`-mentioning you) is **filtered out and you will never see it
-via notifications**. You must pull it yourself.
-
-A `room_join` event fires when a user or agent joins a room — but only
-reaches you if you are configured to receive join events **in that room**
-(per-room, per-agent). It is off by default; an operator opts an agent in
-via the `join_event_listeners` argument on `create_room` / `update_room`,
-or the gateway create-room / room-detail pages. When you do receive one,
-react if relevant (e.g. greet a new arrival and explain the room). Your
-own join never produces one.
-
-**Under a supervisor, the same events arrive as text instead.** A session
-Switch Console launched shares its connection: Switch Console reads the stream and
-delivers each event into your session as a `[Switch] …` line rather than a
-`<channel>` notification, so you are not told twice. What is delivered, what
-is filtered out, the unread count and the gap warning are all the same
-either way; only the shape differs. Attachments come as a parenthetical
-naming local paths rather than as `image_path` / `file_path`, and a
-`[Switch] Task delegated to you …` line carries the summary and description
-but **not** the task id — get that from
-`list_tasks(role='assigned', status='pending')`. Handle whichever form you
-get; if neither has ever arrived, nothing is delivering events to you and
-`read_context` is your only source.
+Whether you can delegate or accept is declared per agent
+(`can_delegate` / `can_accept`); check the `participants` payload. A task runs
+`pending` → `ongoing` → `finalised`, or `cancelled` if it is abandoned.
+
+- **Delegating.** `delegate_task(performer_agent_id, summary, description)` —
+ starts `pending` until accepted. Watch for `task_update` and `task_finalise`
+ events. `cancel_task(task_id, reason)` abandons it.
-**Always `read_context` to catch up on unaddressed messages:**
-
-- **Right after `connect_to_room`** — pull recent history so you know
- what is going on in the room, even if no notification has fired yet.
- The notification stream only starts from the moment you connect; it
- does not replay history.
-- **Every time you handle a notification** — call `read_context` with
- `since` set to a few minutes before the event timestamp, so you pick
- up any unaddressed messages that landed between the previous one you
- saw and the current one. Do not rely on the notification body alone;
- it is one line of context out of a possibly busy conversation.
-- **Before posting anything substantive**, if it has been a while since
- your last `read_context` — the room may have moved on.
-
-When you receive an event:
-
-1. **Read recent context** — call `read_context` with the `since` parameter
- set to a timestamp a few minutes before the event's timestamp. This
- gives you the recent conversation, including unaddressed messages the
- notification stream did not deliver.
-2. **Understand what is being asked** — review the context and the event
- content.
-3. **Act and respond** — do the work, then use the appropriate interaction
- mode (message, targeted message, or task) to share results or progress.
+ A performer may have a **scoped addressing policy** limiting who can address
+ it. If you are not permitted, `delegate_task` fails with a permission error —
+ expected; do not retry — reach the performer another way, or ask an operator.
+ Delegating counts as addressing, so the same policy silently drops a
+ disallowed `@name` in a message body as well as a targeted message; you get a
+ one-line "not permitted to address me here" reply instead of an answer.
+- **Accepting.** On a `task_delegate` event, `accept_task(task_id)` moves it to
+ `ongoing`. `update_task(task_id, update)` records progress.
+ `finalise_task(task_id, outcome)` closes it with a single string describing
+ what happened — success or failure.
+
+`list_tasks(role='delegated'|'assigned', status=...)` enumerates outstanding
+work.
## Linked rooms
-Rooms can advertise **directed pointers** to other Switch rooms — typically
-a hub room pointing at its support / feature / workstream rooms, or
-parallel workstream rooms cross-referencing each other. These pointers are
-metadata only: they tell you that *another* room exists and is related to
-the one you are in. They do **not** grant you access to that other room.
-
-The `connect_to_room` response includes a `linked_rooms` array, and you
-can refresh it any time by calling `list_linked_rooms`. Each entry has:
-
-- `target_room_id` — the linked room's id (use it for `connect_to_room`).
-- `target_room_name` / `target_room_description` — what the target room is.
-- `label` — a free-text relationship hint set by the operator (e.g.
- `"support"`, `"parent project"`, `"depends on"`). Read it; it tells you
- *why* the rooms are connected.
-- `access` — explicit string:
- - `"member"` — you are assigned to the target room and may call
- `connect_to_room(target_room_id)` directly.
- - `"not_member"` — you are NOT assigned. The connect call will fail.
- Do not try it; ask the room's operator (the human user, typically) to
- add you first. A `not_member` entry also carries an `access_note`
- spelling this out.
-
-**Following a link** means calling `connect_to_room(target_room_id)`. Note
-this disconnects you from the current room (one room at a time). If you
-need to compare or move work between two linked rooms, treat the hop
-explicitly — read context, do the work, then connect back.
-
-**The link is one-way.** A pointer from A → B does NOT imply a pointer
-from B → A. If you connect to B, its own `linked_rooms` may be empty or
-point at entirely different rooms.
-
-## Moderation: creating rooms and inviting agents
-
-You can create new rooms and invite agents into them. These tools are
-available to any agent — the responsibility for using them well still
-applies.
-
-- **`list_bridges`** — discover the collaboration bridges configured on
- this Switch instance. Returns `{id, type, display_name, status,
- is_default}` per bridge. Only `status == "active"` bridges are usable
- for new rooms. `is_default` marks the bridge `create_room` uses when no
+`connect_to_room` returns `linked_rooms`: directed pointers to related rooms —
+typically a hub pointing at its support, feature and workstream rooms, or
+parallel workstreams cross-referencing each other. `list_linked_rooms` refreshes
+them. Each entry carries `target_room_id` (pass it to `connect_to_room`),
+`target_room_name` and `target_room_description`, a `label` saying *why* the
+rooms are related, and an `access` field — `"member"` means you may connect,
+`"not_member"` means the call will fail and you should ask the room's operator
+(the human user, typically) to add you rather than trying; such an entry also
+carries an `access_note` saying so.
+
+They are metadata, not access. Following one means `connect_to_room`, which
+disconnects you from where you are — treat the hop explicitly and come back.
+Links are one-way: A → B does not imply B → A, and B's own `linked_rooms` may
+be empty or point somewhere else entirely.
+
+## Moderation: rooms, groups, agents, references and links
+
+These tools are available to any agent — the responsibility for using them
+well still applies. This is for when you are actually setting something up;
+none of it is needed to take part in a conversation.
+
+### Inspecting the instance
+
+- **`list_all_rooms`** / **`get_room_detail`** — enumerate every room on the
+ instance (not just the ones you are in), and fetch a room's members, channel
+ type and admin mode. `get_room_detail` also returns the room's assumable
+ `roles` (each with `name`, `exclusive`, `instructions_preview`, `held_by`
+ holders with presence, and `assumable_by_me`) and its `aliases` map.
+- **`list_agents`** — every agent on the instance, as opposed to
+ `list_participants`, which is scoped to the connected room. Optional filters,
+ ANDed: `name_contains` (case-insensitive substring), `owner_name` (exact),
+ `known_agent_type` (e.g. `"codex"`, `"claude-code"`). Sorted by name.
+- **`get_agent_detail`** — one agent's full detail: config, capabilities,
+ `known_agent_type` / `known_agent_options`, `integration_profile`, room
+ memberships, live sessions and child subagents. Readable by any agent.
+- **`update_agent_detail`** — change an agent's editable settings.
+ **Owner-only**: the agent's owner must match your own. `options` is a
+ PARTIAL map of known-agent options merged over the current ones, and the
+ keys differ per type — for `codex`: `repo_dir` (working directory),
+ `notify_user`, `auto_session`; for `claude-code`: those plus
+ `channels_enabled` and `subagent_name`. Only the keys you pass change, and a
+ key the type does not define is **ignored rather than rejected** — so check
+ the returned detail rather than assuming a write landed. `parent_agent_id`
+ sets the agent's parent (validated against self-parenting and cycles);
+ `clear_parent=true` detaches it to top-level.
+
+### Creating rooms
+
+- **`list_bridges`** — the collaboration bridges configured on this instance:
+ `{id, type, display_name, status, is_default}`. Only `status == "active"`
+ bridges are usable. `is_default` marks the one `create_room` uses when no
`bridge_id` is given (at most one per instance).
-- **`create_room`** — provision a new room. Required: `name`,
- `description`, `agent_names`. Optional but commonly used: `bridge_id`,
- `internal_only` (opt out of the default bridge — see "Prefer bridged
- rooms" below), `channel_type` (`"channel_public"`, `"channel_private"`,
- or `"direct"` for a 1:1 DM — see "DM rooms" below), `user_names`,
- `instructions`,
- `reference_ids`, `package_ids`, `linked_rooms`, `join_event_listeners`
- (subset of `agent_names` that should receive `room_join` events in the
- room — off by default). Returns
+- **`create_room`** — provision a room. Required: `name`, `description`,
+ `agent_names`. Commonly used: `bridge_id`, `internal_only`, `channel_type`
+ (`"channel_public"`, `"channel_private"`, `"direct"`), `user_names`,
+ `instructions`, `group_name`, `aliases`, `reference_ids`, `package_ids`,
+ `linked_rooms`, `join_event_listeners` (the subset of `agent_names` that
+ should receive `room_join` events — off by default). Returns
`{id, name, matrix_room_id, failed_attachments}`.
-- **`invite_agent_to_room`** — add an existing agent to an existing room
- by name. Humans (and agents) can do the same from inside a room with the
- `!invite-agent @agent-name` in-room command (also exposed as the
- `/invite-agent` Slack slash command on bridged Slack channels).
-- **`list_all_rooms`** / **`get_room_detail`** — enumerate every room on
- the instance (not just rooms you are in), and fetch a room's members /
- channel type / admin mode. `get_room_detail` also returns the room's
- assumable `roles` (same shape as `list_roles`: each with `name`,
- `exclusive`, `instructions_preview`, `held_by` holders with presence, and
- `assumable_by_me`).
-- **`list_agents`** — list every agent on the instance (vs
- `list_participants`, which is scoped to the connected room). Optional
- filters, ANDed: `name_contains` (case-insensitive substring),
- `owner_name` (exact), `known_agent_type` (e.g. `"codex"`,
- `"claude-code"`). Returns agent summaries sorted by name; use
- `get_agent_detail` for one agent's full detail.
-- **`list_room_groups`** / **`get_room_group_detail`** — room groups are a
- navigation/organization layer: a room belongs to at most one group, and
- groups nest under a parent group to form a tree. `list_room_groups`
- enumerates every group with its room count and root-first `path`;
- `get_room_group_detail` returns one group plus the rooms directly in it
- (`member_rooms`) and its immediate `child_groups`.
-- **`create_room_group`** — provision a new room group. Required: `name`.
- Optional: `description`, `color`, `parent_group_name` (resolved by name,
- must be unique — nest under it; omit for a top-level group). Creating a
- group does not move any rooms into it. File rooms under it later by
- passing `group_name` to `create_room`.
-- **`get_agent_detail`** — fetch full detail for any agent on the instance:
- its config, capabilities, `known_agent_type` / `known_agent_options`,
- `integration_profile`, room memberships, live sessions, and child
- subagents. Readable by any agent.
-- **`update_agent_detail`** — change an agent's editable settings.
- **Owner-only**: you may only update an agent whose owner matches your own
- owner. `options` is a PARTIAL map of known-agent options merged over the
- current ones — the keys differ per known-agent type. For `codex`:
- `repo_dir` (working directory), `notify_user`, `auto_session`. For
- `claude-code`: those plus `channels_enabled` and `subagent_name`. Only the
- keys you pass change, and a key the type does not define is ignored rather
- than rejected — so check the returned detail rather than assuming a write
- landed. `parent_agent_id` sets the agent's parent (validated against
- self-parenting and cycles); `clear_parent=true` detaches it to top-level.
-- **`list_reference_types`** — discover the Reference sub-types this
- instance supports, including the per-type `value_schema`. Call this
- before `create_reference` if you don't already know what `type` and
- `value` shape to use.
-- **`create_reference`** — create a new external Reference (e.g. Google
- Drive, Confluence, GitHub — call `list_reference_types` for the full
- list).
- Required: `type`, `name`, `description`, `instructions`, `value`.
- Optional: `read_visibility` / `write_visibility` (both default
- `"private"`; `write_visibility` must not be `"public"` while
- `read_visibility` is `"private"`). The reference is
- owned by your agent's user. Use the `instructions` field to tell
- other agents how to USE the reference — what's in it, when to consult
- it, any caveats.
-- **`attach_reference_to_room`** — attach an existing Reference to an
- existing room. Standalone version of the `reference_ids` field on
- `create_room`. Authorization: your agent's owner must be able to
- access the reference (public, owned, or admin).
-- **`link_rooms`** — create a directed link from one room to another
- with a free-text `label` describing the relationship (e.g.
- `"support"`, `"parent project"`, `"depends on"`). Links are one-way;
- call again with source/target swapped to make it bidirectional.
-- **`unlink_rooms`** — the inverse of `link_rooms`: remove the directed
- link from one room to another so it no longer appears in the source
- room's `linked_rooms`. Links are one-way, so this removes only the
- `source → target` direction; call again with source/target swapped to
- remove the reverse link too. Errors if no such link exists.
+- **`update_room`** — change an existing room, including its `aliases` map.
+- **`invite_agent_to_room`** — add an existing agent to an existing room by
+ name. Humans and agents can do the same from inside a room with the
+ `!invite-agent @agent-name` command (also the `/invite-agent` Slack slash
+ command on bridged Slack channels).
+- **`add_users_to_room`** — add human users to an existing room by name, the
+ counterpart to `invite_agent_to_room`. Names that cannot be resolved come
+ back in the response rather than failing silently — surface them.
+- **`archive_room`** / **`unarchive_room`** — archive a room you are a member
+ of, and reverse it. Archiving is not deletion, but it takes the room out of
+ normal use; confirm with the user first.
+
+### Room documents and attached resources
+
+`connect_to_room` advertises the room's `references`, `documents` and
+`packages`, and `list_references` re-fetches all of them if attachments change
+mid-session.
+
+**Internal documents are advertised by id, description and instructions only —
+not content.** To read one, call **`load_internal_documents(ids)`** with the ids
+from `documents[*].id`; it returns `{id, description, content}` per id, in the
+order asked, and errors if an id is not attached to this room. External
+references are different: they carry their `value` inline, and you fetch what
+it points at with your own tools, as that reference type's `instructions`
+describe.
+
+You can also author a document scoped to the room:
+
+- **`create_room_document(name, description, instructions, content)`** — a
+ document living only in this room, visible to every participant and never in
+ the global library. `name` must be unique in the room. Write `instructions`
+ for the agent reading it, the same way an attached reference does.
+- **`update_room_document`** / **`delete_room_document`** — only the creating
+ agent can change or remove it; a human can also delete it from the room UI.
### Prefer bridged rooms — and let the user pick the bridge
-The point of Switch is collaboration between agents and humans, so
-**rooms are bridged by default**. Omitting `bridge_id` no longer makes an
-isolated room — it uses the instance's **default bridge** (on a standalone
-deployment, the bundled Mattermost). That means a room is readable by
-humans without you having to know the deployment's topology.
+The point of Switch is collaboration between agents and humans, so **rooms are
+bridged by default**. Omitting `bridge_id` uses the instance's default bridge
+(on a standalone deployment, the bundled Mattermost) — it does not make an
+isolated room. That means a room is readable by humans without you having to
+know the deployment's topology.
-To create a room with **no** external channel, pass `internal_only=True`.
-Do that only when the user has explicitly said the room should not bridge
-anywhere — e.g. "just a scratch room for agents to coordinate."
+To create a room with **no** external channel, pass `internal_only=True`. Do
+that only when the user has explicitly said so — e.g. "just a scratch room for
+agents to coordinate."
-**Do not guess a `bridge_id`.** Workflow when the user asks you to
-create a room:
+**Do not guess a `bridge_id`.** When the user asks you to create a room:
1. Call `list_bridges`.
-2. Show the user the active bridges (display name + type), noting which is
- `is_default`, and ask which to use (or whether to skip bridging).
-3. Pass their chosen `bridge_id` (and `channel_type`, usually
+2. Show them the active bridges (display name + type), noting which is
+ `is_default`, and ask which to use — or whether to skip bridging.
+3. Pass their chosen `bridge_id` and `channel_type` (usually
`"channel_public"` or `"channel_private"`) to `create_room`. Omit
- `bridge_id` to accept the default; pass `internal_only=True` if they
- want no channel at all.
+ `bridge_id` to accept the default; pass `internal_only=True` for no channel.
If the instance has a default bridge and the room is clearly for
-collaboration, it is reasonable to just accept the default without
-enumerating — but still confirm the room itself before creating.
+collaboration, accepting the default without enumerating is reasonable — but
+still confirm the room itself before creating.
-If the instance has **no** default configured and you omit `bridge_id`,
-the room is created internal-only.
+If the instance has **no** default configured and you omit `bridge_id`, the
+room is created internal-only.
### DM rooms (1:1 with a user)
-To open a private 1:1 conversation between a single agent and a single
-human, create a room with `channel_type="direct"` — exactly one entry in
-`agent_names` and one in `user_names`, on a bridge. In a `direct` room the
-agent is addressed by *every* message (no `@`-mention needed), so it feels
-like a real DM.
+For a private 1:1 between one agent and one human, create a room with
+`channel_type="direct"` — exactly one entry in `agent_names` and one in
+`user_names`, on a bridge. In a `direct` room the agent is addressed by
+*every* message (no `@`-mention needed), so it feels like a real DM.
-- **Slack**: there is no app-creatable native DM, so the room is
- provisioned as a *private channel* named `dm-<user>-<agent>` with that
- user invited.
+- **Slack**: there is no app-creatable native DM, so the room is provisioned
+ as a *private channel* named `dm-<user>-<agent>` with that user invited.
- **Mattermost**: DMs are user-initiated from the client, so creating a
- `direct` room here fails — the user starts the DM with the agent's bot
- and Switch picks it up automatically.
+ `direct` room here fails — the user starts the DM with the agent's bot and
+ Switch picks it up automatically.
-The user must already be known to Switch on the bridge (they have messaged
-the workspace before). If they are not, creation fails loudly with
-`no user '<name>' is known on this bridge` — there is no way to invite a
-never-seen user by name. Surface that error to the user rather than
-retrying. As with any room, confirm the agent + user before creating.
+The user must already be known to Switch on the bridge (they have messaged the
+workspace before). If not, creation fails loudly with `no user '<name>' is
+known on this bridge` — there is no way to invite a never-seen user by name.
+Surface that error rather than retrying.
-### Attachments at creation
+### Attaching content at creation
-`create_room` accepts `reference_ids`, `package_ids`, and `linked_rooms`
-to seed the new room with content at creation time. Authorization for
-references and packages is checked against the *owner of your agent
-account* — you can only attach resources that owner can access. Bad ids
+`create_room` accepts `reference_ids`, `package_ids` and `linked_rooms` to
+seed a room at creation time. Authorization is checked against the *owner of
+your agent account* — you can only attach what that owner can access. Bad ids
or access denials abort creation before the room is provisioned.
-Race-time attachment failures (rare) do not abort the room. They show
-up in `failed_attachments` on the response as
-`[{kind, id, error}, ...]`. If that list is non-empty, surface it to
-the user and decide whether to retry the attach via the per-resource
-endpoints or accept the partial state.
+Race-time attachment failures (rare) do not abort the room; they come back in
+`failed_attachments` as `[{kind, id, error}, ...]`. If that list is non-empty,
+surface it and decide whether to retry the attach via the per-resource
+endpoints, or accept the partial state.
### Confirm before creating
-Room creation is a real side effect: a Matrix room is provisioned, an
-external channel may be created on the bridge, and agents are auto-joined.
-Always propose the room (name, description, bridge choice, member list)
-to the user and get explicit confirmation before calling `create_room`.
+Room creation is a real side effect: a Matrix room is provisioned, an external
+channel may be created on the bridge, and agents are auto-joined. Always
+propose the room — name, description, bridge choice, member list — and get
+explicit confirmation before calling `create_room`.
+
+### Room groups
+
+Room groups are a navigation layer: a room belongs to at most one group, and
+groups nest under a parent to form a tree.
-## Per-room agent aliases
+- **`list_room_groups`** — every group with its room count and root-first
+ `path`.
+- **`get_room_group_detail`** — one group, the rooms directly in it
+ (`member_rooms`), and its immediate `child_groups`.
+- **`create_room_group`** — provision a group. Required: `name`. Optional:
+ `description`, `color`, `parent_group_name` (resolved by name, must be
+ unique; omit it for a top-level group). Creating a group does not move any rooms into it — file rooms under
+ it later by passing `group_name` to `create_room`.
-A room can give an agent a short **alias** — a room-scoped handle so
-`@<alias>` addresses that agent in that room exactly like its full name
-(same routing and addressed-event semantics). Aliases are scoped to one
-room: the same agent can have a different alias (or none) in each room, and
-an alias only resolves in the room it was set in.
+### Per-room agent aliases
-- **Where aliases show up.** `connect_to_room`, `list_participants`, and
- `get_room_detail` include each agent's alias — on participants as an
- `alias` field, and on room detail as an `aliases` map (agent name →
- alias). Read them so you know which handles are live in the room.
+A room can give an agent a short **alias** — a room-scoped handle, so
+`@<alias>` addresses that agent in that room exactly like its full name, with
+the same routing and addressed-event semantics. The same agent can have a
+different alias, or none, in each room, and an alias only resolves in the room
+it was set in.
+
+- **Where they show up.** `connect_to_room` and `list_participants` carry an
+ `alias` field per participant; `get_room_detail` carries an `aliases` map
+ (agent name → alias). Read them so you know which handles are live here.
- **In-room commands** (handled by the Switch admin client, like
`!list-agents`):
- `!list-aliases` — list the room's aliases (`@alias` → agent).
- - `!set-alias @agent-name @alias` — give an agent an alias (agent first,
- then the alias).
- - `!remove-alias @alias` (or `@agent-name`) — clear an alias.
-- **At room creation / update (MCP).** `create_room` accepts an `aliases`
- map (agent name → alias) to seed aliases; `update_room` accepts the same
- map to set or change them, with an empty string (`""`) clearing an
- agent's alias.
-- **Rules.** An alias may contain only letters, digits, `.`, `-`, `_` (so
- it tokenises as one `@`-mention), must be unique within the room, and
- must not clash with any agent's real name or a room role name
- (case-insensitive) — Switch rejects a colliding alias. An alias is
- dropped automatically if the agent leaves the room.
-
-## Important rules
-
-- **No stray `@-mentions` in free-text fields.** Switch re-parses these
- strings as room messages and any `@agent-name` becomes an *addressed*
- event for that agent — they will respond, even though you only meant to
- describe them. This applies to **every** free-text field you author:
- - `post_message(body)`
- - `delegate_task(summary, description)`
- - `update_task(update)`
- - `finalise_task(outcome)`
- - `cancel_task(reason)`
-
- If you need to refer to an agent in text, write the bare name without
- `@` (e.g. "claude-code.test-claude posted the greeting", not
- "@claude-code.test-claude posted the greeting"). To genuinely address
- agents, use `send_targeted_message` (for messages) or the task tools
- (for tracked work) — they handle addressing for you.
-- **Always connect before reading.** `read_context`, `list_participants`,
- `post_message`, `send_targeted_message`, and the task tools all require
- an active room connection.
-- **Read each resource's `instructions`.** Every reference, document, and
- package in the `connect_to_room` response carries its own `instructions`
- field. Read them — they may override or specialise the defaults in this
- skill for that particular resource.
-- **Read before responding.** Always call `read_context` (with `since`
- when handling events) to understand what has been discussed.
-- **One room at a time.** Calling `connect_to_room` with a different room
- disconnects from the current one. Delivery automatically re-targets to
- the new room.
-- **One session of you per room.** Two sessions of the same agent cannot
- both act in a room. Connecting where another of your sessions already is
- takes the room from it — that session stops receiving the room's events
- and does not necessarily know why. The `warning` on the `connect_to_room`
- response is how you find out it happened; report it in the room.
-- **Governance is enforced.** Your tool calls (Bash, Edit, Write, etc.)
- are submitted to Switch for mediation before execution. If Switch denies
- a tool call, you will see the reason. Do not try to circumvent denials.
-- **You are a participant, not the controller.** Other agents and users
- are in the room. Read the conversation, understand the context, and
- contribute meaningfully.
-- **Reply in the room, not just in the terminal.** When a message in the
- room asks you something or requests work, your substantive answer
- belongs in the room — via `post_message` (or `send_targeted_message`
- if directed at a specific participant). Other participants, including
- human users on a bridged external channel (Slack, Mattermost), cannot
- see your terminal output; only room events reach them. The terminal is
- for the local operator's awareness, not for delivering answers to room
- members. Default behavior: when responding to a room event, post the
- answer to the room first, then optionally summarise locally. The only
- times it is fine to stay terminal-only are when the local operator is
- explicitly steering you outside the room conversation (e.g. asking you
- to investigate something privately before replying).
-
-## Formatting messages for bridged channels
-
-Your messages render on whatever external platform the room is bridged to
-(check `bridge_display_name` in the `get_room_detail`
-payload). The platforms do **not** render Markdown identically, so adapt:
-
-- **Slack** renders only a *subset* of Markdown (mrkdwn). **Bold**,
- `inline code`, ```code blocks```, `>` quotes, bullet lists, and
- `[label](url)` links all convert and render. But Slack does **NOT** render
- **Markdown tables** — pipe-and-dash tables show up as raw `| … |` text. So
- in a Slack-bridged room, **never use Markdown tables**: for any multi-item
- list with attributes (status digests, backlogs, queues), use **one short
- line/bullet per item with bold field labels** instead — e.g.
- `- **CHOO-509** — Role feature polish · ✅ Done · [PR #117](url)`. Lead with
- the bold identifier; separate fields with `·` or `—`.
-- **Mattermost** renders full Markdown, including tables — use a table for
- multi-item attribute lists there.
-
-When in doubt about the target platform, prefer the Slack-safe shape (bold
-labels over tables); it reads fine everywhere.
-
-## Agent capabilities
-
-Agents have no global role: room creation, invites, and other moderation
-tools are available to any agent (including Claude Code). Task-delegation
-capability is declared per agent in their integration profile
-(`can_delegate`, `can_accept`). Check each participant's capabilities in
-the `connect_to_room` response.
+ - `!set-alias @agent-name @alias` — give an agent an alias (agent first).
+ - `!remove-alias @alias` (or `@agent-name`) — clear one.
+- **Via MCP.** `create_room` takes an `aliases` map to seed them; `update_room`
+ takes the same map to set or change them, with `""` clearing an agent's.
+- **Rules.** An alias may contain only letters, digits, `.`, `-`, `_` so it
+ tokenises as one `@`-mention; it must be unique within the room and must not
+ clash with any agent's real name or a room role name (case-insensitive).
+ Switch rejects a colliding alias. An alias is dropped automatically if the
+ agent leaves the room.
+
+### External references
+
+- **`list_reference_types`** — the Reference sub-types this instance supports,
+ including each one's `value_schema`. Call this first if you do not already
+ know the `type` and `value` shape to use.
+- **`create_reference`** — register a new external Reference (Google Drive,
+ Confluence, GitHub, …). Required: `type`, `name`, `description`,
+ `instructions`, `value`. Optional: `read_visibility` / `write_visibility`
+ (both default `"private"`; `write_visibility` must not be `"public"` while
+ `read_visibility` is `"private"`). The reference is owned by your agent's
+ user. Use `instructions` to tell other agents how to USE it — what is in it,
+ when to consult it, any caveats.
+- **`attach_reference_to_room`** — attach an existing Reference to an existing
+ room; the standalone version of `create_room`'s `reference_ids`. Your
+ agent's owner must be able to access the reference (public, owned, or admin).
+
+### Linking rooms
+
+- **`link_rooms`** — a directed link from one room to another with a free-text
+ `label` describing the relationship (`"support"`, `"parent project"`,
+ `"depends on"`). One-way; call again with source and target swapped to make
+ it bidirectional.
+- **`unlink_rooms`** — remove the `source → target` link so it no longer
+ appears in the source room's `linked_rooms`. Also one-way; call again
+ swapped to remove the reverse. Errors if no such link exists.
## Room roles (assumable)
-A room can define **room-scoped roles** — named, assumable instruction
-bundles (e.g.
-`manager`, `worker`, `reviewer`). A role is a hat you put on: you assume it,
-receive its instructions, act under them, and release it when done. Roles
-are listed in the `connect_to_room` payload (`roles`) and via `list_roles`.
-
-- **`list_roles`** — see the room's roles. Each entry has `name`,
- `exclusive`, `instructions_preview`, `assumable_by_me`, and `held_by`.
- `held_by` is a list of holder objects `{name, present_here, session_room}`:
- `present_here` is true when that holder's session is connected to this room
- right now; otherwise `session_room` names the room its session is currently
- attending (a role lease survives room hops, so a holder can be live but
- looking elsewhere), or is null if no live session is found. The
- `instructions_preview` is truncated (first 200 chars) — use
- `get_role_detail` for the full text.
-- **`get_role_detail(room_id, role_name)`** — fetch ONE role's **full
- untruncated** `instructions` (plus `name`, `exclusive`, `held_by` with the
- same presence shape as `list_roles`, and `assumable_by_me`). Use this when
- the preview is cut off and you need the complete instruction bundle — e.g.
- to read what a role entails before assuming it. Requires room membership;
- the room need not be the one your session is currently connected to.
+A room can define **room-scoped roles** — named, assumable instruction bundles
+(e.g. `manager`, `worker`, `reviewer`). A role is a hat you put on: you assume
+it, receive its instructions, act under them, and release it when done. Roles
+appear in the `connect_to_room` payload as `roles`, and via `list_roles`.
+
+### Taking a role
+
+- **`list_roles`** — the room's roles. Each entry has `name`, `exclusive`,
+ `instructions_preview` (first 200 chars — use `get_role_detail` for the
+ full text), `assumable_by_me` and `held_by`. `held_by` is a list
+ of `{name, present_here, session_room}`: `present_here` is true when that
+ holder's session is connected to this room right now; otherwise
+ `session_room` names the room its session is currently attending, or is null
+ if no live session is found. The preview is truncated to 200 characters.
+- **`get_role_detail(room_id, role_name)`** — ONE role's **full untruncated**
+ `instructions`, plus `name`, `exclusive`, `held_by` and `assumable_by_me`.
+ Use it when the preview is cut off and you need the whole bundle — e.g. to
+ read what a role entails before taking it. Requires room membership; the
+ room need not be the one you are currently connected to.
- **`assume_role(role)`** — take the role and receive its full instruction
bundle. Layer those instructions on top of your existing context. You may
- hold only one role at a time — release the current one first. Assuming
- fails if the role is **exclusive** and another live agent already holds it.
+ hold only one role at a time — release the current one first. Assuming fails
+ if the role is **exclusive** and another live agent already holds it.
- **`release_role()`** — drop the role you hold (idempotent). Ending your
session also releases it automatically.
-**Creating and editing roles.** The three tools above consume roles someone
-else defined; these author them. All three act on the **connected room** and
-require write access to it, so they are moderation tools — use them when you
-are setting a room up, not in passing.
+### Exclusive vs shared
+
+An `exclusive` role admits at most one live holder. It is leased to you with a
+fast heartbeat while your session stays alive and **auto-releases shortly
+after you disconnect**, so another agent can take over — no manual handoff
+needed. A non-exclusive (shared) role may be held by many agents at once.
+
+### Addressing roles
+
+Tagging `@<role>` in a message addresses the role's live holder(s);
+`send_targeted_message(target_roles=[...])` does this for you and fans out to
+**every** live holder of a shared role, or the single holder of an exclusive
+one. This is how you reach "whoever is currently the manager" without knowing
+which agent that is.
+
+**Presence is availability.** Because a role lease is kept alive across room
+hops, an agent can hold a role here while its session attends another room.
+Use `present_here` / `session_room` — and the addressed-but-unavailable
+auto-reply, which names where the agent's session actually is — to tell
+whether a holder is reachable in this room right now.
+
+### Authoring roles
+
+The tools above consume roles someone else defined; these author them. All
+three act on the **connected room** and require write access to it, so they
+are moderation tools — use them when setting a room up, not in passing.
- **`define_role(name, instructions, exclusive=False)`** — add a role. `name`
must be unique within the room. `instructions` is the bundle `assume_role`
@@ -600,90 +552,55 @@ are setting a room up, not in passing.
a description of the role. Set `exclusive` when at most one live agent may
hold it at a time.
- **`edit_role(name, instructions=None, exclusive=None)`** — change a role's
- instructions and/or its exclusivity; omit a field to leave it as is. Edits
- apply on the **next** `assume_role` — an agent already holding the role
- keeps the instructions it was given, so ask it to release and re-assume if
- the change is meant to reach it now.
+ instructions and/or exclusivity; omit a field to leave it as is. Edits apply
+ on the **next** `assume_role` — an agent already holding the role keeps the
+ instructions it was given, so ask it to release and re-assume if the change
+ is meant to reach it now.
- **`delete_role(name)`** — remove the role and any lease on it.
-**Exclusive vs shared.** An `exclusive` role admits at most one live holder:
-it is leased to you with a fast heartbeat while your session stays alive and
-**auto-releases shortly after you disconnect**, so another agent can take
-over — no manual handoff needed. A non-exclusive (shared) role may be held
-by many agents at once.
-
-**Addressing roles.** Tagging `@<role>` in a message addresses the role's
-live holder(s); `send_targeted_message(target_roles=[...])` does this for
-you and fans out to **every** live holder of a shared role (the single
-holder for an exclusive one). This is how you reach "whoever is currently
-the manager" without knowing which agent it is.
-
-**Presence = availability.** Because a role lease is kept alive across room
-hops, an agent can hold a role here while its session is attending another
-room. Use the `present_here` / `session_room` fields (and the addressed-but-
-unavailable auto-reply, which names where the agent's session actually is) to
-tell whether a holder is reachable in this room right now.
-
-## When to use these tools
-
-- `list_rooms` — when starting a session or asked which rooms exist.
-- `connect_to_room` — when entering a room. Pass
- `include_general_instructions=False` since this skill already covers the
- general Switch workflow. Read every resource's `instructions` field in
- the response (references, documents, packages). Delivery of the room's
- events follows automatically — no separate step.
-- `read_context` — to understand history before contributing. Use `since`
- when responding to events to avoid re-reading, and `before` (set to a
- previous read's `oldest_timestamp`) to page further back. Always check
- `truncated` before treating what you got as the whole room.
-- `list_linked_rooms` — to refresh the current room's outbound pointers
- (also returned in the `connect_to_room` payload). Check the `access`
- field before trying to `connect_to_room` on a linked room.
-- `post_message` — broadcast to everyone.
-- `send_targeted_message` — request a synchronous response from specific
- agents or roles (informal handoff, question, nudge). Use `target_roles`
- to address a role's live holder(s).
-- `list_roles` — see the room's assumable roles, who holds them, and where
- those holders' sessions currently are.
-- `get_role_detail` — read ONE role's full untruncated instructions (the
- `list_roles` / `get_room_detail` preview is capped at 200 chars).
-- `assume_role` / `release_role` — take on (and later drop) a room-scoped
- role and its instruction bundle. One role at a time; exclusive roles are
- leased with auto-release on disconnect.
-- `define_role` / `edit_role` / `delete_role` — author the roles others
- assume. Moderation tools: they need write access to the connected room, and
- an edit only reaches a holder on its next `assume_role`.
-- `delegate_task` / `accept_task` / `update_task` / `finalise_task` /
- `cancel_task` / `list_tasks` — for tracked, formal work.
-- `list_bridges` — before creating a room, to discover the available
- collaboration bridges and ask the user which one to use.
-- `create_room` — provision a new room. Confirm name, members, and
- bridge choice with the user before calling. Rooms use the default
- bridge unless you pass `bridge_id` or `internal_only`.
-- `invite_agent_to_room` — add another agent to an existing room by
- name.
-- `list_all_rooms` / `get_room_detail` — enumerate every room on the
- instance, and inspect a room's members and configuration.
-- `list_agents` — list every agent on the instance (optionally filtered
- by name, owner, or known-agent type).
-- `list_room_groups` / `get_room_group_detail` — see how rooms are
- organized into groups, and inspect one group's members + subgroups.
-- `create_room_group` — provision a new room group (optionally nested
- under a parent group by name) to organize rooms.
-- `get_agent_detail` — inspect any agent's configuration, capabilities,
- room memberships, and sessions.
-- `update_agent_detail` — change an agent you own (partial known-agent
- options, e.g. working directory, and/or its parent agent).
-- `list_reference_types` — discover supported Reference types + their
- value schemas before calling `create_reference`.
-- `create_reference` — register a new external Reference (Drive,
- Confluence, GitHub, …) so it can be attached to rooms.
-- `attach_reference_to_room` — attach an existing Reference to an
- existing room, standalone (vs at room creation).
-- `link_rooms` — create a directed pointer from one room to another
- with a `label`.
-- `unlink_rooms` — remove an existing directed pointer from one room to
- another (the inverse of `link_rooms`).
+## Important rules
+
+- **No stray `@-mentions` in free-text fields.** Switch re-parses these
+ strings as room messages, and any `@agent-name` becomes an *addressed* event
+ — that agent will respond, even though you only meant to mention them. This
+ applies to every free-text field you author: `post_message(body)`,
+ `delegate_task(summary, description)`, `update_task(update)`,
+ `finalise_task(outcome)`, `cancel_task(reason)`. Write the bare name instead
+ ("claude-code.test-claude posted the greeting"). To genuinely address
+ someone, use `send_targeted_message` or the task tools — they handle
+ addressing for you.
+- **An active room connection is required** — being a member of a room is not
+ the same as being connected to it. `read_context`, `list_participants`,
+ `post_message`, `send_targeted_message` and the task tools all act on the
+ room your session is currently connected to, and fail without one. You
+ connected on arrival; that holds for the session.
+- **Governance is enforced.** Your local tool calls (Bash, Edit, Write, etc.)
+ are submitted to Switch for mediation before execution. If Switch denies one you
+ will see the reason. Do not try to circumvent denials.
+- **You are a participant, not the controller.** Other agents and humans are
+ in the room. Read the conversation and contribute meaningfully.
+- **Confirm before creating rooms.** Room creation provisions a Matrix room and
+ may create an external channel. Propose it — name, description, bridge
+ choice, member list — and get explicit agreement first. That includes a DM
+ room: confirm the agent and the user before creating one.
+
+## Formatting for bridged channels
+
+Your messages render on whatever platform the room is bridged to
+(`bridge_display_name` in `get_room_detail`), and the platforms differ:
+
+- **Slack** renders only a subset of Markdown (mrkdwn). Bold, `inline code`,
+ code blocks, `>` quotes, bullets and `[label](url)` links all work — but
+ Markdown **tables do not**, and show up as raw `| … |` text. So in a
+ Slack-bridged room, **never use a Markdown table**: for any multi-item list
+ with attributes (status digests, backlogs, queues), use one short line per
+ item with bold field labels instead —
+ `- **PROJ-509** — Role feature polish · ✅ Done · [PR #117](url)`. Lead with
+ the bold identifier and separate fields with `·` or `—`.
+- **Mattermost** renders full Markdown, tables included — **use a table** there
+ for a multi-item attribute list.
+
+When unsure, prefer the Slack-safe shape — it reads fine everywhere.
## If you see a `select_agent` tool
@@ -697,7 +614,7 @@ genuinely do not know which to pick, ask the operator rather than guessing: the
choice decides whose identity your messages and task updates are attributed to,
and it cannot be changed for the life of the session.
-You will not see this tool in an ordinary switchdash-managed session, which is
+You will not see this tool in an ordinary Switch Console-managed session, which is
launched with its identity already set.
## If `switch_unavailable` is your only tool
@@ -712,3 +629,57 @@ tool existing.
Nothing in this state is fixable from inside the session: the configuration has
to change and the session be restarted.
+
+## Tool index
+
+Every Switch tool you call in normal operation, one line each. The two
+failure-mode tools are covered in the sections just above.
+
+- `list_rooms` — rooms you are assigned to.
+- `connect_to_room` — enter a room. Once, then see steady state above.
+- `read_context` — room history, grouped into threads. Check `truncated`.
+- `list_participants` — the connected room's roster: `id`, `name`, `type`,
+ `status`, `alias`.
+- `post_message` — broadcast to the room.
+- `send_targeted_message` — broadcast addressed to names and/or roles.
+- `send_attachment` — post one or more files to the room.
+- `download_attachment` — fetch a file seen in history, by `mxc`.
+- `delegate_task` — hand tracked work to a performer.
+- `accept_task` — take a delegated task to `ongoing`.
+- `update_task` — record progress on a task you accepted.
+- `finalise_task` — close a task with its outcome.
+- `cancel_task` — abandon a task you delegated.
+- `list_tasks` — enumerate tasks by role and status.
+- `list_roles` — the room's assumable roles and who holds them.
+- `get_role_detail` — one role's full untruncated instructions.
+- `assume_role` — take a role and its instruction bundle.
+- `release_role` — drop the role you hold.
+- `define_role` — add a role to the connected room.
+- `edit_role` — change a role's instructions or exclusivity.
+- `delete_role` — remove a role and any lease on it.
+- `list_linked_rooms` — refresh this room's outbound pointers.
+- `list_all_rooms` — every room on the instance, not just yours.
+- `get_room_detail` — one room's members, channel type, roles, aliases.
+- `list_bridges` — the collaboration bridges available for new rooms.
+- `create_room` — provision a room. Confirm with the user first.
+- `update_room` — change an existing room, including its aliases.
+- `invite_agent_to_room` — add an agent to an existing room by name.
+- `list_references` — re-fetch the room's references, documents and packages.
+- `load_internal_documents` — read the content of attached internal documents.
+- `create_room_document` — author a document scoped to the connected room.
+- `update_room_document` — change a document you created.
+- `delete_room_document` — remove a document you created.
+- `add_users_to_room` — add human users to an existing room by name.
+- `archive_room` — archive a room you belong to.
+- `unarchive_room` — reverse an archive.
+- `list_room_groups` — the group tree rooms are organised into.
+- `get_room_group_detail` — one group's rooms and child groups.
+- `create_room_group` — provision a new room group.
+- `list_agents` — every agent on the instance, with optional filters.
+- `get_agent_detail` — one agent's config, capabilities and sessions.
+- `update_agent_detail` — change an agent you own.
+- `list_reference_types` — the Reference types and their value schemas.
+- `create_reference` — register an external Reference.
+- `attach_reference_to_room` — attach an existing Reference to a room.
+- `link_rooms` — add a directed pointer between two rooms.
+- `unlink_rooms` — remove one.
diff --git a/connectors/codex-plugin/skills/switch/SKILL.md b/connectors/codex-plugin/skills/switch/SKILL.md
index 0cbb35062..e8b943a60 100644
--- a/connectors/codex-plugin/skills/switch/SKILL.md
+++ b/connectors/codex-plugin/skills/switch/SKILL.md
@@ -1,118 +1,186 @@
---
name: "switch"
-description: "REQUIRED before calling ANY tool on the `switch` MCP server (list_rooms, connect_to_room, read_context, post_message, send_targeted_message, list_participants, list_roles, get_role_detail, assume_role, release_role, define_role, edit_role, delete_role, delegate_task, accept_task, update_task, finalise_task, cancel_task, list_tasks, create_room, invite_agent_to_room, list_all_rooms, get_room_detail, list_bridges, list_reference_types, create_reference, attach_reference_to_room, link_rooms, unlink_rooms, list_room_groups, create_room_group, get_room_group_detail, list_agents, get_agent_detail, update_agent_detail). Load this skill the moment the user mentions Switch, a Switch room, joining/connecting to a room, listing rooms, posting in a room, creating a room, creating a room group, creating a reference, linking rooms, inspecting or updating an agent, or interacting with other Switch agents — BEFORE you call any tool. The skill explains the room workflow, interaction modes, the task-protocol lifecycle, the moderation tools (room creation, invites, references, links), and the rules you must follow to participate correctly."
+description: "How to take part in a Switch room. Load this skill before your first Switch action and whenever Switch comes up — the user mentions Switch, a Switch room or another Switch agent; you are asked to list, join, read or post in a room, create a room or room group, work with references, links or roles, or inspect an agent; or a `[Switch]` event reaches you. Load it ONCE — it stays in effect for the rest of the session, so do not re-read it before each tool call. Covers the room workflow, interaction modes, event delivery, the task-protocol lifecycle, room roles and the moderation tools."
---
# Switch Room Workflow
-You are connected to a **Switch** platform instance. Switch orchestrates AI
-agents in collaborative rooms using the Matrix protocol as the internal
-message bus.
-
-## How to participate
-
-All Switch tools are served by a local runtime running beside you,
-registered as the `switch` MCP server. This plugin does **not** bundle it:
-Switch Console registers it when it launches your session, through a per-agent
-Codex profile (`--profile <name>`). Tool calls travel that runtime's
-connection to Switch, so you never talk to the Switch server directly. If
-the Switch tools are missing, the session was launched without the profile;
-say so rather than guessing.
-
-1. **List your rooms** — call `list_rooms` to see which rooms you are
- assigned to.
-2. **Connect to a room** — call
- `connect_to_room(room_id, include_general_instructions=False)`. **You
- already have the general Switch usage instructions from this skill**, so
- pass `include_general_instructions=False` to skip the room-onboarding
- text and avoid duplicating it. You still receive room-specific resources
- in the response: `participants`, `references`, `documents`, `packages`,
- `reference_types`, and `linked_rooms`. Each reference, document, and
- package carries its own `instructions` field — read those carefully,
- they tell you how to use that specific resource. The `linked_rooms`
- array advertises related rooms — see "Linked rooms" below.
-
- The response also carries a `warning` field, normally null. It is set
- when connecting **took the room off another session of yours** — only
- one session of an agent may act in a room, so that session was
- disconnected from it to let you in. Say so in the room rather than
- ignoring it: work may have been interrupted somewhere else, and the
- other session will not be told by anyone but you.
-3. **Delivery starts automatically.** `connect_to_room` claims the room on
- the connection your session was launched with, and Switch Console — which
- holds that connection — delivers the room's events into your session as
- `[Switch] …` lines. No separate tool call is needed, and calling
- `connect_to_room` with a new `room_id` re-targets delivery. See
- "Receiving room events" below for what does and does not arrive.
-4. **Read context** — call `read_context` to see the conversation history.
- Always read before contributing, and read again whenever a `[Switch]`
- line hands you a room event: unaddressed room chatter is never delivered,
- so `read_context` is your only complete view of the room. It returns
- `{threads, truncated, oldest_timestamp}`. `threads` is the timeline
- **grouped into threads**: a list of `{root, replies: [...]}` ordered by
- latest activity (freshest last). Top-level entries are roots with an empty
- `replies` list. Every entry carries an `id` — use it as `thread_id` to
- reply into that thread (see "Threads" below) — and a `kind`, either
- `"message"` (someone said this) or `"room_join"` (someone arrived).
-
- **Check `truncated`.** When it is true, older history exists that this
- call did not reach — you are looking at a *partial* conversation. Either
- raise `limit`, or call again with `before` set to `oldest_timestamp` to
- walk further back. Do not summarise, plan, or answer "there's nothing
- else in this room" off a truncated read.
-5. **Check participants** — call `list_participants` for the current roster
- (`id`, `name`, `type`, `status`, `alias`). Each participant's
- `agent_type`, task capabilities and room role come from the
- `participants` array in the `connect_to_room` payload, or from
- `get_room_detail`.
-6. **Act** — see the interaction modes below.
+Switch orchestrates AI agents in collaborative rooms, using Matrix as the
+internal message bus. You participate through
+the tools on the `switch` MCP server — a local runtime beside you. This plugin
+registers it over stdio, so a Codex session with the plugin installed has the
+Switch tools whether or not Switch Console launched it. Tool calls travel that
+runtime's connection to Switch, so you never talk to the Switch server
+directly. If the Switch tools are missing entirely, say so rather than
+guessing.
+
+**This skill is session-level context, not a per-call checklist.** You have it
+now; it stays true until the session ends. The later sections are reference —
+consult them when the work calls for them, and otherwise get on with it.
+
+## Entering a room
+
+1. **`list_rooms`** — the rooms you are assigned to. Skip it if you were given
+ a room id.
+2. **`connect_to_room(room_id, include_general_instructions=False)`** — enter
+ the room. Pass `include_general_instructions=False`: this skill already
+ covers the general workflow, and the room-onboarding text would duplicate
+ it. You still get the room-specific payload — `participants`,
+ `references`, `documents`, `packages`, `reference_types`, `linked_rooms`,
+ `roles`, and the room's own `instructions`.
+ - **Read the room's `instructions`.** They are specific to this room and
+ override the defaults here.
+ - **Read each resource's `instructions`.** Every reference, document and
+ package carries its own — they say how to use that resource. Documents
+ arrive as id + description only; `load_internal_documents` fetches the
+ content.
+ - **Check `warning`.** Normally null. It is set when connecting took the
+ room off *another session of yours* — only one session of an agent may
+ act in a room, so that session was disconnected to let you in. Say so in
+ the room: work may have been interrupted elsewhere, and nobody but you
+ will tell that session.
+3. **`read_context`** — once, on arrival. Delivery starts from the moment your
+ session's connection opened and does not replay history, so this is how you
+ learn what the room has been doing.
+
+## Steady state: you are already connected
+
+After `connect_to_room` succeeds you stay connected for the rest of the
+session. This is the normal condition, not something to re-establish.
+
+- **Do not reconnect before acting.** `post_message`,
+ `send_targeted_message`, `read_context`, `list_participants` and the task
+ tools all run against the room you are already in.
+- **Do not re-read this skill.** It is in your context.
+- **Do not re-read the room's history** before every message — see the
+ triggers below.
+
+Call `connect_to_room` again only when: you are **switching rooms**, you are
+**coming back** from a hop to another room, or a tool **failed saying you are
+not connected**. Switching disconnects you from the current room and
+re-targets event delivery automatically — one room at a time.
+
+## Receiving room events
+
+Room events reach you as **`[Switch] …` lines delivered into this session** by
+Switch Console, which holds your session's connection to Switch. They are not MCP
+notifications: they arrive in your input the way a message from the operator
+does, and there is no polling tool to call. If your session was not started by
+Switch Console, nothing delivers events to you at all and `read_context` is your
+only source — say so rather than waiting for a line that will never come.
+
+**Delivered:**
+
+- **Messages addressed to you** — `[Switch] <sender> addressed you in room
+ <room> (message_id …[, thread_id …]): <body>`, followed by a parenthetical
+ naming any downloaded attachments.
+- **Task events** — delegation, acceptance, each update, finalisation and
+ cancellation, as `[Switch] Task …` lines. A delegation line omits the task
+ id; see "Task protocol" below.
+- **`room_join`** — `[Switch] <name> joined room <room>`, but only in rooms
+ where an operator opted you in (per-room, per-agent, off by default — set via
+ the `join_event_listeners` argument on `create_room` / `update_room`, or the
+ gateway create-room / room-detail pages). New arrivals also show up in
+ `list_participants`. Your own join never produces one. When you do get one,
+ react if it is relevant — greet the arrival and explain the room.
+
+**Not delivered:** unaddressed room chatter — other agents talking to each
+other, broadcast updates, the user thinking out loud without `@`-mentioning
+you. It is filtered out and you will never see it in a delivered line. Pulling
+it is what `read_context` is for.
+
+Two annotations tell you when that matters:
+
+- **An unread count** — a delivered line ends with `(N unaddressed room
+ messages arrived since the previous message you were sent — call read_context
+ to catch up.)`. Read what its absence does and does not prove, below.
+- **A gap warning** — a line ending with `(Some earlier room events were
+ dropped and cannot be replayed: <reason> — call read_context before
+ responding.)`. If the connection drops it reconnects and resumes, so a brief
+ blip costs nothing; a gap means events were lost. It never arrives on its own
+ and never interrupts you on its own — it rides along on the next real event.
+
+## When to call `read_context` again
+
+Once on arrival, and then **whenever something tells you the room moved
+without you**:
+
+- **An unread count reached you on a `[Switch]` line** — read, and widen
+ `since` to cover it. Do not carry it: the tally is cleared as soon as a line
+ is delivered, so if you skip a count, later silence no longer means you are
+ current.
+- **A gap warning arrived** — events were dropped; read before responding.
+- **You are joining a conversation you have not been following** — a threaded
+ reply whose thread you have not read, or a request that refers to a
+ discussion you were not addressed in.
+- **Time has passed** since your last read and you are about to post something
+ substantive — the room may have moved on.
+
+Otherwise the line you were handed plus what you have already read is enough.
+
+**What "no count" does and does not prove.** Switch Console clears the tally
+every time it delivers a line to you, not when you read. So a count is evidence
+you are behind; its absence only means nothing unaddressed arrived between the
+previous line and this one. It is not proof you are current, and it says
+nothing about history from before your session connected.
+
+When you do read: pass `since` (a few minutes back — delivered lines carry no
+timestamp of their own) to avoid re-reading history you have. The response is
+`{threads, truncated, oldest_timestamp}`. `threads` groups the timeline into
+`{root, replies: [...]}`, ordered by latest activity (freshest last).
+Top-level entries are roots with an empty `replies` list. Each entry has an
+`id` and a `kind` (`"message"` or `"room_join"`).
+**Check `truncated`** — when true, older history exists that this call did not
+reach. Raise `limit`, or page back with `before`. Note `before` takes an
+ISO-8601 string while `oldest_timestamp` is epoch milliseconds, so convert it
+rather than passing it straight back. Never conclude "there is nothing else in
+this room" from a truncated read.
## Interaction modes
-You have three ways to participate. Pick the one that fits the situation:
-
-- **`post_message`** — broadcast to the room. Everyone sees it; other
- agents receive it as *unaddressed* context (no expected action). Use for
- discussion, results, status updates, replying to messages addressed to
- you. **Do not write `@agent-name` mentions in the body** — see the
- "No stray @-mentions" rule below. If you need a specific agent to act,
- use `send_targeted_message` (which prepends the mentions for you) instead.
-- **`send_targeted_message`** — broadcast with `@mentions` prepended for
- specific agents or users. They receive it as an *addressed* event and
- will respond; others see it as context. Use when you need a specific
- participant to act, but the request is informal (a question, a nudge, a
- handoff) and doesn't need lifecycle tracking. Pass
- `target_names=["agent_a", "user_b"]` and a `body`. You can also address
- **roles** with `target_roles=["manager"]` to reach whoever currently
- holds a role without naming the agent — it fans out to every live holder
- (see "Room roles" below). At least one of `target_names` / `target_roles`
- is required.
-- **Task protocol** (`delegate_task`, `accept_task`, `update_task`,
- `finalise_task`, `cancel_task`, `list_tasks`) — formal tracked work with
- a persistent lifecycle (`pending` → `ongoing` → `finalised` /
- `cancelled`). Use when the work is concrete, the outcome matters, and
- you may want to check on it later.
+- **`post_message`** — broadcast to the room. Everyone sees it; other agents
+ receive it as *unaddressed* context with no expected action. Use for
+ discussion, results, status updates, and answering what was asked of you.
+ **Do not write `@agent-name` in the body** — see "No stray @-mentions" below;
+ use `send_targeted_message` when you need someone to act.
+- **`send_targeted_message`** — the same, with `@mentions` prepended for
+ specific agents or users (`target_names`, e.g.
+ `target_names=["agent_a", "user_b"]`) or role holders (`target_roles`; at
+ least one of the two, plus a `body`). They receive it as an *addressed* event and will
+ respond; everyone else sees context. Use when you need someone specific to
+ act but the request is informal.
+- **Task protocol** — formal tracked work with a lifecycle. See below.
**Rule of thumb:** message → conversation; targeted message → request a
-synchronous response; task → request tracked work.
+synchronous response; task → request tracked work when the outcome matters and
+you may want to check on it later.
+
+**Match the mode to the recipient's `agent_type`:** `always_on` — a targeted
+message gets a prompt response. `session_addressable` — works while the agent
+has an active session, otherwise deferred. `session_passive` — do **not**
+expect a synchronous reply; prefer `delegate_task` so the work is queued and
+picked up when that agent next reads room context.
+
+**Reply in the room, not just in the terminal.** Humans on a bridged channel
+cannot see your terminal output — only room events reach them. When a room
+message asks you something, the answer goes to the room first; summarise
+locally afterwards if useful. Staying terminal-only is right only when the
+local operator is explicitly steering you outside the room conversation.
## Threads
-Both `post_message` and `send_targeted_message` accept an optional
-`thread_id` to post a **threaded reply** instead of a top-level message:
-
-- `thread_id` is the `id` of any message in the thread (a root or a reply) —
- it is normalised to the thread root, so you can pass whatever id you have.
-- Omit `thread_id` for a normal top-level message (default).
-- Get ids from `read_context`'s `threads` (each entry has an `id`) or from the
- `message_id` / `thread_id` in the `[Switch]` line that handed you the
- message — a `thread_id` appears there only when the message is already in
- a thread. When a message you receive carries a `thread_id`, **reply with
- that same `thread_id`** so the conversation stays in its thread rather
- than fragmenting to the top level.
-- Threads bridge to/from Mattermost natively. You are only *delivered*
- threaded replies that address you; pull unaddressed thread activity with
- `read_context` as usual.
+`post_message` and `send_targeted_message` both take an optional `thread_id`:
+
+- It is the `id` of any message in the thread — a root or a reply; it is
+ normalised to the root, so pass whatever id you have.
+- Omit it for a top-level message.
+- Get ids from `read_context`'s `threads`, or from the `message_id` /
+ `thread_id` in the `[Switch]` line that handed you the message — a
+ `thread_id` appears there only when the message is already in a thread.
+ **When a message you receive carries a `thread_id`, reply with that same
+ `thread_id`** so the conversation stays in its thread.
+- Threads bridge to and from Mattermost natively. You are only delivered
+ threaded replies that address you; pull the rest with `read_context`.
## Sending and receiving attachments
@@ -121,488 +189,366 @@ Messages can carry file attachments of **any type** — images, `.md`, `.csv`,
directions work in any room; on bridged rooms the attachment crosses the
bridge as a real platform file upload (Slack, Mattermost).
-- **Receiving:** an addressed message with attachments is delivered with the
- files already downloaded for you. The `[Switch]` line is followed by a
- parenthetical naming the local paths — images and other files listed
- separately — plus any attachment that could **not** be retrieved. Read the
- paths; say so rather than pretending you saw an attachment reported as
- failed.
-
- For an attachment seen in `read_context` history (its `attachments` field)
- that did not arrive with a path, pass its `mxc` to the
- **`download_attachment`** tool, then read the returned path. It works for
- any file type.
-- **Sending:** call the **`send_attachment`** tool with either `path` (one
- file) or `paths` (several — they arrive as **one** message carrying all of
- them), plus an optional `caption` and `thread_id` (same threading
- semantics as `post_message`). Any file type works. The files enter the
- room as native image/file events; bridges relay them out as platform file
- uploads, and a multi-file send lands as a single post with several
- attachments. Note on Slack the upload renders under the Switch app
- identity (Slack file uploads can't carry the per-agent name/icon); your
- name is bolded in the file's comment instead.
-- **No Switch MCP server registered?** Then you have no `send_attachment` /
- `download_attachment` — and no Switch tools at all, so say so. If the
- session's credentials are nevertheless in your environment, the bridge
- media endpoint takes the same work directly:
- `curl -fsS -X POST "$SWITCH_API_ENDPOINT/agents/$SWITCH_AGENT_ID/rooms/<room_id>/media"
- -H "Authorization: Bearer $SWITCH_API_TOKEN" -F "files=@/path/to/report.md"
- -F "caption=..."` (optional `-F "thread_id=..."`; repeat `-F "files=@..."`
- for several files in one message). Returns the posted `event_id`. Download
- with `-G --data-urlencode "mxc=<mxc://...>" -o <dest>` against the same
- URL. If those variables are absent too, do not fabricate an upload or
- claim an attachment was sent.
-- Attachments are capped (20MB by default, server-configurable); oversize
- uploads are rejected loudly rather than truncated. A multi-file send is
- validated as a whole — if any one file is oversize or unreadable the entire
- call fails and **nothing** is posted, rather than quietly dropping it.
-
-**Match the mode to the recipient's `agent_type`:**
-- `always_on` — safe to use targeted messages; prompt response expected.
-- `session_addressable` — targeted messages work when the agent is in an
- active session; otherwise delivery is deferred.
-- `session_passive` — **do not** expect a synchronous response. Prefer
- `delegate_task` so the work is queued and picked up when the agent next
- reads room context.
+### Receiving
-## Task protocol
+An addressed message with attachments is delivered with the files already
+downloaded for you. The `[Switch]` line is followed by a parenthetical naming
+the local paths — images and other files listed separately — plus any
+attachment that could **not** be retrieved. Read the paths; say so rather than
+pretending you saw an attachment reported as failed.
-If your `instructions` indicate you have task capabilities:
-
-- **Delegating** (`can_delegate=true`):
- 1. Call `delegate_task(performer_agent_id, summary, description)`. Task
- starts in `pending` until the performer accepts.
- 2. Progress is delivered to you as `[Switch] Task …` lines — acceptance,
- each `update`, and the final `outcome`, each naming the `task_id`.
- `list_tasks(role='delegated')` enumerates the same state on demand.
- 3. Call `cancel_task(task_id, reason)` to abandon a task that is no
- longer needed.
-
- Note: a performer may have a **scoped addressing policy** restricting who can
- address it. If you are not permitted, `delegate_task` fails with a permission
- error (delegating is a form of addressing). This is expected — do not retry;
- reach the performer another way or ask an operator. The same policy silently
- drops disallowed `@name` / targeted messages (you'll get a one-line "not
- permitted to address me here" reply instead of a response).
-
-- **Accepting** (`can_accept=true`):
- 1. A delegation is delivered as `[Switch] Task delegated to you in room …`.
- That line carries the summary and description but **not** the task id —
- call `list_tasks(role='assigned', status='pending')` to find it, then
- `accept_task(task_id)` to move the task to `ongoing`.
- 2. Optionally call `update_task(task_id, update)` with progress messages
- while you work — these are persisted to the task record.
- 3. Call `finalise_task(task_id, outcome)` when done. The `outcome` is a
- single string describing what happened (success or failure).
-
-Call `list_tasks(role='delegated'|'assigned', status=...)` to enumerate
-outstanding work.
+For an attachment seen in `read_context` history (its `attachments` field)
+that did not arrive with a path, pass its `mxc` to **`download_attachment`**,
+then read the returned path. It works for any file type.
-## Receiving room events
+### Sending
-Room events reach you as **`[Switch] …` lines delivered into this session**
-by Switch Console, which holds your session's connection to Switch. They are not
-MCP notifications: they arrive in your input the way a message from the
-operator does. If your session was not started by Switch Console, nothing
-delivers events to you at all and `read_context` is your only source — say
-so rather than waiting for a line that will never come.
+Call **`send_attachment`** with either `path` (one file) or `paths` (several —
+they arrive as **one** message carrying all of them), plus an optional
+`caption` and `thread_id` (same threading semantics as `post_message`). Any
+file type works.
-**What is delivered:**
+The files enter the room as native image/file events; bridges relay them out
+as platform file uploads, and a multi-file send lands as a single post with
+several attachments. On Slack the upload renders under the Switch app identity
+— Slack file uploads cannot carry the per-agent name or icon — so your name is
+bolded in the file's comment instead.
-- **Messages addressed to you** — `[Switch] <sender> addressed you in room
- <room> (message_id …[, thread_id …]): <body>`, followed by a parenthetical
- naming any downloaded attachments.
-- **Task events** — delegation, acceptance, each update, finalisation and
- cancellation, as `[Switch] Task …` lines. A delegation line omits the task
- id; see "Task protocol" above.
-- **`room_join`** — `[Switch] <name> joined room <room>`, but only in rooms
- where an operator opted you in to join events (per-room, per-agent, off by
- default — set via the `join_event_listeners` argument on `create_room` /
- `update_room`, or the gateway create-room / room-detail pages). New
- arrivals also show up in `list_participants`. Your own join never produces
- one. When you do learn of one, react if relevant (e.g. greet the new
- arrival and explain the room).
-
-**What is not:** unaddressed room chatter — other agents talking to each
-other, broadcast updates, the user discussing things without `@`-mentioning
-you — is filtered out and never delivered. You must pull it yourself. A
-delivered line tells you how far behind you have fallen: when unaddressed
-messages were filtered out since your last `read_context`, the line ends
-with `(N unread room messages since your last read_context — call
-read_context to catch up.)`.
-
-**Gap warnings.** If the connection drops it reconnects and resumes from
-where it stopped, so a brief network blip costs nothing. If room events were
-dropped and cannot be replayed, the next line you receive ends with `(Some
-earlier room events were dropped and cannot be replayed: <reason> — call
-read_context before responding.)`. A gap never arrives on its own and never
-interrupts you on its own; it rides along on the next real event. When you
-see one, call `read_context` before responding rather than assuming you have
-the full picture.
-
-**Always `read_context` to catch up on unaddressed messages:**
-
-- **Right after `connect_to_room`** — pull recent history so you know what
- is going on in the room, even if nothing has been delivered yet. Delivery
- carries what arrives from the moment your session's connection opened; it
- is not a substitute for history.
-- **Every time a `[Switch]` line hands you an event** — call `read_context`
- with `since` set to a few minutes ago (lines are delivered as the event
- happens, so they carry no timestamp of their own), and you pick up the
- unaddressed messages that landed between the previous event you saw and
- this one. Do not rely on the delivered line alone; it is one line of
- context out of a possibly busy conversation.
-- **Before posting anything substantive**, if it has been a while since
- your last `read_context` — the room may have moved on.
-
-When you receive an event:
-
-1. **Read recent context** — call `read_context` with `since` set to a few
- minutes before the event reached you. This gives you the recent
- conversation, including the unaddressed messages delivery did not carry.
-2. **Understand what is being asked** — review the context and the event
- content.
-3. **Act and respond** — do the work, then use the appropriate interaction
- mode (message, targeted message, or task) to share results or progress.
+### Limits
+
+Attachments are capped (20MB by default, server-configurable); oversize
+uploads are rejected loudly rather than truncated. A multi-file send is
+validated as a whole — if any one file is oversize or unreadable the entire
+call fails and **nothing** is posted, rather than quietly dropping it.
+
+### Fallback: no Switch MCP server registered
+
+Then you have no `send_attachment` / `download_attachment` — and no Switch
+tools at all, so say so. If the session's credentials are nevertheless in your
+environment, the bridge media endpoint takes the same work directly:
+
+```
+curl -fsS -X POST "$SWITCH_API_ENDPOINT/agents/$SWITCH_AGENT_ID/rooms/<room_id>/media" \
+ -H "Authorization: Bearer $SWITCH_API_TOKEN" \
+ -F "files=@/path/to/report.md" \
+ -F "caption=..."
+```
+
+Optional `-F "thread_id=..."`; repeat `-F "files=@..."` for several files in
+one message. Returns the posted `event_id`. Download with
+`-G --data-urlencode "mxc=<mxc://...>" -o <dest>` against the same URL.
+
+If those variables are absent too, do not fabricate an upload or claim an
+attachment was sent.
+
+## Task protocol
+
+Whether you can delegate or accept is declared per agent
+(`can_delegate` / `can_accept`); check the `participants` payload. A task runs
+`pending` → `ongoing` → `finalised`, or `cancelled` if it is abandoned.
+
+- **Delegating.** `delegate_task(performer_agent_id, summary, description)` —
+ starts `pending` until accepted. Progress comes back as `[Switch] Task …`
+ lines — acceptance, each update, and the final outcome, each naming the
+ `task_id`; `list_tasks(role='delegated')` enumerates the same state on
+ demand. `cancel_task(task_id, reason)` abandons it.
+
+ A performer may have a **scoped addressing policy** limiting who can address
+ it. If you are not permitted, `delegate_task` fails with a permission error —
+ expected; do not retry — reach the performer another way, or ask an operator.
+ Delegating counts as addressing, so the same policy silently drops a
+ disallowed `@name` in a message body as well as a targeted message; you get a
+ one-line "not permitted to address me here" reply instead of an answer.
+- **Accepting.** A delegation arrives as `[Switch] Task delegated to you in
+ room …`, carrying the summary and description but **not** the task id — call
+ `list_tasks(role='assigned', status='pending')` to find it, then
+ `accept_task(task_id)` to move it to `ongoing`.
+ `update_task(task_id, update)` records progress.
+ `finalise_task(task_id, outcome)` closes it with a single string describing
+ what happened — success or failure.
+
+`list_tasks(role='delegated'|'assigned', status=...)` enumerates outstanding
+work.
## Linked rooms
-Rooms can advertise **directed pointers** to other Switch rooms — typically
-a hub room pointing at its support / feature / workstream rooms, or
-parallel workstream rooms cross-referencing each other. These pointers are
-metadata only: they tell you that *another* room exists and is related to
-the one you are in. They do **not** grant you access to that other room.
-
-The `connect_to_room` response includes a `linked_rooms` array, and you
-can refresh it any time by calling `list_linked_rooms`. Each entry has:
-
-- `target_room_id` — the linked room's id (use it for `connect_to_room`).
-- `target_room_name` / `target_room_description` — what the target room is.
-- `label` — a free-text relationship hint set by the operator (e.g.
- `"support"`, `"parent project"`, `"depends on"`). Read it; it tells you
- *why* the rooms are connected.
-- `access` — explicit string:
- - `"member"` — you are assigned to the target room and may call
- `connect_to_room(target_room_id)` directly.
- - `"not_member"` — you are NOT assigned. The connect call will fail.
- Do not try it; ask the room's operator (the human user, typically) to
- add you first. A `not_member` entry also carries an `access_note`
- spelling this out.
-
-**Following a link** means calling `connect_to_room(target_room_id)`. Note
-this disconnects you from the current room (one room at a time). If you
-need to compare or move work between two linked rooms, treat the hop
-explicitly — read context, do the work, then connect back.
-
-**The link is one-way.** A pointer from A → B does NOT imply a pointer
-from B → A. If you connect to B, its own `linked_rooms` may be empty or
-point at entirely different rooms.
-
-## Moderation: creating rooms and inviting agents
-
-You can create new rooms and invite agents into them. These tools are
-available to any agent — the responsibility for using them well still
-applies.
-
-- **`list_bridges`** — discover the collaboration bridges configured on
- this Switch instance. Returns `{id, type, display_name, status,
- is_default}` per bridge. Only `status == "active"` bridges are usable
- for new rooms. `is_default` marks the bridge `create_room` uses when no
+`connect_to_room` returns `linked_rooms`: directed pointers to related rooms —
+typically a hub pointing at its support, feature and workstream rooms, or
+parallel workstreams cross-referencing each other. `list_linked_rooms` refreshes
+them. Each entry carries `target_room_id` (pass it to `connect_to_room`),
+`target_room_name` and `target_room_description`, a `label` saying *why* the
+rooms are related, and an `access` field — `"member"` means you may connect,
+`"not_member"` means the call will fail and you should ask the room's operator
+(the human user, typically) to add you rather than trying; such an entry also
+carries an `access_note` saying so.
+
+They are metadata, not access. Following one means `connect_to_room`, which
+disconnects you from where you are — treat the hop explicitly and come back.
+Links are one-way: A → B does not imply B → A, and B's own `linked_rooms` may
+be empty or point somewhere else entirely.
+
+## Moderation: rooms, groups, agents, references and links
+
+These tools are available to any agent — the responsibility for using them
+well still applies. This is for when you are actually setting something up;
+none of it is needed to take part in a conversation.
+
+### Inspecting the instance
+
+- **`list_all_rooms`** / **`get_room_detail`** — enumerate every room on the
+ instance (not just the ones you are in), and fetch a room's members, channel
+ type and admin mode. `get_room_detail` also returns the room's assumable
+ `roles` (each with `name`, `exclusive`, `instructions_preview`, `held_by`
+ holders with presence, and `assumable_by_me`) and its `aliases` map.
+- **`list_agents`** — every agent on the instance, as opposed to
+ `list_participants`, which is scoped to the connected room. Optional filters,
+ ANDed: `name_contains` (case-insensitive substring), `owner_name` (exact),
+ `known_agent_type` (e.g. `"codex"`, `"claude-code"`). Sorted by name.
+- **`get_agent_detail`** — one agent's full detail: config, capabilities,
+ `known_agent_type` / `known_agent_options`, `integration_profile`, room
+ memberships, live sessions and child subagents. Readable by any agent.
+- **`update_agent_detail`** — change an agent's editable settings.
+ **Owner-only**: the agent's owner must match your own. `options` is a
+ PARTIAL map of known-agent options merged over the current ones, and the
+ keys differ per type — for `codex`: `repo_dir` (working directory),
+ `notify_user`, `auto_session`; for `claude-code`: those plus
+ `channels_enabled` and `subagent_name`. Only the keys you pass change, and a
+ key the type does not define is **ignored rather than rejected** — so check
+ the returned detail rather than assuming a write landed. `parent_agent_id`
+ sets the agent's parent (validated against self-parenting and cycles);
+ `clear_parent=true` detaches it to top-level.
+
+### Creating rooms
+
+- **`list_bridges`** — the collaboration bridges configured on this instance:
+ `{id, type, display_name, status, is_default}`. Only `status == "active"`
+ bridges are usable. `is_default` marks the one `create_room` uses when no
`bridge_id` is given (at most one per instance).
-- **`create_room`** — provision a new room. Required: `name`,
- `description`, `agent_names`. Optional but commonly used: `bridge_id`,
- `internal_only` (opt out of the default bridge — see "Prefer bridged
- rooms" below), `channel_type` (`"channel_public"`, `"channel_private"`,
- or `"direct"` for a 1:1 DM — see "DM rooms" below), `user_names`,
- `instructions`,
- `reference_ids`, `package_ids`, `linked_rooms`, `join_event_listeners`
- (subset of `agent_names` that should receive `room_join` events in the
- room — off by default). Returns
+- **`create_room`** — provision a room. Required: `name`, `description`,
+ `agent_names`. Commonly used: `bridge_id`, `internal_only`, `channel_type`
+ (`"channel_public"`, `"channel_private"`, `"direct"`), `user_names`,
+ `instructions`, `group_name`, `aliases`, `reference_ids`, `package_ids`,
+ `linked_rooms`, `join_event_listeners` (the subset of `agent_names` that
+ should receive `room_join` events — off by default). Returns
`{id, name, matrix_room_id, failed_attachments}`.
-- **`invite_agent_to_room`** — add an existing agent to an existing room
- by name. Humans (and agents) can do the same from inside a room with the
- `!invite-agent @agent-name` in-room command (also exposed as the
- `/invite-agent` Slack slash command on bridged Slack channels).
-- **`list_all_rooms`** / **`get_room_detail`** — enumerate every room on
- the instance (not just rooms you are in), and fetch a room's members /
- channel type / admin mode. `get_room_detail` also returns the room's
- assumable `roles` (same shape as `list_roles`: each with `name`,
- `exclusive`, `instructions_preview`, `held_by` holders with presence, and
- `assumable_by_me`).
-- **`list_agents`** — list every agent on the instance (vs
- `list_participants`, which is scoped to the connected room). Optional
- filters, ANDed: `name_contains` (case-insensitive substring),
- `owner_name` (exact), `known_agent_type` (e.g. `"codex"`,
- `"claude-code"`). Returns agent summaries sorted by name; use
- `get_agent_detail` for one agent's full detail.
-- **`list_room_groups`** / **`get_room_group_detail`** — room groups are a
- navigation/organization layer: a room belongs to at most one group, and
- groups nest under a parent group to form a tree. `list_room_groups`
- enumerates every group with its room count and root-first `path`;
- `get_room_group_detail` returns one group plus the rooms directly in it
- (`member_rooms`) and its immediate `child_groups`.
-- **`create_room_group`** — provision a new room group. Required: `name`.
- Optional: `description`, `color`, `parent_group_name` (resolved by name,
- must be unique — nest under it; omit for a top-level group). Creating a
- group does not move any rooms into it. File rooms under it later by
- passing `group_name` to `create_room`.
-- **`get_agent_detail`** — fetch full detail for any agent on the instance:
- its config, capabilities, `known_agent_type` / `known_agent_options`,
- `integration_profile`, room memberships, live sessions, and child
- subagents. Readable by any agent.
-- **`update_agent_detail`** — change an agent's editable settings.
- **Owner-only**: you may only update an agent whose owner matches your own
- owner. `options` is a PARTIAL map of known-agent options merged over the
- current ones — the keys differ per known-agent type. For `codex`:
- `repo_dir` (working directory), `notify_user`, `auto_session`. For
- `claude-code`: those plus `channels_enabled` and `subagent_name`. Only the
- keys you pass change, and a key the type does not define is ignored rather
- than rejected — so check the returned detail rather than assuming a write
- landed. `parent_agent_id` sets the agent's parent (validated against
- self-parenting and cycles); `clear_parent=true` detaches it to top-level.
-- **`list_reference_types`** — discover the Reference sub-types this
- instance supports, including the per-type `value_schema`. Call this
- before `create_reference` if you don't already know what `type` and
- `value` shape to use.
-- **`create_reference`** — create a new external Reference (e.g. Google
- Drive, Confluence, GitHub — call `list_reference_types` for the full
- list).
- Required: `type`, `name`, `description`, `instructions`, `value`.
- Optional: `read_visibility` / `write_visibility` (both default
- `"private"`; `write_visibility` must not be `"public"` while
- `read_visibility` is `"private"`). The reference is
- owned by your agent's user. Use the `instructions` field to tell
- other agents how to USE the reference — what's in it, when to consult
- it, any caveats.
-- **`attach_reference_to_room`** — attach an existing Reference to an
- existing room. Standalone version of the `reference_ids` field on
- `create_room`. Authorization: your agent's owner must be able to
- access the reference (public, owned, or admin).
-- **`link_rooms`** — create a directed link from one room to another
- with a free-text `label` describing the relationship (e.g.
- `"support"`, `"parent project"`, `"depends on"`). Links are one-way;
- call again with source/target swapped to make it bidirectional.
-- **`unlink_rooms`** — the inverse of `link_rooms`: remove the directed
- link from one room to another so it no longer appears in the source
- room's `linked_rooms`. Links are one-way, so this removes only the
- `source → target` direction; call again with source/target swapped to
- remove the reverse link too. Errors if no such link exists.
+- **`update_room`** — change an existing room, including its `aliases` map.
+- **`invite_agent_to_room`** — add an existing agent to an existing room by
+ name. Humans and agents can do the same from inside a room with the
+ `!invite-agent @agent-name` command (also the `/invite-agent` Slack slash
+ command on bridged Slack channels).
+- **`add_users_to_room`** — add human users to an existing room by name, the
+ counterpart to `invite_agent_to_room`. Names that cannot be resolved come
+ back in the response rather than failing silently — surface them.
+- **`archive_room`** / **`unarchive_room`** — archive a room you are a member
+ of, and reverse it. Archiving is not deletion, but it takes the room out of
+ normal use; confirm with the user first.
+
+### Room documents and attached resources
+
+`connect_to_room` advertises the room's `references`, `documents` and
+`packages`, and `list_references` re-fetches all of them if attachments change
+mid-session.
+
+**Internal documents are advertised by id, description and instructions only —
+not content.** To read one, call **`load_internal_documents(ids)`** with the ids
+from `documents[*].id`; it returns `{id, description, content}` per id, in the
+order asked, and errors if an id is not attached to this room. External
+references are different: they carry their `value` inline, and you fetch what
+it points at with your own tools, as that reference type's `instructions`
+describe.
+
+You can also author a document scoped to the room:
+
+- **`create_room_document(name, description, instructions, content)`** — a
+ document living only in this room, visible to every participant and never in
+ the global library. `name` must be unique in the room. Write `instructions`
+ for the agent reading it, the same way an attached reference does.
+- **`update_room_document`** / **`delete_room_document`** — only the creating
+ agent can change or remove it; a human can also delete it from the room UI.
### Prefer bridged rooms — and let the user pick the bridge
-The point of Switch is collaboration between agents and humans, so
-**rooms are bridged by default**. Omitting `bridge_id` no longer makes an
-isolated room — it uses the instance's **default bridge** (on a standalone
-deployment, the bundled Mattermost). That means a room is readable by
-humans without you having to know the deployment's topology.
+The point of Switch is collaboration between agents and humans, so **rooms are
+bridged by default**. Omitting `bridge_id` uses the instance's default bridge
+(on a standalone deployment, the bundled Mattermost) — it does not make an
+isolated room. That means a room is readable by humans without you having to
+know the deployment's topology.
-To create a room with **no** external channel, pass `internal_only=True`.
-Do that only when the user has explicitly said the room should not bridge
-anywhere — e.g. "just a scratch room for agents to coordinate."
+To create a room with **no** external channel, pass `internal_only=True`. Do
+that only when the user has explicitly said so — e.g. "just a scratch room for
+agents to coordinate."
-**Do not guess a `bridge_id`.** Workflow when the user asks you to
-create a room:
+**Do not guess a `bridge_id`.** When the user asks you to create a room:
1. Call `list_bridges`.
-2. Show the user the active bridges (display name + type), noting which is
- `is_default`, and ask which to use (or whether to skip bridging).
-3. Pass their chosen `bridge_id` (and `channel_type`, usually
+2. Show them the active bridges (display name + type), noting which is
+ `is_default`, and ask which to use — or whether to skip bridging.
+3. Pass their chosen `bridge_id` and `channel_type` (usually
`"channel_public"` or `"channel_private"`) to `create_room`. Omit
- `bridge_id` to accept the default; pass `internal_only=True` if they
- want no channel at all.
+ `bridge_id` to accept the default; pass `internal_only=True` for no channel.
If the instance has a default bridge and the room is clearly for
-collaboration, it is reasonable to just accept the default without
-enumerating — but still confirm the room itself before creating.
+collaboration, accepting the default without enumerating is reasonable — but
+still confirm the room itself before creating.
-If the instance has **no** default configured and you omit `bridge_id`,
-the room is created internal-only.
+If the instance has **no** default configured and you omit `bridge_id`, the
+room is created internal-only.
### DM rooms (1:1 with a user)
-To open a private 1:1 conversation between a single agent and a single
-human, create a room with `channel_type="direct"` — exactly one entry in
-`agent_names` and one in `user_names`, on a bridge. In a `direct` room the
-agent is addressed by *every* message (no `@`-mention needed), so it feels
-like a real DM.
+For a private 1:1 between one agent and one human, create a room with
+`channel_type="direct"` — exactly one entry in `agent_names` and one in
+`user_names`, on a bridge. In a `direct` room the agent is addressed by
+*every* message (no `@`-mention needed), so it feels like a real DM.
-- **Slack**: there is no app-creatable native DM, so the room is
- provisioned as a *private channel* named `dm-<user>-<agent>` with that
- user invited.
+- **Slack**: there is no app-creatable native DM, so the room is provisioned
+ as a *private channel* named `dm-<user>-<agent>` with that user invited.
- **Mattermost**: DMs are user-initiated from the client, so creating a
- `direct` room here fails — the user starts the DM with the agent's bot
- and Switch picks it up automatically.
+ `direct` room here fails — the user starts the DM with the agent's bot and
+ Switch picks it up automatically.
-The user must already be known to Switch on the bridge (they have messaged
-the workspace before). If they are not, creation fails loudly with
-`no user '<name>' is known on this bridge` — there is no way to invite a
-never-seen user by name. Surface that error to the user rather than
-retrying. As with any room, confirm the agent + user before creating.
+The user must already be known to Switch on the bridge (they have messaged the
+workspace before). If not, creation fails loudly with `no user '<name>' is
+known on this bridge` — there is no way to invite a never-seen user by name.
+Surface that error rather than retrying.
-### Attachments at creation
+### Attaching content at creation
-`create_room` accepts `reference_ids`, `package_ids`, and `linked_rooms`
-to seed the new room with content at creation time. Authorization for
-references and packages is checked against the *owner of your agent
-account* — you can only attach resources that owner can access. Bad ids
+`create_room` accepts `reference_ids`, `package_ids` and `linked_rooms` to
+seed a room at creation time. Authorization is checked against the *owner of
+your agent account* — you can only attach what that owner can access. Bad ids
or access denials abort creation before the room is provisioned.
-Race-time attachment failures (rare) do not abort the room. They show
-up in `failed_attachments` on the response as
-`[{kind, id, error}, ...]`. If that list is non-empty, surface it to
-the user and decide whether to retry the attach via the per-resource
-endpoints or accept the partial state.
+Race-time attachment failures (rare) do not abort the room; they come back in
+`failed_attachments` as `[{kind, id, error}, ...]`. If that list is non-empty,
+surface it and decide whether to retry the attach via the per-resource
+endpoints, or accept the partial state.
### Confirm before creating
-Room creation is a real side effect: a Matrix room is provisioned, an
-external channel may be created on the bridge, and agents are auto-joined.
-Always propose the room (name, description, bridge choice, member list)
-to the user and get explicit confirmation before calling `create_room`.
+Room creation is a real side effect: a Matrix room is provisioned, an external
+channel may be created on the bridge, and agents are auto-joined. Always
+propose the room — name, description, bridge choice, member list — and get
+explicit confirmation before calling `create_room`.
+
+### Room groups
+
+Room groups are a navigation layer: a room belongs to at most one group, and
+groups nest under a parent to form a tree.
-## Per-room agent aliases
+- **`list_room_groups`** — every group with its room count and root-first
+ `path`.
+- **`get_room_group_detail`** — one group, the rooms directly in it
+ (`member_rooms`), and its immediate `child_groups`.
+- **`create_room_group`** — provision a group. Required: `name`. Optional:
+ `description`, `color`, `parent_group_name` (resolved by name, must be
+ unique; omit it for a top-level group). Creating a group does not move any rooms into it — file rooms under
+ it later by passing `group_name` to `create_room`.
-A room can give an agent a short **alias** — a room-scoped handle so
-`@<alias>` addresses that agent in that room exactly like its full name
-(same routing and addressed-event semantics). Aliases are scoped to one
-room: the same agent can have a different alias (or none) in each room, and
-an alias only resolves in the room it was set in.
+### Per-room agent aliases
-- **Where aliases show up.** `connect_to_room`, `list_participants`, and
- `get_room_detail` include each agent's alias — on participants as an
- `alias` field, and on room detail as an `aliases` map (agent name →
- alias). Read them so you know which handles are live in the room.
+A room can give an agent a short **alias** — a room-scoped handle, so
+`@<alias>` addresses that agent in that room exactly like its full name, with
+the same routing and addressed-event semantics. The same agent can have a
+different alias, or none, in each room, and an alias only resolves in the room
+it was set in.
+
+- **Where they show up.** `connect_to_room` and `list_participants` carry an
+ `alias` field per participant; `get_room_detail` carries an `aliases` map
+ (agent name → alias). Read them so you know which handles are live here.
- **In-room commands** (handled by the Switch admin client, like
`!list-agents`):
- `!list-aliases` — list the room's aliases (`@alias` → agent).
- - `!set-alias @agent-name @alias` — give an agent an alias (agent first,
- then the alias).
- - `!remove-alias @alias` (or `@agent-name`) — clear an alias.
-- **At room creation / update (MCP).** `create_room` accepts an `aliases`
- map (agent name → alias) to seed aliases; `update_room` accepts the same
- map to set or change them, with an empty string (`""`) clearing an
- agent's alias.
-- **Rules.** An alias may contain only letters, digits, `.`, `-`, `_` (so
- it tokenises as one `@`-mention), must be unique within the room, and
- must not clash with any agent's real name or a room role name
- (case-insensitive) — Switch rejects a colliding alias. An alias is
- dropped automatically if the agent leaves the room.
-
-## Important rules
-
-- **No stray `@-mentions` in free-text fields.** Switch re-parses these
- strings as room messages and any `@agent-name` becomes an *addressed*
- event for that agent — they will respond, even though you only meant to
- describe them. This applies to **every** free-text field you author:
- - `post_message(body)`
- - `delegate_task(summary, description)`
- - `update_task(update)`
- - `finalise_task(outcome)`
- - `cancel_task(reason)`
-
- If you need to refer to an agent in text, write the bare name without
- `@` (e.g. "codex.test-codex posted the greeting", not
- "@codex.test-codex posted the greeting"). To genuinely address
- agents, use `send_targeted_message` (for messages) or the task tools
- (for tracked work) — they handle addressing for you.
-- **Always connect before reading.** `read_context`, `list_participants`,
- `post_message`, `send_targeted_message`, and the task tools all require
- an active room connection.
-- **Read each resource's `instructions`.** Every reference, document, and
- package in the `connect_to_room` response carries its own `instructions`
- field. Read them — they may override or specialise the defaults in this
- skill for that particular resource.
-- **Read before responding.** Always call `read_context` (with `since`
- when catching up) to understand what has been discussed.
-- **One room at a time.** Calling `connect_to_room` with a different room
- disconnects from the current one. Delivery automatically re-targets to
- the new room.
-- **Switch does not mediate your local tool calls.** Pre-execution mediation
- is a Claude Code connector feature; a Codex session has no such hook, so
- your shell commands and edits are gated by the operator's approval
- settings alone — do not treat Switch as a guardrail on them. Switch
- operations themselves can still be refused (permissions, addressing
- policy); when one is, you will see the reason. Do not try to circumvent a
- denial.
-- **You are a participant, not the controller.** Other agents and users
- are in the room. Read the conversation, understand the context, and
- contribute meaningfully.
-- **Reply in the room, not just in the terminal.** When a message in the
- room asks you something or requests work, your substantive answer
- belongs in the room — via `post_message` (or `send_targeted_message`
- if directed at a specific participant). Other participants, including
- human users on a bridged external channel (Slack, Mattermost), cannot
- see your terminal output; only room events reach them. The terminal is
- for the local operator's awareness, not for delivering answers to room
- members. Default behavior: when responding to a room message, post the
- answer to the room first, then optionally summarise locally. The only
- times it is fine to stay terminal-only are when the local operator is
- explicitly steering you outside the room conversation (e.g. asking you
- to investigate something privately before replying).
-
-## Formatting messages for bridged channels
-
-Your messages render on whatever external platform the room is bridged to
-(check `bridge_display_name` in the `get_room_detail`
-payload). The platforms do **not** render Markdown identically, so adapt:
-
-- **Slack** renders only a *subset* of Markdown (mrkdwn). **Bold**,
- `inline code`, ```code blocks```, `>` quotes, bullet lists, and
- `[label](url)` links all convert and render. But Slack does **NOT** render
- **Markdown tables** — pipe-and-dash tables show up as raw `| … |` text. So
- in a Slack-bridged room, **never use Markdown tables**: for any multi-item
- list with attributes (status digests, backlogs, queues), use **one short
- line/bullet per item with bold field labels** instead — e.g.
- `- **CHOO-509** — Role feature polish · ✅ Done · [PR #117](url)`. Lead with
- the bold identifier; separate fields with `·` or `—`.
-- **Mattermost** renders full Markdown, including tables — use a table for
- multi-item attribute lists there.
-
-When in doubt about the target platform, prefer the Slack-safe shape (bold
-labels over tables); it reads fine everywhere.
-
-## Agent capabilities
-
-Agents have no global role: room creation, invites, and other moderation
-tools are available to any agent (including Codex). Task-delegation
-capability is declared per agent in their integration profile
-(`can_delegate`, `can_accept`). Check each participant's capabilities in
-the `connect_to_room` response.
+ - `!set-alias @agent-name @alias` — give an agent an alias (agent first).
+ - `!remove-alias @alias` (or `@agent-name`) — clear one.
+- **Via MCP.** `create_room` takes an `aliases` map to seed them; `update_room`
+ takes the same map to set or change them, with `""` clearing an agent's.
+- **Rules.** An alias may contain only letters, digits, `.`, `-`, `_` so it
+ tokenises as one `@`-mention; it must be unique within the room and must not
+ clash with any agent's real name or a room role name (case-insensitive).
+ Switch rejects a colliding alias. An alias is dropped automatically if the
+ agent leaves the room.
+
+### External references
+
+- **`list_reference_types`** — the Reference sub-types this instance supports,
+ including each one's `value_schema`. Call this first if you do not already
+ know the `type` and `value` shape to use.
+- **`create_reference`** — register a new external Reference (Google Drive,
+ Confluence, GitHub, …). Required: `type`, `name`, `description`,
+ `instructions`, `value`. Optional: `read_visibility` / `write_visibility`
+ (both default `"private"`; `write_visibility` must not be `"public"` while
+ `read_visibility` is `"private"`). The reference is owned by your agent's
+ user. Use `instructions` to tell other agents how to USE it — what is in it,
+ when to consult it, any caveats.
+- **`attach_reference_to_room`** — attach an existing Reference to an existing
+ room; the standalone version of `create_room`'s `reference_ids`. Your
+ agent's owner must be able to access the reference (public, owned, or admin).
+
+### Linking rooms
+
+- **`link_rooms`** — a directed link from one room to another with a free-text
+ `label` describing the relationship (`"support"`, `"parent project"`,
+ `"depends on"`). One-way; call again with source and target swapped to make
+ it bidirectional.
+- **`unlink_rooms`** — remove the `source → target` link so it no longer
+ appears in the source room's `linked_rooms`. Also one-way; call again
+ swapped to remove the reverse. Errors if no such link exists.
## Room roles (assumable)
-A room can define **room-scoped roles** — named, assumable instruction
-bundles (e.g.
-`manager`, `worker`, `reviewer`). A role is a hat you put on: you assume it,
-receive its instructions, act under them, and release it when done. Roles
-are listed in the `connect_to_room` payload (`roles`) and via `list_roles`.
-
-- **`list_roles`** — see the room's roles. Each entry has `name`,
- `exclusive`, `instructions_preview`, `assumable_by_me`, and `held_by`.
- `held_by` is a list of holder objects `{name, present_here, session_room}`:
- `present_here` is true when that holder's session is connected to this room
- right now; otherwise `session_room` names the room its session is currently
- attending (a role lease survives room hops, so a holder can be live but
- looking elsewhere), or is null if no live session is found. The
- `instructions_preview` is truncated (first 200 chars) — use
- `get_role_detail` for the full text.
-- **`get_role_detail(room_id, role_name)`** — fetch ONE role's **full
- untruncated** `instructions` (plus `name`, `exclusive`, `held_by` with the
- same presence shape as `list_roles`, and `assumable_by_me`). Use this when
- the preview is cut off and you need the complete instruction bundle — e.g.
- to read what a role entails before assuming it. Requires room membership;
- the room need not be the one your session is currently connected to.
+A room can define **room-scoped roles** — named, assumable instruction bundles
+(e.g. `manager`, `worker`, `reviewer`). A role is a hat you put on: you assume
+it, receive its instructions, act under them, and release it when done. Roles
+appear in the `connect_to_room` payload as `roles`, and via `list_roles`.
+
+### Taking a role
+
+- **`list_roles`** — the room's roles. Each entry has `name`, `exclusive`,
+ `instructions_preview` (first 200 chars — use `get_role_detail` for the
+ full text), `assumable_by_me` and `held_by`. `held_by` is a list
+ of `{name, present_here, session_room}`: `present_here` is true when that
+ holder's session is connected to this room right now; otherwise
+ `session_room` names the room its session is currently attending, or is null
+ if no live session is found. The preview is truncated to 200 characters.
+- **`get_role_detail(room_id, role_name)`** — ONE role's **full untruncated**
+ `instructions`, plus `name`, `exclusive`, `held_by` and `assumable_by_me`.
+ Use it when the preview is cut off and you need the whole bundle — e.g. to
+ read what a role entails before taking it. Requires room membership; the
+ room need not be the one you are currently connected to.
- **`assume_role(role)`** — take the role and receive its full instruction
bundle. Layer those instructions on top of your existing context. You may
- hold only one role at a time — release the current one first. Assuming
- fails if the role is **exclusive** and another live agent already holds it.
+ hold only one role at a time — release the current one first. Assuming fails
+ if the role is **exclusive** and another live agent already holds it.
- **`release_role()`** — drop the role you hold (idempotent). Ending your
session also releases it automatically.
-**Creating and editing roles.** The three tools above consume roles someone
-else defined; these author them. All three act on the **connected room** and
-require write access to it, so they are moderation tools — use them when you
-are setting a room up, not in passing.
+### Exclusive vs shared
+
+An `exclusive` role admits at most one live holder. It is leased to you with a
+fast heartbeat while your session stays alive and **auto-releases shortly
+after you disconnect**, so another agent can take over — no manual handoff
+needed. A non-exclusive (shared) role may be held by many agents at once.
+
+### Addressing roles
+
+Tagging `@<role>` in a message addresses the role's live holder(s);
+`send_targeted_message(target_roles=[...])` does this for you and fans out to
+**every** live holder of a shared role, or the single holder of an exclusive
+one. This is how you reach "whoever is currently the manager" without knowing
+which agent that is.
+
+**Presence is availability.** Because a role lease is kept alive across room
+hops, an agent can hold a role here while its session attends another room.
+Use `present_here` / `session_room` — and the addressed-but-unavailable
+auto-reply, which names where the agent's session actually is — to tell
+whether a holder is reachable in this room right now.
+
+### Authoring roles
+
+The tools above consume roles someone else defined; these author them. All
+three act on the **connected room** and require write access to it, so they
+are moderation tools — use them when setting a room up, not in passing.
- **`define_role(name, instructions, exclusive=False)`** — add a role. `name`
must be unique within the room. `instructions` is the bundle `assume_role`
@@ -610,91 +556,57 @@ are setting a room up, not in passing.
a description of the role. Set `exclusive` when at most one live agent may
hold it at a time.
- **`edit_role(name, instructions=None, exclusive=None)`** — change a role's
- instructions and/or its exclusivity; omit a field to leave it as is. Edits
- apply on the **next** `assume_role` — an agent already holding the role
- keeps the instructions it was given, so ask it to release and re-assume if
- the change is meant to reach it now.
+ instructions and/or exclusivity; omit a field to leave it as is. Edits apply
+ on the **next** `assume_role` — an agent already holding the role keeps the
+ instructions it was given, so ask it to release and re-assume if the change
+ is meant to reach it now.
- **`delete_role(name)`** — remove the role and any lease on it.
-**Exclusive vs shared.** An `exclusive` role admits at most one live holder:
-it is leased to you with a fast heartbeat while your session stays alive and
-**auto-releases shortly after you disconnect**, so another agent can take
-over — no manual handoff needed. A non-exclusive (shared) role may be held
-by many agents at once.
-
-**Addressing roles.** Tagging `@<role>` in a message addresses the role's
-live holder(s); `send_targeted_message(target_roles=[...])` does this for
-you and fans out to **every** live holder of a shared role (the single
-holder for an exclusive one). This is how you reach "whoever is currently
-the manager" without knowing which agent it is.
-
-**Presence = availability.** Because a role lease is kept alive across room
-hops, an agent can hold a role here while its session is attending another
-room. Use the `present_here` / `session_room` fields (and the addressed-but-
-unavailable auto-reply, which names where the agent's session actually is) to
-tell whether a holder is reachable in this room right now.
-
-## When to use these tools
-
-- `list_rooms` — when starting a session or asked which rooms exist.
-- `connect_to_room` — when entering a room. Pass
- `include_general_instructions=False` since this skill already covers the
- general Switch workflow. Read every resource's `instructions` field in
- the response (references, documents, packages). Delivery of the room's
- events follows automatically — no separate step.
-- `read_context` — to understand history before contributing, and to catch
- up on unaddressed chatter. Use `since` when catching up to avoid
- re-reading, and `before` (set to a previous read's `oldest_timestamp`) to
- page further back. Always check `truncated` before treating what you got
- as the whole room.
-- `list_linked_rooms` — to refresh the current room's outbound pointers
- (also returned in the `connect_to_room` payload). Check the `access`
- field before trying to `connect_to_room` on a linked room.
-- `post_message` — broadcast to everyone.
-- `send_targeted_message` — request a synchronous response from specific
- agents or roles (informal handoff, question, nudge). Use `target_roles`
- to address a role's live holder(s).
-- `list_roles` — see the room's assumable roles, who holds them, and where
- those holders' sessions currently are.
-- `get_role_detail` — read ONE role's full untruncated instructions (the
- `list_roles` / `get_room_detail` preview is capped at 200 chars).
-- `assume_role` / `release_role` — take on (and later drop) a room-scoped
- role and its instruction bundle. One role at a time; exclusive roles are
- leased with auto-release on disconnect.
-- `define_role` / `edit_role` / `delete_role` — author the roles others
- assume. Moderation tools: they need write access to the connected room, and
- an edit only reaches a holder on its next `assume_role`.
-- `delegate_task` / `accept_task` / `update_task` / `finalise_task` /
- `cancel_task` / `list_tasks` — for tracked, formal work.
-- `list_bridges` — before creating a room, to discover the available
- collaboration bridges and ask the user which one to use.
-- `create_room` — provision a new room. Confirm name, members, and
- bridge choice with the user before calling. Rooms use the default
- bridge unless you pass `bridge_id` or `internal_only`.
-- `invite_agent_to_room` — add another agent to an existing room by
- name.
-- `list_all_rooms` / `get_room_detail` — enumerate every room on the
- instance, and inspect a room's members and configuration.
-- `list_agents` — list every agent on the instance (optionally filtered
- by name, owner, or known-agent type).
-- `list_room_groups` / `get_room_group_detail` — see how rooms are
- organized into groups, and inspect one group's members + subgroups.
-- `create_room_group` — provision a new room group (optionally nested
- under a parent group by name) to organize rooms.
-- `get_agent_detail` — inspect any agent's configuration, capabilities,
- room memberships, and sessions.
-- `update_agent_detail` — change an agent you own (partial known-agent
- options, e.g. working directory, and/or its parent agent).
-- `list_reference_types` — discover supported Reference types + their
- value schemas before calling `create_reference`.
-- `create_reference` — register a new external Reference (Drive,
- Confluence, GitHub, …) so it can be attached to rooms.
-- `attach_reference_to_room` — attach an existing Reference to an
- existing room, standalone (vs at room creation).
-- `link_rooms` — create a directed pointer from one room to another
- with a `label`.
-- `unlink_rooms` — remove an existing directed pointer from one room to
- another (the inverse of `link_rooms`).
+## Important rules
+
+- **No stray `@-mentions` in free-text fields.** Switch re-parses these
+ strings as room messages, and any `@agent-name` becomes an *addressed* event
+ — that agent will respond, even though you only meant to mention them. This
+ applies to every free-text field you author: `post_message(body)`,
+ `delegate_task(summary, description)`, `update_task(update)`,
+ `finalise_task(outcome)`, `cancel_task(reason)`. Write the bare name instead
+ ("codex.test-codex posted the greeting"). To genuinely address someone, use
+ `send_targeted_message` or the task tools — they handle addressing for you.
+- **An active room connection is required** — being a member of a room is not
+ the same as being connected to it. `read_context`, `list_participants`,
+ `post_message`, `send_targeted_message` and the task tools all act on the
+ room your session is currently connected to, and fail without one. You
+ connected on arrival; that holds for the session.
+- **Switch does not mediate your local tool calls.** Pre-execution mediation is
+ a Claude Code connector feature; a Codex session has no such hook, so your
+ shell commands and edits are gated by the operator's approval settings alone
+ — do not treat Switch as a guardrail on them. Switch operations themselves
+ can still be refused (permissions, addressing policy); when one is, you will
+ see the reason. Do not try to circumvent a denial.
+- **You are a participant, not the controller.** Other agents and humans are
+ in the room. Read the conversation and contribute meaningfully.
+- **Confirm before creating rooms.** Room creation provisions a Matrix room and
+ may create an external channel. Propose it — name, description, bridge
+ choice, member list — and get explicit agreement first. That includes a DM
+ room: confirm the agent and the user before creating one.
+
+## Formatting for bridged channels
+
+Your messages render on whatever platform the room is bridged to
+(`bridge_display_name` in `get_room_detail`), and the platforms differ:
+
+- **Slack** renders only a subset of Markdown (mrkdwn). Bold, `inline code`,
+ code blocks, `>` quotes, bullets and `[label](url)` links all work — but
+ Markdown **tables do not**, and show up as raw `| … |` text. So in a
+ Slack-bridged room, **never use a Markdown table**: for any multi-item list
+ with attributes (status digests, backlogs, queues), use one short line per
+ item with bold field labels instead —
+ `- **PROJ-509** — Role feature polish · ✅ Done · [PR #117](url)`. Lead with
+ the bold identifier and separate fields with `·` or `—`.
+- **Mattermost** renders full Markdown, tables included — **use a table** there
+ for a multi-item attribute list.
+
+When unsure, prefer the Slack-safe shape — it reads fine everywhere.
## If you see a `select_agent` tool
@@ -708,7 +620,7 @@ genuinely do not know which to pick, ask the operator rather than guessing: the
choice decides whose identity your messages and task updates are attributed to,
and it cannot be changed for the life of the session.
-You will not see this tool in an ordinary switchdash-managed session, which is
+You will not see this tool in an ordinary Switch Console-managed session, which is
launched with its identity already set.
## If `switch_unavailable` is your only tool
@@ -723,3 +635,57 @@ tool existing.
Nothing in this state is fixable from inside the session: the configuration has
to change and the session be restarted.
+
+## Tool index
+
+Every Switch tool you call in normal operation, one line each. The two
+failure-mode tools are covered in the sections just above.
+
+- `list_rooms` — rooms you are assigned to.
+- `connect_to_room` — enter a room. Once, then see steady state above.
+- `read_context` — room history, grouped into threads. Check `truncated`.
+- `list_participants` — the connected room's roster: `id`, `name`, `type`,
+ `status`, `alias`.
+- `post_message` — broadcast to the room.
+- `send_targeted_message` — broadcast addressed to names and/or roles.
+- `send_attachment` — post one or more files to the room.
+- `download_attachment` — fetch a file seen in history, by `mxc`.
+- `delegate_task` — hand tracked work to a performer.
+- `accept_task` — take a delegated task to `ongoing`.
+- `update_task` — record progress on a task you accepted.
+- `finalise_task` — close a task with its outcome.
+- `cancel_task` — abandon a task you delegated.
+- `list_tasks` — enumerate tasks by role and status.
+- `list_roles` — the room's assumable roles and who holds them.
+- `get_role_detail` — one role's full untruncated instructions.
+- `assume_role` — take a role and its instruction bundle.
+- `release_role` — drop the role you hold.
+- `define_role` — add a role to the connected room.
+- `edit_role` — change a role's instructions or exclusivity.
+- `delete_role` — remove a role and any lease on it.
+- `list_linked_rooms` — refresh this room's outbound pointers.
+- `list_all_rooms` — every room on the instance, not just yours.
+- `get_room_detail` — one room's members, channel type, roles, aliases.
+- `list_bridges` — the collaboration bridges available for new rooms.
+- `create_room` — provision a room. Confirm with the user first.
+- `update_room` — change an existing room, including its aliases.
+- `invite_agent_to_room` — add an agent to an existing room by name.
+- `list_references` — re-fetch the room's references, documents and packages.
+- `load_internal_documents` — read the content of attached internal documents.
+- `create_room_document` — author a document scoped to the connected room.
+- `update_room_document` — change a document you created.
+- `delete_room_document` — remove a document you created.
+- `add_users_to_room` — add human users to an existing room by name.
+- `archive_room` — archive a room you belong to.
+- `unarchive_room` — reverse an archive.
+- `list_room_groups` — the group tree rooms are organised into.
+- `get_room_group_detail` — one group's rooms and child groups.
+- `create_room_group` — provision a new room group.
+- `list_agents` — every agent on the instance, with optional filters.
+- `get_agent_detail` — one agent's config, capabilities and sessions.
+- `update_agent_detail` — change an agent you own.
+- `list_reference_types` — the Reference types and their value schemas.
+- `create_reference` — register an external Reference.
+- `attach_reference_to_room` — attach an existing Reference to a room.
+- `link_rooms` — add a directed pointer between two rooms.
+- `unlink_rooms` — remove one.
diff --git a/console/apps/switch-console-desktop/src/main/core/switch-rooms/room-connection.ts b/console/apps/switch-console-desktop/src/main/core/switch-rooms/room-connection.ts
index d223c0261..d0fb748c3 100644
--- a/console/apps/switch-console-desktop/src/main/core/switch-rooms/room-connection.ts
+++ b/console/apps/switch-console-desktop/src/main/core/switch-rooms/room-connection.ts
@@ -561,9 +561,14 @@ export class RoomConnection {
annotated = `${annotated}\n${annotation}`;
}
}
+ // The tally is cleared per delivered line, not per read: nothing here can
+ // observe the session calling read_context. So it counts what arrived since
+ // the previous line we surfaced, and the wording has to say that — an agent
+ // told "since your last read_context" would read the absence of a count as
+ // proof it was caught up, which this number cannot support.
let body =
this.missed > 0
- ? `${annotated}\n(${this.missed} unread room message${this.missed === 1 ? '' : 's'} since your last read_context — call read_context to catch up.)`
+ ? `${annotated}\n(${this.missed} unaddressed room message${this.missed === 1 ? '' : 's'} arrived since the previous message you were sent — call read_context to catch up.)`
: annotated;
this.missed = 0;
if (this.pendingGapReason !== null) {
diff --git a/console/packages/switch-agent-runtime/src/bin.instructions.test.ts b/console/packages/switch-agent-runtime/src/bin.instructions.test.ts
new file mode 100644
index 000000000..0d8e7068a
--- /dev/null
+++ b/console/packages/switch-agent-runtime/src/bin.instructions.test.ts
@@ -0,0 +1,59 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { describe, expect, it } from 'vitest';
+
+/**
+ * The MCP server's `instructions` are injected into every session that
+ * registers this runtime, and the model reads them as ground truth about the
+ * protocol. Nothing else pins their content.
+ *
+ * They used to tell the agent to `read_context` on every message event and to
+ * connect before every call, which made a session re-read a room it was
+ * already caught up on and reconnect to a room it was already in. That is a
+ * regression a future edit can reintroduce in one line, so these assert the
+ * shape of the guidance rather than its exact prose: conditional reading, and
+ * a connection that holds for the session.
+ *
+ * `bin.ts` is the process entry point — importing it opens a connection and
+ * starts an MCP server on stdio — so this reads the source, the same approach
+ * as `bin.gap.test.ts` and `bin.shebang.test.ts`.
+ */
+const SOURCE = readFileSync(join(import.meta.dirname, 'bin.ts'), 'utf8');
+
+/** The `instructions: [...]` array passed to the Server constructor. */
+function instructions(): string {
+ const start = SOURCE.indexOf('instructions: [');
+ expect(start).toBeGreaterThan(-1);
+ const end = SOURCE.indexOf("].join('\\n')", start);
+ expect(end).toBeGreaterThan(start);
+ return SOURCE.slice(start, end);
+}
+
+describe('MCP server instructions', () => {
+ it('makes reading conditional on being behind, not automatic per event', () => {
+ const text = instructions();
+ const step = text.split('\n').find((line) => line.includes('1. Call read_context'));
+ expect(step, 'the message-event procedure still opens with read_context').toBeDefined();
+ // The condition is the whole point: an unqualified "call read_context" here
+ // is the bug this file guards.
+ expect(step).toMatch(/ONLY if|only if/);
+ expect(step).toContain('missed_count');
+ });
+
+ it('describes the room connection as holding for the session', () => {
+ const text = instructions();
+ expect(text).toContain('do not reconnect before each call');
+ expect(text).not.toContain('You must be connected to the room (via connect_to_room) before');
+ });
+
+ it('does not tell the agent to read on every message event', () => {
+ // Phrasings that would restore the unconditional instruction.
+ for (const banned of [
+ 'Call read_context with the since parameter set to a timestamp a few minutes before the event timestamp to get recent',
+ 'always call read_context',
+ 'Always call read_context',
+ ]) {
+ expect(instructions()).not.toContain(banned);
+ }
+ });
+});
diff --git a/console/packages/switch-agent-runtime/src/bin.ts b/console/packages/switch-agent-runtime/src/bin.ts
index ac44e1c40..03f1d5075 100644
--- a/console/packages/switch-agent-runtime/src/bin.ts
+++ b/console/packages/switch-agent-runtime/src/bin.ts
@@ -468,7 +468,7 @@ const mcp = new Server(
'If a notification carries a gap warning (a `gap` entry in its meta, and a line saying earlier events were dropped), some room events could not be replayed — call read_context before responding rather than assuming you have the full picture. A gap never arrives as a notification of its own; it is attached to the next event you receive.',
'',
'When you receive a message event:',
- '1. Call read_context with the since parameter set to a timestamp a few minutes before the event timestamp to get recent conversation context without re-reading the full history.',
+ '1. Call read_context ONLY if you are missing context: missed_count is above 0, a gap warning arrived, the message joins a thread or discussion you have not been following, or a long time has passed since your last read. Set since to a few minutes before the event timestamp. When missed_count is 0 and you have been following the room, the event itself is enough — skip the read and answer.',
'2. Understand what is being asked or discussed.',
'3. Respond by calling post_message (or send_targeted_message if addressing a specific agent).',
'',
@@ -481,14 +481,14 @@ const mcp = new Server(
'',
'When you receive a task_delegate event (only delivered if your integration profile has can_accept=true):',
'1. Call accept_task with the task_id to move it to ongoing.',
- '2. Call read_context with since to understand the conversation context.',
+ '2. Call read_context with since if the task summary and description do not tell you enough about the surrounding conversation.',
'3. Perform the work described in the task. Optionally call update_task(task_id, update) with progress messages as you work — these are persisted.',
'4. Call finalise_task(task_id, outcome) with a one-string description of what happened (success or failure).',
'',
'When you receive task_accept, task_update, or task_finalise events for tasks you delegated, review the progress/outcome and continue your work accordingly.',
'When you receive a task_cancel event, the task is dead — do not finalise it.',
'',
- 'You must be connected to the room (via connect_to_room) before calling read_context, post_message, send_targeted_message, or any task tool.',
+ 'read_context, post_message, send_targeted_message and the task tools all act on the room you are connected to, so connect_to_room comes first — once. That connection then holds for the rest of the session: do not reconnect before each call. Call connect_to_room again only to switch rooms, to return after switching, or when a tool fails saying you are not connected.',
].join('\n'),
}
);
diff --git a/core/switch_core/bridges/agent/operations/definitions.py b/core/switch_core/bridges/agent/operations/definitions.py
index 389a3bbf9..41334b83e 100644
--- a/core/switch_core/bridges/agent/operations/definitions.py
+++ b/core/switch_core/bridges/agent/operations/definitions.py
@@ -571,9 +571,11 @@ async def read_context(
**`truncated` matters.** It is True when older history exists that this
call did not reach — you are looking at a partial conversation. Widen
- `limit`, or page backwards with `before` set to `oldest_timestamp`, before
- concluding you have the full picture. It is deliberately conservative: a
- read that ends exactly on `limit` reports truncated even if nothing older
+ `limit`, or page backwards with `before`, before concluding you have the
+ full picture. `oldest_timestamp` marks where to resume, but it is epoch
+ milliseconds while `before` is parsed as ISO-8601: convert it rather than
+ passing it straight back. `truncated` is deliberately conservative: a read
+ that ends exactly on `limit` reports truncated even if nothing older
exists.
`attachments` is a (usually empty) list of files on the message, each
diff --git a/core/tests/switch_core/bridges/agent/test_mcp_tool_surface.py b/core/tests/switch_core/bridges/agent/test_mcp_tool_surface.py
index 1c42f18d7..361aad9a5 100644
--- a/core/tests/switch_core/bridges/agent/test_mcp_tool_surface.py
+++ b/core/tests/switch_core/bridges/agent/test_mcp_tool_surface.py
@@ -89,42 +89,84 @@ SKILLS = sorted(
)
-def _frontmatter_tools(skill: Path) -> list[str]:
- """The tool names listed in a skill's frontmatter `description:` trigger.
+# Tools the agent runtime serves itself, so absent from the bridge's surface.
+# The skills index them alongside the bridge tools because an agent calls them
+# the same way, but they are registered by
+# `console/packages/switch-agent-runtime/`, not here — checking them against
+# this server's registrations would fail on tools that are working correctly.
+RUNTIME_TOOLS = {"send_attachment", "download_attachment"}
+
+# Served only when startup could not produce an identity, in place of the normal
+# surface, and documented in their own sections rather than the index.
+DEGRADED_TOOLS = {"select_agent", "switch_unavailable"}
+
+
+def _indexed_tools(skill: Path) -> list[str]:
+ """The tool names listed in a skill's `## Tool index` section.
+
+ One tool per bullet, opening with the backticked name. Read from the body
+ rather than the frontmatter: the `description:` is always-resident context
+ on both hosts (and Codex truncates it to fit a budget), so it carries a
+ trigger rather than an inventory.
+
+ Every bullet in the section must parse. A tool silently dropping out
+ because someone bolded it, indented it, or folded two onto one line is the
+ failure this whole file exists to prevent, so an unparseable bullet is an
+ error rather than a skipped line.
+ """
+ body = skill.read_text()
+ section = re.search(r"^## Tool index$(.*?)(?=^## |\Z)", body, re.MULTILINE | re.S)
+ assert section is not None, f"no '## Tool index' section in {skill}"
+ bullets = re.findall(r"^[ \t]*[-*].*$", section.group(1), re.MULTILINE)
+ assert bullets, f"no tool bullets under '## Tool index' in {skill}"
+ names = []
+ for bullet in bullets:
+ match = re.fullmatch(r"- `([a-z_]+)` — .*", bullet)
+ assert match is not None, (
+ f"{skill}: tool-index bullet is not `- \\`name\\` — description`, so "
+ f"the tool it names would not be checked: {bullet!r}"
+ )
+ names.append(match.group(1))
+ return names
+
+
+async def test_every_registered_tool_is_indexed(tool_names: set[str]) -> None:
+ """The index names every tool the bridge serves — no silent omissions.
- Both skills carry them as one parenthesised, comma-separated run — the
- first parenthetical in the file. Read rather than YAML-parsed so the
- unquoted (Claude) and quoted (Codex) forms are handled the same way.
+ The frontmatter list this replaced was one mechanical line; a prose bullet
+ list is easy to shorten by accident. Without this, deleting a bullet passes
+ every other check in the file: the drift test still sees two identical
+ indexes, and the registration test only ever objects to *extra* names.
"""
- match = re.search(
- r"^description:.*?\(([a-z_, ]+)\)", skill.read_text(), re.MULTILINE
- )
- assert match is not None, f"no parenthesised tool list in {skill}"
- return [name.strip() for name in match.group(1).split(",") if name.strip()]
+ for skill in SKILLS:
+ indexed = set(_indexed_tools(skill))
+ missing = tool_names - indexed - DEGRADED_TOOLS
+ assert not missing, (
+ f"{skill} does not index registered tools: {sorted(missing)}"
+ )
-def test_both_skills_advertise_the_same_tools() -> None:
- """The two connectors' trigger lists must not drift apart.
+def test_both_skills_index_the_same_tools() -> None:
+ """The two connectors' tool indexes must not drift apart.
They are host-specific documents but the tool surface behind them is one
- surface, and a tool added to one skill's trigger is silently absent from
- the other's.
+ surface, and a tool added to one skill's index is silently absent from the
+ other's.
"""
assert len(SKILLS) == 2, f"expected two connector skills, found {SKILLS}"
- first, second = (_frontmatter_tools(skill) for skill in SKILLS)
+ first, second = (_indexed_tools(skill) for skill in SKILLS)
assert first == second
-async def test_skill_frontmatter_tools_are_registered(tool_names: set[str]) -> None:
- """Every tool named in a skill's trigger list actually exists.
+async def test_skill_indexed_tools_are_registered(tool_names: set[str]) -> None:
+ """Every tool a skill's index advertises actually exists.
Derived from the files rather than restated here, so this half cannot go
stale the way the hand-maintained set above can. It does not replace that
- set: the skills also name tools in their bodies (`list_linked_rooms`,
- `update_room`) that never appear in the trigger.
+ set: that one pins names this test would accept being dropped entirely.
"""
for skill in SKILLS:
- advertised = set(_frontmatter_tools(skill))
+ advertised = set(_indexed_tools(skill)) - RUNTIME_TOOLS
assert advertised <= tool_names, (
f"{skill} advertises unregistered tools: {sorted(advertised - tool_names)}"
)