From af339b2da7b0b2b43af9d4d3ee8315dd5f247f0d Mon Sep 17 00:00:00 2001 From: Renato Date: Mon, 17 Aug 2026 11:38:00 +0200 Subject: [PATCH] docs: update multi-engine integration status --- README.md | 56 +++++++++++++++++++++++++++++- ROADMAP.md | 19 +++++++--- docs/getting-started/quickstart.md | 21 ++++++++++- docs/index.md | 2 ++ docs/integrations/overview.md | 6 ++++ site/index.html | 36 +++++++++++++++---- 6 files changed, 128 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 45e1084..d84ceb0 100644 --- a/README.md +++ b/README.md @@ -32,7 +32,22 @@ Open source · Local first · Provider neutral · Zero mandatory runtime depende MARGINAL does not assume that more calls are wasteful. Missing or ambiguous evidence fails open. -## Install for Codex +## Current integrations + +| Engine | Capability | Integration | +|---|---|---| +| **Codex** | **Tool Enforcement** | Native plugin. Shadow Mode by default; enforcement requires local Earned Enforcement evidence. | +| **Claude Code** | **Observe** | Native plugin using Claude Code hooks. Records engine-declared success/failure without changing the next model action. | +| **OpenCode** | **Observe** | In-process JavaScript plugin with a persistent stdio bridge to the provider-neutral runtime. | +| **PrivacyCode** | **Observe** | OpenCode-compatible install target with a distinct engine identity, ledger root, and trust evidence. | + +`Observe` integrations record evidence and recommendations but cannot block. A compatible install target +may share an adapter, but it never shares earned trust: **same adapter does not mean same enforcement +evidence**. + +## Native integrations + +### Codex Install the native plugin from the repository: @@ -61,6 +76,43 @@ marginal install codex --autopilot-consent Installation alone never enables enforcement. Earned Enforcement requires verified evidence and explicit promotion. +### Claude Code + +With the Python CLI installed: + +```bash +marginal install claude-code +marginal uninstall claude-code +``` + +Claude Code is **Observe-only** today. Its hooks expose separate success and failure events, so those +outcomes are engine-declared rather than inferred from tool output. + +### OpenCode + +```bash +marginal install opencode +marginal uninstall opencode +``` + +OpenCode is **Observe-only**. The JavaScript plugin runs in the engine process and communicates with one +long-running local MARGINAL bridge over stdio. Shell exit codes can prove shell success/failure; outcomes +without a reliable engine signal remain `unknown`. + +### PrivacyCode + +```bash +marginal install privacycode +marginal uninstall privacycode +``` + +PrivacyCode reuses the OpenCode plugin contract but keeps a distinct engine label, installation path, +ledger root, and evidence history. Compatibility is validated, not assumed permanently; a protocol +divergence requires a separate adapter. + +See the [integration overview](docs/integrations/overview.md), [Claude Code guide](docs/integrations/claude-code.md), +and [OpenCode / PrivacyCode guide](docs/integrations/opencode.md). + ## How Autopilot works 1. **Observe.** Hooks collect derived state, outcome, and coverage signals in Shadow Mode. @@ -200,6 +252,8 @@ evidence semantics. See the [architecture guide](docs/product/architecture.md). | Getting started | [Quickstart](docs/getting-started/quickstart.md) | | Product | [Concepts](docs/product/concepts.md) · [Architecture](docs/product/architecture.md) | | Codex | [Plugin guide](docs/integrations/codex.md) · [Benchmark readiness](docs/integrations/codex-benchmark-readiness.md) | +| Claude Code | [Observe plugin](docs/integrations/claude-code.md) | +| OpenCode / PrivacyCode | [Observe plugin and compatible targets](docs/integrations/opencode.md) | | Evaluation | [Benchmarking](docs/evaluation/benchmarking.md) · [Public benchmarks](docs/evaluation/public-benchmarks.md) | | Operations | [Privacy](docs/operations/privacy.md) · [Governance](docs/project/governance.md) | | Reference | [API](docs/reference/api.md) · [Roadmap](ROADMAP.md) | diff --git a/ROADMAP.md b/ROADMAP.md index 7e6acba..486a2a3 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -41,7 +41,7 @@ This roadmap is milestone-driven rather than date-driven. GitHub Issues and pull | **v0.2 — Learning Loop Foundation** | Complete | Universal protocol, non-blocking observation, versioned evidence, privacy and replay | | **Community hardening** | In progress | Governance tax, false-stop accounting, diminishing-return control and clearer evidence UX | | **v0.3 — Codex Reference Integration** | Validation | Native plugin, one-command install, Earned Enforcement, and measured smoke | -| **v0.4 — Multi-Engine Developer Preview** | Planned | Shared core across materially different coding agents | +| **v0.4 — Multi-Engine Developer Preview** | In progress | Codex, Claude Code and OpenCode-family surfaces sharing one governance core | | **v0.5 — One-Command Universal Installation** | Planned | Detection, installation, diagnostics and rollback across engines | | **v0.6 — Adaptive and Causal Allocation** | Planned | Calibrated learning, exploration and stronger identification strategies | | **v0.7 — Ecosystem and Operational Scale** | Planned | Persistence, observability, team controls and more engines | @@ -196,11 +196,22 @@ See [Codex benchmark readiness](docs/integrations/codex-benchmark-readiness.md). ## v0.4 — Multi-Engine Developer Preview -**Status:** Planned +**Status:** In progress + +The multi-engine layer is now real rather than roadmap-only: -Build OpenCode, Claude Code and GitHub Copilot integrations where official control surfaces permit them. Reuse the same protocol, policy, governance accounting, privacy boundaries and reports. Publish a capability matrix and label each engine as Observe, Tool Enforcement or Full Compute Enforcement. +- [x] Claude Code native plugin, labeled **Observe**, mapped through the engine-neutral hook core. +- [x] OpenCode plugin, labeled **Observe**, using one persistent stdio bridge for interleaved sessions. +- [x] PrivacyCode supported as an OpenCode-compatible target with separate engine identity and ledger state. +- [x] Keep economic policy in `UniversalRuntime`; adapters normalize native events and declare only capabilities they can prove. +- [x] Preserve fail-open behavior and record unavailable/unknown evidence instead of inventing measurements. +- [ ] Migrate older duplicated hook logic onto the shared integration core only after conformance coverage is sufficient. +- [ ] Add another materially different engine surface where its official API supports a defensible adapter. +- [ ] Publish cross-engine conformance and paired evidence before expanding enforcement claims. -**Exit criteria:** at least four environments pass protocol conformance; economic logic remains centralized; at least two integrations support real enforcement; each engine documents limitations and fail-open behavior. +**Exit criteria:** at least four environments pass protocol conformance; economic logic remains centralized; +at least two integrations support real enforcement backed by engine-specific Earned Enforcement evidence; +each engine documents outcome limits, privacy boundaries and fail-open behavior. --- diff --git a/docs/getting-started/quickstart.md b/docs/getting-started/quickstart.md index d95aa7e..ba25fa8 100644 --- a/docs/getting-started/quickstart.md +++ b/docs/getting-started/quickstart.md @@ -1,6 +1,25 @@ # Quickstart -## Install +## Native agent integrations + +MARGINAL starts conservatively. Codex installs in Shadow Mode before any earned tool enforcement; +Claude Code, OpenCode, and PrivacyCode are **Observe-only** and cannot block. + +```bash +# Codex native plugin +codex plugin marketplace add SignalLayerLabs/Marginal --ref main +codex plugin add marginal@marginal + +# With the MARGINAL Python CLI installed +marginal install claude-code +marginal install opencode +marginal install privacycode +``` + +Remove an integration with its matching uninstall command. See the +[integration overview](../integrations/overview.md) for capability and evidence limits. + +## Python library / development install ```bash python -m pip install -e ".[dev]" diff --git a/docs/index.md b/docs/index.md index 477ffc4..3cf6acf 100644 --- a/docs/index.md +++ b/docs/index.md @@ -16,6 +16,8 @@ MARGINAL documentation is organized by user intent instead of keeping every guid - [Integration overview](integrations/overview.md) - [Codex plugin](integrations/codex.md) +- [Claude Code plugin](integrations/claude-code.md) +- [OpenCode and PrivacyCode](integrations/opencode.md) - [Codex benchmark readiness](integrations/codex-benchmark-readiness.md) ## Evaluation and research diff --git a/docs/integrations/overview.md b/docs/integrations/overview.md index ce673a7..aa21ed5 100644 --- a/docs/integrations/overview.md +++ b/docs/integrations/overview.md @@ -85,6 +85,12 @@ child process over pipes. Its outcome evidence is weaker than Claude Code's: the exit code, most other tools prove nothing, and those outcomes stay `unknown`. See [OpenCode plugin](opencode.md). +PrivacyCode is an **Observe** install target for the same OpenCode adapter because its validated plugin +surface is currently compatible. It keeps a distinct engine label, configuration path, ledger root, and +evidence history. Target compatibility does not transfer Earned Enforcement authority: trust remains +engine-specific. If the plugin/event contract diverges, PrivacyCode becomes a separate adapter rather +than accumulating target-specific governance semantics. + GitHub Copilot remains roadmap work. Codex is labeled Tool Enforcement, not Full Compute Enforcement, because specialized and hosted tool paths can fall outside local hook coverage. diff --git a/site/index.html b/site/index.html index 26eaac7..bc6e18b 100644 --- a/site/index.html +++ b/site/index.html @@ -5,7 +5,7 @@ MARGINAL — Evidence-Driven Compute Governance for AI Agents - + @@ -29,6 +29,7 @@