@goodfoot/agent-hooks 1.0.7 → 1.0.9

package/dist/agents/antigravity/outputs.js

@@ -1,3 +1,14 @@
+/**
+ * Antigravity output builders, one per event.
+ *
+ * Unlike Claude Code and Codex, Antigravity gives each event a **different**
+ * stdout shape — there is no single envelope every event shares. `PreToolUse`
+ * returns a permission decision, `PostToolUse` returns `{}` and nothing else,
+ * the two invocation events return injected steps, and `Stop` returns a
+ * continue-or-not decision. Each builder below emits only the fields its own
+ * event's contract names; see `CONTRACT.md` in this directory.
+ * @module
+ */
 import { HookBlockError } from "../../core/transport.js";
 /**
  * Antigravity has no exit-code signaling channel: every event replies at
@@ -15,14 +26,16 @@ export const EXIT_CODES = {
  * **before** consulting `unexpectedError` policy — exactly mirroring Claude
  * Code's `HookBlockError` usage and Codex's `BlockError` re-export.
  *
- * This mechanism is a stated *prerequisite*, not a follow-up, for
- * Antigravity specifically: because every Antigravity event replies at exit
- * 0 with the decision expressed only in the JSON payload (Research, plan
- * Step 5), a handler that throws mid-decision has no narrower exit-code
- * fallback to land on the way Codex's stderr+exit-2 channel does — the block
- * decision would otherwise be indistinguishable from a swallowed crash. This
- * class landing is what makes it safe to ever widen `events.ts`'s advisory
- * allow-list past empty.
+ * The class matters more here than on the other two agents: because every
+ * Antigravity event replies at exit 0 with the decision expressed only in the
+ * JSON payload, a handler that throws mid-decision has no narrower exit-code
+ * fallback to land on the way Codex's stderr+exit-2 channel does. Without
+ * this class the block would be indistinguishable from a swallowed crash.
+ *
+ * The transport serializes it as `{ "decision": "deny", ... }`, which the
+ * host acts on for `PreToolUse` only. On the other four events the reply is
+ * well-formed but carries no decision the host recognizes, so it reads as an
+ * empty response.
  */
 export class AntigravityBlockError extends HookBlockError {
     reason;
@@ -41,41 +54,35 @@ function buildOutput(type, stdout) {
         stdout: omitUndefined(stdout),
     };
 }
+/** Builds a `PreToolUse` reply: a permission decision, optionally with argument overwrites. */
 export function preToolUseOutput(options = {}) {
     return buildOutput("PreToolUse", {
         decision: options.decision,
         reason: options.reason,
-        additionalContext: options.additionalContext,
-        updatedInput: options.updatedInput,
-        systemMessage: options.systemMessage,
+        permissionOverrides: options.permissionOverrides,
+        overwrite: options.overwrite,
     });
 }
-export function postToolUseOutput(options = {}) {
-    return buildOutput("PostToolUse", {
-        decision: options.decision,
-        reason: options.reason,
-        additionalContext: options.additionalContext,
-        systemMessage: options.systemMessage,
-    });
+/**
+ * Builds the `PostToolUse` reply. The contract defines the reply as an empty
+ * object, so this builder takes no options: there is nothing a `PostToolUse`
+ * handler can tell the host.
+ */
+export function postToolUseOutput() {
+    return buildOutput("PostToolUse", {});
 }
+/** Builds a `PreInvocation` reply carrying steps to inject before the model runs. */
 export function preInvocationOutput(options = {}) {
-    return buildOutput("PreInvocation", {
-        decision: options.decision,
-        reason: options.reason,
-        additionalContext: options.additionalContext,
-        systemMessage: options.systemMessage,
-    });
+    return buildOutput("PreInvocation", { injectSteps: options.injectSteps });
 }
+/** Builds a `PostInvocation` reply: injected steps, a termination override, or both. */
 export function postInvocationOutput(options = {}) {
     return buildOutput("PostInvocation", {
-        additionalContext: options.additionalContext,
-        systemMessage: options.systemMessage,
+        injectSteps: options.injectSteps,
+        terminationBehavior: options.terminationBehavior,
     });
 }
+/** Builds a `Stop` reply. `decision: "continue"` blocks the stop; `reason` is injected as a system message. */
 export function stopOutput(options = {}) {
-    return buildOutput("Stop", {
-        stop: options.stop,
-        reason: options.reason,
-        systemMessage: options.systemMessage,
-    });
+    return buildOutput("Stop", { decision: options.decision, reason: options.reason });
 }

package/dist/agents/antigravity/scaffold.js

@@ -0,0 +1,211 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { HOOK_FACTORY_TO_EVENT, PACKAGE_NAME } from "./constants.js";
+const IMPORT_SPECIFIER = `${PACKAGE_NAME}/antigravity`;
+const EVENT_NAMES = Object.values(HOOK_FACTORY_TO_EVENT);
+const EVENT_LOOKUP = new Map(EVENT_NAMES.map((event) => [event.toLowerCase(), event]));
+const EVENT_TO_FACTORY = Object.fromEntries(Object.entries(HOOK_FACTORY_TO_EVENT).map(([factory, event]) => [event, factory]));
+const EVENT_TO_OUTPUT = {
+    PreToolUse: "preToolUseOutput",
+    PostToolUse: "postToolUseOutput",
+    PreInvocation: "preInvocationOutput",
+    PostInvocation: "postInvocationOutput",
+    Stop: "stopOutput",
+};
+/** Resolves user-supplied hook names case-insensitively, rejecting the whole list on any miss. */
+export function validateHookNames(requested) {
+    const normalized = [];
+    const rejected = [];
+    for (const name of requested) {
+        const event = EVENT_LOOKUP.get(name.toLowerCase());
+        if (event === undefined) {
+            rejected.push(name);
+        }
+        else {
+            normalized.push(event);
+        }
+    }
+    if (rejected.length > 0) {
+        return {
+            valid: false,
+            error: `Invalid hook names: ${rejected.join(", ")}. Valid names: ${EVENT_NAMES.join(", ")}`,
+        };
+    }
+    return { valid: true, normalized };
+}
+function kebab(value) {
+    return value
+        .replace(/([a-z])([A-Z])/g, "$1-$2")
+        .replace(/([A-Z])([A-Z][a-z])/g, "$1-$2")
+        .toLowerCase();
+}
+function packageJson(projectName, outputPath) {
+    return `${JSON.stringify({
+        name: projectName,
+        version: "1.0.0",
+        type: "module",
+        scripts: {
+            build: `agent-hooks --agent antigravity -i "src/**/*.ts" -o "${outputPath}"`,
+            test: "vitest run",
+            lint: "biome check .",
+            typecheck: "tsc --noEmit",
+        },
+        dependencies: { [PACKAGE_NAME]: "^1.0.9" },
+        devDependencies: {
+            "@biomejs/biome": "2.4.9",
+            "@types/node": "^24.0.0",
+            typescript: "^5.9.3",
+            vitest: "^4.0.13",
+        },
+        engines: { node: ">=20.11.0" },
+    }, null, 2)}\n`;
+}
+function pluginJson(projectName) {
+    return `${JSON.stringify({
+        name: projectName,
+        version: "1.0.0",
+        description: `Antigravity hooks built with ${PACKAGE_NAME}`,
+    }, null, 2)}\n`;
+}
+function tsConfig() {
+    return `${JSON.stringify({
+        compilerOptions: {
+            target: "ES2022",
+            module: "NodeNext",
+            moduleResolution: "NodeNext",
+            strict: true,
+            esModuleInterop: true,
+            skipLibCheck: true,
+        },
+        include: ["src/**/*.ts", "test/**/*.ts"],
+        exclude: ["dist", "node_modules"],
+    }, null, 2)}\n`;
+}
+function biomeConfig() {
+    return `{
+  "$schema": "https://biomejs.dev/schemas/2.4.9/schema.json",
+  "formatter": { "enabled": true, "indentStyle": "space", "indentWidth": 2, "lineWidth": 120 },
+  "linter": { "enabled": true, "rules": { "recommended": true } },
+  "assist": { "actions": { "source": { "organizeImports": "on" } } },
+  "files": { "includes": ["src/**/*.ts", "test/**/*.ts", "*.ts"] }
+}
+`;
+}
+function vitestConfig() {
+    return `import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: { include: ["test/**/*.test.ts"] },
+});
+`;
+}
+function readme(projectName, events) {
+    return `# ${projectName}
+
+Antigravity hooks built with \`${PACKAGE_NAME}\`. This project includes: ${events.map((event) => `\`${event}\``).join(", ")}.
+
+Run \`npm install\`, then \`npm run build\` to compile the hooks and write \`hooks.json\`. Antigravity reads that manifest from the plugin root and runs each command with its working directory set to the manifest's own directory, so the generated commands are relative and need no rewriting after install.
+
+Every hook replies at exit 0: Antigravity has no exit-code channel, and each decision travels inside the JSON payload on stdout.
+`;
+}
+function gitignore() {
+    return `bin/
+dist/
+node_modules/
+*.log
+`;
+}
+function hookSource(event) {
+    const factory = EVENT_TO_FACTORY[event];
+    const output = EVENT_TO_OUTPUT[event];
+    switch (event) {
+        case "PreToolUse":
+            return `import { ${factory}, ${output} } from "${IMPORT_SPECIFIER}";
+
+export default ${factory}({ matcher: "run_command" }, (input) => {
+  // Antigravity gives tool arguments no fixed schema, so narrow before reading.
+  const commandLine = input.toolCall.args.CommandLine;
+  if (typeof commandLine === "string" && commandLine.includes("rm -rf")) {
+    return ${output}({ decision: "deny", reason: "Refusing a destructive shell command." });
+  }
+  return ${output}({ decision: "allow" });
+});
+`;
+        case "PostToolUse":
+            return `import { ${factory}, ${output} } from "${IMPORT_SPECIFIER}";
+
+export default ${factory}({ matcher: "run_command" }, (input, { logger }) => {
+  // PostToolUse has no reply channel: the contract defines its output as {}.
+  // Report findings through the logger, never through stdout.
+  logger.info("Tool step finished", { stepIdx: input.stepIdx, error: input.error });
+  return ${output}();
+});
+`;
+        case "PreInvocation":
+            return `import { ${factory}, ${output} } from "${IMPORT_SPECIFIER}";
+
+export default ${factory}({}, () => {
+  return ${output}({
+    injectSteps: [{ ephemeralMessage: "Check for lint errors before proposing changes." }],
+  });
+});
+`;
+        case "PostInvocation":
+            return `import { ${factory}, ${output} } from "${IMPORT_SPECIFIER}";
+
+export default ${factory}({}, (input) => {
+  if (input.invocationNum < 2) {
+    return ${output}({ terminationBehavior: "force_continue" });
+  }
+  return ${output}({});
+});
+`;
+        case "Stop":
+            return `import { ${factory}, ${output} } from "${IMPORT_SPECIFIER}";
+
+export default ${factory}({}, (input) => {
+  if (!input.fullyIdle) {
+    return ${output}({ decision: "continue", reason: "Background tasks are still running." });
+  }
+  return ${output}({});
+});
+`;
+    }
+}
+function hookTest(event) {
+    return `import { describe, expect, it } from "vitest";
+import hook from "../src/${kebab(event)}.js";
+
+describe("${event} hook", () => {
+  it("exports a ${event} hook", () => {
+    expect(hook.hookEventName).toBe("${event}");
+  });
+});
+`;
+}
+/** Creates a new Antigravity hook project. Refuses to write into an existing directory. */
+export function scaffoldProject(options) {
+    const validation = validateHookNames(options.hooks);
+    if (!validation.valid) {
+        throw new Error(validation.error);
+    }
+    const { directory, outputPath } = options;
+    if (fs.existsSync(directory)) {
+        throw new Error(`Directory already exists: ${directory}`);
+    }
+    fs.mkdirSync(path.join(directory, "src"), { recursive: true });
+    fs.mkdirSync(path.join(directory, "test"), { recursive: true });
+    const projectName = path.basename(directory);
+    fs.writeFileSync(path.join(directory, "package.json"), packageJson(projectName, outputPath));
+    fs.writeFileSync(path.join(directory, "plugin.json"), pluginJson(projectName));
+    fs.writeFileSync(path.join(directory, "tsconfig.json"), tsConfig());
+    fs.writeFileSync(path.join(directory, "biome.json"), biomeConfig());
+    fs.writeFileSync(path.join(directory, "vitest.config.ts"), vitestConfig());
+    fs.writeFileSync(path.join(directory, ".gitignore"), gitignore());
+    fs.writeFileSync(path.join(directory, "README.md"), readme(projectName, validation.normalized));
+    for (const event of validation.normalized) {
+        fs.writeFileSync(path.join(directory, "src", `${kebab(event)}.ts`), hookSource(event));
+        fs.writeFileSync(path.join(directory, "test", `${kebab(event)}.test.ts`), hookTest(event));
+    }
+}

package/dist/agents/antigravity/transport.js

@@ -3,7 +3,7 @@
  * `drive()`/`Transport` interface — the same seam Claude Code's and Codex's
  * transports are rewritten/re-exported against.
  *
- * Antigravity's wire semantics are the simplest of the three shipped agents,
+ * Antigravity's wire semantics are the simplest of the four shipped agents,
  * and also the least forgiving: **every reply exits 0, unconditionally.**
  * There is no exit-code channel at all — not the 2-of-30-events native-deny
  * split Claude Code has, not Codex's uniform stderr+exit-2 `BlockError`
@@ -16,6 +16,8 @@
  *   ...fields }` on stdout at exit 0 — this is why the class is a stated
  *   prerequisite (`outputs.ts` module docs, `events.ts` module docs): with no
  *   exit-code fallback, a block computed mid-throw has nowhere else to land.
+ *   The host acts on that decision for `PreToolUse`; on the other four events
+ *   it is a well-formed reply carrying no decision the host recognizes.
  * - an unexpected handler/runtime failure → its stacktrace on stderr
  *   (diagnostic only, not a wire signal) plus the empty response `{}` on
  *   stdout, still at exit 0.

package/dist/agents/antigravity/types.js

@@ -1,11 +1,18 @@
 /**
- * Antigravity wire types (plan step 5, item-6 descope: typed factories +
- * output builders + conformance matrix only — no `CONTRACT.md` pin, no
- * published protocol doc exists for this release). Shapes below are the
- * minimal surface the plan names for the five shipped events
- * (`PreToolUse`/`PostToolUse`/`PreInvocation`/`PostInvocation`/`Stop`),
- * derived structurally from Claude Code's and Codex's `types.ts` rather than
- * from any Antigravity-specific reference — there is none to cite yet.
+ * Antigravity wire types, transcribed from the host's own hook reference.
+ *
+ * Source of record: `assets/external/skills/agy-customizations/docs/hooks.md`,
+ * embedded in the `agy` binary and pinned verbatim in this directory's
+ * `CONTRACT.md`. Nothing here is derived by analogy from Claude Code or
+ * Codex — the three agents' payloads share no field.
+ *
+ * Two properties of this contract drive every shape below:
+ *
+ * 1. **All keys are camelCase** (protojson encoding), including `stepIdx` and
+ *    `conversationId`.
+ * 2. **No payload carries its own event name.** Claude Code's
+ *    `hook_event_name` and Codex's equivalent have no counterpart here; a
+ *    handler knows its event only from the factory it was built with.
  * @module
  */
 export {};

package/dist/agents/codex/scaffold.js

@@ -55,7 +55,7 @@ function generatePackageJson(projectName, outputPath) {
             typecheck: "tsc --noEmit",
         },
         dependencies: {
-            [PACKAGE_NAME]: "^1.0.7",
+            [PACKAGE_NAME]: "^1.0.9",
         },
         devDependencies: {
             "@biomejs/biome": "2.4.9",

package/dist/cli.js

@@ -26,7 +26,7 @@ import { scaffoldProject } from "./scaffold.js";
 // ============================================================================
 // Constants
 // ============================================================================
-const VERSION = "1.0.7";
+const VERSION = "1.0.9";
 const DEFAULT_ESBUILD_LOADERS = {
     ".md": "text",
 };
@@ -71,6 +71,10 @@ Required Arguments:
       bundle. There is no default: omitting this flag is an error.
       With --agent opencode, -o/--output is treated as a plugin artifact
       directory (no hooks.json manifest is generated).
+      With --agent antigravity, -o/--output is the hooks.json path at the
+      plugin root; bundles are written to a bin/ directory beside it and the
+      generated commands are relative to the manifest, which is the working
+      directory Antigravity runs each handler in.
       Example: --agent claude-code
 
 Build Mode (compile existing hooks):
@@ -94,6 +98,8 @@ Scaffold Mode (create new hook project):
       Valid types: PreToolUse, PostToolUse, PostToolUseFailure, Notification,
                    UserPromptSubmit, SessionStart, SessionEnd, Stop,
                    SubagentStart, SubagentStop, PreCompact, PermissionRequest
+      With --agent antigravity the valid types are: PreToolUse, PostToolUse,
+                   PreInvocation, PostInvocation, Stop
       Example: --hooks Stop,SubagentStop,PreToolUse
 
   -o, --output <path>
@@ -1252,9 +1258,61 @@ async function main() {
             closeLog();
         }
     }
-    // Antigravity ships in step 5; fail closed until then.
+    // Antigravity's manifest shape has no counterpart in the other agents: the
+    // top-level keys are hook names, only two of the five events wrap their
+    // handlers in a matcher group, and the host sets each handler's working
+    // directory to the manifest's own directory. See
+    // src/agents/antigravity/CONTRACT.md.
+    if (args.agent === "antigravity") {
+        const { runAntigravityCli, validateAntigravityArgs } = await import("./agents/antigravity/cli-support.js");
+        const antigravityValidationError = validateAntigravityArgs({
+            input: args.input,
+            output: args.output,
+            loaderFlags: args.loaderFlags ?? [],
+            sourcemap: args.sourcemap,
+            stableNames: args.stableNames,
+            scaffold: args.scaffold,
+            hooks: args.hooks,
+        });
+        if (antigravityValidationError !== undefined) {
+            process.stderr.write(`Error: ${antigravityValidationError}\n\n`);
+            process.stdout.write(HELP_TEXT);
+            process.exit(1);
+        }
+        try {
+            const compiledCount = await runAntigravityCli({
+                input: args.input,
+                output: args.output,
+                executable: args.executable,
+                loaderFlags: args.loaderFlags ?? [],
+                sourcemap: args.sourcemap,
+                stableNames: args.stableNames,
+                scaffold: args.scaffold,
+                hooks: args.hooks,
+            });
+            if (args.scaffold !== undefined && args.scaffold !== "") {
+                process.stdout.write(`Scaffolded ${path.resolve(process.cwd(), args.scaffold)}\n`);
+            }
+            else {
+                process.stdout.write(`Generated ${path.resolve(process.cwd(), args.output)} with ${compiledCount} hook(s)\n`);
+            }
+            process.exit(0);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            log("error", "Antigravity build failed", { error: message });
+            process.stderr.write(`Error: ${message}\n`);
+            process.exit(1);
+        }
+        finally {
+            closeLog();
+        }
+    }
+    // Everything below is the Claude Code path. Each other agent returns from
+    // its own branch above, so reaching here with a different agent would mean
+    // a branch was removed without removing its VALID_AGENTS entry.
     if (args.agent !== "claude-code") {
-        process.stderr.write(`Error: --agent ${args.agent} is not implemented in this release; only "claude-code", "codex", and "opencode" build today (antigravity ships in step 5).\n`);
+        process.stderr.write(`Error: --agent ${args.agent} has no build branch.\n`);
         process.exit(1);
     }
     // Handle scaffold mode

package/dist/index.js

@@ -6,8 +6,8 @@
  * {@link HookBlockError}, the Logger, env utilities, and stdin helpers.
  *
  * Per-agent entry points (`@goodfoot/agent-hooks/claude-code`, `/codex`,
- * `/antigravity`) are added to the package `exports` map only in the step
- * that lands their implementation — never pre-declared.
+ * `/opencode`, `/antigravity`) expose each host's native protocol without
+ * leaking host-specific types through this root module.
  * @module
  */
 export { defineHook } from "./core/define-hook.js";

package/dist/scaffold.js

@@ -131,7 +131,7 @@ function generatePackageJson(projectName, outputPath) {
             typecheck: "tsc --noEmit",
         },
         dependencies: {
-            "@goodfoot/agent-hooks": "^1.0.7",
+            "@goodfoot/agent-hooks": "^1.0.9",
         },
         devDependencies: {
             "@biomejs/biome": "2.4.16",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodfoot/agent-hooks",
-  "version": "1.0.7",
+  "version": "1.0.9",
   "description": "Unified agent hooks library: shared core runtime with per-agent entry points for Claude Code, Codex, and Antigravity",
   "homepage": "https://github.com/goodfoot-io/marketplace/tree/main/packages/agent-hooks",
   "repository": {
@@ -43,6 +43,10 @@
     "./opencode": {
       "import": "./dist/agents/opencode/index.js",
       "types": "./types/agents/opencode/index.d.ts"
+    },
+    "./antigravity": {
+      "import": "./dist/agents/antigravity/index.js",
+      "types": "./types/agents/antigravity/index.d.ts"
     }
   },
   "bin": "./dist/cli.js",

package/types/agents/antigravity/cli-support.d.ts

@@ -0,0 +1,100 @@
+/**
+ * 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 esbuild from "esbuild";
+import type { HookEventName } from "./types.js";
+/** Arguments the `--agent antigravity` branch accepts. */
+export interface AntigravityCliArgs {
+    input: string;
+    output: string;
+    executable?: string;
+    loaderFlags: string[];
+    sourcemap?: boolean;
+    stableNames?: boolean;
+}
+/** What the analyzer recovers from one hook source file. */
+export interface AntigravityHookMetadata {
+    hookEventName: HookEventName;
+    matcher?: string;
+    /** As written in the source config, in milliseconds. Converted to seconds on the wire. */
+    timeout?: number;
+}
+interface CompiledAntigravityHook {
+    sourcePath: string;
+    outputPath: string;
+    hookName: string;
+    metadata: AntigravityHookMetadata;
+}
+/** One handler entry, as it appears in `hooks.json`. */
+export interface AntigravityHandler {
+    type: "command";
+    command: string;
+    timeout: number;
+}
+/** A grouped entry, used by `PreToolUse` and `PostToolUse` only. */
+export interface AntigravityMatcherGroup {
+    matcher: string;
+    hooks: AntigravityHandler[];
+}
+/**
+ * One named hook's event table. Grouped events carry
+ * {@link AntigravityMatcherGroup} entries; flat events carry handlers
+ * directly.
+ */
+export type AntigravityNamedHook = {
+    [Event in HookEventName]?: Event extends "PreToolUse" | "PostToolUse" ? AntigravityMatcherGroup[] : AntigravityHandler[];
+};
+/** The whole manifest: hook name to event table. */
+export type AntigravityHooksJson = Record<string, AntigravityNamedHook>;
+/**
+ * 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 declare function analyzeAntigravityHookFile(sourcePath: string): AntigravityHookMetadata | undefined;
+/**
+ * Bundles one hook source into a self-contained ESM executable whose entry
+ * wrapper calls this agent's `execute`.
+ */
+export declare function compileAntigravityHook(sourcePath: string, loaders: Record<string, esbuild.Loader>, sourcemap?: boolean): Promise<{
+    content: string;
+    contentHash: string;
+}>;
+/**
+ * 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 declare function generateAntigravityHooksJson(compiled: CompiledAntigravityHook[], manifestPath: string, executable?: string): AntigravityHooksJson;
+/** Validates the Antigravity build arguments beyond the shared `--agent` gate. */
+export declare function validateAntigravityArgs(args: AntigravityCliArgs & {
+    scaffold?: string;
+    hooks?: string;
+}): string | 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 declare function runAntigravityCli(args: AntigravityCliArgs & {
+    scaffold?: string;
+    hooks?: string;
+}): Promise<number>;
+export {};

package/types/agents/antigravity/constants.d.ts

@@ -0,0 +1,15 @@
+import type { HookEventName } from "./types.js";
+export declare const PACKAGE_NAME = "@goodfoot/agent-hooks";
+/** The host's own default handler timeout, in seconds (`CONTRACT.md`, Hook Handler Fields). */
+export declare const DEFAULT_TIMEOUT_SECONDS = 30;
+export declare const DEFAULT_ESBUILD_LOADERS: {
+    readonly ".md": "text";
+};
+/** Maps each exported factory name to the event it binds. */
+export declare const HOOK_FACTORY_TO_EVENT: Record<string, HookEventName>;
+/**
+ * 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 declare const GROUPED_EVENTS: Set<HookEventName>;