Feat/tool script safety guard

[zzp1221]

Description

Summary

Add a configurable pre-execution safety guard for Python scripts and Bash commands used by tools, skills, and code
execution flows.

The guard can scan script-like inputs before execution, classify risk as allow, deny, or needs_human_review,
emit structured reports, and write audit events.

What Changed

• Added trpc_agent_sdk.tools.safety with:

  • Python and Bash static scanner
  • YAML policy loader
  • structured report types
  • JSONL audit logging
  • OpenTelemetry-ready safety attributes
  • Tool Filter integration
  • CodeExecutor wrapper integration

• Added CLI utility:

  • scripts/tool_safety_check.py

• Added example assets:

  • examples/tool_safety_guard/tool_safety_policy.yaml
  • 12 sample scripts covering safe, high-risk, and review-needed cases
  • sample structured report
  • sample audit log
  • README with integration guidance, limitations, and extension notes

• Added acceptance coverage for:

  • dangerous deletes
  • secret file reads
  • non-allowlisted network egress
  • allowlisted network requests
  • subprocess and shell injection patterns
  • dependency installation
  • infinite loops and resource abuse
  • sensitive information output
  • Filter and CodeExecutor pre-execution blocking
  • audit event emission
  • policy-driven behavior changes

Validation

.venv\Scripts\python.exe -m pytest tests\tools\safety\test_tool_safety_guard.py

Result:

32 passed

Notes

This guard is a pre-execution static control. It does not replace sandbox isolation because static scanning can miss
obfuscated code, generated strings, downloaded second-stage scripts, shell expansion behavior, and interpreter-
specific behavior. Production use should still rely on sandboxing, least-privilege credentials, filesystem and network
egress controls, process limits, timeouts, and post-execution auditing.

[github-actions]

CLA Assistant Lite bot All contributors have signed the CLA ✍️ ✅

[zzp1221]

I have read the CLA Document and I hereby sign the CLA

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
⚠️ Please upload report for BASE (main@099b571). Learn more about missing BASE report.

Additional details and impacted files

@@            Coverage Diff             @@
##             main        #123   +/-   ##
==========================================
  Coverage        ?   87.79247%           
==========================================
  Files           ?         474           
  Lines           ?       45005           
  Branches        ?           0           
==========================================
  Hits            ?       39511           
  Misses          ?        5494           
  Partials        ?           0           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[raychen911]

是否可以提供一个和quickstart一样的结构目录的例子？目前看实现的代码没有这个，期望可以深刻理解该issue实现的功能特性，另外，补充一下设计文档，方便理解

[zzp1221]

@raychen911 您好，已根据您的建议补齐了quickstart和设计文档。
该 quickstart 演示同一个 ToolSafetyGuard 在三种接入路径中的使用：

1. direct scan
2. Tool Filter 预执行拦截
3. SafetyGuardedCodeExecutor wrapper 预执行拦截
   感谢您的反馈

[raychen911]

建议例子按照quickstart的目录格式来写，包含agent/目录，run_agent.py这些文件，保持和其他例子的一致性，方便用户使用