@mokuyoaxis/agent-guard 0.2.3 → 0.2.5-rc1

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 (80) hide show
  1. package/README.md +158 -571
  2. package/README.zh-CN.md +133 -490
  3. package/SECURITY.md +53 -0
  4. package/adapters/INTEGRATION.md +8 -6
  5. package/adapters/claude/README.md +3 -3
  6. package/adapters/claude/harness/README.md +1 -1
  7. package/adapters/codex/harness/README.md +2 -2
  8. package/adapters/dsh/README.md +17 -6
  9. package/adapters/dsh/harness/README.md +8 -8
  10. package/adapters/dsh/harness/guard_lab.py +3 -3
  11. package/adapters/dsh/lib/index.js +1 -1
  12. package/adapters/kimi-code/README.md +7 -7
  13. package/adapters/kimi-code/harness/README.md +3 -3
  14. package/adapters/kimi-code/harness/guard_lab.py +1 -1
  15. package/assets/linux-do-community.svg +19 -0
  16. package/core/__init__.py +1 -1
  17. package/core/classifier.py +66 -17
  18. package/core/policy.py +28 -13
  19. package/core/recovery.py +261 -24
  20. package/core/redaction.py +122 -21
  21. package/core/trash_index.py +193 -0
  22. package/docs/README.md +113 -0
  23. package/docs/{architecture.md → design/architecture.md} +51 -12
  24. package/docs/{compatibility.md → design/compatibility.md} +124 -4
  25. package/docs/{threat-model.md → design/threat-model.md} +10 -8
  26. package/docs/guides/getting-started.md +104 -0
  27. package/docs/{harness-capabilities.md → guides/harness-capabilities.md} +14 -9
  28. package/docs/guides/trash-index.md +106 -0
  29. package/docs/{development-note-unguarded-deletion.md → history/development-note-unguarded-deletion.md} +2 -2
  30. package/docs/{friction.md → history/friction.md} +123 -0
  31. package/docs/{secret-guard-analysis.md → history/secret-guard-analysis.md} +12 -12
  32. package/docs/{secret-guard-architecture.md → history/secret-guard-architecture.md} +2 -2
  33. package/docs/{secret-guard-design.md → history/secret-guard-design.md} +14 -14
  34. package/docs/lab/cases/injection-case-fake-ai-api.md +346 -0
  35. package/docs/{guard-lab.md → lab/guard-lab.md} +15 -13
  36. package/docs/{release-notes-0.2.0-rc1.md → releases/release-notes-0.2.0-rc1.md} +3 -3
  37. package/docs/{release-notes-0.2.0.md → releases/release-notes-0.2.0.md} +5 -5
  38. package/docs/{release-notes-0.2.1.md → releases/release-notes-0.2.1.md} +6 -6
  39. package/docs/{release-notes-0.2.2.md → releases/release-notes-0.2.2.md} +2 -2
  40. package/docs/{release-notes-0.2.3-rc1.md → releases/release-notes-0.2.3-rc1.md} +1 -1
  41. package/docs/{release-notes-0.2.3-rc2.md → releases/release-notes-0.2.3-rc2.md} +9 -9
  42. package/docs/{release-notes-0.2.3.md → releases/release-notes-0.2.3.md} +3 -3
  43. package/docs/releases/release-notes-0.2.4.md +89 -0
  44. package/docs/releases/release-notes-0.2.5-rc1.md +91 -0
  45. package/docs/{test-report-claude-code-harness.md → reports/test-report-claude-code-harness.md} +5 -5
  46. package/docs/reports/test-report-dsh-0.2.4-ptc.md +79 -0
  47. package/docs/{test-report-dsh-guard-lab.md → reports/test-report-dsh-guard-lab.md} +1 -1
  48. package/docs/{test-report-dsh-native-session.md → reports/test-report-dsh-native-session.md} +1 -1
  49. package/docs/{test-report-dsh-paired-lab.md → reports/test-report-dsh-paired-lab.md} +1 -1
  50. package/docs/{test-report-dsh-real-followup.md → reports/test-report-dsh-real-followup.md} +1 -1
  51. package/docs/{test-report-dsh-retry-evidence.md → reports/test-report-dsh-retry-evidence.md} +1 -1
  52. package/docs/{test-report-dsh-v0.1.1.md → reports/test-report-dsh-v0.1.1.md} +4 -4
  53. package/docs/{test-report-kimi-code-block.md → reports/test-report-kimi-code-block.md} +3 -3
  54. package/docs/{test-report-kimi-guard-lab.md → reports/test-report-kimi-guard-lab.md} +3 -3
  55. package/docs/{test-report-release-readiness-0.2.3.md → reports/test-report-release-readiness-0.2.3.md} +1 -1
  56. package/docs/{test-report-workbuddy-windows-core.md → reports/test-report-workbuddy-windows-core.md} +1 -1
  57. package/docs/{test-report-zcode-glm-flash.md → reports/test-report-zcode-glm-flash.md} +2 -2
  58. package/package.json +4 -2
  59. package/skills/delete-guard/SKILL.md +80 -7
  60. package/skills/delete-guard/references/policy.md +104 -8
  61. package/skills/delete-guard/scripts/check.py +22 -0
  62. package/skills/delete-guard/scripts/restore.py +34 -7
  63. package/skills/delete-guard/scripts/safe_delete.py +52 -29
  64. package/skills/delete-guard/scripts/status.py +52 -0
  65. package/skills/exfil-guard/SKILL.md +23 -11
  66. package/skills/exfil-guard/references/channels.md +9 -2
  67. package/skills/exfil-guard/references/rules.md +83 -6
  68. package/skills/exfil-guard/scripts/_payload.py +20 -0
  69. package/skills/exfil-guard/scripts/check_span.py +5 -1
  70. package/skills/exfil-guard/scripts/sanitize.py +6 -3
  71. /package/docs/{host-drift.md → guides/host-drift.md} +0 -0
  72. /package/docs/{publishing-from-ephemeral-environments.md → guides/publishing-from-ephemeral-environments.md} +0 -0
  73. /package/docs/{guard-lab-clean-task.md → lab/tasks/guard-lab-clean-task.md} +0 -0
  74. /package/docs/{guard-lab-read-trial-task.md → lab/tasks/guard-lab-read-trial-task.md} +0 -0
  75. /package/docs/{guard-lab-trial-task.md → lab/tasks/guard-lab-trial-task.md} +0 -0
  76. /package/docs/{test-report-codex-gpt-5.6-sol.md → reports/test-report-codex-gpt-5.6-sol.md} +0 -0
  77. /package/docs/{test-report-codex-gpt-6-astra-high.md → reports/test-report-codex-gpt-6-astra-high.md} +0 -0
  78. /package/docs/{test-report-dsh-0.1.5-rc.1.md → reports/test-report-dsh-0.1.5-rc.1.md} +0 -0
  79. /package/docs/{test-report-dsh-0.2-upgrade.md → reports/test-report-dsh-0.2-upgrade.md} +0 -0
  80. /package/docs/{test-report-dsh-read-redaction.md → reports/test-report-dsh-read-redaction.md} +0 -0
package/SECURITY.md ADDED
@@ -0,0 +1,53 @@
1
+ # Security policy
2
+
3
+ ## Reporting
4
+
5
+ Open a GitHub issue for non-sensitive issues, or contact the maintainer
6
+ directly for anything you believe is exploitable. Please include the
7
+ verdict JSON and audit lines involved.
8
+
9
+ ## What agent-guard claims to be
10
+
11
+ Reliability infrastructure: it makes destructive actions reversible by
12
+ default and records evidence. It is **not a security sandbox** - an agent
13
+ with the same OS privileges as the guard can bypass it. See
14
+ [docs/design/threat-model.md](docs/design/threat-model.md) before relying on it.
15
+
16
+ ## Expected scanner hits on this repository
17
+
18
+ This repository documents, tests, and demonstrates destructive commands -
19
+ that is its subject matter. Static scanners (including `dsh-plugin-gate`)
20
+ will therefore report hits such as:
21
+
22
+ - `rm_recursive` / command patterns inside `README*`, `docs/`, and
23
+ especially `tests/` fixtures, which must contain real command strings to
24
+ exercise the classifier;
25
+ - `dynamic_require` in `core/policy.py` (the `subprocess` call backing
26
+ `git check-ignore`);
27
+ - credential-adjacent wording in `docs/guides/publishing-from-ephemeral-environments.md`
28
+ (a guide about *avoiding* credential leaks).
29
+
30
+ As of v0.1.0 a full self-scan reports 61 hits (29 high / 10 medium / 22
31
+ low) with **zero in runtime decision paths** - all are documentation or
32
+ test fixtures. If you find a hit outside docs/tests/fixtures, please
33
+ report it.
34
+
35
+ ## Data handling
36
+
37
+ The command guards store recovery and audit data locally. The default bucket
38
+ is the workspace's `.agent-trash/`; `AGENT_GUARD_TRASH` can select a custom or
39
+ external bucket. Recovery may also write Git metadata, including local exclude
40
+ rules and retained stashes. Linked worktrees can share Git metadata outside
41
+ the selected worktree. Diagnostics and Lab commands use their declared output
42
+ locations. A dry-run assessment can still write metadata.
43
+
44
+ There is no automatic telemetry. Built-in Lab controls call no model and use
45
+ only bounded loopback observation. Explicit live-host/model tests can contact
46
+ the configured provider through the host and consume quota; they are separate
47
+ from local command checks and require a selected experiment scope.
48
+
49
+ Recovery manifests, CLI diagnostics and historical audit records can contain
50
+ exact paths or other private text. Audit minimization in the 0.2.5-rc1 source
51
+ candidate does not make every output or old record secret-free. The exfil text
52
+ CLIs return decisions/plans or sanitized stdout; they do not automatically
53
+ persist egress audit events. Review and redact evidence before sharing it.
@@ -2,7 +2,7 @@
2
2
 
3
3
  This is a checklist for a user or their agent, **not** a claim that an
4
4
  unlisted host is supported. Start with the [capability and evidence
5
- matrix](../docs/harness-capabilities.md). A prompt, Skill, CLI call, or
5
+ matrix](../docs/guides/harness-capabilities.md). A prompt, Skill, CLI call, or
6
6
  adapter exit code alone does not prove automatic tool interception.
7
7
 
8
8
  ## 1. Identify the actual boundary
@@ -33,7 +33,7 @@ or a public report. If the host contract or version is unclear, mark it
33
33
  second copy of the rule table. Inspect the [Claude](claude/pre_tool_use.py),
34
34
  [Kimi](kimi-code/pre_tool_use.py), and [DSH](dsh/lib/index.js) adapters as
35
35
  examples of host-specific mapping, not drop-in templates.
36
- - **No verified blocking event:** use the [Skills](../skills/) and explicit
36
+ - **No verified blocking event:** use the [Skills](../skills) and explicit
37
37
  CLI cooperatively. Say `Skill/CLI only`; do not claim native interception.
38
38
  A hook limited to some tools does not cover other tools or hidden uploads.
39
39
 
@@ -42,8 +42,10 @@ call. It must never silently become allow. Treat malformed payloads and
42
42
  adapter failures conservatively **when the adapter is invoked**; this does
43
43
  not protect a call when the host never starts the hook. For a shell tool,
44
44
  `check.py --enforce` may relocate files or snapshot Git state, so use it only
45
- in an authorized execution path; use advisory mode for non-mutating policy
46
- checks.
45
+ in an authorized execution path. Advisory mode assesses without changing
46
+ command targets, but may initialize quarantine/audit metadata and a Git local
47
+ exclude rule. Its exit 0 does not authorize a BLOCK or ASK decision. See the
48
+ [assessment contract](../skills/delete-guard/references/policy.md#assessment-and-dry-run-side-effects).
47
49
 
48
50
  ## 3. Configure and verify without destructive trials
49
51
 
@@ -73,7 +75,7 @@ For those two hosts, `--check-drift` adds local version/profile comparison and
73
75
  privacy-safe hook/runtime fingerprints. `STALE` asks for re-testing after a
74
76
  version change; it does not assert incompatibility. `CURRENT` still does not
75
77
  promote `host_interception` above `UNVERIFIED`. See the
76
- [host drift contract](../docs/host-drift.md).
78
+ [host drift contract](../docs/guides/host-drift.md).
77
79
 
78
80
  An explicit `--live-sentinel` can spend one configured model call to test one
79
81
  real root-agent Bash path in a private fixture. PASS requires a hashed exact
@@ -87,7 +89,7 @@ Report the host/version, tool and event, config scope, root/subagent path,
87
89
  dialect, model setup if one was used, the Core decision, host outcome, and
88
90
  independent non-execution observation. Label evidence as `CLI`, `Adapter`,
89
91
  `Hook observed`, or `Enforcement observed` using the
90
- [matrix definitions](../docs/harness-capabilities.md#evidence-levels).
92
+ [matrix definitions](../docs/guides/harness-capabilities.md#evidence-levels).
91
93
  Unknown versions or untested paths remain `UNVERIFIED`; no blocking event is
92
94
  `Skill/CLI only` or `UNSUPPORTED`. An agent's self-test is useful setup
93
95
  evidence, not an independent security boundary against that same agent or a
@@ -78,11 +78,11 @@ prompt.
78
78
  A passing check does **not** inspect Claude's merged settings, prove a
79
79
  running session loaded the hook, or verify host-level interception. For
80
80
  those claims, use the isolated host acceptance in the
81
- [capability matrix](../../docs/harness-capabilities.md).
81
+ [capability matrix](../../docs/guides/harness-capabilities.md).
82
82
  Add `--check-drift` to compare the installed Claude Code version with the
83
83
  shipped profile and compute privacy-safe configuration/runtime
84
84
  fingerprints. `CURRENT` still does not prove live interception; see the
85
- [drift status contract](../../docs/host-drift.md).
85
+ [drift status contract](../../docs/guides/host-drift.md).
86
86
  An explicit `--live-sentinel` may then use one configured model call in a
87
87
  private fixture and requires adapter, audit, host-feedback, and marker
88
88
  evidence. It keeps `dontAsk` and never enables permission bypass.
@@ -126,7 +126,7 @@ returns `BLOCK_DIALECT_UNKNOWN` and the hook exits 2.
126
126
  Validated end-to-end against real Claude Code sessions (2.1.270 and 2.1.273) with a
127
127
  scripted mock Anthropic endpoint standing in for the model, plus the
128
128
  `python3`-free regression tests. See
129
- [`docs/test-report-claude-code-harness.md`](../../docs/test-report-claude-code-harness.md)
129
+ [`docs/reports/test-report-claude-code-harness.md`](../../docs/reports/test-report-claude-code-harness.md)
130
130
  and the shipped harness in [`harness/`](harness/README.md).
131
131
 
132
132
  The guard child is spawned with `sys.executable`, never `python3` from
@@ -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.
@@ -125,6 +129,13 @@ is forwarded verbatim rather than swapped for POSIX, so `check.py` returns
125
129
 
126
130
  ## Notes
127
131
 
132
+ The [0.2.4 official Flash/PTC report](../../docs/reports/test-report-dsh-0.2.4-ptc.md)
133
+ also observed sampled root/child SDK Bash collision refusals. Its original root
134
+ PTC task failed; a separate summary completed. This does not establish general
135
+ PTC Node API mediation or injection L2. The 0.2.5-rc1 documentation update adds
136
+ no new native-host/model result; use the
137
+ [capability matrix](../../docs/guides/harness-capabilities.md) for the full scope.
138
+
128
139
  - Deletion commands inherit the caller's sandbox policy per invocation
129
140
  (`exec.agent.session`) through the native shell executor.
130
141
  - Once the adapter has registered its pre-execute listener, Core process and
@@ -136,7 +147,7 @@ is forwarded verbatim rather than swapped for POSIX, so `check.py` returns
136
147
  reproducing a test; a source checkout may contain later changes.
137
148
  - DSH `0.1.5-rc.1` package loading and one harmless execution-level `bash`
138
149
  block are independently verified in the
139
- [bounded host report](../../docs/test-report-dsh-0.1.5-rc.1.md). Model,
150
+ [bounded host report](../../docs/reports/test-report-dsh-0.1.5-rc.1.md). Model,
140
151
  subagent, concurrency, ASK UI and non-`bash` paths remain separate tests.
141
152
  - For repeatable baselines and reviewed guard-off/on Lab pairs, use the
142
153
  [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)
@@ -0,0 +1,19 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" width="1000" height="160" viewBox="0 0 1000 160" role="img" aria-labelledby="title desc">
2
+ <title id="title">LINUX DO community link</title>
3
+ <desc id="desc">A project-made banner linking to the LINUX DO community, not an official endorsement.</desc>
4
+ <defs>
5
+ <linearGradient id="background" x2="1" y2="1">
6
+ <stop offset="0" stop-color="#111827"/>
7
+ <stop offset="1" stop-color="#263b55"/>
8
+ </linearGradient>
9
+ </defs>
10
+ <rect width="1000" height="160" rx="18" fill="url(#background)"/>
11
+ <rect x="0" y="0" width="12" height="160" rx="6" fill="#f59e0b"/>
12
+ <rect x="40" y="33" width="11" height="11" fill="#f59e0b"/>
13
+ <rect x="55" y="33" width="11" height="11" fill="#f59e0b"/>
14
+ <rect x="40" y="48" width="11" height="11" fill="#f59e0b"/>
15
+ <rect x="55" y="48" width="11" height="11" fill="#f59e0b"/>
16
+ <text x="86" y="79" fill="#ffffff" font-family="Arial, Helvetica, sans-serif" font-size="49" font-weight="700" letter-spacing="2">LINUX DO</text>
17
+ <text x="87" y="115" fill="#cbd5e1" font-family="Arial, Helvetica, sans-serif" font-size="22">COMMUNITY LINK · 社区友链</text>
18
+ <path d="M790 80h145m-27-27 27 27-27 27" fill="none" stroke="#f59e0b" stroke-width="5" stroke-linecap="round" stroke-linejoin="round"/>
19
+ </svg>
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
@@ -33,7 +33,7 @@ import shlex
33
33
  from dataclasses import dataclass, field
34
34
  from typing import List, Optional, Tuple
35
35
 
36
- from . import dialects
36
+ from . import AUDIT_NAME, MANIFEST_NAME, STATE_NAME, dialects
37
37
 
38
38
  # ---------------------------------------------------------------- vocabulary
39
39
 
@@ -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
@@ -190,6 +192,7 @@ class PathSpec:
190
192
  inside_trash: bool = False
191
193
  protected: Optional[str] = None # None | ancestor-root | workspace-root
192
194
  # | outside-workspace | git-metadata
195
+ # | quarantine-control
193
196
  error: Optional[str] = None
194
197
 
195
198
  # ------------------------------------------------------------- path analysis
@@ -248,6 +251,26 @@ def _physical_keep_final(path: str) -> str:
248
251
  return os.path.join(os.path.realpath(parent), name)
249
252
 
250
253
 
254
+ def _quarantine_control_path(absolute: str, physical: str,
255
+ trash_root: str, trash_physical: str,
256
+ workspace: str) -> bool:
257
+ """Protect storage access and root metadata, retaining leaf-link location."""
258
+ # A configured final link is also the access path to an external bucket.
259
+ # Deleting its parent would sever that access even if storage is elsewhere.
260
+ if (inside_path(physical, workspace) and
261
+ any(inside_path(storage, physical) for storage in
262
+ (trash_physical, _physical_keep_final(trash_root)))):
263
+ return True
264
+ controls = {MANIFEST_NAME, AUDIT_NAME, STATE_NAME, STATE_NAME + ".tmp",
265
+ "sessions"}
266
+ for candidate in (physical, _physical_keep_final(absolute)):
267
+ if inside_path(candidate, trash_physical):
268
+ relative = os.path.relpath(candidate, trash_physical)
269
+ if relative.split(os.sep)[0] in controls:
270
+ return True
271
+ return False
272
+
273
+
251
274
  def workspace_boundary_root(workspace: str) -> str:
252
275
  """Physical form of a workspace root, for callers that compare roots."""
253
276
  return _physical(os.path.normpath(os.path.abspath(workspace)))
@@ -363,6 +386,9 @@ def classify_paths(
363
386
  # content. `rm -rf .` stays a hard BLOCK. (When no trash_root is
364
387
  # given, trash_physical is None and cannot match a real path.)
365
388
  spec.protected = "workspace-root"
389
+ elif trash_root and _quarantine_control_path(
390
+ absolute, physical, trash_root, trash_physical, workspace):
391
+ spec.protected = "quarantine-control"
366
392
  elif not spec.inside_workspace:
367
393
  spec.protected = "outside-workspace"
368
394
  else:
@@ -839,9 +865,21 @@ def _parse_git(segment: List[str]) -> OpSpec:
839
865
  if "--hard" in rest:
840
866
  spec.kind = KIND_GIT_RESET_HARD
841
867
  spec.force = True
842
- spec.targets = [
843
- t for t in rest if t != "--hard" and not t.startswith("-")
844
- ]
868
+ for tok in rest:
869
+ if tok in ("--hard", "-q", "--quiet"):
870
+ continue
871
+ if tok.startswith("-"):
872
+ spec.undeterminable = True
873
+ spec.note("unsupported hard reset option or path limit")
874
+ continue
875
+ spec.targets.append(tok)
876
+ if len(spec.targets) > 1:
877
+ spec.undeterminable = True
878
+ spec.note("hard reset requires a single target commit")
879
+ _scan_targets(spec)
880
+ if spec.wildcard:
881
+ spec.undeterminable = True
882
+ spec.note("hard reset target contains shell glob syntax")
845
883
  if not spec.targets:
846
884
  spec.note("whole-tree reset (no path limit)")
847
885
  apply_global_uncertainty()
@@ -947,16 +985,17 @@ def _has_create_redirect(segment: List[str]) -> bool:
947
985
 
948
986
 
949
987
  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).
988
+ creation_positions: List[int],
989
+ segment_count: int = 1) -> None:
990
+ """Whole-command-line restrictions (docs/history/friction.md F1/F2).
952
991
 
953
992
  F1: a destructive op preceded by cd resolves against the wrong working
954
993
  directory - compensation would enumerate/snapshot the wrong tree.
955
994
  Applies to every destructive kind.
956
995
  F2: a target created earlier in the same line does not exist yet at
957
996
  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.
997
+ Force-push, which is blocked anyway, is exempt. Hard reset also
998
+ needs a preflight of untracked content against its target tree.
960
999
  Shapes are DECISION-CLASS facts, not effect-uncertainty: the operation
961
1000
  itself is well understood, only its safe automatic compensation is not.
962
1001
  Policy maps them to ASK (single-execution authorization), keeping true
@@ -966,6 +1005,10 @@ def _apply_shape_rules(specs: List[OpSpec], cd_positions: List[int],
966
1005
  if spec.kind in (KIND_OTHER, KIND_UNKNOWN):
967
1006
  continue
968
1007
  idx = spec.segment_index
1008
+ if spec.kind == KIND_GIT_RESET_HARD and segment_count != 1:
1009
+ spec.undeterminable = True
1010
+ spec.note("hard reset must be a standalone command; other "
1011
+ "segments may change its target or collisions")
969
1012
  if any(pos < idx for pos in cd_positions):
970
1013
  spec.shape = "F1"
971
1014
  spec.note(
@@ -1152,14 +1195,19 @@ def _classify_posix(cmd: str) -> Tuple[List[OpSpec], Optional[str]]:
1152
1195
  elif head == "find":
1153
1196
  emit(_parse_find(seg), index)
1154
1197
  elif head == "git":
1155
- emit(_parse_git(seg), index)
1198
+ spec = _parse_git(seg)
1199
+ if spec.kind == KIND_GIT_RESET_HARD and len(seg) != len(segment):
1200
+ spec.undeterminable = True
1201
+ spec.note("hard reset wrappers may change its Git context")
1202
+ emit(spec, index)
1156
1203
  # anything else: kind OTHER, intentionally ignored by policy
1157
1204
 
1158
1205
  for spec in specs:
1159
1206
  spec.dialect = dialects.DIALECT_POSIX
1160
1207
  _append_dialect_mismatches(
1161
1208
  specs, command_segments, dialects.DIALECT_POSIX)
1162
- _apply_shape_rules(specs, cd_positions, creation_positions)
1209
+ _apply_shape_rules(specs, cd_positions, creation_positions,
1210
+ len(raw_segments))
1163
1211
  return [s for s in specs if s.kind != KIND_OTHER], None
1164
1212
 
1165
1213
 
@@ -1189,7 +1237,7 @@ def _classify_windows_dialect(cmd: str, dialect: str
1189
1237
  accepts `/`, while leaving `\\` in the fact makes Linux and Windows CI
1190
1238
  disagree about the same command.
1191
1239
 
1192
- Shape rules (docs/friction.md F1/F2) apply to Windows lines too: `cd`
1240
+ Shape rules (docs/history/friction.md F1/F2) apply to Windows lines too: `cd`
1193
1241
  and the interpreter prefix set are shared shell concepts, so F1 means
1194
1242
  the same thing in cmd and PowerShell.
1195
1243
  """
@@ -1213,7 +1261,8 @@ def _classify_windows_dialect(cmd: str, dialect: str
1213
1261
  spec.targets = [t.replace("\\", "/") for t in spec.targets]
1214
1262
  _attribute_targets(spec)
1215
1263
  _append_dialect_mismatches(specs, stream.segments, dialect)
1216
- _apply_shape_rules(specs, cd_positions, creation_positions)
1264
+ _apply_shape_rules(specs, cd_positions, creation_positions,
1265
+ len(stream.segments))
1217
1266
  return [s for s in specs if s.kind != KIND_OTHER], None
1218
1267
 
1219
1268
 
@@ -1230,7 +1279,7 @@ def classify_command(cmd: str, dialect: str = dialects.DEFAULT_DIALECT
1230
1279
  dialect layer exists to prevent.
1231
1280
 
1232
1281
  Heredoc bodies are stripped before POSIX parsing (they are written
1233
- payload, not commands - see docs/friction.md F5).
1282
+ payload, not commands - see docs/history/friction.md F5).
1234
1283
 
1235
1284
  Returns (specs, parse_error). Segments that are not destructive are
1236
1285
  returned as kind=OTHER and ignored by policy. A parse_error (unbalanced