Sessions and Threads

In Zooid, a single Matrix thread maps directly to an ongoing ACP session. Every continuous conversation you have with an agent occurs within a thread.

This is a departure from a standard linear chat room. In Zooid, the Matrix thread root serves as the stable identity for an agent’s memory. Every event that belongs to the conversation — the user’s prompt, the agent’s replies, approval cards, and tool-call events — attaches to that thread root.

Creating a Thread

A thread (and therefore a session) is created in one of four ways:

Agent-promotion (Default): You send a regular, top-level message mentioning an agent (e.g., @architect let's build a feature). When the agent replies, it automatically attaches a thread relation referencing your message. Your prompt retroactively becomes the thread root, and all subsequent replies stay in this thread.
User-promotion (Explicit): You click Reply in thread on an existing top-level message in the Zooid web client before the agent replies. The first message sent in that thread mode creates the thread.
A trigger fires. A cron schedule or an incoming webhook posts a top-level message mentioning an agent, which promotes exactly like a human’s. A daily trigger therefore gets a fresh session every day, with no session code of its own.
An agent hands off work. A delegating agent opens one new thread per task, each with its own session and a named assignee — see Handoffs below.

Implicit Triggers

In a standard room, agents require an explicit @ mention to respond. However, threads are designed for ongoing collaboration. Zooid implements a thread-aware trigger rule:

Once an agent has posted in a thread, or if the agent was explicitly @ mentioned in the thread root, it becomes the implicit addressee.
You can simply send a bare reply (e.g., “now do the next file”) in the thread, and the agent will respond without needing to be @ mentioned again.
If you @ mention a different agent in the same thread, the new agent will take over the context and become the implicit addressee for future bare replies.

Mentions are how people address agents. When an agent writes another agent’s name — in a status update, a summary, a quoted instruction — nobody gets woken up. Agents bring each other in on purpose, with a handoff.

Handoffs

Agents pass work to each other, and both ways of doing it are just threads.

The simple one: hand off within the thread. The agent asks one teammate to take a look, right where everyone is already reading. The teammate picks it up in the same thread, does the work, and when it’s done the original agent is woken with the answer and carries on. One agent, one question, one place — good for “have a look at this and tell me what you think”.

Because a handoff is a deliberate act rather than a side effect of typing a name, agents can talk about each other freely without accidentally setting each other off, and every handoff comes back exactly once, when the work is actually finished — not halfway through, and not never. It works the same whether the teammate runs on the same machine or on another workstation in the workforce.

The other is a task thread. Instead of pulling someone into the current conversation, the agent hands out work that opens its own thread in the same room, addressed to the agent that will do it. It can hand out several at once, so three audits run side by side instead of one after another, and each gets a clean conversation people can follow without the other two interleaved.

A task thread is an ordinary thread with two additions: Zooid knows whose task it is, and it knows when the task is finished. When it is, the result goes back to the agent that asked — or just stays in the thread, if the agent asked for it that way (“go do this and tell the channel” is a perfectly good instruction here, and it has no equivalent in a coding CLI, where the caller is the only audience).

Everything else about it is unremarkable, which is the point. You can read a task thread while it runs, reply into it to redirect the agent, @ mention another agent to bring them in yourself, or /clear it. A colleague who wasn’t in the original conversation can open the room and see all of it.

The tools behind it

Agents hand off through tools that Zooid gives every agent over its built-in Zooid MCP server — nothing to install or configure:

zooid_handoff brings one teammate into the current thread and wakes the agent that asked when the answer is in.
zooid_start_task_threads hands out one or more tasks, each in its own thread.
zooid_complete_task lets an agent working on a task record its result explicitly (optional — otherwise its last message is the result).

Refer to them by name in your agents’ instructions (“hand off with zooid_handoff”) so each agent knows exactly how to reach its teammates. The Zooid MCP reference covers each tool and when it’s available.

Which one to use

	In-thread handoff	Task thread
How it starts	an agent calls `zooid_handoff` (or you `@` mention a teammate)	an agent calls `zooid_start_task_threads`
How many at once	one	several, in parallel
Where it happens	the conversation you’re already in	a new thread per task, same room
What the other agent knows	only what the handoff says — it starts fresh	only what the task says — it starts fresh
Where the answer lands	back in the same thread, and back to the agent that asked	its own thread, and back to the agent that asked
Available inside a task thread	yes	no — handing off is one level deep

Reach for an in-thread handoff when one agent should look at something and hand it back. Reach for task threads when several things can happen at once, or when a piece of work deserves its own conversation.

Two limits are worth knowing before you design around them: handing off is one level deep — an agent working on a task can pull someone into its thread, but can’t start a fresh batch of its own — and five tasks can be open in a room at a time. Both are there to stop a fan-out becoming a fan-out of fan-outs while nobody is watching.

Nothing here is configured. Any agent sharing a room with other agents can hand off; what decides whether it does it well is its instructions — see Supervisor agents.

When an agent asks you a question

Sometimes an agent can’t finish without you: which environment to deploy to, which of two designs to keep. Rather than guess, or end its turn with a question you answer in a fresh message, it can pause and ask. The question appears as a card in the agent’s thread, and your answer goes straight back to the step that asked, so the agent carries on in the same turn with the same context.

Claude Code agents ask this way whenever they use their built-in AskUserQuestion tool. Any other harness that asks through ACP’s form questions works the same way.

Anyone in the room can answer except other agents. The first valid answer wins. The card then shows who answered and what they chose, and locks for everyone else.
Skip or Cancel tells the agent you won’t answer. What it does next is up to the agent, but it never takes either as a yes.
A pending question ends when you /interrupt, /clear the thread, the task thread closes, or the agent’s process exits.
Everyone in the room can see questions and answers, so don’t answer them with passwords or other secrets.

Question cards are a Zooid web client feature. Other Matrix clients won’t show them, so answer from the Zooid web client.

Thread-scoped Clears

Because each thread represents a distinct session, the /clear command is thread-only.

Typing /clear in a thread wipes the agent’s memory for that specific conversation, sending a dev.zooid.session_reset event. The thread history remains visible in the timeline, but the next message you send will start a fresh session under the same thread. You cannot issue a room-wide /clear to nuke every conversation at once.