Ping the server

List configured agents merged with their current state

Return the current external-agents state file (per-agent healthy/not_installed/needs_auth/quota_exhausted/errored_transient with metadata)

Probe a specific agent by id; runs an install-check and updates the state file. Returns the new state.

Persist an API-key env variable so the next dispatch (and future sessions) see it. Writes to ~/.local/state/external-agents/keys.env (mode 0600).

Pick up to N distinct healthy candidates by round-robin (preference_order + last_used_at). Optional min_distinct_providers enforces cross-provider diversity, counted per provider FAMILY: google3 and google4 are two API keys for one source, not two opinions. A model is never seated twice while an unseated one is available, so a panel gets distinct voices rather than clones of one model. Exclusion uses the same identity: filter.exclude_ids drops every entry serving the same model as each named id (excluding gemini-3.6-flash-6 will NOT seat gemini-3.6-flash-5 instead), and filter.exclude_providers matches by family, so 'google' covers google3..8.

ROUTING NOTE: omitting filter.tier defaults to tier='weak' here — enforced, not just advisory, so a forgotten tier can't silently draw a strong (costlier/slower) candidate instead. Most atomic tasks (single-file edits, refactors, glue code, summaries, format conversions, well-scoped fixes) get the same quality answer from a weak-tier free-tier model as from Claude Opus or Codex Pro, in a fraction of the time and cost. Reach for strong-tier by passing filter.tier='strong' explicitly, ONLY when the task actually needs deep reasoning: multi-step debugging, architecture decisions, ambiguous requirements, novel algorithms. Frontier ≠ better output for the long tail of routine work; often it is slower with no quality gain. Be smart, not lavish.

Run a specific agent by id with a prompt. transport ('generate_new' | 'edit_exists' | 'read_only') overrides the default. With cwd, edit_exists is preferred when declared; otherwise generate_new is preferred. escalate_to_pro=true uses the same-provider strong-tier entry instead.

read_only: use when the agent must NOT be able to write — e.g. a reviewer dispatched into a live repo it is judging. Selects a declared read_only command, or an implicit generate_new (HTTP has no filesystem access at all). An entry with only edit_exists and no read_only errors rather than silently falling back to the write-capable command.

ROUTING NOTE: for the same task, weak-tier free-tier models (Gemini flash, Groq Qwen, DeepSeek, OpenRouter :free) are usually correct AND fast enough. Use dispatch against Claude Opus, Codex Pro, or any strong-tier subscription model ONLY when the task genuinely needs frontier capability. escalate_to_pro is a retry lever, not a default. If a weak agent's output is wrong, first ask whether the SPEC was ambiguous (fix the spec, re-dispatch weak) before escalating tier — reaching for stronger models hides prompt-engineering failures behind expensive compute.

cwd: absolute path of an existing directory (e.g. a git worktree) for an edit_exists agent to run IN and edit files in place. When an agent declares edit_exists, supplying cwd selects it by default. generate_new (HTTP) ignores cwd and has no filesystem access. When cwd is a git repo, the returned files list is the git-changed set, not the whole tree.

files: array of {path, lines?, label?} entries. Their contents are read from disk and prepended to the prompt as a structured context block. CRITICAL for generate_new agents (they have ZERO filesystem access — without files they hallucinate code shapes). Optional for edit_exists: direct CLIs can inspect cwd themselves; attach files only when you need to constrain or highlight context. Paths resolve relative to cwd. IMPORTANT: when using files, ALWAYS pass cwd (the repo root) — it serves as the containment basedir for path resolution and security. Without cwd, paths resolve against the MCP server process cwd, which is likely wrong.

By default this refuses a prompt larger than agent_id's known token-per-minute ceiling (the same declared/observed limit pick_agents checks before seating one) instead of sending it and getting a live HTTP 413. Pick a different (or larger-ceiling) agent_id, or set allow_oversized_prompt=true to send it anyway.

Aggregate dispatch telemetry from ~/.local/state/external-agents/dispatch-log.jsonl. Returns per-agent counts, tokens, outcomes; per-transport totals.