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.

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.