/consult

name: consult
description: Consult a strong reasoning model for strategy — feed it the current elaboration, take its reply as the next master_guidance, and dispatch workers from it. This is the main agent's high-intelligence step (workers prove; the consult decomposes and steers). Runs over the gpt_pro transport (a paid API, default), the claude_api transport (the Anthropic API, per-token BYO key), or the claude_code transport (your Claude subscription); if no key/login is configured it degrades to off, where the main agent reasons on its own. Use it each strategic cycle, on events (a worker finished a round / real new progress), not a blind timer.

Consult for strategy

You are the **main agent**. Workers do the proving; **you do the high-level thinking by consulting a strong reasoning model and turning its reply into dispatch.** This is the strategic core of the loop: distil state (the `elaboration` skill) → consult → record the reply as `master_guidance` → assign workers from it.

The consult is the **core direction-guidance mechanism** — it is how the swarm gets steered — and the **only step that costs money** (codex workers + the verify service are free). Treat it as central, not optional.

When to consult (events, not a timer)

The gate is **judgment about new state**, not the clock. Consult only when there is genuinely new state to reason over:

• a worker **finished a round** and produced real new state;
• a **substantive new finding / dead end / verified fact** changed the picture;
• the swarm is **stuck** and needs a new direction.

Do **not** re-consult when nothing material has changed since the last `master_guidance`. A sensible cadence is **at most once every ~2 hours** — a consult itself takes minutes, and you want real state to reason over, not churn. Drive cadence off main-agent events (or your own `/loop`), never a blind timer.

**Spend discipline.** Each API consult costs money and accrues to the project's running total. Prefer `--effort high` (the workhorse); reserve `xhigh` for genuine forks. As project spend approaches the operator's ceiling, **surface it — that is a load-bearing fork** (see the main-agent contract).

**Project start (no record, no direction yet):** do not launch blind. First **discuss the problem with both the model AND the human**, get direction from both sides, then start the workers.

How to consult

1. **Prepare the elaboration first** (the `elaboration` skill): read global memory

• the fact graph (never worker local memory), produce the five-section

synthesis, and publish it with `gm_add` (kind `elaboration`). That published document is the consult prompt — never consult on an empty or stale prompt.

2. **Call the consult CLI** with the elaboration as input:

   consult --file <elaboration.md> --project <project_dir> --out <reply.md>

• `consult` is the wrapper on PATH — it sources the deployment env and execs

the strategy consult CLI (in `danus/strategy`) with the right Python.

• **Transport** comes from config (`DANUS_CONSULT_TRANSPORT`, default `gpt_pro`); a

per-call override is `--transport gpt_pro|claude_api|claude_code|off`. `gpt_pro` runs the paid OpenAI-compatible endpoint; `claude_api` runs the native Anthropic API (per-token, BYO key); `claude_code` runs the consult through the Claude Code CLI (`claude -p`); `off` short-circuits (see the `off` path below).

• **Effort** (`--effort high|xhigh|max`, default `high`): `high` is the

workhorse; reserve stronger levels for the hardest forks. All transports support through `max`; on `gpt_pro`, `max` fails rather than silently running without the requested reasoning effort when an endpoint rejects it.

• `--project` records the spend: one line per call appended to

`<project_dir>/spend/consult.jsonl`, and the CLI returns the running `project_total_usd`. **Always pass `--project`.**

• It prints a one-line JSON envelope (`transport`, `reply`, `usage.input` /

`usage.output` / `usage.reasoning`, `cost_usd`, `seconds`, `project_total_usd`) and, with `--out`, writes the full reply as markdown. Field shapes and pricing are owned by `danus/strategy` — read them there; do not re-derive them here.

• It is a **stateless gateway**: prompt in, reply out. It does **not** write the

stores — you do, in the next step.

• **If the consult could not run**, the envelope comes back `status="failed"`

with an `error` and an empty `reply` (exit non-zero) — e.g. the endpoint rejected the requested effort. There is nothing to record: do **not** publish an empty `master_guidance` and do **not** invent direction. Report the `error` to the operator, then either retry at a level the endpoint accepts or reason on your own for this cycle — and say which you did. **If the `error` names a parameter the endpoint refuses, re-run the call with that parameter changed** — the error tells you which: `background` → add `--background off`; `store` → `--store on`; `max_output_tokens` → `--max-output-tokens 0` (omits it entirely, for an endpoint that rejects the parameter rather than the value); the reasoning effort → a level it accepts. Nothing to edit, just the next invocation. If the same override keeps being needed on this deployment, tell the operator to pin it in `config/danus.env` (`DANUS_CONSULT_BACKGROUND` / `DANUS_CONSULT_STORE`) so you stop passing it.

3. **Record the reply as `master_guidance`, VERBATIM.** Take the reply as the direction and publish it unedited:

   gm_add(kind="master_guidance", claim=<one-line gist of the direction>,
          evidence=<the full, unedited reply>,
          links={"elaboration_id": <the gm_add id from step 1>},
          input_tokens=<usage.input>, output_tokens=<usage.output>, cost_usd=<cost_usd>)

The call's `input_tokens` / `output_tokens` / `cost_usd` from the envelope ride