Skip to content

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

docs(connectors): stop documenting the task protocol in the skills (CHOO-1418) (#244)

Louis Amaudruz7dd98e4bab27
diff --git a/CLAUDE.md b/CLAUDE.md
index 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, runtime
package, 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 confirm
every remaining difference is intentional rather than a fix that only landed
on 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.md
index 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 changes
or 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 same
thread.
@@ -81,8 +78,8 @@ 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.
+ `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 the
triggers below.
@@ -98,9 +95,9 @@ 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` /
+**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 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.
@@ -123,11 +120,9 @@ Two fields tell you when that matters:
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.
+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 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 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 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.
+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 channel
cannot 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; summarise
locally afterwards if useful. Staying terminal-only is right only when the
local 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 with
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. 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 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
+ 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 handles
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.
+ `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 you
will 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 you
genuinely do not know which to pick, ask the operator rather than guessing: the
-choice decides whose identity your messages and task updates are attributed to,
-and it cannot be changed for the life of the session.
+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 is
launched 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.md
index 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 changes
or 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 same
thread.
@@ -84,8 +81,8 @@ 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.
+ `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 the
triggers 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 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
@@ -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 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 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 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.
+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 channel
cannot 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; summarise
locally afterwards if useful. Staying terminal-only is right only when the
local 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 with
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. 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 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.
+ 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 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.
+ `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 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
@@ -695,8 +676,8 @@ refusal names the candidates.
Call `select_agent` once with the name you are, then carry on as normal. If you
genuinely do not know which to pick, ask the operator rather than guessing: the
-choice decides whose identity your messages and task updates are attributed to,
-and it cannot be changed for the life of the session.
+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 is
launched 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.md
index 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 changes
or 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 same
thread.
@@ -92,8 +89,8 @@ 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.
+ `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 the
triggers 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 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
@@ -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 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 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 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.
+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 channel
cannot 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; summarise
locally afterwards if useful. Staying terminal-only is right only when the
local 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 with
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. 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 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
- ("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 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.
+ `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 is
a Claude Code connector feature; an OpenCode session has no such hook, so your
shell 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 you
genuinely do not know which to pick, ask the operator rather than guessing: the
-choice decides whose identity your messages and task updates are attributed to,
-and it cannot be changed for the life of the session.
+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 is
launched 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.ts
index 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 changes
or 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 same
thread.
@@ -100,8 +97,8 @@ 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.
+ \`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 the
triggers 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 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
@@ -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 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 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 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.
+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 channel
cannot 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; summarise
locally afterwards if useful. Staying terminal-only is right only when the
local 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 with
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. 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 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
- ("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 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.
+ \`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 is
a Claude Code connector feature; an OpenCode session has no such hook, so your
shell 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 you
genuinely do not know which to pick, ask the operator rather than guessing: the
-choice decides whose identity your messages and task updates are attributed to,
-and it cannot be changed for the life of the session.
+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 is
launched 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.py
index 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 here
when 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 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.
+
+ `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_TOOLS
assert 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.