run_subagent

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.

Workspace authorization: an unapproved workspace makes this call wait in place for the user to approve the notification Fluxion just raised (up to FLUXION_MCP_AUTHORIZATION_WAIT_MS, default 60s), then run normally — so an approved task usually needs no follow-up at all. If the user has not answered by then it returns error_code=WORKSPACE_NOT_AUTHORIZED with pending=true and an authorization_request_id. That is a pending HUMAN decision, not a transient failure, so retrying right away cannot succeed: call wait_for_authorization with that id instead of ending your turn to ask the user to report back. Retry this call only when the wait reports approved (pass the same id) or project-allowed (pass no id). If it reports denied, report the refusal instead of re-requesting.

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.

reasoning_effort: optional per-run reasoning depth, e.g. "low", "medium", "high", "xhigh", "max". Valid values differ per model — read models[].supported_reasoning_efforts from list_agent_models; asking for one a model does not publish returns error_code=MODEL_UNRESOLVED listing what it does publish, rather than silently running at a neighbouring effort. Leave empty for the model's own default. Antigravity encodes effort in the model id (gemini-3.7-flash-high); pass models[].id plus reasoning_effort and Fluxion selects the published variant, or pass one of models[].variants verbatim. The run payload reports what was actually used as effective_model / effective_reasoning_effort.

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.