harness-multitool

Orchestration

In orchestration mode an agent becomes the master of agents it starts: it gives each a journal entry as its work, follows it, checks the result against the specs and closes the entry. Each agent it starts is a slave whose only contact is its master.

What it is

Orchestration is a mode of the harness, not a utility (Modes). The agent enters it with mode__orchestrate on. Its prompt then gains the mode's rules, and the tools to start, read, answer and close agents appear (CON-100).

Master and slave are technical terms only. The master is an agent like any other; its slaves are agents in tabs of its group, in the same project folder and git, with the journal and every tool.

How it works

Starting an agent

The master writes the work first, as an open journal entry, then starts an agent on it with mode__agent_spawn (CON-109):

ArgumentIs
nickwhat the agent goes by; unique among the open conversations
adapter, modelone of those mode__agent_models lists as authorized
taskthe id of the open journal entry that is its work

A spawn without an open entry is refused. The agent starts in a new tab of the master's group, with no history, and its system prompt names its task. It starts on it at once.

A slave starts on its master's profile, and mode__agent_models lists what is signed in under it (CON-124). A hook tells each agent it works for the master and asks it to report ready.

Who talks to whom

The task is a journal entry

Only the master closes a slave's task (CON-109). The cycle, as the agent workflow holds it:

  1. The slave reads the entry and works on it (W-50).
  2. Its work done and proved, it asks its master with agent_send to close the entry, naming the proofs (W-57). If it calls journal_close or journal_abandon on its own task, the harness refuses it.
  3. The master checks the work with mode__agent_read (W-54, W-59).
  4. Good: the master calls journal_close and tells the slave. Not good: it sends the slave back (W-62).
  5. On approval, the slave asks to close its session (W-58), and the master calls mode__agent_close.

The master can close an agent at any time.

Checking against the specs

Guaranteeing that its agents' work matches the specs is the master's duty, since a slave may not keep track of them (CON-112).

Before approving, the master reads what binds the change (journal_search, journal_list) and reads the change itself against it, not only the slave's report. If the slave broke a spec, the master does not close the entry and does not fix it itself: it sends the slave back with agent_send, naming the rule and what breaks it. A spec that has to change takes the user's word.

Plans and permissions

A slave plans like any agent. Its plan holds a mind map of its strategy pointing at its task, and a flowchart of the logic it builds; mode__plan_exit refuses it until both exist (CON-111).

The slave sends its plan to its master and waits. When the master says to go, the slave calls mode__plan_exit with the master's words in user_said (W-56). A slave's plan is never put to the user's window or Telegram (CON-163).

Without asking anyone, a slave reads and writes files inside its folder, runs reading commands, and builds and tests with cargo (CON-103). Anything else goes to its master: other commands, redirection, substitution, the network, a path outside the folder.

On an agent backend a slave always runs isolated: none of the user's settings, hooks, rules or servers, and never with permissions skipped (CON-108). Each request beyond the basics goes to the master with the tool and its arguments, through mode__permission_ask, and the program waits.

The master answers with mode__agent_answer: once, always (for this tool and target in that session) or deny. No answer in 30 minutes, or no master, is a deny.

Reminders

While a slave lives, the harness reminds its master every 10 minutes to check on it, naming the agent, its task and whether it is running (CON-110). On a reminder the master calls mode__agent_read; a slave that stopped with no word is told to move on, or closed if its work is over (W-60).

In the window

The group's tabs are set off together, with (M) and (S) on their titles. The status line's MODE says orchestrate on the master and slave on its agents (Modes).

Using it

ToolFor
mode__orchestratethe mode on or off (on)
mode__agent_modelsthe adapters an agent can start on, with their models
mode__agent_spawnstart an agent on a task: nick, adapter, model, task
mode__agent_readwhat an agent has done: each message it got, each call in order with its arguments, its last words (nick)
mode__agent_answeranswer an agent's permission request: nick, answer
mode__agent_closeend an agent: its process stops and its tab closes; what it wrote stays (nick)
agent_sendgive an agent work, or tell it a verdict

The mode__agent_* tools work only in orchestration mode. On an agent backend they come over the mode server as mcp__mode__agent_spawn and so on; its list is fixed at the start, so outside the mode they are refused rather than absent (Tools and modes).

mode__orchestrate with on false ends the mode. The master's agents stay until it closes them.

The workflow rows

The agent workflow binds both sides:

RowWhoSituation
W-50slavejust started on a journal entry: read the file and the entry, work on it
W-51slavea user message in its tab stands for the user
W-52slavedone or in need: agent_send its orchestrator, its only contact
W-55slavea question: ask_user, which goes to the orchestrator
W-56slaveplan ready: send it, wait, then mode__plan_exit with the master's words
W-57slavework done and proved: ask to close the entry; do not close it
W-58slaveapproved: ask to close its session, and stop
W-53masterwork for an agent: write the entry, spawn with it as task, end the turn
W-54masterchecking work: mode__agent_read, against the rows of the workflow
W-59masterasked to close an entry: check, then journal_close or send back; then mode__agent_close
W-60mastera reminder: mode__agent_read, then move it on or close it
W-62masterchecking a change: read what binds it and the diff; a broken spec goes back named

Limits and status

Specs and decisions

This page's source