Native tools
The native surface registers six tools under the ensemble namespace: ensemble_task_status, ensemble_review, ensemble_dispatch, ensemble_ask_person, ensemble_remember, ensemble_share.
These tools keep only decisions the server cannot infer safely. Roster and directory facts arrive in the per-turn ensemble_turn block, and ordinary replies and $Name mentions route work without a tool call.
| Tool | Purpose | Caller |
|---|---|---|
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. | Any session that can call the location's Ensemble tools. The intended caller is a bound workspace member. |
ensemble_review | Decide every item in a batch review turn: delegate it, start it, end it, or dismiss it. | The batch's assignee. The leader usually receives the batch, but any workspace member can be the assignee. |
ensemble_dispatch | Start the next ticket as a new command root with a fresh command budget and this assignment batch. This is the leader's terminal-continuation tool. | The workspace leader only. |
ensemble_ask_person | Ask the user for a judgment call and pause the current work item until they answer. | Any bound workspace member. |
ensemble_remember | Save durable project, workspace, or cross-project knowledge. | Any bound workspace member. |
ensemble_share | Request user authorization before cross-project or private-transcript disclosure. | Any bound workspace member. |
A tool result is a single content string. JSON-returning tools serialise their payload; errors and refusals are plain text. Some refusal paths also return an undeclared refused field, so read content rather than assuming the declared result type is exhaustive.
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.
| Property | Value |
|---|---|
| Caller | Any session that can call the location's Ensemble tools. The intended caller is a bound workspace member. |
| Gate | Read-only. An optional workspaceID narrows the result to one workspace. |
Registered description: List pending, working, and replied Ensemble subtasks.
Inputs
| Field | Type | Notes |
|---|---|---|
workspaceID | string | — |
Returns
A JSON array. Each row carries id, title, state, status, outcome, attempts, queueKey, leaseUntil, deadlineAt, failure, assignee, parent, dispatchGroupID, resultMessageID, workKind, handoff, and turn. state is pending, working, or replied; status is derived from state, lease, retry, children, and approvals. Fields whose value is undefined are omitted by JSON.stringify.
Example
{
"workspaceID": "workspace_01JEXAMPLE"
}Safety
- When the session is bound to another workspace and
workspaceIDdiffers, the call returnsCross-workspace reads require ensemble_share approval.It does not create that approval; useensemble_sharedeliberately. - The handler does not require a bound session. Without a binding and without
workspaceID, it returns work from every workspace in the service. Treat an unbound call as a cross-workspace read and scope it explicitly.
ensemble_review
Decide every item in a batch review turn: delegate it, start it, end it, or dismiss it.
| Property | Value |
|---|---|
| Caller | The batch's assignee. The leader usually receives the batch, but any workspace member can be the assignee. |
| Gate | A bound session, a batch in the same workspace with workKind: "handoff" and handoff.batch: true, an open batch, and an assignee that matches the caller. |
Registered description: Decide each item in a batch review turn (delegate, start, end, or dismiss). A delegate decision requires maxHops for the recipient. The batch closes only when every item is decided; non-leader reviewers hand it onward to the leader.
Inputs
| Field | Type | Notes |
|---|---|---|
batch | string | required |
decisions | array | required |
hand_to | string | — |
decisions[] item
| Field | Type | Notes |
|---|---|---|
item | string | required |
action | string | required |
assignee | string | — |
note | string | — |
maxHops | integer minimum 0 | Required for delegate: direct dispatches the recipient may make. |
Returns
Newline-joined result lines, for example <item> (<title>): delegated to $<name>., started — assigned to $<reviewer>., ended., or dismissed.. The call also reports Batch closed: every item decided. or Batch stays open: <n> of <m> decided. Refusals explain the failed item.
Example
{
"batch": "task_batch_01JEXAMPLE",
"decisions": [
{
"item": "task_item_01JEXAMPLE",
"action": "end",
"note": "Covered by the existing guide"
},
{
"item": "task_item_02JEXAMPLE",
"action": "delegate",
"assignee": "Nova",
"maxHops": 1,
"note": "Needs a fresh reference page"
}
]
}Safety
actionaccepts exactlydelegate,start,end, ordismiss. The JSON Schema types it as a string; the parser enforces the four values.delegateis leader-only, even when a non-leader is reviewing. It also requiresassigneeandmaxHops; the target must be an active workspace member.- The batch closes only when every item is decided. A closing non-leader hands the batch onward to the leader by default;
hand_tonames a different recipient. - Individual item refusals do not close the batch. Re-read the batch with
ensemble_task_statusif you are unsure which items remain.
ensemble_dispatch
Start the next ticket as a new command root with a fresh command budget and this assignment batch. This is the leader's terminal-continuation tool.
| Property | Value |
|---|---|
| Caller | The workspace leader only. |
| Gate | A bound session, an unpaused workspace, an active leader turn, and a terminal turn (synthesis, completion review, or batch review). One terminal turn starts at most one new command. |
Registered description: Leader-only terminal continuation: start the next ticket as a new command root with a fresh budget and this assignment batch. Normal chat uses the routing operator; a retry returns the existing command.
Inputs
| Field | Type | Notes |
|---|---|---|
title | string | required |
instruction | string | required |
assignments | array | required |
continuationOf | string | — |
assignments[] item
| 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. |
Returns
Started command "<title>" as a new command root with <n> assignment(s). Root <id>. <budget line> on success, a dedupe line, or a Dispatch refused: … line. Refusals are also posted as a system message in the group chat.
Example
{
"title": "Reference section for 0.1.x",
"instruction": "Build the reference pages from the code catalogs and add the contract test.",
"assignments": [
{
"assignee": "Nova",
"title": "Tool and command reference",
"instruction": "Generate the six native tools, the legacy surface, and every `:` command.",
"maxHops": 1,
"mode": "edit"
},
{
"assignee": "Sage",
"title": "Config and CLI reference",
"instruction": "Document workspace config, settings, environment variables, storage, and operator CLIs.",
"maxHops": 1,
"mode": "edit"
}
]
}Safety
- Normal chat uses the routing operator; do not call this tool to ask a teammate a question. Use
$Namein your final text. - The whole batch is preflighted before any work row is created. A refusal creates no work and is visible in the group chat.
continuationOfrecords provenance only. The next command still gets a fresh root group and a fresh command budget, not the exhausted command's remainder.assignments[].modeacceptsresearchoredit; anything else becomesresearch.maxHopsis required on every assignment and0is a one-shot ask.- The tool exists only on the native surface. A leader running the legacy rollback surface cannot start the next command with it.
ensemble_ask_person
Ask the user for a judgment call and pause the current work item until they answer.
| Property | Value |
|---|---|
| Caller | Any bound workspace member. |
| Gate | A bound session. The workspace may be paused. |
Registered description: Ask the user for a judgment call and pause this subtask until they answer.
Inputs
| Field | Type | Notes |
|---|---|---|
question | string | required |
Returns
Waiting for the user's answer in the approval inbox.
Example
{
"question": "Should the reference target 0.1.x only, or also the next prerelease?"
}Safety
- Creates a pending
ask_personapproval and an approval-kind system message. When an active turn exists, the approval attaches to that work item. - Approve requeues the work item. Reject marks it failed and stopped, which the Work pane shows as cancelled rather than a native failure.
ensemble_remember
Save durable project, workspace, or cross-project knowledge.
| Property | Value |
|---|---|
| Caller | Any bound workspace member. |
| Gate | A bound session. The workspace may be paused. |
Registered description: Save durable project, workspace, or cross-project knowledge. Cross-project knowledge needs approval.
Inputs
| Field | Type | Notes |
|---|---|---|
text | string | required |
scope | string project, workspace, global | required |
Returns
Saved <scope> memory. for project and workspace. global returns Cross-project memory needs approval: <approval id>.
Example
{
"text": "The docs check reads canonical constants from src/v2; never hand-copy host or Node versions.",
"scope": "project"
}Safety
globalis first saved as a project-scoped memory and apromote_memoryapproval is created. Approving it promotes the same memory to global; rejecting it leaves it project-scoped.- Empty text returns
Memory text is empty.and saves nothing. - Memory rows record automatic provenance (
source: agent:<id>) and an agent-authored history entry.
ensemble_share
Request user authorization before cross-project or private-transcript disclosure.
| Property | Value |
|---|---|
| Caller | Any bound workspace member. |
| Gate | A bound session. The workspace may be paused. |
Registered description: Request authorization before cross-project or private-transcript disclosure.
Inputs
| Field | Type | Notes |
|---|---|---|
text | string | required |
scope | string cross_project, private_transcript | required |
Returns
Sharing needs user authorization: <approval id>.
Example
{
"text": "Our staging host is reached through the team VPN profile.",
"scope": "cross_project"
}Safety
- Creates a pending
cross_projectapproval and an approval-kind system message. Approving it creates a new global memory from the text; rejecting it creates nothing. cross_projectandprivate_transcripthave the same approval effect.private_transcriptchanges the approval title toShare private transcript contentso the user sees the disclosure context; the post-approval memory is identical.ensemble_task_statuspoints here when a cross-workspace read is refused. It never auto-creates the approval.
Surface selection
The host installs one toolset per location from effectiveToolSurface(settings):
nativeFirstother thanonselects the legacy surface.nativeMentionRouting: falseselects the legacy surface.toolSurface: "legacy"selects the legacy surface.- Otherwise the native surface is installed.
:tools native is the explicit restore after a legacy tool-surface override. :native-first on does not clear that override. See Migration and legacy tools for the other surface.
Next
- Migration and legacy tools: the one-release rollback surface.
- Command reference:
:toolsand:native-first.