docs: add tool safety guard example and guides

Author: moriihyq

docs/mkdocs.yml

@@ -33,6 +33,7 @@ nav:
       - Skill: skill.md
       - Evolution: evolution.md
       - Tool: tool.md
+      - Tool Safety Guard: tool-safety-guard.md
       - Session:
           - Overview: session/index.md
           - Session Summary: session/summary.md
@@ -140,6 +141,7 @@ plugins:
                 - Skill: skill.md
                 - Evolution: evolution.md
                 - Tool: tool.md
+                - Tool 安全防护: tool-safety-guard.md
                 - Session:
                     - Overview: session/index.md
                     - Session Summary: session/summary.md

docs/mkdocs/en/tool-safety-guard.md

@@ -0,0 +1,68 @@
+# Tool Safety Guard
+
+`tool/safety` is an opt-in, fail-closed guard for model-initiated tool calls. It scans the final arguments after before-tool callbacks, blocks or requests approval before execution, emits metadata-only audit records, and recursively redacts the final result after all callbacks and hooks.
+
+Existing applications keep their historical behavior until a guard is configured. Decisions always compose as `deny > ask > allow`.
+
+## What it covers
+
+The built-in rules cover destructive commands, sensitive paths and credential reads, non-allowlisted network access, shell bypasses, host or interactive execution, dependency changes, excessive resources, and secret exposure. Policies support strict YAML or JSON parsing, exact domains and explicit `*.example.com` wildcards, per-tool command and environment allowlists, timeouts, and hard combined stdout/stderr limits.
+
+## Configure the framework
+
+```go
+policyData, err := os.ReadFile("tool_safety_policy.yaml")
+if err != nil { return err }
+policy, err := safety.ParsePolicy(policyData, safety.PolicyFormatAuto)
+if err != nil { return err }
+sink, err := safety.NewJSONLSink("tool_safety_audit.jsonl")
+if err != nil { return err }
+defer sink.Close()
+guard, err := safety.NewGuard(policy, safety.WithAuditSink(sink))
+if err != nil { return err }
+
+runOptions := agent.NewRunOptions(
+    agent.WithToolPermissionPolicy(guard),
+)
+```
+
+Framework-wide configuration protects every tool and is recommended. The built-in `workspaceexec`, `hostexec`, and `codeexec` tools also accept `WithSafetyGuard(guard)` for direct calls. Their local guard is discoverable by framework observability, so raw arguments are suppressed before the tool executes. Runtime timeout/output profiles compose by the most restrictive value; `codeexec` passes limits through `codeexecutor.ExecutionLimits`, the local executor enforces them while running, and the wrapper caps returned output and file content.
+
+## Example policy
+
+```yaml
+version: 1
+default_action: allow
+profiles:
+  workspace_exec:
+    allowed_commands: [go, git]
+    allowed_domains: [api.github.com, "*.trusted.example"]
+    allowed_env: [CI]
+    max_timeout: 2m
+    max_output_bytes: 1048576
+```
+
+Policy parsing rejects unknown fields, duplicate keys, trailing documents, invalid actions, and ambiguous numeric duration units. Reloading is atomic: an invalid replacement never weakens the active policy.
+
+## Reports, audit, and telemetry
+
+Every `Report` has stable `decision`, `risk_level`, `rule`, `rule_ids`, `evidence`, `recommendation`, `tool_name`, `command`, `backend`, and `blocked` fields. JSONL audit events contain metadata and a request SHA-256 digest, never raw arguments or results. OpenTelemetry spans expose the decision, blocked flag, risk, sorted bounded rule IDs, backend, digest, and scan duration.
+
+An audit or final-redaction failure blocks execution or suppresses the result. Output and error sanitizers run after ordinary callbacks, tool-result-message hooks, post-result hooks, and streaming final-state handling.
+
+## Verify without executing dangerous samples
+
+The example is scan-only:
+
+```bash
+go test -v ./tool_safety_guard -run TestAcceptanceMetrics
+go run ./tool_safety_guard \
+  -policy tool_safety_guard/tool_safety_policy.yaml \
+  -output-dir tool_safety_guard/output
+```
+
+The public acceptance corpus asserts high-risk detection of at least 90%, safe false positives of at most 10%, and 100% denial for credential reads, protected destructive deletion, and non-allowlisted network access.
+
+## Security boundary
+
+Scanning is defense in depth, not a sandbox. Use least-privilege credentials, filesystem and network isolation, non-root containers or VMs, operating-system resource controls, and human approval for `ask`. Capability-aware workspace backends are rejected when a configured profile depends on guarantees they cannot provide. Third-party CodeExecutors must honor the supplied context limits while running; the wrapper can cap their returned result but cannot force a backend that ignores cancellation to stop.

docs/mkdocs/zh/tool-safety-guard.md

@@ -0,0 +1,68 @@
+# Tool 安全防护
+
+`tool/safety` 是一个按需启用、失败时关闭执行通道（fail closed）的工具安全组件。它会在 before-tool 回调完成后扫描最终参数，在执行前拒绝或请求人工批准，并在所有普通回调和 Hook 完成后递归脱敏最终结果；审计只记录元数据。
+
+未配置 Guard 的应用保持原有行为。多层策略固定按 `deny > ask > allow` 合并。
+
+## 覆盖范围
+
+内置规则覆盖危险删除、敏感路径与凭据读取、非白名单网络、Shell 绕过、宿主机或交互执行、依赖变更、资源滥用和密钥泄露。严格 YAML/JSON 策略支持精确域名、显式 `*.example.com` 通配符、工具级命令与环境变量白名单、超时及 stdout/stderr 共用的硬输出上限。
+
+## 在框架中配置
+
+```go
+policyData, err := os.ReadFile("tool_safety_policy.yaml")
+if err != nil { return err }
+policy, err := safety.ParsePolicy(policyData, safety.PolicyFormatAuto)
+if err != nil { return err }
+sink, err := safety.NewJSONLSink("tool_safety_audit.jsonl")
+if err != nil { return err }
+defer sink.Close()
+guard, err := safety.NewGuard(policy, safety.WithAuditSink(sink))
+if err != nil { return err }
+
+runOptions := agent.NewRunOptions(
+    agent.WithToolPermissionPolicy(guard),
+)
+```
+
+推荐使用框架级配置来保护所有工具。内置的 `workspaceexec`、`hostexec` 和 `codeexec` 也支持 `WithSafetyGuard(guard)`，可用于直接调用；框架能够发现这个工具本地 Guard，并在工具执行前抑制原始参数日志和遥测。运行时超时/输出 profile 按最严格值合并；`codeexec` 通过 `codeexecutor.ExecutionLimits` 下传限制，本地执行器在运行中执行，wrapper 再限制最终输出与文件内容。
+
+## 策略示例
+
+```yaml
+version: 1
+default_action: allow
+profiles:
+  workspace_exec:
+    allowed_commands: [go, git]
+    allowed_domains: [api.github.com, "*.trusted.example"]
+    allowed_env: [CI]
+    max_timeout: 2m
+    max_output_bytes: 1048576
+```
+
+解析器会拒绝未知字段、重复键、尾随文档、非法动作和没有明确单位的时长。重载是原子的：新策略无效时，旧策略继续生效。
+
+## 报告、审计与遥测
+
+每份 `Report` 稳定包含 `decision`、`risk_level`、`rule`、`rule_ids`、`evidence`、`recommendation`、`tool_name`、`command`、`backend` 和 `blocked`。JSONL 审计只记录元数据与请求 SHA-256 摘要，不保存原始参数或结果。OpenTelemetry Span 记录决策、是否阻断、风险、排序且有界的完整规则 ID、后端、摘要和扫描耗时。
+
+审计或最终脱敏失败时会阻止执行或压制结果。输出与错误脱敏屏障位于普通回调、工具结果消息 Hook、Post-result Hook 以及流式最终状态处理之后。
+
+## 安全验证（不执行危险样本）
+
+示例只做扫描：
+
+```bash
+go test -v ./tool_safety_guard -run TestAcceptanceMetrics
+go run ./tool_safety_guard \
+  -policy tool_safety_guard/tool_safety_policy.yaml \
+  -output-dir tool_safety_guard/output
+```
+
+公开验收语料直接断言：高危检出率不低于 90%，安全样本误报率不高于 10%，凭据读取、受保护路径危险删除、非白名单网络三类拒绝率均为 100%。
+
+## 安全边界
+
+扫描属于纵深防御，不能替代沙箱。生产环境仍应使用最小权限凭据、文件系统与网络隔离、非 root 容器或虚拟机、操作系统资源限制，并对 `ask` 决策进行人工审批。具备能力声明的 workspace 后端无法满足策略依赖时会失败关闭；第三方 CodeExecutor 必须在运行中遵守 context 限制，wrapper 能限制最终结果，但无法强制忽略取消信号的后端停止。

docs/tool-safety-guard.md

@@ -0,0 +1,144 @@
+# Tool Safety Guard
+
+Package `tool/safety` provides an opt-in, fail-closed guard for model-initiated tool calls. It scans the final execution input before a tool runs, returns a structured permission decision, emits metadata-only audit events, and recursively removes secrets from the final result after callbacks.
+
+Existing applications are unchanged until they configure a guard.
+
+## Security contract
+
+The guard addresses seven execution risks: destructive commands, sensitive paths, network access, shell bypasses, host/interactive execution, dependency changes, and resource abuse. Secret exposure is an always-on input/output protection and cannot be disabled by policy.
+
+The key ordering is:
+
+1. before-tool callbacks finish modifying arguments;
+2. the permission guard scans the effective arguments;
+3. only `allow` reaches the executor;
+4. plugins and after-tool callbacks finish modifying the result;
+5. the final sanitizer recursively redacts the effective result;
+6. only the sanitized result reaches events, model messages, and tool-result telemetry.
+
+`deny` outranks `ask`, which outranks `allow`. Invalid policy or audit state never silently weakens the configured contract. A failed audit write or final sanitization returns an error and suppresses the unsafe result.
+
+## Create a guard
+
+```go
+policyData, err := os.ReadFile("policy.yaml")
+if err != nil {
+    return err
+}
+policy, err := safety.ParsePolicy(policyData, safety.PolicyFormatAuto)
+if err != nil {
+    return err
+}
+sink, err := safety.NewJSONLSink("tool-audit.jsonl")
+if err != nil {
+    return err
+}
+defer sink.Close()
+guard, err := safety.NewGuard(policy, safety.WithAuditSink(sink))
+if err != nil {
+    return err
+}
+```
+
+`NewDefaultGuard` enables all built-in detections with a default `allow` action. `Reload` parses and atomically installs a complete policy; a rejected reload leaves the previous snapshot active.
+
+## Framework-wide integration
+
+Pass the guard as the per-run permission policy:
+
+```go
+runOptions := agent.NewRunOptions(
+    agent.WithToolPermissionPolicy(guard),
+)
+```
+
+This route covers standard function-call processing and Graph execution, including wrapped tools and callback-provided custom results. The guard also acts as a final-result sanitizer.
+
+## Direct built-in tool integration
+
+Applications that call a built-in tool directly can opt in at construction:
+
+```go
+workspaceTool := workspaceexec.NewExecTool(exec,
+    workspaceexec.WithSafetyGuard(guard),
+)
+
+hostTools := hostexec.NewToolSet(
+    hostexec.WithSafetyGuard(guard),
+)
+
+codeTool := codeexec.NewTool(exec,
+    codeexec.WithSafetyGuard(guard),
+)
+```
+
+Use either framework-wide integration or the direct option for a call path. Configuring the same guard in both places is safe but produces two scans and two audit events.
+
+For `codeexec`, scanning occurs after flexible input decoding and language validation, over the code that the executor will actually receive. The wrapper applies the most restrictive direct/invocation timeout and output profile, passes in-flight limits through `codeexecutor.ExecutionLimits`, and caps the combined returned output/file content; the local executor enforces the output budget while the child is running. For interactive write tools, an empty poll remains allowed while non-empty input or newline submission requires approval by default.
+
+## Policy
+
+Policies are versioned and strictly decoded. Unknown fields, duplicate keys, multiple YAML documents, trailing JSON values, invalid actions, invalid domains, and negative limits are rejected.
+
+```yaml
+version: 1
+default_action: allow
+profiles:
+  workspace_exec:
+    allowed_commands: [go, git]
+    denied_commands: [curl]
+    allowed_domains: [api.github.com, "*.corp.example"]
+    forbidden_paths: [/etc, ~/.ssh]
+    allowed_env: [CI]
+    max_timeout: 2m
+    max_output_bytes: 1048576
+    allow_host: false
+    allow_background: false
+    allow_pty: false
+```
+
+Domain matching is exact. `*.corp.example` matches `build.corp.example`, but not `corp.example` or `evilcorp.example`. Proxying, destination remapping, external curl/SSH configuration, and SSH forwarding require stronger handling because they can change the effective destination.
+
+Profile timeout and output values are ceilings, not requested defaults. Runtimes that advertise hard-limit support receive and enforce these ceilings; a configured hard limit must not be represented as enforced on an opaque backend that cannot guarantee it.
+
+## Reports, audit, and telemetry
+
+`Report` contains a decision, redacted findings, request digest, duration, risk level, recommendation, backend, and blocked/redacted flags. It never needs the raw request to correlate repeated activity.
+
+`JSONLSink` serializes concurrent writes, creates or tightens files to owner-only mode on POSIX systems, rejects directories and symbolic links, and makes `Close` idempotent. Each line is an independent `AuditEvent` containing metadata and hashes rather than arguments or results.
+
+The guard attaches bounded, low-cardinality OpenTelemetry attributes for the decision, blocked state, risk level, rule IDs, request ID, and scan duration. Applications can also drop the framework's raw tool argument/result span attributes with the telemetry span-attribute policy.
+
+## Redaction
+
+Final-result redaction recursively handles strings, byte slices, maps, slices, arrays, and JSON-serializable structs. Sensitive keys such as `api_key`, `password`, `private_key`, and `session_token` are redacted even when their values are short. Common access tokens, bearer credentials, cloud keys, assignments, and multi-line private keys are detected by value.
+
+Do not treat redaction as authorization. Inputs containing secret material are denied; output redaction is the last containment layer for tools that unexpectedly return a secret.
+
+## Verification
+
+From the repository root:
+
+```bash
+go test ./tool/safety ./tool/codeexec ./tool/hostexec ./tool/workspaceexec
+go test ./internal/flow/processor ./graph ./telemetry/trace
+go test -race ./tool/safety
+go test -run '^$' -bench BenchmarkGuardScan500 ./tool/safety
+```
+
+Run the public, scan-only acceptance set from `examples`:
+
+```bash
+go test ./tool_safety_guard
+go run ./tool_safety_guard -policy ./tool_safety_guard/tool_safety_policy.yaml -output-dir ./tool_safety_guard/output
+```
+
+Platform-specific executor tests should run on their native operating systems. A Linux container or CI runner is recommended for the repository's Unix-oriented integration tests.
+
+## Limitations
+
+- Static scanning is a policy boundary, not a full shell interpreter or sandbox. Use isolated runtimes and least privilege as independent layers.
+- `ask` means “do not execute yet.” The host application owns the user-approval interaction and may retry only after approval.
+- Third-party code executors receive a deadline and `codeexecutor.ExecutionLimits` and must honor them while running. The wrapper still caps their returned result, but cannot retroactively make an executor that ignores context cancellation stop work.
+- Audit files protect integrity and local confidentiality through restrictive access, but applications remain responsible for retention, rotation, and centralized transport.