FORG Adapter Protocol Governance
Conformance requirements, versioning policy, and the deprecation schedule for adapters that emit behavioral signals to the FORG Rule Engine.
What is the FORG Adapter Protocol?
The FORG Adapter Protocol defines how AI coding tool adapters (Claude Code, Cursor, Windsurf, OpenCode, and third-party adapters) emit behavioral signals to the FORG Rule Engine.
Conformance means the adapter: (a) emits signals using the correct schema, (b) authenticates every emission via HMAC-SHA256, (c) never includes prompt or completion content in any payload, and (d) handles all seven hook event types correctly.
This page defines what conformance requires, how protocol versions are numbered, and how long each version is supported before EOL.
Conformance requirements
Adapters that claim FORG compatibility must satisfy all requirements in all four categories below. The FORG conformance test suite validates these programmatically.
Signal schema
- ✓Emit signals that conform to FORG signal schema v3 (JSON, required fields: adapter, model, tokens_in, tokens_out, latency_ms, cost_usd, ts)
- ✓Never include content fields (prompt, completion, user input) in any signal payload
- ✓Tag all signals with the adapter slug (e.g. claudecode, cursor, windsurf) as defined in the adapter registry
Authentication
- ✓HMAC-SHA256 authenticate every hook emission using the session key from the license bundle
- ✓Include a Unix timestamp (ms precision) in each emission for replay-attack detection
- ✓Reject or ignore signals that arrive without valid HMAC or with a timestamp skew > 5 minutes
Transport
- ✓Transmit signals exclusively to forg.pro/engine/* (no direct subroute access)
- ✓Use TLS 1.2 or higher on all connections; refuse non-TLS transport
- ✓Do not batch signals older than 30 seconds; flush before session end
Hook lifecycle
- ✓Implement all seven event types: PostToolUse, PreCompact, PreToolUse, SessionEnd, SessionStart, Stop, UserPromptSubmit
- ✓Hook implementations must be idempotent — duplicate calls with the same timestamp are discarded
- ✓Declare _forg_managed on status-line injections to prevent double-injection conflicts
Versioning policy
Semantic versioning (major only).The protocol uses integer major versions (v1, v2, v3). Minor changes that don't break conforming adapters are incorporated without a version bump. Breaking changes (new required fields, removed fields, changed authentication requirements) require a new major version.
12-month minimum deprecation window. When a new major version ships, the previous version enters deprecated status. Deprecated versions continue to be accepted by the Rule Engine for a minimum of 12 months. At EOL, signals from deprecated adapters are rejected.
Announcement policy. Version announcements are sent to all active license holders 30 days before the deprecation clock starts and 90 days before EOL. Check the FORG changelog or subscribe to release notifications from your dashboard.
Version history & support schedule
Building a third-party adapter
Third-party adapter authors can test conformance against the FORG conformance test suite before publishing. The test suite is available in the FORG GitHub organization. To list your adapter in the FORG adapter registry, submit a PR to the registry repo with your adapter slug, schema version, and a link to the conformance test results.
All adapters in the registry must pass the automated conformance test on every PR. Adapters that fail conformance are automatically unlisted from the registry until they pass. UpgradIQ, Inc. does not endorse or guarantee the security of third-party adapters.