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

DefenseClaw leaves max_exclusive empty until an upstream release publishes a breaking hook change. Future versions are tracked through hook_contract_lock.json and doctor drift checks rather than a guessed major-version cap.

The floors come from upstream release notes or current vendor docs: Codex 0.124.0 is the stable-hooks release, Gemini CLI 0.26.0 enabled hooks by default, Cursor 1.7.0 introduced beta hooks, Hermes 0.11.0 added shell hooks (hermes-hooks-v1 covers the full seven-event lifecycle — pre_llm_call, pre_tool_call, post_tool_call, post_llm_call, session start/end, subagent_stop), Windsurf 1.12.41 added user prompt hooks to the Cascade pre-hook set, and Copilot CLI 1.0.18 is the first release containing every event in the current DefenseClaw Copilot contract. OpenCode loads JS plugins through a stable plugin API rather than a versioned hook config, so it is accepted as unversioned (validated with opencode 1.16.2). OmniGent uses its documented six-phase custom policy API and is accepted as unversioned until upstream publishes a policy-contract floor. OpenHands uses the current documented .openhands/hooks.json contract, installs globally through ~/.openhands/hooks.json by default, has been validated with OpenHands CLI 1.16.0, and is accepted as unversioned until upstream publishes a hook-version floor. Antigravity (agy) is pinned at >=1.0.0 (the version agy --version returns today); the upper bound stays open because agy auto-updates and DefenseClaw tracks compatibility through hook_contract_lock.json plus doctor drift checks. Claude Code is pinned to the current documented hook surface captured at 2.1.144; older Claude Code versions exposed smaller event sets.

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. 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.