Host support: Gemini CLI — native extension manifest, MCP, commands, skills, and hook codecs

[ScriptedAlchemy]

Scope / research status

P2 feature expansion. Researched 2026-09-06 against official Gemini CLI documentation. Agent Bundle baseline 5fc8de37c9695b816d55bdcf18a6bcb1dfee69f5; no Gemini installation or authenticated test executed. Pin the actual supported CLI/source revision during implementation. This issue covers Gemini CLI; Antigravity product/CLI compatibility must be established separately, not inferred from Ponytail's renaming claim.

Authoritative references

• Extension manifest and management reference
• Hooks wire contract and event-specific outputs
• Custom command TOML format
• Agent Skills
• MCP server transports/configuration
• Official implementation
• Ponytail extension example — consumer evidence only

Host contract

A native extension has root gemini-extension.json; installed extensions live beneath ~/.gemini/extensions. The manifest provides identity, optional context-file selection, and MCP configuration. ${extensionPath} is the supported relocatable anchor. Commands use TOML; skills use skills/<name>/SKILL.md. Hooks are discovered from hooks/hooks.json, not an invented manifest hooks property.

Hook input is JSON on stdin; stdout is the result protocol, not a logging channel. Event output semantics differ: BeforeTool can block or adjust tool input; AfterTool can affect returned content; lifecycle/notification events have distinct control capabilities. Do not map every nonzero exit or continue field to the same canonical behavior. Unsupported control effects must be diagnosed rather than silently discarded.

MCP supports local and remote transports through host configuration. Credentials, OAuth and trust belong to Gemini. Extension settings may declare required environment inputs; sanitized host environments mean blindly inheriting the developer shell is not a valid runtime contract.

Example output and configuration

Illustrative generated layout (not an implemented Agent Bundle API):

composite-root/
  gemini-extension.json
  GEMINI.md
  commands/review.toml
  skills/review/SKILL.md
  hooks/hooks.json             # Gemini-specific native document
  hooks/tool-before.gemini.mjs
  mcp/example.mjs              # only when MCP is declared

{
  "name": "example-plugin",
  "version": "1.0.0",
  "contextFileName": "GEMINI.md",
  "mcpServers": {
    "example": {
      "command": "node",
      "args": ["${extensionPath}/mcp/example.mjs"],
      "cwd": "${extensionPath}"
    }
  }
}

A simple commands/review.toml contains an authored description and prompt:

description = "Review the selected change"
prompt = "Review the selected change using the plugin's review guidance."

Do not convert arbitrary application strings into command shell interpolation. Any argument/file/shell expansion syntax must follow the native command parser and trust semantics.

Installation / development / removal

gemini extensions install ./composite-root
gemini extensions install https://github.com/example/plugin --ref v1.0.0
gemini extensions link ./composite-root
gemini extensions disable example-plugin --scope workspace
gemini extensions enable example-plugin --scope workspace
gemini extensions update example-plugin
gemini extensions uninstall example-plugin

Ordinary install copies content; local link is a separate development mode. Restart/session adoption rules matter: do not promise that every edit changes an already running session. Preserve native prompts; do not add --consent as an automatic approval bypass. Use normal host commands and record only registrations/data Agent Bundle actually owns.

Critical composite conflict

Agent Bundle's existing Claude projection requires conventional hooks/hooks.json. Gemini also auto-discovers that filename but expects its own event names and result codec. Ponytail avoids the conflict by moving its Claude/Codex hook file; that does not prove Agent Bundle can move every native conventional path.

The adapter must establish an effective-discovery contract for a combined selection. If both hosts' hooks cannot coexist without leakage under documented rules, reject that particular combination with a precise diagnostic or expose an explicitly separate installable projection. Never emit a merged foreign event map and call it composite support. Static/skills/MCP-only combinations may still be valid; test them separately.

Also test user/workspace MCP name precedence and extension-command collisions rather than silently renaming canonical operation identities.

Implementation plan

1. Add a versioned native extension projection over existing content/operation/executable records; initially enable only verified capabilities.
2. Generate TOML commands and a deterministic context artifact from authored content. Preserve intentional variants; no automatic summarization.
3. Add Gemini hook input/output codecs with per-event block/observe/transform capability metadata.
4. Lower MCP launch records using ${extensionPath}, preserving argv, cwd and declared environment without embedding secrets.
5. Keep preflight cheap and reuse canonical execution; no standalone Gemini orchestration runtime.
6. Teach install/inspect/Workbench to report exact supported projections and absent capabilities without spawning unnecessary processes.

Acceptance

• Native parser accepts the generated manifest, command, skill and hook documents at the pinned version.
• Static-only output has no synthetic MCP/Flight/state runtime.
• Deterministic before-tool deny prevents a sentinel action; success/error/after-tool context use the actual Gemini contract.
• A generated MCP tool succeeds from a relocated/read-only artifact, with declared environment and no source checkout.
• Test discovery collisions with Claude/portable and reversed target order; incompatibility is explicit, not leakage.
• User/workspace configuration and permissions keep native precedence.
• Installed-copy versus linked-development update behavior is proven; cleanup preserves foreign files and state.
• Record real native invocation and hooks evidence separately from synthetic parser tests.
• English/Chinese setup docs link the pinned contract and explain supported combinations.

Reuse src/adapters, src/build/compose.ts, canonical manifest/evidence, existing install receipts, #651 conformance and #652 small-plugin tests. No global relaxation of AB4106, credential storage, terminal UI requirement, or domain-policy ownership.

[ScriptedAlchemy]

Resolved by #723 (4dc11a4a06).

Gemini CLI — observed @google/gemini-cli 0.58.0, installed and exercised 2026-09-06. Supported at the skills tier: the emitted skill tree loads; the manifest does not.

Surface	State	Evidence
manifest	unavailable	2026-09-06: gemini extensions validate /tmp/hostcli/fixture on 0.58.0 exited 1 with "Configuration file not found at /tmp/hostcli/fixture/gemini-extension.json" — Gemini CLI requires its own gemini-extension.json manifest, which this projection does not emit, and gemini extensions list then reported "No extensions installed."
skills	supported	2026-09-06: 0.58.0 parsed the emitted SKILL.md frontmatter and listed the skill as review [Enabled] with Description: Review a change from ~/.gemini/skills/review/SKILL.md.
mcp	unavailable	2026-09-06: Gemini CLI reads MCP servers from the mcpServers map of its own gemini-extension.json manifest or a settings.json (https://geminicli.com/docs/extensions/reference/, last updated May 14, 2026); with the manifest rejected, the emitted mcp.json is never consulted, and the skills install path copies only the skill directory.
placeholders	unavailable	2026-09-06: Gemini CLI documents ${extensionPath} for portability inside its own manifest, not the reserved ${PLUGIN_ROOT} and ${PLUGIN_DATA} of Agent Plugins 1.0.0 §9.1; no emitted document that carries those tokens is read at this tier.
hooks	unavailable	2026-09-06: Gemini CLI loads extension hooks from hooks/hooks.json and states "hooks are not defined in the gemini-extension.json manifest" (https://geminicli.com/docs/extensions/reference/); Agent Plugins 1.0.0 defines no hooks, so this projection emits no hooks document for it to read.

Paths it reads: skills.
Install: gemini skills install <plugin directory>/skills/<skill>.

Every row above is pinned to that client's own documentation on the date shown, is validated on every build, and renders in INSTALL.md and the generated hosts reference. A surface recorded unavailable or degraded names exactly what the client would need; no unsupported feature is projected silently.