Connector Compatibility
Versioned hook contracts, setup-time compatibility checks, and the runtime hook contract lock for DefenseClaw connectors.
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.
Version compatibility is not platform certification
A connector can have a valid hook contract and still be unsupported or not certified on native Windows. The current packaged Windows release contract certifies Codex, Claude Code, and Amp; see the native Windows connector matrix.
CEL policy and tool-call state contract
The version gate below proves that DefenseClaw understands a connector's hook schema; it does not by itself prove that pre/post tool calls can be paired or that a post event means success. See the stateful connector lifecycle for tool-surface coverage, outcome and identity tiers, and connector-specific rollout holds. Existing policy defaults are unchanged.
Current contracts
| Connector | Gate | Supported connector versions | Contract / hook script | AID surfaces |
|---|---|---|---|---|
| OpenClaw | proxy, not hook-gated | not gated by hook contract | n/a | proxy request/response |
| ZeptoClaw | proxy, not hook-gated | not gated by hook contract | n/a | proxy request/response |
| Codex | hook contract | >=0.124.0,<0.129.0 | codex-hooks-v1 / v6 (6 events) | prompt, tool_call, tool_result |
| Codex | hook contract | >=0.129.0,<0.133.0 | codex-hooks-v2 / v6 (8 events) | prompt, tool_call, tool_result |
| Codex | hook contract | >=0.133.0,<0.135.0 | codex-hooks-v3 / v6 (10 events, selective local tools) | prompt, tool_call, tool_result |
| Codex | hook contract | >=0.135.0,<0.145.0 | codex-hooks-v3-generic / v6 (10 events, generic local tools) | prompt, tool_call, tool_result |
| Codex | hook contract | >=0.145.0 | codex-hooks-v4 / v6 (11 events) | prompt, tool_call, tool_result |
| Claude Code | hook contract | >=2.1.152 | claudecode-hooks-v1 / v7 | prompt, tool_call, tool_result, event_content |
| Hermes | hook contract | >=0.11.0 | hermes-hooks-v1 / v6 | prompt, tool_call, tool_result, event_content |
| Cursor | hook contract | >=1.7.0 | cursor-hooks-v1 / v8 | prompt, tool_call, tool_result |
| Windsurf | hook contract | >=1.12.41 | windsurf-hooks-v1 / v6 | prompt, tool_call, tool_result |
| Gemini CLI | hook contract | >=0.26.0 | geminicli-hooks-v1 / v6 | prompt, tool_call, tool_result |
| GitHub Copilot CLI | hook contract | >=1.0.18 | copilot-hooks-v1 / v6 | prompt, tool_call, tool_result |
| OpenHands | hook contract | unversioned / documented hooks; tested with OpenHands CLI 1.16.0 | openhands-hooks-v1 / v6 | prompt, tool_call, tool_result, event_content |
| Antigravity | hook contract | >=1.1.9 | antigravity-hooks-v2 / v7 | prompt, tool_call, tool_result |
| OpenCode | hook contract | unversioned / plugin API; tested with opencode 1.16.2 | opencode-hooks-v1 / v7 | tool_call, tool_result |
| Amp | plugin contract | >=0.0.1785334225 | amp-plugin-v1 / v2 | prompt, tool_call, tool_result, event_content |
| OmniGent | hook contract | unversioned / documented custom-policy API | omnigent-custom-policy-v1 / v1 | prompt, tool_call, tool_result |
Open-ended contracts leave max_exclusive empty until an upstream release
publishes a breaking hook change. Codex is the current exception: its bounded
ranges capture both 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.
Codex 0.124.0 starts the six-event stable contract; 0.129.0 adds
PreCompact and PostCompact; 0.133.0 adds SubagentStart and
SubagentStop; 0.135.0 expands hook payloads to generic local function
tools; and 0.145.0 adds the true main-thread SessionEnd boundary.
The per-turn Codex Stop event never closes cross-turn chain state. Gemini CLI
0.26.0 enabled hooks by default, Cursor 1.7.0
introduced beta hooks, and Hermes 0.11.0 added shell hooks. The Hermes
contract covers ten events: four LLM/tool callbacks, session
start/end/finalize/reset, and subagent start/stop. Windsurf 1.12.41 added
user-prompt hooks to the Cascade pre-hook set, while Copilot CLI 1.0.18 is
the first release containing every event in the current DefenseClaw contract.
OpenCode's plugin API, OmniGent's six-phase custom-policy API, and OpenHands'
documented hooks are accepted as unversioned contracts. The manifest records
validation with opencode 1.16.2 and OpenHands CLI 1.16.0; those are
validation points, not minimum versions. 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; Amp does not declare it as
the upstream minimum. Execute mode additionally needs
--plugin-ready-timeout 30 so policy plugins load before the turn starts.
Antigravity is gated at >=1.1.9 because that release fixed PostToolUse firing
on non-tool steps and matcher handling.
Claude Code is gated at >=2.1.152, which is the 28-event surface represented
by the current contract.
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.
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:
| Field | Purpose |
|---|---|
raw_agent_version | The exact connector version string discovered locally. |
normalized_agent_version | The semver-like value used for manifest range matching. |
contract_id | The deterministic hook contract selected for this connector. |
hook_script_version | The DefenseClaw hook script generation installed on disk. |
hook_script_digests | Hashes of installed hook scripts for drift detection. |
defenseclaw_version | The DefenseClaw build that produced the lock. |
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.
Connectors
Fourteen built-in connectors share one adapter interface while exposing connector-specific proxy, hook, policy, telemetry, and approval capabilities.
Claude Code
Claude Code connector wires the documented lifecycle hook set plus native OTel. Thirteen current events can return block decisions, and PreToolUse supports native HITL ask.