# permit0-ai/permit0-core architecture

> Architecture diagram of the GitHub repository permit0-ai/permit0-core, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/permit0-ai/permit0-core
- Repository: https://github.com/permit0-ai/permit0-core

## Overview

1. **Overall shape**
   - Permit0 is a Rust workspace centered on a **policy engine** that sits between AI agent tool calls and the real side effects they would trigger.
   - The repo is split into a small number of clear planes: **decision engine**, **pack DSL and taxonomy**, **state/audit storage**, **UI/API**, **CLI/hook tooling**, and **language/integration adapters**.

2. **Core runtime: `permit0-engine`**
   - This is the main execution path for policy decisions.
   - It takes a normalized action plus context, runs the decision pipeline, applies policy/cache checks, risk evaluation, session amplification, and routing to allow/deny/human review.
   - The engine is the boundary where deterministic policy enforcement happens; everything else feeds it or consumes its outputs.

3. **Action vocabulary and normalization: `permit0-types`, `permit0-dsl`, `permit0-normalize`**
   - `permit0-types` defines the canonical taxonomy, normalized action model, permissions, risks, and tool-call types.
   - `permit0-dsl` owns the YAML pack model, validation, loading, normalization evaluation, and risk rule execution.
   - `permit0-normalize` provides reusable normalization primitives such as aliases, registries, fallbacks, and context-aware helpers.
   - Architecturally, this is the “translation layer” that maps vendor/tool-specific calls into Permit0’s canonical action space.

4. **Packs as policy content: `packs/permit0/email`**
   - Packs are the repo’s policy content format: YAML normalizers, risk rules, lockfiles, and tests.
   - The shipped email pack is the reference implementation, covering Gmail and Outlook surfaces.
   - Packs are what make the engine extensible without changing core code; the engine consumes packs, while the pack directory defines the supported action boundaries.

5. **Scoring and session-aware decisions: `permit0-scoring` and `permit0-session`**
   - `permit0-scoring` computes risk based on taxonomy dimensions and configured amplifiers, producing the numeric score and tier routing used by the engine.
   - `permit0-session` tracks multi-call behavior, maintains per-session context, and applies amplification/block rules when repeated actions increase risk.
   - These crates represent the “decision intelligence” layer: the engine is not just matching rules, it is combining action semantics with session state.

6. **State and persistence: `permit0-store`**
   - This crate owns durable state for both **policy decisions/caches** and **audit logging**.
   - It supports multiple backends: SQLite and PostgreSQL for state, plus several audit sinks including SQLite, Postgres, stdout, memory, and OpenTelemetry.
   - The audit subsystem includes digest chaining, signing, redaction, teeing, and export, which makes the audit trail a first-class subsystem rather than an afterthought.

7. **Human-in-the-loop and review workflows: `permit0-ui`**
   - The UI is the operator surface for approvals, pack browsing, and dashboard-style review.
   - It includes server routes, approval handling, pack routes, and authentication with OIDC/session support.
   - This is where human review decisions are made when the engine routes an action above the allow threshold or when unknown actions are blocked.

8. **Command-line entrypoints and host integration: `permit0-cli`, hooks, and gateway**
   - `permit0-cli` provides operational commands such as serve, check, calibrate, digest, audit, pack, gateway, and hook.
   - The hook path is the critical integration boundary for agent hosts like Claude Code: it intercepts pre-tool execution, consults the daemon, and returns the enforcement verdict.
   - The gateway path is the broader service boundary for non-hook integrations or remote enforcement setups.

9. **Language bindings and external agent integrations**
   - `permit0-node` and `permit0-py` expose the core functionality to JavaScript/TypeScript and Python consumers.
   - `integrations/permit0-openclaw` is a concrete adapter that wraps OpenClaw execution through Permit0’s decision flow.
   - These adapters sit outside the core policy engine, but they are important architectural boundaries because they are the entrypoints from different agent runtimes.

10. **Testing and calibration data**
   - `corpora/calibration` contains real-world policy calibration cases for Gmail and Outlook actions.
   - The repository also includes crate-level tests, pack integration tests, CLI snapshots, and integration tests for the Node/Python bindings.
   - This indicates the system is designed around repeatable policy calibration and regression safety, not just unit-level correctness.

11. **Deployment and infrastructure**
   - The repo is designed to run in Docker and can compose an engine + dashboard stack alongside external MCP servers.
   - It uses Rust 1.85+, SQLite by default, PostgreSQL when deployed centrally, and OpenTelemetry for audit/export integration.
   - OIDC appears in the UI as the identity boundary for operators; the hook config determines whether human review is handled in the UI or returned to the caller.

12. **End-to-end data flow**
   - A tool call originates in an agent host, passes through the hook or gateway, gets normalized by a pack into a canonical action, then is scored and routed by the engine.
   - The decision is cached and written to audit/state storage; if needed, it is surfaced to the UI for human approval.
   - The result flows back to the caller as allow/deny/escalate, while the signed audit chain preserves a verifiable record of what happened.

Main entry points: [`crates/permit0-engine`](https://github.com/permit0-ai/permit0-core/tree/main/crates/permit0-engine) (Engine), [`crates/permit0-dsl`](https://github.com/permit0-ai/permit0-core/tree/main/crates/permit0-dsl) (DSL), [`crates/permit0-store`](https://github.com/permit0-ai/permit0-core/tree/main/crates/permit0-store) (Store), [`crates/permit0-cli`](https://github.com/permit0-ai/permit0-core/tree/main/crates/permit0-cli) (CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Core policy"]
  node_permit0_engine["Engine<br/>policy runtime"]
  node_permit0_types["Types<br/>taxonomy"]
  node_permit0_dsl["DSL<br/>pack runtime"]
  node_permit0_normalize["Normalize<br/>translation helpers"]
  node_permit0_scoring{{"Scoring"}}
  node_permit0_session[("Session")]
  node_permit0_store[("Store<br/>state and audit")]
end

subgraph group_content["Policy content"]
  node_packs_email["Email pack<br/>policy content"]
  node_calibration_corpora["Calibration<br/>policy corpus"]
end

subgraph group_interfaces["Interfaces"]
  node_permit0_ui["UI<br/>review console"]
  node_permit0_cli["CLI<br/>operator entrypoint"]
  node_permit0_agent["Agent client<br/>review client"]
  node_permit0_node["Node binding<br/>js binding"]
  node_permit0_py["Python binding<br/>py binding"]
end

subgraph group_integrations["Integrations"]
  node_openclaw_integration["OpenClaw<br/>integration adapter"]
end

subgraph group_ops["Ops and auth"]
  node_permit0_shell_dispatch["Shell dispatch<br/>hook parser"]
  node_permit0_token["Token"]
end

node_permit0_cli -->|"serves"| node_permit0_engine
node_permit0_cli -->|"hook path"| node_permit0_shell_dispatch
node_permit0_cli -->|"manages"| node_permit0_store
node_permit0_cli -->|"packs"| node_permit0_dsl
node_permit0_engine -->|"uses"| node_permit0_types
node_permit0_engine -->|"evaluates"| node_permit0_dsl
node_permit0_engine -->|"normalizes"| node_permit0_normalize
node_permit0_engine -->|"scores"| node_permit0_scoring
node_permit0_engine -->|"tracks"| node_permit0_session
node_permit0_engine -->|"persists"| node_permit0_store
node_permit0_dsl -->|"models"| node_permit0_types
node_permit0_dsl -->|"applies"| node_permit0_normalize
node_permit0_dsl -->|"loads"| node_packs_email
node_permit0_dsl -.->|"validates"| node_calibration_corpora
node_permit0_scoring -->|"interprets"| node_permit0_types
node_permit0_session -->|"stores"| node_permit0_store
node_permit0_store -->|"feeds"| node_permit0_ui
node_permit0_store -->|"serves state"| node_permit0_engine
node_permit0_ui -->|"authenticates"| node_permit0_token
node_permit0_ui -->|"reviews"| node_permit0_store
node_permit0_agent -->|"reviews"| node_permit0_ui
node_permit0_node -->|"wraps"| node_permit0_engine
node_permit0_py -->|"wraps"| node_permit0_engine
node_openclaw_integration -->|"enforces"| node_permit0_engine
node_permit0_shell_dispatch -->|"consults"| node_permit0_engine

click node_permit0_engine "https://github.com/permit0-ai/permit0-core/tree/main/crates/permit0-engine"
click node_permit0_types "https://github.com/permit0-ai/permit0-core/tree/main/crates/permit0-types"
click node_permit0_dsl "https://github.com/permit0-ai/permit0-core/tree/main/crates/permit0-dsl"
click node_permit0_normalize "https://github.com/permit0-ai/permit0-core/tree/main/crates/permit0-normalize"
click node_permit0_scoring "https://github.com/permit0-ai/permit0-core/tree/main/crates/permit0-scoring"
click node_permit0_session "https://github.com/permit0-ai/permit0-core/tree/main/crates/permit0-session"
click node_permit0_store "https://github.com/permit0-ai/permit0-core/tree/main/crates/permit0-store"
click node_packs_email "https://github.com/permit0-ai/permit0-core/tree/main/packs/permit0/email"
click node_calibration_corpora "https://github.com/permit0-ai/permit0-core/tree/main/corpora/calibration"
click node_permit0_ui "https://github.com/permit0-ai/permit0-core/tree/main/crates/permit0-ui"
click node_permit0_cli "https://github.com/permit0-ai/permit0-core/tree/main/crates/permit0-cli"
click node_permit0_agent "https://github.com/permit0-ai/permit0-core/tree/main/crates/permit0-agent"
click node_permit0_node "https://github.com/permit0-ai/permit0-core/tree/main/crates/permit0-node"
click node_permit0_py "https://github.com/permit0-ai/permit0-core/tree/main/crates/permit0-py"
click node_permit0_shell_dispatch "https://github.com/permit0-ai/permit0-core/tree/main/crates/permit0-shell-dispatch"
click node_permit0_token "https://github.com/permit0-ai/permit0-core/tree/main/crates/permit0-token"
click node_openclaw_integration "https://github.com/permit0-ai/permit0-core/tree/main/integrations/permit0-openclaw"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_permit0_engine,node_permit0_types,node_permit0_dsl,node_permit0_normalize,node_permit0_scoring,node_permit0_session,node_permit0_store toneBlue
class node_packs_email,node_calibration_corpora toneAmber
class node_permit0_ui,node_permit0_cli,node_permit0_agent,node_permit0_node,node_permit0_py toneMint
class node_openclaw_integration toneRose
class node_permit0_shell_dispatch,node_permit0_token toneIndigo
```

## Components

### Core policy

Canonical types, normalization, policy evaluation, scoring, session state, and persistence.

- [Engine](https://github.com/permit0-ai/permit0-core/tree/main/crates/permit0-engine): policy runtime · Main decision pipeline that evaluates normalized actions and routes allow, deny, or human review. · `crates/permit0-engine`
- [Types](https://github.com/permit0-ai/permit0-core/tree/main/crates/permit0-types): taxonomy · Canonical action model, permissions, risks, and tool-call vocabulary. · `crates/permit0-types`
- [DSL](https://github.com/permit0-ai/permit0-core/tree/main/crates/permit0-dsl): pack runtime · Pack schema, loading, validation, normalization evaluation, and risk-rule execution. · `crates/permit0-dsl`
- [Normalize](https://github.com/permit0-ai/permit0-core/tree/main/crates/permit0-normalize): translation helpers · Reusable normalization primitives such as aliases, registries, fallbacks, and context helpers. · `crates/permit0-normalize`
- [Scoring](https://github.com/permit0-ai/permit0-core/tree/main/crates/permit0-scoring): risk scoring · Converts taxonomy and amplifiers into numeric risk scores and routing tiers. · `crates/permit0-scoring`
- [Session](https://github.com/permit0-ai/permit0-core/tree/main/crates/permit0-session): session risk · Tracks multi-call context and applies amplification or block rules across a session. · `crates/permit0-session`
- [Store](https://github.com/permit0-ai/permit0-core/tree/main/crates/permit0-store): state and audit · Persistent policy state, decision cache, and audit chain with multiple storage and sink backends. · `crates/permit0-store`

### Policy content

Packs and calibration corpora that define and validate policy behavior.

- [Email pack](https://github.com/permit0-ai/permit0-core/tree/main/packs/permit0/email): policy content · Reference policy pack for Gmail and Outlook normalizers, risk rules, and lockfile. · `packs/permit0/email`
- [Calibration](https://github.com/permit0-ai/permit0-core/tree/main/corpora/calibration): policy corpus · Real-world calibration cases used to tune and regress policy decisions. · `corpora/calibration`

### Interfaces

Operator UI, CLI entrypoints, and language-facing client crates.

- [UI](https://github.com/permit0-ai/permit0-core/tree/main/crates/permit0-ui): review console · Operator dashboard for approvals, pack browsing, authentication, and review workflows. · `crates/permit0-ui`
- [CLI](https://github.com/permit0-ai/permit0-core/tree/main/crates/permit0-cli): operator entrypoint · Operational commands for serving, checking, calibrating, digesting, auditing, packaging, gateway, and hooks. · `crates/permit0-cli`
- [Agent client](https://github.com/permit0-ai/permit0-core/tree/main/crates/permit0-agent): review client · Client-side helper for talking to Permit0 and presenting reviewer flows. · `crates/permit0-agent`
- [Node binding](https://github.com/permit0-ai/permit0-core/tree/main/crates/permit0-node): js binding · JavaScript/TypeScript binding around the core policy flow. · `crates/permit0-node`
- [Python binding](https://github.com/permit0-ai/permit0-core/tree/main/crates/permit0-py): py binding · Python binding around the core policy flow. · `crates/permit0-py`

### Integrations

External adapters and host-facing execution boundaries.

- [OpenClaw](https://github.com/permit0-ai/permit0-core/tree/main/integrations/permit0-openclaw): integration adapter · TypeScript adapter that routes OpenClaw execution through Permit0 decisions. · `integrations/permit0-openclaw`

### Ops and auth

Supporting authentication, tokens, and shell dispatch for host integration.

- [Shell dispatch](https://github.com/permit0-ai/permit0-core/tree/main/crates/permit0-shell-dispatch): hook parser · Shell command parsing and YAML-based dispatch used by host hooks. · `crates/permit0-shell-dispatch`
- [Token](https://github.com/permit0-ai/permit0-core/tree/main/crates/permit0-token): auth token · Token/provider utilities for secure client and service access. · `crates/permit0-token`

## Connections

- CLI → Engine: serves · CLI launches or drives the policy engine for local and daemon modes.
- CLI → Shell dispatch: hook path · CLI hook mode uses shell dispatch to intercept tool execution.
- CLI → Store: manages · CLI commands operate on policy state, digests, and audits.
- CLI → DSL: packs · CLI exposes pack inspection, validation, and calibration flows.
- Engine → Types: uses · Engine consumes the canonical taxonomy and normalized action model.
- Engine → DSL: evaluates · Engine loads and executes pack-defined policy content.
- Engine → Normalize: normalizes · Engine depends on reusable normalization primitives.
- Engine → Scoring: scores · Engine computes routing risk from taxonomy and amplifiers.
- Engine → Session: tracks · Engine applies session-aware amplification and block logic.
- Engine → Store: persists · Engine writes and reads cached decisions and audit state.
- DSL → Types: models · DSL schemas and loaders are built around the canonical action types.
- DSL → Normalize: applies · Pack normalization uses shared normalization helpers and registries.
- DSL → Email pack: loads · DSL is the runtime for pack content such as the email reference pack.
- DSL → Calibration: validates · Calibration cases exercise pack behavior and decision boundaries.
- Scoring → Types: interprets · Scoring maps taxonomy dimensions into numeric risk outcomes.
- Session → Store: stores · Session state relies on durable backing storage.
- Store → UI: feeds · UI reads decision and audit data for review and operations.
- Store → Engine: serves state · Policy cache and audit lookups support engine decisions.
- UI → Token: authenticates · UI uses token and identity plumbing for operator access.
- UI → Store: reviews · UI surfaces approvals, state, and audit history.
- Agent client → UI: reviews · Agent helper connects callers into review and approval flows.
- Node binding → Engine: wraps · Node binding exposes core decisions to JS/TS consumers.
- Python binding → Engine: wraps · Python binding exposes core decisions to Python consumers.
- OpenClaw → Engine: enforces · OpenClaw adapter routes execution through Permit0 policy decisions.
- Shell dispatch → Engine: consults · Hook dispatch consults the policy engine before side effects occur.