permit0-ai/permit0-core

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.