Connector Compatibility

DefenseClaw tracks hook connector compatibility with a packaged JSON manifest at cli/defenseclaw/inventory/hook_contracts.json. The manifest maps each connector version range to the hook contract DefenseClaw knows how to install, parse, evaluate, and respond to.

Current contracts

Open-ended contracts leave max_exclusive empty until an upstream release publishes a breaking hook change. Bounded contracts stop setup from claiming compatibility beyond a source-reviewed surface. Codex's adjacent ranges also capture hook-event additions and the 0.135.0 expansion from selective to generic local-function tool payloads. Installed versions and selected contracts are recorded in hook_contract_lock.json for doctor drift checks.

Gemini CLI is no longer an active compatibility row. DefenseClaw rejects new Gemini CLI setup on every platform and directs operators to Antigravity; the retired contract remains compiled only for receipt-bound teardown of existing managed hooks.

The active floors and bounds come from upstream release notes, current vendor docs, or source review: Codex 0.124.0 is the stable-hooks release. Cursor introduced beta hooks in 1.7.0, but DefenseClaw's current 21-event contract is pinned exactly to Cursor Agent build 2026.07.23-e383d2b; the application/Desktop cursor_version field is not accepted as Agent CLI version evidence. Hermes is bounded to >=0.19.0,<0.21.0, OpenHands starts at 1.12.0 and is source-reviewed against 1.16.0, and Devin is pinned exactly to the source-reviewed 3000.4.25 CLI contract. Copilot CLI v1 starts at 1.0.18, while v2 starts at 1.0.76. OpenCode is bounded to the v1.18.10-v1.18.19 source-reviewed plugin/config/MCP contract. OmniGent is capped at >=0.7.0,<0.8.0. Antigravity (agy) starts at 1.1.8; the protected harness currently pins official CLI 1.1.10. Claude Code v1 is bounded to >=2.1.154,<2.1.219, and v2 begins at 2.1.219 with observational DirectoryAdded.

Codex 0.133.0 through 0.134.x use the ten-event codex-hooks-v3 selective-local-tool contract. Codex 0.135.0 through 0.144.x use the same event matrix under codex-hooks-v3-generic, reflecting the expansion to generic local function tools. The official 0.145.0 release added SessionEnd, beginning the eleven-event codex-hooks-v4 contract. In all v3/v4 tiers, DefenseClaw preserves the official hook response semantics: SessionStart continue: false ends the turn; SubagentStop decision: "block" continues the subagent; PreCompact stops before compaction; PostCompact stops only after compaction; Stop block continues with a new prompt; and PostToolUse block feeds/replaces the completed tool result (with the code-mode promise rejecting) rather than undoing the tool. These lifecycle-control claims are limited to v3/v4 (>=0.133) and are not inferred or backfilled onto the smaller v1/v2 contracts. SessionEnd is observation-only in DefenseClaw: it is a best-effort teardown notification with a three-second maximum timeout, not a block or native ask surface.

Amp's normalized 0.0.1785334225 value is DefenseClaw's pinned contract snapshot and certification floor for the documented five-event API used by amp-plugin-v1 with managed plugin script generation v2; Amp does not declare it as the upstream minimum. Execute mode also needs --plugin-ready-timeout 30 so policy plugins load before the turn starts.

Setup-time checks

Every defenseclaw setup ... path that chooses a connector refreshes local agent discovery, reads the installed connector version, and checks it against the manifest before writing config. Unsupported or unverified hook connector versions are allowed in observe mode with a warning, but action mode fails closed unless DEFENSECLAW_ALLOW_HOOK_CONTRACT_DRIFT=1 is set for exploratory testing. OpenCode is the bounded exception: a detected version outside >=1.18.10,<1.18.20 is refused before mutation in both observe and action mode because its plugin registration and contract lock must converge as one transaction.

The most common reason a version can't be read is the connector binary living outside a trusted install prefix (for example a bespoke install under ~/.local). Interactive action-mode setup detects this and offers to trust the directory (defaulting to No, persisting to ~/.defenseclaw/.env, then re-running the full contract check — trusting a path never bypasses the version gate). Non-interactive runs print the equivalent remediation: defenseclaw setup trusted-paths add <dir>. See the trusted-paths group on the CLI reference and the trust model in AI Discovery.

Proxy connectors are recorded in the manifest too, but they are marked not-gated because their enforcement surface is the DefenseClaw proxy instead of an agent hook contract.

Runtime lock

After gateway setup completes, DefenseClaw writes hook_contract_lock.json under the configured data directory. Among its contract and integrity fields, the lock records:

defenseclaw doctor reads the lock and compares it with the current discovery cache so connector upgrades, hook contract changes, and hook script drift show up before action-mode enforcement depends on them.