start_run
Starts a background harness run for a task using a selected or default chain, returning a run ID to poll status; if it stops immediately, returns the exit code and log tail.
Instructions
Start a harness run in the background. Returns the run id to poll with run_status, or started:false with the exit code and log tail if the run stopped at once. chain is a chain name as list_chains shows it (never a path); leave it out to use the default chain, and the answer names it. task, draft, context and from_run are paths inside your working directory (tasks/x.md, context/my-project, runs/); anything outside it, or on the secret/credential denylist, is refused. draft + from_run + rounds=1 makes a panel-only grading pass. ladder and ladder_credit set the ladder for a chain with exactly three reviewer layers (the CLI's --ladder and --ladder-credit).
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"task": "<task>"
},
"name": "start_run"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| task | Yes | ||
| chain | No | ||
| draft | No | path to a draft to review instead of building one | |
| ladder | No | true to run the chain under the ladder: a block of 3 layer-1 revisions, then a pass that starts at layer 2; after 3 such layer-2 visits the next block ends at layer 3. It needs a chain with exactly three reviewer layers and either overseer rounds or its own `ladder` key; anything else is refused and nothing is started. The setting is saved in the run, so a resume keeps it. Left out: the chain decides: one with a `ladder` key runs the ladder, any other runs without it. | |
| rounds | No | ||
| context | No | ||
| max_usd | No | the figure to suggest as the run's spending limit, in USD, a positive number. When COUNCIL_SPEND_CAPS holds a run of this chain to a limit per provider, leave max_usd out: it is refused before anything starts, the dialog suggests no figure, and the person types one limit per provider. Otherwise, for a paid chain the limit is the number the person types in the dialog; this figure is only the suggestion, and "none" is refused (nothing started). Left out, the dialog suggests MAX_USD_PER_RUN (a user who set COUNCIL_MAX_USD_LIMIT gets the lesser of the two, with $12 for an unset MAX_USD_PER_RUN); with neither set it suggests nothing. A chain with no paid seat has no dialog: there this figure is the run's ceiling ($12 when nothing sets it) and "none" removes it. A figure above COUNCIL_MAX_USD_LIMIT is refused, and so is "none" on a chain with no paid seat where the user set that limit; 0 is refused. The run stops cleanly before any call that, by THC's estimate, would pass its limit, and resumes with a higher total. | |
| from_run | No | reuse this earlier run's criteria | |
| claude_route | No | where the chain's Claude seats are called: "auto" (the default: straight to Anthropic, or through OpenRouter when only an OpenRouter key is set), "anthropic", "openrouter" or "session". With "session" every Claude seat is answered by the person's own Claude Code session, one session for each seat: the run pauses at each such seat the way it does at an external stage, and those seats cost no API money. Only the person chooses it; leave it out unless the person chose a route. A run that began as a session run stays one when nothing is typed. | |
| persona_form | No | title or voice: whether every named seat of the chain is given its title or its voice for this run (the CLI's --persona-form). The chain must already switch seat_personas on, or the call is refused. Left out: the chain's own form. A resume keeps the form its run began with. | |
| ladder_credit | No | how many of the first passes run under the plain rules before the ladder starts (they count as its first block), a whole number; goes with ladder: true. Left out: 0. | |
| allow_unfenced | No | waive the artifact gate: true for the whole task, or a list of file names that are only locations, not content the panel needs | |
| zero_retention | No | "on" or "off": with "on" every call through OpenRouter names only the hosts that OpenRouter's list gives for its model as zero-retention hosts, and a seat no such host serves is named and the start refused. Seats called straight to their lab are not covered. Leave it out unless the person chose; a run that began with it on keeps it. | |
| ladder_exchange | No | no longer used: layers 2 and 3 have their own exchange round, so any value is refused. Leave it out. |