opencode-semantic-anchors

Runtime steering plugin for opencode — enforces Semantic Anchors, contracts, and step confirmations via plugin hooks.

🇬🇧 English

What is it?

opencode-semantic-anchors is a plugin for the opencode AI coding agent that enforces behavioral contracts at runtime. It implements the Semantic Anchors methodology — a set of rules that keep AI agents focused, traceable, and safe.

The plugin monitors:

• Chat messages — checks every message against configured rules
• Tool execution — validates tool calls before they run
• Step confirmation — enforces step-by-step approval with configurable intervals

Features

• 📋 Contract System — Define contracts that BLOCK or WARN on specific patterns
• 🧩 Profile System — Built-in profiles (socratic, architecture) with role-based presets
• 🔍 Source Anchor Enforcement — Require URL-verifiable sources for claims (with requireSource)
• ⏭️ Override Mechanism — Emergency bypass with configurable maximum (default: 3 per session)
• 🛑 Step Confirmation — Automatic pause every N steps (configurable interval)
• 🔧 Three Built-in Tools — anchor-bypass, anchor-status, anchor-config-reload
• 🔄 Dynamic Role Switching — Contracts re-resolve on setRole() via ContractResolver
• 📦 Zod-Validated Config — Type-safe YAML configuration with full schema validation

Installation

npm install opencode-semantic-anchors

Then add it to your opencode.jsonc:

{
  "plugin": "opencode-semantic-anchors",
  "config": "path/to/opencode-semantic-anchors.yaml"
}

Quick Start

Create a config file opencode-semantic-anchors.yaml:

version: "1"
profiles:
  - socratic
contracts:
  - id: custom-rule
    mode: WARN
    description: "Agent must always cite its sources"
    triggers:
      - type: message
        pattern: "*"
        requireSource: true
    maxOverrides: 3

Built-in Profiles

| Profile | Description | Anchors | |---------|-------------|---------| | socratic | Basic source verification | Source Anchor, Intent Anchor, Verification Anchor | | architecture | Architecture decisions (⚠️ requires separate PR) | ADR format, Boundary Anchor, Stakeholder Anchor |

Profiles can be combined. Use roleProfiles to assign profiles per role:

roleProfiles:
  developer: ["socratic"]
  architect: ["socratic", "architecture"]

Contracts

A contract defines what the agent must (or must not) do:

| Field | Description | |-------|-------------| | id | Unique identifier | | mode | BLOCK (hard stop) or WARN (soft reminder) | | description | What the contract enforces | | triggers | Patterns that activate the contract | | maxOverrides | How many bypasses allowed per contract |

Tools

The plugin registers three tools in opencode:

| Tool | Description | |------|-------------| | anchor-bypass | Temporarily bypass a blocked contract | | anchor-status | Show active contracts, counters, and current role | | anchor-config-reload | Reload configuration without restart |

Step Confirmation

Every N tool calls (default: 3), the plugin pauses and asks for confirmation before proceeding. Set settings.stepConfirmationInterval to adjust.

Override Mechanism

When a contract blocks an action, the agent can request a one-time override via anchor-bypass. The override counter resets when contracts are reloaded. Maximum overrides per contract is configurable (default: 3).

🇩🇪 Deutsch

Was ist das?

opencode-semantic-anchors ist ein Plugin für den opencode KI-Coding-Agenten, das Verhaltensverträge (Contracts) zur Laufzeit durchsetzt. Es implementiert die Semantic Anchors Methodik — ein Regelwerk, das KI-Agenten fokussiert, nachvollziehbar und sicher hält.

Das Plugin überwacht:

• Chat-Nachrichten — prüft jede Nachricht gegen konfigurierte Regeln
• Tool-Ausführung — validiert Tool-Aufrufe bevor sie ausgeführt werden
• Schritt-Bestätigung — erzwingt schrittweise Freigabe mit konfigurierbaren Intervallen

Funktionen

• 📋 Vertragssystem — Definiere Contracts, die bestimmte Muster BLOCKieren oder WARNen
• 🧩 Profilsystem — Vorgefertigte Profile (socratic, architecture) mit rollenbasierten Presets
• 🔍 Source Anchor Enforcement — Erzwinge URL-überprüfbare Quellenangaben (mit requireSource)
• ⏭️ Override-Mechanismus — Notfall-Bypass mit konfigurierbarem Maximum (Standard: 3 pro Session)
• 🛑 Schritt-Bestätigung — Automatische Pause alle N Schritte (konfigurierbares Intervall)
• 🔧 Drei Built-in-Tools — anchor-bypass, anchor-status, anchor-config-reload
• 🔄 Dynamischer Rollenwechsel — Contracts werden bei setRole() via ContractResolver neu aufgelöst
• 📦 Zod-validierte Config — Typsichere YAML-Konfiguration mit vollständiger Schema-Validierung

Installation

npm install opencode-semantic-anchors

Danach in der opencode.jsonc einbinden:

{
  "plugin": "opencode-semantic-anchors",
  "config": "path/to/opencode-semantic-anchors.yaml"
}

Schnellstart

Erstelle eine Konfigurationsdatei opencode-semantic-anchors.yaml:

version: "1"
profiles:
  - socratic
contracts:
  - id: custom-rule
    mode: WARN
    description: "Agent muss immer seine Quellen angeben"
    triggers:
      - type: message
        pattern: "*"
        requireSource: true
    maxOverrides: 3

Vorgefertigte Profile

| Profil | Beschreibung | Anchors | |--------|-------------|---------| | socratic | Basis-Quellenprüfung | Source Anchor, Intent Anchor, Verification Anchor | | architecture | Architekturentscheidungen (⚠️ erfordert separaten PR) | ADR-Format, Boundary Anchor, Stakeholder Anchor |

Profile können kombiniert werden. Mit roleProfiles lassen sich Profile pro Rolle zuweisen:

roleProfiles:
  developer: ["socratic"]
  architect: ["socratic", "architecture"]

Contracts (Verträge)

Ein Contract definiert, was der Agent tun (oder nicht tun) darf:

| Feld | Beschreibung | |------|-------------| | id | Eindeutige Kennung | | mode | BLOCK (hartes Stopp) oder WARN (weiche Erinnerung) | | description | Was der Contract durchsetzt | | triggers | Muster, die den Contract aktivieren | | maxOverrides | Wie viele Bypässe pro Contract erlaubt sind |

Tools

Das Plugin registriert drei Tools in opencode:

| Tool | Beschreibung | |------|-------------| | anchor-bypass | Temporär einen blockierten Contract umgehen | | anchor-status | Aktive Contracts, Zähler und aktuelle Rolle anzeigen | | anchor-config-reload | Konfiguration ohne Neustart neu laden |

Schritt-Bestätigung

Alle N Tool-Aufrufe (Standard: 3) pausiert das Plugin und fragt nach Bestätigung. Einstellbar über settings.stepConfirmationInterval.

Override-Mechanismus

Wenn ein Contract eine Aktion blockiert, kann der Agent einen einmaligen Override via anchor-bypass anfordern. Der Override-Zähler wird beim Neuladen der Contracts zurückgesetzt. Die maximale Anzahl Overrides pro Contract ist konfigurierbar (Standard: 3).

📚 Documentation

Full documentation, including the arc42 architecture documentation, is available in the docs/ directory.

🤝 Contributing

Contributions are welcome! Please read CONTRIBUTING.md and the Code of Conduct.

Security issues — please report via GitHub Private Vulnerability Reporting (see SECURITY.md).

📄 License

Apache-2.0 — see LICENSE.