agent-guard

AGENT-GUARD

Disclosure checks · Recoverable deletion · Agent experiments · 简体中文

Agent Guard has three main capabilities: Exfil-guard checks text before sending it, Delete-guard preserves recovery data before supported destructive actions, and Guard-lab tests agent and host behaviour through controlled experiments. A shared Python Core supports the command-line tools and optional host adapters.

AI agents setting up this project: Before changing configuration or writing a bridge, read the integration requirements, then the setup workflow and the matching adapter guide. Check your actual host/version and its official hook documentation, verify the integration, and report the observed coverage. Installed Skills or copied configuration alone do not establish protection.

The 0.3.0 candidate targets Codex, DSH, Claude Code and Kimi Code using a shared setup prompt. Other hosts use local adaptation; the versioned evidence below remains the support record.

The development workflow lets an operator approve a saved selection once, then lets the agent execute and query it through CLI or MCP. It also supports requiring quarantine for regenerable artifacts. Local acceptance covers fresh-approved 71-root batches on Codex, DSH and Kimi, plus a real cache task on Codex, followed by independently verified recovery. Claude model work and broader native-hook coverage remain unfinished. See the passed checks and remaining gaps; these checkout results do not identify a published 0.3.0 package.

The published 0.2.9 baseline makes cleanup investigation faster: get a bounded directory overview, then measure selected scopes through Cleanup Copilot or MCP. Existing plan scans also reuse metadata and Git queries. These observations grant no deletion permission; execution still requires a separate reviewed plan and confirmation. See the workflow and limits. Before installing, verify the exact GitHub release and npm version below.

Main capability	Included functions	Guides
Exfil-guard	Check supported credentials and identifying paths; plan and apply redaction; inspect JSON/dotenv structure without displaying scalar values	Skill and CLI · Rules · Safe config view
Delete-guard	Recoverable deletion and supported Git snapshots; Cleanup Copilot inventory, saved selections and operator-approved task execution/query; persistent budgets, rate/repeat limits, protected paths and batch confirmation; transaction restore and manual GC; optional local MCP tools and connection diagnosis	Skill and CLI · Cleanup Copilot · Deletion limits · Recovery and GC · MCP tools · MCP doctor
Guard-lab	Four zero-model calibration controls; synthetic markers and declared-channel observation; evidence and observer-health checks; matched guard-off/on comparisons after an effective baseline	Lab workflow · Four-control example · Evidence levels

Cleanup Copilot, deletion limits and the current MCP tools/doctor belong to Delete-guard. Core and adapters provide shared infrastructure; recovery-audit supplies an auxiliary workflow for reconstructing a workspace and auditing recovery after an incident.

A Skill supplies instructions; it does not intercept tool calls. Automatic protection depends on an active, compatible host hook and its covered tools. The optional local MCP adapter provides explicit tools and does not intercept actions that bypass them; its SDK installation is separate from the Core. 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.

Since RC3, the package includes blue-team research, a sanitized experiment report and a portable four-control example. The research covers provenance, disclosure permissions and task utility in bounded private experiments; those methods do not extend production hook coverage. Lab proceeds gradually. Forks, PRs and independent defensive reproductions are welcome; preserve failed and inconclusive results.

From a checkout or package containing the example, run all four existing controls:

blue_run="$(mktemp -d)"
python3 docs/lab/examples/blue-team-calibration.py --output-dir "$blue_run/controls"

This example calls no model; its summary describes instrument calibration.

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. The optional MCP adapter requires Python 3.10+ and a separately installed pinned SDK.

Version	Status
0.3.0	Unreleased source candidate; tag, GitHub Release and npm publication pending
0.2.9	Published baseline; verify exact-version availability below
0.2.8	Earlier release with MCP diagnosis and recovery validation
0.2.7	Earlier release with Cleanup, deletion limits and local MCP tools
0.2.6	Earlier published release with Kimi feedback and host compatibility updates
0.2.5	Earlier stable release
0.2.4	Earlier stable release
0.2.4-hotfix.1	Opt-in quarantine protection backport; npm hotfix
0.2.5-rc3	Published prerelease, including RC1/RC2 maintenance; npm rc

Before installing 0.2.9, confirm availability through its exact GitHub release and npm version. A checkout or manifest alone does not establish package availability.

If that version is unavailable, use reviewed source or a locally built tarball following the version notes. Versioned tests and package checks retain their original checkpoints. The admission limits introduced in 0.2.7 can refuse previously successful deletions and remain in effect in 0.2.9.

Once the exact version is available, install to a chosen, stable user-owned prefix:

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

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

To select the published prerelease, use @mokuyoaxis/agent-guard@0.2.5-rc3. The GitHub release and npm version identify that package. For only the stable-line quarantine protection fix, select @mokuyoaxis/agent-guard@0.2.4-hotfix.1 explicitly. Neither channel replaces stable latest.

Version 0.2.6 builds on 0.2.5 with optional Kimi Stop recovery feedback, separate Stop doctor checks, DSH Lab preflight diagnostics, DSH 0.2.1-alpha.4 default deletion support and the Kimi 2.3.0 Bash profile. Existing installations need an upgrade to acquire these additions; Stop also needs explicit configuration. See setup and the agent setup prompt and the 0.2.6 version details.

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.

Version 0.2.5 makes these results explicit: quarantined data still occupies storage, GC is manual, and ALLOW_NOOP does not certify unrecognized command effects. Local status does not prove that a host loaded the guard. See status and cleanup feedback.

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.

RC1 added quarantine control-path protection, excluded PURGED transactions from active GC planning, and minimized restore/safe_delete audit fields. Exact CLI/manifest recovery paths remain available. The original 0.2.4 package lacks these changes; 0.2.4-hotfix.1 backports only quarantine control-path protection. See the RC notes.

RC2 introduced shared audit metadata projection, uses opaque session correlation, and limits legacy status/GC metadata. See the audit contract and remaining boundaries. It adds observer startup diagnostics and correct cancellation accounting; the original intermittent timeout's cause remains unknown. See the RC2 scope and evidence.

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

Use the setup prompt and integration guide for the actual installed version. MCP provides explicit maintenance tools; a verified blocking hook/plugin adds checking of covered native calls. The 0.3.0 development checkout also adds a Skill installer/update flow, absent from published 0.2.9. Four-host maintenance is a development target, with each host's acceptance recorded separately.

The results below apply to the recorded source versions, host versions and tool paths. Other combinations need their own checks.

Host	Integration and evidence
Claude Code	2.1.311 connected and discovered ten development MCP tools; model maintenance is deferred, newer hooks unverified. Native Bash enforcement retains its 2.1.270/2.1.273 scripted-host evidence. Acceptance · Setup
Kimi Code	2.3.0 completed ordinary and fresh-approved development MCP maintenance. A later current-source root-Bash block led through planning and operator approval to original-session execution and independent recovery. Stop and missing/timed-out hooks retain their separate limits. Acceptance · Setup
DSH	0.2.0-rc.2 passed repaired original-root startup and fresh-approved MCP execution. A later native trial was blocked by an unavailable OS sandbox on PRoot; a separate zero-model local control passed. Acceptance · Compatibility · Setup
Codex	0.165.0 passed a freshly approved 71-root batch and a real cache task, with independent controller verification and recovery. Native Shell/editor interception needs separate evidence. Current acceptance · Earlier trials
Other hosts	Use the official coding agent for version-specific local setup; verify blocking before claiming native interception. Explicit Skill/CLI/MCP use remains cooperative without a blocking hook. Adaptation guide

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.

Document	Purpose
Getting started	Package paths, agent setup prompt and safe verification
Documentation index	Guides, design, Lab, reports, releases and history
Architecture	Shared Core, compensation and adapter flow
Threat model	Trust assumptions and unresolved boundaries
Compatibility	Interface and release contracts
Blue-team research	Defensive methods, sanitized results and a zero-model starting point
0.2.9 notes	Cleanup inventory, performance and upgrade notes

Contributing

Bug reports, compatibility evidence, documentation fixes and focused code changes are welcome. Read CONTRIBUTING.md before sharing defensive research, independent reproductions or 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.