Skip to content

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 ​

SettingResult
nativeFirst: off or shadowLegacy surface, even if toolSurface: "native" is stored.
nativeMentionRouting: falseLegacy surface so the explicit message path returns with the kill switch.
toolSurface: "legacy" with nativeFirst: onLegacy surface while native ingestion stays on.
Native mode, routing enabled, no legacy overrideNative 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 ​

ToolPurpose
ensemble_workspace_infoShow the current workspace, directory, leader, members, and paused state.
ensemble_list_workspacesList workspaces with their directories, leaders, and members.
ensemble_list_agentsList the roster and each agent's busy state.
ensemble_send_messageCompatibility shim for the pre-native chat surface: post to the group chat or queue a direct message to an agent.
ensemble_handoffQueue a typed Markdown hop to a teammate with a required hop budget and have the answer relayed back.
ensemble_delegateDelegate 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.

PropertyValue
CallerA bound workspace member. Unbound callers are refused.
SurfaceLegacy 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 ​

json
{}

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.

PropertyValue
CallerAny caller.
SurfaceLegacy 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 ​

json
{}

Safety ​

  • Read-only roster and directory read. The native surface omits it.

ensemble_list_agents ​

List the roster and each agent's busy state.

PropertyValue
CallerAny caller.
SurfaceLegacy 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 ​

json
{}

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.

PropertyValue
CallerA bound workspace member. Unbound callers are refused.
SurfaceLegacy 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 ​

FieldTypeNotes
kindstring workspace, agentrequired
idstring—
textstringrequired

Returns ​

A short confirmation or a refusal line such as Cross-workspace posts require ensemble_share approval.

Example ​

json
{
  "kind": "workspace",
  "text": "The install guide is ready for review."
}

Safety ​

  • Native-first sessions post their final text and use $Name instead; this tool is not part of the native surface.
  • $Name and !Name mentions 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_roster approval.

ensemble_handoff ​

Queue a typed Markdown hop to a teammate with a required hop budget and have the answer relayed back.

PropertyValue
CallerAny bound workspace member.
SurfaceLegacy 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 ​

FieldTypeNotes
taskstringrequired
instructionstring—
summarystringrequired
pathstringrequired
tostring—
constraintsstring—
expectedstring—
maxHopsinteger minimum 0required; 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 ​

json
{
  "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 ​

  • path must resolve inside .ensemble/handoffs/ after realpath, so a symlink cannot escape the directory.
  • The recipient comes from to or 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_delegate after 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.

PropertyValue
CallerThe workspace leader only. Peers use ensemble_handoff.
SurfaceLegacy 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 ​

FieldTypeNotes
assigneestringrequired
titlestringrequired
instructionstringrequired
constraintsstring—
expectedstring—
modestring research, edit—
maxHopsinteger minimum 0required; Direct dispatches the recipient may make; 0 is a one-shot ask.
continuationOfstringWorkspace leader only: id of the exhausted dispatch group to continue.
groupMaxHopsinteger 8, 16, 24Required 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 ​

json
{
  "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 ​

  • maxHops is required; 0 is a one-shot ask. A paused workspace refuses delegation.
  • continuationOf and groupMaxHops are leader-only. groupMaxHops is required with continuationOf and 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_dispatch is the native next-command tool.

Shared with the native surface ​

These five tools are registered on both surfaces with the same names and schemas:

ToolPurpose
ensemble_task_statusList 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_reviewDecide every item in a batch review turn: delegate it, start it, end it, or dismiss it.
ensemble_ask_personAsk the user for a judgment call and pause the current work item until they answer.
ensemble_rememberSave durable project, workspace, or cross-project knowledge.
ensemble_shareRequest 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_dispatch exists only on the native surface. A leader on the legacy surface cannot start the next command with it.
  • ensemble_delegate and ensemble_handoff are migration tools, not deprecated aliases. They are absent from the native surface, not hidden behind a warning.
  • ensemble_send_message is 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.

Released under the MIT License.