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
docs(connectors): stop documenting the task protocol in the skills (CHOO-1418) (#244)
Louis Amaudruz7dd98e4bab27
diff --git a/CLAUDE.md b/CLAUDE.mdindex f062281f9..c9dc6d36e 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -181,8 +181,8 @@ commands, room workflow, or anything an agent-facing client needs to know:can trust. `console/AGENTS.md` has the table (all three plugins, runtimepackage, sidecar) and the rules for which digit moves.- **Diff the skills against each other after editing.** They are deliberately not identical- (host-specific wording for tool namespacing, event delivery and task- notifications, attachments, and MCP registration), so diff them to confirm+ (host-specific wording for tool namespacing, event delivery, attachments, and+ MCP registration), so diff them to confirmevery remaining difference is intentional rather than a fix that only landedon one side.- **Publishing the runtime is a tag**, not a merge:diff --git a/connectors/claude-code-plugin/skills/switch/SKILL.md b/connectors/claude-code-plugin/skills/switch/SKILL.mdindex 6d87afdf5..924cc938c 100644--- a/connectors/claude-code-plugin/skills/switch/SKILL.md+++ b/connectors/claude-code-plugin/skills/switch/SKILL.md@@ -1,6 +1,6 @@---name: switch-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.+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, room roles and the moderation tools.---# Switch Room Workflow@@ -44,9 +44,6 @@ then post the result.pad it with a plan.- Acknowledge once. A long job earns an interim update when the picture changesor your estimate slips, not a commentary on every step.-- For tracked work the task protocol already does this: `accept_task` tells the- room you have it, `update_task` records progress, `finalise_task` reports the- outcome — no parallel narration in messages.- The heads-up is not the answer. Always come back with the result, in the samethread.@@ -81,8 +78,8 @@ After `connect_to_room` succeeds you stay connected for the rest of thesession. 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.+ `send_targeted_message`, `read_context` and `list_participants` 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 thetriggers below.@@ -98,9 +95,9 @@ Events arrive on their own as `<channel>` notifications — no polling tool tocall. If the connection drops it reconnects and resumes, so a brief blipcosts 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` /+**Delivered:** messages addressed to you 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 arrivalsalso show up in `list_participants`. Your own join never produces one. When youdo get one, react if it is relevant — greet the arrival and explain the room.@@ -123,11 +120,9 @@ Two fields tell you when that matters:launched shares its connection, so each event is delivered into your sessionas 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.+parenthetical naming local paths. 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@@ -180,17 +175,15 @@ this room" from a truncated read.least one of the two, plus a `body`). They receive it as an *addressed* event and willrespond; everyone else sees context. Use when you need someone specific toact 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 when the outcome matters and-you may want to check on it later.+synchronous response.**Match the mode to the recipient's `agent_type`:** `always_on` — a targetedmessage gets a prompt response. `session_addressable` — works while the agenthas 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.+expect a synchronous reply; it picks up what it missed when it next reads+room context.**Reply in the room, not just in the terminal.** Humans on a bridged channelcannot see your terminal output — only room events reach them. When a room@@ -198,6 +191,20 @@ message asks you something, the answer goes to the room first; summariselocally afterwards if useful. Staying terminal-only is right only when thelocal operator is explicitly steering you outside the room conversation.+## Scoped addressing policy++An agent may have a **scoped addressing policy** limiting who can address it.+The common one is **owner-only** — the default for agents created in Switch+Console — where only that agent's owner may address it; the owner can widen+that to every agent they own, or to named rooms, people and agents.++**Messages are not blocked.** `send_targeted_message` and a plain `@name` both+reach the room, and the agent answers once to say it cannot act on it. What+you get back from `send_targeted_message` is `not_permitted` in that agent's+`target_statuses` instead of a reachability value — read its reply rather+than sending again. Commands are covered too, so `!reset` on a restricted+agent is declined the same way.+## Threads`post_message` and `send_targeted_message` both take an optional `thread_id`:@@ -283,37 +290,18 @@ one message. Returns the posted `event_id`. Download withIf those variables are absent too, do not fabricate an upload or claim anattachment 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. Watch for `task_update` and `task_finalise`- events. `cancel_task(task_id, reason)` abandons it.-- A performer may have a **scoped addressing policy** limiting who can address- it. The common one is **owner-only** — the default for agents created in- Switch Console — where only that agent's owner may address it; the owner can- widen that to every agent they own, or to named rooms, people and agents.- If you are not permitted, **`delegate_task` fails** with a permission error:- a task is work someone is expected to pick up, so it is refused at the point- of asking. Expected; do not retry — reach the performer another way, or ask- an operator to allow you.- **Messages are not blocked.** `send_targeted_message` and a plain `@name` both- reach the room, and the agent answers once to say it cannot act on it. What- you get back from `send_targeted_message` is `not_permitted` in that agent's- `target_statuses` instead of a reachability value — read its reply rather- than sending again. Commands are covered too, so `!reset` on a restricted- agent is declined the same way.-- **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.+## Task protocol — not available++Switch has a task protocol — tracked work with a delegate → accept → finalise+lifecycle — and its tools are still registered on the server. **It is not+ready to be used.** Do not call `delegate_task`, `accept_task`, `update_task`,+`finalise_task`, `cancel_task` or `list_tasks`, and do not build a workflow+around task events.++Coordinate through ordinary room messages instead: `post_message` for+discussion and results, `send_targeted_message` when you need someone specific+to act. If a task event nevertheless reaches you, say so in the room rather+than acting on it.## Linked rooms@@ -631,17 +619,15 @@ are moderation tools — use them when setting a room up, not in passing.- **No stray `@-mentions` in free-text fields.** Switch re-parses thesestrings 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+ applies to every free-text field you author, `post_message(body)` above all.+ Write the bare name instead ("claude-code.test-claude posted the greeting").+ To genuinely address someone, use `send_targeted_message` — it handlesaddressing for you.- **An active room connection is required** — being a member of a room is notthe 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.+ `post_message` and `send_targeted_message` 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 youwill see the reason. Do not try to circumvent denials.@@ -689,8 +675,8 @@ refusal names the candidates.Call `select_agent` once with the name you are, then carry on as normal. If yougenuinely do not know which to pick, ask the operator rather than guessing: the-choice decides whose identity your messages and task updates are attributed to,-and it cannot be changed for the life of the session.+choice decides whose identity your messages are attributed to, and it cannot+be changed for the life of the session.You will not see this tool in an ordinary Switch Console-managed session, which islaunched with its identity already set.@@ -722,12 +708,6 @@ failure-mode tools are covered in the sections just above.- `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.diff --git a/connectors/codex-plugin/skills/switch/SKILL.md b/connectors/codex-plugin/skills/switch/SKILL.mdindex 7fb62817b..c748e898b 100644--- a/connectors/codex-plugin/skills/switch/SKILL.md+++ b/connectors/codex-plugin/skills/switch/SKILL.md@@ -1,6 +1,6 @@---name: "switch"-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."+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, room roles and the moderation tools."---# Switch Room Workflow@@ -47,9 +47,6 @@ then post the result.pad it with a plan.- Acknowledge once. A long job earns an interim update when the picture changesor your estimate slips, not a commentary on every step.-- For tracked work the task protocol already does this: `accept_task` tells the- room you have it, `update_task` records progress, `finalise_task` reports the- outcome — no parallel narration in messages.- The heads-up is not the answer. Always come back with the result, in the samethread.@@ -84,8 +81,8 @@ After `connect_to_room` succeeds you stay connected for the rest of thesession. 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.+ `send_targeted_message`, `read_context` and `list_participants` 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 thetriggers below.@@ -109,9 +106,6 @@ only source — say so rather than waiting for a line that will never come.- **Messages addressed to you** — `[Switch] <sender> addressed you in room<room> (message_id …[, thread_id …]): <body>`, followed by a parentheticalnaming 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 roomswhere an operator opted you in (per-room, per-agent, off by default — set viathe `join_event_listeners` argument on `create_room` / `update_room`, or the@@ -184,17 +178,15 @@ this room" from a truncated read.least one of the two, plus a `body`). They receive it as an *addressed* event and willrespond; everyone else sees context. Use when you need someone specific toact 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 when the outcome matters and-you may want to check on it later.+synchronous response.**Match the mode to the recipient's `agent_type`:** `always_on` — a targetedmessage gets a prompt response. `session_addressable` — works while the agenthas 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.+expect a synchronous reply; it picks up what it missed when it next reads+room context.**Reply in the room, not just in the terminal.** Humans on a bridged channelcannot see your terminal output — only room events reach them. When a room@@ -202,6 +194,20 @@ message asks you something, the answer goes to the room first; summariselocally afterwards if useful. Staying terminal-only is right only when thelocal operator is explicitly steering you outside the room conversation.+## Scoped addressing policy++An agent may have a **scoped addressing policy** limiting who can address it.+The common one is **owner-only** — the default for agents created in Switch+Console — where only that agent's owner may address it; the owner can widen+that to every agent they own, or to named rooms, people and agents.++**Messages are not blocked.** `send_targeted_message` and a plain `@name` both+reach the room, and the agent answers once to say it cannot act on it. What+you get back from `send_targeted_message` is `not_permitted` in that agent's+`target_statuses` instead of a reachability value — read its reply rather+than sending again. Commands are covered too, so `!reset` on a restricted+agent is declined the same way.+## Threads`post_message` and `send_targeted_message` both take an optional `thread_id`:@@ -282,42 +288,18 @@ one message. Returns the posted `event_id`. Download withIf those variables are absent too, do not fabricate an upload or claim anattachment 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. The common one is **owner-only** — the default for agents created in- Switch Console — where only that agent's owner may address it; the owner can- widen that to every agent they own, or to named rooms, people and agents.- If you are not permitted, **`delegate_task` fails** with a permission error:- a task is work someone is expected to pick up, so it is refused at the point- of asking. Expected; do not retry — reach the performer another way, or ask- an operator to allow you.- **Messages are not blocked.** `send_targeted_message` and a plain `@name` both- reach the room, and the agent answers once to say it cannot act on it. What- you get back from `send_targeted_message` is `not_permitted` in that agent's- `target_statuses` instead of a reachability value — read its reply rather- than sending again. Commands are covered too, so `!reset` on a restricted- agent is declined the same way.-- **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.+## Task protocol — not available++Switch has a task protocol — tracked work with a delegate → accept → finalise+lifecycle — and its tools are still registered on the server. **It is not+ready to be used.** Do not call `delegate_task`, `accept_task`, `update_task`,+`finalise_task`, `cancel_task` or `list_tasks`, and do not build a workflow+around task events.++Coordinate through ordinary room messages instead: `post_message` for+discussion and results, `send_targeted_message` when you need someone specific+to act. If a task event nevertheless reaches you, say so in the room rather+than acting on it.## Linked rooms@@ -635,16 +617,15 @@ are moderation tools — use them when setting a room up, not in passing.- **No stray `@-mentions` in free-text fields.** Switch re-parses thesestrings 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.+ applies to every free-text field you author, `post_message(body)` above all.+ Write the bare name instead ("codex.test-codex posted the greeting"). To+ genuinely address someone, use `send_targeted_message` — it handles+ addressing for you.- **An active room connection is required** — being a member of a room is notthe 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.+ `post_message` and `send_targeted_message` 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 isa Claude Code connector feature; a Codex session has no such hook, so yourshell commands and edits are gated by the operator's approval settings alone@@ -695,8 +676,8 @@ refusal names the candidates.Call `select_agent` once with the name you are, then carry on as normal. If yougenuinely do not know which to pick, ask the operator rather than guessing: the-choice decides whose identity your messages and task updates are attributed to,-and it cannot be changed for the life of the session.+choice decides whose identity your messages are attributed to, and it cannot+be changed for the life of the session.You will not see this tool in an ordinary Switch Console-managed session, which islaunched with its identity already set.@@ -728,12 +709,6 @@ failure-mode tools are covered in the sections just above.- `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.diff --git a/connectors/opencode-plugin/skills/switch/SKILL.md b/connectors/opencode-plugin/skills/switch/SKILL.mdindex 98f5f0b18..6b18ee2e4 100644--- a/connectors/opencode-plugin/skills/switch/SKILL.md+++ b/connectors/opencode-plugin/skills/switch/SKILL.md@@ -1,6 +1,6 @@---name: "switch"-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."+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, room roles and the moderation tools."---# Switch Room Workflow@@ -55,9 +55,6 @@ then post the result.pad it with a plan.- Acknowledge once. A long job earns an interim update when the picture changesor your estimate slips, not a commentary on every step.-- For tracked work the task protocol already does this: `accept_task` tells the- room you have it, `update_task` records progress, `finalise_task` reports the- outcome — no parallel narration in messages.- The heads-up is not the answer. Always come back with the result, in the samethread.@@ -92,8 +89,8 @@ After `connect_to_room` succeeds you stay connected for the rest of thesession. 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.+ `send_targeted_message`, `read_context` and `list_participants` 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 thetriggers below.@@ -117,9 +114,6 @@ only source — say so rather than waiting for a line that will never come.- **Messages addressed to you** — `[Switch] <sender> addressed you in room<room> (message_id …[, thread_id …]): <body>`, followed by a parentheticalnaming 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 roomswhere an operator opted you in (per-room, per-agent, off by default — set viathe `join_event_listeners` argument on `create_room` / `update_room`, or the@@ -192,17 +186,15 @@ this room" from a truncated read.least one of the two, plus a `body`). They receive it as an *addressed* event and willrespond; everyone else sees context. Use when you need someone specific toact 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 when the outcome matters and-you may want to check on it later.+synchronous response.**Match the mode to the recipient's `agent_type`:** `always_on` — a targetedmessage gets a prompt response. `session_addressable` — works while the agenthas 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.+expect a synchronous reply; it picks up what it missed when it next reads+room context.**Reply in the room, not just in the terminal.** Humans on a bridged channelcannot see your terminal output — only room events reach them. When a room@@ -210,6 +202,20 @@ message asks you something, the answer goes to the room first; summariselocally afterwards if useful. Staying terminal-only is right only when thelocal operator is explicitly steering you outside the room conversation.+## Scoped addressing policy++An agent may have a **scoped addressing policy** limiting who can address it.+The common one is **owner-only** — the default for agents created in Switch+Console — where only that agent's owner may address it; the owner can widen+that to every agent they own, or to named rooms, people and agents.++**Messages are not blocked.** `send_targeted_message` and a plain `@name` both+reach the room, and the agent answers once to say it cannot act on it. What+you get back from `send_targeted_message` is `not_permitted` in that agent's+`target_statuses` instead of a reachability value — read its reply rather+than sending again. Commands are covered too, so `!reset` on a restricted+agent is declined the same way.+## Threads`post_message` and `send_targeted_message` both take an optional `thread_id`:@@ -290,42 +296,18 @@ one message. Returns the posted `event_id`. Download withIf those variables are absent too, do not fabricate an upload or claim anattachment 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. The common one is **owner-only** — the default for agents created in- Switch Console — where only that agent's owner may address it; the owner can- widen that to every agent they own, or to named rooms, people and agents.- If you are not permitted, **`delegate_task` fails** with a permission error:- a task is work someone is expected to pick up, so it is refused at the point- of asking. Expected; do not retry — reach the performer another way, or ask- an operator to allow you.- **Messages are not blocked.** `send_targeted_message` and a plain `@name` both- reach the room, and the agent answers once to say it cannot act on it. What- you get back from `send_targeted_message` is `not_permitted` in that agent's- `target_statuses` instead of a reachability value — read its reply rather- than sending again. Commands are covered too, so `!reset` on a restricted- agent is declined the same way.-- **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.+## Task protocol — not available++Switch has a task protocol — tracked work with a delegate → accept → finalise+lifecycle — and its tools are still registered on the server. **It is not+ready to be used.** Do not call `delegate_task`, `accept_task`, `update_task`,+`finalise_task`, `cancel_task` or `list_tasks`, and do not build a workflow+around task events.++Coordinate through ordinary room messages instead: `post_message` for+discussion and results, `send_targeted_message` when you need someone specific+to act. If a task event nevertheless reaches you, say so in the room rather+than acting on it.## Linked rooms@@ -643,17 +625,15 @@ are moderation tools — use them when setting a room up, not in passing.- **No stray `@-mentions` in free-text fields.** Switch re-parses thesestrings 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- ("opencode.test-opencode posted the greeting"). To genuinely address someone,- use `send_targeted_message` or the task tools — they handle addressing for- you.+ applies to every free-text field you author, `post_message(body)` above all.+ Write the bare name instead ("opencode.test-opencode posted the greeting").+ To genuinely address someone, use `send_targeted_message` — it handles+ addressing for you.- **An active room connection is required** — being a member of a room is notthe 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.+ `post_message` and `send_targeted_message` 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 isa Claude Code connector feature; an OpenCode session has no such hook, so yourshell commands and edits are gated by OpenCode's own permission settings alone@@ -704,8 +684,8 @@ refusal names the candidates.Call `select_agent` once with the name you are, then carry on as normal. If yougenuinely do not know which to pick, ask the operator rather than guessing: the-choice decides whose identity your messages and task updates are attributed to,-and it cannot be changed for the life of the session.+choice decides whose identity your messages are attributed to, and it cannot+be changed for the life of the session.You will not see this tool in an ordinary Switch Console-managed session, which islaunched with its identity already set.@@ -737,12 +717,6 @@ failure-mode tools are covered in the sections just above.- `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.diff --git a/console/packages/plugins/src/agents/impl/opencode/skill-file.ts b/console/packages/plugins/src/agents/impl/opencode/skill-file.tsindex 5b366a755..d440d8ca3 100644--- a/console/packages/plugins/src/agents/impl/opencode/skill-file.ts+++ b/console/packages/plugins/src/agents/impl/opencode/skill-file.ts@@ -8,7 +8,7 @@export const OPENCODE_SKILL_CONTENT = `\---name: "switch"-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."+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, room roles and the moderation tools."---# Switch Room Workflow@@ -63,9 +63,6 @@ then post the result.pad it with a plan.- Acknowledge once. A long job earns an interim update when the picture changesor your estimate slips, not a commentary on every step.-- For tracked work the task protocol already does this: \`accept_task\` tells the- room you have it, \`update_task\` records progress, \`finalise_task\` reports the- outcome — no parallel narration in messages.- The heads-up is not the answer. Always come back with the result, in the samethread.@@ -100,8 +97,8 @@ After \`connect_to_room\` succeeds you stay connected for the rest of thesession. 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.+ \`send_targeted_message\`, \`read_context\` and \`list_participants\` 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 thetriggers below.@@ -125,9 +122,6 @@ only source — say so rather than waiting for a line that will never come.- **Messages addressed to you** — \`[Switch] <sender> addressed you in room<room> (message_id …[, thread_id …]): <body>\`, followed by a parentheticalnaming 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 roomswhere an operator opted you in (per-room, per-agent, off by default — set viathe \`join_event_listeners\` argument on \`create_room\` / \`update_room\`, or the@@ -200,17 +194,15 @@ this room" from a truncated read.least one of the two, plus a \`body\`). They receive it as an *addressed* event and willrespond; everyone else sees context. Use when you need someone specific toact 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 when the outcome matters and-you may want to check on it later.+synchronous response.**Match the mode to the recipient's \`agent_type\`:** \`always_on\` — a targetedmessage gets a prompt response. \`session_addressable\` — works while the agenthas 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.+expect a synchronous reply; it picks up what it missed when it next reads+room context.**Reply in the room, not just in the terminal.** Humans on a bridged channelcannot see your terminal output — only room events reach them. When a room@@ -218,6 +210,20 @@ message asks you something, the answer goes to the room first; summariselocally afterwards if useful. Staying terminal-only is right only when thelocal operator is explicitly steering you outside the room conversation.+## Scoped addressing policy++An agent may have a **scoped addressing policy** limiting who can address it.+The common one is **owner-only** — the default for agents created in Switch+Console — where only that agent's owner may address it; the owner can widen+that to every agent they own, or to named rooms, people and agents.++**Messages are not blocked.** \`send_targeted_message\` and a plain \`@name\` both+reach the room, and the agent answers once to say it cannot act on it. What+you get back from \`send_targeted_message\` is \`not_permitted\` in that agent's+\`target_statuses\` instead of a reachability value — read its reply rather+than sending again. Commands are covered too, so \`!reset\` on a restricted+agent is declined the same way.+## Threads\`post_message\` and \`send_targeted_message\` both take an optional \`thread_id\`:@@ -298,42 +304,18 @@ one message. Returns the posted \`event_id\`. Download withIf those variables are absent too, do not fabricate an upload or claim anattachment 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. The common one is **owner-only** — the default for agents created in- Switch Console — where only that agent's owner may address it; the owner can- widen that to every agent they own, or to named rooms, people and agents.- If you are not permitted, **\`delegate_task\` fails** with a permission error:- a task is work someone is expected to pick up, so it is refused at the point- of asking. Expected; do not retry — reach the performer another way, or ask- an operator to allow you.- **Messages are not blocked.** \`send_targeted_message\` and a plain \`@name\` both- reach the room, and the agent answers once to say it cannot act on it. What- you get back from \`send_targeted_message\` is \`not_permitted\` in that agent's- \`target_statuses\` instead of a reachability value — read its reply rather- than sending again. Commands are covered too, so \`!reset\` on a restricted- agent is declined the same way.-- **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.+## Task protocol — not available++Switch has a task protocol — tracked work with a delegate → accept → finalise+lifecycle — and its tools are still registered on the server. **It is not+ready to be used.** Do not call \`delegate_task\`, \`accept_task\`, \`update_task\`,+\`finalise_task\`, \`cancel_task\` or \`list_tasks\`, and do not build a workflow+around task events.++Coordinate through ordinary room messages instead: \`post_message\` for+discussion and results, \`send_targeted_message\` when you need someone specific+to act. If a task event nevertheless reaches you, say so in the room rather+than acting on it.## Linked rooms@@ -651,17 +633,15 @@ are moderation tools — use them when setting a room up, not in passing.- **No stray \`@-mentions\` in free-text fields.** Switch re-parses thesestrings 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- ("opencode.test-opencode posted the greeting"). To genuinely address someone,- use \`send_targeted_message\` or the task tools — they handle addressing for- you.+ applies to every free-text field you author, \`post_message(body)\` above all.+ Write the bare name instead ("opencode.test-opencode posted the greeting").+ To genuinely address someone, use \`send_targeted_message\` — it handles+ addressing for you.- **An active room connection is required** — being a member of a room is notthe 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.+ \`post_message\` and \`send_targeted_message\` 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 isa Claude Code connector feature; an OpenCode session has no such hook, so yourshell commands and edits are gated by OpenCode's own permission settings alone@@ -712,8 +692,8 @@ refusal names the candidates.Call \`select_agent\` once with the name you are, then carry on as normal. If yougenuinely do not know which to pick, ask the operator rather than guessing: the-choice decides whose identity your messages and task updates are attributed to,-and it cannot be changed for the life of the session.+choice decides whose identity your messages are attributed to, and it cannot+be changed for the life of the session.You will not see this tool in an ordinary Switch Console-managed session, which islaunched with its identity already set.@@ -745,12 +725,6 @@ failure-mode tools are covered in the sections just above.- \`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.diff --git a/core/tests/switch_core/bridges/agent/test_mcp_tool_surface.py b/core/tests/switch_core/bridges/agent/test_mcp_tool_surface.pyindex f6b638e53..e72182bec 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@@ -30,10 +30,12 @@ async def tool_names() -> set[str]:async def test_task_protocol_is_fully_exposed(tool_names: set[str]) -> None:- """Every stage of the documented task lifecycle is callable over MCP.+ """Every stage of the task lifecycle is still callable over MCP.- `cancel_task` is the requester's abort path: without it the lifecycle the- skills describe has no exit for the agent that opened it.+ The skills no longer document the protocol — it is not ready for use — but+ the tools remain registered, and a half-present lifecycle is worse than+ either a whole one or none. `cancel_task` in particular is the requester's+ abort path: without it an opened task has no exit."""assert TASK_PROTOCOL_TOOLS <= tool_names@@ -45,7 +47,7 @@ async def test_documented_tools_exist(tool_names: set[str]) -> None:including those named only in the body. Maintained by hand: add a name herewhen a skill starts advertising one."""- documented = TASK_PROTOCOL_TOOLS | {+ documented = {"list_rooms","connect_to_room","read_context",@@ -100,6 +102,13 @@ RUNTIME_TOOLS = {"send_attachment", "download_attachment"}# surface, and documented in their own sections rather than the index.DEGRADED_TOOLS = {"select_agent", "switch_unavailable"}+# Registered, and deliberately kept out of the skills. The task protocol is not+# ready to be used, so each skill carries a section telling agents not to call+# these rather than a workflow that exercises them. The tools stay on the server+# — nothing here removes them — and this set is what keeps that gap deliberate:+# empty it when the protocol is either documented again or taken off the server.+UNDOCUMENTED_TOOLS = TASK_PROTOCOL_TOOLS+def _indexed_tools(skill: Path) -> list[str]:"""The tool names listed in a skill's `## Tool index` section.@@ -137,15 +146,34 @@ async def test_every_registered_tool_is_indexed(tool_names: set[str]) -> None:list is easy to shorten by accident. Without this, deleting a bullet passesevery other check in the file: the drift test still sees two identicalindexes, and the registration test only ever objects to *extra* names.++ `UNDOCUMENTED_TOOLS` is the one sanctioned way past this: a tool leaves the+ index by being named there, not by a bullet quietly going missing."""for skill in SKILLS:indexed = set(_indexed_tools(skill))- missing = tool_names - indexed - DEGRADED_TOOLS+ missing = tool_names - indexed - DEGRADED_TOOLS - UNDOCUMENTED_TOOLSassert not missing, (f"{skill} does not index registered tools: {sorted(missing)}")+async def test_undocumented_tools_are_disclaimed() -> None:+ """A tool kept out of the index is named as off-limits, not just omitted.++ Silence would read as the tool not existing, and an agent that meets one in+ an event or an error message has nothing to go on. Every skill has to spell+ out that these are registered and must not be called.+ """+ for skill in SKILLS:+ body = skill.read_text()+ unmentioned = {tool for tool in UNDOCUMENTED_TOOLS if f"`{tool}`" not in body}+ assert not unmentioned, (+ f"{skill} drops registered tools without saying they are off-limits: "+ f"{sorted(unmentioned)}"+ )++def test_every_connector_ships_a_skill() -> None:"""Each connector documents the room workflow for its own host.