第8章 工具系统：ToolCallExecutor 与 Hook 链

// ToolCallExecutor 关键结构（简化）
public final class ToolCallExecutor {
    private volatile IHookService hookService;
    private volatile RuntimeApprovalGate approvalGate;

    // PRE_HOOK：返回 true 表示被拦截
    private boolean blockedByPreHook(String toolName, ...) {
        return hookService.runHooks(HookDialect.CLAUDE_CODE, HookPoint.PRE_TOOL_USE, toolName, ...)
            .map(d -> d == HookDecision.BLOCK || d == HookDecision.DENY)  // 阻止类决策优先
            ...
    }

    public boolean execute(...) {
        // PRE_TOOL_USE → 执行 → POST_TOOL_USE → 事件回填 SessionLog
    }
}

// domain/agent/adapter/port/IRuntimeApprovalBroker.java
public interface IRuntimeApprovalBroker {
    ApprovalVerdict requestApproval(ApprovalRequest request);   // 阻塞
    boolean resolve(String approvalId, ApprovalVerdict verdict); // 提交裁决
    List listPending();                    // 前端轮询
    int pendingCount();
    record PendingApprovalView(String approvalId, String sessionId,
                               String toolName, String displayCommand,
                               Map arguments, String createdAt) {}
}

// 简化：runtime broker 内部
private final ConcurrentMap> waits = new ConcurrentHashMap<>();

public ApprovalVerdict requestApproval(ApprovalRequest req) {
    CompletableFuture future = new CompletableFuture<>();
    waits.put(req.approvalId(), future);
    try {
        return future.get();  // 阻塞，直到 resolve() 触发 complete()
    } finally {
        waits.remove(req.approvalId());
    }
}

public boolean resolve(String approvalId, ApprovalVerdict v) {
    var f = waits.remove(approvalId);
    if (f == null) return false;
    f.complete(v);   // 唤醒阻塞的请求
    return true;
}

// domain/tool/service/MatrixRuntimeApprovalGate.java
public class MatrixRuntimeApprovalGate implements RuntimeApprovalGate {
    private final IPermissionMatrixPort matrix;
    private final String sessionId;
    private final BiFunction, ApprovalVerdict> askHandler;

    @Override
    public Decision check(String toolName, Object args) {
        PermissionMatrixVO m = matrix.load();
        if (!m.approvalRequiredTools().contains(toolName)) {
            return Decision.ALLOW;          // 不在审批清单 → 直接放行
        }
        ApprovalRequest req = new ApprovalRequest(UUID.randomUUID().toString(),
                                                  sessionId, toolName, args);
        ApprovalVerdict v = askHandler.apply(req, /* 临时引用 */);
        return v.approved() ? Decision.ALLOW : Decision.DENY;
    }
}

// AgentFactory.wireAgent()（简化）
ToolCallExecutor executor = new ToolCallExecutor(toolView, session, 10,
                                                new JacksonToolArgumentsParser(objectMapper));
if (hookService != null) executor.setHookService(hookService);

// 运行期审批：矩阵 + broker 都在才接 gate
if (permissionMatrixPort != null && approvalBroker != null) {
    MatrixRuntimeApprovalGate gate = new MatrixRuntimeApprovalGate(
            permissionMatrixPort,
            session.sessionId(),
            (req, g) -> approvalBroker.requestApproval(req)   // 注入 ask handler
    );
    executor.setApprovalGate(gate);
}

// infrastructure 侧的真实超时挂载点（简化）
// JsonRpcPluginToolBridge.java:159 — Node 插件 sidecar
return future.orTimeout(DEFAULT_TIMEOUT_MS, TimeUnit.MILLISECONDS);

// StdioMcpClient.java:178 — MCP stdio JSON-RPC
return future.orTimeout(callTimeoutMs, TimeUnit.MILLISECONDS);

// domain/guard/service/GuardService.java（全文截取）
public class GuardService implements IGuardService {
    private final RepeatToolReminderEngine reminderEngine;

    @Override
    public GuardDecision postExecute(Optional<String> agentId, String toolName,
                                     String arguments, String resultJson) {
        if (agentId.isEmpty()) return GuardDecision.allow();
        Optional<String> reminder = reminderEngine.observe(agentId.get(), toolName, arguments);
        return reminder.map(GuardDecision::allowWithReminder).orElse(GuardDecision.allow());
    }

    @Override
    public void preStep(String agentId, boolean hasUserMessage) {
        if (hasUserMessage) reminderEngine.reset(agentId);   // 新用户消息 → 重置重复计数
    }
}