Skip to content
Agentic Control Plane

Reference architecture

ACP is two pieces: a hook and a gateway. The hook lives in the agent harness and sends every tool call it is given to the gateway before the tool runs. The gateway records the call, applies the workspace’s rules, and returns a decision. The console shows the record.

The call path

agent harness
Claude Code, Codex, Cursor, …
→
hook
fires before the tool runs
→
gateway
record · classify · rules
→
decision
allow · flag · ask · deny
the tool
runs, or doesn't
→
console
the record · rules · approvals · export
Every call the hook is given is recorded and checked before it runs.

One request per tool call the hook sees. Nothing is sampled, and nothing is reconstructed after the fact.

Two limits apply. If the gateway is unreachable, the Claude Code plugin lets an interactive session’s call run, shows a loud UNGOVERNED banner, and the call is not recorded. Unattended tiers (subagent, background, api) fail closed. The shared hook other harnesses use fails open unless ACP_FAIL_MODE=closed or ~/.acp/failmode is set on that machine. New workspaces start in audit mode, so most calls are recorded and allowed until you turn on rules. Turning off hooks or using a harness’s bypass flags skips the hook. On Codex the hook sees shell commands only. Per-harness limits are on /coverage.

1. The hook

The hook uses the harness’s own pre-tool-call seam: PreToolUse in Claude Code, hooks.json in Cursor, codex_hooks in Codex, an in-process plugin where the harness has no shell hook. Harnesses covered today: Claude Code, Codex, Cursor, GitHub Copilot, opencode, Antigravity, dsh, Hermes, pi, Qwen Code, Muse Code, Prime Agent, Grok Build, OpenClaw (14). What each can enforce differs: the Codex hook, for example, sees shell commands only, and file edits need the MCP supplement. See /coverage. Each has a page under /controls that says exactly what the plugin registers and what the harness does on its own.

Before a tool runs, the hook sends the gateway the tool name and its arguments, the agent identity, the session, and the tier the agent is running under. Then it waits for the decision.

One command installs it:

curl -sf https://agenticcontrolplane.com/install.sh | bash

Add --local and the hook evaluates rules on the machine and never calls the gateway. Which harnesses support that is listed on install, explained.

2. The gateway

The hook calls one endpoint, POST /govern/tool-use. The gateway does three things, in order:

  1. Record. The call is written before anything else happens. A denied call is a row; so is an allowed one.
  2. Classify. The raw call is normalized to a name a rule can match: Bash.git, Write, notion.readPage. A shell command and an MCP tool get the same treatment.
  3. Decide. The workspace’s rules are matched against the classified tool and the agent’s tier, and one outcome comes back.

Tiers

Tier Who is running
interactive A person is at the terminal and can answer a prompt.
subagent Spawned by another agent. The person may never see its calls.
background Unattended: cron, CI, a long-running loop.
api Calls arriving with a workspace key and no session.

Rules are set per tool and per tier. rm -rf can be allowed for the person at the keyboard and denied for the background job.

Outcomes

Outcome What happens
allow The tool runs. The row is recorded.
flag The tool runs. The row is marked for review.
ask The tool waits for a person.
deny The tool does not run. The agent is told why and continues.

ask is the one that matters unattended. If someone is attending the session, the harness prompts them. If nobody is (a background tier, a subagent, a loop that has been running for an hour) the call does not run, and it appears in the console as a pending approval with the full arguments. Answer it there. Any row, including a pending approval, can be turned into a rule, so the second time is a decision you already made.

3. The record and the console

Each row carries the tool as called and as classified, the arguments, the agent and its tier, the rule that matched, the outcome, the session, and the timestamp. cloud.agenticcontrolplane.com shows it. From the console you filter the record, set a rule from any row, answer pending approvals, and export.

Where it runs

  • Cloud, the default. The gateway is api.agenticcontrolplane.com; the console is cloud.agenticcontrolplane.com. Free for small teams; see pricing.
  • Local. install.sh --local keeps rules on the machine. Nothing phones home.
  • Frameworks. For agents you write in code, the SDKs (pip install acp-crewai, npm i @agenticcontrolplane/governance) call the same endpoint from a decorator or a wrapper. See frameworks.
  • Model traffic. The proxy records LLM calls and cost per agent. It is a separate path from the tool-call hook. See cost tracking.

Packages and source

Harness plugins are published under @agenticcontrolplane/* on npm and as acp-* packages on PyPI. Source is one repo per harness under github.com/agentic-control-plane, MIT licensed. See community.

Get started → · Install, explained → · Controls by harness →

Running coding agents? ACP records each tool call its hook sees and makes the dangerous shell commands (a force-push, destructive SQL, curl | sh) wait for you. One command, free up to 5 agents:

macOS · Linux · WSL
curl -fsSL https://agenticcontrolplane.com/install.sh | bash
Windows · PowerShell
irm https://agenticcontrolplane.com/install.ps1 | iex

What the installer writes  ·  Getting started