harness-multitool

Modes: plan, step-debug

A mode is a way the harness runs an agent: while it is on, what the agent may do and what it is told change. Plan mode is for studying and planning before anything is built; debug mode is for reproducing a fix before changing anything and verifying it after.

What it is

An agent has two sorts of thing to call (Tools and modes, CON-96):

A mode is a framework, not a prompt (P-10). It comes with its tools, hooks, rules and memory: the plan is journal entries and maps, step-debug has a router contract and live charts.

The modes:

ModeEntered withPage
Planmode__plan_enter, or /planthis page
Debug, with step-debug for pipelinesmode__debug, or /stepdebugthis page
Orchestrationmode__orchestrateOrchestration

On a program running as an agent backend, such as Claude Code, the modes come over a second MCP server, mode, as mcp__mode__plan_enter and so on (CON-106).

How it works

When an agent enters a mode

The rules are in every session's system prompt (ADR 0021):

The agent workflow holds these as rows W-1 to W-5 and W-41.

Plan mode

The agent studies the task and the code and writes a plan; the user approves it; only then does work begin (ADR 0016).

In plan mode the agent can:

Anything else is refused. Entering the mode also fires the hook point PlanEnter for a project's own hooks.

The plan is the journal and the maps, so the next session and other agents find it (agent workflow, W-30 to W-36):

mode__plan_exit refuses a plan with no journal entry, mind map or flowchart, and a plan whose map or chart is empty (CON-117).

Approving a plan

mode__plan_exit takes plan, the plan in short with the journal ids of its work items. There are two ways out:

The two places:

The first answer decides, and the other place follows. Answered in the window, the Telegram message loses its buttons and says where it was decided. Answered on Telegram, the window's card is withdrawn and a toast says "✅ План одобрен в Telegram" or "✏️ План не одобрен в Telegram".

An approval reaches the agent with plan mode already off. A rejection asks it to find out what to change. A message from the user's Telegram counts for user_said like one typed in the window (CON-158).

A slave's plan is approved by its master, not by the user (Orchestration).

Debug mode

mode__debug with on true switches debug mode on: the agent's instructions change to reproducing and verifying, and the window follows the run. The agent turns it off when the result is verified and the evidence is in the journal.

A small program is checked by running it and by tests; a small bug is reproduced by a failing test. A large pipeline, above all a distributed one, is also walked step by step: that is step-debug.

In plan mode, debugging is refused: it comes after the user approves the plan (W-5).

Step-debug

Step-debug is event-driven, step-by-step debugging of the project the agent works on, like an IDE's stepping debugger (ADR 0013). It pays off for large pipelines spread over services, queues and agents, where no ordinary debugger spans the whole path.

While it is on, the agent:

  1. draws a flowchart of each pipeline it debugs (live flowcharts);
  2. instruments the project's code with callbacks into the harness: notification brings data to the agent, journal records the event, flowstate_update marks the chart's active node;
  3. builds a debug router in the target project, so the pipeline takes its next step only when the agent allows it.

The harness pauses nobody's code: the stepping lives in the target project.

The debug router is always built by one contract, an OpenAPI document the harness ships (CON-27):

A waiting step advances only on the agent's approve: no timeout, no default action (CON-29). Everything the mode adds to the target project is active only with MULTITOOL_DEBUG_MODE=1, and the router only with authorization (CON-25). Without the gate the code is inert.

When a run reaches a terminal block of its flowchart, the cycle ends. It is saved to the project's .harness/debug/runs.sqlite and the chart is reset (CON-24).

The status line

The status line shows the mode first, as the field MODE:

MODEWhen
normalno mode is on
planplan mode
debugdebug mode
orchestratethe conversation is an orchestrator
slavethe conversation is an agent of an orchestrator

Several at once are joined with +, as in orchestrate + plan. A new tab resets MODE (CON-105).

Using it

ToolFor
mode__plan_enterenter plan mode; answers with its rules
mode__plan_exitshow the plan and ask to leave: plan, and user_said when the user has just said to go
mode__debugdebug mode on or off (on)
debug_contractthe step-debug router's contract, as an OpenAPI document (a utility)
debug_runssaved step-debug runs, to compare (a utility)

In the terminal UI (the TUI):

From the command line:

Settings

session.plan_first says what the built-in hook mode-guide does when the agent writes with no plan made in the session (CON-64):

It never touches reads or memory, and cannot loop. mode-guide also says the step of the cycle that is due, for one turn, at each user message and each change of mode (CON-66).

Limits and status

Specs and decisions

Specs:

This page's source