grounded
hyde0395/grounded
Deterministic guardrail for Claude Code: hooks that block ungrounded agent actions — editing files it never read, installing hallucinated packages, citing dead links. No LLM in the loop.
Instalação
npx convez-ai hyde0395/grounded1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
grounded
Make AI coding agents prove it before they act.
grounded is a guardrail for Claude Code that deterministically stops an agent from acting on things it never verified — editing files it never read, installing packages it never checked, citing URLs it never fetched.
No LLM in the loop. No network calls (for the core rule). Just hooks, a local ledger, and exit codes.

A real session: a hallucinated pip install blocked by G-2, a blind sed -i blocked by G-1, and a proper read-then-edit passing — ending with the file actually changed.
Why
The most expensive failure of AI coding agents isn't the dangerous command — existing security guardrails catch those. It's the agent claiming it verified something it never did: editing from a guess, installing a hallucinated package, citing a dead link. Every ungrounded action stacks the next action on a false premise, and a human pays the bill re-verifying everything.
This isn't hypothetical. A USENIX Security 2025 study of 576,000 generated code samples found that 5.2–21.7% of LLM-recommended packages don't exist (205,474 unique hallucinated names) — a supply-chain attack surface now known as slopsquatting. G-2 closes it at the moment of install.
Writing "don't guess" in your CLAUDE.md is a suggestion the model interprets at runtime — it can be talked out of it. A hook is enforcement: it runs no matter what the model thinks.
| Security guardrails (many) | grounded | |
|---|---|---|
| Blocks | dangerous actions (rm -rf, force push, secrets) | ungrounded actions (edit-without-read, unverified installs, dead links) |
| Asks | "Is this command dangerous?" | "Does this action have evidence?" |
| Judged by | static command patterns | session behavior history (stateful) |
grounded is a complement to security guardrails, not a replacement.
How it works
Hooks are stateless one-shot processes, so the state lives in a local ledger. PostToolUse accrues evidence; PreToolUse demands it.
tool ran (Read / Grep / cat) ───────────────┐
▼
PostToolUse hook ── accrue ──▶ .grounded/ledger.json
{ read_files, verified_urls, known_pkgs }
│ look up
agent attempts Edit / Write ──▶ PreToolUse hook
│
┌──────────────────────┼──────────────────────┐
▼ ▼ ▼
grounded uncertain ungrounded
exit 0 · pass exit 0 · inject warning exit 2 · block
(reason fed back
to the model)
Every rule resolves to one of three verdicts — and the design philosophy is false positives are worse than misses. If grounded isn't sure, it warns instead of blocking. It only blocks when the absence of evidence is unambiguous.
| Verdict | When | What happens |
|---|---|---|
| PASS | evidence is in the ledger | exit 0, silent |
| WARN | evidence is ambiguous (403, timeout) | exit 0 + warning injected to the model |
| STOP | evidence is clearly absent | exit 2, blocked with an actionable reason |
Warnings are idempotent: each (rule, target) pair warns at most once per
session (tracked in the ledger's warned section), and every injection ends
with an explicit "advisory — will not repeat, don't retry to clear it"
note. Injected context is itself a side effect; without this, a warning that
reappears on every retry reads like an escalating problem and can send the
agent chasing the warning instead of the task.
Rules
| Rule | What it enforces | Status |
|---|---|---|
| G-1 Read-before-edit | A file can't be edited unless it was read this session (Read, Grep, cat, git diff/git show output) | ✅ v0.1 |
| G-1s Shell-write gating | sed -i, perl -i, tee, >, cp/mv onto a never-read file → blocked; >> (append) and batch writes with run-time targets (find -exec sed -i, xargs sed -i) → warning only | ✅ v0.2 |
| G-2 Verify-before-install | A package can't be installed unless it exists on its registry (npm / PyPI / crates.io) | ✅ v0.2 |
| G-3 Fetch-before-cite | Dead URLs (404/410/DNS failure) are blocked; ambiguous ones (403/5xx/timeout) only warn | ✅ v0.3 |
| freshness Stale-read detection | A file that changed on disk after it was read → warning to re-read before relying on it | ✅ v0.5 |
When a rule blocks, the model receives an actionable reason:
[grounded G-1] This command overwrites src/auth.py (truncate) but there is no
record of reading it this session. Read the file first (Read tool or cat), then retry.
[grounded G-2] Package 'reqests' was not found on PyPI. This usually means a
hallucinated or misspelled package name. Search the registry for the correct
name before installing.
G-2 and G-3 lookups are cached in the session ledger (positive and
negative), use a 2.5s timeout, and never block on network trouble — an
unreachable registry is not evidence of hallucination. Negative results
expire after 10 minutes and get re-checked, so the package you published
five minutes ago doesn't stay blocked for the whole session. A cached re-check costs
~50ms, and one command's lookups share a 5s total budget — past it, uncached
targets are skipped (fail open) rather than stalling your tool call. G-3
probes with HEAD only, skips private/localhost hosts (a dev server that isn't
running yet is normal), and skips curl -X POST/--data calls (API
endpoints legitimately reject HEAD probes).
Configuration
Every rule can be toggled individually — in .grounded/config.json in the
project, or with the GROUNDED_DISABLE environment variable (comma-separated,
case-insensitive; env wins over file):
{ "G-1": true, "G-1s": true, "G-2": true, "G-3": false, "freshness": true, "grep-evidence": false }
GROUNDED_DISABLE="g-3,grep_evidence"
grep-evidence: false is strict mode: a Grep match no longer counts as
having read the file — only a full read does. A missing or corrupt config
enables everything (the toggles exist to opt out, so failing to read them
must not change default behavior).
Install
As a plugin (recommended)
/plugin marketplace add hyde0395/grounded
/plugin install grounded@grounded
As a project hook
Copy hooks/ into your project and register in .claude/settings.json:
{
"hooks": {
"SessionStart": [
{ "hooks": [{ "type": "command", "command": "python3 \"$CLAUDE_PROJECT_DIR/hooks/session_start.py\"" }] }
],
"PostToolUse": [
{ "matcher": "Read|Grep|Edit|Write|MultiEdit|NotebookEdit|Bash|WebFetch",
"hooks": [{ "type": "command", "command": "python3 \"$CLAUDE_PROJECT_DIR/hooks/post_record.py\"" }] }
],
"PreToolUse": [
{ "matcher": "Edit|Write|MultiEdit|NotebookEdit|Bash|WebFetch",
"hooks": [{ "type": "command", "command": "python3 \"$CLAUDE_PROJECT_DIR/hooks/pre_gate.py\"" }] }
]
}
}
Requirements: Python 3 on PATH as python3 or python (stdlib only — zero
dependencies). On Windows, hooks run under Git Bash (installed with Git); if
Python is missing entirely, grounded fails open — your tools keep working,
just unguarded.
Verify it yourself in 60 seconds
Every claim above is reproducible in any project with grounded installed:
- Ask Claude to run
pip install reqests(the classic typo) → blocked before execution:[grounded G-2] Package 'reqests' was not found on PyPI… - Ask it to run
sed -i 's/a/b/' <a file it hasn't opened>→ blocked:[grounded G-1] … no record of reading it this session. - Ask it to read that file first, then edit it → passes silently, and the change lands.
The GIF at the top is exactly this, recorded unscripted against a live
session (demo/demo.tape reproduces it).
Network access & privacy
No telemetry, no analytics, no calls home. The complete list of network traffic grounded can generate:
- G-2 — one existence lookup against the public registry (registry.npmjs.org / pypi.org / crates.io) the first time a session installs a given package; the answer is cached in the local ledger.
- G-3 — one HEAD probe (GET fallback) against a URL the agent is about to fetch or cite; private/localhost hosts are never probed.
Both rules can be turned off ({"G-2": false, "G-3": false} in
.grounded/config.json), every lookup is capped at 2.5s with a 5s
per-command budget, and G-1/G-1s/freshness work entirely offline. All state
lives in .grounded/ledger.json inside your project.
Honest limitations
We'd rather tell you up front than have you find out:
- Text responses are invisible to hooks. If the agent pastes a link or a claim as plain chat text without using a tool, no hook fires. That's a structural limit of hooks; a bundled prompt rule (roadmap v0.4) only partially mitigates it.
- Recent Claude Code already covers the simplest G-1 case. Claude Code's built-in validation rejects
Editon a never-read file by itself. grounded's G-1 is defense-in-depth there — its own value is the evidence ledger (it countscat/grepas reads, tracks freshness, and powers the rules the built-in check doesn't have: shell-level write bypasses, G-2, G-3). - Bot walls cause false signals. Cloudflare answering
curlwith 403 doesn't mean the link is dead — which is exactly why G-3 warns instead of blocks on 403. - grounded is not an adversarial boundary. Shell-write gating catches the common idioms (
sed -i,tee, redirections) — the lazy path, not the evasive one. A model that deliberately hides a write behindpython -cor base64 isn't being sloppy, it's evading a guardrail; that's a security problem, and the answer is sandboxing and permissions — the layer grounded explicitly complements, not replaces. - What we promise: grounding enforcement at the tool boundary. What we don't: catching every hallucination.
Related work
grounded independently converges on two ideas the research community has recently formalized:
- AgentSpec (ICSE 2026) frames agent safety as runtime enforcement: trigger → predicate → enforcement rules living outside the model. grounded is that model specialized to Claude Code's hook boundary — matcher → ledger-backed verdict → exit code, ~30ms per invocation (measured on an M-series MacBook), no LLM in the judgment path.
- CaMeL (Google DeepMind) treats the LLM as an untrusted component and puts a deterministic layer in control. CaMeL applies that stance to prompt injection; grounded applies it to ungrounded action.
- The package-hallucination problem G-2 targets is quantified in "We Have a Package for You!" (USENIX Security 2025).
Development
python3 -m unittest discover -s tests # 210 tests, hooks exercised via real stdin/exit-code interface
The layout mirrors the architecture: thin entrypoints (session_start.py, post_record.py, pre_gate.py), pure logic (verdict.py, shell_scan.py — no I/O, no LLM), and side effects at the edges (ledger_io.py, registry.py, urlcheck.py). Network calls take an injectable opener, so the whole suite runs offline.
Roadmap
| Version | Ships | Kills this failure |
|---|---|---|
| v0.1 ✅ | G-1 read-before-edit + session ledger | editing from a guess |
| v0.2 ✅ | G-2 package-existence check + caching, shell-write gating (sed -i, echo >, tee) | hallucinated installs, Edit-tool bypasses |
| v0.3 ✅ | G-3 URL liveness (block 404·DNS-dead / warn 403·5xx) for WebFetch + curl/wget | citing dead links |
| v0.4 ✅ | marketplace plugin packaging, Windows support (python3/python launcher), bundled prompt rule for plain-text claims | install friction, text blind spot (partial) |
| v0.5 ✅ | freshness — detect external edits after read, per-rule on/off config, more evidence sources (git diff/git show, Grep content output), hardening (heredoc-aware parsing, ledger lock, 5s network budget) | acting on stale evidence, false positives on indirect reads |
| v0.6.0 ✅ | batch-write warnings (find -exec/xargs sed -i), cp/mv overwrite gating, negative-cache 10-min TTL (re-check published packages), Windows ledger lock (msvcrt) | unverified batch writes, stale negative cache, lost accruals on Windows |
| v0.6.1 ✅ | ledger anchored to project root (cwd-drift fix), demo GIF, network-access disclosure + 60-second verification | mis-anchored ledger when cwd ≠ project root |