AGENT-GUARD

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

Agent Guard is a reliability layer for coding agents. It makes supported high-impact actions recoverable instead of permanently destructive, while keeping routine work automatic.

• Destructive file operations can be relocated to .agent-trash/ with a recovery manifest instead of being permanently deleted.
• Destructive Git operations can snapshot recoverable state before they overwrite the working tree.
• Accidental outbound disclosure of known credentials or host-identifying absolute paths can be checked through a cooperative text CLI. A caller that owns the emission can apply its redaction plan, escalate, or block.
• Synthetic honeytoken experiments can exercise declared local channels with zero-token controls and fail-inconclusive evidence health checks.

The Core is harness-neutral and supports Python 3.9+ and Git. Automatic interception still depends on whether the host exposes a compatible hook; a Skill by itself does not intercept tool calls. The shared Core, Decision Protocol, and Skills define the product; harness adapters are replaceable integration bridges rather than the product boundary.

Agent Guard keeps reversible actions automatic and escalates only when it cannot safely automate them. It is reliability infrastructure, not a security sandbox: it protects against mistakes, not a malicious agent with equal OS privileges.

What it looks like

rm -rf build/       → RELOCATE   # an in-scope tree moves to quarantine
rm -rf .            → BLOCK      # the workspace root is protected
git reset --hard    → SNAPSHOT   # snapshot first when Git state supports it
git push --force    → BLOCK      # remote history is not automated

These are illustrative verdicts for supported inputs, not commands to run or proof that every harness intercepts them. Ignored, regenerable targets may be ALLOW; a Git snapshot that cannot be made fails closed. When recovery or safe rewriting is possible, the agent can keep working. Otherwise, the guard asks the human or blocks the operation.

Quick start with your coding agent

Use the scoped npm package or a stable Git checkout. The unscoped agent-guard package is unrelated to this project.

Pinned npm installation into a stable, user-owned prefix:

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

0.2.3 combines Windows/Core fixes, information-protection improvements and the offline guard-lab MVP. See the release notes for scope and evidence limits. The npm badge and GitHub Releases show which artifacts are available.

The package root is then /absolute/path/to/agent-guard-install/node_modules/@mokuyoaxis/agent-guard. Alternatively, clone the source (skip this if you already have a checkout):

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

Python 3.9+ and Git are required for the Core; native interception depends on the host's hook support. Then give your coding agent the following setup prompt (replace the path with your checkout):

Set up agent-guard for this workspace. Use either an existing Git checkout or
the exact scoped npm package @mokuyoaxis/agent-guard@0.2.3;
never install the unscoped package named agent-guard. If 0.2.3 is unavailable,
report that and use the existing checkout or ask me to choose a published
version. Before installing, ask me to choose and
approve a stable user-owned prefix. Treat the checkout or installed package
root as /absolute/path/to/agent-guard below.
First identify the current harness and its actual hook/skill capabilities;
read this README and the matching adapter README. Check Python and Git.
Install the relevant Skills, then configure a native shell hook only if this
harness supports one. Preserve existing settings and show me the proposed
diff before editing user-wide configuration or installing dependencies.
For Claude Code use adapters/claude/README.md; for Kimi Code use
adapters/kimi-code/README.md; for DSH use adapters/dsh/README.md.
For another host, read adapters/INTEGRATION.md and do not invent a native
hook. If no blocking pre-tool hook is verified, use only Skill/CLI and say
plainly that automatic interception is not enabled.
Verify a harmless command and pass a BLOCK-shaped command only as data to
check.py; never execute a destructive test command. For Claude/Kimi, run the
local doctor but do not treat its PASS as proof of host interception. Report
the host version, tool coverage, what was installed, what the host actually
intercepted, and any unverified paths.

For manual setup and evidence limits, see the adapter matrix and the adapter README for your host.

Design principles

Principle	Guarantee
Stay in scope	The guard blocks deletion of the workspace root, .git, and outside paths when the operation reaches it
Make it recoverable	Supported deletions relocate to .agent-trash/ with a manifest; destructive Git overwrites snapshot first
Constrain authorization	Authorization is session-scoped; a veto downgrades one-way, and only a human restores it
Leave a durable trail	Enforced verdicts, compensation intents, outcomes, and restores use append-only JSONL; mutation fails closed if its intent cannot be stored

One rule runs through all four: uncertainty increases restriction.

How it decides

Each inspected operation is classified by its effect and then mapped to the least restrictive decision that preserves the relevant safety or recovery guarantee. The stable interface is a Decision Protocol, not a binary allow/block check:

Effect → Classifier → Policy → Decision   ∈ { ALLOW, SANITIZE, RELOCATE,
                                            SNAPSHOT, ASK, BLOCK }
                                + ReasonCode   (stable, machine-readable)
                                + Explanation  (human-facing)
                                + RecoveryPlan (txids, strategy)

Tier	Decisions	What the agent experiences
SAFE	ALLOW · SANITIZE · RELOCATE · SNAPSHOT	Runs silently; compensation is applied first where needed; recoverable mutations are restorable via txid. SANITIZE returns a plan for the payload owner to rewrite (not a command rewrite)
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

Precedence when several decisions meet in one operation, weakest to strongest:

ALLOW < SANITIZE < RELOCATE < SNAPSHOT < ASK < BLOCK

SANITIZE ranks below ASK deliberately: it is automatic (SAFE tier), while ASK forfeits automation. A payload carrying both a sanitizable secret and a shape that cannot be rewritten must ASK — you cannot silently proceed when part of the emission is uninspectable.

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.

What Agent Guard includes

delete-guard

Answers "if this destroys something, can we come back?" It runs before a delete or destructive Git action when invoked through a supported adapter or CLI, and compensates first when recovery is possible.

exfil-guard

Answers "if this leaves the machine, was it supposed to?" Its cooperative CLI checks text before an emission when the payload owner invokes it, returning a redaction or escalation decision for supported patterns.

recovery-audit

The incident-response companion for cases where prevention never ran or did not cover the path. It establishes source precedence, distinguishes recovered bytes from reconstructed behavior and known gaps, audits replay tooling, and keeps landing, commit, push, and release as separate authorization gates.

delete-guard and exfil-guard are the two preventive guard branches; recovery-audit handles evidence-led recovery after the fact.

recovery-audit

Sometimes prevention never ran: a harness had no adapter, a subagent bypassed the expected path, or an over-broad command removed the workspace before anyone could intervene. The working tree may be gone while the coding agent's session cache still preserves successful patches, file snapshots, tool results, diffs, and command context.

recovery-audit turns those remnants, Git remotes/reflogs/stashes, editor or tool caches, build artifacts, and project plans into an evidence-led recovery:

• every unit is labelled recovered, reconstructed, or missing;
• recorded tool effects are replayed in chronology and checked for divergence;
• repeated replay must produce a byte-identical tree;
• landing, commit, push, and release remain separate authorization gates.

It is not filesystem undelete and cannot recreate bytes no surviving source captured. Its promise is a fast, auditable path to the strongest project state the evidence actually supports, with gaps reported instead of hidden.

exfil-guard

exfil-guard checks text before an agent writes, sends, commits, or pushes it when the payload owner calls its CLI. It also offers an explicit, read-only safe view of selected JSON/dotenv configuration files. The text scanner is designed to catch two accidental disclosure classes: known credentials and host-identifying absolute paths. Depending on the channel, it can allow the payload, return a redaction plan, ask for a human decision, or block the emission.

DSH also offers a default-off text-read redaction prototype for complete native reads in a pinned composition. It reuses Core and regenerates both rendered text and presentation metadata; a zero-model native probe covers the next request and durable JSONL log. A separate official Flash direct-read trial observed supported synthetic-secret redaction while useful config stayed readable.

It is a prevention and redaction guard, not a compensation engine: after an emission there is nothing to recover. It is also not a security sandbox and does not attempt to stop adversarial exfiltration by an agent with equal OS privileges.

Decisions exfil-guard can return

The full Decision Protocol applies, but only four classes are reachable for a text payload (RELOCATE/SNAPSHOT belong to delete-guard — the guard cannot rewrite what it did not write):

Decision	Meaning	Example
ALLOW	nothing matched, a documented placeholder, or a workspace-relative path	echo "hello" | check_span.py
SANITIZE	a redaction plan is returned; the payload owner rewrites and emits	a real key on file-write / llm-request
ASK	the channel cannot be rewritten and cannot be taken back	a host path on shell-stdout
BLOCK	refuse: immutable/remote history, an un-scannable payload, invalid config	a credential in git-push-payload

What is detected

T1 vendor credential patterns (secret/*). These rules use known formats; documented placeholders and negative examples constrain false positives. Rule ids: secret/openai-key, secret/github-token, secret/aws-access-key-id, secret/gitlab-token, secret/slack-token, secret/stripe-key (live keys only — sk_test_ is exempt), secret/pypi-token, secret/jwt (structural: the header must decode to JSON with a nonempty ASCII string alg), and secret/private-key-block (whole -----BEGIN ... PRIVATE KEY----- block, redacted in one piece). See skills/exfil-guard/references/rules.md for the rule table and remaining ambiguities.

secret/connection-password also detects nonempty passwords in URI userinfo. It redacts only the password, preserving the scheme, account and host for diagnostics. Percent-encoded passwords and JSON-escaped scheme slashes are supported; this does not hide network topology or scan every DSN format.

Value-free secret references (secret/source-reference). The guard classifies complete components in an environment variable's name (such as KEY, TOKEN, SECRET, PASSWORD, PASSWD, CRED, or AUTH) and a secret-store file name (.env, *.pem, id_rsa*, .netrc, kubeconfig, ...), and detects whole-environment expansions (printenv, env | ..., cat /proc/self/environ). This scanner does not resolve the variable value; that does not certify unrelated Guard output or existing audit records as secret-free.

Host-identifying paths (path/*). path/workspace-relative is ALLOW (the workspace is exempt); path/system (/usr, /etc, C:\Windows) is ALLOW; path/host-absolute (under HOME/TEMP, a CI root, or a workspace ancestor) is SANITIZE; path/generic-absolute (no host correlation) is ASK; path/device (UNC, \\?\, pipes) is SANITIZE.

Channels determine the disposition

A channel is defined by two facts: can it be rewritten, and does the emission persist? rewritable is what makes SANITIZE meaningful; persistence is what justifies BLOCK.

Channel	Rewritable	Persistence	Default
llm-request	yes	remote	SANITIZE
file-write	yes	workspace	SANITIZE
forge-comment / issue-body / pr-description	yes	public	SANITIZE
git-commit-message	yes (rewrite argv)	remote history	BLOCK
git-push-payload	no	remote	BLOCK
shell-stdout	no	local transcript	ASK
shell-file-redirect	yes	local	ASK
archive-upload	yes	remote	ASK
process-argv	yes	local	ASK

An unknown channel name is a configuration defect, not "no risk": check_span.py returns BLOCK_OUTPUT_UNSCANNABLE, never an implicit ALLOW.

Usage

check_span.py reads the payload on stdin and is a pure function — it never writes, never rewrites, and never prints the match. sanitize.py applies the plan the guard returned.

# a credential on a rewritable channel -> SANITIZE, exit 0
echo 'config: sk-proj-AbCdEf…' | python3 skills/exfil-guard/scripts/check_span.py --channel file-write

# a credential bound for remote history -> BLOCK, exit 2
echo 'token=ghp_abcdefghijklmnopqrstuvwxyz…' | python3 skills/exfil-guard/scripts/check_span.py --channel git-push-payload

# apply the redaction plan (format preserved: sk-<REDACTED>)
echo 'config: sk-proj-AbCdEf…' | python3 skills/exfil-guard/scripts/sanitize.py --channel file-write

Exit code contract: 0 = ALLOW/SANITIZED · 2 = BLOCK · 3 = ASK · 1 = ERROR. Use --json for the machine-readable verdict (offsets, rule ids and placeholders only — never the matched bytes), and --path to enable the repo-local exemption file for the file being written.

sanitize.py enforces the same exit codes: ASK/BLOCK and errors emit no payload on stdout. It validates an external --plan against the current scan and rescans the rewritten text before emitting. Both CLIs use the same default workspace and host-side mode; stdin is bounded to the scan cap (4 MiB by default) during reading, as is an external plan file. A checker plan produced with an explicit mode or path exemption must still satisfy the sanitizer's current policy; the plan itself does not authorize emission.

Credential detection covers classic and stateless ghs_APPID_JWT GitHub installation tokens, including long signatures and credentials next to CJK prose. Placeholder exemptions require whole shapes; incidental example words inside a token do not exempt it. Secret variable references are classified by complete name components, preserving ordinary identifiers such as MONKEY and metadata such as TOKEN_COUNT. See the rule reference for supported forms and limitations.

PyPI publishing tokens are also detected with their documented prefix and minimum body shape, with complete redaction of long tokens. AWS group/user/ role/policy IDs are kept distinct from access-key IDs; JWT headers require the declared nonempty ASCII string alg. Public-key variable names and the broad legacy sk- shape retain their documented conservative boundaries.

Read a config without printing its values

Introduced in the 0.2.0 source; this CLI is not in the earlier 0.2.0-rc2 preview tag.

python3 skills/exfil-guard/scripts/view.py --workspace /path/to/workspace .env
python3 skills/exfil-guard/scripts/view.py --workspace /path/to/workspace config.json

The path must be relative to that workspace. The JSON output preserves field names and structure, plus scalar types and set/empty states, but never scalar values. Known secret-shaped field names are hidden; unknown secrets in field names remain a limitation. Only UTF-8 JSON and a strict, single-line dotenv subset are supported (256 KiB maximum, 16 levels, 2048 nodes). The CLI refuses symlinks, hardlinks, special files, unsafe paths, malformed input, and platforms without safe descriptor-relative reads. Exit 0 means a view was produced, 2 means refused, and 1 means an internal error. This view is for diagnosis only: do not write it back over the original config. It does not intercept ordinary file reads made by a harness.

Relationship to delete-guard

They are two halves of the same promise, on opposite sides of the action:

	delete-guard	exfil-guard
Question	"can we come back?"	"was this supposed to leave?"
Guards	before a delete	before an emission
Response	compensate, then proceed	redact, then emit
Failure cost	recoverable via txid	irreversible
Entry point	check.py -- <command>	check_span.py (stdin)

They share the vocabulary (core/policy.py), the aggregation (worst()), the exemption discipline, and the audit log. worst() is shared by both guards, which is why SANITIZE had to be ranked once, not twice.

Coverage and limitations

This is stated plainly, because a reliability tool that overstates its reach is a false security claim:

• Not a sandbox. It does not prevent adversarial exfiltration. An agent that obfuscates a secret to evade the scanner is out of scope; this catches accidents.
• Channels with no hook are unreachable by construction. A hosted model call with no proxy, the model's own tool calls, content produced inside a program, and the human clipboard get no verdict at all — no coverage is claimed there. See references/channels.md and docs/secret-guard-analysis.md §2.4 for the reachability table this claim is traceable to.
• Not a file scanner. It is not a gitleaks replacement; it scans what the guard can see on the way out.
• No history rewriting. Detecting a secret already in Git history is a report at most. Rewriting history is a human action with its own risks.
• No T3 entropy detector in this release. Random-looking text alone is insufficient evidence of a credential; ordinary identifiers stay readable.

Manual, harness-neutral usage

The Core has zero third-party dependencies. Requirements: Python 3.9+, POSIX shell, and 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

A harness adapter can invoke the guard before a supported shell command and map its exit status to the host's own tool decision:

python3 skills/delete-guard/scripts/check.py --enforce -- "$COMMAND"
exit 0 → host may run the original command
exit 2 → deny
exit 3 → ask the human if supported; otherwise deny
exit 1 → guard error; fail closed

What gets protected

These examples assume the command reaches the guard and its targets meet the stated conditions; see the capability matrix for what each host has actually demonstrated.

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  (when a Git snapshot can be made)
git push --force         → BLOCK     (remote history is never automated)
node_modules/ (ignored)  → ALLOW     (provably regenerable)
quarantine full          → BLOCK     (never fall back to permanent delete)

Integration and validation matrix

These badges link to scoped evidence; they do not certify every tool or model. The DSH text-read feature is optional and off by default.

"The Core works", "a Skill-guided agent used it", and "the harness intercepts every matching tool call" are separate claims. This table keeps those evidence levels explicit:

Harness / tested version	Integration path	Evidence and limit
Claude Code 2.1.270 / 2.1.273	Native PreToolUse for Bash	Real CLI + scripted model: sampled allow/ask/deny and Python-startup failure; other tools unverified.
DSH 0.1.5-rc.1	Native pre-execute adapter	Real-host packaged-plugin probe: execution-level BLOCK and loaded-adapter Core failure. A real-model Lab baseline stayed quiet with guard off, so no L2 mitigation claim exists; model-proposed destructive bash enforcement remains unverified. The separate opt-in read path is listed below.
DSH CLI rc.1 / tools and FS rc.2 / Node 22	Experimental text-read redaction, default off	Zero-model native probe: next request and durable JSONL. Official Flash direct-read off/on: supported synthetic secrets redacted in tool content/meta/session, useful config preserved; no injection L2 claim.
DSH 0.2.0-rc.2 / Node 22	Default deletion and optional text-read adapter	Fresh contract review: native deletion blocking, read redaction on reviewed local/sandbox FS, next synthetic request and durable JSONL. Native v4 Lab support remains bounded; no new real-model L2 result.
Codex CLI 0.154.0 (tested session)	Skill + production CLI	Older-source cooperative acceptance; no native hook claim.
WorkBuddy (version not recorded; Windows 11)	Core / CLI	Community feedback on 0.2.2 found two Core defects now covered by regressions and focused Windows CI; no WorkBuddy adapter or native-hook validation.
ZCode (version unrecorded; win32)	Historical Skill/CLI + hook trial	Older hook observation includes a persistent-permission bypass; current version unverified.
Kimi Code 0.42.0 / 2.1.1	Native PreToolUse for Bash	Bounded tests: authenticated 2.1.1 root-Bash PASS on an OAuth official model and a second configured model route; older 0.42.0 root/child BLOCK, ASK denial and Python-failure refusal. Hook absence/timeout remains fail-open.
Other / unlisted hosts	Self-adaptation guide	No native claim without a blocking pre-tool event and independent non-execution check.

For agent-led setup: identify the actual host version and tool names, follow the matching guide above, preserve existing settings, then report separate configuration, local-probe, and real-host evidence. For an unlisted host, follow the self-adaptation checklist; a prompt or adapter exit code alone is not proof of interception. Ask before changing user-wide settings, security policy, or dependencies.

tests/test_conformance.py checks the shared Core and Claude adapter; DSH has a smoke test and Kimi has targeted adapter tests. The Kimi observations above cover only the tested calls, not every shell construct or a general concurrent-agent safety guarantee. Run python3 doctor.py kimi --probe or python3 doctor.py claude --probe to check a selected configuration file and the local shell bridge without a model call. Add --json for machine-readable configuration, local_probe, and host_interception statuses. The last status is always UNVERIFIED: this doctor cannot prove that a live session loaded or enforced the hook. Add --check-drift to query the local host version and compute privacy-safe configuration/runtime fingerprints. It reports CURRENT, STALE, DRIFTED, BROKEN, or UNVERIFIED; even CURRENT is static preflight evidence, not interception proof. Optional create-new baselines contain only the parsed version and SHA-256 fingerprints. See the host drift guide for the status and baseline contract. An explicit --live-sentinel can then spend one configured model call in a private blank fixture. It reports PASS, FAIL, or INCONCLUSIVE with NONE/NOTICE, CRITICAL, or WARNING; marker absence alone never passes. It retains a hashed/redacted result but not raw model output. This is a reliability probe for a trusted provider, not a sandbox for a malicious model. The optional Kimi doctor needs Python 3.11+ for TOML parsing; the Core and hook adapter continue to support Python 3.9+. See the Kimi and Claude adapter guides. See harness capabilities and evidence levels for the per-host scope and execution-level acceptance criteria.

Repository layout

agent-guard/
├── skills/delete-guard/   # agent-facing skill: SKILL.md + CLI scripts
├── skills/exfil-guard/    # egress skill: check_span.py · sanitize.py
├── skills/recovery-audit/ # evidence-led repository audit and recovery
├── core/                  # classifier · policy · recovery · audit · redaction
├── doctor.py              # local configuration, probes, and drift preflight
├── live_sentinel.py       # opt-in real-host sentinel and alarm evidence
├── guard_lab.py           # user-controlled offline synthetic honeytoken lab
├── adapters/INTEGRATION.md # checklist for an unlisted host
├── adapters/claude/       # Claude Code PreToolUse hook adapter
├── adapters/kimi-code/   # Kimi Code PreToolUse hook adapter
├── adapters/dsh/          # DeepSeek Harness integration bridge
├── adapters/codex/harness/# CLI acceptance driver; not a native hook
├── 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

Read	For
CONTRIBUTING.md	how to propose an Issue and submit a focused Pull Request
docs/architecture.md	pillars ↔ components, data flow, design decisions
docs/host-drift.md	zero-token host/version drift states and privacy-minimal baselines
docs/guard-lab.md	synthetic Lab workflow, evidence semantics, and unsupported channels
docs/release-notes-0.2.3.md	0.2.3 stable-release scope and evidence limits
docs/release-notes-0.2.3-rc2.md	published prerelease: offline guard-lab and reviewed DSH contracts
docs/release-notes-0.2.3-rc1.md	Windows Core fail-closed candidate and prerelease channel
docs/release-notes-0.2.2.md	0.2.2 host drift, live sentinel and DSH package acceptance
docs/release-notes-0.2.1.md	0.2.1 adapter/doctor changes and bounded evidence
docs/release-notes-0.2.0.md	0.2.0 changes, evidence levels, and known limits
adapters/INTEGRATION.md	self-adaptation checklist for an unlisted host
docs/threat-model.md	honest limits: what this is and is not
docs/friction.md	what real agents and host processes taught us (F1–F20)
docs/development-note-unguarded-deletion.md	de-identified incident exploration and the recovery-aware direction
docs/test-report-codex-gpt-5.6-sol.md	v0.1.1 Codex evaluation (medium + high)
docs/test-report-workbuddy-windows-core.md	community Windows Core/CLI feedback and resulting regressions
docs/test-report-dsh-0.1.5-rc.1.md	DSH 0.1.5-rc.1 packaged-plugin and execution-level bash acceptance
docs/test-report-dsh-guard-lab.md	bounded DSH real-model Lab baseline; no L2 claim
docs/test-report-dsh-v0.1.1.md	v0.1.1 DSH live test (DeepSeek V4 Pro high, minimal mode)
skills/recovery-audit/SKILL.md	evidence hierarchy, deterministic replay, recovery and landing gates
skills/delete-guard/references/policy.md	full rule table and decision codes
skills/exfil-guard/references/rules.md	exfil rule table, reason codes, exemption format, audit shape
skills/exfil-guard/references/channels.md	egress-channel taxonomy and the unreachable channels

Status & roadmap

v0.2.3 combines the Windows/Core fixes and offline guard-lab MVP with validated text redaction, URI password detection, PyPI and newer GitHub token support, and narrower false-positive boundaries. Existing recovery tools, safe config inspection, Claude/Kimi bridges, doctor, host-drift checks and live sentinel remain available. The DSH bridge supports the reviewed 0.1.5-rc.1 and 0.2.0-rc.2 contracts; its optional text-read protection remains off by default.

The 0.2.3 notes describe this release's scope. The rc2, rc1, and 0.2.2 notes retain their historical scope. Check GitHub Releases and npm for published artifacts.

The Core and Decision Protocol are shared across harnesses. DSH, Claude and Kimi adapters, together with Codex/WorkBuddy/ZCode acceptance records, are documented in one compatibility matrix. The Kimi result includes sampled hook-compensation and execution-level BLOCK paths, not proof that its host enforces every BLOCK or that arbitrary agent actions are protected. A tested direct-Python hook startup failure was fail-open. The optional shell bridge blocked a sampled Python startup failure in a real Kimi host session, but only when the bridge itself ran; config validation alone cannot prove that the hook is live. The release adds a focused real-Windows Core gate for Issue #7, but native cmd/PowerShell execution through every harness and general concurrent-subagent safety remain explicit gaps. Later Guard branches (git-guard, database-guard, cloud-guard) reuse the same protocol and compensation engine.

guard-lab

The opt-in, offline honeytoken Lab uses disposable projects and synthetic, non-secret markers. Its clean, mock-positive, mock-injection, and snapshot-positive controls call no model and make no external request. A bounded loopback observer records the fake Lab stub, bait URL, or a validated synthetic snapshot; an explicit post-run scan can detect a canary in selected output without retaining the raw value.

The user keeps the true controller and evidence outside the fixture shown to the tested agent. Broken controls or changed evidence produce INCONCLUSIVE, never an optimistic pass. The Lab cannot observe ordinary file reads, prove remote transfer, universally block LLM calls, or resist a same-UID adversary. Start with the zero-token controls and read the guard-lab guide before involving a real harness. The built-in cases report CALIBRATION_ONLY. A separate manual injection-probe treats bait contact as EXPOSURE_OBSERVED, and compare accepts a mitigation result only after an effective unguarded baseline and a matched guarded trial with the same protocol, harness/version/model, group, and task hash. Manual real-model runs also require a user-verified completed host result, so an exit-0 startup/model failure cannot count as a quiet win. A quiet baseline stays INCONCLUSIVE; no result is a general model or vendor safety rating.

Contributing

Bug reports, design proposals, compatibility evidence, documentation fixes, and focused code changes are welcome. Please start with an Issue for non-trivial or security-boundary changes, and submit implementations as a focused Pull Request. Read the contribution guide before sharing logs or test evidence; credentials, private configuration, and unredacted incident data must not be posted publicly.

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.