Skip to main content
Reference Last updated: 16 November 2026

Antigravity CLI → Untether events

Nathan Schram
By Founder, Little Bear Apps

How AntigravityRunner.translate() (src/untether/runners/antigravity.py) turns agy’s stream into Untether’s three-event contract: one StartedEvent, any number of ActionEvents, exactly one CompletedEvent. Line shapes are in the stream-json cheatsheet. Checked against agy 1.3.2; the subagent, timer and background rows against 1.3.3.

Mapping

agy lineUntether event
init with a conversation_idStartedEvent (once), resume token agy --conversation <id>, meta model · effort · permissionMode. Followed by any ⚠️ rows learnt before the run started
init without an idNothing. The id is taken from the first step_update or the result instead; an empty id never becomes a session
init reporting a permission policy other than request-review / strict when Untether didn’t pass the bypass flagagy is stopped; CompletedEvent(ok=False) with the “agy’s own settings change its permission checks” text
init (or first id) that differs from the --conversation id asked foragy is stopped; CompletedEvent(ok=False) “conversation no longer exists”; every later line is ignored
step_update tool, ACTIVEActionEvent started. Kind and title come from the shared tool vocabulary (see below)
step_update tool, DONE, with outputActionEvent completed, ok=True, with a 500-character output preview
step_update tool, DONE, no output, for a tool agy can blockHeld back. Closed ok=True when a later step arrives; turned into a ⚠️ Blocked row if result.denied_actions names its family
step_update tool, ERRORActionEvent completed, ok=False, with tool_info.error.message (a hook refusal lands here)
step_update tool, DONE with tool_info.errorThe same as ERROR (a step agy stopped itself ends this way: “context canceled”, #1062)
step_update tool invoke_subagent, ACTIVE (agy 1.3.3)ActionEvent of kind subagent started, titled <type>: <role> (+N for more) from parameters.Subagents[]
step_update subagent, ACTIVE / DONE / ERRORActionEvent of kind subagent, started (1.3.1 sends this type at ACTIVE too) / completed
step_update agent_responseNo event. text_delta is collected per step as the fallback answer
step_update agent_response, DONE, with usage, when init.model named a model with a known windowActionEvent updated, kind telemetry, id antigravity.context, only when the percentage changed. detail: context_pct, context_used, context_window, model, context_estimated: true. It feeds the header’s ~N% ctx and is never a step (#979)
step_update finish (or any type) closing a step that opened as a toolActionEvent completed
step_update user_input, system_message, checkpoint, unknown, anything newerNo event. A user_input injected mid-run is not a new run; with the gate, one after a steer injection adds a completed note action ↪️ steer received: … (detail.absorbed_command_uuid, #981). A system_message updates the background task map (below). An ask_question arrives as unknown; its card comes from the gate, not the stream (below). A DONE checkpoint is recorded: on a /compact run it is the confirmation that sets usage["compaction"] on the CompletedEvent (#1114)
Gate: PreToolUse for ask_question (socket, not stdout)ActionEvent(started, kind="warning") titled ❓ <question> with detail.request_id, ask_flow, inline_keyboard (option buttons + Other); completed as ❓ answered: …, ⏱️ No answer — agy carried on or ❓ question withdrawn … (#980, runner reference)
a run_command that counts as background, or a schedule / manage_task step ACTIVE for more than 5 sActionEvent updated, title ⏳ background: <command> (once, on the next line agy prints)
result SUCCESSOpen rows are closed, then CompletedEvent(ok=True). Answer is result.response, or the collected text when that is empty
result with denied_actionsA ⚠️ Blocked: <what> (<agy name>) — <title> row per denial, and a closing paragraph on the answer
result SUCCESS of a Plan first run, after a write_to_file DONE into brain/<conversation id>/ (#981)CompletedEvent(ok=True): the answer is 📋 Plan — <file>, the plan read from that file, then agy’s reply. usage["review_card"] = {"text", "buttons"} (Approve Plan / Deny / Let’s discuss, callback agy_plan:<action>:<id>), sent by the bridge as the final’s last message. A cron or webhook run gets usage["unattended"] (denied: {"plan approval": 1}, hint) instead of the card. No plan file: the ordinary answer plus a one-line note
result SUCCESS of a /compact run (#1114)After a checkpoint: CompletedEvent(ok=True) with usage["compaction"] = {count: 1, trigger: "manual", result: "success", manual_success: true} and the empty answer (the bridge shows 🗜️ Context compacted (manual)); /compact <message> keeps agy’s answer under 🗜️ Context compacted.. With no checkpoint, no compaction key and the answer Antigravity finished /compact without reporting a compaction, …. No plan review
/compact with no conversationNothing spawns: one CompletedEvent(ok=False) Nothing to compact: … with usage["prespawn_blocked"] = "compact_no_conversation" (a plain reply on the bridge)
result SUCCESS of the run an Approve startedThe answer starts 📋 Plan (approved) — <file>; the footer label is workspace · plan approved
Any CompletedEvent after ⚠️ rowsThe answer gets those rows appended after it, once each, one per line (the post-run config re-check’s rows included), because the final replaces the progress message that showed them (#1045). ⚠️ Blocked rows are left out: the closing paragraph already explains them
result ERROR + interruptedCompletedEvent(ok=False), resumable, “Antigravity was interrupted …”
result ERROR + other textCompletedEvent(ok=False) with agy’s text, redacted and trimmed to three lines
result with any other statusCompletedEvent(ok=False) antigravity ended with status <status>[: <error>]
command_resultIgnored during a run (used only by the /usage, /credits, /effort and /config probes)
a line that isn’t valid JSONA note row (invalid JSON from antigravity; ignoring line); the run continues. Leading non-JSON text before a { is skipped first
a JSON line with an event name Untether doesn’t knowDropped and logged (jsonl.msgspec.invalid), not shown

Ends without a result

What happenedUntether event
A stderr line of a stop class (signed out, account block, quota, credits, unknown conversation)agy is stopped; CompletedEvent(ok=False) with that class’s text. It also wins over whatever result agy then sends
Exit code 3, or an AGY_ERROR: lineCompletedEvent(ok=False) agy reported a model/agent error (<status>, retryable=…; …)
Any other non-zero exitCompletedEvent(ok=False) antigravity failed (<exit>) plus the session and a redacted stderr excerpt (300 characters)
Stream ended, exit 0, no resultCompletedEvent(ok=False) antigravity finished without a result event (or … but no session_id was captured)

In every case rows still open are closed first, so nothing is left “running”. A result that arrived before a late stderr error is kept.

Refused before agy starts

These yield a single CompletedEvent(ok=False) and keep the chat’s saved session:

Reason (prespawn_blocked)When
RAM / concurrency guardSame pre-spawn guard as every engine
no_projectNo project directory, or it is /, the home directory or the bot’s own directory, or its path can’t be resolved
invalid_argumentThe model id or the conversation id being resumed isn’t a valid value (it could be read by agy as a flag). The bad id is not kept as the resume token
gate_missingAsk me, and Untether’s agy plugin isn’t installed on the host (#980)
gate_not_readyAsk me, and the plugin is edited, outdated or disabled, agy doesn’t list its hooks for the project, the planted-config scan didn’t finish, or the run’s socket couldn’t open
gate_self_protectAsk me in a project that contains Untether’s own package, venv or plugin folder
gate_foreign_configAsk me in a project with agy hooks, plugins, agents or MCP servers Untether doesn’t manage (or user-level ones)
unsupported_versionagy is older than 1.3.1
continue_unresolved/continue found no conversation for this exact project directory, its latest one has also been run from another folder, or agy’s record of recent conversations couldn’t be read (#1039)
compact_no_conversation/compact in a chat with no Antigravity conversation yet (or after /new): nothing to compact (#1114)
config_changedUnattended run, and the project’s agy config differs from what an attended run last showed
config_uncheckedUnattended run, and that config couldn’t be checked
agy_always_proceedWorkspace run, and agy’s own settings report a toolPermission other than request-review / strict
tool_permission_unknownUnattended Workspace run, and the agy -p /config check failed or returned no toolPermission (#1044)

Background task map

Besides events, translate() keeps AntigravityStreamState.tasks, the map the bridge renders as the ⏳ background (N) block (#978). It emits no event of its own: the block is re-read whenever the progress message is drawn. Each entry is an EngineBackgroundTask (src/untether/background_tasks.py).

agy lineTask map
tool run_command, ACTIVEcmd:<step> added, listed from the moment it counts as background: IsDaemon / WaitMsBeforeAsync from the parameters if present, a later tool / subagent / agent_response step while it is still open, else 5 s
tool schedule, ACTIVEtimer:<step> added and listed at once (timer (<DurationSeconds>s))
tool invoke_subagent ACTIVE, or subagent ACTIVE / DONEsub:<step>:<n> per subagent, listed at once as <role> (<type>). DONE only adds the child’s conversation id: the children are still working
the run_command / schedule step DONE / ERRORRemoved if it never counted as background; otherwise completed / failed, and one system_message is expected for it. A DONE with a cancellation error is stopped (⏹️), with no notice expected (#1062)
tool manage_task ACTIVE with Action: killThe cmd:<step> / timer:<step> its TaskId (<cid>/task-<step>) names → stopped, if still running
the schedule step DONE with output Timer cancelled early: … met by a message from <sender>.The timer → completed; its expected notice is that message (agy sends no other for the timer). If <sender> is a running subagent’s conversation id, that sub: row → completed (attribution=sender) (#1086)
tool manage_subagents ACTIVE with Action: kill_all (or kill + ConversationIds)Every running sub: row (or the named ones) → stopped (source=manage_subagents); no notice expected (#1086)
invoke_subagent step ERRORIts subagents → failed
system_message DONESpends an expected notice if there is one; otherwise the oldest running subagent → completed (attribution=fifo)
any tool step ACTIVEExpected notices are dropped
result, or the run ending without oneEverything still running → ended (never failed: a daemon command is still running by design)

The state also offers two lines the bridge duck-types (#1061): background_hold_note(), the last line of the ⏳ background block, and cancelled_hold_note(), added to the cancelled progress message when a listed task was still running at /cancel (agy drops an answer it is holding when it is stopped).

Only run_command, schedule and manage_task steps count for the background wait (awaiting_background); a subagent row never does.

Tool vocabulary

agy toolShown as
run_commandbash (the command line is the title)
view_fileread
write_to_filewrite
replace_file_content, multi_replace_file_content, sed_fileedit
list_dirls
find_by_nameglob
grep_searchgrep
search_webwebsearch
read_url_contentwebfetch
invoke_subagenta subagent row titled <type>: <role>
ask_questionaskuserquestion
call_mcp_toolmcp: <server>/<tool>
browser_*browser: <action>
anything elseits own name, lower-cased

File paths are read from TargetFile, AbsolutePath, DirectoryPath, SearchPath, SearchDirectory, file_path, path or filePath.

Usage

CompletedEvent.usage carries input_tokens, output_tokens, cache_read_tokens, reasoning_tokens (agy’s thinking_tokens) and duration_ms (measured by Untether). agy’s totals are per conversation, so the bridge’s token ledger turns them into a per-run figure. num_turns and agy’s duration_seconds are conversation totals too and are not passed on.

When a context percentage was shown, usage["context"] holds {pct, used, window, model, estimated: true} for the runner.completed log (context_pct). used is the latest model call’s input_tokens + cache_read_tokens, not the summed input_tokens beside it. See Context use.

Session handling

  • Resume line: `agy --conversation <id>`; ids shorter than 8 characters are never parsed as one.
  • A failed resume clears the chat’s saved session only for the “conversation no longer exists” reply. Sign-in, quota and other errors keep it. So does a /continue that finds a deleted conversation: the reply is “The conversation Antigravity had recorded for this project no longer exists, so nothing was resumed”, with no resume token.
  • Antigravity is not a turn-counting engine, and its child processes don’t earn the long stall threshold except through the background wait described in the runner reference.
Was this helpful?

Related Articles