agent-guard

Make destructive agent actions reversible by default.
简体中文

Agents increasingly run shell commands autonomously. When the command is
rm -rf, a wrong variable or one misjudged context switch is all it takes
to lose a repository — or worse. agent-guard makes destruction reversible
by default and audited always, across any harness that can run Python.

Agent Guard is not an approval system. It is an automatic recovery
system with human escalation. The agent works uninterrupted while
operations stay reversible; only when the guard cannot safely automate —
but user intent may be legitimate — does a decision escalate to a human.

It is reliability infrastructure, not a security sandbox: it defends
against mistakes, not against a malicious agent with equal OS privileges.

The four pillars

A rule runs through all four: uncertainty increases restriction.

How it decides

The stable interface is not allow/block — it is a Decision Protocol:

Effect → Classifier → Policy → Decision   ∈ { ALLOW, RELOCATE, SNAPSHOT,
                                            ASK, BLOCK }
                                + ReasonCode   (stable, machine-readable)
                                + Explanation  (human-facing)
                                + RecoveryPlan (txids, strategy)

True effect-uncertainty ($VAR targets, bash -c, find -delete,
stdin-fed lists) stays on the BLOCK path: allowing it would forfeit the
core guarantee. Adapters map decisions onto their harness natively — DSH
PreToolDecision, Claude Code PreToolUse ask, or a deny carrying the
explanation where no ask exists.

Quickstart

Zero third-party dependencies. Requirements: Python 3.9+, POSIX shell,
git.

# delete something - it is quarantined, not destroyed:
python3 skills/delete-guard/scripts/safe_delete.py build/ --reason "stale"

# inspect and undo:
python3 skills/delete-guard/scripts/status.py
python3 skills/delete-guard/scripts/restore.py list
python3 skills/delete-guard/scripts/restore.py <txid>

# quarantine maintenance (dry plan by default):
python3 skills/delete-guard/scripts/gc.py

Harness adapter - intercept before executing any shell command:

python3 skills/delete-guard/scripts/check.py --enforce -- "$COMMAND"
case $? in 0) run "$COMMAND" ;; 2) refuse ;; 3) ask-the-human ;; esac

What gets protected

rm -rf build/            → RELOCATE  (tree quarantined, command proceeds)
rm -rf .                 → BLOCK     (workspace root)
rm -rf $DIR/             → BLOCK     (unresolvable target: fail closed)
rm *.log                 → BLOCK     (opaque glob; safe_delete expands it)
cd X && rm -rf build     → ASK_ONCE  (COMPOUND_CWD_DELETE)
touch f && rm f          → ASK_ONCE  (COMPOUND_CREATE_DELETE)
git clean -fd            → RELOCATE  (enumerate via -n, relocate, proceed)
git reset --hard         → SNAPSHOT  (stash first, apply to recover)
git push --force         → BLOCK     (remote history is never automated)
node_modules/ (ignored)  → ALLOW     (provably regenerable)
quarantine full          → BLOCK     (never fall back to permanent delete)

Adapters

Cross-harness guarantee, enforced by tests/test_conformance.py:
identical command + cwd + workspace state must produce identical core
decision + reason code through any adapter.

Repository layout

agent-guard/
├── skills/delete-guard/   # agent-facing skill: SKILL.md + CLI scripts
├── core/                  # classifier · policy · recovery · audit
├── adapters/claude/       # Claude Code PreToolUse hook adapter
├── tests/                 # unittest suites incl. cross-harness conformance
└── docs/                  # architecture · threat-model · friction log

Skills guide agent behavior; constraints live in Core. Future
git-guard, database-guard, cloud-guard skills plug into the same
compensation engine without restructuring.

Documentation

Status & roadmap

V1 hardening complete; v0.1.0 release gate: CI (this repository),
retention policy documented, Claude adapter conformance green.
Next: second live adapter verification, retention automation,
Windows dialects (demand-driven), then database-guard /
cloud-guard on the same compensation engine.

License

MIT — see LICENSE.