Self-Evolving Deterministic Agent Control Protocol

A governance gateway for AI agents — making every action bounded, auditable, reversible, and explainable.

Works transparently with Cursor, Claude Code, Codex, and any MCP-compatible agent. Also supports shell command governance and a language-agnostic HTTP API.

🛡️ Governance in Action

https://github.com/user-attachments/assets/ec7a9524-1527-4e51-b837-7e05a24b189d

Table of Contents

• How It Works
• Core Principles
• Quick Start
• Agent Integrations
• Built-in Policies
• Integration Modes
• Policy Self-Evolution
• Architecture
• Policy DSL Reference
• Built-in Tool Adapters
• Custom Tool Adapters
• Development
• Contributing
• License

How It Works

Agents never execute tools directly. Every action flows through the control plane for evaluation, enforcement, and audit:

flowchart LR
    A["Agent"] -->|"action request"| CP["Control Protocol"]
    CP -->|"evaluate against policy"| D{"Decision"}
    D -->|"allow"| E["Agent Executes Action"]
    D -->|"deny"| F["Blocked + Reason Logged"]
    D -->|"gate"| G["Human Approval Required"]
    E -->|"record result"| L["Evidence Ledger"]
    G -->|"approved"| E

The protocol does not execute actions itself. It evaluates them against a policy, enforces session-level budgets, requires human approval for risky operations, and records everything in a tamper-evident audit ledger.

Core Principles

| Principle | Description | | ----------------------- | ------------------------------------------------------------------------- | | Bounded | Agents can only perform allowed actions within allowed scopes | | Session-Aware | Budget, rate limits, and escalation rules across the full interaction | | Auditable | Every action logged in a tamper-evident ledger with SHA-256 hash chaining | | Reversible | Compensation plans for undoing executed actions | | Explainable | Full reporting — what was allowed, denied, gated, and why |

Quick Start

Install

npm i @det-acp/core

Set Up Governance (One Command)

npx det-acp init cursor        # Cursor
npx det-acp init codex         # Codex CLI
npx det-acp init claude-code   # Claude Code

This generates all required files (policy, MCP config, governance rules) with sensible defaults. Edit policy.yaml to customize — everything else is handled automatically.

# Use your own policy instead of the default
npx det-acp init cursor --policy ./my-policy.yaml

After running init, restart your agent to pick up the MCP server.

Define a Policy

Create agent.policy.yaml:

version: "1.0"
name: "my-agent"

capabilities:
  - tool: "file:read"
    scope:
      paths: ["./src/**"]
  - tool: "file:write"
    scope:
      paths: ["./src/**"]
  - tool: "command:run"
    scope:
      binaries: ["npm", "node", "tsc"]

limits:
  max_runtime_ms: 1800000
  max_files_changed: 50

gates:
  - action: "file:delete"
    approval: "human"
    risk_level: "high"

evidence:
  require: ["checksums", "diffs"]
  format: "jsonl"

forbidden:
  - pattern: "**/.env"
  - pattern: "rm -rf"

session:
  max_actions: 100
  max_denials: 10
  rate_limit:
    max_per_minute: 30
  escalation:
    - after_actions: 50
      require: human_checkin
    - after_minutes: 15
      require: human_checkin

Use as a Library

import { AgentGateway } from '@det-acp/core';

const gateway = await AgentGateway.create({
  ledgerDir: './ledgers',
  onStateChange: (sessionId, from, to) => console.log(`${from} -> ${to}`),
});

// Create a session
const session = await gateway.createSession('./agent.policy.yaml', {
  agent: 'my-coding-agent',
});

// Evaluate an action (does NOT execute it)
const verdict = await gateway.evaluate(session.id, {
  tool: 'file:read',
  input: { path: './src/index.ts' },
});

if (verdict.decision === 'allow') {
  // Execute the action yourself
  const content = fs.readFileSync('./src/index.ts', 'utf-8');

  // Record the result
  await gateway.recordResult(session.id, verdict.actionId, {
    success: true,
    output: content,
    durationMs: 5,
  });
}

// Terminate and get report
const report = await gateway.terminateSession(session.id, 'task complete');
console.log(`Allowed: ${report.allowed}, Denied: ${report.denied}`);

Agent Integrations

Ready-to-use guides for popular AI agents. Each integration includes policy, config templates, governance rules, test sandbox, and step-by-step instructions.

| Agent | Integration Mode | Governance Level | Guide | | --------------------- | ------------------------------------- | ---------------- | --------------------------------------------------- | | Cursor | MCP Proxy + Cursor Rules | Soft | integrations/cursor/ | | Codex CLI | MCP Proxy + AGENTS.md + OS Sandbox | Soft + Sandbox | integrations/codex/ | | Claude Code | MCP Proxy + CLAUDE.md + settings.json | Soft + Semi-Hard | integrations/claude-code/ | | OpenClaw | HTTP API + Skill + Docker Sandbox | Hard | integrations/openclaw/ |

• Soft — The LLM is instructed (via rules/instructions files) to prefer governed tools. Effective in practice, but a creative prompt could theoretically bypass it.
• Semi-Hard — Soft instructions combined with the agent's built-in permission system that can deny direct tool access (e.g., Claude Code's settings.json).
• Hard — The agent physically cannot access tools outside the governance layer. Achieved via Docker sandboxing, tool allow/deny lists, or custom agent harnesses.

For any MCP-compatible agent not listed above, see MCP Proxy (General).

Built-in Policies

Production-ready policies in examples/ — usable out of the box:

| Policy | File | Use Case | Tools Used | | ---------------------- | ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------- | ---------- | | Coding Agent | coding-agent.policy.yaml | AI coding agents operating on a project | 13 tools | | DevOps Deploy | devops-deploy.policy.yaml | Deployment agents that build, test, and deploy code | 16 tools | | Video Upscaler | video-upscaler.policy.yaml | Media processing agents running upscaling pipelines | 11 tools | | Data Analyst | data-analyst.policy.yaml | Data analysis agents processing datasets and generating reports | 12 tools | | Security Audit | security-audit.policy.yaml | Security scanning agents auditing code and dependencies | 11 tools | | Infrastructure Manager | [`