[Feature]: Expose mavis orchestrator via `mcode exec --team` (CLI parity with Desktop GUI Team button)

Bắt đầu bằng cách tái hiện các tùy chọn còn thiếu --team và --agent với mcode exec, sau đó đọc cơ chế dispatch Task hiện có của mavis và template delegation.md.hbs được đề cập trong issue. Theo dõi cách nút Team trên GUI đi tới cơ chế đó và cách CLI hiện đang xử lý --model, các session và output. Hoàn tất khi một đường dẫn CLI dựa trên roster được tài liệu hóa tái sử dụng orchestrator hiện có với các handoff có thể kiểm tra, xử lý vòng đời và output tổng hợp.

Problem

mcode exec (v0.2.6, verified 2026-08-27) is a single-agent executor with no native multi-agent dispatch. The Desktop GUI has a Team button that triggers mavis to orchestrate sub-agents, but the CLI does not.

Why this matters strategically

Exposing the full power of mcode via the CLI is not just a parity
fix — it is what lets MiniMax realize the maximum capability of this
harness and of MiniMax as a platform company.

The whole point of an agent harness is to give a single human (or
agent) leverage: instead of writing code, you describe a goal and the
harness coordinates the work. Today, the harness coordinates only
one agent through the CLI — the moment a task needs a writer +
verifier + synthesist (which is most real research, code-review,
ingest, and data-pipeline work), the user is pushed into either GUI
mode or fragile shell-fan-out. Neither scales.

If the CLI exposes mavis's orchestrator the way the GUI Team
button already does, then any human — or any other agent — can have
an agent team enabled, harness-controlled complex job achieved, by
simply entering a line of CLI code:

mcode exec --team roster.yaml -o final.md "verify this filing"

That single line replaces:

• A click path through the Desktop GUI.
• A hand-written orchestration prompt that encodes five different
  sub-agent instructions, output paths, wait conditions, and
  handoff rules.
• A bespoke shell script that launches N parallel mcode exec
  processes and tries to glue their outputs back together.

Making the CLI a first-class surface for multi-agent work turns
mcode from "a coding agent with a team mode" into "an agent
harness that any user can drive end-to-end from a terminal or from
another agent". That is the version of the product that earns the
"platform" framing — and it is the version that agents (including
MiniMax-built ones) can call without permission-grants, without GUI
sessions, and without ad-hoc wrappers.

The GUI Team button is the proof of concept; the CLI flag is what
makes it platform-grade.

Reproduce the missing flag:

$ mcode exec --team
error: unknown option '--team'
$ mcode exec --agent verifier
error: unknown option '--agent'

The only flags available are --config / --cwd / --input-format / --max-steps / --output-format / --output-last-message / --output-schema / --permission / --timeout / --model / --session / --continue / --input / --file. There is no --team, no --agent-profile, no --orchestrator, no --subagent-roster.

This forces any CLI user who wants multi-agent work (e.g. writer→verifier→synthesist, ingest pipelines, parallel scrapers with handoff) to either:

1. Encode the entire sub-agent plan into the prompt — including the names, output paths, "wait for all sub-agents before synthesizing", and disjoint file-ownership rules. If any of those five instructions is missing, the main agent silently does all the work itself and the deliverable looks like multi-agent evidence but isn't.
2. Shell-level fan-out of N parallel mcode exec processes — no shared coordinator, no handoff log, no synthesis visibility. This is the failure mode I hit on 2026-08-27 (launched 4 parallel execs for a verification task; 2 sub-agents failed silently; the synthesist had no inputs and did the work inline, producing a report that looked tier-tagged but wasn't).

Both options are worse than what the GUI Team button does. They are also worse than what mavis's internal Task tool already does when a parent agent delegates to a child — the runtime clearly knows how to manage sub-agent lifetime, handoff logging, foreground/background discipline, and disjoint ownership (delegation.md.hbs in the dist). The CLI just has no entry point into that machinery.

Proposed solution

Expose the existing mavis orchestrator behind CLI flags. At minimum:

# Sub-agent roster as JSON / YAML file (or inline)
mcode exec \
  --team agents.yaml \
  --cwd ~/work/dennis-1988 \
  --model minimax/MiniMax-M3 \
  --permission smart \
  --max-steps 25 \
  --timeout 8m \
  -o final.md \
  "Verify Richard Dennis's 1988 inflation claims across historian + economist sub-agents"

# agents.yaml (or .json) example
roster:
  - name: verifier
    role: source-integrity
    output: verifier.md
  - name: historian
    role: data-pull
    output: historian.md
    background: true
  - name: economist
    role: causal-logic
    output: economist.md
  - name: synthesist
    role: synthesis
    waits_for: [verifier, historian, economist]
    output: final.md
synthesis:
  wait_for_outputs: [verifier.md, historian.md, economist.md]
  handoff_log_required: true
  final_file: final.md

Behaviors the GUI Team button already implements and that the CLI should reuse:

• Sub-agent lifetime managed by mavis (spawn → work → return → terminate), all in the same session / workspace / scratchpad.
• Handoff log enforced by the runtime, not left to the prompt.
• Foreground / background discipline — background: true only for independent work; parallel writers must have disjoint file ownership.
• Task registry — sub-agent work auditable via mavis session list / session messages.
• Per-sub-agent model — model: field in the roster, instead of inheriting the parent --model.

What the CLI should NOT have to invent:

• A new orchestrator. Reuse mavis's Task tool dispatch.
• A new handoff format. Reuse the existing delegation.md.hbs template.
• A new model-routing layer. Reuse the existing --model plumbing.

The CLI change is essentially: add --team <file> (or --team <inline-json>), have mcode exec instantiate mavis as the parent, and have mavis fan out per the roster.

Optional follow-ups that would also help:

• mcode team list / mcode team validate agents.yaml — schema-check the roster before launch.
• mcode team init <name> — scaffold a new agent template under ~/.mcode/agents/<name>/ (mirroring the assets/agents/verifier/ / worker/ / explore/ built-ins).
• Document the existing CLI gap in docs/code/cli/quick-start so users don't waste hours encoding multi-agent plans into single-agent prompts.

Platform

• macOS
• Windows
• Linux desktop support
• All desktop platforms

Additional context

• MiniMax Code v0.2.6 (CLI), installed via npm.
• mavis delegation.md.hbs already encodes the rules the CLI would need: foreground when result blocks next decision; background only for independent / long-running work; parallel writers must have disjoint ownership; the child does not inherit conversation history — the parent must brief it with objective / known facts / scope / acceptance criteria / output format.
• Failure case that produced this request: 2026-08-27 verification of Richard Dennis's mid-1988 inflation claims in Market Wizards. Launched 4 parallel mcode exec calls — historian and economist sub-agents returned with Runtime completed without a final assistant response and Web search is down; the synthesist had no inputs and did the work inline, producing a 15KB "synthesis" that looked tier-tagged but wasn't. The whole failure is a direct consequence of the CLI not exposing mavis's orchestrator.
• I have not seen any open issue requesting this exact CLI feature. Searched: cli subagent, --team, --agent, orchestrate. Closest match is #120 (mavis CLI removal) and #101 (web mode), neither covers team-mode CLI.

Before submitting

• I have searched existing issues.