interlock-mcp

A human-in-the-loop governance interlock for AI agents (MCP server). Agents propose changes; a human countersigns the exact plan; only then does it execute — stage by stage, precondition-checked against live state, verified, and audited. Bring your own executors.

An interlock is a safety mechanism that prevents an action until every required condition is engaged. Nothing here actuates unless the plan validates, a human countersigns those exact bytes, and the live preconditions still hold.

---

Why this exists

Most ways of letting an agent change real systems fall into two camps, and neither is safe enough for infrastructure:

• Direct-execute tool servers (docker/shell/k8s MCPs) hand the model the keys — it plans and applies in one step. No review, no verification, no audit.
• Synchronous human-in-the-loop (elicitation, approval dialogs) pauses a single tool call to ask right now, in-session. That doesn't fit changes a human should review out-of-band, minutes or hours later, from a different surface.

Interlock is the missing envelope: an asynchronous, hash-bound, human-countersigned, precondition-checked, verified, audited path from agent intent to real change. The agent never holds the keys; it holds a proposal.

The loop

   sequenceDiagram
    participant A as agent
    participant IC as interlock core
    participant H as human
    participant W as world
    A ->> IC: propose(body)
    Note right of IC: validate (schema + invariants) <br/> hash (RFC-8785 JCS)
    IC ->> A: plan_id
    Note right of IC: store as PROPOSED (held)
    H ->> IC: review + countersign
    Note right of H: interlock approve
    Note over H,IC: bind (schema_version, hash)
    A ->> IC: execute(plan_id)
    Note right of A: re-validate + release gate <br/> per stage:
    activate IC
    IC ->> W: preconditions vs LIVE state ---- probe
    IC ->> W: dispatch (adapter) ---- execute
    IC ->> W: verify post-conditions ---- probe
    deactivate IC
    IC -x IC: halt-and-audit on any failure
    Note right of IC: append to hash-chained audit

Guarantees

• Hash-bound approval. An approval binds (schema_version, plan_hash) to the exact bytes reviewed. Edit the body afterward and the approval is void (tamper-evident).
• One-shot & time-boxed. An approved plan runs once; a stale approval expires.
• Fail-closed preconditions. A stage's preconditions are re-checked against live ground truth immediately before dispatch. Unmet — or unprobeable — halts with nothing dispatched.
• Forward-only. On any failure it halts and records what committed; no surprise auto-rollback. Remediation is a new plan.
• Tamper-evident audit. Every decision is appended to a hash-chained log; interlock verify-audit detects any edit, reorder, or drop.
• Reproducible hashing. RFC-8785 JCS over a YAML-1.2 value model — no on/off→bool coercion, no source-text hashing. Any re-implementation must reproduce the pinned vector.

Quickstart

pip install interlock-mcp            # or: pip install "interlock-mcp[server]" for the MCP server

# run the dependency-free demo (propose -> approve -> execute -> verify a file write)
python examples/filesystem_demo.py

Embed it in a few lines — implement two adapters for your world and the core does the rest:

from interlock.engine import Interlock
from interlock.policy import Policy, registry
from interlock.approval import FileStore
from interlock.audit import FileAuditSink

engine = Interlock(
    policy=Policy(action_registry=registry(mutating=["restart_service"])),
    store=FileStore("./plans"), audit=FileAuditSink("./audit.jsonl"),
    executor=MyExecutor(),   # .execute(action, params, target) -> ExecResult
    prober=MyProber(),       # .probe(check, probe) -> ProbeResult  (read-only)
    ttl_seconds=72 * 3600,
)

The agent talks to the MCP server (propose_plan, get_plan, list_plans, execute_plan). A human reviews on a separate channel:

interlock list --status proposed
interlock approve <plan_id> --by alice --reason "reviewed"
interlock verify-audit ./audit.jsonl

Security model (in one sentence)

The proposer and the approver are different surfaces: the agent's MCP tools can propose and execute, but cannot approve — approval is a human action on the CLI/admin channel, so nothing the model can call flips a plan to approved. Details in docs/THREAT-MODEL.md.

Concepts

Piece	What it is
Plan	An envelope + a hashed body of ordered stages (action, target, typed preconditions, verify, rollback). Actions are opaque to the core.
Policy	Your deployment's domain knowledge: which actions mutate, which actions/targets are forbidden, what a secret looks like — plus (optionally) your schema extension and custom invariants. Not baked into the schema.
Invariants	Seven universal checks the validator enforces (schema, hash-recompute, unique ids + known actions, mutating→rollback, mutating→preconditions, no-forbidden, no-secrets) — plus any CustomInvariants your Policy adds.
Adapters	Two small protocols — ExecutorAdapter.execute(...) and ProbeAdapter.probe(...) — the only place your infrastructure appears.
Extensions	Carry your own plan fields (SchemaExtension) and validation rules (CustomInvariant) on the Policy — the core stays domain-agnostic; you declare your extras without forking it. See docs/SCHEMA.md.

See docs/SCHEMA.md, docs/PROTOCOL.md, and docs/THREAT-MODEL.md.

Status

Alpha (0.2). The deterministic core (hashing, schema, validator, precondition engine) and the approval/audit/executor layer are covered by an adversarial test suite. 0.2 adds the two extension seams (SchemaExtension, CustomInvariant) so a deployment carries its own plan fields and validation rules without forking the core. APIs may shift before 1.0. Issues and review welcome.

License

Apache-2.0 © Zigerus. See LICENSE and NOTICE.