salacia-guard

salacia-guard

Zero-token scope enforcement for AI coding agents.

A Claude Code plugin that intercepts file edits in real-time, blocking out-of-scope changes without consuming any LLM tokens. The interception runs as a Node.js shell process — completely outside the model context.

The Problem

AI coding agents (Claude Code, Codex, Cursor, etc.) are bad at staying in scope. You ask it to fix the scheduler, it "helpfully" refactors config, updates README, and touches .env. On SWE-bench, scope drift is a leading cause of agent failure.

Current solutions:

• Plan mode: Ask the model to plan first. But the model still decides scope — garbage in, garbage out.
• Post-hoc review: Human reviews the diff. Doesn't scale for autonomous agents.
• Harness systems (Salacia paper, Agentless, etc.): Pre-compute scope, inject into prompt. Works, but costs tokens and doesn't enforce.

salacia-guard takes a different approach: enforce scope at the tool level, not the prompt level. The model can "think" whatever it wants — if it tries to edit a protected file, the edit is blocked before it happens. Zero tokens spent on enforcement.

How It Works

Agent receives task
    │
    ├─ /salacia-init generates .salacia/contract.json
    │   (which files are allowed, soft-allowed, protected)
    │
    ├─ Agent works normally...
    │
    ├─ Agent calls Edit("packages/core/src/scheduler.ts")
    │   └─ PreToolUse hook → guard.mjs → in scope → ✅ allow (silent)
    │
    ├─ Agent calls Edit(".env")
    │   └─ PreToolUse hook → guard.mjs → protected → 🛡️ BLOCK
    │   └─ Agent sees: "Salacia: BLOCKED — .env is a protected path"
    │
    ├─ Agent calls Edit("README.md")
    │   └─ PostToolUse hook → guard.mjs → out of scope → tracked
    │   └─ drift score += 5, warn if threshold exceeded
    │
    └─ /salacia-status shows drift report

Key insight: hooks run as shell commands, not LLM calls. Interception is free.

Research Background

This plugin draws from several research projects and papers. We didn't invent the ideas — we made them practical for everyday use.

Papers

Paper	What we took	What we didn't
Salacia (StartripAI, 2025)	Contract concept: define allowed paths before execution. Drift scoring formula (out-of-scope=+5, protected=+40).	Their pre-pass layers (fault localization, repo map, intent IR). Their system is a SWE-bench harness; ours is a runtime guard.
AgentFL (2024)	Three-step navigation idea (understand→navigate→confirm) validated that fault localization helps agents. $0.074/bug is the bar.	Their multi-agent architecture. We're simpler — single hook script.
ContextCov (2025)	Agent instructions → executable constraints. Confirmed that scope can be derived from task description.	Their formal constraint language. We use glob patterns — good enough.

Open-Source Projects

Project	What we took	Link
commit-prophet	Co-change coupling algorithm: coupling(A,B) = co_changes(A,B) / max(changes(A), changes(B)). We ported the core ~50 lines.	GitHub
Axon	Coupling threshold ≥0.3 as the default for "related files". Validated by their Tree-sitter knowledge graph.	GitHub
CodeScene	Commercial validation that temporal coupling works. Their "change coupling" feature proved the concept at scale.	codescene.com

Our Contributions

What's original in salacia-guard:

1. Zero-token enforcement via hooks. Everyone else injects scope into the prompt (costs tokens, model can ignore it). We enforce at the tool call level. The model literally cannot edit a protected file.

2. Soft/hard two-layer scope. Prior work treats scope as binary (in/out). We add a "soft allowed" zone for co-change companions — files that are related but not explicitly in scope. They don't trigger drift penalties but are tracked. This alone cut our false-positive rate from 67% to 27%.

3. Sibling directory inference. If the contract allows execution/scheduler.ts, we automatically soft-allow execution/**. Simple heuristic, massive impact — 21 files saved from false-positive in our test suite.

4. Mid-pattern glob matching. Sounds trivial, but config*.ts matching config.ts and configReader.ts is not handled by naive glob implementations. We added regex fallback for * in filename position.

Design Philosophy

Why not a full harness?

The Salacia paper (StartripAI) implements 5 layers: fault localization → repo map → intent IR → contract → verify & retry. That's a SWE-bench harness — it wraps the entire agent execution.