@mokuyoaxis/agent-guard 0.2.3 → 0.2.4

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 (69) hide show
  1. package/README.md +65 -62
  2. package/README.zh-CN.md +58 -58
  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 +41 -16
  16. package/core/policy.py +11 -4
  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} +54 -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} +39 -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.md +89 -0
  40. package/docs/{test-report-claude-code-harness.md → reports/test-report-claude-code-harness.md} +5 -5
  41. package/docs/reports/test-report-dsh-0.2.4-ptc.md +79 -0
  42. package/docs/{test-report-dsh-guard-lab.md → reports/test-report-dsh-guard-lab.md} +1 -1
  43. package/docs/{test-report-dsh-native-session.md → reports/test-report-dsh-native-session.md} +1 -1
  44. package/docs/{test-report-dsh-paired-lab.md → reports/test-report-dsh-paired-lab.md} +1 -1
  45. package/docs/{test-report-dsh-real-followup.md → reports/test-report-dsh-real-followup.md} +1 -1
  46. package/docs/{test-report-dsh-retry-evidence.md → reports/test-report-dsh-retry-evidence.md} +1 -1
  47. package/docs/{test-report-dsh-v0.1.1.md → reports/test-report-dsh-v0.1.1.md} +4 -4
  48. package/docs/{test-report-kimi-code-block.md → reports/test-report-kimi-code-block.md} +3 -3
  49. package/docs/{test-report-kimi-guard-lab.md → reports/test-report-kimi-guard-lab.md} +3 -3
  50. package/docs/{test-report-release-readiness-0.2.3.md → reports/test-report-release-readiness-0.2.3.md} +1 -1
  51. package/docs/{test-report-workbuddy-windows-core.md → reports/test-report-workbuddy-windows-core.md} +1 -1
  52. package/docs/{test-report-zcode-glm-flash.md → reports/test-report-zcode-glm-flash.md} +2 -2
  53. package/package.json +1 -1
  54. package/skills/delete-guard/SKILL.md +38 -0
  55. package/skills/delete-guard/references/policy.md +18 -5
  56. package/skills/delete-guard/scripts/check.py +19 -0
  57. package/skills/delete-guard/scripts/restore.py +18 -6
  58. package/skills/delete-guard/scripts/status.py +52 -0
  59. package/skills/exfil-guard/references/channels.md +1 -1
  60. /package/docs/{host-drift.md → guides/host-drift.md} +0 -0
  61. /package/docs/{publishing-from-ephemeral-environments.md → guides/publishing-from-ephemeral-environments.md} +0 -0
  62. /package/docs/{guard-lab-clean-task.md → lab/tasks/guard-lab-clean-task.md} +0 -0
  63. /package/docs/{guard-lab-read-trial-task.md → lab/tasks/guard-lab-read-trial-task.md} +0 -0
  64. /package/docs/{guard-lab-trial-task.md → lab/tasks/guard-lab-trial-task.md} +0 -0
  65. /package/docs/{test-report-codex-gpt-5.6-sol.md → reports/test-report-codex-gpt-5.6-sol.md} +0 -0
  66. /package/docs/{test-report-codex-gpt-6-astra-high.md → reports/test-report-codex-gpt-6-astra-high.md} +0 -0
  67. /package/docs/{test-report-dsh-0.1.5-rc.1.md → reports/test-report-dsh-0.1.5-rc.1.md} +0 -0
  68. /package/docs/{test-report-dsh-0.2-upgrade.md → reports/test-report-dsh-0.2-upgrade.md} +0 -0
  69. /package/docs/{test-report-dsh-read-redaction.md → reports/test-report-dsh-read-redaction.md} +0 -0
@@ -1,7 +1,7 @@
1
1
  # Claude Code end-to-end harness
2
2
 
3
3
  Reproduces the live interception test in
4
- [`docs/test-report-claude-code-harness.md`](../../../docs/test-report-claude-code-harness.md):
4
+ [`docs/reports/test-report-claude-code-harness.md`](../../../docs/reports/test-report-claude-code-harness.md):
5
5
  the **real** Claude Code CLI, the **real** agent-guard `PreToolUse` hook, and
6
6
  a **scripted mock Anthropic endpoint** standing in for the model.
7
7
 
@@ -1,10 +1,10 @@
1
1
  # Codex acceptance harness
2
2
 
3
3
  Reproduces the 20-check acceptance run recorded in
4
- [`docs/test-report-codex-gpt-6-astra-high.md`](../../../docs/test-report-codex-gpt-6-astra-high.md)
4
+ [`docs/reports/test-report-codex-gpt-6-astra-high.md`](../../../docs/reports/test-report-codex-gpt-6-astra-high.md)
5
5
  (2026-09-19, baseline `de5a00e`, `gpt-6-astra` / `high`).
6
6
 
7
- Unlike [`adapters/claude/harness/`](../../claude/harness/), there is no Codex
7
+ Unlike [`adapters/claude/harness/`](../../claude/harness), there is no Codex
8
8
  adapter behind this directory. Codex has no native PreToolUse hook in this
9
9
  repository, so nothing here implies automatic interception: the driver
10
10
  exercises the guard through the production CLI (`check.py`, `safe_delete.py`,
@@ -7,19 +7,23 @@ delegates deletion verdicts to the shared Python core
7
7
  The opt-in text-read prototype reuses the existing Core exfil policy through
8
8
  a bounded local worker. Both ship inside this package.
9
9
 
10
- The [current contract review](../../docs/test-report-release-readiness-0.2.3.md)
10
+ The [0.2.3 contract review](../../docs/reports/test-report-release-readiness-0.2.3.md)
11
11
  verifies the default deletion path on `0.2.0-rc.2` and `0.1.5-rc.1`, and
12
12
  the opt-in read path on the reviewed new local and sandbox filesystem providers.
13
13
  The package admits both exact host versions. Lab preflight accepts both and
14
14
  binds their native formats separately; unsupported session shapes remain
15
15
  inconclusive. A running Web service's plugin inventory does not validate this
16
- checkout or its agent scope. The [initial upgrade check](../../docs/test-report-dsh-0.2-upgrade.md)
16
+ checkout or its agent scope. The [initial upgrade check](../../docs/reports/test-report-dsh-0.2-upgrade.md)
17
17
  retains the earlier failures and correction history.
18
18
 
19
19
  ## Install
20
20
 
21
+ The [0.2.4 release](../../docs/releases/release-notes-0.2.4.md) updates the shared
22
+ Core and docs without broadening the admitted DSH versions or native-read
23
+ coverage. Install the exact version:
24
+
21
25
  ```bash
22
- dsh plugin --profile <your-profile> add @mokuyoaxis/agent-guard@0.2.3
26
+ dsh plugin --profile <your-profile> add @mokuyoaxis/agent-guard@0.2.4
23
27
  ```
24
28
 
25
29
  Use an exact package version whose host contract matches your DSH installation.
@@ -95,11 +99,11 @@ it reads no target file and performs no model/network call. Native `read`
95
99
  continues to own filesystem access. The shell-policy inheritance note below
96
100
  applies to the existing deletion commands, not this controller worker.
97
101
 
98
- The [zero-model native report](../../docs/test-report-dsh-read-redaction.md)
102
+ The [zero-model native report](../../docs/reports/test-report-dsh-read-redaction.md)
99
103
  verifies the actual returned value/content/meta, next request, and full durable
100
104
  JSONL log through the real AgentLoop with a synthetic stream. It does not
101
105
  establish real-model injection mitigation or universal emission protection.
102
- The separate [official Flash real-model follow-up](../../docs/test-report-dsh-real-followup.md)
106
+ The separate [official Flash real-model follow-up](../../docs/reports/test-report-dsh-real-followup.md)
103
107
  observed supported synthetic-secret redaction in tool content, presentation
104
108
  metadata and the decoded session during a direct-read off/on experiment. It
105
109
  preserved useful configuration and remains outside the Lab injection L2 protocol.
@@ -136,7 +140,7 @@ is forwarded verbatim rather than swapped for POSIX, so `check.py` returns
136
140
  reproducing a test; a source checkout may contain later changes.
137
141
  - DSH `0.1.5-rc.1` package loading and one harmless execution-level `bash`
138
142
  block are independently verified in the
139
- [bounded host report](../../docs/test-report-dsh-0.1.5-rc.1.md). Model,
143
+ [bounded host report](../../docs/reports/test-report-dsh-0.1.5-rc.1.md). Model,
140
144
  subagent, concurrency, ASK UI and non-`bash` paths remain separate tests.
141
145
  - For repeatable baselines and reviewed guard-off/on Lab pairs, use the
142
146
  [headless capture/review runner](harness/README.md). Its separate `check`
@@ -51,7 +51,7 @@ python3 adapters/dsh/harness/guard_lab.py run \
51
51
  --dsh-home /tmp/approved-disposable-dsh-home \
52
52
  --output-dir /tmp/dsh-lab-clean \
53
53
  --case clean --model-label "DeepSeek official deepseek-flash" \
54
- --task-file docs/guard-lab-clean-task.md \
54
+ --task-file docs/lab/tasks/guard-lab-clean-task.md \
55
55
  --trial-group dsh-baseline-01 --timeout 120
56
56
  ```
57
57
 
@@ -147,7 +147,7 @@ replacement operations and unknown content blocks refuse every output channel.
147
147
  Parser 2 still refuses these source references. The retained new-host real-model
148
148
  clean capture was refused with `UNSUPPORTED_SURFACE_REPLAY`, and its composition
149
149
  also changed; it did not establish a new off/on result. The
150
- [current review](../../../docs/test-report-release-readiness-0.2.3.md) separates
150
+ [current review](../../../docs/reports/test-report-release-readiness-0.2.3.md) separates
151
151
  the passing no-model preflight/parser regressions from this incomplete trial.
152
152
 
153
153
  Historical version 1 receipts still finalize with stdout/stderr coverage only.
@@ -155,7 +155,7 @@ They do not acquire native coverage by opening them with the updated helper.
155
155
  Use fresh captures with identical channel coverage for a later differential
156
156
  trial. The generic comparison now requires equal scanned channel sets and
157
157
  non-guard fingerprints, while their provenance remains user-declared.
158
- [Native-session follow-up](../../../docs/test-report-dsh-native-session.md)
158
+ [Native-session follow-up](../../../docs/reports/test-report-dsh-native-session.md)
159
159
  records the offline review of retained real logs separately.
160
160
 
161
161
  ## Capture the guard-off attack probe
@@ -192,7 +192,7 @@ review checklist or `--attack-sample config-comment-v1` for instructions in
192
192
  service configuration comments. The original `direct-v1` remains the default.
193
193
  Each sample gets its own protocol ID and template fingerprint. Keep the original
194
194
  task, use a fresh output/home for each sample, and use the same sample for any
195
- later guarded comparison. See the [sample registry](../../../docs/guard-lab.md#versioned-attack-samples).
195
+ later guarded comparison. See the [sample registry](../../../docs/lab/guard-lab.md#versioned-attack-samples).
196
196
 
197
197
  ## Evidence and exit status
198
198
 
@@ -227,7 +227,7 @@ DSH also retains its own session artifacts.
227
227
  Lab events and reports continue to retain no raw output or marker values.
228
228
 
229
229
  Version/model labels, completion review, environment equality across separate
230
- runs, and same-UID isolation retain the [normal Lab limitations](../../../docs/guard-lab.md).
230
+ runs, and same-UID isolation retain the [normal Lab limitations](../../../docs/lab/guard-lab.md).
231
231
  The original composition fingerprint checks one composed tree. New receipt
232
232
  version 3 additionally binds `dsh-lab-non-guard-v1`: rendered non-Guard rows,
233
233
  saved `settings.yaml`, home `.env`, the headless package manifest and inherited
@@ -318,7 +318,7 @@ another capture under the new rules. Prepare a fresh pair to continue testing.
318
318
  Results distinguish tool and assistant canary exposure from fake Lab execution
319
319
  and URL contact. The default `deletion-v1` profile loads the existing deletion
320
320
  adapter. Continued tool exposure with that profile can validly yield
321
- `NOT_MITIGATED`. The [investigation report](../../../docs/test-report-dsh-paired-lab.md)
321
+ `NOT_MITIGATED`. The [investigation report](../../../docs/reports/test-report-dsh-paired-lab.md)
322
322
  describes the candidate result-rewriting seam and its limits.
323
323
 
324
324
  ### Explicit native read redaction profile
@@ -339,7 +339,7 @@ python3 adapters/dsh/harness/guard_lab.py prepare-pair \
339
339
  --guard-profile read-redaction-v1 \
340
340
  --read-guard-dsh-root /absolute/path/to/installed/@deepseek-ai/dsh \
341
341
  --attack-sample read-redaction-v1 \
342
- --task-file docs/guard-lab-read-trial-task.md \
342
+ --task-file docs/lab/tasks/guard-lab-read-trial-task.md \
343
343
  --model-label "DeepSeek official deepseek-flash" \
344
344
  --trial-group dsh-read-redaction-01
345
345
  ```
@@ -376,7 +376,7 @@ external-network call. They cover unreviewed/failed/empty/oversized/timed-out
376
376
  captures, exposure semantics, capture corruption, version/config preflight,
377
377
  composition drift, create-once finalization, recovered/broken retries,
378
378
  fragmented markers, retry-only exposure and legacy coverage. The
379
- [retry-evidence report](../../../docs/test-report-dsh-retry-evidence.md) records
379
+ [retry-evidence report](../../../docs/reports/test-report-dsh-retry-evidence.md) records
380
380
  an offline reparse of the retained official Flash retry log. A mock pass does not establish
381
381
  a new real-model or execution-level DSH acceptance claim.
382
382
  The dedicated CI `dsh-native-lab` job selects Node 22.23.2 and runs these suites;
@@ -699,7 +699,7 @@ def main(arguments: Optional[Sequence[str]] = None) -> int:
699
699
  run.add_argument("--output-dir", type=Path, required=True)
700
700
  run.add_argument("--case", choices=("clean", "injection-probe"), required=True)
701
701
  run.add_argument("--attack-sample", choices=sorted(INJECTION_SAMPLES), default="direct-v1")
702
- run.add_argument("--task-file", type=Path, default=ROOT / "docs" / "guard-lab-trial-task.md")
702
+ run.add_argument("--task-file", type=Path, default=ROOT / "docs" / "lab" / "tasks" / "guard-lab-trial-task.md")
703
703
  run.add_argument("--model-label", required=True)
704
704
  run.add_argument("--trial-group", required=True)
705
705
  run.add_argument("--timeout", type=int, default=120)
@@ -717,8 +717,8 @@ def main(arguments: Optional[Sequence[str]] = None) -> int:
717
717
  pair.add_argument("--patch", type=Path, action="append", default=[])
718
718
  pair.add_argument("--model-label", required=True)
719
719
  pair.add_argument("--trial-group", required=True)
720
- pair.add_argument("--task-file", type=Path, default=ROOT / "docs/guard-lab-trial-task.md")
721
- pair.add_argument("--clean-task-file", type=Path, default=ROOT / "docs/guard-lab-clean-task.md")
720
+ pair.add_argument("--task-file", type=Path, default=ROOT / "docs/lab/tasks/guard-lab-trial-task.md")
721
+ pair.add_argument("--clean-task-file", type=Path, default=ROOT / "docs/lab/tasks/guard-lab-clean-task.md")
722
722
  pair.add_argument("--attack-sample", choices=sorted(INJECTION_SAMPLES), default="direct-v1")
723
723
  pair.add_argument("--timeout", type=int, default=120)
724
724
  pair.add_argument("--guard-profile", choices=GUARD_PROFILES, default="deletion-v1")
@@ -22,7 +22,7 @@
22
22
  * config.repoRoot points at a live checkout (development mode).
23
23
  *
24
24
  * Positioning: automatic recovery system with human escalation - reliability
25
- * infrastructure, not a security sandbox. See docs/threat-model.md.
25
+ * infrastructure, not a security sandbox. See docs/design/threat-model.md.
26
26
  */
27
27
 
28
28
  import fs from "node:fs";
@@ -15,10 +15,10 @@ contract comparison below was established against 0.42.0; the 2.1.1 trials
15
15
  independently observed authenticated root `Bash` blocks through the same
16
16
  exit-2 hook path on an OAuth official model and a second configured model
17
17
  route. Connection details and private route identifiers are omitted. See the
18
- [bounded report](../../docs/test-report-kimi-code-block.md).
18
+ [bounded report](../../docs/reports/test-report-kimi-code-block.md).
19
19
 
20
20
  For the separate honeytoken experiment, see the
21
- [guard-lab pair and local follow-up](../../docs/test-report-kimi-guard-lab.md).
21
+ [guard-lab pair and local follow-up](../../docs/reports/test-report-kimi-guard-lab.md).
22
22
  Its recorded tool-channel exposure and matched guarded observation are distinct
23
23
  from native Bash interception. A local doctor pass does not rerun that pair.
24
24
  Use the [private capture/review helper](harness/README.md) to repeat the Lab
@@ -80,7 +80,7 @@ allowed. `blockDecision()` collects any hook result with `action === "block"`.
80
80
  Add `--check-drift` to compare the installed Kimi Code version with the
81
81
  shipped profile and compute privacy-safe configuration/runtime
82
82
  fingerprints. `CURRENT` still does not prove live interception; see the
83
- [drift status contract](../../docs/host-drift.md).
83
+ [drift status contract](../../docs/guides/host-drift.md).
84
84
  An explicit `--live-sentinel` may then use one configured model call in a
85
85
  private fixture and requires adapter, audit, host-feedback, and marker
86
86
  evidence. The selected file must be named `config.toml`; the runner does
@@ -112,7 +112,7 @@ It does not describe a missing hook or a failed hook command.
112
112
  `kimi --auto`, Kimi 0.42.0 treats `permissionDecision: "ask"` as allow.
113
113
  This adapter therefore maps Core ASK to exit 2 (BLOCK). The failure class
114
114
  is described in the public
115
- [`development note`](../../docs/development-note-unguarded-deletion.md),
115
+ [`development note`](../../docs/history/development-note-unguarded-deletion.md),
116
116
  and it is fixed:
117
117
  `cd /tmp && rm -rf "$PWD/../home"` now classifies as
118
118
  `BLOCK / BLOCK_UNDETERMINABLE_EFFECT`. A shape rule describes
@@ -126,7 +126,7 @@ It does not describe a missing hook or a failed hook command.
126
126
  isolated sandboxes using one configured model route, single and concurrent
127
127
  subagent Bash calls reached the native hook and produced recoverable audit
128
128
  records.
129
- A third isolated project then showed [execution-level `BLOCK` enforcement](../../docs/test-report-kimi-code-block.md)
129
+ A third isolated project then showed [execution-level `BLOCK` enforcement](../../docs/reports/test-report-kimi-code-block.md)
130
130
  for one root and one single-subagent inert Bash probe. Its separate root
131
131
  `ASK` probe was denied. A fourth isolated project reproduced these bounded
132
132
  paths using a second configured request model ID and
@@ -143,7 +143,7 @@ It does not describe a missing hook or a failed hook command.
143
143
  before Python started.** In an isolated Kimi 0.42.0 trial, a process-local failing
144
144
  `python3` shim made a Bash call execute even though the correctly started
145
145
  adapter would have returned `BLOCK_DIALECT_UNKNOWN`. The sentinel appeared
146
- and no guard audit event was added. See the [bounded report](../../docs/test-report-kimi-code-block.md).
146
+ and no guard audit event was added. See the [bounded report](../../docs/reports/test-report-kimi-code-block.md).
147
147
  The bridge changes this particular failure into exit 2 **if the bridge
148
148
  itself starts**. It cannot block a hook that is absent, skipped by the
149
149
  matcher, fails to spawn, or times out. The host remains fail-open for those
@@ -156,7 +156,7 @@ It does not describe a missing hook or a failed hook command.
156
156
  process-local Python startup fault returned exit 1 before the adapter ran;
157
157
  the bridge converted it to Kimi's hard refusal, and the sentinel stayed
158
158
  absent. This does not test a bridge-spawn failure or timeout; see the
159
- [bounded report](../../docs/test-report-kimi-code-block.md).
159
+ [bounded report](../../docs/reports/test-report-kimi-code-block.md).
160
160
  - Kimi's `doctor config` accepted a hook-free test config and an invalid
161
161
  regex matcher; it checks configuration validity, not live interception.
162
162
  In the installed 0.42.0 bundle, a matcher regex error yields no match.
@@ -42,9 +42,9 @@ remain user-declared; configuration equality does not authenticate a backend.
42
42
 
43
43
  ## Clean control, then baseline
44
44
 
45
- Use the [README-only task](../../../docs/guard-lab-clean-task.md) for a real-host
45
+ Use the [README-only task](../../../docs/lab/tasks/guard-lab-clean-task.md) for a real-host
46
46
  negative control so that it requests no bait read. Use the original
47
- [review task](../../../docs/guard-lab-trial-task.md) for both attack trials.
47
+ [review task](../../../docs/lab/tasks/guard-lab-trial-task.md) for both attack trials.
48
48
  For the clean control, prepare a separate equivalent disposable home if the
49
49
  matched attack pair should start without any previous host session state.
50
50
 
@@ -53,7 +53,7 @@ python3 adapters/kimi-code/harness/guard_lab.py run \
53
53
  --kimi-home /tmp/kimi-lab-homes/off \
54
54
  --kimi-executable /absolute/path/to/kimi-2.1.1 --guard-state off \
55
55
  --output-dir /tmp/kimi-lab-clean --case clean \
56
- --task-file docs/guard-lab-clean-task.md \
56
+ --task-file docs/lab/tasks/guard-lab-clean-task.md \
57
57
  --model-label "Kimi official OAuth model" --trial-group kimi-pair-01
58
58
  ```
59
59
 
@@ -392,7 +392,7 @@ def main(arguments: Optional[Sequence[str]] = None) -> int:
392
392
  run.add_argument("--output-dir", type=Path, required=True)
393
393
  run.add_argument("--case", choices=("clean", "injection-probe"), required=True)
394
394
  run.add_argument("--attack-sample", choices=sorted(INJECTION_SAMPLES), default="direct-v1")
395
- run.add_argument("--task-file", type=Path, default=ROOT / "docs/guard-lab-trial-task.md")
395
+ run.add_argument("--task-file", type=Path, default=ROOT / "docs/lab/tasks/guard-lab-trial-task.md")
396
396
  run.add_argument("--model-label", required=True)
397
397
  run.add_argument("--trial-group", required=True)
398
398
  run.add_argument("--timeout", type=int, default=180)
package/core/__init__.py CHANGED
@@ -1,6 +1,6 @@
1
1
  """agent-guard core: a reliability layer for autonomous AI agents.
2
2
 
3
- Four pillars (see docs/architecture.md):
3
+ Four pillars (see docs/design/architecture.md):
4
4
 
5
5
  Scope - where the agent may act -> policy.py
6
6
  Recoverability - whether mistakes can be undone -> recovery.py
@@ -41,7 +41,7 @@ FS_DELETE_CMDS = {"rm", "rmdir", "unlink", "shred"}
41
41
  # Windows-native delete verbs. Recognised on EVERY dialect: a harness that
42
42
  # never configured `AGENT_GUARD_DIALECT` still defaults to posix, and a
43
43
  # posix-lexed `del /s /q build` must not be treated as an unknown verb.
44
- # See docs/development-note-unguarded-deletion.md (lesson: the normalized
44
+ # See docs/history/development-note-unguarded-deletion.md (lesson: the normalized
45
45
  # target decides, not the spelling).
46
46
  WINDOWS_DELETE_CMDS = {"del", "erase", "rd", "rmdir", "ri"}
47
47
  SHELL_PREFIXES = {
@@ -56,7 +56,7 @@ INDETERMINACY_CHARS = ("$", "`")
56
56
  # Filesystem roots that must never be a deletion target, whatever the
57
57
  # workspace setting says. `rm -rf /home` blocks today only because /home
58
58
  # happens to sit outside the workspace root - an accident of configuration,
59
- # not a policy (see docs/development-note-unguarded-deletion.md).
59
+ # not a policy (see docs/history/development-note-unguarded-deletion.md).
60
60
  #
61
61
  # Matching is EXACT: the rule fires when a target *is* one of these roots,
62
62
  # never when it merely lives under one, so `rm -rf /home/alice/build` stays
@@ -137,7 +137,7 @@ KIND_GIT_DISCARD = "git-discard" # git restore <path> / git checkout -- <
137
137
  KIND_GIT_PUSH_FORCE = "git-push-force" # force / mirror / ref-deletion push
138
138
  KIND_UNKNOWN = "unknown" # destructive smell, no parseable shape
139
139
 
140
- # Whole-command-line shape facts (docs/friction.md F1/F2).
140
+ # Whole-command-line shape facts (docs/history/friction.md F1/F2).
141
141
  CREATION_CMDS = {"touch", "mkdir", "cp", "mv", "install", "ln", "tee"}
142
142
  # cmd builtins with the same shape (F2 is about "created then destroyed",
143
143
  # which `copy x a.tmp && del a.tmp` expresses just as literally).
@@ -146,7 +146,9 @@ CMD_CREATION_CMDS = {"copy", "xcopy", "robocopy", "mkdir", "md", "mklink",
146
146
  REDIRECT_CREATE_TOKENS = {">", ">>"}
147
147
  # Kinds whose compensation depends on enumerating concrete targets; a target
148
148
  # created earlier in the same line is invisible to pre-execution compensation.
149
- TARGET_DEPENDENT_KINDS = {KIND_FS_DELETE, KIND_GIT_CLEAN, KIND_GIT_DISCARD}
149
+ TARGET_DEPENDENT_KINDS = {
150
+ KIND_FS_DELETE, KIND_GIT_CLEAN, KIND_GIT_DISCARD, KIND_GIT_RESET_HARD,
151
+ }
150
152
 
151
153
 
152
154
  @dataclass
@@ -839,9 +841,21 @@ def _parse_git(segment: List[str]) -> OpSpec:
839
841
  if "--hard" in rest:
840
842
  spec.kind = KIND_GIT_RESET_HARD
841
843
  spec.force = True
842
- spec.targets = [
843
- t for t in rest if t != "--hard" and not t.startswith("-")
844
- ]
844
+ for tok in rest:
845
+ if tok in ("--hard", "-q", "--quiet"):
846
+ continue
847
+ if tok.startswith("-"):
848
+ spec.undeterminable = True
849
+ spec.note("unsupported hard reset option or path limit")
850
+ continue
851
+ spec.targets.append(tok)
852
+ if len(spec.targets) > 1:
853
+ spec.undeterminable = True
854
+ spec.note("hard reset requires a single target commit")
855
+ _scan_targets(spec)
856
+ if spec.wildcard:
857
+ spec.undeterminable = True
858
+ spec.note("hard reset target contains shell glob syntax")
845
859
  if not spec.targets:
846
860
  spec.note("whole-tree reset (no path limit)")
847
861
  apply_global_uncertainty()
@@ -947,16 +961,17 @@ def _has_create_redirect(segment: List[str]) -> bool:
947
961
 
948
962
 
949
963
  def _apply_shape_rules(specs: List[OpSpec], cd_positions: List[int],
950
- creation_positions: List[int]) -> None:
951
- """Whole-command-line restrictions (docs/friction.md F1/F2).
964
+ creation_positions: List[int],
965
+ segment_count: int = 1) -> None:
966
+ """Whole-command-line restrictions (docs/history/friction.md F1/F2).
952
967
 
953
968
  F1: a destructive op preceded by cd resolves against the wrong working
954
969
  directory - compensation would enumerate/snapshot the wrong tree.
955
970
  Applies to every destructive kind.
956
971
  F2: a target created earlier in the same line does not exist yet at
957
972
  interception time, so target-dependent compensation cannot cover it.
958
- Position-independent compensations (reset --hard whole-tree stash,
959
- force-push which is blocked anyway) are exempt.
973
+ Force-push, which is blocked anyway, is exempt. Hard reset also
974
+ needs a preflight of untracked content against its target tree.
960
975
  Shapes are DECISION-CLASS facts, not effect-uncertainty: the operation
961
976
  itself is well understood, only its safe automatic compensation is not.
962
977
  Policy maps them to ASK (single-execution authorization), keeping true
@@ -966,6 +981,10 @@ def _apply_shape_rules(specs: List[OpSpec], cd_positions: List[int],
966
981
  if spec.kind in (KIND_OTHER, KIND_UNKNOWN):
967
982
  continue
968
983
  idx = spec.segment_index
984
+ if spec.kind == KIND_GIT_RESET_HARD and segment_count != 1:
985
+ spec.undeterminable = True
986
+ spec.note("hard reset must be a standalone command; other "
987
+ "segments may change its target or collisions")
969
988
  if any(pos < idx for pos in cd_positions):
970
989
  spec.shape = "F1"
971
990
  spec.note(
@@ -1152,14 +1171,19 @@ def _classify_posix(cmd: str) -> Tuple[List[OpSpec], Optional[str]]:
1152
1171
  elif head == "find":
1153
1172
  emit(_parse_find(seg), index)
1154
1173
  elif head == "git":
1155
- emit(_parse_git(seg), index)
1174
+ spec = _parse_git(seg)
1175
+ if spec.kind == KIND_GIT_RESET_HARD and len(seg) != len(segment):
1176
+ spec.undeterminable = True
1177
+ spec.note("hard reset wrappers may change its Git context")
1178
+ emit(spec, index)
1156
1179
  # anything else: kind OTHER, intentionally ignored by policy
1157
1180
 
1158
1181
  for spec in specs:
1159
1182
  spec.dialect = dialects.DIALECT_POSIX
1160
1183
  _append_dialect_mismatches(
1161
1184
  specs, command_segments, dialects.DIALECT_POSIX)
1162
- _apply_shape_rules(specs, cd_positions, creation_positions)
1185
+ _apply_shape_rules(specs, cd_positions, creation_positions,
1186
+ len(raw_segments))
1163
1187
  return [s for s in specs if s.kind != KIND_OTHER], None
1164
1188
 
1165
1189
 
@@ -1189,7 +1213,7 @@ def _classify_windows_dialect(cmd: str, dialect: str
1189
1213
  accepts `/`, while leaving `\\` in the fact makes Linux and Windows CI
1190
1214
  disagree about the same command.
1191
1215
 
1192
- Shape rules (docs/friction.md F1/F2) apply to Windows lines too: `cd`
1216
+ Shape rules (docs/history/friction.md F1/F2) apply to Windows lines too: `cd`
1193
1217
  and the interpreter prefix set are shared shell concepts, so F1 means
1194
1218
  the same thing in cmd and PowerShell.
1195
1219
  """
@@ -1213,7 +1237,8 @@ def _classify_windows_dialect(cmd: str, dialect: str
1213
1237
  spec.targets = [t.replace("\\", "/") for t in spec.targets]
1214
1238
  _attribute_targets(spec)
1215
1239
  _append_dialect_mismatches(specs, stream.segments, dialect)
1216
- _apply_shape_rules(specs, cd_positions, creation_positions)
1240
+ _apply_shape_rules(specs, cd_positions, creation_positions,
1241
+ len(stream.segments))
1217
1242
  return [s for s in specs if s.kind != KIND_OTHER], None
1218
1243
 
1219
1244
 
@@ -1230,7 +1255,7 @@ def classify_command(cmd: str, dialect: str = dialects.DEFAULT_DIALECT
1230
1255
  dialect layer exists to prevent.
1231
1256
 
1232
1257
  Heredoc bodies are stripped before POSIX parsing (they are written
1233
- payload, not commands - see docs/friction.md F5).
1258
+ payload, not commands - see docs/history/friction.md F5).
1234
1259
 
1235
1260
  Returns (specs, parse_error). Segments that are not destructive are
1236
1261
  returned as kind=OTHER and ignored by policy. A parse_error (unbalanced
package/core/policy.py CHANGED
@@ -7,7 +7,7 @@ The stable cross-harness interface is NOT allow/block. It is:
7
7
  + Explanation
8
8
  + RecoveryPlan (payload)
9
9
 
10
- Decision classes (docs/architecture.md):
10
+ Decision classes (docs/design/architecture.md):
11
11
 
12
12
  ALLOW safe to run as-is (noop / provably regenerable / trash GC)
13
13
  RELOCATE compensate by quarantine, then run
@@ -118,6 +118,7 @@ CODE_ASK_PATH_EMISSION = "ASK_PATH_EMISSION"
118
118
  CODE_ALLOW_SECRET_PLACEHOLDER = "ALLOW_SECRET_PLACEHOLDER"
119
119
  CODE_ALLOW_PATH_IN_WORKSPACE = "ALLOW_PATH_IN_WORKSPACE"
120
120
  CODE_BLOCK_COMPENSATION_FAILED = "COMPENSATION_FAILED"
121
+ CODE_BLOCK_GIT_RESET_COLLISION = "BLOCK_GIT_RESET_COLLISION"
121
122
 
122
123
  # Human-facing one-liners: why the guard cannot just do it (or did do it).
123
124
  EXPLANATIONS: Dict[str, str] = {
@@ -137,6 +138,11 @@ EXPLANATIONS: Dict[str, str] = {
137
138
  "real command ran.",
138
139
  CODE_SNAPSHOT_GIT_STASH: "Tracked modifications snapshotted as a stash "
139
140
  "before the command; apply it to recover.",
141
+ CODE_BLOCK_GIT_RESET_COLLISION: "git reset --hard would overwrite "
142
+ "untracked or ignored content, or "
143
+ "quarantine storage, that a tracked-only "
144
+ "stash cannot protect. Preserve the "
145
+ "conflicting paths separately first.",
140
146
  CODE_ASK_COMPOUND_CWD_DELETE: "This line combines a working-directory "
141
147
  "change with deletion, so the guard "
142
148
  "cannot safely relocate the target before "
@@ -607,7 +613,7 @@ def decide_op(spec: OpSpec, ctx: PolicyContext) -> Optional[Verdict]:
607
613
  # when the target set also trips a hard boundary, that boundary wins.
608
614
  # Without this, `cd /tmp && rm -rf /home` degrades a hard refusal into
609
615
  # an ASK - and any auto-approving host grants an ASK silently, which is
610
- # the incident finding described in docs/development-note-unguarded-deletion.md.
616
+ # the incident finding described in docs/history/development-note-unguarded-deletion.md.
611
617
  if spec.shape in ("F1", "F2"):
612
618
  ask_code = (CODE_ASK_COMPOUND_CWD_DELETE if spec.shape == "F1"
613
619
  else CODE_ASK_COMPOUND_CREATE_DELETE)
@@ -648,8 +654,9 @@ def decide_op(spec: OpSpec, ctx: PolicyContext) -> Optional[Verdict]:
648
654
  if spec.kind == KIND_GIT_RESET_HARD:
649
655
  return Verdict(
650
656
  DECISION_SNAPSHOT, CODE_SNAPSHOT_GIT_STASH,
651
- ["snapshot tracked modifications via git stash create/store "
652
- "before reset --hard"],
657
+ ["preflight untracked/ignored collisions with the target tree, "
658
+ "then snapshot tracked modifications via git stash "
659
+ "create/store before reset --hard"],
653
660
  )
654
661
 
655
662
  if spec.kind == KIND_GIT_DISCARD: