vx dispatch

Dispatch a soldier (mission or scout) into an isolated camp.

Usage:
  vx dispatch <prompt> [--kind mission|scout] [--profile <name>] [--model <model>] [--effort <level>]

A mission changes code and delivers something to land; a scout only
investigates and reports back (default: mission).

--model and --effort are passed straight through to the harness's real CLI.
On claude (the default): --model haiku, sonnet, opus or fable; --effort low,
medium, high, xhigh or max. On a profile that selects the pi harness: --model
is a provider/id such as anthropic/claude-sonnet-5 (it becomes pi --model) and
--effort is a thinking level, off, minimal, low, medium, high, xhigh or max (it
becomes pi --thinking, which pi clamps to what the model supports). vexillum
only validates the value has the right shape for the harness - it never picks
one for you.

--profile <name> looks the model and effort up in the profile table
('vx models' lists it: <project>/.vexillum/models.json over the
optional ~/.vexillum/models.json over the built-in defaults). An explicit
--model or --effort still wins over the profile. An unknown profile is
an error listing the valid ones; "default" selects the table's default
entry. Which profile fits a task is your call. See the vexillum skill.

A profile may also name the harness (the agent CLI) its soldier runs on, in
models.json: "claude" (the default when it names none), "pi" or "opencode". The
harness is recorded on the task and kept by 'vx redispatch'. A pi
soldier is answered as free text when it blocks (it has no question selector
to press a key in), and needs the pi CLI on PATH.

On a profile that selects the opencode harness, --model is provider/model with
an optional #variant, such as opencode/glm-5.3-flash-free or
anthropic/claude-sonnet-5#high ('opencode models' lists them), and --effort is
only a label that is recorded on the task: it is never turned into an OpenCode
variant, because variant names differ per model. Both OpenCode 1.x (from
1.18.29) and 2.x are driven; the version found on PATH is detected at dispatch
and recorded, and re-dispatch, prompt and decide keep using it. On 2.x the
soldier gets its own OpenCode session on that model and variant, created
through the OpenCode background service (which dispatch starts, from an
environment without OPENCODE_CONFIG, OPENCODE_CONFIG_DIR and
OPENCODE_CONFIG_CONTENT, when none runs) and opened with opencode --session.
Dispatch first checks the provider, model and variant against what OpenCode
lists for the camp, and fails naming what exists when one is not there.
Nothing is written into the camp or the project: its own opencode.json or
opencode.jsonc, agents, default agent and permission denies apply untouched.
The session id is recorded on the task and re-dispatch reuses it. An opencode
soldier is answered as free text when it asks a question, and needs the
opencode CLI on PATH. See 'vx doctor'.

Runs a real, interactive session of the harness (Claude Code by default, with
--dangerously-skip-permissions; pi has no permission prompts to skip and is
started with --approve so it never stops to ask whether to trust the camp) in
a herdr pane, inside a fresh git worktree isolated from this project's own
working tree: the soldier has full host access under
the invoking OS user (no container, chroot, or other sandbox) - the
worktree only bounds where its commits land, not what it can read,
write, or exfiltrate elsewhere on the machine. Nothing reaches the
project's real history until 'vx land' is explicitly approved;
never dispatch against a prompt, repository, or machine where reading
sensitive host state would be a problem. Requires HERDR_WORKSPACE_ID (run
this from inside a herdr-managed pane) and both herdr and the harness's CLI
(claude, pi or opencode) on PATH; if any is missing it says so and exits before
creating anything ('vx doctor' checks your setup).

The task records the commander that dispatched it: the project its Stop hook
await drains and its herdr pane (HERDR_PANE_ID), found from the live await of
that pane, else from where the pane's agent works. The sentinel puts the
soldier's wakes in that commander's own project, so a commander working in one
repository can dispatch into another and still hear the soldier finish. When
the two projects differ, dispatch warns, since status, land, strike and prompt
still run from the project the soldier was dispatched into. Outside a herdr
pane nothing is recorded and the wake stays in the task's own project.

Returns quickly: it submits the prompt and stops waiting as soon as the
soldier is seen working (or has already settled), not for its whole task. A
trivial prompt that settles at once reports its result immediately; anything
else is left running and auto-starts a sentinel (if one isn't already watching this project) to
record its final status. See 'vx sentinel'.