The Flaky Hook Started Failing Every Time — Migrating to Declarative Sessions in the Antigravity SDK

Tier A is pure mechanics

Registrations with no condition and no loop just move.

# Before: create the session, then bolt things onto it
def build(session):
    session.register_hook("pre_tool_use", audit_hook)
    session.register_trigger("on_file_write", reindex)
    return session

# After: hand everything over at creation time
from google.antigravity import AgentConfig
 
config = AgentConfig(
    hooks={"pre_tool_use": [audit_hook]},
    triggers={"on_file_write": [reindex]},
)

The diff looks unremarkable. What it buys is that from this point on, reading the configuration no longer requires running it.

Tier B moves the condition from "register?" to "execute?"

I took a detour here worth describing, because it wasted an afternoon.

My first attempt pushed the conditions into the declaration: one AgentConfig per flag combination, selected at startup. I stopped a few lines in. Three flags means eight configurations, and the count doubles with every flag added. I could not see myself maintaining that.

The correct direction was the opposite. Declare everything statically, and decide whether to act inside the hook.

# Before: the condition lives in whether we register
if feature_flags.get("strict_diff"):
    session.register_hook("post_tool_use", diff_guard)

# After: the condition moves inside. The declaration is always the same shape.
def diff_guard(event, ctx):
    if not ctx.flags.get("strict_diff"):
        return  # when disabled, it exists as a hook that does nothing
    ...
 
config = AgentConfig(hooks={"post_tool_use": [diff_guard]})

Declarations are static; judgments are runtime. Once I settled that line, the rest of the rewrites stopped requiring decisions.

Loops fold the same way — extract the factory, expand into the array.

# Before
for name in ("lint", "typecheck", "test"):
    session.register_hook("post_tool_use", make_gate(name))

# After (the ordering now becomes visible on the page)
GATES = ["lint", "typecheck", "test"]
config = AgentConfig(
    hooks={"post_tool_use": [make_gate(n) for n in GATES]},
)

I hesitated over whether a comprehension belongs inside a declaration. I have concluded that it does. It evaluates exactly once, at creation, so the guarantee that configuration cannot change at runtime still holds.

Nobody had ever decided the order

This is where the migration actually consumed my time.

While registration was scattered across asynchronous init paths, hook execution order was simply "whichever registration finished first." Slip a config file read or an MCP server connection into one of those paths and the order shifts from run to run.

I had no intuition for how much it shifted, so I measured it. Not the SDK itself — a minimal reproduction of how each scheme decides ordering.

import asyncio, random, collections, time
 
HOOKS = ["audit", "diff_guard", "reindex", "metrics", "cost_cap"]
 
# Scheme A: dynamic registration, each setup path doing async I/O
async def dynamic_register(sink, name):
    await asyncio.sleep(random.uniform(0.0, 0.002))  # config reads, MCP connects
    sink.append(name)
 
async def run_dynamic():
    sink = []
    await asyncio.gather(*(dynamic_register(sink, h) for h in HOOKS))
    return tuple(sink)
 
# Scheme B: declared at creation, array order is execution order
def run_declarative():
    return tuple(HOOKS)
 
N = 500
dyn = collections.Counter(asyncio.run(run_dynamic()) for _ in range(N))
dec = collections.Counter(run_declarative() for _ in range(N))
 
print(f"dynamic:     distinct orders observed = {len(dyn)}")
for o, c in dyn.most_common(3):
    print(f"  {c/N*100:5.1f}%  {' -> '.join(o)}")
print(f"declarative: distinct orders observed = {len(dec)}")

Across 500 runs:

dynamic:     distinct orders observed = 119
    1.8%  audit -> diff_guard -> cost_cap -> reindex -> metrics
    1.6%  diff_guard -> cost_cap -> metrics -> audit -> reindex
    1.6%  cost_cap -> metrics -> reindex -> audit -> diff_guard
declarative: distinct orders observed = 1

Five hooks have 120 possible orderings. In 500 runs, 119 of them showed up. The most frequent single ordering appeared 1.8% of the time. No ordering was meaningfully favored.

On its own that is just "ordering varies." It becomes a defect the moment hooks depend on each other. In my setup cost_cap finalizes the spend ceiling and diff_guard reads it to decide. Reverse them and the decision reads an unfinalized value.

async def dynamic_once():
    sink = []
    await asyncio.gather(*(reg(sink, h) for h in
                           ["audit", "diff_guard", "reindex", "metrics", "cost_cap"]))
    return sink.index("cost_cap") < sink.index("diff_guard")  # True = dependency held
 
N = 2000
ok = sum(asyncio.run(dynamic_once()) for _ in range(N))
print(f"dynamic, {N} runs: dependency satisfied {ok/N*100:.1f}% of the time")

dynamic, 2000 runs: dependency satisfied 48.2% of the time (violated 51.8%)
declarative: dependency satisfied 100.0% of the time

48.2% over 2,000 runs. Essentially a coin flip.

"Passes about four times out of ten" lines up with that number well. The test was not failing because of the environment, and not because of some subtle timing skew. It was failing because nobody had ever decided the order.

"Fails every time" means the bug is finally visible

Back to that red CI board.

Once declared, execution order follows the array I wrote. And the array I first wrote happened to be the losing side — diff_guard before cost_cap. I had not reconstructed the previous ordering; I had simply listed them in the order they appeared in the old code.

My intuition said that pinning the order would make the flaky test settle into passing. The opposite happened. It settled into failing.

Declarative configuration does not remove defects. It makes them reproducible.

That distinction matters more than it sounds. A bug that fails 48.2% of the time cannot be verified as fixed — two green runs might be luck. A bug that fails 100% of the time is fixed the first time it passes. In terms of pulling failures reliably onto your own machine, this sits alongside the approach in Record & Replay for Antigravity Agents — A Production Pattern to Reproduce Failures in 3 Minutes.

If your CI goes solid red right after this migration, suspect the declared order before you suspect the migration. I lost half a day there.

Three rules I used to decide the order

Rather than arranging the array by feel and repeating the same mistake later, I wrote down rules first.

Written out, it reads as obvious. But under dynamic registration there was no place in the codebase where that ordering could be written down at all. Having somewhere to write it may be the real substance of this change.

from google.antigravity import AgentConfig
 
HOOK_ORDER = [cost_cap, audit, metrics, diff_guard]  # the order carries meaning
 
config = AgentConfig(
    hooks={"post_tool_use": HOOK_ORDER},
    triggers={"on_session_end": [flush_metrics]},
)

Naming the array and lifting it out gives reviewers exactly one place to ask "why this order?" The broader idea of checking declarations statically also runs through A Typo in agent.md Quietly Widened My Permissions — Writing a Strict Frontmatter Lint.

Two gotchas that are not in the docs

Two things bit me during the move that no amount of reading would have prevented.

The first is the scanner quietly under-reporting. Re-run it partway through the migration and half-edited files raise SyntaxError. Swallow that with a bare except SyntaxError: continue and your remaining-work count drops to zero for the wrong reason. I convinced myself I was finished once. One line to stderr avoids it, and I would treat that line as mandatory.

The second is the runtime cost of hooks that are permanently resident but disabled. Once conditions live inside the hook, disabled hooks still get invoked on every event. As an indie developer running these agents unattended overnight, I wanted a number rather than a feeling, so I measured it:

disabled hook: 0.168 microseconds per invocation (1,000,000 iterations)
200 post_tool_use events x 3 disabled hooks per session: 100.8 microseconds total

Roughly 0.1 ms per session. I decided that was safe to ignore. The caveat is that this only holds if the early return comes before any I/O — put a config read above it and the order of magnitude changes. That is a rule worth fixing before you measure anything.

Migration checklist

1. Run scan.py across every directory and get the A/B/C counts before touching code
2. For any C (registration inside try), decide up front whether failure halts startup
3. Move the A's into arrays — this part is mechanical
4. Push B conditions into early returns inside hooks, not into the declaration
5. Extract B loops into factories and expand them with a comprehension
6. Decide the ordering deliberately — ceilings, then records, then judgments
7. If a test starts failing after the move, suspect the array order first
8. Wire scan.py into CI so dynamic registration cannot creep back in

Items 7 and 8 were added after being bitten. Item 8 in particular came from an older branch merging the previous style back in once the migration was already "done."

What got worse

To be fair about the trade: declaring everything made one thing more awkward.

Swapping a single hook for a test used to be one extra registration line. Now I build the configuration through a small factory and let tests substitute the array.

def build_config(hooks=None):
    return AgentConfig(hooks={"post_tool_use": hooks or HOOK_ORDER})

That solved it, but it is undeniably one more moving part. In exchange I get a guarantee that configuration cannot drift at runtime, and I am comfortable with that trade.

Ordering non-determinism stays invisible for as long as things happen to work. Until I saw 48.2%, I was convinced the environment was to blame. If you have a hook that fails "sometimes," run the harness above against your own setup and find out what your number actually is.