Issue #98：工具执行 Hook 机制（PreToolUse / PostToolUse）

// agent/engine.go:93
ToolExecutor func(ctx context.Context, tc llm.ToolCall) (*tools.ToolResult, error)

// engine.go:391-395
start := time.Now()
result, execErr := toolExecutor(execCtx, tc)  // ← 【统一插入点】
elapsed := time.Since(start)

package tools

import (
    "context"
    "time"
)

// ToolHook 工具执行钩子接口
// 在工具调用前后提供扩展点，用于日志、审计、拦截、统计等场景。
type ToolHook interface {
    // Name 返回 hook 名称，用于日志和调试
    Name() string

    // PreToolUse 在工具执行前调用。
    // params: 工具参数（已解析的 JSON，map 形式，便于 hook 访问字段）
    // 返回 error 时跳过工具执行，将 error 作为工具执行结果返回给 LLM。
    PreToolUse(ctx context.Context, toolName string, params map[string]any) error

    // PostToolUse 在工具执行后调用（无论 PreToolUse 是否跳过）。
    // result: 工具执行结果（PreToolUse 返回 error 时为 nil）
    // elapsed: 工具执行耗时
    // err: 工具执行错误（PreToolUse 返回 error 时为该 error）
    PostToolUse(ctx context.Context, toolName string, params map[string]any, result *ToolResult, err error, elapsed time.Duration)
}

// HookChain 工具 hook 链，按注册顺序执行所有 hook。
// 并发安全：支持运行时动态注册/注销。
type HookChain struct {
    mu    sync.RWMutex
    hooks []ToolHook
}

func NewHookChain() *HookChain { ... }
func (c *HookChain) Use(hooks ...ToolHook) { ... }
func (c *HookChain) Remove(name string) int { ... }
func (c *HookChain) RunPre(ctx context.Context, toolName string, params map[string]any) error { ... }
func (c *HookChain) RunPost(ctx context.Context, toolName string, params map[string]any, result *ToolResult, err error, elapsed time.Duration) { ... }

type RunConfig struct {
    // ... 现有字段 ...
    
    // HookChain 工具执行 hook 链（nil = 无 hook）
    HookChain *tools.HookChain
}

return func(ctx context.Context, tc llm.ToolCall) (*tools.ToolResult, error) {
    // ... 现有的 1-4 步（查找、激活检查、刷新 round、mkdir） ...
    
    // 5. 解析参数（供 hook 使用）
    var params map[string]any
    json.Unmarshal([]byte(tc.Arguments), &params)
    
    // 6. 执行 PreToolUse hooks
    if cfg.HookChain != nil {
        if err := cfg.HookChain.RunPre(ctx, tc.Name, params); err != nil {
            return nil, err  // 跳过工具执行
        }
    }
    
    // 7. 执行工具
    toolCtx := buildToolContext(ctx, cfg)
    start := time.Now()
    result, execErr := tool.Execute(toolCtx, tc.Arguments)
    elapsed := time.Since(start)
    
    // 8. 执行 PostToolUse hooks
    if cfg.HookChain != nil {
        cfg.HookChain.RunPost(ctx, tc.Name, params, result, execErr, elapsed)
    }
    
    return result, execErr
}

func defaultToolExecutor(cfg *RunConfig) func(ctx context.Context, tc llm.ToolCall) (*tools.ToolResult, error) {
    return func(ctx context.Context, tc llm.ToolCall) (*tools.ToolResult, error) {
        tool, ok := cfg.Tools.Get(tc.Name)
        if !ok {
            return nil, fmt.Errorf("unknown tool: %s", tc.Name)
        }

        // 解析参数
        var params map[string]any
        json.Unmarshal([]byte(tc.Arguments), &params)

        // Pre hooks
        if cfg.HookChain != nil {
            if err := cfg.HookChain.RunPre(ctx, tc.Name, params); err != nil {
                return nil, err
            }
        }

        toolCtx := buildToolContext(ctx, cfg)
        start := time.Now()
        result, execErr := tool.Execute(toolCtx, tc.Arguments)
        elapsed := time.Since(start)

        // Post hooks
        if cfg.HookChain != nil {
            cfg.HookChain.RunPost(ctx, tc.Name, params, result, execErr, elapsed)
        }

        return result, execErr
    }
}

type LoggingHook struct{}

func (h *LoggingHook) Name() string { return "logging" }

func (h *LoggingHook) PreToolUse(ctx context.Context, toolName string, params map[string]any) error {
    log.Ctx(ctx).WithFields(log.Fields{
        "tool":   toolName,
        "params": params,
    }).Info("Tool execution started")
    return nil
}

func (h *LoggingHook) PostToolUse(ctx context.Context, toolName string, params map[string]any, result *ToolResult, err error, elapsed time.Duration) {
    fields := log.Fields{
        "tool":    toolName,
        "elapsed": elapsed.Round(time.Millisecond),
    }
    if err != nil {
        log.Ctx(ctx).WithFields(fields).WithError(err).Warn("Tool execution failed")
    } else {
        log.Ctx(ctx).WithFields(fields).Info("Tool execution completed")
    }
}

type TimingHook struct {
    mu       sync.Mutex
    stats    map[string]*toolTimingStats  // toolName → stats
}

type toolTimingStats struct {
    Count    int
    Total    time.Duration
    Min      time.Duration
    Max      time.Duration
}

func NewTimingHook() *TimingHook { ... }

func (h *TimingHook) Name() string { return "timing" }

func (h *TimingHook) PreToolUse(ctx context.Context, toolName string, params map[string]any) error {
    return nil  // 仅在 Post 中统计
}

func (h *TimingHook) PostToolUse(ctx context.Context, toolName string, params map[string]any, result *ToolResult, err error, elapsed time.Duration) {
    h.mu.Lock()
    defer h.mu.Unlock()
    // 累加统计
}

// Stats 返回各工具的耗时统计快照
func (h *TimingHook) Stats() map[string]toolTimingStats { ... }

// Reset 清零统计
func (h *TimingHook) Reset() { ... }

type Agent struct {
    // ... 现有字段 ...
    hookChain *tools.HookChain  // 工具执行 hook 链
}

// agent/agent.go New() 函数中
hookChain := tools.NewHookChain()
hookChain.Use(tools.NewLoggingHook())
hookChain.Use(tools.NewTimingHook())
agent.hookChain = hookChain

// ToolHookChain 返回 Agent 的工具 hook 链，支持运行时动态注册/注销
func (a *Agent) ToolHookChain() *tools.HookChain {
    return a.hookChain
}