convez.ai
Agente
hyde0395

grounded

hyde0395/grounded

Ver no GitHub
InicialPluginScore · de 0 a 100

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/grounded

1 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

Estrelas
1
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 4 meses
Versão
v0.6.1
Issues abertas
0
Contribuidores
1

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.

version license engine category

grounded blocking a hallucinated package install and a blind sed -i, then passing a proper read-then-edit

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
Blocksdangerous 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 bystatic command patternssession 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.

VerdictWhenWhat happens
PASSevidence is in the ledgerexit 0, silent
WARNevidence is ambiguous (403, timeout)exit 0 + warning injected to the model
STOPevidence is clearly absentexit 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

RuleWhat it enforcesStatus
G-1 Read-before-editA 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 gatingsed -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-installA package can't be installed unless it exists on its registry (npm / PyPI / crates.io)✅ v0.2
G-3 Fetch-before-citeDead URLs (404/410/DNS failure) are blocked; ambiguous ones (403/5xx/timeout) only warn✅ v0.3
freshness Stale-read detectionA 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:

  1. Ask Claude to run pip install reqests (the classic typo) → blocked before execution: [grounded G-2] Package 'reqests' was not found on PyPI…
  2. 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.
  3. 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 Edit on a never-read file by itself. grounded's G-1 is defense-in-depth there — its own value is the evidence ledger (it counts cat/grep as 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 curl with 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 behind python -c or 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

VersionShipsKills this failure
v0.1 ✅G-1 read-before-edit + session ledgerediting 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/wgetciting dead links
v0.4 ✅marketplace plugin packaging, Windows support (python3/python launcher), bundled prompt rule for plain-text claimsinstall 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 verificationmis-anchored ledger when cwd ≠ project root

License

MIT

Ver o original no GitHub

Bom para

Relacionados