Skip to main content
Glama

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

NameRequiredDescriptionDefault
taskYes
chainNo
draftNopath to a draft to review instead of building one
ladderNotrue 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.
roundsNo
contextNo
max_usdNothe 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_runNoreuse this earlier run's criteria
claude_routeNowhere 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_formNotitle 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_creditNohow 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_unfencedNowaive the artifact gate: true for the whole task, or a list of file names that are only locations, not content the panel needs
zero_retentionNo"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_exchangeNono longer used: layers 2 and 3 have their own exchange round, so any value is refused. Leave it out.

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed7 schema fields changedv0.8.4
    • addedInput schema / properties / claude_route
      Added value: +{
      +  "description": "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.",
      +  "type": "string"
      +}
    • addedInput schema / properties / ladder
      Added value: +{
      +  "description": "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.",
      +  "type": "boolean"
      +}
    • addedInput schema / properties / ladder_credit
      Added value: +{
      +  "description": "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.",
      +  "maximum": 9007199254740991,
      +  "minimum": 0,
      +  "type": "integer"
      +}
    • addedInput schema / properties / ladder_exchange
      Added value: +{
      +  "description": "no longer used: layers 2 and 3 have their own exchange round, so any value is refused. Leave it out.",
      +  "maximum": 7,
      +  "minimum": 0,
      +  "type": "integer"
      +}
    • changedInput schema / properties / max_usd / description
      Previous value: -"the figure to suggest as the run's spending limit, in USD, a positive number. 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 $7 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 ($7 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 stage that could pass its limit, and resumes with a higher total."New value: +"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."
    • addedInput schema / properties / persona_form
      Added value: +{
      +  "description": "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.",
      +  "type": "string"
      +}
    • addedInput schema / properties / zero_retention
      Added value: +{
      +  "description": "\"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.",
      +  "type": "string"
      +}
  2. Changed4 schema fields changedv0.8.3
    • removedInput schema / properties / allow_secret_shaped
      Removed value: -{
      -  "description": "send key-shaped text anyway. Every prompt is scanned for the key formats in src/secret-patterns.js before it leaves, and a match refuses the run (exit 11, started:false with the file, line and format in the log, never the value). Saved with the run, so resume_run keeps it. Off unless given.",
      -  "type": "boolean"
      -}
    • changedInput schema / properties / max_usd / description
      Previous value: -"per-run spend ceiling in USD, a positive number. Defaults to MAX_USD_PER_RUN or $7. Pass \"none\" for no ceiling (refused if the user set COUNCIL_MAX_USD_LIMIT); 0 is refused. The run stops cleanly before any stage that could breach it, and resumes with a higher ceiling."New value: +"the figure to suggest as the run's spending limit, in USD, a positive number. 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 $7 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 ($7 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 stage that could pass its limit, and resumes with a higher total."
    • removedInput schema / properties / pii_gate
      Removed value: -{
      -  "description": "scan the task for PII and the key formats in src/secret-patterns.js before any provider call: warn logs and proceeds, hard-stop refuses the run. Off unless given.",
      -  "enum": [
      -    "warn",
      -    "hard-stop"
      -  ],
      -  "type": "string"
      -}
    • changedInput schema / required
      Previous value: -[
      -  "chain",
      -  "task"
      -]New value: +[
      +  "task"
      +]
  3. First observedv0.8.1

TDQS

A4.5/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations supplied, the description carries the full burden and does so: it declares background execution, the success and immediate-failure return shapes (started:false with exit code and log tail), a working-directory boundary plus secret/credential denylist that cause refusals, and for ladder that anything else "is refused and nothing is started." These are precisely the side effects and failure modes an agent needs before launching a real run.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

It is front-loaded correctly — purpose and return value first, then scoping constraints, then the specialized ladder note. It is a dense single paragraph with several semicolon-chained clauses, and the final ladder sentence largely restates what the ladder property schema already explains in depth.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 14-parameter launcher with no output schema, the description covers the return shape and the high-risk path/refusal semantics that most often cause misuse. Gaps remain around spending behavior (max_usd), the artifact gate (allow_unfenced) and zero_retention, all of which exist only in schema text and are consequential enough to warrant a line.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 71%, so the baseline is 3, and the description earns above that by adding meaning the schema lacks: chain is "never a path" and matches what list_chains shows, task/draft/context/from_run are working-directory-relative paths, and draft+from_run+rounds=1 composes into a distinct panel-only mode. It does not touch max_usd, allow_unfenced, zero_retention or persona_form, which are left entirely to the schema text.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with a specific verb and resource ("Start a harness run in the background") and immediately states the return contract ("run id to poll with run_status"), which cleanly separates it from the polling sibling. An agent knows exactly what this tool initiates and what it gets back without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives concrete selection conditions throughout: omit chain for the default chain, use draft + from_run + rounds=1 for a panel-only grading pass, use ladder only for chains with exactly three reviewer layers, and leave claude_route out unless a human chose it. What's missing is an explicit statement of when NOT to call it, e.g. previewing with dry_run or continuing with resume_run instead.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.