Deterministic Agent Control Protocol

Self-Evolving Deterministic Agent Control Protocol

[](https://github.com/elliot35/deterministic-agent-control-protocol/stargazers) [](https://github.com/elliot35/deterministic-agent-control-protocol/network/members) [](https://github.com/elliot35/deterministic-agent-control-protocol/graphs/contributors) [](LICENSE) [](https://www.npmjs.com/package/@det-acp/core)

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.

1. Block Secrets Exfiltration

Agent attempts to read .env and write secrets — blocked instantly.

1. 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](#how-it-works)
• [Core Principles](#core-principles)
• [Quick Start](#quick-start)
• [Agent Integrations](#agent-integrations)
• [Built-in Policies](#built-in-policies)
• [Integration Modes](#integration-modes)
• [Policy Self-Evolution](#policy-self-evolution)
• [Architecture](#architecture)
• [Policy DSL Reference](#policy-dsl-reference)
• [Built-in Tool Adapters](#built-in-tool-adapters)
• [Custom Tool Adapters](#custom-tool-adapters)
• [Development](#development)
• [Contributing](#contributing)
• [License](#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/](integrations/cursor/) | | Codex CLI | MCP Proxy + AGENTS.md + OS Sandbox | Soft + Sandbox | [integrations/codex/](integrations/codex/) | | Claude Code | MCP Proxy + CLAUDE.md + settings.json | Soft + Semi-Hard | [integrations/claude-code/](integrations/claude-code/) | | OpenClaw | HTTP API + Skill + Docker Sandbox | Hard | [integrations/openclaw/](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)](#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](examples/coding-agent.policy.yaml) | AI coding agents operating on a project | 13 tools | | DevOps Deploy | [devops-deploy.policy.yaml](examples/devops-deploy.policy.yaml) | Deployment agents that build, test, and deploy code | 16 tools | | Video Upscaler | [video-upscaler.policy.yaml](examples/video-upscaler.policy.yaml) | Media processing agents running upscaling pipelines | 11 tools | | Data Analyst | [data-analyst.policy.yaml](examples/data-analyst.policy.yaml) | Data analysis agents processing datasets and generating reports | 12 tools | | Security Audit | [security-audit.policy.yaml](examples/security-audit.policy.yaml) | Security scanning agents auditing code and dependencies | 11 tools | | Infrastructure Manager | [infrastructure-manager.policy.yaml](examples/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 

### Shell Proxy

Execute commands through the policy gateway:

```bash
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//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//record \
  -H "Content-Type: application/json" \
  -d '{"actionId": "", "result": {"success": true, "output": "..."}}'

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

CLI Reference

npx det-acp init                   # Set up governance (cursor, codex, claude-code)
npx det-acp init  --policy   # Use custom policy
npx det-acp validate         # Validate a policy
npx det-acp proxy --policy   # Start MCP proxy (simplified)
npx det-acp proxy --policy  --evolve  # With policy self-evolution
npx det-acp proxy            # Start MCP proxy (full config)
npx det-acp exec    # Execute via shell proxy
npx det-acp report           # View audit report
npx det-acp serve [--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 suggestion (e.g. “Add file:read capability for path ./config/**?”) via the agent’s own chat UI.
• Three choices:
• Add to policy — Apply the change to the session’s policy and persist it to the policy YAML file.
• Allow once — Apply the change in memory only for the current session (no disk write).
• Deny — Keep the block; no change.
• Retry — After approval, the agent retries the original tool call against the updated policy.

Budget and session-limit denials (e.g. “Budget exceeded”, “Rate limit exceeded”) are not suggestible; only permission/scope/forbidden denials can trigger evolution.

How it works (MCP-native)

When running as an MCP proxy (the default for Cursor, Claude Code, and Codex), evolution uses a two-step asynchronous protocol built entirely on standard MCP tool calls — no terminal stdin/stdout required:

1. On deny: The proxy returns the denial to the agent with a structured suggestion and a unique suggestion_id.
2. On approve: The agent presents the suggestion to the user in chat, collects their decision, and calls policy_evolution_approve with the suggestion_id and decision.
3. On retry: The proxy applies the policy change. The agent retries the original tool call, which now succeeds.

sequenceDiagram
    participant User
    participant Agent as Agent (Cursor / Claude Code)
    participant Proxy as MCP Proxy
    participant GW as Gateway

    Agent->>Proxy: callTool("read_text_file", path)
    Proxy->>GW: evaluate()
    GW-->>Proxy: deny
    Proxy->>Proxy: suggestPolicyChange()
    Proxy-->>Agent: Denied + suggestion + suggestionId

    Agent->>User: "read_text_file denied. Add capability for path X?"
    User-->>Agent: "Yes, add to policy"

    Agent->>Proxy: callTool("policy_evolution_approve", suggestionId, "add-to-policy")
    Proxy->>Proxy: applyPolicyChange + writePolicyToFile
    Proxy-->>Agent: "Policy updated"

    Agent->>Proxy: callTool("read_text_file", path)
    Proxy->>GW: evaluate()
    GW-->>Proxy: allow
    Proxy-->>Agent: file contents

This works in every MCP client because it uses only the standard MCP tool-call protocol — no readline, no stdin conflicts.

Enabling self-evolution

MCP proxy (simplified mode):

npx det-acp proxy --policy ./policy.yaml --evolve

> The init command includes --evolve by default in generated MCP configurations.

Programmatic (library): pass policyEvolution in GatewayConfig for non-MCP setups (e.g. CLI scripts, custom agents):

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

const gateway = await AgentGateway.create({
  ledgerDir: './ledgers',
  policyEvolution: {
    policyPath: './agent.policy.yaml',
    handler: createCliEvolutionHandler(),
    timeoutMs: 30_000,
  },
});

You can plug a custom EvolutionHandler (e.g. GUI dialog, webhook) instead of createCliEvolutionHandler().

Evolution architecture (high level)

flowchart LR
    subgraph Denial["On Deny"]
        A["Action Denied"] --> B["Suggestion Engine"]
        B --> C{"Suggestible?"}
        C -->|No| D["Keep Deny"]
        C -->|Yes| E["PolicySuggestion + ID"]
    end
    E --> F["Agent presents to user"]
    F --> G{"User Decision"}
    G -->|Add to policy| H["policy_evolution_approve → Apply + Write YAML"]
    G -->|Allow once| I["policy_evolution_approve → Apply in-memory"]
    G -->|Deny| D
    H --> J["Retry original tool call"]
    I --> J
    J --> K{"Verdict"}
    K -->|allow| L["Proceed"]
    K -->|deny| D

The Suggestion Engine maps denial reasons to one of: add capability, widen scope (paths/binaries/domains/methods/repos), or remove a forbidden pattern. In MCP proxy mode, the MCP Evolution Handler returns the suggestio

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: elliot35
• Source: elliot35/deterministic-agent-control-protocol
• License: MIT
• Homepage: https://www.npmjs.com/package/@det-acp/core

Install and usage instructions live in the source repository linked above.