feat: strengthen tool safety guard validation

Author: xyxhhhhh

examples/tool_safety/README.md

@@ -61,10 +61,12 @@ tRPC-Agent 的 Tool、MCP Tool、Skill 和 CodeExecutor 能让 Agent 执行脚
 | --- | --- | --- |
 | 安全检查器代码 | 已完成 | `trpc_agent_sdk/tools/safety/` |
 | CLI 工具 | 已完成 | `scripts/tool_safety_check.py` |
+| Manifest 验收工具 | 已完成 | `scripts/tool_safety_manifest_report.py` |
 | 策略示例 | 已完成 | `examples/tool_safety/tool_safety_policy.yaml` |
-| 31 条公开样例 | 已完成 | `examples/tool_safety/samples/` |
+| 40 条公开样例 | 已完成 | `examples/tool_safety/samples/` |
+| 样例 manifest | 已完成 | `examples/tool_safety/samples/manifest.yaml` |
 | 报告示例 | 已完成 | `examples/tool_safety/tool_safety_report.json` |
-| 31 条样例汇总报告 | 已完成 | `examples/tool_safety/all_reports.json` |
+| 40 条样例汇总报告 | 已完成 | `examples/tool_safety/all_reports.json` |
 | 审计日志示例 | 已完成 | `examples/tool_safety/tool_safety_audit.jsonl` |
 | 自动化测试 | 已完成 | `tests/tools/safety/` |
 | 设计说明 | 已完成 | 本文档 |
@@ -109,6 +111,7 @@ Tool / Skill / MCP Tool / CodeExecutor
 | `_wrapper.py` | 独立 wrapper，执行前扫描、审计、埋点和拦截 |
 | `_filter.py` | tRPC-Agent Filter 接入示例 |
 | `scripts/tool_safety_check.py` | 命令行扫描工具 |
+| `scripts/tool_safety_manifest_report.py` | Manifest 驱动验收和 deterministic 报告生成工具 |
 
 ## 规则体系
 
@@ -118,14 +121,16 @@ Tool / Skill / MCP Tool / CodeExecutor
 | --- | --- |
 | `allow` | 当前静态策略未命中风险，允许执行 |
 | `deny` | 命中高危或严重风险，执行前拒绝 |
-| `needs_human_review` | 命中不确定或中等风险，需要人工复核 |
+| `needs_human_review` | 命中不确定或中等风险，需要人工复核，默认记录但不阻断 |
 
 最终决策由命中的 finding 聚合得到：
 
 - 任意 finding 为 `deny`，最终结果为 `deny`。
 - 没有 `deny`，但存在 `needs_human_review`，最终结果为 `needs_human_review`。
 - 没有 finding 时，最终结果为 `allow`。
 
+扫描决策和执行拦截分开处理：`deny` 默认会在执行前拦截；`needs_human_review` 默认只写入报告、审计和 telemetry，不阻断执行；设置 `block_on_review=True` 后，`needs_human_review` 也会阻断。
+
 ### 风险等级
 
 | 风险等级 | 典型含义 |
@@ -326,7 +331,7 @@ if report.blocked:
 
 ### Wrapper 接入
 
-`ToolSafetyGuard` 适合不直接修改核心执行链路时使用。它会在真实执行函数之前扫描脚本，写审计日志，设置 OpenTelemetry attributes，并在非 `allow` 时阻止执行。
+`ToolSafetyGuard` 适合不直接修改核心执行链路时使用。它会在真实执行函数之前扫描脚本，写审计日志，设置 OpenTelemetry attributes，并按 `deny` 或 `block_on_review=True` 策略阻止执行。
 
 ```python
 from trpc_agent_sdk.tools.safety import ToolSafetyGuard
@@ -358,6 +363,15 @@ if result.blocked:
     # Return or log the structured report instead of executing the tool.
 ```
 
+如果希望人工复核决策也阻断执行：
+
+```python
+guard = ToolSafetyGuard(
+    audit_log_path="tool_safety_audit.jsonl",
+    block_on_review=True,
+)
+```
+
 如果希望直接抛错，可使用：
 
 ```python
@@ -476,8 +490,10 @@ if not result.is_continue:
 
 当前测试覆盖：
 
-- 31 条公开样例，其中包含 issue 指定的 12 类必测场景和额外边界场景。
+- 40 条公开样例，其中包含 issue 指定的 12 类必测场景和额外边界场景。
+- Manifest 驱动验收，校验 expected decision 和 required rule ids。
 - YAML policy 加载和匹配。
+- Strict policy validation，拒绝未知字段、错误类型和负数限制。
 - 结构化报告字段。
 - 500 行脚本扫描性能。
 - 命令行参数、工作目录、超时和输出大小检查。
@@ -486,15 +502,30 @@ if not result.is_continue:
 - Filter 执行前拦截和审计日志。
 - CLI 输出和返回码。
 
-### 扫描 31 个公开样例
+### 扫描 40 个公开样例
 
-仓库中已提供一份汇总报告：
+仓库中已提供一份 deterministic 汇总报告：
 
 ```text
 examples/tool_safety/all_reports.json
 ```
 
-也可以重新扫描生成：
+推荐使用 manifest 验收脚本重新生成：
+
+```bash
+.venv/bin/python scripts/tool_safety_manifest_report.py \
+  --strict-policy \
+  --output examples/tool_safety/all_reports.json
+```
+
+该命令会校验：
+
+- 40/40 expected decision 匹配。
+- 40/40 required rule ids 匹配。
+- 读取密钥、危险删除、非白名单网络外连三类样例均不会被 allow。
+- 安全样例不会被 deny。
+
+也可以使用通用 CLI 扫描目录：
 
 ```bash
 .venv/bin/python scripts/tool_safety_check.py \
@@ -503,41 +534,19 @@ examples/tool_safety/all_reports.json
   --output examples/tool_safety/all_reports.json
 ```
 
-样例覆盖：
+样例期望决策和 required rule ids 由 `examples/tool_safety/samples/manifest.yaml` 维护。
 
-| 样例 | 期望决策 |
-| --- | --- |
-| `aiohttp_non_whitelist.py` | `deny` |
-| `apt_install.sh` | `deny` |
-| `background_process.sh` | `needs_human_review` |
-| `bash_pipe.sh` | `deny` |
-| `command_substitution.sh` | `needs_human_review` |
-| `credential_file_key.py` | `deny` |
-| `danger_delete.sh` | `deny` |
-| `dependency_install.sh` | `deny` |
-| `fork_bomb.sh` | `deny` |
-| `human_review.py` | `needs_human_review` |
-| `infinite_loop.py` | `needs_human_review` |
-| `long_sleep.sh` | `needs_human_review` |
-| `network_non_whitelist.py` | `deny` |
-| `network_whitelist.py` | `allow` |
-| `npm_install.sh` | `deny` |
-| `os_system.py` | `needs_human_review` |
-| `pip_module_install.py` | `deny` |
-| `private_key_literal.py` | `deny` |
-| `privilege_escalation.sh` | `deny` |
-| `read_env.py` | `deny` |
-| `read_secret.py` | `deny` |
-| `safe_bash.sh` | `allow` |
-| `safe_file_read.py` | `allow` |
-| `safe_python.py` | `allow` |
-| `sensitive_output.py` | `deny` |
-| `shell_injection.py` | `needs_human_review` |
-| `socket_access.py` | `needs_human_review` |
-| `subprocess_call.py` | `needs_human_review` |
-| `subprocess_danger_delete.py` | `deny` |
-| `system_overwrite.sh` | `deny` |
-| `unknown_network_dynamic.py` | `needs_human_review` |
+新增高价值绕过样例包括：
+
+- `base64 | sh`
+- `python -c`
+- `bash -c` / `sh -c`
+- 动态 URL
+- 动态 `.env` / `~/.ssh` 路径
+- `curl --data-binary @.env`
+- `find -delete`
+- `xargs rm -rf`
+- `os.getenv("API_TOKEN")` 外传
 
 ### 性能验证
 
@@ -658,7 +667,8 @@ trpc_agent_sdk/tools/safety/
 └── _wrapper.py
 
 scripts/
-└── tool_safety_check.py
+├── tool_safety_check.py
+└── tool_safety_manifest_report.py
 
 examples/tool_safety/
 ├── README.md
@@ -670,22 +680,31 @@ examples/tool_safety/
     ├── aiohttp_non_whitelist.py
     ├── apt_install.sh
     ├── background_process.sh
+    ├── base64_exec_review.sh
+    ├── bash_inline_command.sh
     ├── bash_pipe.sh
     ├── command_substitution.sh
     ├── credential_file_key.py
+    ├── curl_env_upload.sh
     ├── danger_delete.sh
     ├── dependency_install.sh
+    ├── dynamic_secret_path.py
+    ├── dynamic_url_join.py
+    ├── find_delete_review.sh
     ├── fork_bomb.sh
     ├── human_review.py
     ├── infinite_loop.py
     ├── long_sleep.sh
+    ├── manifest.yaml
     ├── network_non_whitelist.py
     ├── network_whitelist.py
     ├── npm_install.sh
+    ├── os_getenv_token_exfiltration.py
     ├── os_system.py
     ├── pip_module_install.py
     ├── private_key_literal.py
     ├── privilege_escalation.sh
+    ├── python_inline_command.sh
     ├── read_env.py
     ├── read_secret.py
     ├── safe_bash.sh
@@ -697,7 +716,8 @@ examples/tool_safety/
     ├── subprocess_call.py
     ├── subprocess_danger_delete.py
     ├── system_overwrite.sh
-    └── unknown_network_dynamic.py
+    ├── unknown_network_dynamic.py
+    └── xargs_rm_review.sh
 
 tests/tools/safety/
 ├── test_audit.py