Connector compatibility

Versioned hook contracts, setup-time compatibility checks, and the runtime hook contract lock for DefenseClaw connectors.

DefenseClaw tracks hook connector compatibility in a packaged manifest, cli/defenseclaw/inventory/hook_contracts.json. It maps each agent version range to the hook contract DefenseClaw knows how to install, parse, evaluate and answer.

Contracts and platform support are separate

A contract says DefenseClaw understands an agent version's hooks. It does not say the connector runs on every OS: see the support matrix.

CEL policy and tool-call state contract

For pre/post tool-call pairing and outcome tiers per connector, see the stateful connector lifecycle.

Current contracts

ConnectorSupported versionsContract / hook scriptEventsInspects
OpenClawnot gated (proxy)n/an/aproxy request/response
ZeptoClawnot gated (proxy)n/an/aproxy request/response
Codex>=0.124.0, <0.129.0codex-hooks-v1 / v66prompt, tool_call, tool_result
Codex>=0.129.0, <0.133.0codex-hooks-v2 / v68prompt, tool_call, tool_result
Codex>=0.133.0, <0.135.0codex-hooks-v3 / v610prompt, tool_call, tool_result
Codex>=0.135.0, <0.145.0codex-hooks-v3-generic / v610prompt, tool_call, tool_result
Codex>=0.145.0codex-hooks-v4 / v611prompt, tool_call, tool_result
Claude Code>=2.1.154, <2.1.219claudecode-hooks-v1 / v728prompt, tool_call, tool_result, event_content
Claude Code>=2.1.219claudecode-hooks-v2 / v729prompt, tool_call, tool_result, event_content
Hermes>=0.19.0, <0.21.0; exact pins 2026.7.20, 2026.7.30, 2026.8.3, 2026.8.13, 2026.8.16, 2026.8.16.2, 2026.8.18, 2026.8.19, 2026.8.27hermes-hooks-v1 / v623prompt, tool_call, tool_result, event_content
Hermes>=0.21.0, <0.22.0; exact pins 2026.8.31, 2026.9.7, 2026.9.11, 2026.9.14, 2026.9.21, 2026.9.24hermes-hooks-v2 / v623prompt, tool_call, tool_result, event_content
Cursor>=2.4.0, <4.0.0; exact pins 2026.07.23-e383d2bcursor-hooks-v1 / v821prompt, tool_call, tool_result
Devin3000.4.25, 3000.11.3devin-hooks-v1 / v78prompt, tool_call, tool_result
GitHub Copilot CLI>=1.0.18, <1.0.76copilot-hooks-v1 / v713prompt, tool_call, tool_result
GitHub Copilot CLI>=1.0.76copilot-hooks-v2 / v714prompt, tool_call, tool_result
Antigravity>=1.1.8antigravity-hooks-v2 / v85tool_call, event_content
OpenCode>=2.0.0, <2.3.0opencode-hooks-v2 / v78tool_call, tool_result
Amp>=0.0.1785334225amp-plugin-v1 / v25prompt, tool_call, tool_result, event_content
Kirokiro-cli >=2.27.1; Kiro IDE >=1.0.182native hooks on both Kiro hook surfaces, plus the optional ACP contractn/aprompt, tool_call, tool_result; ACP adds permission, filesystem, terminal
  • Kiro. Kiro IDE and kiro-cli --v3 read .kiro/hooks/*.json, and bare kiro-cli (2.x) reads its agent config. Per-user installs have no hook contract, but kiro-cli must be 2.27.1 or later: before it, a non-interactive kiro-cli chat --v3 run loads no hooks, so setup refuses an older kiro-cli in both modes when no supported IDE is present. An IDE before 1.0.182 cannot read global hooks: per-user and managed setup refuse an older IDE in both modes when it is the only Kiro installation. A Kiro form whose version could not be read is unknown and not protected: action setup refuses it unless a supported form is installed. With Kiro IDE 1.0.182 or later, setup installs the shared global hooks for the IDE and reports the CLI separately as unsupported. Managed Windows pins kiro-cli-windows-managed-hooks-v1 (kiro-cli >=2.24.1 for an earlier enrolled row; new rows require >=2.27.1) or kiro-ide-windows-managed-hooks-v1 (Kiro IDE >=1.0.182). An earlier enrolled CLI below 2.27.1 keeps its interactive hook files, but status reports it as uncovered and verify fails because its headless V3 path sends no hooks.
  • Cursor. The range >=2.4.0, <4.0.0 is the Cursor Desktop application version; from 4.0.0 on it runs as an untested newer version. The Agent CLI is covered only at the reviewed exact build 2026.07.23-e383d2b. A later Agent build runs as an untested newer version, and a build with the same date but another build ID has no contract. The cursor_version field in hook payloads is the Desktop application version.
  • Codex. 0.133.0 to 0.134.x use the ten-event codex-hooks-v3 contract with selective local-function tool payloads. 0.135.0 to 0.144.x keep the event matrix and expand to generic local function tools (codex-hooks-v3-generic). 0.145.0 adds SessionEnd (codex-hooks-v4). Per-user setup also needs Codex 0.136.0 or newer for its app-server command, and checks this before it changes anything.
  • Claude Code. v1 covers >=2.1.154, <2.1.219 with 28 events. v2 starts at 2.1.219 with 29 events and adds the observation-only DirectoryAdded.
  • Antigravity (agy). The contract starts at >=1.1.8. The OpenShell sandbox image installs agy 1.2.12.
  • Amp. 0.0.1785334225 is DefenseClaw's contract snapshot and certification floor for the five-event plugin API (amp-plugin-v1, plugin script v2). Amp does not declare it as the upstream minimum.
  • Hermes. A git install that prints only its release date, such as Hermes Agent vunknown (2026.9.24), is matched by the date tags in the table. An earlier date has no contract and a later one is an untested newer version.
  • Hermes 0.19.0 to 0.21.0 run their TUI without the hooks. Their TUI (hermes --tui) and dashboard chat run tools without the shell hooks DefenseClaw registers, so a terminal call there is neither checked nor recorded (upstream fix). Their classic interface, cron, ACP and messaging gateway run the hooks, so DefenseClaw sets these releases up (also the release dates 2026.7.20 up to 2026.9.7, and a git build that prints one of those dates), and setup, defenseclaw doctor and the gateway log warn about the TUI. Use the classic interface, or update Hermes to 0.21.1 or later (hermes update). The pinned Hermes in the OpenShell image is not refused either; the sandbox refuses its TUI, dashboard chat and hermes serve instead. See Hermes.

Open-ended contracts leave max_exclusive empty until an upstream release publishes a breaking hook change. A bounded contract records how far DefenseClaw tested a connector, not where it stops working.

Version policy

OpenCode supports V2 only. Detected V1 and future majors are refused even with the exploratory drift override. Newer V2 minors use the V2 contract with an untested-version warning outside strict profiles.

DefenseClaw assumes a connector version works unless it knows otherwise.

CaseWhat happens
Untested newer version: above every tested range, or between two exact pins of one contractUses the newest contract. Setup keeps your mode. Doctor and setup print an informational "untested newer version" line.
Below the lowest tested version, in a gap between ranges, or the same version as an exact-build pin with another build IDNo contract. Setup refuses the connector in observe and action mode and changes nothing.
Known broken: listed in known_broken_versions with a reason and an issue linkTreated like a version below the floor, and the refusal names the reason. An entry with warn_only is not refused: the version keeps its contract, and setup and doctor warn with the reason. Today the list holds one warning: Hermes 0.19.0 to 0.21.0 on the host (see above).
Compatible update after setupDoctor reports information. defenseclaw setup <connector> or the next gateway start refreshes the lock.
Enterprise standalone profileSame rules. A version with no contract gets no hooks in any guardrail mode, and status and verify report hook_contract_unverified with coverage_complete: false.

Setup-time checks

Every defenseclaw setup path that chooses a connector refreshes agent discovery, reads the installed version and checks it against the manifest before it writes config.

  • A version with no contract is refused in observe and action mode before any change, with the version to upgrade to. defenseclaw init and quickstart leave such a connector out in both modes too. Upgrade the agent, then run defenseclaw setup <connector> again. DEFENSECLAW_ALLOW_HOOK_CONTRACT_DRIFT=1 skips this check for exploratory testing only.
  • OpenCode is refused the same way. A detected version with no contract is below 1.18.10 or known broken; its plugin and contract lock must change together.
  • If the agent is not installed on the host, action mode accepts the harness image DefenseClaw built for it. The image must be the one a sandbox would run now: built by this release for this user from the current openshell.image settings, hook-fire verified, and with a harness version that resolves to a known contract. Run defenseclaw sandbox image build <harness> if it is refused.
  • If the version cannot be read because the binary is outside a trusted install prefix, interactive setup offers to trust the directory. Non-interactive runs print defenseclaw setup trusted-paths add <dir>. Trusting a path never bypasses the version gate.

The gateway checks the version again when it starts. DEFENSECLAW_ALLOW_HOOK_CONTRACT_DRIFT=1 skips both checks.

  • With one connector, a version with no contract is refused in observe and action mode for every hook connector, and the gateway does not start. A version that could not be read is refused in action mode. This check is skipped when the enterprise hook guardian owns the hooks (a managed enterprise computer).
  • With several connectors, a version with no contract is refused in action mode, and OpenCode in both modes. A version that could not be read is refused in action mode. The guardian does not skip this check. In observe mode a version with no contract gets a warning in the gateway log; Claude Code and Codex then fail their setup, because they build their hooks from the contract, and other connectors install their hooks.
  • A refused or failed connector that this gateway did not guard before is skipped, and the other connectors keep running. One it already guarded, as after an upgrade of DefenseClaw or of the agent, stops the start: the gateway restores the earlier connector state and does not start, except on a managed computer. If every connector is refused, the gateway does not start.

Proxy connectors are recorded in the manifest as not-gated, because their enforcement surface is the proxy.

Runtime lock

After gateway setup, DefenseClaw writes hook_contract_lock.json in the data directory.

FieldPurpose
raw_agent_versionThe exact version string discovered locally.
normalized_agent_versionThe semver-like value used for range matching.
contract_idThe contract selected for this connector.
hook_script_versionThe hook script generation installed on disk.
hook_script_digestsHashes of installed hook scripts, for drift detection.
defenseclaw_versionThe DefenseClaw build that wrote the lock.
updated_atWhen the gateway last wrote the lock, for the file and for each connector.

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

Fields the gateway rewrites

The gateway writes the lock again each time it starts, and on every upgrade, rollback or roll-forward. Those writes change only updated_at (for the file and for each connector) and, when the DefenseClaw version changed, defenseclaw_version. The new updated_at tells defenseclaw setup that the restarted gateway checked the hooks. The other fields change only when the agent, its hooks or your setup change.

A saved lock that you put back keeps its bytes until the gateway next starts. To check a restored lock, compare it without these two fields.