Coco
Understand Coco

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:

  1. Decide every tool call before it runs, in code the model doesn't control.
  2. Decide facts deterministically, so a decision replays exactly.
  3. Derive the rules from your own documents, each citing its clause.
  4. Keep a tamper-evident record of every decision.
  5. Start without breaking anything, then tighten when you're ready.
  6. 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| gate

The parts

PartLocationWhat it does
Enginepython/coco_sdk/engine/Contracts, the rule language, judge checks, verdicts, and the SQLite ledger.
CocoGuardpython/coco_sdk/guard.pyMiddleware on the agent's tool-call seam, with one body for coco-framework and upstream LangChain.
RemoteEnginepython/coco_sdk/remote.pyThe Engine's surface, with the gate deciding over HTTP.
Project and CLIpython/coco_sdk/project.py, cli.pycoco.yaml and the coco command.
Compilerpython/coco_sdk/compile/Canonical policy to draft contracts and boundary cases.
Claude Code hookpython/coco_sdk/hooks/, cli/A PreToolUse hook and its installer.
TypeScript clientjs/CocoEnforcer, which always asks the gate.
Gategate/The engine behind HTTP, a record per project, and the SDK's package index.
Document servicepolicy/Documents to AI-ready context, canonical policy, and draft contracts.
Evaluationpython/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
    end

Each 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 rejected

A policy document to a live contract

  1. A person adds a PDF or DOCX to policies/, or uploads it on the dashboard.
  2. The pipeline reads the document into AI-ready context, builds a search index, and extracts each rule with its clause.
  3. The compiler groups rules into draft contracts, one per action, and writes boundary cases.
  4. 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.
  5. The contract goes to testing or live. Nothing is enforced until a person activates it.

Key decisions and trade-offs

DecisionWhyWhat it costs
Rules decide before any modelFacts 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 verdictA model must never be able to loosen policy.Calls held for a person.
Fail closedA control that disappears under failure is no control.A gate outage stops calls in Enforce, unless fail_open is set.
Monitor is the defaultYou see real verdicts before anything is blocked.Nothing is stopped until someone promotes the project.
Facts come through a callbackA model must not assert the facts that judge it.The application has to supply them.
A decision is read from the recordNeither the agent nor the application can forge an approval.Resuming needs a checkpointer and the record.
One Engine surface, in process or remoteConnecting 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 serviceThe 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 signedEditing an earlier receipt breaks the chain.The chain shows tampering only to someone checking it.
One chain per project, one writer at a timeThe chain never forks, and two calls can't pass a ceiling at once.Decisions within one project are serialised.
Documents are deleted once pulledThe service should hold a policy no longer than it needs to.Reprocessing means uploading again, unless you use --keep.
Every draft waits for a personA model reads the document, so its output varies between runs.Someone has to review before anything goes live.
The agent runtime is a renamed forkImports and tracing stay under Coco's control, and the tracer sends nothing.The fork has to track upstream.

Integration points

PointDirectionShape
Tool-call middlewareFramework to guard.wrap_tool_call and awrap_tool_call on create_agent.
PreToolUse hookClaude Code to hook.One tool call on stdin, a permission decision on stdout.
HTTP checkAny runtime to the gate.POST /v1/check with a project key.
State providerGuard to your systems.A callable, (action, args) to a dictionary.
Escalation webhookGate to your application.POST of {"type": "escalation_decided", "project", "escalation"} to the project's webhook URL.
ClassifierEngine to coco-classifier.POST /v1/classify.
Document serviceCLI or dashboard to the service.Register, signed upload, complete, poll, and pull.
Package indexuv 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_error verdict.
  • 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.

On this page