Architecture
See what Coco is built to do, the parts that do it, how data moves between them, and the decisions behind the design.
See the parts of Coco, how data moves between them, and the decisions behind the design.
An AI agent acts by proposing tool calls. A system prompt asks it to follow your rules, but nothing in a prompt stops a call. Regulated teams also need to show, afterwards, why each action was allowed.
Goals
Coco is built to:
- Decide every tool call before it runs, in code the model doesn't control.
- Decide facts deterministically, so a decision replays exactly.
- Derive the rules from your own documents, each citing its clause.
- Keep a tamper-evident record of every decision.
- Start without breaking anything, then tighten when you're ready.
- Work in any runtime.
Coco doesn't replace a bank's or provider's own checks, run identity or screening checks itself, or measure whether an agent completes its task.
High-level design
flowchart LR
subgraph app["Your application"]
model["Model"] -->|proposes a tool call| guard["CocoGuard, CocoEnforcer or hook"]
records["Systems of record"] -->|facts, through a callback| guard
guard -->|allowed| tool["Tool"]
end
guard -->|in process| engine["Engine and local ledger"]
guard -->|"POST /v1/check"| gate["Hosted gate"]
gate --> chain[("Receipts, hash-chained per project")]
gate --> dashboard["Dashboard: Audit Logs, Escalations, Contracts"]
gate -.->|judge checks| classifier["coco-classifier"]
engine -.->|judge checks| classifier
docs["Policy documents"] --> service["Document service or local pipeline"]
service --> compiler["Compiler"]
compiler --> drafts["Draft contracts, each citing its clause"]
drafts -->|a person activates| engine
drafts -->|a person activates| gateThe parts
| Part | Location | What it does |
|---|---|---|
| Engine | python/coco_sdk/engine/ | Contracts, the rule language, judge checks, verdicts, and the SQLite ledger. |
CocoGuard | python/coco_sdk/guard.py | Middleware on the agent's tool-call seam, with one body for coco-framework and upstream LangChain. |
RemoteEngine | python/coco_sdk/remote.py | The Engine's surface, with the gate deciding over HTTP. |
| Project and CLI | python/coco_sdk/project.py, cli.py | coco.yaml and the coco command. |
| Compiler | python/coco_sdk/compile/ | Canonical policy to draft contracts and boundary cases. |
| Claude Code hook | python/coco_sdk/hooks/, cli/ | A PreToolUse hook and its installer. |
| TypeScript client | js/ | CocoEnforcer, which always asks the gate. |
| Gate | gate/ | The engine behind HTTP, a record per project, and the SDK's package index. |
| Document service | policy/ | Documents to AI-ready context, canonical policy, and draft contracts. |
| Evaluation | python/coco_sdk/evaluate/, bench/ | Replays labelled calls through the engine and scores each decision. |
Three more repositories supply the rest: coco-framework (the agent runtime), coco-classifier (the model behind judge checks), and coco-policy-generation-pipeline (documents to context and canonical policy).
Data flow
One tool call
sequenceDiagram
participant M as Model
participant G as CocoGuard
participant S as Your systems
participant E as Engine or gate
participant T as Tool
M->>G: propose send_payment(amount, payee)
G->>S: state provider(action, args)
S-->>G: facts
G->>E: check(action, args, state, session)
E->>E: select contracts, run rules, ask the classifier
E->>E: write the receipt, chained to the last
E-->>G: verdict, effect, reason, receipt
alt effect is run
G->>T: call the tool
T-->>M: result
else effect is deny
G-->>M: Coco denied this action, with the reason
else effect is escalate
G->>G: pause the graph
endEach decision runs in one transaction, from reading the session to writing the receipt. Parallel calls can't fork the chain or pass a ceiling together.
An escalation
sequenceDiagram
participant A as Agent
participant C as Coco
participant P as Person
participant App as Your application
A->>C: check, verdict ESCALATE
C-->>A: pause on ESC-001
P->>C: approve or reject, with a reason
C->>C: write the decision to the chain
C-->>App: optional webhook, escalation_decided
App->>A: resume the same thread
A->>C: read ESC-001 from the record
C-->>A: the tool runs if approved, the model gets the reason if rejectedA policy document to a live contract
- A person adds a PDF or DOCX to
policies/, or uploads it on the dashboard. - The pipeline reads the document into AI-ready context, builds a search index, and extracts each rule with its clause.
- The compiler groups rules into draft contracts, one per action, and writes boundary cases.
- A person reviews each draft against the document, confirms how the policy's words map to the tool's arguments, and settles any review issues.
- The contract goes to testing or live. Nothing is enforced until a person activates it.
Key decisions and trade-offs
| Decision | Why | What it costs |
|---|---|---|
| Rules decide before any model | Facts must replay exactly. On the payment corpus, the classifier alone let 454 refused transfers through where rules stopped every one. | Rules stop only what their facts reach. |
| The classifier can only raise a verdict | A model must never be able to loosen policy. | Calls held for a person. |
| Fail closed | A control that disappears under failure is no control. | A gate outage stops calls in Enforce, unless fail_open is set. |
| Monitor is the default | You see real verdicts before anything is blocked. | Nothing is stopped until someone promotes the project. |
| Facts come through a callback | A model must not assert the facts that judge it. | The application has to supply them. |
| A decision is read from the record | Neither the agent nor the application can forge an approval. | Resuming needs a checkpointer and the record. |
| One Engine surface, in process or remote | Connecting a project to the gate changes one object and no code. | The remote client supports only what a key may do. |
| The gate is a separate service | The agent's host can't change a rule or a receipt. | A network round trip per call, not yet measured. |
| Receipts are hash-chained, not signed | Editing an earlier receipt breaks the chain. | The chain shows tampering only to someone checking it. |
| One chain per project, one writer at a time | The chain never forks, and two calls can't pass a ceiling at once. | Decisions within one project are serialised. |
| Documents are deleted once pulled | The service should hold a policy no longer than it needs to. | Reprocessing means uploading again, unless you use --keep. |
| Every draft waits for a person | A model reads the document, so its output varies between runs. | Someone has to review before anything goes live. |
| The agent runtime is a renamed fork | Imports and tracing stay under Coco's control, and the tracer sends nothing. | The fork has to track upstream. |
Integration points
| Point | Direction | Shape |
|---|---|---|
| Tool-call middleware | Framework to guard. | wrap_tool_call and awrap_tool_call on create_agent. |
| PreToolUse hook | Claude Code to hook. | One tool call on stdin, a permission decision on stdout. |
| HTTP check | Any runtime to the gate. | POST /v1/check with a project key. |
| State provider | Guard to your systems. | A callable, (action, args) to a dictionary. |
| Escalation webhook | Gate to your application. | POST of {"type": "escalation_decided", "project", "escalation"} to the project's webhook URL. |
| Classifier | Engine to coco-classifier. | POST /v1/classify. |
| Document service | CLI or dashboard to the service. | Register, signed upload, complete, poll, and pull. |
| Package index | uv to the gate. | A PEP 503 simple index at /v1/sdk/simple/, behind the key. |
Known limits
- Receipts aren't signed.
- The hosted gate has no classifier today, so judge checks there take their
on_errorverdict. - The gate's round-trip time hasn't been measured. The 0.27 ms rule decision covers the engine alone.
- In process, the guard is part of the application, so whoever owns that code owns the guard.