prempti: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Overview

Prempti is a policy and visibility layer for AI coding agents. It intercepts tool calls (shell commands, file writes, web requests, etc.) before execution, evaluates them against Falco rules, and produces allow/deny/ask verdicts in real time. It operates entirely in user space with no elevated privileges.

It is not a sandbox or OS-level security boundary: at the hook level it only sees what the agent declares, not the runtime side effects of the resulting commands. It is a cooperative policy layer — the agent receives LLM-friendly feedback on blocked or flagged actions and adapts — meant to complement containment techniques, not replace them.

The project targets Claude Code as its primary integration on Linux, macOS, and Windows, with experimental Codex CLI support (interceptor + plugin path; installer wiring deferred). The wire envelope, broker, and plugin field schema are agent-agnostic by design — adding another agent is a new interceptor crate plus any agent-specific field decoding, not a rewrite.

Architecture

┌──────────────┐     ┌──────────────┐     ┌────────────────────────────┐
│ Coding Agent │───▶│ Interceptor  │───▶│     Falco (nodriver)       │
│              │     │   (hook)     │     │  ┌───────────────────────┐ │
│              │◀───│              │◀───│  │  Plugin (src + extract│ │
│              │     │              │     │  │  + embedded broker)   │ │
└──────────────┘     └──────────────┘     │  └───────────────────────┘ │
                                          │  Rule Engine + Rules       │
                                          └────────────────────────────┘

Pipeline flow

1. Interception — The coding agent's hook API fires before each tool call. The interceptor captures structured event data and pauses tool execution while awaiting a verdict.
2. Event delivery — The interceptor sends the event to the plugin's embedded broker via Unix domain socket.
3. Rule evaluation — The plugin feeds the event to Falco's rule engine via the source plugin API (next_batch). Falco evaluates all loaded rules.
4. Alert feedback — Matching rules generate alerts. Falco delivers them back to the plugin's embedded broker via http_output (localhost).
5. Verdict resolution — The broker determines the verdict from rule tags (deny, ask, or the no-match floor allow/defer per default_action) and responds to the interceptor.
6. Verdict delivery — The interceptor communicates the verdict to the coding agent using the standard hook response format.