// Package tools defines the Tool interface (what the engine dispatches) and
// the capability hooks (DryRunnable / Reversible / MetadataProvider /
// CapabilityProvider) that let consumers describe tool-level properties to
// the engine and to UIs/auditors.
//
// Consumer integration surfaces fall into three shapes. For the full
// taxonomy see `docs/api-reference.md` section "API 消费形态 / API
// Consumption Patterns".
//
// Synchronous callback — form 3:
//   - Tool.Execute: engine dispatches the tool with a Request and blocks
//     for *Result. Custom tools implement this — SDK consumers inject via
//     engine.Config.Tools.
//
// Pull — form 2 (metadata / capability description):
//   - MetadataProvider.Metadata() Metadata — engine reads to classify
//     tool safety (destructive / read-only)
//   - CapabilityProvider.Capability() ToolCapability — lists
//     AffectedResources / UndoMethod / MinConfidence so UIs can render
//     preview UX
//   - DryRunnable.DryRun(input) (*DryRunResult, error) — consumer-provided
//     preview of tool effects without executing
//   - Reversible.Undo(result) / UndoInfo — enables operation history / undo
//
// Package tools 定义 Tool 接口 (引擎分发工具的入口) 和能力钩子 (DryRunnable /
// Reversible / MetadataProvider / CapabilityProvider), 让消费者向引擎和
// UI / 审计面声明工具级属性.
//
// 消费者接入面分三种形态. 完整分类见 `docs/api-reference.md` "API 消费形态 /
// API Consumption Patterns" 章节.
//
// 同步回调 (callback) —— 形态三:
//   - Tool.Execute: 引擎传 Request 阻塞等 *Result. 自定义工具实现此接口,
//     SDK 消费者经 engine.Config.Tools 注入.
//
// 调取 (pull) —— 形态二 (元数据 / 能力描述):
//   - MetadataProvider.Metadata() Metadata —— 引擎据此分类工具安全性
//     (破坏性 / 只读)
//   - CapabilityProvider.Capability() ToolCapability —— 列出
//     AffectedResources / UndoMethod / MinConfidence, 供 UI 渲染预览 UX
//   - DryRunnable.DryRun(input) —— 消费者提供的工具效果预览, 不真正执行
//   - Reversible.Undo(result) / UndoInfo —— 支持操作历史 / 撤销
package tools