Host integrations and plugin adapters
ECC is a shared workflow layer for assistant hosts. It gives each supported host access to common engineering guidance and checks while adapting to the host's own plugin, event, and configuration rules.
Shared integration boundary
ECC keeps the workflow in shared assets and uses an adapter only where a host needs a different entry point. This lets hosts share the same skills, rules, commands, hooks, memory, and connector references without making each host a separate workflow system.
Canonical assets
Canonical assets define what ECC should do. A host integration defines how the host finds those assets and sends host events into ECC. The integration should change the edge contract, not copy or fork the shared workflow.
The boundary has four main rules:
- Keep durable workflow behavior in shared ECC assets.
- Translate host-specific event names, payloads, and limits at the edge.
- Keep unsupported host features visible instead of claiming full parity.
- Use the terminal path when a host has no matching runtime surface.
References: hooks/README.md• L20-25
Host capability states
ECC describes host support by the level of runtime enforcement that the host can provide. This state tells engineers what runs automatically and what still needs host action or review.
| State | Meaning |
|---|---|
| Native | ECC uses the host surface directly. |
| Adapter-backed | A thin adapter or plugin connects ECC to the host, but parity is incomplete. |
| Instruction-backed | ECC provides guidance and files, but the host lacks the runtime surface for full enforcement. |
| Reference-only | The host informs design but has no direct ECC adapter. |
These states describe a product boundary. They do not rank the quality of a host.
References: hooks/hooks.json• L1-17 hooks/hooks.metadata.json• L3-54
Host adaptation surfaces
Each host uses the strongest integration surface that it supports. Plugin assets handle discovery, native hook settings handle lifecycle events, and compatibility shims cover differences in names or payloads.
Plugin assets
Plugin assets are the install and discovery contract for hosts that support plugins. They expose shared workflow resources through the host's own loading rules and keep optional features behind an explicit host choice.
The Codex plugin manifest points the host to shared ECC skills and MCP configuration. It also supplies the host-facing product description and default prompts that steer users toward core workflows such as test-first work, security review, and verification. This gives Codex an installable entry point without moving the shared workflow into a Codex-only copy.
The plugins/…/plugin.json file provides experimental adapter metadata for Antigravity 2.0 and the agy CLI. Its description marks native acceptance as pending, so this package metadata is an adapter surface and does not claim full native host support.
Codex also has a native session-start adapter. It requires the host's PLUGIN_ROOT, maps that value to the shared ECC root, and starts the verified session bootstrap. The Claude hook profiles remain separate, so Codex receives its own session contract while shared session behavior remains reusable.
The Qoder adapter uses the host's QODER_PLUGIN_ROOT and invokes the same session bootstrap for startup, resume, clear, compact, and new-session events. Its host matcher and status message remain Qoder-specific, while the session behavior stays shared.
The plugin boundary separates these concerns:
- Resource discovery loads the shared ECC assets.
- Host metadata records how the host should treat those assets.
- Default prompts guide optional workflow use without replacing the shared assets.
- External connectors remain opt-in when they add tools or state.
See Plugin packaging and Aura integration for the plugin package and its external trust integration.
References: plugins/…/plugin.json• L1-12 plugins/…/plugin.json• L23-47 hooks/codex-hooks.json• L2-16 hooks/qoder-hooks.json• L2-18
Native hook configuration
Native hook configuration maps host lifecycle events to ECC checks and session behavior. The Claude hook graph covers tool use, prompt submission, context compaction, session start, post-tool failures, response stop, and session end through host-recognized event groups. Codex and Qoder add separate session-start contracts instead of changing the Claude profile.
The configuration keeps the host contract separate from the hook descriptions. hooks/hooks.json contains the entries that Claude Code accepts. hooks/hooks.metadata.json provides stable IDs, descriptions, and fingerprints for ECC tools that install, validate, or manage those entries. The two Claude files must stay aligned by event and index, while the checked-in hook configuration remains a plugin or repository contract rather than a file to paste into user settings.
The hook flow is:
- An assistant host emits a supported event.
- The adapter resolves the installed ECC root before it starts shared hook behavior.
- ECC applies its runtime profile and disabled-hook controls.
- The selected hook runs as a blocking check, warning, or background task according to the host event contract.
This diagram shows how host events reach shared ECC behavior while preserving host-specific blocking and async limits.
flowchart LR
A[Assistant host event] --> B[Native hook configuration]
B --> C[ECC root resolution]
C --> D[Profile and disable controls]
D --> E[Shared hook behavior]
E --> F[Block, warn, or continue]
Pre-tool hooks can block a tool call. Post-tool and lifecycle hooks inspect results or save state, and async hooks cannot block the main action. The host event contract therefore determines what ECC can enforce at each point.
The Hermes adapters show the same boundary in a different host model. The console-log observer reads a post-tool JSON event and warns through stderr without blocking. The config-protection guard reads a pre-tool event and returns a host decision that blocks edits to existing lint or format configuration files. Both fail open when their input is not usable so a broken observer does not stop the host.
See Hooks, memory, and host events for the wider event and persistence model.
References: hooks/README.md• L3-25 hooks/hooks.json• L3-19 hooks/hooks.json• L102-140 hooks/hooks.json• L144-184 hooks/hooks.json• L187-283 hooks/hooks.metadata.json• L3-154
Compatibility shims
Compatibility shims translate a host's input into the shared ECC contract. They should stay small because their purpose is access to shared behavior, not a second host-specific workflow.
The main shim patterns are:
- Mount shared skills, commands, and rules through a host's project or prompt model.
- Convert host event names and payloads before calling shared hook behavior.
- Return the host's expected warning or block format at the boundary.
- Limit the advertised capability state when the host cannot support a full event contract.
- Keep optional companion packages outside the core adapter boundary.
The same pattern supports hosts such as Cursor, Pi, Gemini, Zed, Codex, Qoder, and Hermes. Codex and Qoder use host-specific session entry points. Hermes uses host-native Python hooks for pre-tool and post-tool events. These differences do not change the shared ECC workflow model.
References: hooks/README.md• L3-15 hooks/README.md• L314-322 hooks/codex-hooks.json• L2-16 hooks/qoder-hooks.json• L2-18 hooks/…/check-console-log.py• L3-16 hooks/…/config-protection.py• L3-20
External integration boundary
External integrations extend a host without becoming part of ECC's core workflow state. MCP adds optional tool connections through a host configuration, while AURA supplies an optional trust signal for a caller-owned policy decision.
MCP connectors
MCP connectors provide optional access to external tools. A host must load each connector through its own configuration form, so connector activation remains separate from the shared ECC workflow.
The safe integration model is additive. Existing host settings remain user-owned, and a connector is not treated as active until the host accepts its configuration. This prevents a shared connector description from silently changing host behavior.
References: hooks/hooks.json• L41-89 hooks/hooks.metadata.json• L31-49 plugins/…/plugin.json• L23-24
AURA trust checks
AURA is an optional read-only check of a counterparty agent's past reputation. It returns a signal for the caller's policy layer; it does not approve actions, sign requests, hold keys, or replace action-risk checks.
The caller chooses when to use the signal and how to combine it with its own policy. AURA must therefore remain an external trust input rather than a host hook or an authorization system.
See Plugin packaging and Aura integration for the adapter boundary and trust model.
References: hooks/README.md• L20-25
Integration lifecycle
An integration starts with a host entry point and ends with host-visible behavior. The host owns discovery and event delivery. ECC owns the shared workflow and the checks that keep the boundary clear.
The lifecycle is:
- Select the host's plugin, native, or compatibility onramp.
- Load shared assets through the host-supported mechanism.
- Translate only host-specific event or tool names at the edge.
- Apply the host's blocking, warning, and async limits.
- Verify that the host can reach the installed ECC resources.
This diagram shows the path from a host event to shared ECC behavior and back to the host interface.
flowchart LR
A[Assistant host] --> B[Plugin or adapter]
B --> C[Shared ECC assets]
C --> D[Hook runner or workflow]
D --> E[Host-safe result]
E --> A
C -. optional .-> F[MCP connector]
C -. trust signal .-> G[AURA verdict]
The result is host-aware behavior rather than identical behavior. A host that lacks a lifecycle event can still load ECC guidance, but it must not claim the enforcement provided by a host with the full event surface.
References: hooks/README.md• L27-45 hooks/hooks.json• L3-19 hooks/codex-hooks.json• L2-16 hooks/qoder-hooks.json• L2-18
Change checklist
When these files or sections are changed, remember to consider these:
- Keep hooks/hooks.json and hooks/hooks.metadata.json aligned by event and index.
- When a Claude hook is reordered or its command changes, refresh its metadata fingerprint with the validation flow.
- When a host event or payload changes, review its blocking, warning, fail-open, and async contract before claiming support.
- Keep Codex and Qoder root variables mapped to an installed ECC location instead of a repository path.
- Keep plugin commands resolvable from the installed ECC root instead of relying on the repository path.
- When hook IDs or descriptions change, review installer and dashboard behavior that uses the metadata sidecar.
- When a plugin manifest changes, keep its shared-asset paths, MCP path, and host-facing defaults aligned with the install package.
- Keep experimental host metadata clear about native acceptance status and supported host scope.
- When a connector or trust signal changes, keep host configuration and caller-owned policy separate.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| hooks.json and its metadata sidecar drift | ECC tools can report the wrong hook ID or description, or validation rejects the plugin | Keep entries aligned and refresh fingerprints after changes. |
| A hook command cannot resolve the installed ECC root | The host starts the hook with the wrong files or skips the shared behavior | Resolve the plugin root at the host boundary. |
| A Codex or Qoder root variable is missing or points to an unusable install | Session bootstrap cannot reach shared ECC behavior | Require the host plugin root and keep the session adapter on the installed package path. |
| A blocking hook is placed on an event that cannot block | The check only warns or runs after the action, so the safety claim is false | Match the hook behavior to the host event contract. |
| An async hook is treated as a gate | The main tool action continues before the check finishes | Use async hooks only for background work. |
| A Hermes hook returns the wrong event format | The host ignores the warning or block decision | Keep stderr warnings and stdout decision JSON within the host hook contract. |
| A plugin manifest points to an unavailable shared asset or MCP path | The host installs the package but cannot discover the expected skills or connectors | Keep manifest paths valid from the installed plugin location. |
| Experimental adapter metadata is treated as native acceptance | Users expect Antigravity or agy CLI behavior that the host does not yet accept | Keep the pending acceptance status visible and limit the capability claim. |
| A host shim claims full event parity without the needed event surface | Users expect checks that the host cannot run | Keep the capability state and host documentation honest. |
| An external trust signal is treated as authorization | A past reputation result is mistaken for current action safety | Combine the signal with caller-owned policy and action-risk checks. |
Key files
| File | Why to read it |
|---|---|
| hooks/README.md | Explains the host event model, hook limits, install boundary, runtime profiles, and metadata contract. |
| hooks/hooks.json | Defines the native Claude hook event surface and installed-root entry points. |
| hooks/hooks.metadata.json | Defines stable hook identity, descriptions, and fingerprints used by ECC management tools. |
| hooks/codex-hooks.json | Defines the Codex session-start adapter and its installed plugin-root boundary. |
| hooks/qoder-hooks.json | Defines the Qoder session-start adapter and its host event matcher. |
| hooks/…/check-console-log.py | Shows a non-blocking Hermes post-tool observer with fail-open behavior. |
| hooks/…/config-protection.py | Shows a Hermes pre-tool guard that returns a host block decision. |
| plugins/…/plugin.json | Records the experimental Antigravity 2.0 and agy CLI adapter metadata and its pending native acceptance. |
| plugins/…/plugin.json | Defines the Codex plugin entry point for shared skills, MCP configuration, and host-facing workflow defaults. |
| docs/hooks-memory-and-host-events.md | Describes hook lifecycle, memory persistence, and host event behavior. |
| docs/plugin-packaging-and-aura-integration.md | Describes plugin packaging and the AURA integration boundary. |