@goodfoot/agent-hooks 1.0.7 → 1.0.9

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @goodfoot/agent-hooks npm package changelog
 
+## 1.0.9
+- Added support for Antigravity hooks, including event handling, output formatting, and transport
+- Added scaffolding for Antigravity hook projects via the CLI
+- Documented the Antigravity hook contract in the README
+
+## 1.0.9
+
+Adds full Antigravity support to the public package: typed hook factories and outputs, transport behavior, the `@goodfoot/agent-hooks/antigravity` export, CLI compilation, and a scaffold that emits an installable Antigravity plugin manifest. The implementation is covered by unit, conformance, export-surface, scaffold, and live host smoke tests.
+
+## 1.0.8
+
+Maintenance release accompanying a repository version-bump hook fix: a version surface is now exempt only for its version, not for its whole contents, so an edit to a manifest or a version-bearing source file can no longer ship unversioned. No changes to the hook API, the compiler, or the CLI.
+
 ## 1.0.7
 
 Corrects the README's OpenCode install rationale. The plugin packages now declare a `main` entrypoint, so `opencode plugin` no longer rejects them with `No plugin targets found`; the reason a checkout is still required is that `opencode plugin` never writes `skills.paths`, so installing the plugin does not deliver the skill. Also moves a sentence about compiling hooks for OpenCode out of the version-checking paragraph it had attached itself to. No changes to the hook API, the compiler, or the CLI.

package/README.md

@@ -6,17 +6,15 @@
 `@goodfoot/codex-hooks`: a shared agent-neutral core (hook factory primitive, transport
 driver, `Logger`, env/stdin utilities) with a per-agent entry point on top. Write
 TypeScript hooks, compile them with the bundled CLI, and run the resulting
-self-contained executables under Claude Code or Codex.
+self-contained executables under Claude Code, Codex, OpenCode, or Antigravity.
 
-**Status: `1.0.0`.** Three entry points ship and are published: `@goodfoot/agent-hooks/claude-code`
+**Status: `1.0.8`.** Four host entry points ship: `@goodfoot/agent-hooks/claude-code`
 (full parity with `@goodfoot/claude-code-hooks`), `@goodfoot/agent-hooks/codex` (full
-parity with `@goodfoot/codex-hooks`), and `@goodfoot/agent-hooks/opencode` (native support
-for OpenCode's in-process plugin model — see [OpenCode](#opencode) below). Antigravity CLI
-support exists internally as typed factories, output builders, and a conformance matrix,
-but is **not** part of this release's public surface — there is no
-`@goodfoot/agent-hooks/antigravity` export yet, and `--agent antigravity` is rejected by
-the CLI. It ships once a non-interactive, authenticated Antigravity CLI exists to
-validate against.
+parity with `@goodfoot/codex-hooks`), `@goodfoot/agent-hooks/opencode` (native support
+for OpenCode's in-process plugin model — see [OpenCode](#opencode) below), and
+`@goodfoot/agent-hooks/antigravity` (five typed events, host-native output builders,
+manifest generation, scaffolding, and an exit-0 payload transport). The Antigravity
+surface is pinned to and behaviorally verified against `agy` 1.1.22.
 
 ## Install
 
@@ -35,9 +33,10 @@ yarn add @goodfoot/agent-hooks
 ### The plugin, for development
 
 All four hosts install from
-[`goodfoot-io/marketplace`](https://github.com/goodfoot-io/marketplace). Claude Code,
-Codex, and Antigravity resolve the repository directly. Only OpenCode needs a checkout,
-because it loads skills from a config path rather than from a plugin.
+[`goodfoot-io/marketplace`](https://github.com/goodfoot-io/marketplace). Claude Code and
+Codex add the repository as a marketplace and install by name. Antigravity installs one
+plugin root at a time. OpenCode needs a checkout, because these plugin packages are not
+published to npm.
 
 Note that the plugin and the npm package version independently — the plugin version you
 install will not match the package version above.
@@ -50,6 +49,8 @@ claude plugin install agent-hooks@goodfoot
 ```
 
 Verify with `claude plugin list` — `agent-hooks@goodfoot` should be listed as enabled.
+`claude plugin details agent-hooks` reports the component inventory, confirming the skill
+itself arrived rather than just the plugin.
 
 #### Codex
 
@@ -59,48 +60,71 @@ codex plugin add agent-hooks@goodfoot
 ```
 
 The marketplace source must be a repository, git URL, or directory; passing the manifest
-path itself is rejected. `codex plugin add` requires the `<plugin>@<marketplace>` form.
-Verify with `codex plugin list --json`; the skill tree lands under
+path itself is rejected. A bare plugin name is rejected even when exactly one marketplace
+is configured — qualify it as `agent-hooks@goodfoot` or pass `--marketplace goodfoot`. If
+you set `CODEX_HOME`, create that directory first; Codex will not create it and fails with
+`failed to resolve CODEX_HOME`.
+
+Verify with `codex plugin list`, which lists every marketplace plugin with a `STATUS`
+column. Do not use `codex plugin list --json` for this: on codex-cli 0.150.1 its
+`available` array is empty even when the plain listing shows all seven plugins, so a
+correctly installed plugin can look missing. The skill tree lands under
 `$CODEX_HOME/plugins/cache/goodfoot/agent-hooks/<version>/skills`.
 
 #### Antigravity
 
-`agy` has no marketplace command. It installs a plugin root directly, from a git URL
-with the in-repo path appended:
+`agy` installs one plugin root at a time, from a git URL with the in-repo path appended:
 
 ```bash
 agy plugin install https://github.com/goodfoot-io/marketplace.git/plugins-antigravity/agent-hooks
 ```
 
-The `#subdir` fragment form other tools accept fails here with `could not detect plugin
-structure`. A local path works the same way: `agy plugin install
-./plugins-antigravity/agent-hooks`.
+There is no marketplace form that installs several at once: pointing `agy plugin install`
+at the repository root is rejected with `could not detect plugin structure`, as is the
+`#subdir` fragment form other tools accept. A local path works the same way: `agy plugin
+install ./plugins-antigravity/agent-hooks`.
+
+To add the sibling plugins, repeat the command for each root you want —
+`plugins-antigravity/` carries `agent-hooks`, `agent-skills`, `claude-code-skill-reader`,
+`gmail`, `goodfoot`, `jsdoczoom`, and `linear`.
 
 A successful install reports `skills : 1 processed`; `agents`, `commands`, `mcpServers`,
 and `hooks` report `skipped (not found)`, expected for a skills-only plugin. Files land
-in `~/.gemini/config/plugins/agent-hooks/`. Verify with `agy plugin list`.
+in `~/.gemini/config/plugins/agent-hooks/`. Verify with `agy plugin list`, which reports
+`"components": ["skills"]` for the installed plugin.
 
-This installs the authoring skill only. It is unrelated to `--agent antigravity`, which
-the compiler CLI still rejects (see the status note above).
+This marketplace plugin installs the authoring skill only. Hook projects use the npm
+package separately: import `@goodfoot/agent-hooks/antigravity` and compile with
+`agent-hooks --agent antigravity`. The compiler writes the host-native `hooks.json` at
+the plugin root plus its executable bundles under `bin/`; install that resulting plugin
+root with `agy plugin install <dir>`. Scaffolding an Antigravity hook project also emits
+the root `plugin.json` required by that install command.
 
 #### OpenCode
 
-OpenCode plugins are hook-transport modules and cannot contribute skills — skills load
-only from `skills.paths`, and `opencode plugin` never writes that key. Installing the
-plugin is not a way to get the skill. Clone the repository and register the skill
-directory in `opencode.json`:
+These plugin packages are not published to npm, so `opencode plugin` takes a path into a
+checkout rather than a module name:
 
 ```bash
 git clone https://github.com/goodfoot-io/marketplace.git
+opencode plugin "$PWD/marketplace/plugins-opencode/agent-hooks"
 ```
 
-```json
-{
-  "skills": {
-    "paths": ["./marketplace/plugins-opencode/agent-hooks/skills"]
-  }
-}
-```
+Pass a path, not a bare name. `opencode plugin` resolves a specifier containing a
+separator as a path — absolute, `./`-prefixed, and plain relative forms all load on
+OpenCode 1.18.23. A single segment with no separator (`agent-hooks`) is instead resolved as an
+npm package name and silently fails to load, with nothing logged. The absolute form
+above avoids the ambiguity.
+
+That is the whole install — no `opencode.json` editing. `opencode plugin` writes only the
+top-level `plugin` key, and OpenCode keeps `plugin` and `skills` as disjoint config keys,
+so registering the module would not by itself surface its skills. The plugin closes that
+gap from the inside: its `config` hook runs against the resolved config before use and
+appends its own bundled `skills/` directory to `skills.paths`, resolved relative to
+wherever the package was installed. Installing is enough.
+
+Without flags this installs into the current project's `.opencode/opencode.json`. Add
+`-g` to install into the global config instead.
 
 Verify with `opencode debug skill`. Its output is large and embeds whole skill bodies:
 redirect it to a file and search there. Piping it to `head` truncates the JSON mid-string
@@ -119,7 +143,8 @@ Re-running the install command does not move the version on every host.
 - **Codex** — `codex plugin marketplace upgrade goodfoot` moves the installed version;
   there is no separate plugin-update command.
 - **Antigravity** — re-run `agy plugin install`.
-- **OpenCode** — pull the checkout.
+- **OpenCode** — pull the checkout; the plugin resolves its skills from that directory, so
+  no reinstall is needed. Re-run with `-f` to replace a pinned plugin version.
 
 Check the installed version rather than the exit code. Several hosts report success while
 leaving a stale version in place, and a newer directory in a host's cache proves only that
@@ -251,6 +276,12 @@ export default defineOpenCodePlugin({
   `observe`/`observeResumed` record first-seen-event distinctly and `isRoot`/`isResumed`
   answer from that record.
 
+`Hooks` also includes `config?: (input: Config) => Promise<void>`, which runs against the
+resolved config before use and can mutate it. That is how a plugin contributes
+configuration it would otherwise need the user to hand-write — the plugins in this
+repository use it to append their own `skills/` directory to `skills.paths`, so installing
+one delivers its skills without any `opencode.json` edit.
+
 Compile with the same unified CLI, but `--agent opencode` treats `-o`/`--output` as a
 plugin-artifact **directory**, not a manifest path — OpenCode config references built
 files directly, so there is no `hooks.json`-equivalent manifest or shebang wrapper:

package/dist/agents/antigravity/cli-support.js

@@ -0,0 +1,282 @@
+/**
+ * Antigravity-specific CLI internals: source analysis, bundle compilation
+ * linking the Antigravity runtime module, and `hooks.json` generation in the
+ * host's own named-hook shape.
+ *
+ * The manifest shape here has no counterpart in the other agents. Claude Code
+ * and Codex both emit `{ "hooks": { "<Event>": [...] } }`; Antigravity's
+ * top-level keys are **hook names**, each mapping to its own event table, and
+ * only two of the five events wrap their handlers in a `{ matcher, hooks }`
+ * group. The host also sets each handler's working directory to the directory
+ * containing `hooks.json`, so commands are emitted relative to it and need no
+ * `${PLUGIN_ROOT}` substitution or git-toplevel escape. See `CONTRACT.md` in
+ * this directory for the pinned reference all of that is transcribed from.
+ *
+ * Driver-level primitives (loader parsing, glob discovery, content hashing,
+ * symlink re-rooting, stale-bundle pruning) are imported from the shared CLI
+ * module — never re-derived here.
+ * @module
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import * as esbuild from "esbuild";
+import ts from "typescript";
+import { buildEsbuildLoaderMap, discoverHookSourceFiles, parseEsbuildLoaderFlag, pruneStaleHashedBundles, sha256Prefix8, symlinkVisiblePath, } from "../../cli.js";
+import { DEFAULT_TIMEOUT_SECONDS, GROUPED_EVENTS, HOOK_FACTORY_TO_EVENT } from "./constants.js";
+import { HOOK_EVENT_NAMES } from "./events.js";
+/** The matcher emitted when a grouped event's config names none. `"*"` matches every tool. */
+const MATCH_ALL = "*";
+/**
+ * Recovers the bound event, matcher, and timeout from a hook module's default
+ * export. Returns `undefined` when the default export is not a call to a
+ * known Antigravity factory, which is how non-hook files in the input glob
+ * are skipped.
+ */
+export function analyzeAntigravityHookFile(sourcePath) {
+    const sourceFile = ts.createSourceFile(sourcePath, fs.readFileSync(sourcePath, "utf-8"), ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    const unwrap = (node) => {
+        if (ts.isParenthesizedExpression(node) || ts.isAwaitExpression(node)) {
+            return unwrap(node.expression);
+        }
+        return ts.isCallExpression(node) ? node : undefined;
+    };
+    const factoryOf = (call) => {
+        if (ts.isIdentifier(call.expression)) {
+            return call.expression.text;
+        }
+        return ts.isPropertyAccessExpression(call.expression) ? call.expression.name.text : undefined;
+    };
+    const literalString = (node) => ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node) ? node.text : undefined;
+    let found;
+    const inspect = (node) => {
+        if (ts.isExportAssignment(node) && !node.isExportEquals) {
+            const call = unwrap(node.expression);
+            const factory = call === undefined ? undefined : factoryOf(call);
+            const hookEventName = factory === undefined ? undefined : HOOK_FACTORY_TO_EVENT[factory];
+            if (call !== undefined && hookEventName !== undefined) {
+                const result = { hookEventName };
+                const [config] = call.arguments;
+                if (config !== undefined && ts.isObjectLiteralExpression(config)) {
+                    for (const property of config.properties) {
+                        if (!ts.isPropertyAssignment(property) || !ts.isIdentifier(property.name)) {
+                            continue;
+                        }
+                        if (property.name.text === "matcher") {
+                            result.matcher = literalString(property.initializer);
+                        }
+                        if (property.name.text === "timeout" && ts.isNumericLiteral(property.initializer)) {
+                            result.timeout = Number(property.initializer.text);
+                        }
+                    }
+                }
+                found = result;
+            }
+        }
+        ts.forEachChild(node, inspect);
+    };
+    inspect(sourceFile);
+    return found;
+}
+/**
+ * Bundles one hook source into a self-contained ESM executable whose entry
+ * wrapper calls this agent's `execute`.
+ */
+export async function compileAntigravityHook(sourcePath, loaders, sourcemap = true) {
+    const resolveDir = path.dirname(sourcePath);
+    const runtimeAbsolute = symlinkVisiblePath(path.resolve(path.dirname(fileURLToPath(import.meta.url)), "./transport.js"), resolveDir);
+    const runtimeRelative = path.relative(resolveDir, runtimeAbsolute).replace(/\\/g, "/");
+    const runtimeSpecifier = runtimeRelative.startsWith(".") ? runtimeRelative : `./${runtimeRelative}`;
+    const entry = [
+        `import hook from ${JSON.stringify(`./${path.basename(sourcePath)}`)};`,
+        `import { execute } from ${JSON.stringify(runtimeSpecifier)};`,
+        `execute(hook);`,
+        ``,
+    ].join("\n");
+    const built = await esbuild.build({
+        stdin: {
+            contents: entry,
+            resolveDir,
+            sourcefile: `${path.basename(sourcePath, path.extname(sourcePath))}-entry.ts`,
+            loader: "ts",
+        },
+        loader: loaders,
+        format: "esm",
+        platform: "node",
+        target: "node20",
+        bundle: true,
+        sourcemap: sourcemap ? "inline" : false,
+        write: false,
+        external: ["node:*", "fs", "path", "os", "crypto", "module", "url"],
+        mainFields: ["module", "main"],
+        conditions: ["import", "node"],
+        preserveSymlinks: true,
+    });
+    const content = built.outputFiles?.[0]?.text;
+    if (content === undefined) {
+        throw new Error(`esbuild produced no output for ${sourcePath}`);
+    }
+    return { content, contentHash: sha256Prefix8(content) };
+}
+/**
+ * Converts a source file's basename to the manifest's top-level hook name.
+ * Names must be unique across the whole manifest, since the host merges
+ * same-named entries; a collision is suffixed rather than silently dropped.
+ */
+function assignHookName(sourcePath, taken) {
+    const base = path.basename(sourcePath, path.extname(sourcePath));
+    if (!taken.has(base)) {
+        taken.add(base);
+        return base;
+    }
+    let suffix = 2;
+    while (taken.has(`${base}-${suffix}`)) {
+        suffix++;
+    }
+    const unique = `${base}-${suffix}`;
+    taken.add(unique);
+    return unique;
+}
+async function compileAll(hookFiles, binDir, loaders, options) {
+    fs.mkdirSync(binDir, { recursive: true });
+    const compiled = [];
+    const taken = new Set();
+    const written = new Set();
+    for (const sourcePath of hookFiles) {
+        const metadata = analyzeAntigravityHookFile(sourcePath);
+        if (metadata === undefined) {
+            continue;
+        }
+        const { content, contentHash } = await compileAntigravityHook(sourcePath, loaders, options.sourcemap);
+        const hookName = assignHookName(sourcePath, taken);
+        const filename = options.stableNames ? `${hookName}.mjs` : `${hookName}.${contentHash}.mjs`;
+        const outputPath = path.join(binDir, filename);
+        fs.writeFileSync(outputPath, `#!/usr/bin/env -S node --enable-source-maps\n${content}`, {
+            encoding: "utf-8",
+            mode: 0o755,
+        });
+        written.add(filename);
+        compiled.push({ sourcePath, outputPath, hookName, metadata });
+    }
+    pruneStaleHashedBundles(binDir, written);
+    return compiled;
+}
+/**
+ * Renders the command string for one bundle. The host runs each handler
+ * through `sh -c` with the working directory set to the directory holding
+ * `hooks.json`, so a manifest-relative path is portable across every install
+ * location without substitution.
+ */
+function commandFor(manifestDir, outputPath, executable) {
+    const relative = path.relative(manifestDir, outputPath).replace(/\\/g, "/");
+    const specifier = relative.startsWith(".") ? relative : `./${relative}`;
+    return `${executable} ${JSON.stringify(specifier)}`;
+}
+function timeoutSeconds(timeoutMs) {
+    if (timeoutMs === undefined) {
+        return DEFAULT_TIMEOUT_SECONDS;
+    }
+    return Math.max(1, Math.ceil(timeoutMs / 1000));
+}
+/**
+ * Builds the manifest. Each compiled hook becomes one top-level named entry
+ * holding exactly one event, which is what the host merges across plugins.
+ */
+export function generateAntigravityHooksJson(compiled, manifestPath, executable = "node") {
+    const manifestDir = path.dirname(manifestPath);
+    const manifest = {};
+    for (const entry of compiled) {
+        const handler = {
+            type: "command",
+            command: commandFor(manifestDir, entry.outputPath, executable),
+            timeout: timeoutSeconds(entry.metadata.timeout),
+        };
+        const event = entry.metadata.hookEventName;
+        const named = {};
+        if (GROUPED_EVENTS.has(event)) {
+            const group = { matcher: entry.metadata.matcher ?? MATCH_ALL, hooks: [handler] };
+            if (event === "PreToolUse") {
+                named.PreToolUse = [group];
+            }
+            else {
+                named.PostToolUse = [group];
+            }
+        }
+        else if (event === "PreInvocation") {
+            named.PreInvocation = [handler];
+        }
+        else if (event === "PostInvocation") {
+            named.PostInvocation = [handler];
+        }
+        else {
+            named.Stop = [handler];
+        }
+        manifest[entry.hookName] = named;
+    }
+    return manifest;
+}
+/** Validates the Antigravity build arguments beyond the shared `--agent` gate. */
+export function validateAntigravityArgs(args) {
+    if (args.scaffold !== undefined && args.scaffold !== "") {
+        if (args.output === "") {
+            return "Scaffold mode requires -o/--output";
+        }
+        if (args.hooks === undefined || args.hooks === "") {
+            return "Scaffold mode requires --hooks";
+        }
+        const unknown = args.hooks
+            .split(",")
+            .map((value) => value.trim())
+            .filter((value) => value.length > 0)
+            .filter((value) => !HOOK_EVENT_NAMES.some((name) => name.toLowerCase() === value.toLowerCase()));
+        if (unknown.length > 0) {
+            return `Unknown Antigravity hook name(s): ${unknown.join(", ")}. Valid names: ${HOOK_EVENT_NAMES.join(", ")}`;
+        }
+        return undefined;
+    }
+    if (args.input === "") {
+        return "Missing required argument: -i/--input";
+    }
+    if (args.output === "") {
+        return "Missing required argument: -o/--output";
+    }
+    for (const flag of args.loaderFlags) {
+        if (parseEsbuildLoaderFlag(flag) === undefined) {
+            return `Invalid --loader value: ${flag}. Expected .ext=type`;
+        }
+    }
+    return undefined;
+}
+/**
+ * Runs the Antigravity build or scaffold branch. Bundle filenames are stable
+ * by default: a manifest committed into a plugin tree must not churn on every
+ * rebuild, and the host reads the command string rather than globbing the
+ * directory.
+ */
+export async function runAntigravityCli(args) {
+    if (args.scaffold !== undefined && args.scaffold !== "") {
+        const { scaffoldProject } = await import("./scaffold.js");
+        scaffoldProject({
+            directory: path.resolve(process.cwd(), args.scaffold),
+            hooks: (args.hooks ?? "")
+                .split(",")
+                .map((value) => value.trim())
+                .filter((value) => value.length > 0),
+            outputPath: args.output,
+        });
+        return 0;
+    }
+    const cwd = process.cwd();
+    const manifestPath = path.resolve(cwd, args.output);
+    const binDir = path.join(path.dirname(manifestPath), "bin");
+    const hookFiles = await discoverHookSourceFiles(args.input, cwd);
+    const loaders = buildEsbuildLoaderMap(args.loaderFlags);
+    const compiled = await compileAll(hookFiles, binDir, loaders, {
+        stableNames: args.stableNames ?? true,
+        sourcemap: args.sourcemap ?? true,
+    });
+    const manifest = generateAntigravityHooksJson(compiled, manifestPath, args.executable ?? "node");
+    fs.mkdirSync(path.dirname(manifestPath), { recursive: true });
+    fs.writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+    return compiled.length;
+}

package/dist/agents/antigravity/constants.js

@@ -0,0 +1,20 @@
+export const PACKAGE_NAME = "@goodfoot/agent-hooks";
+/** The host's own default handler timeout, in seconds (`CONTRACT.md`, Hook Handler Fields). */
+export const DEFAULT_TIMEOUT_SECONDS = 30;
+export const DEFAULT_ESBUILD_LOADERS = {
+    ".md": "text",
+};
+/** Maps each exported factory name to the event it binds. */
+export const HOOK_FACTORY_TO_EVENT = {
+    preToolUseHook: "PreToolUse",
+    postToolUseHook: "PostToolUse",
+    preInvocationHook: "PreInvocation",
+    postInvocationHook: "PostInvocation",
+    stopHook: "Stop",
+};
+/**
+ * Events whose `hooks.json` entry is a grouped `{ matcher, hooks }` wrapper.
+ * The remaining three are flat lists of handler objects; the host ignores a
+ * matcher on them.
+ */
+export const GROUPED_EVENTS = new Set(["PreToolUse", "PostToolUse"]);

package/dist/agents/antigravity/events.js

@@ -1,23 +1,23 @@
 /**
- * Antigravity hook event names and the (currently empty) advisory allow-list.
+ * Antigravity hook event names, the grouped/flat structural split, and the
+ * (empty) advisory allow-list.
  *
- * Unlike Claude Code's and Codex's allow-lists, which transcribe a named set
- * of enrichment hooks out of a shipped README, Antigravity has no in-repo
- * doc to transcribe from this release (Step 0 descope — see the plan's Step
- * 5 blockquote). The allow-list therefore defaults to **every event
- * excluded**, not a curated subset, until a future card's `CONTRACT.md`
- * names a specific enrichment hook safe to opt into `unexpectedError:
- * "continue"`.
+ * The host's hook reference — pinned in this directory's `CONTRACT.md` —
+ * names five events and splits them structurally: `PreToolUse` and
+ * `PostToolUse` wrap their handlers in a `{ matcher, hooks }` group, while
+ * `PreInvocation`, `PostInvocation`, and `Stop` list handler objects
+ * directly and ignore any matcher. {@link EVENTS_WITH_MATCHER} is that split,
+ * and `cli-support.ts` emits `hooks.json` from it.
  *
- * That default is itself gated on a second precondition: because Antigravity
- * has no exit-code channel at all (every event is payload-only — see
- * `transport.ts` and `outputs.ts`'s {@link AntigravityBlockError}), a
- * fail-open swallow on this agent has no narrower fallback than Claude
- * Code's or Codex's — there is no stderr+exit-2 loud path to fall back to.
- * `AntigravityBlockError` landing first (this same step) is what makes it
- * safe to ever widen this list at all: an intentional block computed
- * mid-throw still survives `unexpectedError: "continue"` via `drive()`'s
- * pre-policy classification, exactly as it does for the other two agents.
+ * The advisory allow-list is empty, and stays empty: the reference names no
+ * event as safe to fail open. That default is load-bearing here in a way it
+ * is not on the other two agents, because Antigravity has no exit-code
+ * channel at all (every event is payload-only — see `transport.ts` and
+ * `outputs.ts`'s {@link AntigravityBlockError}), so a fail-open swallow has
+ * no loud path to degrade to. `AntigravityBlockError` is what would make
+ * widening the list safe at all: an intentional block computed mid-throw
+ * still survives `unexpectedError: "continue"` via `drive()`'s pre-policy
+ * classification, exactly as it does for the other two agents.
  * @module
  */
 /** All Antigravity hook event names as a readonly array. */
@@ -28,15 +28,17 @@ export const HOOK_EVENT_NAMES = [
     "PostInvocation",
     "Stop",
 ];
-/** The two events whose config accepts a `matcher` (plan step 5.3: "matcher on the two ToolUse events"). */
+/**
+ * The two events whose `hooks.json` entry is grouped under a `matcher`. The
+ * other three are flat: the host ignores a matcher on them entirely.
+ */
 export const EVENTS_WITH_MATCHER = ["PreToolUse", "PostToolUse"];
 /**
  * Events never allowed the fail-open `unexpectedError: "continue"` policy.
  *
- * Every shipped event, by default — see module docs. This is a stated
- * default (plan Decisions: "advisory list default empty until CONTRACT.md
- * justifies an entry"), not a silent gap.
+ * Every shipped event. The host's hook reference names no event as safe to
+ * fail open, so this is a transcribed conclusion, not a placeholder.
  */
 export const EXCLUDED_FROM_ADVISORY = [...HOOK_EVENT_NAMES];
-/** The advisory allow-list. Empty until a future `CONTRACT.md` names an entry. */
+/** The advisory allow-list. Empty: `CONTRACT.md` names no event safe to fail open. */
 export const ADVISORY_EVENTS = HOOK_EVENT_NAMES.filter((eventName) => !EXCLUDED_FROM_ADVISORY.includes(eventName));

package/dist/agents/antigravity/hooks.js

@@ -2,20 +2,19 @@
  * Typed factory functions for Antigravity hooks, built on the shared core
  * {@link ../../core/define-hook.ts|defineHook}.
  *
- * This release ships the typed factory surface and output builders only
- * (plan Step 5, item-6 descope) — no `CONTRACT.md`-derived e2e file, no
- * `./antigravity` export. Every factory injects the advisory allow-list
- * policy gate, so `unexpectedError: "continue"` fails closed at
- * factory-call time for every event ({@link ADVISORY_EVENTS} is empty this
- * release); {@link HookConfigFor} additionally narrows the policy field at
- * compile time.
+ * Every factory injects the advisory allow-list policy gate, so
+ * `unexpectedError: "continue"` fails closed at factory-call time for every
+ * event ({@link ADVISORY_EVENTS} is empty, and `CONTRACT.md` names no event
+ * safe to fail open); {@link HookConfigFor} additionally narrows the policy
+ * field at compile time.
  *
  * Antigravity's config surface is a single conditional type rather than the
  * separate matcher/no-matcher interface pair Claude Code and Codex use: only
  * two of the five events (`PreToolUse`, `PostToolUse`) carry a `matcher`
  * ({@link EVENTS_WITH_MATCHER} in `events.ts`), and a conditional type on the
  * bound event expresses that distinction without duplicating the base field
- * list twice.
+ * list twice. The host ignores a matcher on the other three events entirely,
+ * so accepting one there would be a silent no-op.
  * @module
  */
 import { defineHook } from "../../core/define-hook.js";

package/dist/agents/antigravity/index.js

@@ -1,28 +1,17 @@
 /**
  * `@goodfoot/agent-hooks/antigravity` — the Antigravity agent surface.
  *
- * **Not yet published as a package subpath.** Step 5 ships under its item-6
- * descope (Step 0 concluded "not runnable / unknown" for the real
- * `antigravity` CLI in this release's environment): typed factories, output
- * builders, and a conformance matrix only. `packages/agent-hooks/package.json`
- * deliberately does not add a `./antigravity` `exports` entry this release —
- * see `tests/export-surface.test.ts`, which asserts the exports map stays
- * closed at `.`/`./claude-code`/`./codex`. This module exists for in-repo
- * testing (the conformance matrix imports it directly by relative path) and
- * for the follow-up card that resolves the CLI-availability question to
- * build on without re-deriving the surface from scratch.
+ * Re-exports the five hook factories, their per-event output builders, the
+ * `AntigravityBlockError` block signal, the wire input/output types, and the
+ * runtime `execute` entry point. No default export.
  *
- * Re-exports the 5 hook factories, their output builders (reserved fields
- * emitted only when passed), the `AntigravityBlockError` block signal,
- * input/output types, and the runtime `execute` entry point. No default
- * export.
+ * Every shape here is transcribed from `CONTRACT.md` in this directory, which
+ * pins the host's own hook reference. Two consequences shape the whole
+ * surface: keys are camelCase, and each event has a **different** stdout
+ * shape rather than one shared envelope.
  * @module
  */
-// Advisory allow-list events
 export { ADVISORY_EVENTS, EVENTS_WITH_MATCHER, EXCLUDED_FROM_ADVISORY, HOOK_EVENT_NAMES } from "./events.js";
-// Hook factory functions - all 5 event types
 export { postInvocationHook, postToolUseHook, preInvocationHook, preToolUseHook, stopHook } from "./hooks.js";
-// Output types and builders (AntigravityBlockError subclasses core HookBlockError)
 export { AntigravityBlockError, EXIT_CODES, postInvocationOutput, postToolUseOutput, preInvocationOutput, preToolUseOutput, stopOutput, } from "./outputs.js";
-// Runtime exports - execute function and transport factory
 export { createAntigravityTransport, execute } from "./transport.js";