Hand a coding or review task to a cross-vendor lane — a cheap, non-Claude
agent that does the work for you. Use this INSTEAD OF shelling out to any CLI: it
picks the vendor, injects the correct per-vendor permission flags, captures all
output synchronously, and reports a real status. Do NOT run `agy`/`devin`
yourself in Bash — the raw CLIs take DIFFERENT per-vendor flags (pass the wrong
one and a build silently makes ZERO edits yet exits 0), and hand-driven
background calls flush output late (a finished call looks empty for tens of
seconds). This tool is the only robust path.
First call `list` — it needs no setup, confirms cross-vendor is enabled, and
shows each vendor's selectable_models + default_model. If dispatch/review return
a disabled error, cross-vendor is OFF: run `nucleus onboard` once (one-time),
then retry.
Actions:
dispatch - Hand a task to a cross-vendor lane.
params: {vendor, prompt, artifact_ref, mode?, model?, expect_paths?, to?}
REQUIRED: vendor ∈ 'agy'|'devin', prompt, artifact_ref.
mode ∈ 'write'|'read' (default 'write'):
write = the vendor CHANGES things (edit files, run commands, build/fix).
read = the vendor only LOOKS and REPORTS (analyze/summarize); no file changes.
When unsure use 'write': a read task still works in write mode, but a write
task silently does NOTHING in read mode.
model? — optional. Defaults to the vendor's verified model
(agy → gemini-3.1-pro-high, devin → glm-5.2). These are ALREADY the
defaults, so omitting model is sufficient; pass it only to be explicit or
to override. The response echoes model_id — read model_id (NOT model_family)
to confirm which model ran. A cross-wired model (e.g. glm-5.2 with agy) is
rejected with the valid ids named.
artifact_ref — a commit SHA / PR# / file path to bind the result to. No commit
yet (a from-scratch build)? Pass the repo-relative path you will write,
e.g. src/foo.py.
expect_paths? — optional list of file paths you expect the vendor to change.
If you pass them and the vendor changes none, status comes back NOT success
("no_files_touched") even if it narrated success. Without expect_paths,
success means only that the vendor produced output — not that it edited
anything, so ALWAYS confirm with your own `git diff`. (Paths are checked in
the nucleus server process's working dir; pass paths valid there.)
You never pass CLI flags — the tool injects the right permissions per vendor.
Example (build): action="dispatch", params={"vendor":"devin","prompt":"<task>",
"artifact_ref":"src/foo.py","mode":"write","model":"glm-5.2",
"expect_paths":["src/foo.py"]}
review - Independent, different-model verdict on pasted code / a diff.
params: {content, ref?, vendor?, model?, to?}
content REQUIRED (paste the code/diff inline). Default vendor agy (Gemini,
model gemini-3.1-pro-high) — a genuinely different model from the devin/GLM
builder, so the review is diverse. Read-only, edits nothing. Returns a terse
two-line verdict. For a devin/GLM second opinion pass vendor='devin'.
Example: action="review", params={"content":"<code or diff>",
"model":"gemini-3.1-pro-high"}
list - Show vendors, their selectable_models + default_model, the mode vocabulary,
and whether cross-vendor is enabled. Needs no setup — call it first.
A green result is a hypothesis until you verify it on your own shell (zero-trust).
Read the response's `status` and `success`: 'ok' = produced output; 'empty_output'
/ 'no_files_touched' / 'timed_out' / 'error' come back success=false — NOT done.
(If NUCLEUS_ENVELOPE is on, gate on the INNER success flag, not the envelope's ok.)
Two caveats from real use:
- SECRET HYGIENE: vendor OUTPUT is best-effort secret-redacted (Bearer/JWT/API-key
patterns -> <REDACTED>; the count is in the response `redacted` field). This is a
BACKSTOP, not a guarantee — never put credentials in a prompt, and the tool CANNOT
scrub a file the vendor writes itself, so review any vendor file-writes near secrets
yourself before trusting them.
- REVIEW SEES ONLY WHAT YOU PASTE: 'review' (and 'dispatch') cannot read the repo, a
diff, or any file — they judge only the text in your params. Paste the real code/diff
or the reviewer will confidently critique things it cannot see. For a whole PR, paste
the actual diff, not a description of it.