delegate

Delegates a task to a separate, full agentic loop running on a different model (local via Ollama, or remote via OpenRouter), with its own tool access (files, bash), returning only a final result — functionally equivalent to a native subagent, but model-agnostic. Driven from the command line by a person or a script.

See mcp-subagent-delegation-plan.md for the full build plan, phased as separate commits/checkpoints.

Status

Phase 1, 2, 3, and 4 complete.

• delegate task — single-shot chat completion against a configured OpenAI-compatible endpoint (Ollama, LM Studio, vLLM, OpenRouter, ...).

• delegate agentic — gives the delegated model its own tool-use loop (read_file, write_file, run_bash) scoped to a caller-specified working directory, running until it stops calling tools, hits max_iterations, or exceeds timeout_seconds.

• delegate batch — a JSONL of jobs run concurrently in one process, under one semaphore.

• delegate list — inspect what past delegations actually did, without digging through logs or re-running anything.

• delegate transcript — full message/tool-call transcript for one delegation, when it was run with --capture-transcript (e.g. for model comparison/eval runs).

Deviation from the original plan: Phase 2 called for wrapping agent-loop as a subprocess. agent-loop only supports Linux/macOS/WSL, and this needs to run natively on Windows, so we built the in-process loop described as Phase 5's alternative instead — same tool interface, no subprocess/ANSI-stripping complexity, and it sidesteps agent-loop's AGPL/no-commercial license entirely. See delegate/agentic.py.

Safety note: working_dir is caller-specified, not a fixed sandbox — the delegated model gets unattended file/bash access to whatever directory it's pointed at. File tools (read_file/write_file) are scoped to stay within working_dir; run_bash runs with that directory as cwd but shell commands are not fully sandboxed and could escape it (e.g. cd ..). Point this at a directory you're comfortable an unattended model can read, write, and execute commands in.

Guardrail note: the original plan's Phase 4 asked to confirm agent-loop's own guardrails (iteration cap, repetition detection) were active. Since we're not using agent-loop, that doesn't apply directly — our loop has its own max_iterations and timeout_seconds caps (verified in testing), but no repetition detection. A model that gets stuck alternating between two tool calls will run until it hits max_iterations rather than being caught early. Worth adding if that turns out to happen in practice.

Binary files

read_file refuses binary files (tools.BINARY_EXTENSIONS — PDF, ZIP, .db, Office formats, images — plus a null-byte sniff on the first 1 KB for anything not on that list) instead of silently decoding them as garbled text. Before this guard existed, a delegated model called read_file directly on three PDFs instead of extracting their text with pypdf/pdfplumber first; .read_text(errors="replace") turned each one into a wall of � characters — often more characters than the source file's own byte size, since many raw bytes decode to multi-byte replacement characters — and the resulting ~1.9M-character blob blew straight through the model's context window on the very next turn, before any real work happened. Now that raises a clear ToolError naming the file type and pointing at the right extraction library instead.

Images are on that list like anything else, so the error names the format ("PNG image") rather than falling through to the sniff's generic "binary data".

Tool results are capped

run_bash and read_file both return at most 10,000 characters (tools.MAX_OUTPUT_CHARS): the first 5,000, a note saying how many were dropped and what to do instead, then the last 5,000. Head and tail, because the tail is where a traceback and its failing line are, and a head-only cut throws away the half worth reading. The [exit code: N] line is appended after truncation, never before, so it cannot be the thing that gets cut.

This is the same failure the binary guard above exists for, arriving by a different door — a cat of a room file, a chatty pip install, a wide find. The guard can refuse a file that is the wrong kind; it can't refuse one that is merely large, and run_bash can't refuse anything — so both truncate.

The advice in the notice differs by tool, because what the model can do about it differs. Command output is gone once cut, so run_bash says to re-run something narrower. A file is still sitting on disk unchanged, so read_file says to go back for the part it wants with grep, sed -n 'START,ENDp', or head/tail. read_file matters more than it looks: workers are told to extract a PDF's text to a file and read that back, and extracted text is exactly what gets large.

Every command also runs with PAGER=cat, MANPAGER=cat, LESS=-R, PIP_PROGRESS_BAR=off and TQDM_DISABLE=1. The two Python ones do the real work, since delegated workers are told to do file operations in Python; the pager settings bind when a Unix tool gets invoked, which happens because Git for Windows puts less/man on PATH. There is no stdin in a delegated run, so a pager doesn't produce noise — it hangs until the timeout kills it.

Vision was removed

read_file used to detect images by extension and show them to the model as real multimodal content, with downscaling and context pruning to keep an image-heavy run affordable. Visual judgment on plans and RCPs moved to the take-off tool, so none of that is reachable any more and it was deleted rather than left to rot.

It worked, and three things it had to get right are worth knowing before anyone adds vision back — all recoverable in full from the commit that removed this section:

• A tool-role message cannot carry an image_url block on any OpenAI-compatible provider, so the image has to go in a synthetic user message after every tool result for that turn.

• Pruning an old image means replacing the whole content block, not overwriting image_url.url with placeholder text — OpenRouter validates that field as a URL and 400s.

• Without pruning, a real 3-room extraction task reached ~194K prompt tokens by iteration 20 and still didn't finish, almost entirely from re-sending every image it had ever viewed.

Related MCP server: deepseek-subagent-mcp

Setup

uv sync
cp .env.example .env             # fill in DELEGATE_BASE_URL / DELEGATE_API_KEY / DELEGATE_MODEL
cp models.json.example models.json   # optional: named backends, see below

Multiple backends

Both tools take an optional backend param that looks up base_url/model/api_key from models.json instead of the default DELEGATE_* env vars — e.g. backend="ollama-local" for one call and backend="openrouter-free" for another in the same turn, each running concurrently. model, if also given, overrides just the model string within that backend.

Reference an env var for a key instead of writing it into models.json directly:

{
  "openrouter-free": {
    "base_url": "https://openrouter.ai/api/v1",
    "model": "nvidia/nemotron-3-nano-omni-30b-a3b-reasoning:free",
    "api_key_env": "OPENROUTER_API_KEY"
  }
}

models.json is gitignored, same as .env.

Concurrency

DELEGATE_MAX_CONCURRENCY (default 4, see .env.example) caps how many delegations — any command, any backend — run at once, to avoid a large fan-out overwhelming a local model server or a paid API's rate limits. It is an in-process semaphore, so use delegate batch to fan out rather than launching N copies of the CLI from a shell loop; see the CLI section below.

Logging

Every task/agentic call — success or failure — is logged to a local SQLite file, delegations.db (gitignored, created on first use): tool, backend, model, task text, start/end time, iteration count, success/failure, a truncated result/error preview, and token usage if the backend returned it. Query it with delegate list, or directly with sqlite3 delegations.db "select * from delegations order by id desc limit 20". Logging is best-effort — a logging failure won't take down an otherwise-successful delegation.

Both also append a trailing [tokens: N prompt / N completion / N total ($cost)] line to their own output when the backend reports usage, so you see it immediately without a separate delegate list call.

Cost tracking

The provider prices the call and tells us; nothing is looked up. OpenRouter returns a cost field on every response's usage object — no request flag needed — and that number is summed across a delegation's iterations, logged to delegations.db (cost_usd), and shown in the [tokens: ...] suffix.

The distinction that matters: a missing cost is unknown, not free. Ollama and other local endpoints have no such field, so those rows log cost_usd = NULL and print no dollar figure. A model that genuinely costs nothing — OpenRouter's :free variants — reports cost: 0, which is a fact and gets printed as $0.000000. Summing an absent field into 0.0 would render a paid run as free, which is the one error this must never make.

This replaced a hand-maintained pricing.json. That file mapped model → per-million rates and had to be re-fetched whenever a price moved or a model was added, and it could only ever cover models someone had remembered to enter. Provider-reported cost is ground truth, covers every model automatically, and cannot go stale. The two agreed where they overlapped: delegation 56 logged $0.01137843 from the table, which is exactly 353,970 prompt tokens at $0.03/M plus 5,841 completion tokens at $0.13/M.

Transcript capture (model comparison / eval runs)

Both take --capture-transcript (off by default). When set, the full message exchange — every model message, tool call, and tool result, not just the final answer — is logged, and the output gets a [delegation_id: N] suffix. Fetch it with delegate transcript <delegation_id>.

This exists for running the same task through several different models/backends and comparing not just the final answer but how each one got there (tool selection, malformed tool calls, retries) — e.g. a bake-off across candidate models before picking one for production use. Off by default since it's extra logging overhead you don't want for routine delegation.

CLI

delegate/__main__.py is the only front door. An MCP server used to sit beside it, exposing four of these commands as model-callable tools, but it was enabled in no project, never grew batch, and made every change a question of whether both surfaces had been updated. Delegation here is driven by a person or a script — which is what a bake-off or a batch run actually is.

py -m delegate task    "summarise this" --backend openrouter --model qwen/qwen3.7-flash
py -m delegate agentic --dir ./sandbox --task-file step-600.md --backend openrouter
py -m delegate batch   jobs.jsonl --out-dir results/
py -m delegate list    --limit 10
py -m delegate transcript 42

uv run delegate ... works too, via the [project.scripts] entry point.

--task-file is the point. A real task is paragraphs — a step file, a spec extract — and shell-quoting that is how a task arrives mangled. Every command taking a prompt also accepts - or a pipe, to read stdin.

batch, and why it exists

concurrency.limit_concurrency is an in-process semaphore. It caps parallel delegations inside one invocation and cannot see any other, so launching N copies of this CLI from a shell loop gives each its own cap and effectively removes it — a real way to trip a provider's rate limit or swamp a local Ollama. batch runs every job in one process, under one semaphore.

Jobs are JSONL, one per line; # comments and blank lines are skipped. A job with a dir runs agentic, one without runs single-shot; every other key matches the corresponding function argument.

{"name": "step-900", "task": "...", "dir": "./sandbox", "backend": "openrouter", "model": "qwen/qwen3.7-flash"}
{"name": "smoke",    "task": "Reply with exactly: OK",   "backend": "openrouter"}

One job failing does not stop the rest. Each result lands in --out-dir/<name>.txt (or stdout), failures included, and the exit status is non-zero if any job failed.

A retired model is an ordinary outcome, not a crash

Free-tier model ids get withdrawn without notice — nvidia/nemotron-nano-9b-v2:free began 404ing three days after the bake-off measured it. The CLI prints that as one error line rather than a traceback; pass --traceback when you want the stack because it really is a bug.

Tools

• delegate_task(prompt, model=None, system_prompt=None, backend=None, capture_transcript=False) -> str — single-shot chat completion against the configured backend.

• delegate_agentic_task(task, working_dir, model=None, max_iterations=20, timeout_seconds=600, backend=None, capture_transcript=False) -> str — multi-step delegation with read_file/write_file/run_bash tools scoped to working_dir. Returns only the final answer, not the full transcript, unless capture_transcript=True. read_file on an image file shows it to a vision-capable model as an actual image — see "Vision" above.

• list_recent_delegations(limit=20) -> list[dict] — most recent logged delegations, newest first.

• get_delegation_transcript(delegation_id) -> list[dict] — full transcript for one delegation logged with capture_transcript=True.

delegate_task/delegate_agentic_task return errors (bad config, unreachable endpoint, timeout, iteration cap) as "Error: ..." strings rather than raising, so a calling agent can see what went wrong.