How Coco enforces
Follow one tool call from the model's proposal through rules, the classifier, the verdict, and the record.
Follow one tool call from the model's proposal to the recorded decision.
Coco decides every tool call an agent proposes, before the call runs, in code the model doesn't control. The decision has two layers:
- Rules decide first. Contracts compiled from your own policies run as plain logic against facts from your systems of record. No model is involved, so the same call always gets the same verdict and an auditor can replay it.
- A classifier can add judgement. It's optional, and handles what rules can't reach, such as whether the user asked for this at all. It can raise a verdict but never lower one.
For the evidence behind this order, see Results.
Where the check sits
A model never executes anything. It proposes a tool call, and the framework executes it. Coco sits between the two:
model proposes a call ──▶ CocoGuard ──▶ engine: select contracts, run rules, (classifier) ──▶ verdict
│ │
◀──────────── run / deny with the reason / pause for a person ◀┘
│
receipt, hash-chained| Runtime | Interception point |
|---|---|
| coco-framework, LangChain, LangGraph | wrap_tool_call(request, handler). The tool runs only if CocoGuard calls handler. |
| Claude Code | The PreToolUse hook, before Claude Code's own permission prompt. |
| Anything else | POST /v1/check to the gate, before the application runs the tool. |
How rules decide
A contract governs one action, such as payments.send. It holds checks, and each check is a rule that must hold, with the verdict to apply when it doesn't:
- id: amount_within_auto_limit
check: 'args.amount <= limits.auto_release_limit'
on_fail: ESCALATEContracts are compiled from policy documents, each citing its clause. They move from draft to testing (recorded, never enforced) to live.
A rule reads the call, plus facts nobody in the conversation supplied:
| Name | Contents | Comes from |
|---|---|---|
args | The arguments the model proposed. | The call. |
state | Account status, approved payees, and customer records. | Your systems of record, through a callback. Never the model. |
session | What already ran in this conversation: counts and running totals. | Coco's ledger. |
limits | The project's numbers. | coco.yaml or the platform. |
action, agent | The action and the agent's identity. | The guard. |
Before a rule runs, Coco parses it and checks it against an allowlist: comparisons, and, or, not, arithmetic, literals, field reads, and a few pure functions such as matches and lower. Nothing else can run. Coco then works in a fixed order:
- An escalation already open for this call answers first.
- Contracts are selected by action, then by
applies_when. prechecks run. A failedprecheck at DENY skips the rest.- Constraints run.
- If no rule denied, judge checks go to the classifier.
- The most severe verdict among live contracts wins: DENY, then ESCALATE, then OBSERVE, then AUTO_EXECUTE.
- The mode turns the verdict into an effect, and the receipt is written.
Verdicts and modes
A verdict is what the contracts decided. An effect is what happens to the call. The mode turns one into the other:
| Verdict | In Monitor | In Enforce |
|---|---|---|
| AUTO_EXECUTE | Runs. | Runs. |
| OBSERVE | Runs, and the receipt is flagged. | Runs, and the receipt is flagged. |
| ESCALATE | Runs, recorded as "would escalate". | Pauses until a person decides. |
| DENY | Runs, recorded as "would deny". | Doesn't run. The model receives the reason. |
The receipt always holds the verdict, so a week in Monitor is a truthful account of what Enforce would have stopped. New projects start in Monitor, so installing Coco breaks nothing on day one.
Good to know: The older names ALLOW and BLOCK are still accepted as aliases of AUTO_EXECUTE and DENY.
Fail closed
An engine that can't decide denies. A field the call lacks reads as null, comparing a number against null is an error, and an error is DENY.
| What fails | Verdict | In Enforce | In Monitor |
|---|---|---|---|
| The gate is unreachable, late, or answers with an error | DENY | The call stops. | The call runs, and the reason says the gate wasn't reached. |
| The in-process engine raises | DENY | The call stops. | The call runs, recorded as "would deny". |
| A rule raises, or compares a missing field | DENY | The call stops. | The call runs, recorded as "would deny". |
| The classifier fails or answers late | The check's on_error, ESCALATE by default | The call waits for a person. | The call runs. |
fail_open in Python and failOpen in TypeScript let a call run when Coco is unreachable or the engine raises. Neither changes a rule's own error, which stays DENY.
Escalations
An ESCALATE in Enforce pauses the agent's graph and opens an escalation, such as ESC-001. A person approves it, or rejects it with a reason. The guard reads the decision from Coco's record, never from the message that resumes the graph, so neither the agent nor the application can forge an approval. An agent with no way to pause gets DENY.
The record
Every decision writes a receipt: the call, the facts it was judged against, every check with its observed value, the verdict, and the effect. The ledger is the sequence of receipts, each carrying the hash of the one before it. coco verify walks the chain. On the gate, each project has its own chain.
Keep in mind: Receipts are hash-chained, not signed. Signing isn't built.
The classifier
A judge check asks coco-classifier a yes or no question, phrased so yes means the check fails. For example: does this call serve a goal the user did not set?
- When it runs: After the rules, and only when no rule denied. It only raises a verdict.
- How it's isolated: It's a separate model in its own server, and the agent's prompt never reaches it. The call and the conversation go in as quoted evidence, the question comes from the contract, and no text is generated.
- How it answers: Coco reads the probabilities of the two options, and a threshold turns them into ESCALATE or DENY.
- When it fails: A classifier that fails or answers late gives ESCALATE.
Use it for what rules can't see: a permitted action the user never asked for, and policy written in prose. Never use it for a hard limit. On the payment corpus, the classifier alone let refused transfers through where a rule stopped every one.
Keep in mind: The hosted gate has no classifier today, so on a connected project each judge check takes its on_error verdict.
Tools no contract governs
With ungoverned: impact, a tool that only reads runs, and a tool that changes something outside the conversation escalates. A tool declares its impact with metadata["coco_impact"]. Otherwise, the classifier is asked once per tool definition. An impact nobody establishes escalates.
How independent the check is
- From the model: Complete. The model proposes, the check is code at the execution boundary, and the rules, facts, and record are out of its reach.
- From the application: With the gate. In process, the guard is part of your application, and whoever owns that code owns the guard. The hosted gate is a separate service with its own keys, contracts, and record, so the agent's host can't change a rule or a receipt.