Migration and legacy tools
The legacy surface is the one-release rollback for the native-first cutover. It is selected by migration settings, not by deprecation. It registers eleven tools: the six legacy-only tools in this page plus the five shared tools that also exist on the native surface.
Use this surface only to roll back or to run a documented migration check. Normal native-first work uses final text, $Name routing, and the six native tools.
When the legacy surface is active
| Setting | Result |
|---|---|
nativeFirst: off or shadow | Legacy surface, even if toolSurface: "native" is stored. |
nativeMentionRouting: false | Legacy surface so the explicit message path returns with the kill switch. |
toolSurface: "legacy" with nativeFirst: on | Legacy surface while native ingestion stays on. |
| Native mode, routing enabled, no legacy override | Native surface. |
:tools native restores the native surface after an explicit legacy override. :native-first on sets the mode only and never clears toolSurface: "legacy".
Legacy-only tools
| Tool | Purpose |
|---|---|
ensemble_workspace_info | Show the current workspace, directory, leader, members, and paused state. |
ensemble_list_workspaces | List workspaces with their directories, leaders, and members. |
ensemble_list_agents | List the roster and each agent's busy state. |
ensemble_send_message | Compatibility shim for the pre-native chat surface: post to the group chat or queue a direct message to an agent. |
ensemble_handoff | Queue a typed Markdown hop to a teammate with a required hop budget and have the answer relayed back. |
ensemble_delegate | Delegate a typed work item to another workspace member with an explicit hop budget. |
ensemble_workspace_info
Show the current workspace, directory, leader, members, and paused state.
| Property | Value |
|---|---|
| Caller | A bound workspace member. Unbound callers are refused. |
| Surface | Legacy only |
Registered description: Show the current Ensemble workspace, directory, leader, members, and paused state.
Inputs
This tool takes no inputs.
Returns
JSON with workspace, directory, leader (id, name), members (id, name), paused, and synthesis.
Example
{}Safety
- Read-only. The same facts arrive in the native per-turn block, so the native surface omits this tool.
ensemble_list_workspaces
List workspaces with their directories, leaders, and members.
| Property | Value |
|---|---|
| Caller | Any caller. |
| Surface | Legacy only |
Registered description: List Ensemble workspaces and their directories, leaders, and members.
Inputs
This tool takes no inputs.
Returns
JSON array with id, name, directory, leader, members, and paused.
Example
{}Safety
- Read-only roster and directory read. The native surface omits it.
ensemble_list_agents
List the roster and each agent's busy state.
| Property | Value |
|---|---|
| Caller | Any caller. |
| Surface | Legacy only |
Registered description: List the Ensemble roster, workspace membership, and busy state.
Inputs
This tool takes no inputs.
Returns
JSON array of non-archived agents with id, name, title, busy, and home.
Example
{}Safety
- Read-only. The native surface omits it because agent facts arrive in the turn block.
ensemble_send_message
Compatibility shim for the pre-native chat surface: post to the group chat or queue a direct message to an agent.
| Property | Value |
|---|---|
| Caller | A bound workspace member. Unbound callers are refused. |
| Surface | Legacy only |
Registered description: Compatibility shim: post a message to the group chat or queue a direct message to an agent. Native-first sessions use their final text plus $Name instead.
Inputs
| Field | Type | Notes |
|---|---|---|
kind | string workspace, agent | required |
id | string | — |
text | string | required |
Returns
A short confirmation or a refusal line such as Cross-workspace posts require ensemble_share approval.
Example
{
"kind": "workspace",
"text": "The install guide is ready for review."
}Safety
- Native-first sessions post their final text and use
$Nameinstead; this tool is not part of the native surface. $Nameand!Namementions in a workspace post create peer turns under the normal queue, lease, budget, and approval rules.- A direct message to an agent outside the workspace roster creates an
outside_rosterapproval.
ensemble_handoff
Queue a typed Markdown hop to a teammate with a required hop budget and have the answer relayed back.
| Property | Value |
|---|---|
| Caller | Any bound workspace member. |
| Surface | Legacy only |
Registered description: Queue a typed hop to a teammate with the required maxHops budget (0 = one-shot ask); the answer is relayed back here. The asking turn stays open until it lands — never follow a handoff with ensemble_delegate. Write a self-authored instruction for the recipient (what to do, context, expected output) — never paste the user's message verbatim; task stays the short display title.
Inputs
| Field | Type | Notes |
|---|---|---|
task | string | required |
instruction | string | — |
summary | string | required |
path | string | required |
to | string | — |
constraints | string | — |
expected | string | — |
maxHops | integer minimum 0 | required; Direct dispatches the recipient may make; 0 is a one-shot ask. |
Returns
A confirmation that the hop is queued and the asking turn stays open, or a refusal naming the invalid file, recipient, or budget.
Example
{
"task": "Check the command reference",
"instruction": "Read docs/reference/commands.md and confirm every `:` command has an example. Report gaps only; do not edit.",
"summary": "Independent read of the command reference",
"path": ".ensemble/handoffs/command-reference-review.md",
"maxHops": 0
}Safety
pathmust resolve inside.ensemble/handoffs/afterrealpath, so a symlink cannot escape the directory.- The recipient comes from
toor the file frontmatter. Exactly one active agent is required; archived, ambiguous, or unknown recipients are refused. - The asking turn stays open until the answer lands. Do not call
ensemble_delegateafter a handoff. - This tool exists only on the legacy surface and is a migration/rollback path, not a deprecated alias for native routing.
ensemble_delegate
Delegate a typed work item to another workspace member with an explicit hop budget.
| Property | Value |
|---|---|
| Caller | The workspace leader only. Peers use ensemble_handoff. |
| Surface | Legacy only |
Registered description: Delegate a typed subtask to another workspace member with the required maxHops budget (0 = one-shot ask) and record it on the board. The workspace leader may pass continuationOf (an exhausted dispatch group id) with a required groupMaxHops tier to open a continuation group; later delegations join it automatically. Ensemble leader only — peers hand off with ensemble_handoff, which already queues the hop.
Inputs
| Field | Type | Notes |
|---|---|---|
assignee | string | required |
title | string | required |
instruction | string | required |
constraints | string | — |
expected | string | — |
mode | string research, edit | — |
maxHops | integer minimum 0 | required; Direct dispatches the recipient may make; 0 is a one-shot ask. |
continuationOf | string | Workspace leader only: id of the exhausted dispatch group to continue. |
groupMaxHops | integer 8, 16, 24 | Required with continuationOf: hops for the new group tier (8, 16, 24), bounded by the command remaining. |
Returns
A delegation confirmation or a refusal. A leader can open a continuation group with continuationOf plus a required groupMaxHops tier.
Example
{
"assignee": "Nova",
"title": "Check the keyboard reference",
"instruction": "Compare docs/reference/keyboard.md with the keymap catalog and list any missing context.",
"maxHops": 1
}Safety
maxHopsis required;0is a one-shot ask. A paused workspace refuses delegation.continuationOfandgroupMaxHopsare leader-only.groupMaxHopsis required withcontinuationOfand must be one of the 8, 16, or 24 tiers bounded by the command remaining.- A duplicate delegation returns the existing work. One contact per recipient is allowed per native turn.
- This tool exists only on the legacy surface.
ensemble_dispatchis the native next-command tool.
Shared with the native surface
These five tools are registered on both surfaces with the same names and schemas:
| Tool | Purpose |
|---|---|
ensemble_task_status | List work items visible to the calling session. The stored state is pending, working, or replied; the derived status adds waiting, needs_you, retrying, failed, stalled, and cancelled. |
ensemble_review | Decide every item in a batch review turn: delegate it, start it, end it, or dismiss it. |
ensemble_ask_person | Ask the user for a judgment call and pause the current work item until they answer. |
ensemble_remember | Save durable project, workspace, or cross-project knowledge. |
ensemble_share | Request user authorization before cross-project or private-transcript disclosure. |
Read their caller rules, inputs, returns, examples, and safety notes once in Native tools.
Rollback boundary
ensemble_dispatchexists only on the native surface. A leader on the legacy surface cannot start the next command with it.ensemble_delegateandensemble_handoffare migration tools, not deprecated aliases. They are absent from the native surface, not hidden behind a warning.ensemble_send_messageis a compatibility shim. Its description says so, and native-first sessions use final text plus$Name.- The legacy read-only tools return roster and directory facts that native sessions receive in the turn block.