AGENT-GUARD

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

Agent Guard is reliability infrastructure for coding agents. It provides recovery before supported destructive actions, checks text before disclosure, and gives users a Lab for testing observed agent and harness behaviour. The shared Python Core works through explicit CLIs and optional host adapters.

A Skill supplies instructions; it does not intercept tool calls. Automatic protection depends on an active, compatible host hook and its covered tools. Agent Guard is not an OS sandbox against a malicious process with equal privileges. The capability matrix states the observed coverage and gaps.

guard-lab: test with evidence

guard-lab is a user-controlled experiment tool. It puts non-secret, synthetic markers and harmless bait into a disposable project and observes only declared channels. The real controller and evidence stay outside the fixture given to the tested agent.

Its workflow separates three questions:

1. Calibrate: do the observer, markers, scans and evidence chain work? Built-in controls call no model and make no external-network request.
2. Observe exposure: does an unguarded real-harness trial trigger the selected channel?
3. Compare protection: after an effective baseline, does a matched guarded trial reduce or block that exposure?

Start with one zero-model control from the package or checkout root:

lab_run="$(mktemp -d)"
python3 guard_lab.py run --case clean --output-dir "$lab_run/clean" --json

The other controls are mock-positive, mock-injection and snapshot-positive. Run all four before a real-harness experiment, following the Lab guide. Installed packages also expose agent-guard-lab.

A control PASS means instrument calibration, not model safety. An unhealthy observer or missing evidence is INCONCLUSIVE; a quiet guard-off baseline cannot establish mitigation. Matched comparisons require the same relevant harness/version/model, task, protocol and non-guard configuration. Lab results cover the declared channels, not every file read, external transfer or model request. Existing Kimi and DSH reports retain their bounded results, failures and review states.

Install and choose a version

Python 3.9+ and Git are required for the Core. The examples use a POSIX shell; native bridges and optional capture helpers have their own requirements.

For the published stable package, use a chosen, stable user-owned prefix:

npm install --prefix /absolute/path/to/agent-guard-install @mokuyoaxis/agent-guard@0.2.4

The package root is /absolute/path/to/agent-guard-install/node_modules/@mokuyoaxis/agent-guard. The exact scoped package name matters. A source checkout is also usable:

git clone https://github.com/mokuyoaxis/agent-guard.git
cd agent-guard

For the RC, select @mokuyoaxis/agent-guard@0.2.5-rc1 explicitly; the RC channel does not replace stable latest. Check the GitHub release or npm version for publication. A reviewed checkout or locally supplied tarball is also usable. See setup and the agent setup prompt.

Recover a supported deletion

From the workspace being protected, point at your package/checkout root:

python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/safe_delete.py src/old_module.py --dry-run
python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/safe_delete.py src/old_module.py
python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/restore.py list
python3 /absolute/path/to/agent-guard/skills/delete-guard/scripts/restore.py <txid>

Valuable targets are relocated with exact recovery paths in a manifest. Provably regenerable, Git-ignored artifacts may be deleted directly. Supported Git overwrites snapshot tracked state; hard-reset collisions with untracked/ignored content are refused. Force restore preserves the current occupant before replacement. Errors can leave partial work: inspect the reported transaction IDs, filesystem and state before retrying.

Advisory check.py and safe_delete.py --dry-run preserve command targets but may write quarantine/audit metadata and a Git local exclude entry. Advisory exit 0 is not permission to execute a BLOCK or ASK. See the policy and assessment contract.

The RC adds quarantine control-path protection, excludes PURGED transactions from active GC planning, and minimizes restore/safe_delete audit fields. Exact CLI/manifest recovery paths remain available. These changes are not in the published 0.2.4 package; see the RC notes.

Check text before emission

The payload owner invokes the scanner and applies its decision. For a text file:

python3 skills/exfil-guard/scripts/check_span.py --channel file-write --json < draft.md
python3 skills/exfil-guard/scripts/sanitize.py --channel file-write < draft.md

A complete synthetic credential example is generated at runtime:

python3 -c 'print("config: sk-proj-" + "AbCdEf0123456789GhIjKl")' |
  python3 skills/exfil-guard/scripts/sanitize.py --channel file-write

The expected output is config: sk-<REDACTED>. The checker returns a decision and plan; it never rewrites the payload. Its exit 0 means ALLOW/SANITIZE assessment, while the sanitizer's successful stdout is the allowed or rewritten text. ASK/BLOCK/error withholds sanitizer payload output.

Detection covers documented credential shapes, value-free secret references and selected host paths. It is not a general repository scanner or protection against deliberate obfuscation. The text CLIs do not automatically append egress audit events; a trusted integration owns emission and any audit storage. For configuration inspection, an explicit safe view reports supported JSON/dotenv structure without scalar values; it is not an editable copy or automatic read interception.

Read the Skill, rules and exemption diagnostics, and channel contract.

Connect your coding agent

These are version-specific historical observations. They do not certify a new source candidate, every tool or every subagent path.

Use the full capability and evidence matrix for precise versions, tests and gaps. doctor.py kimi|claude --probe checks a selected configuration and local adapter path; PASS does not prove a live host loaded the hook. Drift checks are local preflight. A live sentinel is explicit, may consume provider quota, and covers only its sampled root Bash call. See the host drift guide.

Decisions, recovery and documentation

The shared protocol is ALLOW · SANITIZE · RELOCATE · SNAPSHOT · ASK · BLOCK, with stable reason codes and explanations. Aggregation is BLOCK > ASK > RELOCATE/SNAPSHOT > SANITIZE > ALLOW. Opaque targets and protected boundaries are refused; supported recoverable mutations compensate before proceeding. Authorization state remains a local discipline, not an isolated identity boundary.

After an incident, recovery-audit helps recover from surviving Git/session/cache evidence, distinguishing original bytes, reconstruction and known gaps. It cannot recreate bytes that no source kept.

Contributing

Bug reports, compatibility evidence, documentation fixes and focused code changes are welcome. Read CONTRIBUTING.md before sharing logs. Use Issues and Pull Requests; keep credentials, private configuration and unredacted incident records out of public reports.

Community

This project-made banner links to our LINUX DO project post. It does not imply official endorsement by the community.

License

MIT — see LICENSE.