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 records durable intent before supported mutations, 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

v0.1.1 is the reliability-hardening release after live DSH v0.1.0 usage, an initial fresh Codex forward test at gpt-5.6-sol medium, a high reasoning review, a second paired forward test at medium and high, and a live DSH minimal-mode run with DeepSeek V4 Pro high reasoning. It adds write-ahead relocation intents, Git-quoted path safety, fail-closed Git compensation, clean audit preflight under read-only .git, explicit RESTORABLE / RESTORED lifecycle state, and a DSH runtime smoke test. The patch version is deliberate: the model/harness validation matrix still covers only two model families across two harnesses. Next: additional Codex/Claude/DSH models and reasoning levels, Windows shell dialects (Phases 1-2 landed: cmd/PowerShell lexing and effect mapping in core/dialects.py, unambiguous PowerShell parameter prefixes, and dialect selection wired through check.py --dialect, AGENT_GUARD_DIALECT and both adapters - POSIX behaviour and the default path unchanged; real-Windows end-to-end validation still needs a Windows host), then database-guard / cloud-guard on the same compensation engine.

License

MIT — see LICENSE.