Project / Agent & Engineering
Agent Guard
Quarantine before deletion, snapshots, and recovery records.
Reliability infrastructure for coding agents: quarantine before deletion, pre-overwrite Git snapshots, exfiltration checks, and reproducible experiments.
0.2.9 stable · npm latest
Overview Project overview
Agent Guard targets destructive operations by coding agents: quarantine before deletion, snapshots before supported Git overwrites, text exfiltration checks, and guard-lab for counterfactual experiments. It is recovery and audit infrastructure rather than yet another sandbox.
Motivation Why it exists
Once an agent runs rm, git reset, or writes text containing credentials, the damage is often irreversible. Agent Guard replaces “cause the damage first, remediate later” with “establish a recovery point first, then allow the action” — escalating to ASK or BLOCK when uncertain.
Architecture Key architecture
- A shared Python Core works through an explicit CLI with optional host adapters; the Skill provides protocol documentation and does not itself intercept tool calls.
- The decision protocol is ALLOW · SANITIZE · RELOCATE · SNAPSHOT · ASK · BLOCK, aggregated as BLOCK > ASK > RELOCATE/SNAPSHOT > SANITIZE > ALLOW.
- delete-guard handles quarantine and recovery, exfil-guard handles credential and path checks, guard-lab handles zero-model counterfactuals and controlled experiments, and recovery-audit handles post-hoc evidence assembly.
Capabilities Capabilities
- Before deletion, valuable targets are relocated into quarantine with precise recovery paths recorded in a manifest; recoverable Git overwrites snapshot tracked state first.
- Checks supported credential shapes and host paths, sanitizing or withholding payloads per policy; checkers only return decisions and never rewrite text themselves.
- guard-lab provides four zero-model counterfactuals — clean, mock-positive, mock-injection, snapshot-positive — keeping observation, exposure, and protection comparisons separate.
- Historical adapter observations cover Claude Code, Kimi Code, DSH and other hosts, with the version and tool scope of each documented.
- 0.2.7 adds Cleanup Copilot, shared deletion admission with protected paths and budgets, and optional local stdio MCP tools. Cleanup execution requires an unchanged reviewed plan and explicit terminal confirmation, and still routes through safe_delete.
- 0.2.8 adds a local MCP doctor for interpreter/SDK handshake, tool inventory, workspace/quarantine binding, and recovery checks after lost responses; it remains a cooperative MCP interface, not host-level interception.
- 0.2.9 adds bounded Cleanup inventory (--discover / --measure --scope) and read-only MCP cleanup_discover / cleanup_measure tools; plan scans reuse file metadata and batch Git queries.
Limitations Known limitations
- Not an OS sandbox; it cannot stop a malicious process with equal privileges.
- Automatic protection depends on the host providing a compatible blocking hook; the Skill itself cannot intercept tool calls.
- The text CLI does not automatically emit outbound audit events; audit storage is the responsibility of a trusted integration.
- Detection covers documented rules, not general repository scanning, and is not aimed at deliberate obfuscation.
- Stop-hook feedback is opt-in and model delivery remains UNVERIFIED; missing or timed-out hooks can still allow tools in the sampled hosts.
- New deletion budgets and protected-path rules can refuse operations that were previously allowed. Local MCP is a cooperative tool interface, not shell, session, or host-level interception.
- A doctor PASS covers the selected service only; host connection, model delivery, and host interception remain UNVERIFIED. It does not install dependencies or rewrite client configuration.
- Cleanup inventory cannot authorize deletion; cache labels are hints, protected or unmeasured sizes remain unknown, and scanning does not coordinate application cache locks. 0.2.9 expects seven MCP tools, so upgrade doctor and server together.
Validation Testing & validation
- The repository includes CI plus test reports scoped by host and version; the Kimi and DSH reports retain failures and uncertain results.
- A guard-lab PASS means the instrument is calibrated, not that the model is safe; without a valid baseline the result is INCONCLUSIVE.
- 0.2.9 is the stable GitHub and npm latest release; local candidate validation passed 1197 Python cases and both Node groups, with all 16 real MCP protocol, doctor, and interruption cases executed.
- CI and the release workflow enforce the updated 1198-case suite before publication; this is a bounded maintenance release, not a new feature line.
- Optional local MCP tools were exercised with actual stdio deletion, restoration, persistent budgets, protection and batch-gate checks; the MCP SDK remains a separate installation.
- Kimi 2.3.0 acceptance covers eight prompt-CLI and eight ACP fixed-loopback paths; no external model calls were made, and Stop delivery is not a general guarantee.
- Versions and coverage follow the repository's capability matrix and release notes.