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

1. Set Up Governance Rule Enable the governance rule in Cursor's settings to protect your workspace.
2. Block Secrets Exfiltration Agent attempts to read .env and write secrets — blocked instantly.	3. Block Credential Scanning Agent tries to search for credentials and secrets files — denied by policy.

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/

Governance Levels Explained

• 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	infrastructure-manager.policy.yaml	Infrastructure management agents handling IaC, deployments, and monitoring	16 tools

Validate any policy with: npx det-acp validate ./policy.yaml

---

Integration Modes

Mode	How It Works	Best For
MCP Proxy	Transparent proxy between agent and MCP servers	Cursor, Claude Code, any MCP client
Shell Proxy	Command wrapper that validates before executing	CLI agents, shell-based workflows
HTTP API	REST endpoints for session management	Any language, custom integrations
Library SDK	TypeScript API for in-process governance	Custom TypeScript agents

MCP Proxy (General)

Works with any MCP-compatible client.

Simplified mode — point at a policy file, auto-configures filesystem backend:

npx det-acp proxy --policy ./policy.yaml
npx det-acp proxy --policy ./policy.yaml --dir /path/to/project

Full config mode

For advanced setups with multiple backends, SSE transport, etc.:

cat > mcp-proxy.config.yaml << 'EOF'
policy: ./agent.policy.yaml
ledger_dir: ./.det-acp/ledgers
transport: stdio
backends:
  - name: filesystem
    transport: stdio
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem", "./src"]
EOF

npx det-acp proxy ./mcp-proxy.config.yaml

Shell Proxy

Execute commands through the policy gateway:

npx det-acp exec ./agent.policy.yaml echo "hello"    # Allowed
npx det-acp exec ./agent.policy.yaml rm -rf /tmp      # Denied (forbidden)

HTTP Session Server

npx det-acp serve --port 3100

HTTP API Examples

# Create a session
curl -X POST http://localhost:3100/sessions \
  -H "Content-Type: application/json" \
  -d '{"policy": "version: \"1.0\"\nname: test\ncapabilities:\n  - tool: file:read\n    scope:\n      paths: [\"./src/**\"]"}'

# Evaluate an action
curl -X POST http://localhost:3100/sessions/<session-id>/evaluate \
  -H "Content-Type: application/json" \
  -d '{"action": {"tool": "file:read", "input": {"path": "./src/index.ts"}}}'

# Record result
curl -X POST http://localhost:3100/sessions/<session-id>/record \
  -H "Content-Type: application/json" \
  -d '{"actionId": "<action-id>", "result": {"success": true, "output": "..."}}'

# Terminate session
curl -X POST http://localhost:3100/sessions/<session-id>/terminate

CLI Reference

npx det-acp init <agent>                  # Set up governance (cursor, codex, claude-code)
npx det-acp init <agent> --policy <file>  # Use custom policy
npx det-acp validate <policy-file>        # Validate a policy
npx det-acp proxy --policy <policy-file>  # Start MCP proxy (simplified)
npx det-acp proxy --policy <policy-file> --evolve  # With policy self-evolution
npx det-acp proxy <config-file>           # Start MCP proxy (full config)
npx det-acp exec <policy-file> <command>  # Execute via shell proxy
npx det-acp report <ledger-file>          # View audit report
npx det-acp serve [--port <port>]         # Start HTTP session server

---

Policy Self-Evolution

When an action is denied by the policy, the self-evolution feature can suggest a minimal policy change that would allow it, prompt you for a decision, and optionally update the policy (in memory and/or on disk). This keeps governance strict by default while letting you relax policy incrementally when you approve.

What it does

• Analyses denials — Pattern-matches denial reasons (missing capability, path/binary/domain outside scope, forbidden pattern) and produces a single, minimal policy edit.
• Prompts you — Presents the