Fix: Antigravity Subagents Won't Run & SSH Crashes

Quick answer

If invoke_subagent fails with CORTEX_STEP_TYPE_INVOKE_SUBAGENT right after define_subagent reported success, stop defining subagents at runtime. Register them statically as .md files in your repo's .agents/agents/ folder, then run /agents. If a remote session throws Antigravity server crashed unexpectedly, the two highest-signal fixes are turning editor telemetry off (if you run pi-hole or DNS-level adblock) and enabling Antigravity under macOS Privacy → Local Network. Full detail and sources below.

Both bugs sit in the same place: the new Go-based agy CLI that ships with Antigravity 2.2.1. They are community-diagnosed, not officially patched, so this guide keeps every claim tied to the Reddit thread or GitHub issue it came from. Where a fix only applies to a specific setup (pi-hole, macOS, a particular version), that is called out.

Bug A: Subagents Won't Invoke After Definition

A developer on r/google_antigravity (thread 1ujqage) documented the core failure. You create a subagent at runtime with define_subagent, the CLI confirms it succeeded, and then invoke_subagent immediately rejects the exact agent it just told you to call:

> define_subagent test_agent_debug
Subagent 'test_agent_debug' defined successfully. It can now be invoked via invoke_subagent.

> invoke_subagent test_agent_debug
Encountered error in step execution: error executing cascade step:
CORTEX_STEP_TYPE_INVOKE_SUBAGENT: subagent "test_agent_debug" not found or not allowed to be invoked

The OP's diagnosis: "the runtime does not update or propagate its map of allowed subagents during the turn." In plain terms, the subagent you just defined is not yet in the allow-list the executor checks, so the very next step fails. A Google engineer (u/SoundDr) replied asking people to file it through /feedback in the app so it can be tracked. That is an acknowledgement, not a patch, so treat runtime define-then-invoke as unreliable until a fix ships. If you are also seeing the separate agent terminated error, that is a different failure mode with its own fixes.

The Fix: Static .md Subagent Config

The workaround the community actually runs (thread 1uk8vw9) skips runtime definition entirely and registers subagents statically. Two things matter:

Use .md files, not .json. Put them directly in ~/<repo>/.agents/agents/ — one file per agent (architect.md, engineer.md). There is no per-agent subfolder.
Put the config in YAML frontmatter. Here is the working frontmatter, verbatim from the report:

---
description: Technical Architect subagent...
kind: local
model: Gemini 3.5 Flash (Medium)
max_turns: 30
timeout_mins: 15
enable_write_tools: true
enable_mcp_tools: true
name: architect
---

Then run /agents and the subagents appear, ready for invoke_subagent. Because the definitions already exist on disk before the turn starts, they are in the allow-list from the beginning — exactly the state Bug A breaks. For orchestration, the same setup puts routing rules in ~/<repo>/.agents/AGENTS.md: a root Orchestrator delegates design to an Architect subagent, then fans out up to three Software-Engineer subagents in parallel through invoke_subagent, each running PYTHONPATH=. uv run pytest tests/ before handing work back.

One open request from thread 1u472t5 is per-subagent model routing. The model field in the frontmatter already lets you pick a model per agent, and people mix a cheap explorer (Gemini 3.5 Flash) with a stronger model for architecture; one setup pairs 3.5 Flash with GPT-5.5. The recurring complaint is cost — one commenter put it as "Claude models are pretty bad while being MUCH more expensive" — so treat the per-agent model choice as a cost lever, and benchmark it against your own tasks rather than trusting the quote.

Ignore the agent.json Message

When you run /agents, the CLI may tell you to create the config at .agents/agents/{name}/agent.json. GitHub issue #105 documents the CLI expecting agents at the workspace path ~/<repo>/.agents/agents/{name}/agent.json and the global path ~/.gemini/antigravity-cli/agents/{name}/agent.json. The poster in thread 1uk8vw9 reports that path did not work for them, and the flat .md files did.

Why this happens: first-party tutorials describe an orchestrator that auto-defines subagents, with names derived entirely by the CLI. That blessed dynamic path is the same one that triggers Bug A. The static .md config is a community reverse-engineering of what the runtime will reliably load, which is why it works when the documented dynamic route does not.

~/<repo>/.agents/
├── AGENTS.md            # orchestration rules (root Orchestrator)
└── agents/
    ├── architect.md     # kind: local, model, name: architect
    └── engineer.md      # one .md per subagent — no subfolders

# Documented fallback (GitHub issue #105) if .md ever stops loading:
#   ~/<repo>/.agents/agents/{name}/agent.json          (workspace)
#   ~/.gemini/antigravity-cli/agents/{name}/agent.json (global)

Bug B: SSH Server Crashed Unexpectedly

The second cluster of reports is remote development. On a macOS host connected to a remote Ubuntu box (thread 1ujioyq), Antigravity throws a popup while plain SSH keeps working everywhere else:

Antigravity server crashed unexpectedly.
Please restart to fully restore AI features.

# from the older cross-thread logs (1p0klc7):
ssh: connect to host <host> port 22: No route to host
SSH server closed unexpectedly

The tell is that plain ssh from a terminal works, VS Code Remote SSH works, and only Antigravity crashes. Reload and restart do not help. An older, larger thread (1p0klc7, 63 comments) collected the same class of failure and its fixes. If your crash is the desktop-app version rather than a remote session, the Antigravity server crashed fix walkthrough covers that path in more depth.

SSH Crash Fixes

Ordered by signal strength. Try them in this order:

Turn telemetry OFF (if you run pi-hole / DNS adblock). u/rowdyspark's diagnosis: DNS-level ad blocking makes Google's telemetry endpoints unreachable, and the failed calls crash the server. Disable telemetry in the editor settings and the crash stops. This is the highest-signal fix if you run a pi-hole.
Enable Antigravity under macOS Local Network. Go to System Settings → Privacy & Security → Local Network and toggle Antigravity on. If the toggle never appears, the 1p0klc7 thread suggests deleting /Library/Preferences/com.apple.networkextension.plist and the matching uuidcache.plist with sudo, then rebooting so macOS rebuilds them.
Install the remote server binary manually. Per thread 1tjoigw, an update can skip auto-downloading the Antigravity server on the remote host; installing it by hand restored SSH. Caveat: one user then hit a secondary bug where the Gemini panel loads indefinitely, and rolling back fixed SSH but left Gemini refusing to run on a "no longer supported" version. There is no clean single-version answer here yet.
Windows alternative. The 1p0klc7 thread's Windows workaround is to skip the SSH extension entirely: mount the remote with rclone as a drive and open that folder locally. Also disable extensions that leak your IP, user, or port (Discord Rich Presence was called out), then reconnect via Ctrl+Shift+P → Remote-SSH: Connect to...

Honesty note: none of these are Google-published fixes. They are user reports from macOS and Ubuntu setups. The telemetry fix is specific to people running DNS-level adblock, and the Local Network fix is macOS-only.

FAQ

Why does invoke_subagent say my subagent is not found or not allowed to be invoked?

Because a subagent created at runtime with define_subagent is not added to the runtime's allowed-subagent map during the same turn. The community diagnosis is that the executor checks an allow-list that was not updated, so the very next invoke_subagent step fails. The reliable fix is to define subagents statically as .md files before the turn starts.

Do I use .md or agent.json for Antigravity CLI subagents?

Community reports say flat .md files placed directly in your repo's .agents/agents/ folder work, while the agent.json layout the CLI suggests did not work for the poster. The .md approach is the reverse-engineered route people actually run; keep agent.json (GitHub issue #105) as a documented fallback.

Where exactly do subagent config files go?

In the workspace, put one .md file per agent directly in ~/<repo>/.agents/agents/ (for example architect.md and engineer.md, no per-agent subfolder). GitHub issue #105 documents the CLI also expecting a workspace path .agents/agents/{name}/agent.json and a global path ~/.gemini/antigravity-cli/agents/{name}/agent.json.

How do I fix Antigravity server crashed unexpectedly over SSH?

Two community fixes have the strongest signal. First, if you run pi-hole or DNS-level ad blocking, turn editor telemetry off, because unreachable Google telemetry endpoints crash the server. Second, on macOS, enable Antigravity under System Settings, Privacy & Security, Local Network. If the remote server binary never downloaded, install it manually on the remote host.

Why does SSH work in my terminal and VS Code but crash Antigravity?

Reporters note plain ssh and VS Code Remote SSH connect fine while only Antigravity crashes. That points to Antigravity-specific telemetry calls and macOS Local Network permission rather than a broken SSH setup, which is why the telemetry and Local Network fixes target the editor, not your SSH config.

Can I route different models to different subagents?

The .md frontmatter includes a model field, so each subagent can name its own model, for example Gemini 3.5 Flash (Medium). Users on the demand thread run mixed setups (a cheap explorer plus a stronger architect), and one pairs 3.5 Flash with GPT-5.5. Per-subagent routing is a requested feature area, so treat model choice as a per-agent cost lever.

Are these official fixes from Google?

No. The static .md config, the telemetry-off fix, the macOS Local Network fix, and the manual remote-server install are all community-reported from Reddit and GitHub issue #105. A Google engineer acknowledged the subagent bug and asked users to file it through /feedback, but no patch had shipped at the time of writing.

Glossary

agy: The Go-based Antigravity CLI. It replaced Gemini CLI for Google AI Pro/Ultra users on June 18, 2026 and runs the subagent orchestration described here.
Subagent: A delegated agent the root orchestrator calls to do a scoped task. In agy it is invoked with the invoke_subagent tool.
define_subagent / invoke_subagent: The runtime tools that create a subagent on the fly and then call it. Bug A lives in the gap between them.
CORTEX_STEP_TYPE_INVOKE_SUBAGENT: The internal cascade step that runs a subagent invocation. It is the step that errors when the target is missing from the allowed-subagent map.
Telemetry: Usage and diagnostic data the editor sends to Google. If those endpoints are blocked (for example by a pi-hole), the failed calls can crash the Antigravity server.
Local Network permission (macOS): A macOS Privacy setting under System Settings that Antigravity needs to reach remote hosts. If it is off, SSH-backed AI features can crash.

Verdict

Both bugs have working escapes, but neither has an official fix yet. For subagents, stop fighting the dynamic define-then-invoke flow — write your agents as static .md files in .agents/agents/ and they load into the allow-list cleanly. For SSH, the crash is almost always the editor's telemetry or macOS Local Network permission, not your SSH connection, so fix those before you touch your remote config. All of this is community-verified on Antigravity 2.2.1 as of late June 2026; if an update changes the config paths, the agent.json layout from issue #105 is the documented fallback. For more Antigravity errors and fixes, see the troubleshooting hub.

Sources

Grouped by bug. Community reports are labelled as such; treat setup-specific fixes (pi-hole, macOS) as conditional on your environment.

Bug A: subagents and config

Bug B: SSH server crash

Antigravity 2.2.1 + agy CLI guideWhat the Go-based CLI adds, and how subagents are meant to work.Antigravity server crashed fixThe desktop-app version of the crash, diagnosed step by step.Agent terminated errorA related agent failure mode, with its own set of fixes.