package com.gzzm.lobster.tool;

import java.util.Map;

/**
 * ToolExecutor —— 工具执行器接口 / Interface to execute a single tool.
 *
 * <p>只有 {@link #execute} 必须实现；{@link #redactAuditDetail} 提供默认 null 实现，
 * 工具可覆盖以对审计表做脱敏（如代码沙箱不落 code 原文）.
 */
public interface ToolExecutor {

    /**
     * 执行工具 / Execute the tool.
     *
     * @param ctx    上下文 / invocation context
     * @param args   参数解析后的 map / parsed arguments
     */
    ToolResult execute(ToolContext ctx, Map<String, Object> args) throws Exception;

    /**
     * 审计脱敏钩子 / Audit redaction hook.
     *
     * <p>返 {@code null} 表示用默认 args 入审计；返非 {@code null} 则以该 map 替换 args
     * 作为审计 detail 的 payload. 典型用途：{@code code_exec} 只落 {@code code_sha256} /
     * {@code code_length}，不落 code 原文.
     */
    default Map<String, Object> redactAuditDetail(Map<String, Object> args, ToolResult result) {
        return null;
    }
}