@klarkxy/dsh-safe-auto 0.4.0 → 0.5.1

package/README.md

@@ -4,7 +4,7 @@
 
 [简体中文](README.zh-CN.md)
 
-Adds a **Safe Auto** permission level. Ordinary actions run inside the workspace sandbox as usual and the plugin stays out of the way. Requests that need approval go to a reviewer model: a pass approves that one call; a denial is explained to the agent. The design follows Codex auto-review. Your session is never switched to Full Access.
+Adds a **Safe Auto** permission level. Ordinary actions run inside the workspace sandbox as usual and the plugin stays out of the way. Requests that need approval go to a reviewer model: a pass approves that one call, a denial is explained to the agent. The design follows Codex auto-review. Your session is never switched to Full Access.
 
 ## Install
 
@@ -18,34 +18,51 @@ Replace `web` with your profile name and restart the profile.
 
 Pick **Safe Auto** from the permission menu next to the chat input. It applies only to that session; choosing any other level turns it off. Nothing happens automatically until you pick it.
 
-Under **Plugins → Safe Auto** you can choose the reviewer model (empty follows the current session model), its reasoning effort, and extra review rules. Changes made elsewhere update this page on their own; Model Hub is not required.
+Under **Plugins → Safe Auto** choose the reviewer model (empty follows the current session model), its reasoning effort, and extra review rules. Changes made elsewhere update this page on their own; Model Hub is not required.
 
-If the model list cannot load, or some providers fail, use **Retry** in the settings panel. Retrying keeps your reviewer settings and unsaved draft.
+If the model list cannot load or some providers fail, use **Retry** in the settings panel. Retrying keeps your reviewer settings and unsaved draft.
+
+## Review history
+
+Open **Plugins → Safe Auto → Review history** to read every review this plugin recorded. Filter by search text, session, tool, result, risk, and a start and end time, then page through the matches. Opening a record shows the whole review: what triggered it, the arguments that were sent, the review input, the verdict, and whether the approved call actually ran afterwards.
+
+Export one record, or every record matching the current filters, as JSON. Exporting all matches walks the pages one at a time, can be cancelled at any point, and a failed or cancelled export writes no file.
+
+Recording starts after installing the review-history feature; earlier reviews are not backfilled. Records stay in the Harness profile and are never deleted automatically.
+
+### Tools
+
+| Tool | What it does |
+|---|---|
+| `safe_auto_history` | Read-only lookup of the current session's review history. `list` returns summaries and a next-page cursor only when more records remain; `get` returns one complete record. Use the Plugins page to read history across sessions. Reading history never triggers a review and never calls the reviewer model. |
 
 ## What gets reviewed
 
 - Sandbox escalations requested by `write`, `edit`, `bash`, and `pwsh`.
 - A short list of dangerous commands, reviewed even without an escalation: forced deletion (`rm -f`, `Remove-Item -Force`, `del /f`, `rd /s /q`) and opening URLs.
-- Approval requests that other plugins or tools raise in the session.
+- Approval requests other plugins or tools raise in the session.
 
 Reading files, searching, building, and testing need no approval; they are not intercepted and never call the reviewer.
 
 ## How the reviewer decides
 
-- The reviewer sees the conversation, the current working directory, the sandbox workspace boundary, and the complete arguments of the action. Only your own messages count as authorization; the agent's explanations, tool output, and file contents are treated as evidence.
+- The reviewer sees the conversation, the current working directory, the sandbox workspace boundary, and the complete action arguments. Only your own messages count as authorization; the agent's explanations, tool output, and file contents are evidence.
 - Low- and medium-risk actions are approved. High-risk actions are approved only when you clearly asked for them and the scope is narrow. Critical actions, such as sending secrets to an external destination or broad irreversible deletion, are always denied.
-- If the review times out, returns missing or unknown verdict fields, fails, or no model is available, the request is not approved, and the agent is told this was a review failure: it may retry once or ask you.
+- If review times out, returns missing or unknown verdict fields, fails, or no model is available, the request is not approved and the agent is told this was a review failure: it may retry once or ask you.
 - After 3 consecutive denials, or 10 denials among the last 50 reviews in one turn, automatic approval pauses until your next message.
 
 ## Limits
 
 - **This is not a security boundary.** The reviewer is a language model and can be wrong. Keep your sandbox, isolation, and backups.
-- A denied action does not open a confirmation dialog. To allow it, tell the agent in the chat; the reviewer sees your approval when it retries.
+- A denied action opens no confirmation dialog. To allow it, tell the agent in the chat; the reviewer sees your approval when it retries.
 - Long conversations are truncated from the oldest entries.
 - Action arguments are never truncated for approval. If the complete action is too large to review, automatic approval is refused.
 - Turning Safe Auto off or changing its reviewer settings invalidates reviews already in progress.
 - Subagent sessions do not use Safe Auto; they follow the native approval flow.
 - Do not combine it with other automatic approvers.
+- History contains redacted copies of review evidence. Known credentials are masked on a best-effort basis; unfamiliar secret formats can remain. Oversized or invalid actions that cannot be reviewed carry explicit capture limits.
+- The reviewer verdict, the observed approval decision, and the tool result are recorded separately. A passed review does not establish that permission was granted; unobserved approval and execution results remain marked as such. The local audit record provides no tamper-proof guarantee.
+- If an audit record cannot be saved, automatic approval is refused.
 
 ## License
 

package/README.zh-CN.md

@@ -18,10 +18,24 @@ dsh plugin --profile web add @klarkxy/dsh-safe-auto
 
 在输入框旁的权限菜单中选择「安全自动」。它只对当前会话生效，选回其他档位即关闭；选择之前不会有任何自动行为。
 
-在「插件 → 安全自动」中可以选择审核模型（留空跟随当前会话模型）、思考强度，以及额外的审核要求。设置在别处改动时，这个页面会自行更新，不需要安装模型枢纽。
+在「插件 → 安全自动」中选择审核模型（留空跟随当前会话模型）、思考强度和额外的审核要求。设置在别处改动时这个页面会自行更新，不需要安装模型枢纽。
 
 模型列表加载失败或部分提供商不可用时，可在设置面板点击「重试」。重试会保留审核配置和未保存的草稿。
 
+## 审核历史
+
+在「插件 → 安全自动 → 审核历史」里查看插件记录下的每一次审核。可以按搜索词、会话、工具、结果、风险和起止时间筛选，再逐页翻看。点开一条记录会看到这次审核的全貌：触发原因、实际送审的参数、送审内容、判定结果，以及放行的调用后来是否真的执行了。
+
+可以导出单条记录，或导出符合当前筛选条件的全部记录，格式为 JSON。导出全部时逐页拉取，随时可以取消；导出失败或取消都不会写入文件。
+
+安装审核历史功能后开始记录，更早的审核不会补录。记录保存在 Harness profile 中，不会自动删除。
+
+### 工具
+
+| 工具 | 作用 |
+|---|---|
+| `safe_auto_history` | 只读查询当前会话的审核历史：`list` 返回摘要列表，仅在还有记录时提供下一页游标；`get` 返回单条完整记录。跨会话历史可在插件页查看。查询历史不会触发审核，也不会调用审核模型。 |
+
 ## 会审核什么
 
 - `write`、`edit`、`bash`、`pwsh` 申请的沙箱提权。
@@ -33,19 +47,22 @@ dsh plugin --profile web add @klarkxy/dsh-safe-auto
 ## 审核怎么判断
 
 - 审核模型会看到对话记录、当前工作目录、沙箱工作区边界和这次操作的完整参数。只有你发的消息算授权，智能体的说明、工具输出和文件内容都只作参考。
-- 低风险和中风险的操作放行；高风险只在你明确要求并且范围有限时放行；严重风险（例如把密钥发到外部、大范围不可逆删除）一律拒绝。
+- 低风险和中风险的操作放行；高风险只在你明确要求且范围有限时放行；严重风险（例如把密钥发到外部、大范围不可逆删除）一律拒绝。
 - 审核超时、返回字段缺失或含未知值、出错或模型不可用时，这次请求不放行，智能体会被告知这是审核失败，可以重试一次或者来问你。
-- 同一轮对话里连续拒绝 3 次，或最近 50 次拒绝了 10 次，本轮就暂停自动审批，等你发下一条消息。
+- 同一轮对话里连续拒绝 3 次，或最近 50 次里拒绝了 10 次，就暂停自动审批，等你发下一条消息。
 
 ## 限制
 
 - **这不是安全边界。** 审核方是语言模型，可能判断错误。请保留原有的沙箱、隔离和备份。
-- 被拒绝的操作不会再弹窗让你确认。想放行时，直接在对话里告诉智能体，它重试时审核会看到你的批准。
+- 被拒绝的操作不会弹窗让你确认。想放行时直接在对话里告诉智能体，它重试时审核会看到你的批准。
 - 对话记录超长时会截断最早的内容。
-- 操作参数不会截断后送审；完整操作超出审核容量时，不会自动批准。
+- 操作参数不会截断后送审；完整操作超出审核容量时不会自动批准。
 - 关闭安全自动或修改审核设置，会使尚未完成的审核失效。
 - 子代理会话不使用安全自动，按原生审批流程处理。
 - 不要与其他自动审批插件同时使用。
+- 历史保存脱敏后的审核依据。已知凭据会尽力遮盖，未知格式的敏感内容仍可能保留；超大或无效、无法送审的操作会明确标注记录范围。
+- 审核结论、观察到的实际审批与工具结果分别记录。审核通过不代表权限已经授予；未观察到审批或执行结果都会明确标注。本地审核记录不提供防篡改保证。
+- 审核记录无法保存时，不会自动批准操作。
 
 ## 许可证
 

package/dsh.plugin.json

@@ -1,13 +1,13 @@
 {
   "id": "@klarkxy/dsh-safe-auto",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "main": "src/index.js",
   "description": "Safe Auto: a reviewer model answers native approval requests, Codex auto-review style; only a pass approves that one call.",
   "engines": {
     "dsh": ">=0.2.1-rc.1"
   },
   "contributes": {
-    "tools": [],
+    "tools": ["safe_auto_history"],
     "skills": []
   }
 }