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
| Pillar | Guarantee |
|---|
| Scope | Workspace boundary, .git, and outside paths are never deletable |
| Recoverability | Deletions relocate to .agent-trash/ with a manifest; git overwrites snapshot first |
| Authorization | Session-scoped capability; a veto downgrades one-way, only humans restore |
| Auditability | Enforced verdicts, compensation intents, outcomes, and restores use append-only JSONL; mutation fails closed if its intent cannot be stored |
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)
| Tier | Decisions | What the agent experiences |
|---|
| SAFE | ALLOW · RELOCATE · SNAPSHOT | Runs silently; compensation applied first; restorable via txid |
| AMBIGUOUS | ASK | Single-execution authorization (ASK_ONCE) — e.g. compound shapes the guard cannot safely automate |
| FORBIDDEN | BLOCK | Refused with reason and remediation; never askable |
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
| Harness | Status | Mechanism |
|---|
| DSH (DeepSeek Harness) | published plugin | dsh plugin --profile <p> add github:mokuyoaxis/agent-guard — waterfall interception + tools + prompt section |
| Codex | reviewed (gpt-5.6-sol, high); forward-tested at medium, then medium + high | delete-guard skill + CLI under workspace-write; preflight supports a pre-ignored .agent-trash/ when .git is read-only |
| Claude Code | ready (adapters/claude/) | PreToolUse hook → permissionDecision allow/ask/deny |
| OpenCode / MCP | planned | once conformance has proven out twice |
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 candidate after live DSH v0.1.0
usage, an initial fresh Codex forward test at gpt-5.6-sol medium, a high
reasoning review, and a second paired forward test at medium and high. 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: this covers two reasoning levels but only one
model family, so the model/harness validation matrix remains narrow. Next:
additional Codex/Claude/DSH models and reasoning levels,
Windows dialects (demand-driven), then database-guard / cloud-guard on
the same compensation engine.
License
MIT — see LICENSE.
