From 683c7508fc4c23e38a43dc3629004284dd229e37 Mon Sep 17 00:00:00 2001
From: Thierry Kwiatkowski <tkman59@gmail.com>
Date: Mon, 5 Oct 2026 22:31:23 +0200
Subject: [PATCH] feat(cli): merge plugin hooks into antigravity's
 .agents/hooks.json

Antigravity now receives the aidd-context memory hook. Setup and plugin
install merge each plugin's hooks into .agents/hooks.json under one key
named after the plugin, copy its scripts under .agents/hooks/<plugin>/,
and clean removes that key alone, deleting the file only when empty.

The project-hooks route Cursor used is generalised: a tool declares a
ProjectHooksFormat beside hooksDestination "project", now allowed in flat
mode too, and the installer and uninstaller read only that. Cursor's
behaviour is unchanged. An unparsable project hooks file now stops the
install with the file named.

agy 1.2.17 rejects Claude's nested { hooks: [...] } groups and runs a
workspace hook from <repo>/.agents through a shell, so each command is
prefixed with "cd .. && "; events other than SessionStart are skipped
with a warning.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../phase-3.md                                |  63 +++++---
 .../2026_10_02_antigravity-flat-host/plan.md  |   7 +-
 .../translator/project-hooks-materializer.ts  |  50 ++++---
 .../shared/remove-project-hooks.ts            |  95 ++++++------
 .../contexts/tools/domain/build-contract.ts   |   3 +-
 .../domain/capabilities/plugins-capability.ts |  44 ++++--
 .../formats/cursor-hooks-project-merge.ts     |  21 +++
 .../domain/formats/project-hooks-format.ts    |  17 +++
 .../profiles/antigravity/antigravity-hooks.ts |  77 ++++++++++
 .../profiles/antigravity/antigravity-paths.ts |   2 +
 .../domain/profiles/antigravity/build.ts      |  13 +-
 .../domain/profiles/antigravity/profile.ts    |  15 +-
 .../tools/domain/profiles/cursor/profile.ts   |   2 +
 cli/src/contexts/tools/domain/registry.ts     |  17 +++
 .../strategies/flat-build-strategy.ts         |   2 +-
 .../context-boundary.arch.test.ts             |   1 +
 .../project-hooks-materializer.unit.test.ts   |  75 ++++++++++
 .../plugins-capability.unit.test.ts           |  28 ++++
 .../antigravity-hooks.unit.test.ts            | 137 ++++++++++++++++++
 .../profiles/antigravity/build.unit.test.ts   |  39 ++++-
 .../profiles/antigravity/profile.unit.test.ts |  10 +-
 .../domain/profiles/claude/build.unit.test.ts |   4 +-
 .../domain/profiles/codex/build.unit.test.ts  |   2 +-
 .../domain/registry-conformance.unit.test.ts  |   4 +
 .../tools/domain/registry.unit.test.ts        |   2 +
 .../snapshots/framework-build/golden.json     |   4 +-
 26 files changed, 603 insertions(+), 131 deletions(-)
 create mode 100644 cli/src/contexts/tools/domain/formats/project-hooks-format.ts
 create mode 100644 cli/src/contexts/tools/domain/profiles/antigravity/antigravity-hooks.ts
 create mode 100644 cli/tests/contexts/tools/domain/profiles/antigravity/antigravity-hooks.unit.test.ts

diff --git a/aidd_docs/tasks/2026_10/2026_10_02_antigravity-flat-host/phase-3.md b/aidd_docs/tasks/2026_10/2026_10_02_antigravity-flat-host/phase-3.md
index ddaf5696f..9ecbafac5 100644
--- a/aidd_docs/tasks/2026_10/2026_10_02_antigravity-flat-host/phase-3.md
+++ b/aidd_docs/tasks/2026_10/2026_10_02_antigravity-flat-host/phase-3.md
@@ -1,5 +1,5 @@
 ---
-status: pending
+status: done
 ---
 
 <!-- Fill or omit these sections; never add, rename, or reorder one. -->
@@ -12,13 +12,26 @@ status: pending
 
 ```txt
 cli/
-├── src/contexts/tools/domain/profiles/antigravity/
-│   ├── antigravity-hooks.ts      ✅ named-hook shape: merge AIDD's `aidd-memory` key into `.agents/hooks.json`, strip it on uninstall, convert Claude-shaped flat hooks
-│   ├── profile.ts                ✏️ HooksCapability on `.agents/hooks.json`
-│   └── build.ts                  ✏️ hooks artifact: scripts under `.agents/hooks/<plugin>/`, hooksMerge into `.agents/hooks.json`
+├── src/contexts/tools/domain/
+│   ├── formats/
+│   │   ├── project-hooks-format.ts        ✅ per-tool project hooks file strategy: merge, unmerge, contributed entries, empty check, script path and dir
+│   │   └── cursor-hooks-project-merge.ts  ✏️ Cursor's functions exposed as one `ProjectHooksFormat`, behaviour unchanged
+│   ├── capabilities/plugins-capability.ts ✏️ `hooksDestination: "project"` + `projectHooksRelativePath` + `projectHooksFormat` allowed on flat params too
+│   ├── build-contract.ts                  ✏️ `hooksMerge` receives the plugin name
+│   └── profiles/
+│       ├── cursor/profile.ts              ✏️ declares Cursor's `ProjectHooksFormat`
+│       └── antigravity/
+│           ├── antigravity-hooks.ts       ✅ named-hook shape: one `<plugin>` key, handlers under `SessionStart`, `cd .. && ` prefix, other events skipped with a warning
+│           ├── profile.ts                 ✏️ flat `acceptsHooks: true`, `hooksDestination: "project"` on `.agents/hooks.json`
+│           └── build.ts                   ✏️ hooks artifact: scripts under `.agents/hooks/<plugin>/`, hooksMerge into `.agents/hooks.json`
+├── src/contexts/framework/application/
+│   ├── framework/translator/project-hooks-materializer.ts  ✏️ reads the tool's `ProjectHooksFormat`; invalid JSON names the file; messages name the tool
+│   └── shared/remove-project-hooks.ts                      ✏️ same, no Cursor import left
+├── src/contexts/translate/application/strategies/flat-build-strategy.ts  ✏️ passes the plugin name to `hooksMerge`
 ├── tests/contexts/tools/domain/profiles/antigravity/
-│   └── antigravity-hooks.unit.test.ts   ✅ merge, idempotence, foreign keys kept, invalid JSON, strip
-├── tests/contexts/tools/domain/build-hooks-support-declaration.unit.test.ts   ✏️ antigravity now supports hooks
+│   └── antigravity-hooks.unit.test.ts     ✅ merge, idempotence, foreign keys kept, invalid JSON, unmerge, empty check, unmapped event warning
+├── tests/ (Cursor project-hooks suites)   ✏️ only messages that named Cursor generically, if any; behaviour assertions untouched
+├── tests/ (antigravity profile, build, build-hooks-support-declaration, registry-conformance)  ✏️ antigravity now delivers hooks to `.agents/hooks.json`
 └── tests/golden/snapshots/framework-build/golden.json   ✏️ `antigravity:flat` cell only
 ```
 
@@ -26,10 +39,10 @@ cli/
 
 ```mermaid
 flowchart TD
-  A[aidd setup --ai antigravity] --> B[.agents/hooks.json gains key aidd-memory with SessionStart command]
+  A[aidd setup --ai antigravity] --> B[.agents/hooks.json gains key aidd-context with SessionStart command, script under .agents/hooks/aidd-context/]
   B --> C[agy new session in trusted folder]
   C --> D[log: loaded N named hooks; memory refresh runs at repo root]
-  E[aidd clean antigravity] --> F[aidd-memory key removed, other named hooks kept, file deleted only if empty]
+  E[aidd clean antigravity] --> F[aidd-context key and its scripts removed, other named hooks kept, file deleted only if empty]
 ```
 
 ## Test Scope
@@ -40,9 +53,9 @@ title: Test scope
 ---
 journey
   section Setup
-    agy 1.2.14 logged in, probe hook printing cwd and workspacePaths => measured cwd recorded: 5: system
+    agy 1.2.17 logged in, interactive session under a pty, probe hook printing cwd and workspacePaths => measured cwd recorded: 5: system
   section Happy path
-    aidd setup --ai antigravity on empty project => .agents/hooks.json has aidd-memory SessionStart entry: 5: cli
+    aidd setup --ai antigravity on empty project => .agents/hooks.json has aidd-context SessionStart entry: 5: cli
     second setup => file byte-identical: 5: cli
     translate --to antigravity --as flat => same hooks.json shape and scripts under .agents/hooks/: 5: cli
   section Edge case - user hooks present
@@ -55,25 +68,29 @@ journey
 
 ## Tasks to do
 
-### `1)` Measure the hook `cwd` on 1.2.14
+### `1)` Measure the hook `cwd` on 1.2.17
 
 > #890 measured `cwd = <repo>/.agents` on 1.2.5; `update_memory.js` silently no-ops when `aidd_docs/` is not in `cwd`.
 
-1. Local probe: a `SessionStart` hook writing `pwd` and its stdin payload to a marker; read the marker, not the turn.
-2. Pick the command from the result: if `cwd` is `.agents`, the command must reach the repo root (e.g. `node ../.aidd/scripts/update_memory.cjs`, or a root resolved from `workspacePaths[0]`); record the evidence in the PR.
+1. Local probe: a `SessionStart` hook writing `pwd` and its stdin payload to a marker; read the marker, not the turn. On 1.2.17 a print-mode turn never reaches the model and fires no hook at all, so the probe runs interactive under a pty: `script -q /dev/null agy -i "reply OK" --add-dir <ws>`, killed after 60s. Without `--add-dir` it loads 0 hooks.
+2. Measured on 2026-10-05: `cwd` is `<repo>/.agents`, as on 1.2.5; stdin carries `workspacePaths[0]` = `<repo>`. A root-relative command needs a `cd .. && ` prefix, and `agy` runs it through a shell: a real session running `cd .. && node <root-relative script>` wrote `AIDD-MEMORY-MARKER cwd=<repo> docs=true`. Record the evidence in the PR.
 
-### `2)` Named-hook merge, test first
+### `2)` Named-hook format, test first
 
-> Shape `{ "<name>": { "SessionStart": [ { "hooks": [ { "type": "command", "command": "…", "timeout": 30 } ] } ] } }`, no wrapper.
+> Shape `{ "<name>": { "SessionStart": [ { "type": "command", "command": "…", "timeout": 30 } ] } }`: no top-level `hooks` wrapper, and handlers sit directly under the event. 1.2.17 rejects the Claude-style nested `[ { "hooks": [ … ] } ]` with `command hook must specify 'command'`; only `PreToolUse` and `PostToolUse` take a `matcher` entry.
 
-1. Tests: empty file, existing foreign keys, re-run idempotent, invalid JSON fails loud (Codex's silent `catch { parsed = {} }` is not copied), strip leaves foreign keys.
-2. Implement in `antigravity-hooks.ts`; mutate the foreign-key preservation and watch its test fail.
+1. Tests: empty file, existing foreign keys, re-run idempotent, invalid JSON fails loud (Codex's silent `catch { parsed = {} }` is not copied), unmerge leaves foreign keys, empty check, an event other than `SessionStart` skipped with a warning (Claude and `agy` tool names differ; the telemetry host is out of scope).
+2. Implement in `antigravity-hooks.ts` as a `ProjectHooksFormat`: the key is the plugin name, each command gets `cd .. && ` and runs `./.agents/hooks/<plugin>/<script>`. Mutate the foreign-key preservation and watch its test fail.
 
-### `3)` Wire setup and translate
+### `3)` Wire setup, clean and translate
 
-1. `profile.ts`: `HooksCapability` targeting `.agents/hooks.json` with the merge and strip; `acceptsHooks` stays false for plugin flat install so the hook is not written twice.
-2. `build.ts`: hooks `hooksBundle`, scripts to `.agents/hooks/<plugin>/`, `hooksMerge` + `hooksMergeDest` converting the rewritten Claude-shaped JSON to one named key per plugin.
-3. Confirm the flat-rewritten script path resolves from the measured `cwd`.
+> `HooksCapability` is not the route: no config ref `codex-hooks` exists, so Codex's own declaration never writes anything and nothing installs `.aidd/scripts/update_memory.cjs`. The memory hook reaches a project through the `aidd-context` plugin; Cursor already merges plugin hooks into a project hooks file with per-entry provenance, and both install routes call `ProjectHooksMaterializer` whenever a tool declares `hooksDestination: "project"`.
+
+1. Generalise, Cursor behaviour unchanged first: extract `ProjectHooksFormat`, have the materializer and `remove-project-hooks.ts` read it from the capability instead of importing Cursor's functions. Cursor's suites stay green with no assertion change. If the PR nears 600 lines, this step ships as its own PR first.
+2. Allow flat params to declare `hooksDestination: "project"`, `projectHooksRelativePath` and `projectHooksFormat`; the constructor guard keeps requiring the path.
+3. `profile.ts`: flat `acceptsHooks: true`, `hooksDestination: "project"`, `projectHooksRelativePath: ".agents/hooks.json"`, the Antigravity format.
+4. `build.ts`: hooks `hooksBundle`, scripts to `.agents/hooks/<plugin>/`, `hooksMerge` + `hooksMergeDest` with the same format function, the plugin name now passed by `flat-build-strategy.ts`.
+5. Confirm with a real `aidd setup --ai antigravity` in a temp project, then `agy` under a pty: the memory refresh runs at repo root.
 
 ### `4)` Golden and suite
 
@@ -85,6 +102,6 @@ journey
 | Task | Acceptance criteria |
 | ---- | ------------------- |
 | 1 | The PR quotes the measured `cwd` and the marker line from a real `agy` session |
-| 2 | Foreign named hooks survive setup and clean; a second setup changes nothing; invalid JSON stops with the file named |
+| 2 | Foreign named hooks survive setup and clean; a second setup changes nothing; invalid JSON stops with the file named; a non-`SessionStart` event is skipped with a warning |
 | 3 | After setup, a new `agy` session logs `loaded … named hooks` and the memory refresh marker appears at repo root |
 | 4 | Only the `antigravity:flat` golden cell changes; full suite passes |
diff --git a/aidd_docs/tasks/2026_10/2026_10_02_antigravity-flat-host/plan.md b/aidd_docs/tasks/2026_10/2026_10_02_antigravity-flat-host/plan.md
index 066fde357..f634dcd76 100644
--- a/aidd_docs/tasks/2026_10/2026_10_02_antigravity-flat-host/plan.md
+++ b/aidd_docs/tasks/2026_10/2026_10_02_antigravity-flat-host/plan.md
@@ -27,19 +27,20 @@ status: in-progress
 
 | Source | Verified |
 | ------ | -------- |
-| https://antigravity.google/docs/hooks | `hooks.json` is keyed by hook name, no `hooks` wrapper; events `PreToolUse`, `PostToolUse`, `PreInvocation`, `PostInvocation`, `Stop`; `SessionStart` works though undocumented (spike, #890) |
+| https://antigravity.google/docs/hooks | `hooks.json` is keyed by hook name, no `hooks` wrapper; handlers sit directly under an event, a `matcher` entry only for `PreToolUse`/`PostToolUse`; events `PreToolUse`, `PostToolUse`, `PreInvocation`, `PostInvocation`, `Stop`; `SessionStart` works though undocumented (spike, #890) |
 | https://antigravity.google/docs/subagents?tab=cli | agents at `.agents/agents/<name>.md` or `<name>/agent.md`; `name`, `description` required; `model` in `inherit`/`flash`/`pro`; `tools` a YAML list |
 | Issue #890 | hooks only from `hooks.json`; hook process `cwd` is `<repo>/.agents` on 1.2.5 |
 | Issue #916 comments | `agy` silently drops an agent with `model: sonnet`/`opus` or a comma-separated `tools`, while `plugin validate` passes |
 | Spike, 2026-10-02 | print-mode turns hang after answering: runtime evidence reads `cli-*.log` lines and markers, never the turn's end; a turn needs a login, so no CI runtime smoke |
+| Probe, 2026-10-05, `agy` 1.2.17 | print mode never reaches the model and fires no hook; an interactive session under a pty with `--add-dir` does. Hook `cwd` is `<repo>/.agents`, stdin `workspacePaths[0]` is `<repo>` |
 
 ## Decisions
 
 | Decision | Why |
 | -------- | --- |
 | The shared plugin-path uninstall bug stays out of #511; phases are numbered 2 to 5 | Codex and Antigravity both write `.agents/skills/`, and uninstalling one deletes plugin files the other still records (probe `uninstall-tools-shared-plugin-path.probe.unit.test.ts` fails). Product owner's call on 2026-10-05: track it separately, ship #511 with it as a known limitation |
-| Setup writes the memory hook through a `HooksCapability` on `.agents/hooks.json`, like Codex, not through a JS bridge like Kilo | `agy` reads a JSON file natively; a bridge only exists where the host has no hooks file |
-| The hook command is chosen from a measured `cwd` on `agy` 1.2.14, not assumed | `update_memory.js` exits 0 in silence when `aidd_docs/` is absent from `cwd`, so a wrong `cwd` looks like success |
+| Setup and `plugin add` merge the `aidd-context` plugin's hooks into `.agents/hooks.json` through the project-hooks route Cursor uses, generalised to a per-tool format; not through `HooksCapability`, not through a JS bridge like Kilo | `agy` reads a JSON file natively; Codex's `HooksCapability` is never fed (no `codex-hooks` config ref exists), so copying it would write nothing; the project-hooks route already has idempotent merge, provenance and clean |
+| The hook command is chosen from a measured `cwd` on `agy` 1.2.17 (`<repo>/.agents`, so `cd .. && node …`), not assumed | `update_memory.js` exits 0 in silence when `aidd_docs/` is absent from `cwd`, so a wrong `cwd` looks like success |
 | The portable agent frontmatter builder lives in `tools/domain/formats/`, not in the profile | it is a cross-host shape (#916 reuses it for Codex flat and Kimi); only the Antigravity paths stay in `profiles/antigravity/` |
 | No CI runtime smoke; CI gets the golden cell and the `build-per-tool` matrix row only | a turn needs a Google login and print mode hangs; the Kilo review's "real binary in the gate" lesson cannot hold here, so the PR says so instead of shipping a skipped test |
 | Native plugin mode, telemetry host, duplicate-agent-name rejection stay out | #511 out of scope; duplicate `name` rejection belongs to #916 |
diff --git a/cli/src/contexts/framework/application/framework/translator/project-hooks-materializer.ts b/cli/src/contexts/framework/application/framework/translator/project-hooks-materializer.ts
index 792d10837..3cea830bf 100644
--- a/cli/src/contexts/framework/application/framework/translator/project-hooks-materializer.ts
+++ b/cli/src/contexts/framework/application/framework/translator/project-hooks-materializer.ts
@@ -1,12 +1,8 @@
 import { dirname, join } from "node:path";
-import {
-  cursorProjectHooksScriptPath,
-  mergeCursorProjectHooksJson,
-} from "../../../../../contexts/tools/domain/formats/cursor-hooks-project-merge.js";
 import type { FileReader } from "../../../../../kernel/ports/file-reader.js";
 import type { FileWriter } from "../../../../../kernel/ports/file-writer.js";
 import type { AiToolId } from "../../../../../kernel/tool.js";
-import { resolvePluginsCapability } from "../../../../tools/domain/registry.js";
+import { projectHooksDeliveryOf } from "../../../../tools/domain/registry.js";
 import {
   type PluginComponentFile,
   PluginDistribution,
@@ -24,6 +20,8 @@ import {
 
 const HOOKS_MANIFEST_PATH = "hooks/hooks.json";
 
+type ProjectHooksDelivery = NonNullable<ReturnType<typeof projectHooksDeliveryOf>>;
+
 /**
  * Delivers a plugin's hooks to the destination a `hooksDestination: "project"` capability names —
  * merged into the project's own hooks file, scripts copied beside it — rather than into the
@@ -47,10 +45,8 @@ export class ProjectHooksMaterializer {
     projectRoot: string,
     previous?: ProjectHooksProvenance
   ): Promise<{ skipped: ReadonlySkipList; projectHooks?: ProjectHooksProvenance }> {
-    const pluginsCap = resolvePluginsCapability(toolId);
-    if (pluginsCap === null || pluginsCap.hooksDestination !== "project") return { skipped: [] };
-    const projectHooksRelativePath = pluginsCap.projectHooksRelativePath;
-    if (projectHooksRelativePath === null) return { skipped: [] };
+    const delivery = projectHooksDeliveryOf(toolId);
+    if (delivery === null) return { skipped: [] };
     const manifestFile = dist.components.hooks.find((f) => f.relativePath === HOOKS_MANIFEST_PATH);
     if (manifestFile === undefined) {
       if (previous !== undefined) {
@@ -65,15 +61,15 @@ export class ProjectHooksMaterializer {
       return { skipped: [] };
     }
     await assertProjectHooksUnchanged(this.fs, dist.manifest.name, previous, toolId, projectRoot);
-    await this.assertScriptsNotUserOwned(dist, projectRoot, previous);
+    await this.assertScriptsNotUserOwned(dist, projectRoot, delivery, previous);
     const { warnings, entries } = await this.mergeProjectHooksJson(
       dist,
       manifestFile,
       projectRoot,
-      projectHooksRelativePath
+      delivery
     );
-    const scripts = await this.writeProjectHooksScripts(dist, projectRoot);
-    await this.removeObsoleteScripts(previous, scripts, projectRoot);
+    const scripts = await this.writeProjectHooksScripts(dist, projectRoot, delivery);
+    await this.removeObsoleteScripts(previous, scripts, projectRoot, delivery);
     return {
       skipped: warnings.map(
         (reason): PluginTranslationSkip => ({
@@ -91,42 +87,49 @@ export class ProjectHooksMaterializer {
     dist: PluginDistribution,
     manifestFile: PluginComponentFile,
     projectRoot: string,
-    projectHooksRelativePath: string
+    delivery: ProjectHooksDelivery
   ): Promise<{ warnings: readonly string[]; entries: ProjectHooksProvenance["entries"] }> {
-    const destPath = join(projectRoot, projectHooksRelativePath);
+    const destPath = join(projectRoot, delivery.relativePath);
     const existing = await this.readExistingJson(destPath);
-    const { content, warnings } = mergeCursorProjectHooksJson(
+    const { content, warnings } = delivery.format.merge(
       existing,
       manifestFile.content,
       dist.manifest.name
     );
     await this.fs.writeFile(destPath, content);
-    return { warnings, entries: recordedProjectHookEntries(content, dist.manifest.name) };
+    return {
+      warnings,
+      entries: recordedProjectHookEntries(delivery.format, content, dist.manifest.name),
+    };
   }
 
   private async assertScriptsNotUserOwned(
     dist: PluginDistribution,
     projectRoot: string,
+    delivery: ProjectHooksDelivery,
     previous?: ProjectHooksProvenance
   ): Promise<void> {
     for (const file of dist.components.hooks) {
       if (file.relativePath === HOOKS_MANIFEST_PATH) continue;
-      const relativePath = cursorProjectHooksScriptPath(dist.manifest.name, file.relativePath);
+      const relativePath = delivery.format.scriptPath(dist.manifest.name, file.relativePath);
       if (previous?.scripts.has(relativePath) === true) continue;
       if (await this.fs.fileExists(join(projectRoot, relativePath))) {
-        throw new Error(`Cursor hook script '${relativePath}' is user-owned; install refused.`);
+        throw new Error(
+          `${delivery.toolName} hook script '${relativePath}' is user-owned; install refused.`
+        );
       }
     }
   }
 
   private async writeProjectHooksScripts(
     dist: PluginDistribution,
-    projectRoot: string
+    projectRoot: string,
+    delivery: ProjectHooksDelivery
   ): Promise<ReadonlyMap<string, string>> {
     const scripts = new Map<string, string>();
     for (const file of dist.components.hooks) {
       if (file.relativePath === HOOKS_MANIFEST_PATH) continue;
-      const dest = cursorProjectHooksScriptPath(dist.manifest.name, file.relativePath);
+      const dest = delivery.format.scriptPath(dist.manifest.name, file.relativePath);
       await this.fs.writeFile(join(projectRoot, dest), file.content);
       scripts.set(dest, (await this.fs.readFileHash(join(projectRoot, dest))).value);
     }
@@ -136,7 +139,8 @@ export class ProjectHooksMaterializer {
   private async removeObsoleteScripts(
     previous: ProjectHooksProvenance | undefined,
     current: ReadonlyMap<string, string>,
-    projectRoot: string
+    projectRoot: string,
+    delivery: ProjectHooksDelivery
   ): Promise<void> {
     if (previous === undefined) return;
     for (const [relativePath, digest] of previous.scripts) {
@@ -145,7 +149,7 @@ export class ProjectHooksMaterializer {
       if (!(await this.fs.fileExists(path))) continue;
       if ((await this.fs.readFileHash(path)).value !== digest) {
         throw new Error(
-          `Cursor hook script '${relativePath}' was edited during reinstall; removal refused.`
+          `${delivery.toolName} hook script '${relativePath}' was edited during reinstall; removal refused.`
         );
       }
       await this.fs.deleteFile(path);
diff --git a/cli/src/contexts/framework/application/shared/remove-project-hooks.ts b/cli/src/contexts/framework/application/shared/remove-project-hooks.ts
index c0674a0e2..faddd0448 100644
--- a/cli/src/contexts/framework/application/shared/remove-project-hooks.ts
+++ b/cli/src/contexts/framework/application/shared/remove-project-hooks.ts
@@ -3,19 +3,17 @@ import { dirname, join, posix } from "node:path";
 import type { FileReader } from "../../../../kernel/ports/file-reader.js";
 import type { FileWriter } from "../../../../kernel/ports/file-writer.js";
 import type { AiToolId } from "../../../../kernel/tool.js";
-import {
-  cursorProjectHooksScriptDir,
-  unmergeCursorProjectHooksJson,
-} from "../../../tools/domain/formats/cursor-hooks-project-merge.js";
-import { resolvePluginsCapability } from "../../../tools/domain/registry.js";
+import type {
+  ProjectHookEntry,
+  ProjectHooksFormat,
+} from "../../../tools/domain/formats/project-hooks-format.js";
+import { projectHooksDeliveryOf } from "../../../tools/domain/registry.js";
 import type {
   InstalledPlugin,
   ProjectHooksProvenance,
 } from "../../domain/plugins/installed-plugin.js";
 import { assertProjectPathWithinRoot } from "../ownership/project-path-boundary.js";
 
-type HookEntry = { command: string; [key: string]: unknown };
-
 /** Preflight the exact project hook entries and scripts installed by AIDD. Does not mutate. */
 export async function assertProjectHooksUnchanged(
   fs: FileReader,
@@ -24,21 +22,21 @@ export async function assertProjectHooksUnchanged(
   toolId: AiToolId,
   projectRoot: string
 ): Promise<{ existing: string | null }> {
-  const cap = resolvePluginsCapability(toolId);
-  if (cap?.hooksDestination !== "project" || cap.projectHooksRelativePath === null) {
-    return { existing: null };
-  }
-  const hooksPath = join(projectRoot, cap.projectHooksRelativePath);
+  const delivery = projectHooksDeliveryOf(toolId);
+  if (delivery === null) return { existing: null };
+  const { format, toolName } = delivery;
+  const hooksPath = join(projectRoot, delivery.relativePath);
   await assertProjectPathWithinRoot(fs, projectRoot, hooksPath);
   const existing = await readExistingJson(fs, hooksPath);
-  const scriptDir = join(projectRoot, cursorProjectHooksScriptDir(pluginName));
+  if (existing !== null) assertParsableJson(existing, delivery.relativePath);
+  const scriptDir = join(projectRoot, format.scriptDir(pluginName));
   await assertProjectPathWithinRoot(fs, projectRoot, scriptDir);
   const scriptsPresent = (await fs.fileExists(scriptDir)) ? await fs.listDirectory(scriptDir) : [];
-  const currentEntries = existing === null ? [] : contributedEntries(existing, pluginName);
+  const currentEntries = existing === null ? [] : format.contributedEntries(existing, pluginName);
   if (provenance === undefined) {
     if (currentEntries.length > 0 || scriptsPresent.length > 0) {
       throw new Error(
-        `Cursor project hooks for '${pluginName}' have an unproven legacy install digest; detach refused.`
+        `${toolName} project hooks for '${pluginName}' have an unproven legacy install digest; detach refused.`
       );
     }
     return { existing };
@@ -54,22 +52,22 @@ export async function assertProjectHooksUnchanged(
     recorded.sort().join("\n") !== current.sort().join("\n")
   ) {
     throw new Error(
-      `Cursor project hooks for '${pluginName}' were edited after install; detach refused.`
+      `${toolName} project hooks for '${pluginName}' were edited after install; detach refused.`
     );
   }
   for (const [relativePath, digest] of provenance.scripts) {
-    assertScriptPath(pluginName, relativePath);
+    assertScriptPath(format, toolName, pluginName, relativePath);
     const path = join(projectRoot, relativePath);
     await assertProjectPathWithinRoot(fs, projectRoot, path);
     if (!(await fs.fileExists(path))) continue;
     if (!/^[0-9a-f]{32}$/.test(digest)) {
       throw new Error(
-        `Cursor hook script '${relativePath}' has an unproven install digest; detach refused.`
+        `${toolName} hook script '${relativePath}' has an unproven install digest; detach refused.`
       );
     }
     if ((await fs.readFileHash(path)).value !== digest) {
       throw new Error(
-        `Cursor hook script '${relativePath}' was edited after install; detach refused.`
+        `${toolName} hook script '${relativePath}' was edited after install; detach refused.`
       );
     }
   }
@@ -93,8 +91,9 @@ export async function removeRecordedProjectHooks(
   toolId: AiToolId,
   projectRoot: string
 ): Promise<boolean> {
-  const cap = resolvePluginsCapability(toolId);
-  if (cap?.hooksDestination !== "project" || cap.projectHooksRelativePath === null) return false;
+  const delivery = projectHooksDeliveryOf(toolId);
+  if (delivery === null) return false;
+  const { format } = delivery;
   const { existing } = await assertProjectHooksUnchanged(
     fs,
     pluginName,
@@ -102,12 +101,13 @@ export async function removeRecordedProjectHooks(
     toolId,
     projectRoot
   );
-  const hooksPath = join(projectRoot, cap.projectHooksRelativePath);
-  const hasEntries = existing !== null && contributedEntries(existing, pluginName).length > 0;
+  const hooksPath = join(projectRoot, delivery.relativePath);
+  const hasEntries =
+    existing !== null && format.contributedEntries(existing, pluginName).length > 0;
   if (hasEntries && existing !== null) {
     await assertProjectPathWithinRoot(fs, projectRoot, hooksPath);
-    const unmerged = unmergeCursorProjectHooksJson(existing, pluginName);
-    if (isHooksFileEmpty(unmerged)) await fs.deleteFile(hooksPath);
+    const unmerged = format.unmerge(existing, pluginName);
+    if (format.isEmpty(unmerged)) await fs.deleteFile(hooksPath);
     else await fs.writeFile(hooksPath, unmerged);
   }
   let removedScript = false;
@@ -131,37 +131,41 @@ export async function removeProjectHooks(
   return removeRecordedProjectHooks(fs, plugin.name, plugin.projectHooks, toolId, projectRoot);
 }
 
-function contributedEntries(
-  content: string,
-  pluginName: string
-): readonly { event: string; entry: HookEntry }[] {
-  const parsed = JSON.parse(content) as { hooks?: Record<string, HookEntry[]> };
-  const marker = cursorProjectHooksScriptDir(pluginName);
-  return Object.entries(parsed.hooks ?? {}).flatMap(([event, entries]) =>
-    entries
-      .filter((entry) => typeof entry.command === "string" && entry.command.includes(marker))
-      .map((entry) => ({ event, entry }))
-  );
-}
-
 /** Hash of one merged hook entry, independent of other plugins' entries. */
-export function digestEntry(entry: HookEntry): string {
+export function digestEntry(entry: ProjectHookEntry): string {
   return createHash("md5").update(JSON.stringify(entry), "utf-8").digest("hex");
 }
 
 export function recordedProjectHookEntries(
+  format: ProjectHooksFormat,
   content: string,
   pluginName: string
 ): ProjectHooksProvenance["entries"] {
-  return contributedEntries(content, pluginName).map(({ event, entry }) => ({
+  return format.contributedEntries(content, pluginName).map(({ event, entry }) => ({
     event,
     command: entry.command,
     digest: digestEntry(entry),
   }));
 }
 
-function assertScriptPath(pluginName: string, relativePath: string): void {
-  const prefix = cursorProjectHooksScriptDir(pluginName);
+/** Merging into a file AIDD cannot parse would mean guessing what it holds. */
+function assertParsableJson(content: string, relativePath: string): void {
+  try {
+    JSON.parse(content);
+  } catch (err) {
+    throw new Error(
+      `${relativePath} is not valid JSON (${(err as Error).message}); left untouched.`
+    );
+  }
+}
+
+function assertScriptPath(
+  format: ProjectHooksFormat,
+  toolName: string,
+  pluginName: string,
+  relativePath: string
+): void {
+  const prefix = format.scriptDir(pluginName);
   if (
     !relativePath.startsWith(prefix) ||
     posix.isAbsolute(relativePath) ||
@@ -169,7 +173,7 @@ function assertScriptPath(pluginName: string, relativePath: string): void {
     posix.normalize(relativePath) !== relativePath
   ) {
     throw new Error(
-      `Cursor hook script path '${relativePath}' has unproven provenance; detach refused.`
+      `${toolName} hook script path '${relativePath}' has unproven provenance; detach refused.`
     );
   }
 }
@@ -182,8 +186,3 @@ async function readExistingJson(fs: FileReader, path: string): Promise<string |
     throw err;
   }
 }
-
-function isHooksFileEmpty(hooksJson: string): boolean {
-  const parsed = JSON.parse(hooksJson) as { hooks?: Record<string, unknown> };
-  return Object.keys(parsed.hooks ?? {}).length === 0;
-}
diff --git a/cli/src/contexts/tools/domain/build-contract.ts b/cli/src/contexts/tools/domain/build-contract.ts
index 799c6c337..fd4dc5627 100644
--- a/cli/src/contexts/tools/domain/build-contract.ts
+++ b/cli/src/contexts/tools/domain/build-contract.ts
@@ -40,7 +40,8 @@ export type ArtifactContract =
        * per plugin (codex flat, claude settings). Warnings are surfaced to the user. */
       readonly hooksMerge?: (
         existing: string | null,
-        incoming: string
+        incoming: string,
+        pluginName: string
       ) => { content: string; warnings: readonly string[] };
       /** Absolute path to the shared hooks merge target; only for hooksMerge contracts. */
       readonly hooksMergeDest?: (outDir: string) => string;
diff --git a/cli/src/contexts/tools/domain/capabilities/plugins-capability.ts b/cli/src/contexts/tools/domain/capabilities/plugins-capability.ts
index 2c66b53b0..fca8e6e6b 100644
--- a/cli/src/contexts/tools/domain/capabilities/plugins-capability.ts
+++ b/cli/src/contexts/tools/domain/capabilities/plugins-capability.ts
@@ -1,5 +1,6 @@
 import { CapabilityConfigError } from "../../../../kernel/errors.js";
 import type { FlatHooksLoaderEntry } from "../../../../kernel/materialization/flat-paths.js";
+import type { ProjectHooksFormat } from "../formats/project-hooks-format.js";
 import type { HooksContentFormat } from "../hooks-format.js";
 import type { MarketplaceSettings } from "../marketplace-settings.js";
 import type { PluginTranslationMode } from "../plugin-translation-mode.js";
@@ -63,7 +64,14 @@ export interface NativeActivation {
 /** One variable, as the caller reads it: a profile is a declaration and reaches no global. */
 export type EnvironmentReader = (name: string) => string | undefined;
 
-export interface NativePluginsParams {
+/** A hook lands in the plugin's own dir, or merged into the project hooks file measured to fire. */
+export interface ProjectHooksDelivery {
+  hooksDestination?: "plugin" | "project";
+  projectHooksRelativePath?: string;
+  projectHooksFormat?: ProjectHooksFormat;
+}
+
+export interface NativePluginsParams extends ProjectHooksDelivery {
   mode: "native";
   pluginsDir: string;
   /** Set to `null` to suppress writing a plugin manifest file into the plugin directory. */
@@ -71,13 +79,6 @@ export interface NativePluginsParams {
   mcpRelativePath?: string;
   hooksRelativePath?: string;
   hooksContentFormat?: HooksContentFormat;
-  /** Where a delivered hook actually lands: under this capability's own plugin directory
-   * (default), or merged into the project's own hooks file — the destination measured to
-   * actually fire. Declared per capability, never guessed per tool. */
-  hooksDestination?: "plugin" | "project";
-  /** Where the project-scope hooks file merges into, relative to the project root. Required
-   * exactly when `hooksDestination` is `"project"` — nothing reads it otherwise. */
-  projectHooksRelativePath?: string;
   acceptsMcp?: boolean;
   /** The variable this tool expands to the installed plugin's directory, as written in a
    * hook or MCP command. Absent means nothing is substituted. */
@@ -113,7 +114,7 @@ export interface FlatHooksBridge {
 }
 
 export type FlatHooksSupport =
-  | {
+  | ({
       acceptsHooks: true;
       flatHooksDir: string;
       /**
@@ -124,7 +125,7 @@ export type FlatHooksSupport =
       /** See {@link FlatHooksBridge}. Omit when this loader triggers a plugin's hooks some
        * other way. */
       flatHooksBridge?: FlatHooksBridge;
-    }
+    } & ProjectHooksDelivery)
   | { acceptsHooks: false; hooksUnsupportedReason: string };
 
 /** Flat skills go under `skills/<plugin>/`, or `skills/<plugin>-<skill>/` for a shallow-scan tool. */
@@ -177,6 +178,7 @@ export class PluginsCapability {
   readonly hooksDestination: "plugin" | "project";
   /** Relative to the project root, or `null` when `hooksDestination` is `"plugin"`. */
   readonly projectHooksRelativePath: string | null;
+  readonly projectHooksFormat: ProjectHooksFormat | null;
   /** Where a flat-mode hook lands, relative to the project root, or `null` when this
    * capability accepts no hooks. */
   readonly flatHooksDir: string | null;
@@ -197,6 +199,7 @@ export class PluginsCapability {
     this.translationMode = PluginsCapability.resolveTranslationMode(params);
     this.installScope = PluginsCapability.resolveInstallScope(params);
     PluginsCapability.validateUserScope(params);
+    PluginsCapability.validateProjectHooks(params);
     if (params.mode === "native") {
       this.pluginsDir = params.pluginsDir;
       this.pluginManifestRelativePath = params.pluginManifestRelativePath;
@@ -211,6 +214,7 @@ export class PluginsCapability {
       this.hooksContentFormat = params.hooksContentFormat ?? DEFAULT_HOOKS_FORMAT;
       this.hooksDestination = params.hooksDestination ?? "plugin";
       this.projectHooksRelativePath = params.projectHooksRelativePath ?? null;
+      this.projectHooksFormat = params.projectHooksFormat ?? null;
       this.flatHooksDir = null;
       this.flatHooksLoaderEntry = null;
       this.flatHooksBridge = null;
@@ -236,8 +240,13 @@ export class PluginsCapability {
       this.mcpRelativePath = DEFAULT_MCP_PATH;
       this.hooksRelativePath = DEFAULT_HOOKS_PATH;
       this.hooksContentFormat = DEFAULT_HOOKS_FORMAT;
-      this.hooksDestination = "plugin";
-      this.projectHooksRelativePath = null;
+      this.hooksDestination = params.acceptsHooks
+        ? (params.hooksDestination ?? "plugin")
+        : "plugin";
+      this.projectHooksRelativePath = params.acceptsHooks
+        ? (params.projectHooksRelativePath ?? null)
+        : null;
+      this.projectHooksFormat = params.acceptsHooks ? (params.projectHooksFormat ?? null) : null;
       this.marketplaceSettings = null;
       this.nativeActivation = null;
       this._userPluginsDir = undefined;
@@ -259,6 +268,7 @@ export class PluginsCapability {
       this.hooksContentFormat = DEFAULT_HOOKS_FORMAT;
       this.hooksDestination = "plugin";
       this.projectHooksRelativePath = null;
+      this.projectHooksFormat = null;
       this.marketplaceSettings = null;
       this.nativeActivation = null;
       this._userPluginsDir = undefined;
@@ -302,10 +312,18 @@ export class PluginsCapability {
         "installScope 'user' requires a userPluginsDir resolver function."
       );
     }
-    if (params.hooksDestination === "project" && params.projectHooksRelativePath === undefined) {
+  }
+
+  private static validateProjectHooks(params: PluginsParams): void {
+    if (params.mode === "unsupported" || !params.acceptsHooks) return;
+    if (params.hooksDestination !== "project") return;
+    if (params.projectHooksRelativePath === undefined) {
       throw new CapabilityConfigError(
         "hooksDestination 'project' requires a projectHooksRelativePath."
       );
     }
+    if (params.projectHooksFormat === undefined) {
+      throw new CapabilityConfigError("hooksDestination 'project' requires a projectHooksFormat.");
+    }
   }
 }
diff --git a/cli/src/contexts/tools/domain/formats/cursor-hooks-project-merge.ts b/cli/src/contexts/tools/domain/formats/cursor-hooks-project-merge.ts
index a63ca8a64..ed7c8ed25 100644
--- a/cli/src/contexts/tools/domain/formats/cursor-hooks-project-merge.ts
+++ b/cli/src/contexts/tools/domain/formats/cursor-hooks-project-merge.ts
@@ -8,6 +8,7 @@
 import { rewriteClaudeRootInJson } from "../../../../kernel/materialization/claude-root-path-rewrite.js";
 import { genericFlatHooksScriptPath } from "../../../../kernel/materialization/flat-paths.js";
 import { mergeCursorFlatHooks } from "./flat-hooks-merge.js";
+import type { ProjectHookEntry, ProjectHooksFormat } from "./project-hooks-format.js";
 
 const HOOKS_PREFIX = "hooks/";
 const CURSOR_HOOKS_DIR = ".cursor/hooks/";
@@ -61,6 +62,26 @@ export function cursorProjectHooksScriptDir(pluginName: string): string {
   return `${CURSOR_HOOKS_DIR}${pluginName}/`;
 }
 
+export const cursorProjectHooksFormat: ProjectHooksFormat = {
+  merge: mergeCursorProjectHooksJson,
+  unmerge: unmergeCursorProjectHooksJson,
+  contributedEntries: (content, pluginName) => {
+    const parsed = JSON.parse(content) as { hooks?: Record<string, ProjectHookEntry[]> };
+    const marker = cursorProjectHooksScriptDir(pluginName);
+    return Object.entries(parsed.hooks ?? {}).flatMap(([event, entries]) =>
+      entries
+        .filter((entry) => typeof entry.command === "string" && entry.command.includes(marker))
+        .map((entry) => ({ event, entry }))
+    );
+  },
+  isEmpty: (content) => {
+    const parsed = JSON.parse(content) as { hooks?: Record<string, unknown> };
+    return Object.keys(parsed.hooks ?? {}).length === 0;
+  },
+  scriptPath: cursorProjectHooksScriptPath,
+  scriptDir: cursorProjectHooksScriptDir,
+};
+
 function stripPluginEntries(existingJson: string, pluginName: string): CursorHooksFile {
   const parsed = JSON.parse(existingJson) as CursorHooksFile;
   const marker = cursorProjectHooksScriptDir(pluginName);
diff --git a/cli/src/contexts/tools/domain/formats/project-hooks-format.ts b/cli/src/contexts/tools/domain/formats/project-hooks-format.ts
new file mode 100644
index 000000000..695638a21
--- /dev/null
+++ b/cli/src/contexts/tools/domain/formats/project-hooks-format.ts
@@ -0,0 +1,17 @@
+export type ProjectHookEntry = { command: string; [key: string]: unknown };
+
+export interface ProjectHooksFormat {
+  merge(
+    existingJson: string | null,
+    pluginHooksJson: string,
+    pluginName: string
+  ): { content: string; warnings: readonly string[] };
+  unmerge(existingJson: string, pluginName: string): string;
+  contributedEntries(
+    content: string,
+    pluginName: string
+  ): readonly { event: string; entry: ProjectHookEntry }[];
+  isEmpty(content: string): boolean;
+  scriptPath(pluginName: string, hooksRelativePath: string): string;
+  scriptDir(pluginName: string): string;
+}
diff --git a/cli/src/contexts/tools/domain/profiles/antigravity/antigravity-hooks.ts b/cli/src/contexts/tools/domain/profiles/antigravity/antigravity-hooks.ts
new file mode 100644
index 000000000..3e999a076
--- /dev/null
+++ b/cli/src/contexts/tools/domain/profiles/antigravity/antigravity-hooks.ts
@@ -0,0 +1,77 @@
+import { rewriteClaudeRootInJson } from "../../../../../kernel/materialization/claude-root-path-rewrite.js";
+import { genericFlatHooksScriptPath } from "../../../../../kernel/materialization/flat-paths.js";
+import type { ProjectHookEntry, ProjectHooksFormat } from "../../formats/project-hooks-format.js";
+import { ANTIGRAVITY_HOOKS_DIR } from "./antigravity-paths.js";
+
+const HOOKS_PREFIX = "hooks/";
+// Claude and `agy` name their tools differently, so only the tool-free event is carried over.
+const MAPPED_EVENTS = new Set(["SessionStart"]);
+// agy 1.2.17 runs a workspace hook through a shell from `<repo>/.agents`, and rejects nested groups.
+const FROM_REPO_ROOT = "cd .. && ";
+
+type NamedHooks = Record<string, Record<string, ProjectHookEntry[]>>;
+type ClaudeHooks = { hooks?: Record<string, { hooks?: ProjectHookEntry[] }[]> };
+
+function scriptPath(pluginName: string, hooksRelativePath: string): string {
+  const rest = hooksRelativePath.startsWith(HOOKS_PREFIX)
+    ? hooksRelativePath.slice(HOOKS_PREFIX.length)
+    : hooksRelativePath;
+  return genericFlatHooksScriptPath(ANTIGRAVITY_HOOKS_DIR, pluginName, rest);
+}
+
+function toHandler(hook: ProjectHookEntry): ProjectHookEntry {
+  const handler: ProjectHookEntry = {
+    type: "command",
+    command: `${FROM_REPO_ROOT}${hook.command}`,
+  };
+  if (hook.timeout !== undefined) handler.timeout = hook.timeout;
+  return handler;
+}
+
+function convert(
+  pluginHooksJson: string,
+  pluginName: string
+): { events: Record<string, ProjectHookEntry[]>; warnings: string[] } {
+  const parsed = JSON.parse(pluginHooksJson) as unknown;
+  const rewritten = rewriteClaudeRootInJson(parsed, (suffix) =>
+    suffix.startsWith(HOOKS_PREFIX) ? `./${scriptPath(pluginName, suffix)}` : suffix
+  ) as ClaudeHooks;
+  const events: Record<string, ProjectHookEntry[]> = {};
+  const warnings: string[] = [];
+  for (const [event, groups] of Object.entries(rewritten.hooks ?? {})) {
+    if (!MAPPED_EVENTS.has(event)) {
+      warnings.push(`antigravity: unmapped event '${event}' skipped`);
+      continue;
+    }
+    events[event] = groups.flatMap((group) => (group.hooks ?? []).map(toHandler));
+  }
+  return { events, warnings };
+}
+
+function withoutPlugin(existingJson: string, pluginName: string): NamedHooks {
+  const { [pluginName]: _removed, ...kept } = JSON.parse(existingJson) as NamedHooks;
+  return kept;
+}
+
+function serialize(hooks: NamedHooks): string {
+  return `${JSON.stringify(hooks, null, 2)}\n`;
+}
+
+export const antigravityProjectHooksFormat: ProjectHooksFormat = {
+  merge(existingJson, pluginHooksJson, pluginName) {
+    const kept = existingJson === null ? {} : withoutPlugin(existingJson, pluginName);
+    const { events, warnings } = convert(pluginHooksJson, pluginName);
+    const merged = Object.keys(events).length > 0 ? { ...kept, [pluginName]: events } : kept;
+    return { content: serialize(merged), warnings };
+  },
+  unmerge: (existingJson, pluginName) => serialize(withoutPlugin(existingJson, pluginName)),
+  contributedEntries(content, pluginName) {
+    const events = (JSON.parse(content) as NamedHooks)[pluginName] ?? {};
+    return Object.entries(events).flatMap(([event, entries]) =>
+      entries.map((entry) => ({ event, entry }))
+    );
+  },
+  isEmpty: (content) => Object.keys(JSON.parse(content) as NamedHooks).length === 0,
+  scriptPath,
+  scriptDir: (pluginName) => `${ANTIGRAVITY_HOOKS_DIR}${pluginName}/`,
+};
diff --git a/cli/src/contexts/tools/domain/profiles/antigravity/antigravity-paths.ts b/cli/src/contexts/tools/domain/profiles/antigravity/antigravity-paths.ts
index e2d651fdc..c08c65d50 100644
--- a/cli/src/contexts/tools/domain/profiles/antigravity/antigravity-paths.ts
+++ b/cli/src/contexts/tools/domain/profiles/antigravity/antigravity-paths.ts
@@ -3,3 +3,5 @@
 
 export const ANTIGRAVITY_DIRECTORY = ".agents/";
 export const ANTIGRAVITY_SKILLS_DIR = `${ANTIGRAVITY_DIRECTORY}skills/`;
+export const ANTIGRAVITY_HOOKS_DIR = `${ANTIGRAVITY_DIRECTORY}hooks/`;
+export const ANTIGRAVITY_HOOKS_FILE = `${ANTIGRAVITY_DIRECTORY}hooks.json`;
diff --git a/cli/src/contexts/tools/domain/profiles/antigravity/build.ts b/cli/src/contexts/tools/domain/profiles/antigravity/build.ts
index 8dabe531e..f064689a2 100644
--- a/cli/src/contexts/tools/domain/profiles/antigravity/build.ts
+++ b/cli/src/contexts/tools/domain/profiles/antigravity/build.ts
@@ -1,9 +1,10 @@
-/** Antigravity's project distribution is flat and carries skills only. A skill sits one level
+/** Antigravity's project distribution is flat and carries skills and hooks. A skill sits one level
  * under `.agents/skills/`, since `agy` expands none nested deeper. */
 
 import { genericFlatSkillPath } from "../../../../../kernel/materialization/flat-paths.js";
 import type { ToolBuildContract } from "../../build-contract.js";
-import { ANTIGRAVITY_SKILLS_DIR } from "./antigravity-paths.js";
+import { antigravityProjectHooksFormat } from "./antigravity-hooks.js";
+import { ANTIGRAVITY_HOOKS_FILE, ANTIGRAVITY_SKILLS_DIR } from "./antigravity-paths.js";
 
 function antigravityFlatSkillPath(plugin: string, rel: string): string {
   return genericFlatSkillPath(ANTIGRAVITY_SKILLS_DIR, plugin, rel.replace(/^skills\//, ""));
@@ -23,7 +24,13 @@ export function buildAntigravityFlatContract(): ToolBuildContract {
       },
       agents: { supported: false },
       mcp: { supported: false },
-      hooks: { supported: false },
+      hooks: {
+        supported: true,
+        source: { kind: "hooksBundle", jsonPath: "hooks/hooks.json", scriptDir: "hooks" },
+        path: antigravityProjectHooksFormat.scriptPath,
+        hooksMerge: antigravityProjectHooksFormat.merge,
+        hooksMergeDest: (outDir) => `${outDir}/${ANTIGRAVITY_HOOKS_FILE}`,
+      },
       rules: { supported: false },
       commands: { supported: false },
     },
diff --git a/cli/src/contexts/tools/domain/profiles/antigravity/profile.ts b/cli/src/contexts/tools/domain/profiles/antigravity/profile.ts
index 858c6055d..38ddc10da 100644
--- a/cli/src/contexts/tools/domain/profiles/antigravity/profile.ts
+++ b/cli/src/contexts/tools/domain/profiles/antigravity/profile.ts
@@ -2,7 +2,12 @@ import { PluginsCapability } from "../../capabilities/plugins-capability.js";
 import { SkillsCapability } from "../../capabilities/skills-capability.js";
 import type { AiTool, HasPlugins, HasSkills } from "../../contracts.js";
 import { registerTool } from "../../registry.js";
-import { ANTIGRAVITY_DIRECTORY } from "./antigravity-paths.js";
+import { antigravityProjectHooksFormat } from "./antigravity-hooks.js";
+import {
+  ANTIGRAVITY_DIRECTORY,
+  ANTIGRAVITY_HOOKS_DIR,
+  ANTIGRAVITY_HOOKS_FILE,
+} from "./antigravity-paths.js";
 import { buildAntigravityFlatContract } from "./build.js";
 
 const TOOL_SUFFIX = ".antigravity.md";
@@ -43,9 +48,11 @@ export const antigravity: AiTool<HasSkills & HasPlugins> = {
       mode: "flat",
       flatNamespacePrefix: "aidd-",
       flatSkillLayout: "single-level",
-      acceptsHooks: false,
-      hooksUnsupportedReason:
-        "Antigravity CLI hooks are not wired yet (follow-up phase 3 of #511: .agents/hooks.json).",
+      acceptsHooks: true,
+      flatHooksDir: ANTIGRAVITY_HOOKS_DIR,
+      hooksDestination: "project",
+      projectHooksRelativePath: ANTIGRAVITY_HOOKS_FILE,
+      projectHooksFormat: antigravityProjectHooksFormat,
     }),
   },
 
diff --git a/cli/src/contexts/tools/domain/profiles/cursor/profile.ts b/cli/src/contexts/tools/domain/profiles/cursor/profile.ts
index cb2854479..b41847c00 100644
--- a/cli/src/contexts/tools/domain/profiles/cursor/profile.ts
+++ b/cli/src/contexts/tools/domain/profiles/cursor/profile.ts
@@ -20,6 +20,7 @@ import {
   convertCommandFrontmatter,
   stripToolSuffix,
 } from "../../formats/command.js";
+import { cursorProjectHooksFormat } from "../../formats/cursor-hooks-project-merge.js";
 import { CURSOR_PLUGIN_ROOT_TOKEN } from "../../formats/plugin-root-token.js";
 import { registerTool } from "../../registry.js";
 import { buildCursorContract, buildCursorFlatContract } from "./build.js";
@@ -119,6 +120,7 @@ export const cursor: AiTool<HasAgents & HasSkills & HasCommands & HasRules & Has
         hooksContentFormat: "flat",
         hooksDestination: "project",
         projectHooksRelativePath: ".cursor/hooks.json",
+        projectHooksFormat: cursorProjectHooksFormat,
         acceptsMcp: true,
         mcpRelativePath: "mcp.json",
         installScope: "user",
diff --git a/cli/src/contexts/tools/domain/registry.ts b/cli/src/contexts/tools/domain/registry.ts
index 75cfa0968..d26283862 100644
--- a/cli/src/contexts/tools/domain/registry.ts
+++ b/cli/src/contexts/tools/domain/registry.ts
@@ -20,6 +20,7 @@ import type {
   PluginsCapability,
 } from "./capabilities/plugins-capability.js";
 import type { AiTool, IdeToolConfig } from "./contracts.js";
+import type { ProjectHooksFormat } from "./formats/project-hooks-format.js";
 
 /** Output layout: a marketplace dist versus a flat workspace inject. Declared here, not by
  * translate, because it is read off a tool's own plugins capability — a tool's build mode is
@@ -187,6 +188,22 @@ export function projectHooksFileOf(toolId: ToolId): string | undefined {
   return resolvePluginsCapability(toolId)?.projectHooksRelativePath ?? undefined;
 }
 
+/** The project hooks file a tool merges plugin hooks into, or `null` when it has none. */
+export function projectHooksDeliveryOf(
+  toolId: ToolId
+): { relativePath: string; format: ProjectHooksFormat; toolName: string } | null {
+  const config = getToolConfig(toolId);
+  if (!isAiTool(config)) return null;
+  const cap = resolvePluginsCapability(toolId);
+  if (cap === null || cap.hooksDestination !== "project") return null;
+  if (cap.projectHooksRelativePath === null || cap.projectHooksFormat === null) return null;
+  return {
+    relativePath: cap.projectHooksRelativePath,
+    format: cap.projectHooksFormat,
+    toolName: config.displayName,
+  };
+}
+
 /** A tool's plugin capability, or `null` when it declares none. Here rather than beside one of
  * its callers: it reads nothing but this registry, and its callers span three of them. */
 export function resolvePluginsCapability(toolId: ToolId): PluginsCapability | null {
diff --git a/cli/src/contexts/translate/application/strategies/flat-build-strategy.ts b/cli/src/contexts/translate/application/strategies/flat-build-strategy.ts
index 93c9acc0d..d0bd38e00 100644
--- a/cli/src/contexts/translate/application/strategies/flat-build-strategy.ts
+++ b/cli/src/contexts/translate/application/strategies/flat-build-strategy.ts
@@ -222,7 +222,7 @@ export class FlatBuildStrategy implements BuildOutputStrategy {
     const rewritten = this.rewriteHooksRawPaths(raw, pluginName);
     const destPath = artifact.hooksMergeDest(this.absOut);
     const existing = (await this.fs.fileExists(destPath)) ? await this.fs.readFile(destPath) : null;
-    const { content, warnings } = artifact.hooksMerge(existing, rewritten);
+    const { content, warnings } = artifact.hooksMerge(existing, rewritten, pluginName);
     for (const w of warnings) this.logger?.warn(w);
     await this.fs.writeFile(destPath, content);
     return 1;
diff --git a/cli/tests/architecture/context-boundary.arch.test.ts b/cli/tests/architecture/context-boundary.arch.test.ts
index 6432af088..55b4964fb 100644
--- a/cli/tests/architecture/context-boundary.arch.test.ts
+++ b/cli/tests/architecture/context-boundary.arch.test.ts
@@ -45,6 +45,7 @@ const PUBLIC_MODULES: Readonly<Record<string, readonly string[]>> = {
     // and the diagnostic that answers whether the tool will run them.
     "src/contexts/tools/domain/formats/flat-hooks-merge.ts",
     "src/contexts/tools/domain/formats/cursor-hooks-project-merge.ts",
+    "src/contexts/tools/domain/formats/project-hooks-format.ts",
     // The variable each tool expands to an installed plugin's directory: a tool declares it,
     // translate substitutes it, the diagnostic looks for it in what was installed.
     "src/contexts/tools/domain/formats/plugin-root-token.ts",
diff --git a/cli/tests/contexts/framework/application/framework/translator/project-hooks-materializer.unit.test.ts b/cli/tests/contexts/framework/application/framework/translator/project-hooks-materializer.unit.test.ts
index 7fd864ed5..8d522fbca 100644
--- a/cli/tests/contexts/framework/application/framework/translator/project-hooks-materializer.unit.test.ts
+++ b/cli/tests/contexts/framework/application/framework/translator/project-hooks-materializer.unit.test.ts
@@ -1,3 +1,4 @@
+import "../../../../../../src/contexts/tools/domain/profiles/antigravity/profile.js";
 import "../../../../../../src/contexts/tools/domain/profiles/cursor/profile.js";
 import { join } from "node:path";
 import { describe, expect, it, vi } from "vitest";
@@ -5,6 +6,7 @@ import {
   ProjectHooksMaterializer,
   withoutHooks,
 } from "../../../../../../src/contexts/framework/application/framework/translator/project-hooks-materializer.js";
+import { removeRecordedProjectHooks } from "../../../../../../src/contexts/framework/application/shared/remove-project-hooks.js";
 import {
   type PluginComponentFile,
   PluginDistribution,
@@ -229,6 +231,79 @@ describe("ProjectHooksMaterializer", () => {
   });
 });
 
+describe("ProjectHooksMaterializer for a flat tool merging into .agents/hooks.json", () => {
+  const AGENTS_HOOKS = join(PROJECT_ROOT, ".agents", "hooks.json");
+  const USER_HOOKS = `${JSON.stringify({ lint: { Stop: [{ command: "./lint.sh" }] } }, null, 2)}\n`;
+
+  it("adds the plugin's key beside the user's, rewrites nothing on a second run, and removes only its own on clean", async () => {
+    const fs = new InMemoryFileAdapter();
+    fs.setFile(AGENTS_HOOKS, USER_HOOKS);
+    const materializer = new ProjectHooksMaterializer(fs);
+    const dist = distWithHooks([hooksManifest("SessionStart"), SCRIPT]);
+
+    const first = await materializer.materializeWithProvenance(dist, "antigravity", PROJECT_ROOT);
+    const afterFirst = fs.getFile(AGENTS_HOOKS);
+    const second = await materializer.materializeWithProvenance(
+      dist,
+      "antigravity",
+      PROJECT_ROOT,
+      first.projectHooks
+    );
+
+    expect(JSON.parse(afterFirst ?? "")).toEqual({
+      lint: { Stop: [{ command: "./lint.sh" }] },
+      [PLUGIN_NAME]: {
+        SessionStart: [
+          { type: "command", command: `cd .. && node ./.agents/hooks/${PLUGIN_NAME}/pre.js` },
+        ],
+      },
+    });
+    expect(fs.getFile(join(PROJECT_ROOT, ".agents/hooks", PLUGIN_NAME, "pre.js"))).toBe(
+      SCRIPT.content
+    );
+    expect(fs.getFile(AGENTS_HOOKS)).toBe(afterFirst);
+
+    await removeRecordedProjectHooks(
+      fs,
+      PLUGIN_NAME,
+      second.projectHooks,
+      "antigravity",
+      PROJECT_ROOT
+    );
+
+    expect(fs.getFile(AGENTS_HOOKS)).toBe(USER_HOOKS);
+    expect(fs.getFile(join(PROJECT_ROOT, ".agents/hooks", PLUGIN_NAME, "pre.js"))).toBeUndefined();
+  });
+
+  it("deletes the hooks file on clean when nothing but the plugin's key was in it", async () => {
+    const fs = new InMemoryFileAdapter();
+    const materializer = new ProjectHooksMaterializer(fs);
+    const { projectHooks } = await materializer.materializeWithProvenance(
+      distWithHooks([hooksManifest("SessionStart"), SCRIPT]),
+      "antigravity",
+      PROJECT_ROOT
+    );
+
+    await removeRecordedProjectHooks(fs, PLUGIN_NAME, projectHooks, "antigravity", PROJECT_ROOT);
+
+    expect(await fs.fileExists(AGENTS_HOOKS)).toBe(false);
+  });
+
+  it("stops on an unparsable hooks file, naming it and leaving it as found", async () => {
+    const fs = new InMemoryFileAdapter();
+    fs.setFile(AGENTS_HOOKS, "{ not json");
+
+    await expect(
+      new ProjectHooksMaterializer(fs).materializeWithProvenance(
+        distWithHooks([hooksManifest("SessionStart"), SCRIPT]),
+        "antigravity",
+        PROJECT_ROOT
+      )
+    ).rejects.toThrow(/^\.agents\/hooks\.json is not valid JSON/);
+    expect(fs.getFile(AGENTS_HOOKS)).toBe("{ not json");
+  });
+});
+
 describe("withoutHooks", () => {
   it("drops every hooks file from the file list and the hooks component alike", () => {
     const stripped = withoutHooks(distWithHooks([hooksManifest("PreToolUse"), SCRIPT]));
diff --git a/cli/tests/contexts/tools/domain/capabilities/plugins-capability.unit.test.ts b/cli/tests/contexts/tools/domain/capabilities/plugins-capability.unit.test.ts
index 5e8565199..d2400682f 100644
--- a/cli/tests/contexts/tools/domain/capabilities/plugins-capability.unit.test.ts
+++ b/cli/tests/contexts/tools/domain/capabilities/plugins-capability.unit.test.ts
@@ -1,5 +1,6 @@
 import { describe, expect, it } from "vitest";
 import { PluginsCapability } from "../../../../../src/contexts/tools/domain/capabilities/plugins-capability.js";
+import { cursorProjectHooksFormat } from "../../../../../src/contexts/tools/domain/formats/cursor-hooks-project-merge.js";
 
 const MARKETPLACE_SETTINGS = {
   settingsPath: ".claude/settings.json",
@@ -290,6 +291,33 @@ describe("PluginsCapability base directory resolution", () => {
       "hooksDestination 'project' requires a projectHooksRelativePath."
     );
   });
+
+  it("refuses a project hooks destination that declares no file format", () => {
+    expect(
+      () =>
+        new PluginsCapability({
+          ...native,
+          hooksDestination: "project",
+          projectHooksRelativePath: ".x/hooks.json",
+        })
+    ).toThrow("hooksDestination 'project' requires a projectHooksFormat.");
+  });
+
+  it("lets a flat capability merge its hooks into a project hooks file", () => {
+    const cap = new PluginsCapability({
+      mode: "flat",
+      acceptsHooks: true,
+      flatHooksDir: ".x/hooks/",
+      flatNamespacePrefix: "aidd-",
+      hooksDestination: "project",
+      projectHooksRelativePath: ".x/hooks.json",
+      projectHooksFormat: cursorProjectHooksFormat,
+    });
+
+    expect(cap.hooksDestination).toBe("project");
+    expect(cap.projectHooksRelativePath).toBe(".x/hooks.json");
+    expect(cap.projectHooksFormat).toBe(cursorProjectHooksFormat);
+  });
 });
 
 describe("PluginsCapability defaults each mode falls back to", () => {
diff --git a/cli/tests/contexts/tools/domain/profiles/antigravity/antigravity-hooks.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/antigravity/antigravity-hooks.unit.test.ts
new file mode 100644
index 000000000..291d63b76
--- /dev/null
+++ b/cli/tests/contexts/tools/domain/profiles/antigravity/antigravity-hooks.unit.test.ts
@@ -0,0 +1,137 @@
+import { describe, expect, it } from "vitest";
+import { antigravityProjectHooksFormat as format } from "../../../../../../src/contexts/tools/domain/profiles/antigravity/antigravity-hooks.js";
+
+// biome-ignore lint/suspicious/noTemplateCurlyInString: intentionally testing Claude hook placeholder substitution
+const PLUGIN_ROOT_VAR = "${CLAUDE_PLUGIN_ROOT}";
+
+const MEMORY_HOOKS = JSON.stringify({
+  hooks: {
+    SessionStart: [
+      { hooks: [{ type: "command", command: `node ${PLUGIN_ROOT_VAR}/hooks/update_memory.js` }] },
+    ],
+  },
+});
+
+const USER_HOOKS = `${JSON.stringify(
+  { lint: { PostToolUse: [{ matcher: "run_command", hooks: [{ command: "./lint.sh" }] }] } },
+  null,
+  2
+)}\n`;
+
+function parse(content: string): Record<string, Record<string, unknown[]>> {
+  return JSON.parse(content) as Record<string, Record<string, unknown[]>>;
+}
+
+describe("antigravityProjectHooksFormat", () => {
+  describe("merge", () => {
+    it("writes one key named after the plugin, its handlers directly under SessionStart, run from the repo root", () => {
+      const { content, warnings } = format.merge(null, MEMORY_HOOKS, "aidd-context");
+
+      expect(parse(content)).toEqual({
+        "aidd-context": {
+          SessionStart: [
+            {
+              type: "command",
+              command: "cd .. && node ./.agents/hooks/aidd-context/update_memory.js",
+            },
+          ],
+        },
+      });
+      expect(warnings).toEqual([]);
+    });
+
+    it("keeps a hook the user declared under another name", () => {
+      const { content } = format.merge(USER_HOOKS, MEMORY_HOOKS, "aidd-context");
+
+      expect(parse(content).lint).toEqual(parse(USER_HOOKS).lint);
+      expect(Object.keys(parse(content))).toEqual(["lint", "aidd-context"]);
+    });
+
+    it("changes nothing when the same plugin is merged twice", () => {
+      const { content: first } = format.merge(USER_HOOKS, MEMORY_HOOKS, "aidd-context");
+      const { content: second } = format.merge(first, MEMORY_HOOKS, "aidd-context");
+
+      expect(second).toBe(first);
+    });
+
+    it("refuses a file it cannot parse rather than overwriting it", () => {
+      expect(() => format.merge("{ not json", MEMORY_HOOKS, "aidd-context")).toThrow();
+    });
+
+    it("keeps a timeout the plugin declared", () => {
+      const withTimeout = MEMORY_HOOKS.replace(
+        '"type":"command",',
+        '"type":"command","timeout":10,'
+      );
+
+      const { content } = format.merge(null, withTimeout, "aidd-context");
+
+      expect(parse(content)["aidd-context"].SessionStart).toEqual([
+        expect.objectContaining({ timeout: 10 }),
+      ]);
+    });
+
+    it("skips an event other than SessionStart with a warning naming it", () => {
+      const telemetry = JSON.stringify({
+        hooks: {
+          SessionStart: [{ hooks: [{ type: "command", command: "node x.cjs start" }] }],
+          PostToolUse: [{ hooks: [{ type: "command", command: "node x.cjs tool" }] }],
+        },
+      });
+
+      const { content, warnings } = format.merge(null, telemetry, "aidd-telemetry");
+
+      expect(Object.keys(parse(content)["aidd-telemetry"])).toEqual(["SessionStart"]);
+      expect(warnings).toEqual(["antigravity: unmapped event 'PostToolUse' skipped"]);
+    });
+
+    it("adds no key for a plugin with no event it maps", () => {
+      const onlyStop = JSON.stringify({
+        hooks: { Stop: [{ hooks: [{ type: "command", command: "node x.cjs" }] }] },
+      });
+
+      const { content } = format.merge(USER_HOOKS, onlyStop, "aidd-telemetry");
+
+      expect(Object.keys(parse(content))).toEqual(["lint"]);
+    });
+  });
+
+  describe("unmerge", () => {
+    it("removes the plugin's key and leaves the user's untouched", () => {
+      const { content } = format.merge(USER_HOOKS, MEMORY_HOOKS, "aidd-context");
+
+      expect(format.unmerge(content, "aidd-context")).toBe(USER_HOOKS);
+    });
+  });
+
+  describe("contributedEntries", () => {
+    it("lists the plugin's handlers with their event, and nothing of the user's", () => {
+      const { content } = format.merge(USER_HOOKS, MEMORY_HOOKS, "aidd-context");
+
+      expect(format.contributedEntries(content, "aidd-context")).toEqual([
+        {
+          event: "SessionStart",
+          entry: {
+            type: "command",
+            command: "cd .. && node ./.agents/hooks/aidd-context/update_memory.js",
+          },
+        },
+      ]);
+      expect(format.contributedEntries(USER_HOOKS, "aidd-context")).toEqual([]);
+    });
+  });
+
+  describe("isEmpty", () => {
+    it("is true only once no named hook is left", () => {
+      expect(format.isEmpty("{}\n")).toBe(true);
+      expect(format.isEmpty(USER_HOOKS)).toBe(false);
+    });
+  });
+
+  it("puts a plugin's scripts under its own directory in .agents/hooks/", () => {
+    expect(format.scriptDir("aidd-context")).toBe(".agents/hooks/aidd-context/");
+    expect(format.scriptPath("aidd-context", "hooks/update_memory.js")).toBe(
+      ".agents/hooks/aidd-context/update_memory.js"
+    );
+  });
+});
diff --git a/cli/tests/contexts/tools/domain/profiles/antigravity/build.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/antigravity/build.unit.test.ts
index a62d41abc..4681169d8 100644
--- a/cli/tests/contexts/tools/domain/profiles/antigravity/build.unit.test.ts
+++ b/cli/tests/contexts/tools/domain/profiles/antigravity/build.unit.test.ts
@@ -17,12 +17,39 @@ describe("buildAntigravityFlatContract", () => {
     expect(skills.source).toEqual({ kind: "fullTree", srcDir: "skills" });
   });
 
-  it.each(["agents", "hooks", "mcp", "rules", "commands"] as const)(
-    "declares %s unsupported",
-    (kind) => {
-      expect(buildAntigravityFlatContract().artifacts[kind].supported).toBe(false);
-    }
-  );
+  it("copies hook scripts under .agents/hooks/<plugin>/ and merges their commands into .agents/hooks.json", () => {
+    const hooks = supported(buildAntigravityFlatContract().artifacts.hooks);
+    const incoming = JSON.stringify({
+      hooks: {
+        SessionStart: [
+          {
+            hooks: [
+              { type: "command", command: "node ./.agents/hooks/aidd-context/update_memory.js" },
+            ],
+          },
+        ],
+      },
+    });
+
+    expect(hooks.path("aidd-context", "hooks/update_memory.js")).toBe(
+      ".agents/hooks/aidd-context/update_memory.js"
+    );
+    expect(hooks.hooksMergeDest?.("/out")).toBe("/out/.agents/hooks.json");
+    expect(JSON.parse(hooks.hooksMerge?.(null, incoming, "aidd-context").content ?? "")).toEqual({
+      "aidd-context": {
+        SessionStart: [
+          {
+            type: "command",
+            command: "cd .. && node ./.agents/hooks/aidd-context/update_memory.js",
+          },
+        ],
+      },
+    });
+  });
+
+  it.each(["agents", "mcp", "rules", "commands"] as const)("declares %s unsupported", (kind) => {
+    expect(buildAntigravityFlatContract().artifacts[kind].supported).toBe(false);
+  });
 
   it("writes no manifest, catalog or config artifact", () => {
     const contract = buildAntigravityFlatContract();
diff --git a/cli/tests/contexts/tools/domain/profiles/antigravity/profile.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/antigravity/profile.unit.test.ts
index 15ffb415d..66715547b 100644
--- a/cli/tests/contexts/tools/domain/profiles/antigravity/profile.unit.test.ts
+++ b/cli/tests/contexts/tools/domain/profiles/antigravity/profile.unit.test.ts
@@ -1,4 +1,5 @@
 import { describe, expect, it } from "vitest";
+import { antigravityProjectHooksFormat } from "../../../../../../src/contexts/tools/domain/profiles/antigravity/antigravity-hooks.js";
 import { antigravity } from "../../../../../../src/contexts/tools/domain/profiles/antigravity/profile.js";
 
 describe("antigravity", () => {
@@ -20,14 +21,17 @@ describe("antigravity", () => {
     expect(antigravity.capabilities.skills.accepts(".kilo/skills/x/SKILL.md")).toBe(false);
   });
 
-  it("is a flat host that accepts no hooks until the hooks phase", () => {
+  it("is a flat host merging plugin hooks into .agents/hooks.json, scripts under .agents/hooks/", () => {
     expect(antigravity.capabilities.plugins).toMatchObject({
       mode: "flat",
       flatNamespacePrefix: "aidd-",
       flatSkillLayout: "single-level",
-      acceptsHooks: false,
+      acceptsHooks: true,
+      flatHooksDir: ".agents/hooks/",
+      hooksDestination: "project",
+      projectHooksRelativePath: ".agents/hooks.json",
+      projectHooksFormat: antigravityProjectHooksFormat,
     });
-    expect(antigravity.capabilities.plugins.hooksUnsupportedReason).toContain("phase 3");
     expect(Object.keys(antigravity.capabilities).sort()).toEqual(["plugins", "skills"]);
   });
 
diff --git a/cli/tests/contexts/tools/domain/profiles/claude/build.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/claude/build.unit.test.ts
index 5c82e47bd..805b73324 100644
--- a/cli/tests/contexts/tools/domain/profiles/claude/build.unit.test.ts
+++ b/cli/tests/contexts/tools/domain/profiles/claude/build.unit.test.ts
@@ -235,7 +235,9 @@ describe("buildClaudeFlatContract()", () => {
   it("appends a plugin's hooks to the settings file, leaving every other setting alone", () => {
     const hooks = supported(buildClaudeFlatContract().artifacts.hooks);
 
-    expect(hooks.hooksMerge?.(JSON.stringify({ model: "opus" }), HOOKS_JSON)).toStrictEqual({
+    expect(
+      hooks.hooksMerge?.(JSON.stringify({ model: "opus" }), HOOKS_JSON, "aidd-dev")
+    ).toStrictEqual({
       content: `${JSON.stringify(
         {
           model: "opus",
diff --git a/cli/tests/contexts/tools/domain/profiles/codex/build.unit.test.ts b/cli/tests/contexts/tools/domain/profiles/codex/build.unit.test.ts
index e1966316b..e421f6553 100644
--- a/cli/tests/contexts/tools/domain/profiles/codex/build.unit.test.ts
+++ b/cli/tests/contexts/tools/domain/profiles/codex/build.unit.test.ts
@@ -318,7 +318,7 @@ describe("buildCodexFlatContract()", () => {
     expect({
       script: hooks.path("aidd-dev", "hooks/journal.cjs"),
       mergeDest: hooks.hooksMergeDest?.("/out"),
-      merged: hooks.hooksMerge?.(null, HOOKS_JSON),
+      merged: hooks.hooksMerge?.(null, HOOKS_JSON, "aidd-dev"),
     }).toStrictEqual({
       script: ".codex/hooks/aidd-dev/journal.cjs",
       mergeDest: "/out/.codex/hooks.json",
diff --git a/cli/tests/contexts/tools/domain/registry-conformance.unit.test.ts b/cli/tests/contexts/tools/domain/registry-conformance.unit.test.ts
index 9ac55f719..307e28a0a 100644
--- a/cli/tests/contexts/tools/domain/registry-conformance.unit.test.ts
+++ b/cli/tests/contexts/tools/domain/registry-conformance.unit.test.ts
@@ -386,6 +386,10 @@ describe("projectHooksFileOf()", () => {
     expect(projectHooksFileOf("cursor")).toBe(".cursor/hooks.json");
   });
 
+  it("returns .agents/hooks.json for antigravity", () => {
+    expect(projectHooksFileOf("antigravity")).toBe(".agents/hooks.json");
+  });
+
   it("returns undefined for a tool with nothing merged into a project hooks file", () => {
     expect(projectHooksFileOf("claude")).toBeUndefined();
   });
diff --git a/cli/tests/contexts/tools/domain/registry.unit.test.ts b/cli/tests/contexts/tools/domain/registry.unit.test.ts
index 31c9db3d4..1cae82c2a 100644
--- a/cli/tests/contexts/tools/domain/registry.unit.test.ts
+++ b/cli/tests/contexts/tools/domain/registry.unit.test.ts
@@ -5,6 +5,7 @@ import {
   PluginsCapability,
 } from "../../../../src/contexts/tools/domain/capabilities/plugins-capability.js";
 import type { AiTool } from "../../../../src/contexts/tools/domain/contracts.js";
+import { cursorProjectHooksFormat } from "../../../../src/contexts/tools/domain/formats/cursor-hooks-project-merge.js";
 import {
   getToolConfig,
   hasToolSignals,
@@ -121,6 +122,7 @@ describe("what a tool's plugin capability declares about activation", () => {
           plugins: nativePlugins({
             hooksDestination: "project",
             projectHooksRelativePath: ".cursor/hooks.json",
+            projectHooksFormat: cursorProjectHooksFormat,
           }),
         },
         null
diff --git a/cli/tests/golden/snapshots/framework-build/golden.json b/cli/tests/golden/snapshots/framework-build/golden.json
index 9888b25a7..6ffd2f06f 100644
--- a/cli/tests/golden/snapshots/framework-build/golden.json
+++ b/cli/tests/golden/snapshots/framework-build/golden.json
@@ -1947,6 +1947,7 @@
     ".kilo/agents/aidd-dev-reviewer.md": "30e2dbb93309d23fc99cbce36a4fcfd0b6d76e49c3425979827727327ba697a6"
   },
   "antigravity:flat": {
+    ".agents/hooks.json": "d0e9c0b5770709182a2b8769fbc93a510047d3f6fe85066bb2dc2afb51f4dd51",
     ".agents/skills/aidd-vcs-04-issue-create/SKILL.md": "3983ed1c71124786fdf737ec5447637a31b1cc146eff43003978cec50c2ddc67",
     ".agents/skills/aidd-vcs-04-issue-create/evals/scenarios.json": "d113c62aae4867e425737948c39c9f687f56c3d37234eca345a2f65f1a234c30",
     ".agents/skills/aidd-vcs-04-issue-create/assets/CONTRIBUTING.md": "1372c7512c02c26e21643ae523a98d7c90ff92c03633532a8c417b4ca8d9e75f",
@@ -2128,6 +2129,7 @@
     ".agents/skills/aidd-async-dev-01-setup/actions/skills/02-ask-config.md": "986335d1e86a633d0083fe4488aae58266a82ec35d0cdb0b74f0bbcea70e6f4e",
     ".agents/skills/aidd-async-dev-01-setup/actions/skills/03-generate-workflow.md": "11f7ec6c03284d0524179f71337691301a6362cf77bf3aa666fe41686b4df40b",
     ".agents/skills/aidd-async-dev-01-setup/actions/skills/04-write-config.md": "eb7ecb812e8bdaaeba2e56c71c77bf8c14fce0a2c44311ff7985444617635dd5",
-    ".agents/skills/aidd-async-dev-01-setup/actions/skills/05-bootstrap-labels.md": "f53177ce1c58767f1bdfcfa3e72f7d4cc5e3d4fd782c35c3998815317be108b1"
+    ".agents/skills/aidd-async-dev-01-setup/actions/skills/05-bootstrap-labels.md": "f53177ce1c58767f1bdfcfa3e72f7d4cc5e3d4fd782c35c3998815317be108b1",
+    ".agents/hooks/aidd-context/update_memory.js": "140d7db788452f5f4c32316d522f595a36e06638b19a42d32e42a1a7324b7149"
   }
 }