@mokuyoaxis/agent-guard 0.2.3 → 0.2.4-hotfix.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (70) hide show
  1. package/README.md +70 -63
  2. package/README.zh-CN.md +61 -59
  3. package/adapters/INTEGRATION.md +4 -4
  4. package/adapters/claude/README.md +3 -3
  5. package/adapters/claude/harness/README.md +1 -1
  6. package/adapters/codex/harness/README.md +2 -2
  7. package/adapters/dsh/README.md +10 -6
  8. package/adapters/dsh/harness/README.md +8 -8
  9. package/adapters/dsh/harness/guard_lab.py +3 -3
  10. package/adapters/dsh/lib/index.js +1 -1
  11. package/adapters/kimi-code/README.md +7 -7
  12. package/adapters/kimi-code/harness/README.md +3 -3
  13. package/adapters/kimi-code/harness/guard_lab.py +1 -1
  14. package/core/__init__.py +1 -1
  15. package/core/classifier.py +66 -17
  16. package/core/policy.py +28 -13
  17. package/core/recovery.py +256 -23
  18. package/core/trash_index.py +193 -0
  19. package/docs/README.md +104 -0
  20. package/docs/{architecture.md → design/architecture.md} +31 -6
  21. package/docs/{compatibility.md → design/compatibility.md} +80 -4
  22. package/docs/{threat-model.md → design/threat-model.md} +4 -4
  23. package/docs/{harness-capabilities.md → guides/harness-capabilities.md} +9 -9
  24. package/docs/guides/trash-index.md +106 -0
  25. package/docs/{development-note-unguarded-deletion.md → history/development-note-unguarded-deletion.md} +2 -2
  26. package/docs/{friction.md → history/friction.md} +61 -0
  27. package/docs/{secret-guard-analysis.md → history/secret-guard-analysis.md} +12 -12
  28. package/docs/{secret-guard-architecture.md → history/secret-guard-architecture.md} +2 -2
  29. package/docs/{secret-guard-design.md → history/secret-guard-design.md} +14 -14
  30. package/docs/lab/cases/injection-case-fake-ai-api.md +346 -0
  31. package/docs/{guard-lab.md → lab/guard-lab.md} +12 -12
  32. package/docs/{release-notes-0.2.0-rc1.md → releases/release-notes-0.2.0-rc1.md} +3 -3
  33. package/docs/{release-notes-0.2.0.md → releases/release-notes-0.2.0.md} +5 -5
  34. package/docs/{release-notes-0.2.1.md → releases/release-notes-0.2.1.md} +6 -6
  35. package/docs/{release-notes-0.2.2.md → releases/release-notes-0.2.2.md} +2 -2
  36. package/docs/{release-notes-0.2.3-rc1.md → releases/release-notes-0.2.3-rc1.md} +1 -1
  37. package/docs/{release-notes-0.2.3-rc2.md → releases/release-notes-0.2.3-rc2.md} +9 -9
  38. package/docs/{release-notes-0.2.3.md → releases/release-notes-0.2.3.md} +3 -3
  39. package/docs/releases/release-notes-0.2.4-hotfix.1.md +75 -0
  40. package/docs/releases/release-notes-0.2.4.md +89 -0
  41. package/docs/{test-report-claude-code-harness.md → reports/test-report-claude-code-harness.md} +5 -5
  42. package/docs/reports/test-report-dsh-0.2.4-ptc.md +79 -0
  43. package/docs/{test-report-dsh-guard-lab.md → reports/test-report-dsh-guard-lab.md} +1 -1
  44. package/docs/{test-report-dsh-native-session.md → reports/test-report-dsh-native-session.md} +1 -1
  45. package/docs/{test-report-dsh-paired-lab.md → reports/test-report-dsh-paired-lab.md} +1 -1
  46. package/docs/{test-report-dsh-real-followup.md → reports/test-report-dsh-real-followup.md} +1 -1
  47. package/docs/{test-report-dsh-retry-evidence.md → reports/test-report-dsh-retry-evidence.md} +1 -1
  48. package/docs/{test-report-dsh-v0.1.1.md → reports/test-report-dsh-v0.1.1.md} +4 -4
  49. package/docs/{test-report-kimi-code-block.md → reports/test-report-kimi-code-block.md} +3 -3
  50. package/docs/{test-report-kimi-guard-lab.md → reports/test-report-kimi-guard-lab.md} +3 -3
  51. package/docs/{test-report-release-readiness-0.2.3.md → reports/test-report-release-readiness-0.2.3.md} +1 -1
  52. package/docs/{test-report-workbuddy-windows-core.md → reports/test-report-workbuddy-windows-core.md} +1 -1
  53. package/docs/{test-report-zcode-glm-flash.md → reports/test-report-zcode-glm-flash.md} +2 -2
  54. package/package.json +1 -1
  55. package/skills/delete-guard/SKILL.md +38 -0
  56. package/skills/delete-guard/references/policy.md +29 -9
  57. package/skills/delete-guard/scripts/check.py +19 -0
  58. package/skills/delete-guard/scripts/restore.py +18 -6
  59. package/skills/delete-guard/scripts/status.py +52 -0
  60. package/skills/exfil-guard/references/channels.md +1 -1
  61. /package/docs/{host-drift.md → guides/host-drift.md} +0 -0
  62. /package/docs/{publishing-from-ephemeral-environments.md → guides/publishing-from-ephemeral-environments.md} +0 -0
  63. /package/docs/{guard-lab-clean-task.md → lab/tasks/guard-lab-clean-task.md} +0 -0
  64. /package/docs/{guard-lab-read-trial-task.md → lab/tasks/guard-lab-read-trial-task.md} +0 -0
  65. /package/docs/{guard-lab-trial-task.md → lab/tasks/guard-lab-trial-task.md} +0 -0
  66. /package/docs/{test-report-codex-gpt-5.6-sol.md → reports/test-report-codex-gpt-5.6-sol.md} +0 -0
  67. /package/docs/{test-report-codex-gpt-6-astra-high.md → reports/test-report-codex-gpt-6-astra-high.md} +0 -0
  68. /package/docs/{test-report-dsh-0.1.5-rc.1.md → reports/test-report-dsh-0.1.5-rc.1.md} +0 -0
  69. /package/docs/{test-report-dsh-0.2-upgrade.md → reports/test-report-dsh-0.2-upgrade.md} +0 -0
  70. /package/docs/{test-report-dsh-read-redaction.md → reports/test-report-dsh-read-redaction.md} +0 -0
@@ -51,11 +51,11 @@ different effects (`-wi`, `-c`, `-p`) stays unknown and BLOCKs.
51
51
  | 1 | dry run / no targets | `ALLOW_NOOP` | proceed unchanged |
52
52
  | 2 | unresolvable targets: shell vars, command substitution, unbalanced quotes, `bash -c` with destructive smell, `find -delete`, `find -exec rm`, stdin-fed (`xargs`) | `BLOCK_UNDETERMINABLE_EFFECT` | refuse - allowing it would forfeit the core guarantee |
53
53
  | 2a | SHAPE F1: destructive op preceded by `cd` in the same command line, target in-workspace and resolvable | `ASK` (`COMPOUND_CWD_DELETE`) | single-execution authorization; splitting the command avoids the prompt. A shape rule describes *compensation* difficulty, never effect scope: if the target set also trips rule 2, 4, 5 or 6, that BLOCK wins (`tests/test_incident_regression.py`) |
54
- | 2b | SHAPE F2: file-creation op (`touch/mkdir/cp/mv/install/ln/tee`, `>`/`>>`) precedes a target-dependent destructive op in the same line | `ASK` (`COMPOUND_CREATE_DELETE`) | single-execution authorization; `reset --hard`/force-push exempt (position-independent) |
54
+ | 2b | SHAPE F2: file-creation op (`touch/mkdir/cp/mv/install/ln/tee`, `>`/`>>`) precedes a target-dependent destructive op in the same line | `ASK` (`COMPOUND_CREATE_DELETE`) | single-execution authorization; force-push is refused separately. Hard reset in a compound line is effect-uncertain and BLOCKED before shape rules |
55
55
  | 2c | target *is* a filesystem root (`/`, `/home`, `/usr`, `/etc`, `/var`, `/tmp`, `/opt`, `/boot`, `$HOME`, ...) | `BLOCK_PROTECTED_ANCESTOR` | refuse. Matched exactly, so paths *under* these roots keep the ordinary codes; enforced by identity rather than workspace geometry, so it holds even when the workspace is `/` |
56
- | 3 | any target inside quarantine (`.agent-trash/`) | `ALLOW_TRASH_GC` | direct delete permitted (housekeeping) |
56
+ | 5 | workspace root, `.git` metadata, quarantine root/control paths, or an in-workspace parent containing configured storage | `BLOCK_PROTECTED_PATH` | refuse before the housekeeping exemption; root manifest/audit/state, state temp and sessions are control paths |
57
+ | 3 | explicit ordinary unprotected payload inside quarantine (`.agent-trash/`) | `ALLOW_TRASH_GC` | opaque globs are refused; safe_delete may enumerate first, and transaction purges use gc.py --execute with an explicit selection |
57
58
  | 4 | target outside workspace | `BLOCK_OUT_OF_WORKSPACE` | refuse |
58
- | 5 | target is workspace root or `.git` (any depth) | `BLOCK_PROTECTED_PATH` | refuse |
59
59
  | 6 | any glob target | `BLOCK_WILDCARD` | refuse; use safe_delete which enumerates |
60
60
  | 7 | RESTRICTED mode, git/remote destructive op | `BLOCK_RESTRICTED_MODE` | refuse |
61
61
  | 8 | RESTRICTED mode, fs delete | narrow files only -> `RELOCATE_NARROW`, else `BLOCK_RESTRICTED_MODE` | refuse or quarantine |
@@ -64,13 +64,22 @@ different effects (`-wi`, `-c`, `-p`) stays unknown and BLOCKs.
64
64
  | 11 | supported `git clean -f...` | `RELOCATE_VIA_CLEAN_ENUMERATE` | enumerate via `clean -n`, decode every Git-quoted path, relocate every match, proceed only on full coverage |
65
65
  | 11a | `git clean -ff`, interactive `-i`, or exclude `-e` | `BLOCK_UNDETERMINABLE_EFFECT` | refuse; nested-repository and interactive/exclusion semantics are not safely mirrored |
66
66
  | 11b | supported `git clean -f...` whose target set cannot be enumerated (not a repository, `git` cannot run) | `BLOCK_UNDETERMINABLE_EFFECT` | refuse; the targets exist but their set is unknowable, so nothing was attempted and nothing may be reported as a failed compensation |
67
- | 12 | `git reset --hard`, `git restore <path>`, `git checkout -- <path>` | `SNAPSHOT_GIT_STASH` | `git stash create`+`store` first; any create/store failure blocks |
67
+ | 12 | supported `git reset --hard [commit]` without untracked/ignored collisions, `git restore <path>`, `git checkout -- <path>` | `SNAPSHOT_GIT_STASH` | hard reset first checks its target tree; `git stash create`+`store` then protects tracked modifications; any create/store failure blocks |
68
+ | 12a | hard reset target overlaps untracked/ignored content or quarantine storage | `BLOCK_GIT_RESET_COLLISION` | refuse before compensation; preserve conflicting paths separately before retrying |
69
+ | 12b | hard reset target cannot be resolved/enumerated, has unsupported options or submodule effects, is stash-relative, or uses shell wrappers/compound commands | `BLOCK_UNDETERMINABLE_EFFECT` | refuse before compensation; use a standalone reset with an explicit stable commit |
68
70
  | 13 | all targets git-ignored AND match artifact patterns | `ALLOW_REGENERABLE` | direct delete |
69
71
  | 14 | rooted recursive delete | `RELOCATE_TREE` | quarantine whole tree, proceed |
70
72
  | 15 | named files/dirs | `RELOCATE_PATHS` | quarantine, proceed |
71
73
 
72
- Precedence inside rule groups: `outside-workspace` > `workspace-root` >
73
- `git-metadata`. RESTRICTED narrows before NORMAL relaxes.
74
+ Filesystem-root and workspace/Git/quarantine protection win before ordinary
75
+ housekeeping. Targets outside the workspace retain their boundary refusal,
76
+ except ordinary unprotected payload inside the explicitly configured quarantine.
77
+ RESTRICTED narrows before NORMAL relaxes.
78
+
79
+ The 0.2.4-hotfix.1 maintenance hotfix backports the RC control-path repair onto 0.2.4.
80
+ The original 0.2.4 artifact does not include this protection. This hotfix uses
81
+ an explicit version or npm hotfix selection.
82
+ The existing 0.2.5 RC line retains its accumulated changes.
74
83
 
75
84
  ## Verdict actions
76
85
 
@@ -154,8 +163,19 @@ model tool.
154
163
 
155
164
  - Command-level interception covers the recognized vocabulary; arbitrary
156
165
  scripts that delete internally are invisible to `check.py` (see
157
- `docs/threat-model.md`).
158
- - `git stash create` captures tracked modifications; untracked files are not
159
- affected by `reset --hard`, so they need no snapshot.
166
+ `docs/design/threat-model.md`).
167
+ - `git stash create` captures tracked modifications only. `reset --hard`
168
+ can delete untracked and ignored content that obstructs its target tree.
169
+ `check.py` checks file/directory/ancestor collisions and refuses them;
170
+ this version does not automatically archive those paths. It also refuses
171
+ target-tree writes into quarantine. Ordinary unrelated untracked files
172
+ remain allowed. Only `--hard`, optional `-q`/`--quiet`, and at most one
173
+ commit are supported; submodules and stash-relative targets are refused.
174
+ - Hard reset must be standalone without shell wrappers: other segments can
175
+ change its revision or create a collision after preflight; wrappers can
176
+ change its Git environment. The preflight and host execution are separate;
177
+ concurrent changes are not atomically excluded.
178
+ Direct callers of `snapshot_git` receive a tracked-only snapshot and must
179
+ run the hard-reset preflight themselves before authorizing that operation.
160
180
  - Windows cmd/PowerShell, databases, cloud resources: future skills
161
181
  (`git-guard`, `database-guard`, `cloud-guard`) on the same core.
@@ -105,6 +105,25 @@ def main() -> int:
105
105
  specs, parse_error = [], None
106
106
  verdicts = [policy.decide_dialect_failure(resolution)]
107
107
 
108
+ # Preflight every reset before ANY compensation in the line. Advisory
109
+ # and enforced checks agree, and a later unsafe reset cannot leave an
110
+ # earlier filesystem relocation half-applied. Stash create only saves
111
+ # tracked modifications, so it cannot authorize an untracked collision.
112
+ if not policy.worst(verdicts).blocked:
113
+ for index, (spec, verdict) in enumerate(zip(specs, verdicts)):
114
+ if spec.kind != classifier.KIND_GIT_RESET_HARD or \
115
+ verdict.decision != policy.DECISION_SNAPSHOT:
116
+ continue
117
+ collisions, error = engine.preflight_git_reset_hard(
118
+ cwd=base, target=spec.targets[0] if spec.targets else "HEAD")
119
+ if error or collisions:
120
+ verdicts[index] = policy.Verdict(
121
+ policy.DECISION_BLOCK,
122
+ policy.CODE_BLOCK_UNDETERMINABLE_EFFECT if error else
123
+ policy.CODE_BLOCK_GIT_RESET_COLLISION,
124
+ [error or "untracked/ignored or quarantine collision"],
125
+ )
126
+
108
127
  top = policy.worst(verdicts)
109
128
  latency_ms = round((time.monotonic() - started) * 1000, 1)
110
129
  check_id = audit.new_txid()
@@ -5,7 +5,8 @@
5
5
  restore.py TXID [--force] [--json]
6
6
 
7
7
  Restore is non-destructive by default: it refuses to overwrite anything now
8
- occupying an origin path. --force is an explicit human decision.
8
+ occupying an origin path. --force preserves that occupant in a separate
9
+ transaction before restoring. Inspect backup_txids after success or failure.
9
10
  """
10
11
  from __future__ import annotations
11
12
 
@@ -69,20 +70,31 @@ def main() -> int:
69
70
 
70
71
  report = engine.restore(args.txid, force=args.force)
71
72
  workspace = engine.workspace
72
- audit.append({"event": "restore", "txid": args.txid, "force": args.force,
73
- "ok": report.get("ok"), "restored": report.get("restored"),
74
- "conflicts": report.get("conflicts"),
75
- "errors": report.get("errors")},
76
- os.path.join(engine.trash_root, AUDIT_NAME))
73
+ event = {"event": "restore", "txid": args.txid, "force": args.force,
74
+ "ok": report.get("ok"), "restored": report.get("restored"),
75
+ "conflicts": report.get("conflicts"),
76
+ "errors": report.get("errors")}
77
+ if report.get("backup_txids"):
78
+ event["backup_txids"] = report["backup_txids"]
79
+ try:
80
+ audit.append(event, os.path.join(engine.trash_root, AUDIT_NAME))
81
+ except OSError:
82
+ report["ok"] = False
83
+ report.setdefault("errors", []).append(
84
+ "restore audit could not be stored; inspect filesystem state")
77
85
  if args.as_json:
78
86
  print(json.dumps(report, ensure_ascii=False, indent=2))
79
87
  else:
88
+ for txid in report.get("backup_txids", []):
89
+ print(f"current-version preservation transaction: {txid} (inspect state)")
80
90
  for path in report.get("restored", []):
81
91
  print(f"restored: {path}")
82
92
  for path in report.get("conflicts", []):
83
93
  print(f"conflict (exists; use --force): {path}")
84
94
  for err in report.get("errors", []):
85
95
  print(f"error: {err}", file=sys.stderr)
96
+ if report.get("error"):
97
+ print(f"error: {report['error']}", file=sys.stderr)
86
98
  if report.get("errors"):
87
99
  return 1
88
100
  if report.get("conflicts"):
@@ -2,6 +2,7 @@
2
2
  """status - inspect guard state, quarantine usage, recent decisions.
3
3
 
4
4
  status.py [--json] [--tail N]
5
+ status.py --trash-index [--root PATH ...] [--trash PATH ...] [--json]
5
6
  """
6
7
  from __future__ import annotations
7
8
 
@@ -21,9 +22,60 @@ def main() -> int:
21
22
  ap = argparse.ArgumentParser(description=__doc__)
22
23
  ap.add_argument("--json", action="store_true", dest="as_json")
23
24
  ap.add_argument("--tail", type=int, default=10)
25
+ ap.add_argument("--trash-index", action="store_true",
26
+ help="read-only quarantine locations for agents and future UI")
27
+ ap.add_argument("--root", action="append", default=[],
28
+ help="search root for --trash-index (repeatable)")
29
+ ap.add_argument("--trash", action="append", default=[],
30
+ help="declared external/custom quarantine path (repeatable)")
31
+ ap.add_argument("--max-depth", type=int, default=None,
32
+ help="directory depth below each search root (default 3)")
33
+ ap.add_argument("--max-entries", type=int, default=None,
34
+ help="index directory-entry budget (default 10000)")
24
35
  args = ap.parse_args()
25
36
 
26
37
  base = os.getcwd()
38
+ if args.trash_index:
39
+ from core.trash_index import (
40
+ DEFAULT_MAX_DEPTH, DEFAULT_MAX_ENTRIES, list_trash_locations)
41
+ roots, paths = list(args.root), list(args.trash)
42
+ if not roots and not paths:
43
+ roots = [base]
44
+ configured = os.environ.get("AGENT_GUARD_TRASH")
45
+ if configured:
46
+ paths.append(configured)
47
+ try:
48
+ result = list_trash_locations(
49
+ roots, trash_paths=paths,
50
+ max_depth=(DEFAULT_MAX_DEPTH if args.max_depth is None
51
+ else args.max_depth),
52
+ max_entries=(DEFAULT_MAX_ENTRIES if args.max_entries is None
53
+ else args.max_entries))
54
+ except ValueError as exc:
55
+ ap.error(str(exc))
56
+ if args.as_json:
57
+ # ASCII escapes preserve unusual POSIX names in valid UTF-8 JSON.
58
+ print(json.dumps(result, ensure_ascii=True, indent=2))
59
+ else:
60
+ print(f"quarantine locations: {result['count']} candidates, "
61
+ f"{result['identified_count']} with metadata")
62
+ print(f"scope: depth={result['max_depth']} budget={result['max_entries']}")
63
+ for path in result["roots"]:
64
+ print(f" root: {json.dumps(path)}")
65
+ for path in result["trash_paths"]:
66
+ print(f" declared: {json.dumps(path)}")
67
+ for row in result["entries"]:
68
+ print(f" [{row['status']}] {json.dumps(row['trash_root'])}")
69
+ if row["trash_root"] != row["resolved_trash_root"]:
70
+ print(f" resolved: {json.dumps(row['resolved_trash_root'])}")
71
+ for error in result["errors"]:
72
+ print(f" {error['code']}: {json.dumps(error['path'])}")
73
+ if not result["complete"]:
74
+ print("partial index: inspect scope and errors")
75
+ return 0 if result["complete"] else 1
76
+ if (args.root or args.trash or args.max_depth is not None or
77
+ args.max_entries is not None):
78
+ ap.error("index options require --trash-index")
27
79
  workspace = classifier.discover_workspace(base)
28
80
  trash_root = os.environ.get(
29
81
  "AGENT_GUARD_TRASH", os.path.join(workspace, TRASH_DIRNAME))
@@ -39,7 +39,7 @@ Rules the table encodes:
39
39
  them here is the opposite of a claim: it is the coverage gap, stated so no
40
40
  reader infers coverage the guard does not have.
41
41
 
42
- Per `docs/threat-model.md`, the guard "may not claim" prevention of
42
+ Per `docs/design/threat-model.md`, the guard "may not claim" prevention of
43
43
  adversarial exfiltration, and per design 4.4 an unreachable channel gets
44
44
  **no verdict at all**.
45
45
 
File without changes