@mokuyoaxis/agent-guard 0.2.2

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 (77) hide show
  1. package/CONTRIBUTING.md +101 -0
  2. package/LICENSE +21 -0
  3. package/README.md +558 -0
  4. package/README.zh-CN.md +488 -0
  5. package/adapters/INTEGRATION.md +94 -0
  6. package/adapters/claude/README.md +141 -0
  7. package/adapters/claude/compatibility.json +17 -0
  8. package/adapters/claude/harness/README.md +59 -0
  9. package/adapters/claude/harness/mock_anthropic_api.mjs +47 -0
  10. package/adapters/claude/harness/run_scenario.sh +79 -0
  11. package/adapters/claude/harness/run_scenario_no_python3.sh +49 -0
  12. package/adapters/claude/hook_bridge.sh +33 -0
  13. package/adapters/claude/pre_tool_use.py +264 -0
  14. package/adapters/claude/settings.example.json +16 -0
  15. package/adapters/codex/harness/README.md +53 -0
  16. package/adapters/codex/harness/acceptance.py +226 -0
  17. package/adapters/dsh/README.md +62 -0
  18. package/adapters/dsh/cordis.patch.yml +30 -0
  19. package/adapters/dsh/lib/index.js +500 -0
  20. package/adapters/kimi-code/README.md +169 -0
  21. package/adapters/kimi-code/compatibility.json +17 -0
  22. package/adapters/kimi-code/config.example.toml +26 -0
  23. package/adapters/kimi-code/hook_bridge.sh +32 -0
  24. package/adapters/kimi-code/pre_tool_use.py +72 -0
  25. package/core/__init__.py +47 -0
  26. package/core/audit.py +86 -0
  27. package/core/classifier.py +1175 -0
  28. package/core/dialects.py +898 -0
  29. package/core/policy.py +817 -0
  30. package/core/recovery.py +700 -0
  31. package/core/redaction.py +1096 -0
  32. package/core/safe_view.py +212 -0
  33. package/docs/architecture.md +223 -0
  34. package/docs/compatibility.md +142 -0
  35. package/docs/development-note-unguarded-deletion.md +187 -0
  36. package/docs/friction.md +266 -0
  37. package/docs/harness-capabilities.md +72 -0
  38. package/docs/host-drift.md +142 -0
  39. package/docs/publishing-from-ephemeral-environments.md +104 -0
  40. package/docs/release-notes-0.2.0-rc1.md +46 -0
  41. package/docs/release-notes-0.2.0.md +72 -0
  42. package/docs/release-notes-0.2.1.md +78 -0
  43. package/docs/release-notes-0.2.2.md +120 -0
  44. package/docs/secret-guard-analysis.md +416 -0
  45. package/docs/secret-guard-architecture.md +93 -0
  46. package/docs/secret-guard-design.md +649 -0
  47. package/docs/test-report-claude-code-harness.md +462 -0
  48. package/docs/test-report-codex-gpt-5.6-sol.md +335 -0
  49. package/docs/test-report-codex-gpt-6-astra-high.md +129 -0
  50. package/docs/test-report-dsh-0.1.5-rc.1.md +84 -0
  51. package/docs/test-report-dsh-v0.1.1.md +126 -0
  52. package/docs/test-report-kimi-code-block.md +198 -0
  53. package/docs/test-report-zcode-glm-flash.md +241 -0
  54. package/docs/threat-model.md +44 -0
  55. package/doctor.py +756 -0
  56. package/live_sentinel.py +339 -0
  57. package/package.json +69 -0
  58. package/skills/delete-guard/SKILL.md +109 -0
  59. package/skills/delete-guard/agents/openai.yaml +4 -0
  60. package/skills/delete-guard/references/policy.md +161 -0
  61. package/skills/delete-guard/scripts/_bootstrap.py +8 -0
  62. package/skills/delete-guard/scripts/check.py +370 -0
  63. package/skills/delete-guard/scripts/gc.py +103 -0
  64. package/skills/delete-guard/scripts/restore.py +98 -0
  65. package/skills/delete-guard/scripts/safe_delete.py +256 -0
  66. package/skills/delete-guard/scripts/status.py +130 -0
  67. package/skills/exfil-guard/SKILL.md +143 -0
  68. package/skills/exfil-guard/agents/openai.yaml +4 -0
  69. package/skills/exfil-guard/references/channels.md +58 -0
  70. package/skills/exfil-guard/references/rules.md +194 -0
  71. package/skills/exfil-guard/scripts/_bootstrap.py +8 -0
  72. package/skills/exfil-guard/scripts/check_span.py +250 -0
  73. package/skills/exfil-guard/scripts/sanitize.py +155 -0
  74. package/skills/exfil-guard/scripts/view.py +44 -0
  75. package/skills/recovery-audit/SKILL.md +283 -0
  76. package/skills/recovery-audit/agents/openai.yaml +4 -0
  77. package/skills/recovery-audit/references/evidence-records.md +85 -0
@@ -0,0 +1,283 @@
1
+ ---
2
+ name: recovery-audit
3
+ description: >-
4
+ Recover and audit repository or workspace work after accidental deletion,
5
+ corruption, or destructive agent actions, including when the original tree
6
+ or .git is gone but Git remotes, AI session records, tool caches, snapshots,
7
+ or plans survive. Use when provenance and completeness matter; not for
8
+ routine code review, filesystem undelete, or an ordinary clean rollback.
9
+ ---
10
+
11
+ # Recovery Audit
12
+
13
+ Recover the strongest state the evidence supports. A passing build is not proof
14
+ that the original bytes or full scope were recovered.
15
+
16
+ This skill is the after-incident branch of agent-guard. It does not undelete a
17
+ disk or promise to restore an entire home directory. It reconstructs project
18
+ state only from bytes and effects preserved by surviving evidence, especially
19
+ AI session/tool records that may contain successful patches, file snapshots,
20
+ command output, and working-directory context after the workspace itself is
21
+ gone.
22
+
23
+ When producing an evidence ledger or final recovery report, read
24
+ `references/evidence-records.md` and use its schemas. Keep the populated copy
25
+ outside publishable source paths unless the user explicitly approves a
26
+ redacted public report.
27
+
28
+ ## Establish authority and permission
29
+
30
+ First distinguish the requested endpoint: audit only, reconstruction, landing
31
+ in the working tree, commit, push, and release are separate permissions. Do not
32
+ infer a later permission from an earlier one.
33
+
34
+ Before any mutation:
35
+
36
+ - inspect branch, HEAD, remotes, tags, status, ignored/untracked files, reflog,
37
+ stashes, local refs, and available backups;
38
+ - preserve the damaged tree and every session/cache/evidence source; do not
39
+ pull over it, re-clone into it, clean it, or run destructive Git commands;
40
+ - prefer a fresh recovery stage rooted at a named trusted commit. If staging is
41
+ impossible, create a recoverable snapshot before touching the tree;
42
+ - record the intended version, last trusted anchor, time window, affected
43
+ paths, and user-selected source precedence.
44
+
45
+ Read the loss itself before reading any reconstruction. Commit history, reflog,
46
+ and the incident-window `git status`/`git log` are primary evidence:
47
+
48
+ - a reflog whose oldest entry is `clone: from …` means the original `.git` is
49
+ gone; there are no dangling objects to mine, and the trusted anchor is
50
+ whatever the remote still holds;
51
+ - an incident-window status line like `ahead N` means N local commits sat
52
+ beyond the pushed anchor. Treat them as an explicit loss class and require
53
+ session evidence for each, rather than assuming the working tree equals HEAD;
54
+ - the incident-window `git status` (modified + untracked) is the best available
55
+ completeness checklist for that moment. Reconcile your final tree against it
56
+ file by file.
57
+
58
+ When deletion or destructive Git work becomes necessary, use `$delete-guard`
59
+ or an equivalent quarantine guard if installed. Before a report, commit,
60
+ archive, or push leaves the recovery boundary, use `$exfil-guard` or an
61
+ equivalent staged/payload scan if available. A recovery audit never grants
62
+ deletion, history rewrite, force-push, or release authority by itself.
63
+
64
+ Re-verify remote state yourself before reporting it. A handoff note that claims
65
+ "nothing was committed or pushed" is a claim, not evidence: check
66
+ `git ls-remote`, ahead/behind, upstream tracking, tags, and repository
67
+ visibility. Treat a recovery branch as potentially published until the remote
68
+ says otherwise, and if it did escape, scan the published contents for
69
+ credentials, private paths, and internal reports before deciding whether to
70
+ retract it.
71
+
72
+ ## Build an evidence ledger
73
+
74
+ Define the authority order for this incident instead of assuming that newest
75
+ or most complete-looking always wins. A useful default is:
76
+
77
+ 1. the user's explicit decisions about intended state and scope;
78
+ 2. a trusted Git anchor as the reconstruction base;
79
+ 3. byte-level snapshots and successful tool effects from authoritative
80
+ sessions, applied in their real chronology;
81
+ 4. secondary session transcripts, editor caches, exported worktrees, CI
82
+ artifacts, and package archives;
83
+ 5. plans, tests, and documentation as behavioral specifications;
84
+ 6. inference, only with explicit approval and a `reconstructed` label.
85
+
86
+ Track each recovered unit with source, timestamp/session ordinal, target path,
87
+ hash when available, observed tool result, confidence, and one status:
88
+
89
+ - `recovered`: the bytes or exact patch are evidenced;
90
+ - `reconstructed`: behavior was rebuilt from a specification, not recovered;
91
+ - `missing`: existence or intent is evidenced but the contents are unavailable.
92
+
93
+ Never collapse these statuses. Preserve gap markers and overturned conclusions.
94
+
95
+ ## Audit the recorder before replaying it
96
+
97
+ The recovery engine is part of the evidence chain and must itself be tested.
98
+ Match the original tool semantics:
99
+
100
+ - replay patch blocks atomically and with their real ordered-search/cursor
101
+ behavior; a global-uniqueness text replacement is not equivalent;
102
+ - distinguish atomic tools from shell commands that may have written files
103
+ before returning a nonzero exit code;
104
+ - preserve complete compound-command semantics, heredocs, encoded payloads,
105
+ working directories, exit status, and generated helper files;
106
+ - decode base64 or similar wrappers before concluding that a symbol or edit is
107
+ absent;
108
+ - treat truncated diffs and alternate recorder/transcript shapes as partial
109
+ evidence, not as empty evidence;
110
+ - do not interpret duplicate retries, approval transcripts, or a command line
111
+ without its result as the final state.
112
+
113
+ ### Hard gates
114
+
115
+ These are pass/fail conditions, not advice. Do not judge recovery quality while
116
+ any of them is unmet.
117
+
118
+ **Engine verdict matrix.** Extract each mutating event together with the status
119
+ the original session recorded for it, then replay and classify:
120
+ `agree_ok`, `agree_fail`, `diverged_ok`, `diverged_fail`. Every event the
121
+ original applied successfully must apply here; tune the engine until
122
+ `diverged_fail` is zero for the authoritative timeline. A large failure count is
123
+ a statement about the engine, not about the cache.
124
+
125
+ **Determinism.** Replay the same frozen inputs twice and compare trees
126
+ byte-for-byte. On any difference, bisect the most recent engine change; do not
127
+ adjust filtering knobs until the numbers look better. Note that a narrow
128
+ predicate change (e.g. `contains` becoming `starts_with` on a snapshot body) can
129
+ silently drop events and invalidate every comparison made after it.
130
+
131
+ **No intra-file hunk skipping.** Fail at file granularity, never at hunk
132
+ granularity. In a multi-file batch, a file whose context is missing is abandoned
133
+ whole and recorded, while its siblings still apply. Skipping only the unmatched
134
+ hunks inside one file leaves it structurally broken: the text still looks
135
+ plausible but no longer parses, and the damage surfaces later as syntax errors in
136
+ files you never touched.
137
+
138
+ **Hunk bounds.** Bound `@@ -l,s +l,s @@` bodies by their declared line counts.
139
+ Transcripts routinely glue unrelated text (tool-call JSON, the next command)
140
+ straight after a diff; without the count bound that text is swallowed as context
141
+ and every anchor becomes unmatchable.
142
+
143
+ ### Replay mechanics
144
+
145
+ File reads, `git diff` output, tarballs, and equivalent byte snapshots can be
146
+ stronger than a chain of fragile patches. Insert snapshots at the point in the
147
+ timeline where they were observed. Prefer the session's own `git diff -- <paths>`
148
+ as a state snapshot: applying it re-synchronizes the tree to the state the next
149
+ recorded edit was written against.
150
+
151
+ Protect journal-replayed paths from an older bulk overlay by hashing the tree
152
+ before and after the replay and skipping exactly the changed paths. Protection is
153
+ not automatically correct: when the bulk overlay is the better reconstruction for
154
+ a given file, protect by evidence per file rather than by a blanket rule.
155
+
156
+ When a diff will not apply, its added lines are still verbatim evidence. Extract
157
+ them and re-anchor onto the current file's real context; a drifted context line
158
+ is not a reason to discard the change.
159
+
160
+ Enumerate every transcript shape before trusting coverage. One recorder may emit
161
+ `user_message` payloads while another emits `message` with a role and a content
162
+ list; a parser that knows only one shape silently loses whole time windows, and
163
+ for some windows the approval/guardian transcript is the only surviving record of
164
+ real executed edits. What is untrustworthy about such transcripts is treating a
165
+ duplicate retry as the final state, not their existence.
166
+
167
+ Merging sources from a shared cache directory requires validated target paths.
168
+ A journal directory often serves several projects; a filter that accepts
169
+ "anything that looks relative" will write unrelated repositories into the tree.
170
+
171
+ Triage failed commands by what they provably wrote. A multi-target edit helper
172
+ applies its targets in order and aborts on the first anchor miss, so a nonzero
173
+ exit can still leave earlier files rewritten. Blanket replaying of failed
174
+ commands corrupts state, blanket skipping loses real work: replay a failure only
175
+ when you can prove which earlier targets it reached, and otherwise restore the
176
+ survivors as anchored edits.
177
+
178
+ ### Residual anchored edits
179
+
180
+ Edits that cannot be placed in the timeline — survivors of an aborted helper, or
181
+ a diff whose base has drifted — may be applied after the ordered replay as an
182
+ explicit, auditable list: source file, path, exact `before`/`after`, and
183
+ provenance for each. Requirements: exact-match anchors only, apply the first
184
+ match and report the count, tolerate one stale entry without dropping the rest of
185
+ the file, keep an eye on repeated sibling blocks (a list of identical entries
186
+ should fill each site in turn), and never use an anchored edit to introduce
187
+ content the evidence does not contain.
188
+
189
+ Replay into a new stage. Change one replay rule at a time and retain
190
+ machine-readable reports of applied, skipped, failed, already-applied, and
191
+ skipped-anchor events.
192
+
193
+ ## Audit scope against facts
194
+
195
+ Separate project intent from implementation facts. Build a compact coverage
196
+ matrix for each promised capability:
197
+
198
+ | Axis | Required evidence |
199
+ |---|---|
200
+ | Implementation | code exists and isolated tests pass |
201
+ | Integration | all intended entry points consume the same fact/contract |
202
+ | Real-world evidence | target platform/provider exercised, or explicitly not run |
203
+ | Release state | documentation and published artifacts may truthfully claim it |
204
+
205
+ Compare plans with code, tests, CLI/API surfaces, persistence schemas, UI, and
206
+ packaging. Classify findings as promised-but-missing, implemented-with-drift,
207
+ or unplanned risk/hard-coded obstruction. Deduplicate dependent symptoms.
208
+
209
+ Use executable probes for pure functions, security boundaries, failure paths,
210
+ and read/write behavior; static reading alone can misclassify intentional UI or
211
+ compatibility behavior. Record corrections without erasing the earlier finding.
212
+
213
+ ## Restore conservatively
214
+
215
+ - Apply exact evidence in the declared authority order onto the trusted base.
216
+ - Keep recovery tools, evidence, rejects, caches, authentication material, signed URLs,
217
+ private paths, and machine-specific configuration outside product sources.
218
+ - Never delete a failing test or weaken a contract merely to obtain green
219
+ output.
220
+ - Do not invent unavailable source. Rebuild only after explicit approval, and
221
+ mark rebuilt files separately from recovered files.
222
+ - Land with a non-deleting copy or explicit file allowlist. Preserve unrelated
223
+ user changes, Git metadata, dependencies, and data directories.
224
+
225
+ ## Verify in layers
226
+
227
+ Run checks proportional to the project, normally in this order:
228
+
229
+ 1. structural checks, syntax, `diff --check`, and targeted tests;
230
+ 2. full tests and lint, comparing file/test counts with the last evidenced
231
+ result rather than accepting a smaller green suite;
232
+ 3. offline/headless diagnostics proving the core does not silently depend on a
233
+ host, network, or user configuration;
234
+ 4. package manifest/dry-run and, when relevant, installation from the produced
235
+ archive outside the repository;
236
+ 5. scans of staged/package contents for secrets, internal reports, absolute
237
+ paths, temporary artifacts, and unintended binary metadata;
238
+ 6. file modes, symlinks, line endings, version fields, tag/release workflows,
239
+ and platform-specific checks.
240
+
241
+ Enumerate failures exhaustively. A runner that stops at the first failing file
242
+ hides the real failure set; execute every test file independently and collect a
243
+ machine-readable matrix before planning work. Lint/total file counts are also
244
+ completeness signals: a suite that is green but smaller than the last evidenced
245
+ count has lost files, not fixed them.
246
+
247
+ Verify a landed tree by re-deriving it, not by trusting the producing artifact.
248
+ Diff the landed tree against the stage that produced it and classify every
249
+ difference. If the improvement came from edited tests, review each test diff and
250
+ state whether the change is a legitimate portability/robustness fix or a
251
+ weakened assertion; a green suite obtained by relaxing contracts is not recovery.
252
+ Implementation files that are byte-identical to the recovered stage are the
253
+ strongest available evidence that the fixes were real.
254
+
255
+ Keep fixture/mock evidence distinct from paid provider, device, browser, or CI
256
+ evidence. State every unrun environment plainly. A lower test count, a lint-only
257
+ pass, or one successful canary must not be reported as full recovery.
258
+
259
+ ## Land and report
260
+
261
+ Before a commit, stage from an allowlist and inspect the staged names, summary,
262
+ content checks, executable bits, package version, and excluded evidence. Prefer
263
+ a dedicated recovery branch and keep it local until publication is separately
264
+ authorized. Mention known gaps in the commit body. Commit, push, tag, package
265
+ publication, and marketplace/release actions remain separate authorization
266
+ gates.
267
+
268
+ The final handoff should state:
269
+
270
+ - trusted baseline and recovered endpoint;
271
+ - evidence sources and precedence;
272
+ - counts of recovered, reconstructed, and missing items;
273
+ - loss classes: files absent from every source, commits beyond the pushed
274
+ anchor, and periods covered only by secondary transcripts;
275
+ - exact validation commands and results, with file and test counts;
276
+ - excluded or quarantined artifacts;
277
+ - unresolved gaps and their practical impact;
278
+ - local commit, remote branch, tag, package, and release status separately,
279
+ re-verified against the remote rather than restated from the plan.
280
+
281
+ Call the outcome an exact recovery only when provenance and completeness support
282
+ that claim. Otherwise use `evidence-backed partial recovery` or `reconstructed
283
+ checkpoint`, even when all current tests pass.
@@ -0,0 +1,4 @@
1
+ interface:
2
+ display_name: "Recovery Audit"
3
+ short_description: "Recover deleted work from Git and AI session evidence"
4
+ default_prompt: "Use $recovery-audit to recover this deleted workspace from surviving Git and AI session evidence, with provenance and gaps clearly reported."
@@ -0,0 +1,85 @@
1
+ # Recovery evidence records
2
+
3
+ Use these schemas when a recovery needs a durable ledger or handoff. Store the
4
+ populated records outside product sources by default. Redact credentials,
5
+ signed URLs, host-identifying paths, usernames, session identifiers, and
6
+ unrelated project names before publishing any derivative.
7
+
8
+ ## Evidence ledger
9
+
10
+ One row represents one file, exact patch, snapshot, or independently verifiable
11
+ unit. Split mixed-confidence material into separate rows.
12
+
13
+ | Field | Required meaning |
14
+ |---|---|
15
+ | `unit` | Stable local identifier, not a secret-bearing cache key |
16
+ | `target` | Intended repository-relative path or scoped capability |
17
+ | `source_kind` | `git`, `ai-session`, `tool-cache`, `snapshot`, `artifact`, `plan`, or `inference` |
18
+ | `source_ref` | Local evidence locator; redact it in public derivatives |
19
+ | `observed_at` | Timestamp or reliable session ordinal; `unknown` when unavailable |
20
+ | `tool_result` | `success`, `failure`, `partial`, or `unknown` as recorded by the source |
21
+ | `sha256` | Hash of recovered bytes when exact bytes exist; otherwise empty |
22
+ | `status` | `recovered`, `reconstructed`, or `missing` |
23
+ | `confidence` | `exact`, `strong`, `partial`, or `inferred` |
24
+ | `notes` | Conflict, precedence, replay result, or practical impact |
25
+
26
+ Never mark a unit `recovered` from prose, a passing test, or a plausible
27
+ rewrite. Those can support `reconstructed`, not byte recovery.
28
+
29
+ ## Replay report
30
+
31
+ Record each mutating event from the authoritative timeline:
32
+
33
+ | Field | Required meaning |
34
+ |---|---|
35
+ | `ordinal` | Stable chronological position |
36
+ | `source_ref` | Evidence locator |
37
+ | `cwd` | Recorded working directory, normalized only for a redacted public copy |
38
+ | `operation` | Patch, write, move, command, or snapshot application |
39
+ | `recorded_result` | What the original tool/session said happened |
40
+ | `replay_result` | `agree_ok`, `agree_fail`, `diverged_ok`, or `diverged_fail` |
41
+ | `affected_paths` | Validated repository-relative targets |
42
+ | `notes` | Partial effects, rejected targets, or engine correction |
43
+
44
+ Recovery quality must not be judged while any authoritative successful event
45
+ is `diverged_fail`.
46
+
47
+ ## Final handoff
48
+
49
+ ```markdown
50
+ # Recovery handoff
51
+
52
+ - Trusted baseline:
53
+ - Recovered endpoint:
54
+ - Evidence precedence:
55
+ - Recovery stage:
56
+
57
+ ## Coverage
58
+
59
+ - Recovered units:
60
+ - Reconstructed units:
61
+ - Missing units:
62
+ - Commits beyond the pushed anchor:
63
+ - Time windows covered only by secondary evidence:
64
+
65
+ ## Verification
66
+
67
+ - Deterministic replay:
68
+ - Tree comparison:
69
+ - Tests and file counts:
70
+ - Package/artifact checks:
71
+
72
+ ## Remaining gaps and impact
73
+
74
+ - ...
75
+
76
+ ## Publication state
77
+
78
+ - Local commit:
79
+ - Remote branch:
80
+ - Tag/release:
81
+ - Package publication:
82
+ ```
83
+
84
+ Use `exact recovery` only when provenance and completeness support it. Otherwise
85
+ use `evidence-backed partial recovery` or `reconstructed checkpoint`.