overlord-cli 0.2607301714.0 → 0.2608011442.0

package/dist/connectors/AGENTS.md

@@ -8,12 +8,12 @@ This file tells agents how to extend the Connectors module to add new agent harn
 
 A connector lets an AI coding harness (Claude Code, Codex, Cursor, etc.) speak the `ovld protocol` and inherit mission context. Extensions in this module fall into four categories:
 
-| Extension type | Example user request |
-| --- | --- |
-| New agent connector | "Add a connector for OpenCode / Windsurf / Zed" |
-| New hook type | "Add a Stop hook for pending-delivery checks" |
-| Extend connector core | "Add a new canonical instruction to all connectors" |
-| New capability flag | "Connectors can now declare `supports-multi-session`" |
+| Extension type        | Example user request                                  |
+| --------------------- | ----------------------------------------------------- |
+| New agent connector   | "Add a connector for OpenCode / Windsurf / Zed"       |
+| New hook type         | "Add a Stop hook for pending-delivery checks"         |
+| Extend connector core | "Add a new canonical instruction to all connectors"   |
+| New capability flag   | "Connectors can now declare `supports-multi-session`" |
 
 Each type has a different procedure below.
 
@@ -29,6 +29,185 @@ Each type has a different procedure below.
 
 ---
 
+## Harness capability descriptors
+
+**Before writing any code for a harness, read
+`connectors/adapters/<agent>/harness-capabilities.yaml`, or run
+`ovld agent-session capabilities <agent>`. It is authoritative and fixture-backed.**
+
+- `unsupported` means the harness cannot do it. **Do not attempt it.** If you believe the cited
+  evidence is now wrong, replace `evidenceRef` and add the executable fixture in the same change
+  that flips the status.
+- `not-implemented` means it is buildable and unbuilt. **This is your work.**
+- `unverified` means find out first. Write the fixture, then flip the status.
+- `supported` without passing fixtures is a CI failure, not a claim.
+
+Two states (`yes`/`no`) would be a trap: an agent reading "no" could not tell whether to give up
+or to start building, and both errors are expensive — one wastes a day on something structurally
+impossible, the other leaves a capability unbuilt for a year because someone assumed it was
+refused.
+
+### What is generated from the descriptor
+
+The descriptor is the **only hand-authored capability source**. Everything below is generated by
+`yarn connectors:capabilities` and must never be hand-edited:
+
+| Artifact                                                                                                                                                    | Purpose                                                                |
+| ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| `connectors/adapters/<agent>/CAPABILITIES.md`                                                                                                               | Per-adapter page with a do-not-edit banner                             |
+| `connectors/HARNESS-MATRIX.md`                                                                                                                              | Cross-adapter matrix                                                   |
+| `cli/src/agent-session/catalog.generated.ts`                                                                                                                | Compiled catalog the CLI runtime reads                                 |
+| The `connector:` block's `capabilities`, `hookTypes`, `integrationShape`, `capabilityTier`, and `harnessCapabilities` fields in `conformance-manifest.yaml` | The deprecated hook-named legacy projection plus the descriptor digest |
+
+`yarn connectors:capabilities:check` is the CI drift check: it validates every descriptor,
+executes every referenced fixture, re-derives each tier, and fails if any generated artifact is
+stale. `yarn connectors:check` runs it alongside the connector version check.
+
+### Rules that keep it honest
+
+1. **A capability is proven by fixture, not by inspection.** CI runs the fixture. Checking only
+   that a named file exists would let an empty fixture claim a capability into existence.
+2. **The tier is derived, never authored.** `capabilityTier` comes from what the fixtures prove.
+   Claimed-but-unproven is worse than absent, because the UI renders controls that do nothing.
+3. **Every adapter ships the unbound-session negative fixture.** An unbound session in an
+   unrelated directory must be untouched and unblocked by every registered integration. A side
+   effect the fixture records must be declared as a hazard with a tracker — recording the truth
+   is required; claiming silence you do not have is not.
+4. **A native session id binds nothing on its own.** It is a correlation alias. The verified
+   channel/session credential is the authorization and mission scope, and the working directory
+   is never a binding authority.
+5. **Adapters make no network call.** Translate, hand off to `ovld agent-session`, return.
+
+### The rendered agent-session hook
+
+Do not write a per-adapter shell script for agent-session traffic. One core script,
+`connectors/core/scripts/agent-session-hook.sh`, is rendered per adapter at `ovld agent-setup`
+time — declare the managed file as `scripts/agent-session-<action>.sh` in the manifest, and the
+installer substitutes both your adapter key and that **fixed action**:
+
+```bash
+[ -n "${OVERLORD_SESSION_CHANNEL_ID:-}" ] || exit 0
+command -v ovld >/dev/null 2>&1 || exit 0
+exec ovld agent-session event --agent claude --payload-file -
+```
+
+The first line is the scope gate, and it is in bash rather than in the CLI on purpose. An
+unbound session — someone's own agent in an unrelated directory on a machine that happens to
+have Overlord installed — must cost no process, no log line, and no measurable delay. A gate
+inside the CLI cannot deliver that, because reaching it already cost a process launch. The CLI
+applies the same gate again, since a check that can be skipped by invoking `ovld` directly is
+not a gate.
+
+The action being fixed at install time is the point, not a simplification. A single script that
+dispatched on `$1` would let whatever wrote the hook registration choose which CLI operation
+runs, and hook registrations are the least-reviewed configuration on a developer's machine. A
+`PostToolUse` registration renders an `event` script; a permission registration renders a
+`request` script; an inject registration renders an `inbox` script; none can become another.
+`event`, `request`, and `inbox` are the only three actions a managed path may name.
+
+The payload streams on stdin — not through a shell variable, which caps size and mangles NUL
+bytes, and not through argv, which is world-readable. For `request` and `inbox`, stdout and exit
+status pass through unchanged so the native decision or injection reaches the harness in its
+exact expected shape.
+
+Silence is the failure mode. A missing `ovld` exits `0` with no output, which for a decision
+hook means _no decision_ and therefore the harness's own prompt. No failure path may ever
+manufacture an approval.
+
+### The event codec
+
+Native event shapes belong to the connector, so they live here as
+`connectors/adapters/<agent>/codec/<agent>.codec.yaml`, referenced from the descriptor's
+`codecSpec` field and compiled by `yarn connectors:capabilities` into
+`cli/src/agent-session/codec-registry.generated.ts`. The CLI executes harness dialects; it is
+never their source of truth.
+
+A codec is a **declaration**, not a function, and that is the whole design:
+
+```yaml
+codecVersion: 1
+adapter: claude
+eventNamePath: hook_event_name # where the native event name lives (omit for a bus transport)
+nativeSessionPaths: [session_id] # correlation alias only, never an authority
+projectRootPaths: [cwd] # used ONLY to relativize file paths
+events:
+  - native: PostToolUse
+    kind: tool.completed # from the closed normalized event vocabulary
+    origin: agent
+    toolPath: tool_name
+    inputPath: tool_input
+    fileEditKind: file.edited # a file-mutating tool becomes this kind instead
+```
+
+A codec can only say **where** native values live. It cannot name a destination the core
+interpreter (`packages/core/service/agent-session/pure/codec.ts`) does not implement, an unknown
+key is a generation error rather than a silently ignored field, and the normalized payload type
+has no index signature to smuggle anything through. So "does this codec forward a raw payload?"
+is a question you answer by looking, not by reading code — which matters on the sixth adapter far
+more than on the first.
+
+What each field feeds:
+
+- `toolPath` is normalized to the **nine-value tool vocabulary**, and the description formatter
+  is keyed by that normalized name in core. Adapters own the mapping; core owns the formatter.
+  `Bash`, `bash`, `Shell`, and `shell_command` are one thing with one card.
+- `inputPath` is never transmitted. It is reduced on the machine into an action, a subject, a
+  bounded detail, and machine-derived risk markers. A tool with no formatter emits its name and
+  the top-level **key names** of its input and nothing else.
+- `promptPath` is the single deliberate exception: prompt text is persisted in full for bound
+  sessions, because the activity feed exists to show it. Secret redaction still runs over it.
+
+Control-plane adapters (Shape C) write the same kind of codec and omit `eventNamePath`, because
+the transport rather than the payload names the event. There is no separate control-plane
+codec format, and that is the evidence the waist is in the right place.
+
+### The decision codec
+
+Callback and extension adapters with fixture-proven `decide.*` capabilities declare
+`codec/<agent>.decision-codec.yaml` and reference it as `decisionCodecSpec`. The declaration
+names native event/request paths and literal allow/deny/defer response bodies; the shared pure
+interpreter owns validation, bounded redacted card construction, and JSON-line emission. Do not
+add an `if (agent === ...)` branch to `cli/src/agent-session/request.ts`.
+
+Every supported callback/extension decision capability must reference a `decision-codec`
+fixture. That fixture executes the shipped interpreter, asserts the complete reduced request
+card, rejects named secret/raw values, and pins exact allow/deny/defer bytes. A
+`native-payload` fixture proves only that upstream fields exist; it cannot prove what the CLI
+emits back to the harness.
+
+### Where the session channel comes from
+
+The credential your adapter's CLI call presents is not something the adapter finds or derives:
+
+| Launch                 | Channel created at                       | Credential reaches the process via                  |
+| ---------------------- | ---------------------------------------- | --------------------------------------------------- |
+| Queued (runner)        | the `launching` transition               | owner-only local cache, keyed by channel id         |
+| Manual (`ovld launch`) | `POST /api/missions/:id/session-channel` | owner-only local cache, keyed by channel id         |
+| Virtual gateway        | the same preparation service             | `OVERLORD_SESSION_CHANNEL_TOKEN` in the environment |
+
+Only `OVERLORD_SESSION_CHANNEL_ID` is exported into the launch environment and the terminal
+launch script. The script lives in `<checkout>/.overlord/tmp`, so nothing secret may enter it —
+a checkout-local secret is one that can be committed, copied into a worktree, or backed up.
+
+`ovld protocol attach` binds the channel to the session and backfills every event published
+before the agent attached. If your adapter learns the harness's session id later, report it with
+`ovld agent-session bind --agent <key> --native-session-id <id>`; it is recorded as an alias and
+grants nothing on its own.
+
+### Fixture kinds
+
+| Kind               | What it does                                                                                                                                                                                                                                                                                                     |
+| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `native-payload`   | Asserts the shape of a recorded native harness payload (pure; no process started)                                                                                                                                                                                                                                |
+| `script-io`        | Runs a shipped adapter script in an isolated sandbox — own `HOME`, `TMPDIR`, cwd, and a `PATH` whose only `ovld` is a recording spy — and asserts exit status, stdout, stderr, every sandbox write, and every CLI invocation attempted                                                                           |
+| `source-guard`     | Asserts a repo file does or does not contain declared markers (how "this dangerous harness flag must stay unset" is enforced)                                                                                                                                                                                    |
+| `normalized-event` | Runs the shipped codec and the real core interpreter against a recorded native payload, asserts the exact normalized envelope, and asserts that named raw content (file bodies, transcript paths, credentials) appears nowhere in it. This is how an `observe.*` capability becomes provable rather than claimed |
+| `decision-codec`   | Runs the connector-owned request/decision declaration through the real pure interpreter, asserts the bounded redacted request card, and pins exact allow/deny/defer bytes. Required for supported callback/extension `decide.*` capabilities                                                                     |
+
+Fixtures never reach the network.
+
+---
+
 ## Adding a New Agent Connector
 
 A new connector is the primary sanctioned extension point for this module. It requires a conformance manifest but does not require a contract version bump unless it introduces new capability flags or hook types.
@@ -54,13 +233,26 @@ A new connector is the primary sanctioned extension point for this module. It re
    - Not clobber existing user settings
    - Be detectable by `ovld doctor` as stale, missing, or partially installed
 
-4. **List managed files** in the adapter's manifest so `ovld doctor` can verify them.
+4. **List managed files** in the adapter's manifest so `ovld doctor` can verify them. Include
+   `harness-capabilities.yaml` and `CAPABILITIES.md` so the installed descriptor digest can be
+   compared with the compiled catalog.
+
+4b. **Write the harness capability descriptor** (`harness-capabilities.yaml`) and its fixtures,
+then run `yarn connectors:capabilities`. Declare every capability id — an omission reads as a
+claim. Start honest: a harness that can do something Overlord has not built yet is
+`not-implemented` with a tracker, never `supported`.
+
+4c. **Write the event codec** (`codec/<agent>.codec.yaml`) and a `normalized-event` fixture per
+capability you intend to grade `supported`. You should not need to write any TypeScript to
+add a push path for a new harness — if you find yourself wanting to, the abstraction is
+wrong and that is worth raising rather than working around.
 
 5. **Write a prompt wrapper** if the agent needs mission context prepended at launch time. The wrapper receives a context file path and emits the final prompt text.
 
 6. **Create `connectors/adapters/<agent-name>/conformance-manifest.yaml`** declaring:
+
    ```yaml
-   contractVersion: "0"
+   contractVersion: '0'
    componentType: connector
    componentKey: <agent-name>
    capabilities:
@@ -105,7 +297,7 @@ The connector core is the set of canonical Markdown workflow instructions every
 
 ## Adding a New Capability Flag
 
-Capability flags (e.g. `supports-checkpointing`, `supports-multi-session`) are listed in `contract/extension-points.yaml` under `approvedConnectorCapabilities`. New flags require a contract update.
+Capability flags (e.g. `sessionEventStream`, `nativeSessionBinding`) are listed in `contract/extension-points.yaml` under `approvedConnectorCapabilities`. New flags require a contract update.
 
 **Steps:**
 

package/dist/connectors/HARNESS-MATRIX.md

@@ -0,0 +1,67 @@
+<!-- GENERATED FILE — DO NOT EDIT. Source: harness-capabilities.yaml. Regenerate with `yarn connectors:capabilities`. -->
+
+# Harness capability matrix
+
+Generated from each adapter's `harness-capabilities.yaml`. This file replaces the
+hand-written capability table that used to live in `connectors/README.md`: prose maintained
+by hand alongside code drifts, and a matrix that is 60% accurate is worse than none because
+it is trusted.
+
+Legend: ✅ supported (fixture-proven) · ⛔ unsupported (harness cannot) · 🚧 not-implemented
+(buildable, unbuilt) · ❓ unverified (find out first).
+
+## Adapters
+
+| Adapter | Harness | Verified version | Shape | Tier | Binding | Decision hold |
+| --- | --- | --- | --- | --- | --- | --- |
+| [`antigravity`](adapters/antigravity/CAPABILITIES.md) | Antigravity CLI | — | `callback` | 0 (Unsupported) | ❓ unverified | ❓ unverified |
+| [`claude`](adapters/claude/CAPABILITIES.md) | Claude Code | `2.1.220` | `callback` | 3 (Conversational) | ✅ supported | ✅ supported |
+| [`codex`](adapters/codex/CAPABILITIES.md) | Codex CLI | `0.146.0` | `callback` | 3 (Conversational) | ✅ supported | ✅ supported |
+| [`cursor`](adapters/cursor/CAPABILITIES.md) | Cursor Agent CLI | `2026.07.23-e383d2b` | `callback` | 0 (Unsupported) | ❓ unverified | ✅ supported |
+| [`opencode`](adapters/opencode/CAPABILITIES.md) | OpenCode | — | `controlPlane` | 3 (Conversational) | ✅ supported | ✅ supported |
+| [`pi`](adapters/pi/CAPABILITIES.md) | Pi Coding Agent | `0.83.0` | `extension` | 3 (Conversational) | ✅ supported | ✅ supported |
+
+## Capabilities
+
+| Capability | `antigravity` | `claude` | `codex` | `cursor` | `opencode` | `pi` |
+| --- | --- | --- | --- | --- | --- | --- |
+| `observe.prompt` | ❓ unverified | ✅ supported | ✅ supported | 🚧 not-implemented | 🚧 not-implemented | ✅ supported |
+| `observe.toolCall` | ❓ unverified | 🚧 not-implemented | ✅ supported | 🚧 not-implemented | 🚧 not-implemented | ✅ supported |
+| `observe.toolResult` | ❓ unverified | ✅ supported | ✅ supported | 🚧 not-implemented | ✅ supported | 🚧 not-implemented |
+| `observe.fileEdit` | ❓ unverified | ✅ supported | ✅ supported | 🚧 not-implemented | ✅ supported | 🚧 not-implemented |
+| `observe.sessionLifecycle` | ❓ unverified | ✅ supported | ✅ supported | 🚧 not-implemented | ✅ supported | ✅ supported |
+| `decide.shell` | ❓ unverified | ✅ supported | ✅ supported | ✅ supported | ✅ supported | ✅ supported |
+| `decide.mcp` | ❓ unverified | ✅ supported | ✅ supported | ✅ supported | ✅ supported | ✅ supported |
+| `decide.fileWrite` | ❓ unverified | ✅ supported | ✅ supported | 🚧 not-implemented | 🚧 not-implemented | ✅ supported |
+| `decide.anyTool` | ❓ unverified | 🚧 not-implemented | 🚧 not-implemented | ✅ supported | ✅ supported | ✅ supported |
+| `decide.universal` | ❓ unverified | ✅ supported | ✅ supported | ⛔ unsupported | 🚧 not-implemented | ✅ supported |
+| `answer.structuredQuestion` | ❓ unverified | ❓ unverified | ❓ unverified | ⛔ unsupported | 🚧 not-implemented | 🚧 not-implemented |
+| `answer.persistentAllow` | ❓ unverified | 🚧 not-implemented | ❓ unverified | ⛔ unsupported | 🚧 not-implemented | ⛔ unsupported |
+| `inject.midTurn` | ❓ unverified | ✅ supported | ❓ unverified | ⛔ unsupported | ✅ supported | ✅ supported |
+| `inject.turnBoundary` | ❓ unverified | ✅ supported | ✅ supported | ✅ supported | ✅ supported | ✅ supported |
+| `inject.nextTurn` | ❓ unverified | 🚧 not-implemented | 🚧 not-implemented | ✅ supported | ✅ supported | 🚧 not-implemented |
+| `terminal.concurrentAnswer` | ❓ unverified | ⛔ unsupported | ⛔ unsupported | ⛔ unsupported | ✅ supported | ⛔ unsupported |
+| `terminal.statusSurface` | ❓ unverified | 🚧 not-implemented | ❓ unverified | ❓ unverified | 🚧 not-implemented | 🚧 not-implemented |
+
+## Open hazards
+
+| Adapter | Hazard | Severity | Verification | Mitigation | Tracked as |
+| --- | --- | --- | --- | --- | --- |
+| `antigravity` | `outside-verification-survey` | medium | unverified | required | `agent-session-verify-antigravity` |
+| `antigravity` | `pre-tool-use-always-allows` | medium | verified | required | `agent-session-verify-antigravity` |
+| `claude` | `shipped-stop-hook-inert` | medium | verified | required | `agent-session-phase-3` |
+| `claude` | `unbound-session-side-effects` | medium | verified | required | `agent-session-phase-4` |
+| `claude` | `fork-and-subagent-identity-unknown` | medium | unverified | required | `taxonomy-7.6` |
+| `codex` | `hooks-version-and-platform-gate` | medium | verified | required | `agent-session-phase-4` |
+| `cursor` | `reads-claude-hook-config` | high | unverified | required | `taxonomy-7.1` |
+| `cursor` | `allowlist-precedence` | medium | unverified | required | `taxonomy-7.8` |
+| `opencode` | `harness-version-unverified` | medium | unverified | required | `agent-session-verify-opencode-frames` |
+| `pi` | `typed-api-version-coupling` | medium | unverified | required | `taxonomy-7.10` |
+
+## Reading this table
+
+Before writing any code for a harness, read its descriptor or run
+`ovld agent-session capabilities <agent>`. Do not attempt an `unsupported` capability. If you
+believe the cited evidence is now wrong, replace `evidenceRef` and add the executable fixture
+in the same change that flips the status.
+

package/dist/connectors/README.md

@@ -70,26 +70,40 @@ or the harness extension catalog (→ Extension System, see [Database module](..
 
 ### Adapter capability matrix
 
-Adapters deliberately differ. This table records what each one ships and, where a
-mechanism is absent, whether the gap is a decision or simply unported work — so a
+> **Agent-session interaction capabilities are not documented here.** What a harness can
+> observe, decide, and inject — and whether a gap is a hard limit, unbuilt work, or simply
+> unknown — lives in the generated, fixture-backed [harness capability
+> matrix](HARNESS-MATRIX.md) and each adapter's `CAPABILITIES.md`. Prose maintained by hand
+> alongside code drifts, and a matrix that is 60% accurate is worse than none because it is
+> trusted. Run `ovld agent-session capabilities <agent>` for the same answer in a terminal.
+
+The table below is about **packaging**, not interaction: which files each adapter ships and,
+where a mechanism is absent, whether the gap is a decision or simply unported work — so a
 contributor adding an adapter can tell signal from neglect. Source of truth for the
 "ships" columns is each adapter's `conformance-manifest.yaml`.
 
-| Adapter | Commands | Hooks | Local MCP shim | MCP config | Rules | Native resume |
-|---|---|---|---|---|---|---|
-| `claude` | `commands/` | `hooks/hooks.json` (4 types) | — | — | — | — |
-| `codex` | — | `.codex-plugin/hooks.json` + `scripts/*.sh` (2 types) | rendered | `.mcp.json` | — | yes |
-| `cursor` | `commands/` | `hooks/*.sh` (4 types) | rendered | `mcp.json` | `rules/` | — |
-| `antigravity` | `skills/*.md` | `hooks.json` + `scripts/*.sh` (2 types) | rendered | `mcp_config.json` | — | — |
-| `pi` | — | `extensions/overlord.ts` (`input` event) | — | — | — | yes |
+| Adapter       | Commands      | Hooks                                                 | Local MCP shim | MCP config        | Rules    | Native resume |
+| ------------- | ------------- | ----------------------------------------------------- | -------------- | ----------------- | -------- | ------------- |
+| `claude`      | `commands/`   | `hooks/hooks.json` (5 types)                          | —              | —                 | —        | —             |
+| `codex`       | —             | `.codex-plugin/hooks.json` + `scripts/*.sh` (2 types) | rendered       | `.mcp.json`       | —        | yes           |
+| `cursor`      | `commands/`   | `hooks/*.sh` (4 types)                                | rendered       | `mcp.json`        | `rules/` | —             |
+| `antigravity` | `skills/*.md` | `hooks.json` + `scripts/*.sh` (2 types)               | rendered       | `mcp_config.json` | —        | —             |
+| `pi`          | —             | `extensions/overlord.ts` (input/tool/session events)  | —              | —                 | —        | yes           |
+| `opencode`    | —             | none — control plane, see below                       | —              | —                 | —        | —             |
 
 Intentional omissions:
 
+- **`opencode` ships no hooks, and never will.** It is a control-plane harness (Shape C): it
+  runs a local HTTP server and publishes an event stream, so integration means subscribing
+  rather than being invoked. Overlord drives it with `ovld agent-session sidecar`, started
+  alongside the harness. The sidecar implements event reconciliation, concurrent permission
+  observation, and `prompt_async` instruction delivery, but the bundled agent catalog does not
+  yet start it automatically. A supervised execution target must supply that launch integration.
 - **`claude` ships no local MCP shim.** The Claude plugin reaches Overlord's hosted
   MCP server, so a local stdio bridge would duplicate it.
-- **`pi` ships no shim, hooks directory, or commands.** PI integrates through a
-  single TypeScript extension, and it has no native permission-request hook — its
-  `input` event carries follow-up capture only.
+- **`pi` ships no shim, hooks directory, or commands.** PI integrates through one TypeScript
+  extension. It has no native permission dialog; its optional `tool_call` decision interceptor
+  is fail-open and requires explicit workspace and project opt-in.
 - **`antigravity` passes no model or effort flag.** Antigravity selects the model
   internally; see [05 — Connectors and Agent Plugins](docs/05-connectors-and-agent-plugins.md#antigravity-connector).
 - **`cursor` passes no effort/thinking flag.** Deferred, not declined — recorded in

package/dist/connectors/VERSION

@@ -1 +1 @@
-0.3.10
+0.3.17

package/dist/connectors/adapters/antigravity/CAPABILITIES.md

@@ -0,0 +1,84 @@
+<!-- GENERATED FILE — DO NOT EDIT. Source: harness-capabilities.yaml. Regenerate with `yarn connectors:capabilities`. -->
+
+# Antigravity CLI — Overlord agent-session capabilities
+
+**Adapter** `antigravity` · **Codec** `antigravity` · **Integration shape** `callback` · **Capability tier** 0 (Unsupported)
+
+**Harness version verified** _not verified_ · **scheme** `opaque`
+
+**Descriptor digest** `c021926c384a72bdaa62ac5f0eab57e80822c5d2996db75ea3c30c6bf5d09ce8`
+
+> The tier is derived from passing fixtures, never authored. `unsupported` means the harness
+> cannot do it — do not attempt it. `not-implemented` means it is buildable and unbuilt: that is
+> your work. `unverified` means find out first. `supported` without a passing fixture is a CI
+> failure, not a claim.
+
+## Session binding
+
+| Field | Value |
+| --- | --- |
+| Status | ❓ unverified |
+| Source | `payload` |
+| Evidence | tracked as `agent-session-verify-antigravity` |
+
+No native session identifier has been established for Antigravity hook payloads. Until one is, this connector cannot bind, and therefore cannot reach any interaction tier.
+
+The native session id is a **correlation alias only**. Authorization and mission scope come
+from the verified channel/session credential; neither the working directory nor an unverified
+native id is a binding authority.
+
+## Decision hold
+
+| Field | Value |
+| --- | --- |
+| Status | ❓ unverified |
+| Harness ceiling | none documented |
+| Evidence | tracked as `agent-session-verify-antigravity` |
+
+The shipped hooks declare a 10-second timeout, but whether a held PreToolUse response actually gates execution — and what the harness does when the hook exceeds that timeout — was not verified.
+
+## Capabilities
+
+| Capability | Status | Native | Evidence |
+| --- | --- | --- | --- |
+| `observe.prompt` | ❓ unverified | `PreInvocation` | tracked as `agent-session-verify-antigravity` |
+| `observe.toolCall` | ❓ unverified | `PreToolUse` | tracked as `agent-session-verify-antigravity` |
+| `observe.toolResult` | ❓ unverified | — | tracked as `agent-session-verify-antigravity` |
+| `observe.fileEdit` | ❓ unverified | — | tracked as `agent-session-verify-antigravity` |
+| `observe.sessionLifecycle` | ❓ unverified | — | tracked as `agent-session-verify-antigravity` |
+| `decide.shell` | ❓ unverified | `PreToolUse` | tracked as `agent-session-verify-antigravity` |
+| `decide.mcp` | ❓ unverified | — | tracked as `agent-session-verify-antigravity` |
+| `decide.fileWrite` | ❓ unverified | — | tracked as `agent-session-verify-antigravity` |
+| `decide.anyTool` | ❓ unverified | `PreToolUse` | tracked as `agent-session-verify-antigravity` |
+| `decide.universal` | ❓ unverified | — | tracked as `agent-session-verify-antigravity` |
+| `answer.structuredQuestion` | ❓ unverified | — | tracked as `agent-session-verify-antigravity` |
+| `answer.persistentAllow` | ❓ unverified | — | tracked as `agent-session-verify-antigravity` |
+| `inject.midTurn` | ❓ unverified | — | tracked as `agent-session-verify-antigravity` |
+| `inject.turnBoundary` | ❓ unverified | — | tracked as `agent-session-verify-antigravity` |
+| `inject.nextTurn` | ❓ unverified | — | tracked as `agent-session-verify-antigravity` |
+| `terminal.concurrentAnswer` | ❓ unverified | — | tracked as `agent-session-verify-antigravity` |
+| `terminal.statusSurface` | ❓ unverified | — | tracked as `agent-session-verify-antigravity` |
+
+## Hazards
+
+| Hazard | Severity | Verification | Mitigation | Tracked as |
+| --- | --- | --- | --- | --- |
+| `outside-verification-survey` | medium | unverified | required | `agent-session-verify-antigravity` |
+| `pre-tool-use-always-allows` | medium | verified | required | `agent-session-verify-antigravity` |
+
+**`outside-verification-survey`** — Antigravity was not part of the harness verification survey. Every row above is unverified rather than inferred, and this connector must stay at its fixture-proven tier until a dedicated verification objective upgrades it.
+
+**`pre-tool-use-always-allows`** — The shipped PreToolUse hook always answers `{"allow_tool":true}` and records the request through a detached `ovld protocol permission-request` call to a subcommand that does not exist. It therefore neither gates nor records anything, while its conformance manifest declared the permissionHook capability.
+
+## Native decision shape
+
+- **Codec** `antigravity`
+- **Never send** `hookSpecificOutput`, `permissionDecision`, `permission`
+
+The observed response shape is a flat `{"allow_tool": boolean}`. No deny or defer shape has been verified, so no decision codec may be written for this adapter yet.
+
+## Unbound-session negative test
+
+Fixture: `fixtures/unbound-session.json` — proves what this adapter's registered
+integrations do in a session with no Overlord binding, in an unrelated directory.
+

package/dist/connectors/adapters/antigravity/README.md

@@ -72,7 +72,9 @@ This connector is intentionally reviewable against the four connector layers in
 - `plugin.json` — Antigravity plugin manifest (name, description, metadata).
 - `skills/overlord-mission/SKILL.md` — Antigravity adapter template with a `<!-- @connector-core -->` marker; setup interpolates shared core content at install time.
 - `skills/attach.md`, `skills/connect.md`, `skills/load.md`, `skills/create.md`, `skills/prompt.md`, `skills/discuss-objective.md`, `skills/add-objectives.md`, `skills/record-work.md`, `skills/spawn.md` — one skill per protocol operation; Antigravity auto-registers each as a `/<name>` slash command.
-- `hooks.json` + `scripts/pre-invocation-hook.sh` + `scripts/pre-tool-use-hook.sh` — follow-up and permission activity capture through `ovld protocol` (see mapping notes below).
+- `hooks.json` + `scripts/pre-invocation-hook.sh` + `scripts/pre-tool-use-hook.sh` — legacy
+  follow-up and pre-tool compatibility hooks (see the limitations below). These are not a
+  fixture-proven agent-session decision path.
 - `mcp_config.json` + `scripts/overlord-mcp.mjs` — MCP bridge to common `ovld protocol` operations. The shim is **generated**: it is rendered from `connectors/core/scripts/overlord-mcp.mjs` at setup time with the adapter key substituted, and there is no copy in this directory to edit.
 - `conformance-manifest.yaml` — connector conformance declaration for the Overlord contract.
 - `prompt-wrapper.md` — Antigravity launch guidance.
@@ -92,7 +94,11 @@ See the [adapter capability matrix](../../README.md#adapter-capability-matrix) f
 Antigravity's native hook events are `PreToolUse`, `PostToolUse`, `PreInvocation`, `PostInvocation`, and `Stop` — it has no event literally named `UserPromptSubmit` or `PermissionRequest` the way Claude Code and Codex do. This adapter maps Antigravity's native events onto Overlord's canonical hook-type vocabulary the same way the Cursor adapter maps `beforeSubmitPrompt` onto `UserPromptSubmit`:
 
 - `PreInvocation` (fires before each agent turn) → recorded as the canonical `UserPromptSubmit` follow-up-capture hook.
-- `PreToolUse` (fires before each tool call) → recorded as the canonical `PermissionRequest` hook. It always responds `{"allow_tool":true}`; it never gates a tool call, it only logs the request through `ovld protocol permission-request`.
+- `PreToolUse` (fires before each tool call) → the legacy script always responds
+  `{"allow_tool":true}`. Its detached `ovld protocol permission-request` target is not a current
+  protocol command, so it neither gates nor reliably records the request. The generated
+  capability descriptor keeps Antigravity at tier 0 until a native fixture-backed path replaces
+  this compatibility hook.
 
 Both hook scripts are defensive: they no-op on any missing `MISSION_ID`, missing `ovld` binary, or unexpected payload shape, and they always return a well-formed allow response so a hook failure never blocks the Antigravity session. Antigravity's public docs do not yet pin an exact `PreInvocation` payload shape the way they do for `PreToolUse` (`toolCall.args`), so `pre-invocation-hook.sh` probes a few plausible field names (`prompt`, `message`, `text`, `input`) for the human turn text; adjust this once the official schema is confirmed.
 

package/dist/connectors/adapters/antigravity/conformance-manifest.yaml

@@ -1,4 +1,4 @@
-contractVersion: "37"
+contractVersion: "52"
 componentType: connector
 componentKey: antigravity
 label: "Antigravity Connector"
@@ -6,16 +6,27 @@ description: "Antigravity plugin adapter for the Overlord mission protocol workf
 
 connector:
   agentIdentifier: antigravity
+  # ── GENERATED: do not edit by hand ───────────────────────────────────────────
+  # Projected from connectors/adapters/antigravity/harness-capabilities.yaml by `yarn connectors:capabilities`.
+  # `capabilities` and `hookTypes` are the DEPRECATED hook-named projection, retained for
+  # one release. `harnessCapabilities` is the authoritative source.
+  integrationShape: callback
+  capabilityTier: 0
+  harnessCapabilities:
+    path: connectors/adapters/antigravity/harness-capabilities.yaml
+    schemaVersion: 1
+    digest: "c021926c384a72bdaa62ac5f0eab57e80822c5d2996db75ea3c30c6bf5d09ce8"
   capabilities:
     - followUpHook
-    - permissionHook
     - contextFilePrompt
     - slashCommands
   hookTypes:
     - UserPromptSubmit
-    - PermissionRequest
+  # ── END GENERATED ────────────────────────────────────────────────────────────
   installPath: "~/.gemini/antigravity-cli/plugins/overlord"
   managedFiles:
+    - "harness-capabilities.yaml"
+    - "CAPABILITIES.md"
     - "plugin.json"
     - "mcp_config.json"
     - "hooks.json"

package/dist/connectors/adapters/antigravity/fixtures/unbound-session.json

@@ -0,0 +1,24 @@
+{
+  "fixtureVersion": 1,
+  "kind": "script-io",
+  "description": "Mandatory negative test: Antigravity's PreToolUse hook in a session with no Overlord binding, in an unrelated directory. It must make no write, no CLI invocation, and no delay. Its stdout is the harness's required allow response, which is the correct fail-toward-the-harness behavior for an unbound session.",
+  "script": "connectors/adapters/antigravity/scripts/pre-tool-use-hook.sh",
+  "stdin": {
+    "hook_event_name": "PreToolUse",
+    "tool_name": "run_command",
+    "tool_input": { "command": "rm -rf ./build" }
+  },
+  "env": {
+    "MISSION_ID": null,
+    "SESSION_KEY": null,
+    "OVERLORD_SESSION_CHANNEL_ID": null,
+    "OVERLORD_SESSION_CHANNEL_TOKEN": null
+  },
+  "expect": {
+    "exitCode": 0,
+    "stdout": "{\"allow_tool\":true}",
+    "stderr": "",
+    "cliInvocations": [],
+    "sandboxWrites": []
+  }
+}