Submit a local Fluxion executor as a sub-agent task.

By default (wait_for_result=false) this returns as soon as the task is queued: you get a run_id — poll get_task_status and read get_task_result once terminal. Set wait_for_result=true for small smoke checks that should block until done; if the wait elapses first the task continues in the background (queued or running, bounded by task_timeout_sec) and is collected later via get_task_result with the run_id (the run is not canceled). For long or open-ended work prefer the default. timeout_sec only limits this blocking wait; it is not the executor runtime limit. The actual task execution cap is settings.task_timeout_sec.

agent: "auto" (default; uses the configured default) or one of "claude", "codex", "antigravity".

workspace: directory the agent runs in. With a configured project, "." is the project root. WITHOUT a project (the default), pass an ABSOLUTE path to the target repo — "." resolves against the server's workspace_root, not the caller's cwd, so it is rarely what you want. Use list_projects to see configured projects.

profile/mode: for edit/fix/implement tasks set profile=implement and mode=workspace-write; the defaults profile=inspect / mode=read-only are intentionally read-only.

task_name: optional free-form label for the run. It is shown as-is in the UI and also slugified into the agent-path segment (lowercased, non [a-z0-9] runs collapsed to _), so spaces, uppercase, and hyphens are all accepted — no need to pre-format it.

model: optional per-run model override for executors that support model selection. Leave empty to use the executor's configured/default model. To choose explicitly, call list_agent_models first and pass one of the returned models[].id values. Do not pass price_references[].id; those entries are pricing context only and may not be accepted by the executor. model is not a provider selector: provider, base URL, and auth remain settings-level configuration. Ping tasks keep their cheapest-model default unless model is explicitly set.

thread / session_policy scope which executor session is reused. Default (empty thread) = a FRESH isolated session per call: independent tasks don't resume, so they can't inherit stale context or have their workspace edits reconciled away by a resumed agent. To CONTINUE a prior run (resume — reuses the agent's context, saving tokens), pass the SAME stable thread string on each call. session_policy is "auto" (default), "continue", or "new" (force a brand-new session even for a reused thread). Note: a resumed Antigravity run may reconcile the workspace to its remembered state, so avoid editing the workspace out-of-band between two same-thread runs.

Results: both are finalized only at terminal status (changed_files_available stays false until then). changed_files is the authoritative, run-scoped list of what THIS run touched — act on it. diff_summary.files mirrors that count, but its additions/deletions are NOT measured per run and are always 0, flagged by lines_counted=false — a whole-tree git diff --stat would fold in pre-existing edits and earlier runs, so no line total is reported rather than a misleading one. For exact line counts, run git diff over the changed_files yourself.

artifacts is not an inventory of files the run produced: it lists only files the agent explicitly declared for delivery via ACTIONS_JSON.upload_files, which it is prompted to do only when asked to send files. Screenshots and other by-products of the work appear in changed_files, not here.

List likely selectable models for one executor, sorted high to low.

Codex uses codex debug models when available. Antigravity uses agy models when available. Claude Code does not expose a stable local model catalog, so models[] contains known CLI aliases and the configured model. Every catalog is enriched with the local price table when possible.

Pass a chosen models[].id to run_subagent(model=...). price_references[] is pricing context only and may not be valid as a model override. Provider, base URL, and auth remain settings-level config.

List configured Fluxion projects available for sub-agent runs.

Return one configured Fluxion project by key.

List recent Fluxion sub-agent runs from the local task store.

Get model-friendly status and next action for a Fluxion run.

The default response is compact for polling. It includes the run status, terminal/cancel hints, progress_signal, recent_output_tail, log freshness, and next_action. Pass detail=true to include the full status view with repeated metadata such as timestamps, subagent metadata, changed_files, diff_summary, artifacts, and change_set_file.

Pass wait_ms > 0 to long-poll: the call blocks until the run reaches a terminal status or the wait elapses, then returns. wait_ms is capped at FLUXION_MCP_STATUS_MAX_WAIT_MS (default 60000 = 60s) to stay under the MCP client's per-call request timeout, so a still-running task just returns RUNNING — call again to keep waiting. This collapses a busy-poll loop into one blocking call per cap. Raise the env var if your client tolerates longer requests (set it to the client's tool timeout minus a margin).

Request cancellation for an active sub-agent run in this MCP process.

Cancel a run that plain cancel_subagent_run cannot reach.

Use after cancel_subagent_run reports the run is unknown to this process, or a run has been non-terminal far longer than it should be.

Runs are owned by the Fluxion process that started them. If this process owns it, the request is delivered to the executor and terminates its whole process group. If another LIVE process owns it, this reports that owner and changes nothing — closing the record here would leave that agent running. If the owner is gone, the run is closed out as INTERRUPTED.

Close out runs whose owning Fluxion process no longer exists.

A process that dies mid-run leaves its tasks recorded as RUNNING forever; this marks those INTERRUPTED so status polls stop reporting work that is not happening. Runs owned by a live process are never touched. This also happens automatically when a Fluxion process starts.

Which Fluxion is serving this session, and what it is doing.

Returns the installation actually in use (code root, .env path, data dir, version, git commit), the settings THIS process loaded at startup, its queue/worker state, other live Fluxion processes, and current workspace locks with their holders.

Use it when a config change appears to have had no effect: config is read once at startup, and a dev checkout and an installed copy can each have their own .env. config_file_changed_since_start=true means the file was edited after this process read it — restart to apply.

Revert recoverable text-file changes recorded for one Fluxion run.

Get a model-friendly result view, optionally including raw output.

With include_output=true, stdout/stderr are the agent's own output. An executor runtime log (Antigravity's agy log) is returned separately as executor_log, with its transport-level glog chatter filtered out — folding it into stdout buried the agent's answer under hundreds of lines of plumbing. Pass raw=true for the unfiltered persisted record.