Every company deploying AI coding agents faces the same uncomfortable question: how do you know what the agent actually did, whether it followed your rules, and whether the evidence would hold up to a regulator’s scrutiny? Ethosure’s answer rests on an open-source project called coding-ethos, built and owned by one of Ethosure’s founders, Patrick Audley. This article walks through what coding-ethos is, how it works at a conceptual level, and why its architecture choices matter for your organization.
The one-sentence version
Coding-ethos is policy-as-code enforcement for AI agents: it turns your engineering principles into runnable rules that both human developers and AI coding agents must pass before their changes can land in your codebase.
Think of it as an automated compliance officer that sits at the exact moment an agent proposes an action – writing code, running a command, editing a file – checks that action against your organization’s stated rules, and either approves it, rewrites it into a safer form, sends it to a human, or blocks it outright. Every decision is recorded as tamper-evident evidence.
Where the rules come from
At the foundation of coding-ethos is a YAML file called `coding_ethos.yml`. This file holds approximately 29 named engineering principles – things like “fail fast and fail hard,” “security by design,” “validation at the gate,” and “radical visibility.” Each principle carries not just a description but the policies, repair guidance, and documentation that belong to it.
Think of these principles as your organization’s engineering constitution. They are not a slide deck or an employee handbook that lives in a drawer; they are structured data that feeds directly into the enforcement system.
The policy compiler: one source of truth
Raw principles need to become something a computer can evaluate instantly. That is the job of the policy compiler. It reads the principles file, your repository-specific settings, and any hook configuration, then compiles everything into a single versioned policy bundle – a JSON file called `policy-bundle.json`.
An important design choice here: “the compiled bundle is data, not code.” The bundle does not execute anything itself. It is a structured record of what is allowed, what is blocked, how severe each rule is, and what repair advice to show when something fails. Every part of the enforcement system – Git hooks, agent hooks, the MCP server query interface, and the runtime sandbox – reads from this one bundle. There is no divergence between what checks a developer’s commit and what checks an AI agent’s proposed edit.
The control plane: decisions
Once a policy bundle exists, the control plane is what applies it. The control plane has two parts working together:
- Go evaluators gather facts. When an agent proposes running a shell command, a Go program parses that command and extracts structured facts: what binary is being called, what arguments are present, what files are targeted.
- CEL evaluators make decisions. CEL stands for Common Expression Language – think of it as a calculator that takes facts as input and produces a decision as output. “Does this command contain a hook-bypass flag?” is a CEL expression. “Does this file edit touch a protected path?” is a CEL expression.
A critical design constraint: CEL is kept pure and deterministic. It cannot read files, call out to the internet, or make probabilistic guesses. Given the same facts and the same policy, it produces the same answer every time. This is what makes the system auditable.
The data plane: confinement
Deciding whether an action is allowed is only half the job. Once an action is approved, there is still the question of what a running process is permitted to touch. That is the data plane, implemented as a runtime sandbox.
The sandbox uses Linux kernel features (namespaces, Landlock filesystem policy, cgroup resource controls) to confine what an approved process can actually see and do. By default, managed tools get no network access, read-only access to the repository, and write access only to explicitly declared paths. If the sandbox cannot be set up properly, the tool fails closed – it does not run in an unsandboxed state as a fallback.
Four outcomes
Every action evaluated by the system resolves to one of exactly four dispositions:
- Allow – the action is permitted as proposed.
- Transform – the action is rewritten into a compliant or lower-risk form and then permitted.
- Escalate – the action is held and routed to a human for review.
- Block – the action is denied.
There is no fifth option. If the system cannot evaluate an action – for example, because the shell text is malformed – it defaults to block. This “fail-closed” default is the difference between a security control and a suggestion.
The evidence ledger
Every decision is recorded. The system emits structured findings in SARIF format (a standard used by code-scanning tools and accepted by regulators), alongside JSON and TOON records. These events are appended to an immutable JSONL log and indexed in a local DuckDB database for later querying. The evidence ledger is designed to answer the question an auditor will eventually ask: “Show me every action your AI agent took, why it was allowed or blocked, and which policy rule applied.”
How it deploys
coding-ethos can be dropped into an existing workflow in several ways: as Git hooks (catching problems before a commit lands), as agent tool-use hooks (intercepting actions mid-session), as an MCP proxy (letting agents query the policy system before acting), or as a planned agent proxy sidecar. The system is local-first – it requires no hosted backend, no cloud dependency, and no data leaving your environment.
The licensing and trust posture
coding-ethos is dual-licensed: AGPLv3 for open-source use, commercial license for proprietary deployments. It holds the OpenSSF Best Practices Silver badge (project #12737) and is tracking toward Gold. The project dogfoods its own rules – the coding-ethos repository enforces coding-ethos policy on itself. Ethosure builds its commercial offering on this open-source core.
