Skip to content

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.

ToolPurposeCaller
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.Any session that can call the location's Ensemble tools. The intended caller is a bound workspace member.
ensemble_reviewDecide 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_dispatchStart 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_personAsk the user for a judgment call and pause the current work item until they answer.Any bound workspace member.
ensemble_rememberSave durable project, workspace, or cross-project knowledge.Any bound workspace member.
ensemble_shareRequest 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.

PropertyValue
CallerAny session that can call the location's Ensemble tools. The intended caller is a bound workspace member.
GateRead-only. An optional workspaceID narrows the result to one workspace.

Registered description: List pending, working, and replied Ensemble subtasks.

Inputs ​

FieldTypeNotes
workspaceIDstring—

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 ​

json
{
  "workspaceID": "workspace_01JEXAMPLE"
}

Safety ​

  • When the session is bound to another workspace and workspaceID differs, the call returns Cross-workspace reads require ensemble_share approval. It does not create that approval; use ensemble_share deliberately.
  • 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.

PropertyValue
CallerThe batch's assignee. The leader usually receives the batch, but any workspace member can be the assignee.
GateA 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 ​

FieldTypeNotes
batchstringrequired
decisionsarrayrequired
hand_tostring—

decisions[] item

FieldTypeNotes
itemstringrequired
actionstringrequired
assigneestring—
notestring—
maxHopsinteger minimum 0Required 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 ​

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

  • action accepts exactly delegate, start, end, or dismiss. The JSON Schema types it as a string; the parser enforces the four values.
  • delegate is leader-only, even when a non-leader is reviewing. It also requires assignee and maxHops; 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_to names a different recipient.
  • Individual item refusals do not close the batch. Re-read the batch with ensemble_task_status if 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.

PropertyValue
CallerThe workspace leader only.
GateA 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 ​

FieldTypeNotes
titlestringrequired
instructionstringrequired
assignmentsarrayrequired
continuationOfstring—

assignments[] item

FieldTypeNotes
assigneestringrequired
titlestringrequired
instructionstringrequired
constraintsstring—
expectedstring—
modestring research, edit—
maxHopsinteger minimum 0required; 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 ​

json
{
  "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 $Name in 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.
  • continuationOf records provenance only. The next command still gets a fresh root group and a fresh command budget, not the exhausted command's remainder.
  • assignments[].mode accepts research or edit; anything else becomes research. maxHops is required on every assignment and 0 is 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.

PropertyValue
CallerAny bound workspace member.
GateA bound session. The workspace may be paused.

Registered description: Ask the user for a judgment call and pause this subtask until they answer.

Inputs ​

FieldTypeNotes
questionstringrequired

Returns ​

Waiting for the user's answer in the approval inbox.

Example ​

json
{
  "question": "Should the reference target 0.1.x only, or also the next prerelease?"
}

Safety ​

  • Creates a pending ask_person approval 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.

PropertyValue
CallerAny bound workspace member.
GateA bound session. The workspace may be paused.

Registered description: Save durable project, workspace, or cross-project knowledge. Cross-project knowledge needs approval.

Inputs ​

FieldTypeNotes
textstringrequired
scopestring project, workspace, globalrequired

Returns ​

Saved <scope> memory. for project and workspace. global returns Cross-project memory needs approval: <approval id>.

Example ​

json
{
  "text": "The docs check reads canonical constants from src/v2; never hand-copy host or Node versions.",
  "scope": "project"
}

Safety ​

  • global is first saved as a project-scoped memory and a promote_memory approval 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.

PropertyValue
CallerAny bound workspace member.
GateA bound session. The workspace may be paused.

Registered description: Request authorization before cross-project or private-transcript disclosure.

Inputs ​

FieldTypeNotes
textstringrequired
scopestring cross_project, private_transcriptrequired

Returns ​

Sharing needs user authorization: <approval id>.

Example ​

json
{
  "text": "Our staging host is reached through the team VPN profile.",
  "scope": "cross_project"
}

Safety ​

  • Creates a pending cross_project approval and an approval-kind system message. Approving it creates a new global memory from the text; rejecting it creates nothing.
  • cross_project and private_transcript have the same approval effect. private_transcript changes the approval title to Share private transcript content so the user sees the disclosure context; the post-approval memory is identical.
  • ensemble_task_status points 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):

  1. nativeFirst other than on selects the legacy surface.
  2. nativeMentionRouting: false selects the legacy surface.
  3. toolSurface: "legacy" selects the legacy surface.
  4. 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 ​

Released under the MIT License.