Skip to main content
LatticeAG

Lex Series

LexShield

Open Source

Policy firewall for agent tool calls. Classifies intent behind each tool call and enforces allow/block/challenge policy before execution.

Quick start

Start with the primary command, then continue with the full workflow below.

git clone https://github.com/LatticeAG/LexShield.git

Problem

AI agents call tools autonomously, and a single out-of-policy call - sending an email with a leaked AWS key, deleting a production resource, or writing to the wrong file - can cause damage faster than any human can intervene. Most agent safety tools only monitor tool calls after the fact, giving operators logs of incidents rather than prevention. Trust-once, permit-forever configurations let a single misjudged call escalate into exfiltration or destructive actions. Teams need a defense-in-depth layer that sits between an agent and its tool fleet and decides before the tool runs, without sending sensitive agent telemetry to a third-party API.

Solution

LexShield sits between an AI agent and its tool fleet, classifies the intent behind each tool call, and enforces allow/block/challenge policy before execution. It is fully local-first: deterministic evaluation works with no API keys, and the entire policy engine runs on your hardware with zero external API calls. The engine is default-deny (every tool call is blocked until a policy explicitly allows it), assigns one of four verdicts - ALLOW, BLOCK, CHALLENGE, DEFER - and appends every evaluation to traces.ndjson for audit. The architectural choice is a cross-platform monorepo with Python and TypeScript engines (golden parity on all deterministic paths) sharing the same policy YAML files, guarded by an optional LLM classifier fallback plus framework adapters for Vercel AI SDK, LangChain, and OpenAI Agents SDK. Human-in-the-loop CHALLENGE verdicts queue for approval and agents resume via signed webhooks.

How it works

01

Clone and install the monorepo: git clone https://github.com/LatticeAG/LexShield.git && cd LexShield && uv sync (Python via uv, TypeScript via pnpm).

02

Scaffold a config in a scratch directory using a policy pack - drop-in guardrails such as baseline-deny, pii-guard, and change-window: mkdir /tmp/lexshield-demo && cd /tmp/lexshield-demo && lexshield init --pack baseline-deny.

03

Validate the policy in a CI-friendly fashion: lexshield check --strict.

04

Evaluate a tool call offline - deterministic, no API key: lexshield evaluate --tool send_email --args '{"to":"user@example.com"}' --json returns a decision like BLOCK with the matched rule id (e.g. block-secret-exposure), while lexshield evaluate --tool health_check --args '{}' --json returns ALLOW.

05

In an agent loop, insert the shield between the agent and the tool fleet: the agent's ToolCallRequest hits the engine, classifiers (deterministic tool maps + regex, optional OpenAI-compatible LLM fallback) run, policy YAML plus rules.yaml produce a verdict, and only ALLOW reaches the tool upstream.

06

Run CHALLENGE verdicts through human approval end-to-end: cd examples/python-challenge-delete && uv run --project ../.. python main.py - the flow is CHALLENGE, CLI approve, then the guarded delete succeeds.

07

For TypeScript evaluation (golden parity with the Python engine): pnpm install, pnpm --filter @latticeag/lexshield build, then pnpm example:ts-evaluate.

08

Every verdict - ALLOW, BLOCK, CHALLENGE, or DEFER - is appended to traces.ndjson with the tool name, arguments, matched rule, and latency; an optional FastAPI server on 127.0.0.1:8787 exposes evaluate, execute, traces, and challenge-resolve endpoints.

Technical architecture

Each handoff carries structured context through the product's execution path. Hover a node to inspect its role.

01

Tool Call Capture

Step 1: Tool Call Capture receives structured context from the prior stage and prepares it for the next handoff.

02

Intent Classification

Step 2: Intent Classification receives structured context from the prior stage and prepares it for the next handoff.

03

Policy Matching

Step 3: Policy Matching receives structured context from the prior stage and prepares it for the next handoff.

04

Verdict Decision

Step 4: Verdict Decision receives structured context from the prior stage and prepares it for the next handoff.

05

Audit Tracing

Step 5: Audit Tracing receives structured context from the prior stage and prepares it for the next handoff.

06

Challenge Resolution

Step 6: Challenge Resolution receives structured context from the prior stage and prepares it for the next handoff.

07

Execution Gate

Step 7: Execution Gate receives structured context from the prior stage and prepares it for the next handoff.

When to use

  • You run agents (OpenAI Agents SDK, LangChain, Vercel AI SDK, or custom loops) that call tools with write/delete/network side effects.
  • You need a default-deny guardrail with graduated control, not binary pass/fail.
  • You want audit-ready traces of every tool-call verdict without standing up extra observability tooling.
  • You require local-only evaluation with zero external API calls and no vendor lock-in.
  • You need human approval (CHALLENGE) gating for destructive or sensitive operations.
  • You operate both Python and TypeScript agent stacks and want one policy surface for both.

Not for

  • Post-hoc result validation - LexShield verifies the call's permissibility before execution, not whether the result was correct (pair with LexVerdict for that).
  • Teams wanting a hosted/managed service - LexShield is self-hostable and local-first.
  • Very large rule sets - lexshield check --strict may take several seconds for 100+ rules.
  • Latency-critical flows with the optional LLM classifier - evaluation latency increases 500-2000ms when it is enabled (deterministic-only mode has no overhead).

Features

Default-deny YAML policies - priority rules, globs, tags, and safe expressions; no implicit allow

Intent classification layer - classifies semantic intent (send_email, delete_resource, read_fs) and applies intent-specific policies

Multi-verdict policy engine - ALLOW, BLOCK, CHALLENGE, DEFER with audit-friendly reasons for every verdict

Human-in-the-loop - CHALLENGE verdicts queue for human approval; agents resume with signed webhooks

Policy packs - baseline-deny, pii-guard, change-window drop-in policies for common guardrail scenarios

Python SDK - Shield.evaluate, @shield.guard decorator, await_challenge, trace sinks

TypeScript SDK - @latticeag/lexshield with golden parity on all deterministic paths

CLI - init, check, evaluate, run, traces, challenge, packs, and shell completion

Local API - FastAPI server on 127.0.0.1:8787 (evaluate, execute, traces, challenge resolve)

Structured traces - every verdict appended to traces.ndjson with tool name, args, matched rule, latency

Cross-engine golden parity - Python and TypeScript engines tested against the same golden fixture suite

Framework adapters - community patterns for Vercel AI SDK, LangChain, and OpenAI Agents SDK

Deterministic by default - regex pattern matching and intent classification run locally, no external API calls required

Pre-execution, not post-hoc - evaluates before the tool runs, prevents rather than monitors

Install and usage

usage.sh
# Clone and install (Python via uv)
git clone https://github.com/LatticeAG/LexShield.git
cd LexShield
uv sync

# Scaffold config in a scratch directory with a policy pack
mkdir /tmp/lexshield-demo && cd /tmp/lexshield-demo
lexshield init --pack baseline-deny

# Validate the policy (CI-friendly)
lexshield check --strict

# Evaluate a tool call offline - deterministic, no API key
lexshield evaluate \
  --tool send_email \
  --args '{"to":"user@example.com","body":"<redacted:AKIA...>"}' \
  --json
# -> "decision": "BLOCK", "matchedRuleId": "block-secret-exposure"

lexshield evaluate --tool health_check --args '{}' --json
# -> "decision": "ALLOW", "matchedRuleId": "allow-health"

# Challenge flow (human approval end-to-end)
cd examples/python-challenge-delete
uv run --project ../.. python main.py
# CHALLENGE -> CLI approve -> guarded delete succeeds

# TypeScript evaluation (golden parity)
pnpm install
pnpm --filter @latticeag/lexshield build
pnpm example:ts-evaluate

Architecture explorer

Problem

AI agents call tools autonomously, and a single out-of-policy call - sending an email with a leaked AWS key, deleting a production resource, or writing to the wrong file - can cause damage faster than any human can intervene. Most agent safety tools only monitor tool calls after the fact, giving operators logs of incidents rather than prevention. Trust-once, permit-forever configurations let a single misjudged call escalate into exfiltration or destructive actions. Teams need a defense-in-depth layer that sits between an agent and its tool fleet and decides before the tool runs, without sending sensitive agent telemetry to a third-party API.

Solution

LexShield sits between an AI agent and its tool fleet, classifies the intent behind each tool call, and enforces allow/block/challenge policy before execution. It is fully local-first: deterministic evaluation works with no API keys, and the entire policy engine runs on your hardware with zero external API calls. The engine is default-deny (every tool call is blocked until a policy explicitly allows it), assigns one of four verdicts - ALLOW, BLOCK, CHALLENGE, DEFER - and appends every evaluation to traces.ndjson for audit. The architectural choice is a cross-platform monorepo with Python and TypeScript engines (golden parity on all deterministic paths) sharing the same policy YAML files, guarded by an optional LLM classifier fallback plus framework adapters for Vercel AI SDK, LangChain, and OpenAI Agents SDK. Human-in-the-loop CHALLENGE verdicts queue for approval and agents resume via signed webhooks.