Adds first-class integration with Google's Antigravity IDE (https://antigravity.google/) as a third sibling to the existing Claude Code and Codex hook integrations. Strictly additive — no existing files in main are restructured. What ships ---------- * `.antigravity-plugin/` — verified-minimal plugin package: * `plugin.json` with `{"name": "mempalace"}` (no fabricated fields) * `mcp_config.json` registering the `mempalace-mcp` stdio server * `hooks.json.tmpl` templated with `__PLUGIN_DIR__` substitution * `skills/mempalace/SKILL.md` (real file — no symlinks) * `hooks/antigravity/`: * `lib/common.sh` — shared bash 3.2.57-compatible helpers with sentinel-guarded camelCase JSON parser, antigravity_*-namespaced state files, every existing kill switch, `MEMPAL_SAVE_INTERVAL >= 1` floor (no /0), and fail-open emitters * `mempal_save_hook_antigravity.sh` — Stop event handler: increments per-conversation counter, defers when fullyIdle=False or terminationReason=error, validates transcriptPath against `..` traversal, spawns `mempalace mine --mode convos` in a detached subprocess with a per-conversation pending marker, ALWAYS emits `{}` (never `{"decision":"continue"}` — that would force an infinite agent loop) * `mempal_wake_hook_antigravity.sh` — PreInvocation handler gated to invocationNum==1 with an atomic mkdir loop guard, runs `mempalace wake-up` with a 500ms hard timeout, emits verbatim output as `{"injectSteps":[{"ephemeralMessage":"..."}]}` or `{}` on any failure * `install.sh` — idempotent installer with cmp-gated copies, `__PLUGIN_DIR__` substitution, relative path absolutization, `--dry-run`, and basename-guarded `--uninstall` (refuses to wipe a directory whose basename isn't `mempalace`) * `INVESTIGATION.md` — verbatim quotes + URLs + dates from the five official Antigravity doc pages, recording every surface shipped and every surface deliberately omitted (PreCompact equivalent, slash-commands, rules/, plugin permissions field — the latter is third-party fabrication) * `STDIN_SHAPE.md` — exact stdin/stdout contract per event with worked examples * `README.md` — local hook docs + troubleshooting * `examples/antigravity/{hooks.json,mcp_config.json,README.md}` — standalone configs for users who don't want the full installer * `website/guide/antigravity.md` + sidebar entry — VitePress guide * Updates to `README.md`, `CHANGELOG.md` (Unreleased), `hooks/README.md` Tests (56 new, all passing) --------------------------- * `tests/test_antigravity_plugin_manifest.py` (11 tests) — schema contract on the in-repo `.antigravity-plugin/` directory, including guards against re-introducing the fabricated `permissions` field and against any symlink leak. * `tests/test_antigravity_hooks_shell.py` (31 tests) — invokes the bash hooks via subprocess with synthetic camelCase stdin, asserts `{}` on every failure path, kill-switch coverage (env vars + config.json + palace nuke), divide-by-zero floor, transcript traversal rejection, namespacing, wing inference, and the hard refusal to ever emit `decision=continue` from the Stop hook. * `tests/test_antigravity_hooks_install.py` (14 tests) — `--dry-run` side-effect-free, real install layout, executable bits preserved, byte-identical idempotent re-runs (md5 + filecmp), basename-match uninstall safety, refusal when plugin.json is missing or names a different plugin, relative path absolutization. Skipped on Windows. Verification ------------ * `uv run pytest tests/ --ignore=tests/benchmarks -v` → 2314 passed, 3 skipped (Windows), 1 unrelated warning * `uv run ruff check .` → all checks passed * `uv run ruff format --check .` → 139 files already formatted * `bash -n` clean on common.sh, both hook scripts, install.sh * Local install at `~/.gemini/config/plugins/mempalace/` verified end- to-end: layout correct, paths absolutized in hooks.json, both hooks fire with realistic camelCase JSON in <1s, wing inference picks `wing_mempalace` from workspacePaths[0], state files all `antigravity_*`-namespaced, second `install.sh` run produces byte-identical output (md5 snapshots match), uninstall removes only the mempalace plugin and leaves all 6 sibling Google plugins untouched. Constraints honoured -------------------- bash 3.2.57 (no mapfile / readarray / declare -A / `${var^^}`), verbatim guarantee on all wake injections, hooks <500ms / startup injection <100ms target (kill-switch path returns in <1.5s in CI), zero new runtime dependencies, no telemetry, no external API, strictly additive (existing Claude/Codex hooks unchanged). Refs: hooks/antigravity/INVESTIGATION.md for the full audit.
9.1 KiB
Antigravity hook STDIN / STDOUT contract
This file documents the exact wire format the Antigravity IDE uses
when invoking the MemPalace hook scripts. All fields are verbatim
from Google's official Antigravity hooks documentation
(https://antigravity.google/docs/hooks?app=antigravity, accessed
2026-05-27). See INVESTIGATION.md for the
provenance audit.
Wire format
Hooks receive JSON on stdin and must emit JSON on stdout. Field names are camelCase.
Hook execution timeout defaults to 30 seconds. The MemPalace plugin
sets the Stop hook timeout to 30s and the PreInvocation hook timeout
to 5s in the rendered hooks.json.
Common stdin fields (every event)
| Field | Type | Notes |
|---|---|---|
conversationId |
string | UUID of the active agent conversation. |
workspacePaths |
array | Absolute workspace dirs. First element is canonical. |
transcriptPath |
string | Absolute path to transcript.jsonl. |
artifactDirectoryPath |
string | Path to conversation artifacts and screenshots. |
Stop event
Stdin (additional fields)
| Field | Type | Notes |
|---|---|---|
executionNum |
integer | Sequence number of the execution attempt for this conversation. |
terminationReason |
string | "model_stop", "max_steps_exceeded", "error", etc. |
error |
string | Optional. Set when termination was caused by a system error. |
fullyIdle |
boolean | Required. True iff all background commands and async tasks have completed. |
Stdout
| Field | Type | Notes |
|---|---|---|
decision |
string | If "continue", forces the agent to keep running. Anything else allows the stop. |
reason |
string | Optional. If decision == "continue", injected as a system message into the conversation. |
MemPalace policy: the save hook ALWAYS emits {} and exits 0. It
NEVER emits {"decision": "continue"} — that would force an infinite
agent loop. There is an explicit refusal in
mempal_save_hook_antigravity.sh to ever construct a stdout JSON
object containing the literal word "continue" in a decision field.
MemPalace gating
The save hook short-circuits with {} (no save triggered) when ANY
of the following hold:
MEMPAL_DISABLE_HOOK=1(ortrue/yes) is set.MEMPALACE_HOOKS_AUTO_SAVE=false(or0/no) is set.~/.mempalace/config.jsonhashooks.auto_save: false.~/.mempalace/directory does not exist (user nuked the palace).- Stdin is malformed or empty (sentinel-guarded parse failure).
fullyIdle == false(background tasks still running; defer save).terminationReason == "error"(transcript may be corrupt).transcriptPathvalidation fails (not a.json/.jsonl, or..traversal).- The transcript file does not exist on disk.
- The save counter has not yet hit
count % MEMPAL_SAVE_INTERVAL == 0. - A pending save is still running for this conversation (less than 1 hour old).
- The
mempalaceCLI is not on$PATH.
When the modulo gate is hit and validation passes, the hook spawns
mempalace mine <transcript-dir> --mode convos --wing <inferred> in
the background and returns {} immediately.
PreInvocation event
Stdin (additional fields)
| Field | Type | Notes |
|---|---|---|
invocationNum |
integer | Sequence number of the current model invocation (1-based). |
initialNumSteps |
integer | Number of steps currently in the trajectory. |
Stdout
| Field | Type | Notes |
|---|---|---|
injectSteps |
array | Optional. Steps to inject before the model is called. Each step has one of: {"toolCall": {...}}, {"userMessage": "..."}, {"ephemeralMessage": "..."} |
The ephemeralMessage form is what the MemPalace wake hook emits — it
delivers the wake-up text to the model on this turn but does not
persist into the transcript, so subsequent invocations don't see a
duplicate.
MemPalace gating
The wake hook short-circuits with {} (no injection) when ANY of:
- Any kill switch trips (same five conditions as the save hook).
invocationNum != 1— we only inject on the first model call of each conversation, mimicking Cursor'ssessionStartsemantics.- The atomic
mkdir-based loop guard is already taken (this conversation already received a wake injection). mempalace wake-up --wing <inferred>exits non-zero, times out (500ms hard cap), or produces empty output.
When the gates pass and mempalace wake-up returns text, the hook
emits:
{
"injectSteps": [
{ "ephemeralMessage": "<verbatim wake-up output>" }
]
}
The wake hook NEVER emits a decision field — that field belongs to
the Stop event. There is a final guard against any stdout that
contains a decision key.
Worked example: Stop event
Input
{
"executionNum": 1,
"terminationReason": "model_stop",
"error": "",
"fullyIdle": true,
"conversationId": "ec33ebf9-0cba-4100-8142-c61503f6c587",
"workspacePaths": ["/home/me/projects/mempalace"],
"transcriptPath": "/home/me/projects/mempalace/.gemini/jetski/transcript.jsonl",
"artifactDirectoryPath": "/home/me/projects/mempalace/.gemini/jetski/artifacts"
}
Output (always)
{}
(Side effects: counter ~/.mempalace/hook_state/antigravity_save_count_<id> is
incremented; if the modulo gate fires, a background mempalace mine
subprocess is spawned with the transcript directory and the inferred
wing wing_mempalace.)
Worked example: PreInvocation, first invocation
Input
{
"invocationNum": 1,
"initialNumSteps": 0,
"conversationId": "ec33ebf9-0cba-4100-8142-c61503f6c587",
"workspacePaths": ["/home/me/projects/mempalace"],
"transcriptPath": "/home/me/projects/mempalace/.gemini/jetski/transcript.jsonl",
"artifactDirectoryPath": "/home/me/projects/mempalace/.gemini/jetski/artifacts"
}
Output (when the palace has memory for wing_mempalace)
{
"injectSteps": [
{
"ephemeralMessage": "<exact verbatim text from `mempalace wake-up --wing wing_mempalace`>"
}
]
}
Output (when invocationNum != 1, or any gate trips)
{}
State files
All hook state lives under ~/.mempalace/hook_state/ (overridable
via $MEMPAL_STATE_DIR) and is namespaced with the antigravity_
prefix to coexist with Claude Code, Cursor, and Codex hook state in
the same directory.
| File | Purpose |
|---|---|
antigravity_hook.log |
All hook activity, ISO8601Z timestamps. |
antigravity_save_count_<conversationId> |
Per-conversation Stop counter. |
antigravity_pending_<conversationId> |
Marker file for in-flight save subprocess. |
antigravity_woke_<conversationId> (dir) |
Atomic mkdir marker for wake injection. |
antigravity_last_input.log |
4 KB cap, mode 0600, set on parse failure. |
antigravity_last_python_err.log |
Python stderr from the JSON parser, mode 0600. |
Environment variables
| Variable | Default | Purpose |
|---|---|---|
MEMPAL_PYTHON |
$(command -v python3) |
Override the Python interpreter used by the hooks. |
MEMPAL_STATE_DIR |
~/.mempalace/hook_state |
Override the hook state directory. |
MEMPAL_SAVE_INTERVAL |
15 |
Save every Nth Stop fire. Floored to >= 1 (no /0). |
MEMPAL_DISABLE_HOOK |
unset | Set to 1 / true / yes to disable both hooks. |
MEMPALACE_HOOKS_AUTO_SAVE |
unset | Set to false / 0 / no to disable both hooks. |