Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.
Python agent-orchestrationaiai-agentschatopsdiscordlangchainmcpmicrosoft-teamsmulti-agentopen-sourceopenaiself-hostedslack
fix(connectors): make the room-workflow skills state-aware (#186)
Christian McDermott27a2a0e9b598
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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#### Changeddiff --git a/connectors/claude-code-plugin/hooks/hooks.json b/connectors/claude-code-plugin/hooks/hooks.jsonindex 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.mdindex 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 thebridge 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 idsor 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 instructionbundle. 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 yoursession 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 mayhold 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: thechoice 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 islaunched 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 hasto 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.mdindex 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 thebridge 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 idsor 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 instructionbundle. 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 yoursession 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 mayhold 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: thechoice 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 islaunched 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 hasto 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.pyindex 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 thiscall 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 olderexists.`attachments` is a (usually empty) list of files on the message, eachdiff --git a/core/tests/switch_core/bridges/agent/test_mcp_tool_surface.py b/core/tests/switch_core/bridges/agent/test_mcp_tool_surface.pyindex 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 gostale 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_TOOLSassert advertised <= tool_names, (f"{skill} advertises unregistered tools: {sorted(advertised - tool_names)}")