Add files via upload

internal/multiagent/runner_tool_call_id_test.go

@@ -0,0 +1,37 @@
+package multiagent
+
+import (
+	"testing"
+
+	"github.com/cloudwego/eino/schema"
+)
+
+func TestEmitToolCallsUsesUniqueFallbackIDsAcrossBatches(t *testing.T) {
+	index := 0
+	msg := &schema.Message{ToolCalls: []schema.ToolCall{{
+		Index: &index,
+		Function: schema.FunctionCall{
+			Name:      "http-framework-test",
+			Arguments: `{}`,
+		},
+	}}}
+	var ids []string
+	progress := func(eventType, _ string, raw interface{}) {
+		if eventType != "tool_call" {
+			return
+		}
+		data, _ := raw.(map[string]interface{})
+		if id, _ := data["toolCallId"].(string); id != "" {
+			ids = append(ids, id)
+		}
+	}
+	for i := 0; i < 2; i++ {
+		emitToolCallsFromMessage(msg, "agent", "agent", "conversation", "deep", progress, nil, make(map[string]int), nil)
+	}
+	if len(ids) != 2 {
+		t.Fatalf("fallback IDs = %v, want two IDs", ids)
+	}
+	if ids[0] == ids[1] {
+		t.Fatalf("fallback ID was reused across batches: %q", ids[0])
+	}
+}

internal/multiagent/shell_tool_guidance.go

@@ -0,0 +1,33 @@
+package multiagent
+
+import (
+	"strings"
+
+	"cyberstrike-ai/internal/projectprompt"
+)
+
+func shellToolsPresent(toolNames []string) bool {
+	for _, n := range toolNames {
+		switch strings.ToLower(strings.TrimSpace(n)) {
+		case "exec", "execute":
+			return true
+		}
+	}
+	return false
+}
+
+// injectShellToolGuidance 在系统提示末尾追加 exec/execute 分工（仅当工具列表含 exec 或 execute）。
+func injectShellToolGuidance(instruction string, toolNames []string) string {
+	if !shellToolsPresent(toolNames) {
+		return instruction
+	}
+	block := strings.TrimSpace(projectprompt.ShellExecExecuteGuidanceSection())
+	if block == "" {
+		return instruction
+	}
+	s := strings.TrimSpace(instruction)
+	if s == "" {
+		return block
+	}
+	return s + "\n\n" + block
+}

internal/multiagent/shell_tool_guidance_test.go

@@ -0,0 +1,17 @@
+package multiagent
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestInjectShellToolGuidance(t *testing.T) {
+	got := injectShellToolGuidance("base", []string{"nmap"})
+	if got != "base" {
+		t.Fatalf("expected unchanged, got %q", got)
+	}
+	got = injectShellToolGuidance("base", []string{"exec", "nmap"})
+	if !strings.Contains(got, "exec/execute") || !strings.Contains(got, "base") {
+		t.Fatalf("expected shell guidance appended, got %q", got)
+	}
+}

internal/multiagent/sub_agent_context.go

@@ -0,0 +1,208 @@
+package multiagent
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"strings"
+
+	"cyberstrike-ai/internal/agent"
+
+	"github.com/cloudwego/eino/adk"
+	"github.com/cloudwego/eino/components/tool"
+	"github.com/cloudwego/eino/schema"
+)
+
+const userContextSupplementHeader = "\n\n## 用户历史输入（原文，子代理必读）\n"
+
+// taskContextEnrichMiddleware intercepts "task" tool calls on the orchestrator
+// and appends the user's original conversation messages to the task description.
+// This ensures sub-agents always receive the full user intent (target URLs,
+// scope, etc.) even when the orchestrator forgets to include them.
+//
+// Design: user context is injected into the task description (per-task), NOT
+// into the sub-agent's Instruction (system prompt). This keeps sub-agent
+// Instructions clean as pure role definitions while attaching context to the
+// specific delegation — aligned with Claude Code's agent design philosophy.
+type taskContextEnrichMiddleware struct {
+	adk.BaseChatModelAgentMiddleware
+	supplement string // pre-built user context block
+}
+
+// newTaskContextEnrichMiddleware returns a middleware that enriches task
+// descriptions with user conversation context. Returns nil if disabled
+// (maxRunes < 0) or no user messages exist.
+// projectBlackboard 仅传项目黑板索引块（BuildFactIndexBlock）；勿传完整 systemPromptExtra。
+func newTaskContextEnrichMiddleware(userMessage string, history []agent.ChatMessage, maxRunes int, projectBlackboard string) adk.ChatModelAgentMiddleware {
+	supplement := buildUserContextSupplement(userMessage, history, maxRunes)
+	if bb := strings.TrimSpace(projectBlackboard); bb != "" {
+		if supplement != "" {
+			supplement += "\n\n" + bb
+		} else {
+			supplement = "\n\n" + bb
+		}
+	}
+	if supplement == "" {
+		return nil
+	}
+	return &taskContextEnrichMiddleware{supplement: supplement}
+}
+
+type agenticTaskContextEnrichMiddleware struct {
+	*adk.TypedBaseChatModelAgentMiddleware[*schema.AgenticMessage]
+	supplement string
+}
+
+func newAgenticTaskContextEnrichMiddleware(userMessage string, history []agent.ChatMessage, maxRunes int, projectBlackboard string) adk.TypedChatModelAgentMiddleware[*schema.AgenticMessage] {
+	supplement := buildUserContextSupplement(userMessage, history, maxRunes)
+	if bb := strings.TrimSpace(projectBlackboard); bb != "" {
+		if supplement != "" {
+			supplement += "\n\n" + bb
+		} else {
+			supplement = "\n\n" + bb
+		}
+	}
+	if supplement == "" {
+		return nil
+	}
+	return &agenticTaskContextEnrichMiddleware{
+		TypedBaseChatModelAgentMiddleware: &adk.TypedBaseChatModelAgentMiddleware[*schema.AgenticMessage]{},
+		supplement:                        supplement,
+	}
+}
+
+func (m *taskContextEnrichMiddleware) WrapInvokableToolCall(
+	ctx context.Context,
+	endpoint adk.InvokableToolCallEndpoint,
+	tCtx *adk.ToolContext,
+) (adk.InvokableToolCallEndpoint, error) {
+	return wrapTaskContextEnrichCall(m, ctx, endpoint, tCtx)
+}
+
+func (m *agenticTaskContextEnrichMiddleware) WrapInvokableToolCall(
+	ctx context.Context,
+	endpoint adk.InvokableToolCallEndpoint,
+	tCtx *adk.ToolContext,
+) (adk.InvokableToolCallEndpoint, error) {
+	return wrapTaskContextEnrichCall(m, ctx, endpoint, tCtx)
+}
+
+type taskContextEnricher interface {
+	enrichTaskDescription(argsJSON string) string
+}
+
+func wrapTaskContextEnrichCall(
+	m taskContextEnricher,
+	ctx context.Context,
+	endpoint adk.InvokableToolCallEndpoint,
+	tCtx *adk.ToolContext,
+) (adk.InvokableToolCallEndpoint, error) {
+	if tCtx == nil || !strings.EqualFold(strings.TrimSpace(tCtx.Name), "task") {
+		return endpoint, nil
+	}
+	return func(ctx context.Context, argumentsInJSON string, opts ...tool.Option) (string, error) {
+		enriched := m.enrichTaskDescription(argumentsInJSON)
+		return endpoint(ctx, enriched, opts...)
+	}, nil
+}
+
+// enrichTaskDescription parses the task JSON arguments, appends user context
+// to the "description" field, and re-serializes. Falls back to the original
+// JSON if parsing fails or no description field exists.
+func (m *taskContextEnrichMiddleware) enrichTaskDescription(argsJSON string) string {
+	return enrichTaskDescriptionWithSupplement(argsJSON, m.supplement)
+}
+
+func (m *agenticTaskContextEnrichMiddleware) enrichTaskDescription(argsJSON string) string {
+	return enrichTaskDescriptionWithSupplement(argsJSON, m.supplement)
+}
+
+func enrichTaskDescriptionWithSupplement(argsJSON, supplement string) string {
+	var raw map[string]interface{}
+	if err := json.Unmarshal([]byte(argsJSON), &raw); err != nil {
+		return argsJSON
+	}
+	desc, ok := raw["description"].(string)
+	if !ok {
+		return argsJSON
+	}
+	raw["description"] = desc + supplement
+	enriched, err := json.Marshal(raw)
+	if err != nil {
+		return argsJSON
+	}
+	return string(enriched)
+}
+
+// buildUserContextSupplement collects user messages from conversation history
+// and the current message, returning a formatted block to append to task
+// descriptions. Returns "" if disabled or no user messages exist.
+func buildUserContextSupplement(userMessage string, history []agent.ChatMessage, maxRunes int) string {
+	if maxRunes < 0 {
+		return ""
+	}
+
+	var userMsgs []string
+	for _, h := range history {
+		if h.Role == "user" {
+			if m := strings.TrimSpace(h.Content); m != "" {
+				userMsgs = append(userMsgs, m)
+			}
+		}
+	}
+	if um := strings.TrimSpace(userMessage); um != "" {
+		if len(userMsgs) == 0 || userMsgs[len(userMsgs)-1] != um {
+			userMsgs = append(userMsgs, um)
+		}
+	}
+	if len(userMsgs) == 0 {
+		return ""
+	}
+
+	lines := make([]string, 0, len(userMsgs))
+	for i, msg := range userMsgs {
+		lines = append(lines, fmt.Sprintf("[第%d轮] %s", i+1, msg))
+	}
+	joined := strings.Join(lines, "\n")
+	if maxRunes > 0 && len([]rune(joined)) > maxRunes {
+		joined = truncateKeepFirstLast(userMsgs, maxRunes)
+	}
+
+	return userContextSupplementHeader + joined
+}
+
+// truncateKeepFirstLast keeps the first and last user messages, giving each
+// half the rune budget. The first message typically contains target info;
+// the last contains the current instruction.
+func truncateKeepFirstLast(msgs []string, maxRunes int) string {
+	if len(msgs) == 1 {
+		return truncateRunes(msgs[0], maxRunes)
+	}
+
+	first := msgs[0]
+	last := msgs[len(msgs)-1]
+	sep := "\n---\n...(中间对话省略)...\n---\n"
+	sepLen := len([]rune(sep))
+
+	budget := maxRunes - sepLen
+	if budget <= 0 {
+		return truncateRunes(first+"\n---\n"+last, maxRunes)
+	}
+
+	halfBudget := budget / 2
+	firstTrunc := truncateRunes(first, halfBudget)
+	lastTrunc := truncateRunes(last, budget-len([]rune(firstTrunc)))
+
+	return firstTrunc + sep + lastTrunc
+}
+
+func truncateRunes(s string, max int) string {
+	rs := []rune(s)
+	if len(rs) <= max {
+		return s
+	}
+	if max <= 0 {
+		return ""
+	}
+	return string(rs[:max])
+}

internal/multiagent/sub_agent_context_test.go

@@ -0,0 +1,183 @@
+package multiagent
+
+import (
+	"context"
+	"encoding/json"
+	"strings"
+	"testing"
+
+	"cyberstrike-ai/internal/agent"
+
+	"github.com/cloudwego/eino/adk"
+	"github.com/cloudwego/eino/components/tool"
+)
+
+// --- buildUserContextSupplement tests ---
+
+func TestBuildUserContextSupplement_SingleMessage(t *testing.T) {
+	result := buildUserContextSupplement("http://8.163.32.73:8081 测试命令执行", nil, 0)
+	if result == "" {
+		t.Fatal("expected non-empty supplement")
+	}
+	if !strings.Contains(result, "http://8.163.32.73:8081") {
+		t.Error("expected URL in supplement")
+	}
+}
+
+func TestBuildUserContextSupplement_MultiTurn(t *testing.T) {
+	history := []agent.ChatMessage{
+		{Role: "user", Content: "http://8.163.32.73:8081 这是一个pikachu靶场，尝试测试命令执行"},
+		{Role: "assistant", Content: "好的，我来测试..."},
+		{Role: "user", Content: "继续，并持久化webshell"},
+		{Role: "assistant", Content: "正在处理..."},
+	}
+	result := buildUserContextSupplement("你好", history, 0)
+	if !strings.Contains(result, "http://8.163.32.73:8081") {
+		t.Error("expected first turn URL to be preserved")
+	}
+	if !strings.Contains(result, "你好") {
+		t.Error("expected current message")
+	}
+}
+
+func TestBuildUserContextSupplement_Empty(t *testing.T) {
+	if result := buildUserContextSupplement("", nil, 0); result != "" {
+		t.Errorf("expected empty, got %q", result)
+	}
+}
+
+func TestBuildUserContextSupplement_Deduplicate(t *testing.T) {
+	history := []agent.ChatMessage{{Role: "user", Content: "你好"}}
+	result := buildUserContextSupplement("你好", history, 0)
+	if strings.Count(result, "你好") != 1 {
+		t.Errorf("expected '你好' once, got: %s", result)
+	}
+}
+
+func TestBuildUserContextSupplement_SkipsNonUser(t *testing.T) {
+	history := []agent.ChatMessage{
+		{Role: "user", Content: "目标是 10.0.0.1"},
+		{Role: "assistant", Content: "不应该出现"},
+	}
+	result := buildUserContextSupplement("确认", history, 0)
+	if strings.Contains(result, "不应该出现") {
+		t.Error("assistant message should not be included")
+	}
+}
+
+func TestBuildUserContextSupplement_DisabledByNegative(t *testing.T) {
+	if result := buildUserContextSupplement("test", nil, -1); result != "" {
+		t.Errorf("expected empty when disabled, got %q", result)
+	}
+}
+
+func TestBuildUserContextSupplement_CustomMaxRunes(t *testing.T) {
+	msg := strings.Repeat("A", 200)
+	result := buildUserContextSupplement(msg, nil, 50)
+	header := userContextSupplementHeader
+	body := strings.TrimPrefix(result, header)
+	if len([]rune(body)) > 50 {
+		t.Errorf("body should be capped at 50 runes, got %d", len([]rune(body)))
+	}
+}
+
+func TestBuildUserContextSupplement_TruncateKeepsFirstAndLast(t *testing.T) {
+	first := "http://target.com " + strings.Repeat("A", 500)
+	var history []agent.ChatMessage
+	history = append(history, agent.ChatMessage{Role: "user", Content: first})
+	for i := 0; i < 10; i++ {
+		history = append(history, agent.ChatMessage{Role: "user", Content: strings.Repeat("B", 500)})
+	}
+	last := "最后一条指令"
+	result := buildUserContextSupplement(last, history, 800)
+	if !strings.Contains(result, "http://target.com") {
+		t.Error("first message (target URL) should survive truncation")
+	}
+	if !strings.Contains(result, last) {
+		t.Error("last message should survive truncation")
+	}
+}
+
+// --- middleware integration tests ---
+
+func TestTaskContextEnrichMiddleware_EnrichesTaskDescription(t *testing.T) {
+	mw := newTaskContextEnrichMiddleware(
+		"继续测试",
+		[]agent.ChatMessage{{Role: "user", Content: "http://8.163.32.73:8081 pikachu靶场"}},
+		0,
+		"",
+	)
+	if mw == nil {
+		t.Fatal("expected non-nil middleware")
+	}
+
+	called := false
+	var capturedArgs string
+	fakeEndpoint := func(ctx context.Context, args string, opts ...tool.Option) (string, error) {
+		called = true
+		capturedArgs = args
+		return "ok", nil
+	}
+
+	wrapped, err := mw.(interface {
+		WrapInvokableToolCall(context.Context, adk.InvokableToolCallEndpoint, *adk.ToolContext) (adk.InvokableToolCallEndpoint, error)
+	}).WrapInvokableToolCall(context.Background(), fakeEndpoint, &adk.ToolContext{Name: "task"})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	taskArgs := `{"subagent_type":"recon","description":"扫描目标端口"}`
+	wrapped(context.Background(), taskArgs)
+
+	if !called {
+		t.Fatal("endpoint was not called")
+	}
+
+	var parsed map[string]interface{}
+	if err := json.Unmarshal([]byte(capturedArgs), &parsed); err != nil {
+		t.Fatalf("enriched args not valid JSON: %v", err)
+	}
+	desc := parsed["description"].(string)
+	if !strings.Contains(desc, "扫描目标端口") {
+		t.Error("original description should be preserved")
+	}
+	if !strings.Contains(desc, "http://8.163.32.73:8081") {
+		t.Error("user context should be appended to description")
+	}
+	if !strings.Contains(desc, "继续测试") {
+		t.Error("current user message should be in description")
+	}
+}
+
+func TestTaskContextEnrichMiddleware_IgnoresNonTaskTools(t *testing.T) {
+	mw := newTaskContextEnrichMiddleware("test", nil, 0, "")
+	if mw == nil {
+		t.Fatal("expected non-nil middleware")
+	}
+
+	original := `{"command":"nmap -sV target"}`
+	var capturedArgs string
+	fakeEndpoint := func(ctx context.Context, args string, opts ...tool.Option) (string, error) {
+		capturedArgs = args
+		return "ok", nil
+	}
+
+	wrapped, err := mw.(interface {
+		WrapInvokableToolCall(context.Context, adk.InvokableToolCallEndpoint, *adk.ToolContext) (adk.InvokableToolCallEndpoint, error)
+	}).WrapInvokableToolCall(context.Background(), fakeEndpoint, &adk.ToolContext{Name: "nmap_scan"})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	wrapped(context.Background(), original)
+	if capturedArgs != original {
+		t.Errorf("non-task tool args should not be modified, got %q", capturedArgs)
+	}
+}
+
+func TestTaskContextEnrichMiddleware_NilWhenDisabled(t *testing.T) {
+	mw := newTaskContextEnrichMiddleware("test", nil, -1, "")
+	if mw != nil {
+		t.Error("middleware should be nil when disabled")
+	}
+}

internal/multiagent/system_message_normalizer_middleware.go

@@ -0,0 +1,86 @@
+package multiagent
+
+import (
+	"context"
+
+	"github.com/cloudwego/eino/adk"
+	"github.com/cloudwego/eino/schema"
+	"go.uber.org/zap"
+)
+
+// systemMessageNormalizerMiddleware merges duplicate role=system messages into a single
+// leading system message before summarization and each ChatModel call.
+type systemMessageNormalizerMiddleware struct {
+	adk.BaseChatModelAgentMiddleware
+	logger *zap.Logger
+	phase  string
+}
+
+func newSystemMessageNormalizerMiddleware(logger *zap.Logger, phase string) adk.ChatModelAgentMiddleware {
+	return &systemMessageNormalizerMiddleware{logger: logger, phase: phase}
+}
+
+func (m *systemMessageNormalizerMiddleware) BeforeModelRewriteState(
+	ctx context.Context,
+	state *adk.ChatModelAgentState,
+	mc *adk.ModelContext,
+) (context.Context, *adk.ChatModelAgentState, error) {
+	_ = mc
+	if m == nil || state == nil || len(state.Messages) == 0 {
+		return ctx, state, nil
+	}
+	before := countADKSystemMessages(state.Messages)
+	if before <= 1 {
+		return ctx, state, nil
+	}
+	normalized := normalizeSingleLeadingSystemMessage(state.Messages, "")
+	if len(normalized) == len(state.Messages) && countADKSystemMessages(normalized) >= before {
+		return ctx, state, nil
+	}
+	if m.logger != nil {
+		m.logger.Info("eino system messages merged",
+			zap.String("phase", m.phase),
+			zap.Int("system_before", before),
+			zap.Int("system_after", countADKSystemMessages(normalized)),
+			zap.Int("messages_before", len(state.Messages)),
+			zap.Int("messages_after", len(normalized)),
+		)
+	}
+	out := *state
+	out.Messages = normalized
+	return ctx, &out, nil
+}
+
+func countADKSystemMessages(msgs []adk.Message) int {
+	n := 0
+	for _, msg := range msgs {
+		if msg != nil && msg.Role == schema.System {
+			n++
+		}
+	}
+	return n
+}
+
+// stripADKSystemMessages removes all system messages. Use before runner.Run restart when
+// genModelInput will prepend a fresh Instruction.
+func stripADKSystemMessages(msgs []adk.Message) []adk.Message {
+	if len(msgs) == 0 {
+		return msgs
+	}
+	out := make([]adk.Message, 0, len(msgs))
+	for _, msg := range msgs {
+		if msg == nil || msg.Role == schema.System {
+			continue
+		}
+		out = append(out, msg)
+	}
+	return out
+}
+
+// mergeCollectedSystemMessages collapses multiple system messages into one (or none).
+func mergeCollectedSystemMessages(systemMsgs []adk.Message) []adk.Message {
+	if len(systemMsgs) == 0 {
+		return nil
+	}
+	return normalizeSingleLeadingSystemMessage(systemMsgs, "")
+}

internal/multiagent/system_message_normalizer_middleware_test.go

@@ -0,0 +1,75 @@
+package multiagent
+
+import (
+	"context"
+	"testing"
+
+	"github.com/cloudwego/eino/adk"
+	"github.com/cloudwego/eino/schema"
+)
+
+func TestStripADKSystemMessages(t *testing.T) {
+	in := []adk.Message{
+		schema.SystemMessage("a"),
+		schema.UserMessage("u"),
+		schema.SystemMessage("b"),
+		schema.AssistantMessage("x", nil),
+	}
+	out := stripADKSystemMessages(in)
+	if len(out) != 2 {
+		t.Fatalf("got %d messages, want 2", len(out))
+	}
+	if out[0].Role != schema.User || out[1].Role != schema.Assistant {
+		t.Fatalf("unexpected roles: %s, %s", out[0].Role, out[1].Role)
+	}
+}
+
+func TestEinoMessagesForRunRestart_StripsSystemFromTrace(t *testing.T) {
+	holder := newModelFacingTraceHolder()
+	holder.storeFromState(&adk.ChatModelAgentState{Messages: []adk.Message{
+		schema.SystemMessage("sys-1"),
+		schema.SystemMessage("sys-2"),
+		schema.UserMessage("task"),
+	}})
+	msgs, src := einoMessagesForRunRestart(&einoADKRunLoopArgs{ModelFacingTrace: holder}, nil, nil, 0)
+	if src != einoRestartContextModelTrace {
+		t.Fatalf("source: got %q want model_trace", src)
+	}
+	if len(msgs) != 1 || msgs[0].Role != schema.User {
+		t.Fatalf("expected user-only restart msgs, got %+v", msgs)
+	}
+}
+
+func TestSystemMessageNormalizerMiddleware_MergesDuplicates(t *testing.T) {
+	mw := newSystemMessageNormalizerMiddleware(nil, "test")
+	state := &adk.ChatModelAgentState{Messages: []adk.Message{
+		schema.SystemMessage("a"),
+		schema.SystemMessage("b"),
+		schema.UserMessage("u"),
+	}}
+	_, out, err := mw.(*systemMessageNormalizerMiddleware).BeforeModelRewriteState(context.Background(), state, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if countADKSystemMessages(out.Messages) != 1 {
+		t.Fatalf("want 1 system, got %d", countADKSystemMessages(out.Messages))
+	}
+	if out.Messages[0].Content != "a\n\nb" {
+		t.Fatalf("merged content: %q", out.Messages[0].Content)
+	}
+}
+
+func TestSystemMessageNormalizerMiddleware_NoOpSingleSystem(t *testing.T) {
+	mw := newSystemMessageNormalizerMiddleware(nil, "test")
+	state := &adk.ChatModelAgentState{Messages: []adk.Message{
+		schema.SystemMessage("only"),
+		schema.UserMessage("u"),
+	}}
+	_, out, err := mw.(*systemMessageNormalizerMiddleware).BeforeModelRewriteState(context.Background(), state, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if out != state {
+		t.Fatalf("expected same state pointer for no-op")
+	}
+}

internal/multiagent/tool_always_visible.go

@@ -0,0 +1,72 @@
+package multiagent
+
+import (
+	"strings"
+)
+
+// expandAlwaysVisibleNameSet 将配置中的常驻工具名展开为可匹配运行时工具名的集合。
+// 支持：内置短名 read_file；外部 mcp::tool；运行时 mcp__tool（OpenAI/Eino 命名）。
+func expandAlwaysVisibleNameSet(names []string) map[string]struct{} {
+	set := make(map[string]struct{}, len(names)*3)
+	add := func(name string) {
+		n := strings.TrimSpace(strings.ToLower(name))
+		if n == "" {
+			return
+		}
+		set[n] = struct{}{}
+	}
+	for _, raw := range names {
+		n := strings.TrimSpace(strings.ToLower(raw))
+		if n == "" {
+			continue
+		}
+		add(n)
+		if mcp, tool, ok := strings.Cut(n, "::"); ok && mcp != "" && tool != "" {
+			// 外部工具用 mcp::tool 配置时只展开运行时 mcp__tool，避免短名误伤其它 MCP 同名工具。
+			add(mcp + "__" + tool)
+			continue
+		}
+		if idx := strings.LastIndex(n, "__"); idx > 0 {
+			mcp, tool := n[:idx], n[idx+2:]
+			if mcp != "" && tool != "" {
+				add(mcp + "::" + tool)
+			}
+			continue
+		}
+	}
+	return set
+}
+
+// toolMatchesAlwaysVisible 判断运行时工具名是否命中常驻白名单（含别名）。
+func toolMatchesAlwaysVisible(runtimeName string, nameSet map[string]struct{}) bool {
+	if len(nameSet) == 0 {
+		return false
+	}
+	name := strings.TrimSpace(strings.ToLower(runtimeName))
+	if name == "" {
+		return false
+	}
+	if _, ok := nameSet[name]; ok {
+		return true
+	}
+	if mcp, tool, ok := strings.Cut(name, "::"); ok && mcp != "" && tool != "" {
+		if _, ok := nameSet[mcp+"__"+tool]; ok {
+			return true
+		}
+		if _, ok := nameSet[tool]; ok {
+			return true
+		}
+	}
+	if idx := strings.LastIndex(name, "__"); idx > 0 {
+		mcp, tool := name[:idx], name[idx+2:]
+		if mcp != "" && tool != "" {
+			if _, ok := nameSet[mcp+"::"+tool]; ok {
+				return true
+			}
+			if _, ok := nameSet[tool]; ok {
+				return true
+			}
+		}
+	}
+	return false
+}

internal/multiagent/tool_always_visible_test.go

@@ -0,0 +1,32 @@
+package multiagent
+
+import "testing"
+
+func TestToolMatchesAlwaysVisible_ExternalAliases(t *testing.T) {
+	t.Parallel()
+	set := expandAlwaysVisibleNameSet([]string{"zhidemai::discount_search", "read_file"})
+
+	cases := []struct {
+		runtime string
+		want    bool
+	}{
+		{"zhidemai__discount_search", true},
+		{"zhidemai::discount_search", true},
+		{"read_file", true},
+		{"zhidemai__product_search_pro", false},
+		{"github__discount_search", false},
+	}
+	for _, tc := range cases {
+		if got := toolMatchesAlwaysVisible(tc.runtime, set); got != tc.want {
+			t.Fatalf("toolMatchesAlwaysVisible(%q) = %v, want %v", tc.runtime, got, tc.want)
+		}
+	}
+}
+
+func TestExpandAlwaysVisibleNameSet_LegacyShortName(t *testing.T) {
+	t.Parallel()
+	set := expandAlwaysVisibleNameSet([]string{"discount_search"})
+	if !toolMatchesAlwaysVisible("zhidemai__discount_search", set) {
+		t.Fatal("legacy short name should match external runtime tool")
+	}
+}

internal/multiagent/tool_call_arguments_sanitizer_middleware.go

@@ -0,0 +1,103 @@
+package multiagent
+
+import (
+	"context"
+	"encoding/json"
+	"strings"
+
+	"github.com/cloudwego/eino/adk"
+	"github.com/cloudwego/eino/schema"
+	"go.uber.org/zap"
+)
+
+const repairedMalformedToolArguments = `{}`
+
+// toolCallArgumentsSanitizerMiddleware guarantees that every historical
+// tool_calls[].function.arguments value sent to an OpenAI-compatible provider is
+// a syntactically valid JSON object. Some providers reject the entire request
+// with HTTP 400 when a model previously emitted truncated arguments.
+//
+// The original malformed payload is intentionally not copied into model-facing
+// history: it may contain secrets and can itself be large enough to trigger the
+// same failure again. The paired tool result already records the execution error
+// and gives the model enough information to recover.
+type toolCallArgumentsSanitizerMiddleware struct {
+	adk.BaseChatModelAgentMiddleware
+	logger *zap.Logger
+	phase  string
+}
+
+func newToolCallArgumentsSanitizerMiddleware(logger *zap.Logger, phase string) adk.ChatModelAgentMiddleware {
+	return &toolCallArgumentsSanitizerMiddleware{logger: logger, phase: phase}
+}
+
+func (m *toolCallArgumentsSanitizerMiddleware) BeforeModelRewriteState(
+	ctx context.Context,
+	state *adk.ChatModelAgentState,
+	mc *adk.ModelContext,
+) (context.Context, *adk.ChatModelAgentState, error) {
+	_ = mc
+	if m == nil || state == nil || len(state.Messages) == 0 {
+		return ctx, state, nil
+	}
+
+	out, repaired := sanitizeMalformedToolCallArguments(state.Messages)
+	if repaired == 0 {
+		return ctx, state, nil
+	}
+	if m.logger != nil {
+		m.logger.Warn("eino malformed tool-call arguments repaired before model call",
+			zap.String("phase", m.phase),
+			zap.Int("repaired_calls", repaired),
+		)
+	}
+	ns := *state
+	ns.Messages = out
+	return ctx, &ns, nil
+}
+
+func sanitizeMalformedToolCallArguments(messages []adk.Message) ([]adk.Message, int) {
+	var out []adk.Message
+	repaired := 0
+	for i, msg := range messages {
+		if msg == nil || msg.Role != schema.Assistant || len(msg.ToolCalls) == 0 {
+			continue
+		}
+		calls := append([]schema.ToolCall(nil), msg.ToolCalls...)
+		changed := false
+		for j := range calls {
+			if validToolArgumentsJSONObject(calls[j].Function.Arguments) {
+				continue
+			}
+			calls[j].Function.Arguments = repairedMalformedToolArguments
+			changed = true
+			repaired++
+		}
+		if !changed {
+			continue
+		}
+		if out == nil {
+			out = append([]adk.Message(nil), messages...)
+		}
+		cloned := *msg
+		cloned.ToolCalls = calls
+		out[i] = &cloned
+	}
+	if out == nil {
+		return messages, 0
+	}
+	return out, repaired
+}
+
+func validToolArgumentsJSONObject(arguments string) bool {
+	arguments = strings.TrimSpace(arguments)
+	if arguments == "" {
+		return false
+	}
+	var value any
+	if err := json.Unmarshal([]byte(arguments), &value); err != nil {
+		return false
+	}
+	_, ok := value.(map[string]any)
+	return ok
+}

internal/multiagent/tool_call_arguments_sanitizer_middleware_test.go

@@ -0,0 +1,65 @@
+package multiagent
+
+import (
+	"context"
+	"testing"
+
+	"github.com/cloudwego/eino/adk"
+	"github.com/cloudwego/eino/schema"
+)
+
+func TestToolCallArgumentsSanitizerRepairsOnlyMalformedObjects(t *testing.T) {
+	valid := assistantToolCallsMsg("", "valid")
+	valid.ToolCalls[0].Function.Arguments = `{"command":"echo ok"}`
+	malformed := assistantToolCallsMsg("", "broken", "array")
+	malformed.ToolCalls[0].Function.Arguments = `{"command":"unterminated`
+	malformed.ToolCalls[1].Function.Arguments = `[]`
+	messages := []adk.Message{valid, malformed, schema.ToolMessage("failed", "broken")}
+
+	out, repaired := sanitizeMalformedToolCallArguments(messages)
+	if repaired != 2 {
+		t.Fatalf("repaired=%d, want 2", repaired)
+	}
+	if out[0].ToolCalls[0].Function.Arguments != `{"command":"echo ok"}` {
+		t.Fatalf("valid arguments changed: %q", out[0].ToolCalls[0].Function.Arguments)
+	}
+	for _, tc := range out[1].ToolCalls {
+		if tc.Function.Arguments != repairedMalformedToolArguments {
+			t.Fatalf("malformed arguments not repaired: %q", tc.Function.Arguments)
+		}
+	}
+	if malformed.ToolCalls[0].Function.Arguments == repairedMalformedToolArguments {
+		t.Fatal("input message was mutated")
+	}
+}
+
+func TestToolCallArgumentsSanitizerMiddlewareRewritesState(t *testing.T) {
+	msg := assistantToolCallsMsg("", "broken")
+	msg.ToolCalls[0].Function.Arguments = ""
+	mw := newToolCallArgumentsSanitizerMiddleware(nil, "test").(*toolCallArgumentsSanitizerMiddleware)
+	_, state, err := mw.BeforeModelRewriteState(context.Background(), &adk.ChatModelAgentState{
+		Messages: []adk.Message{msg},
+	}, &adk.ModelContext{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got := state.Messages[0].ToolCalls[0].Function.Arguments; got != `{}` {
+		t.Fatalf("arguments=%q, want {}", got)
+	}
+}
+
+func TestValidToolArgumentsJSONObject(t *testing.T) {
+	cases := map[string]bool{
+		`{}`:      true,
+		`{"x":1}`: true,
+		`null`:    false,
+		`[]`:      false,
+		`{"x":`:   false,
+		``:        false,
+	}
+	for input, want := range cases {
+		if got := validToolArgumentsJSONObject(input); got != want {
+			t.Errorf("validToolArgumentsJSONObject(%q)=%v, want %v", input, got, want)
+		}
+	}
+}

internal/multiagent/tool_error_middleware.go

@@ -0,0 +1,148 @@
+package multiagent
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"strings"
+
+	"github.com/cloudwego/eino/compose"
+	"github.com/cloudwego/eino/schema"
+)
+
+// softRecoveryToolCallMiddleware returns an InvokableToolMiddleware that catches
+// specific recoverable errors from tool execution (JSON parse errors, tool-not-found,
+// etc.) and converts them into soft errors: nil error + descriptive error content
+// returned to the LLM. This allows the model to self-correct within the same
+// iteration rather than crashing the entire graph and requiring a full replay.
+//
+// Without Invokable (+ Streamable where applicable) registration, a JSON parse failure
+// in InvokableRun / StreamableRun propagates as a hard error through the Eino ToolsNode
+// → [NodeRunError] → ev.Err, which
+// either triggers the full-replay retry loop (expensive) or terminates the run
+// entirely once retries are exhausted. With it, the LLM simply sees an error message
+// in the tool result and can adjust its next tool call accordingly.
+func softRecoveryToolCallMiddleware() compose.InvokableToolMiddleware {
+	return func(next compose.InvokableToolEndpoint) compose.InvokableToolEndpoint {
+		return func(ctx context.Context, input *compose.ToolInput) (*compose.ToolOutput, error) {
+			output, err := next(ctx, input)
+			if err == nil {
+				return output, nil
+			}
+			if !isSoftRecoverableToolError(err) {
+				return output, err
+			}
+			// Convert the hard error into a soft error: the LLM will see this
+			// message as the tool's output and can self-correct.
+			msg := buildSoftRecoveryMessage(input.Name, input.Arguments, err)
+			return &compose.ToolOutput{Result: msg}, nil
+		}
+	}
+}
+
+// softRecoveryStreamableToolCallMiddleware mirrors softRecoveryToolCallMiddleware for
+// tools that implement StreamableTool only (e.g. Eino ADK filesystem execute).
+// Eino applies Invokable vs Streamable middleware to disjoint code paths in ToolsNode;
+// registering only Invokable leaves streaming tools uncovered — empty/malformed JSON
+// then fails inside [LocalStreamFunc] before the inner endpoint runs.
+func softRecoveryStreamableToolCallMiddleware() compose.StreamableToolMiddleware {
+	return func(next compose.StreamableToolEndpoint) compose.StreamableToolEndpoint {
+		return func(ctx context.Context, input *compose.ToolInput) (*compose.StreamToolOutput, error) {
+			out, err := next(ctx, input)
+			if err == nil {
+				return out, nil
+			}
+			if !isSoftRecoverableToolError(err) {
+				return out, err
+			}
+			toolName := ""
+			args := ""
+			if input != nil {
+				toolName = input.Name
+				args = input.Arguments
+			}
+			msg := buildSoftRecoveryMessage(toolName, args, err)
+			return &compose.StreamToolOutput{
+				Result: schema.StreamReaderFromArray([]string{msg}),
+			}, nil
+		}
+	}
+}
+
+// softRecoveryToolMiddleware returns a ToolMiddleware with both Invokable and Streamable
+// soft recovery (same semantics as hitlToolCallMiddleware bundling).
+func softRecoveryToolMiddleware() compose.ToolMiddleware {
+	return compose.ToolMiddleware{
+		Invokable:  softRecoveryToolCallMiddleware(),
+		Streamable: softRecoveryStreamableToolCallMiddleware(),
+	}
+}
+
+// isSoftRecoverableToolError determines whether a tool execution error should be
+// silently converted to a tool-result message rather than crashing the graph.
+//
+// Design: default-soft (blacklist). Almost every tool execution error should be
+// fed back to the LLM so it can self-correct or choose an alternative tool.
+// Only a small set of "truly fatal" conditions (user cancellation) should
+// propagate as hard errors that terminate the orchestration graph.
+// This avoids the fragile whitelist approach where every new error pattern
+// would need to be explicitly enumerated.
+func isSoftRecoverableToolError(err error) bool {
+	if err == nil {
+		return false
+	}
+
+	// 用户主动取消 — 唯一应当终止编排的情况，不应重试。
+	if errors.Is(err, context.Canceled) {
+		return false
+	}
+
+	// 其他所有工具执行错误（超时、命令不存在、JSON 解析失败、工具未找到、
+	// 权限不足、网络不可达……）一律转为 soft error，让 LLM 看到错误信息
+	// 后自行决策：换工具、调整参数、或向用户说明。
+	return true
+}
+
+// buildSoftRecoveryMessage creates a bilingual error message that the LLM can act on.
+func buildSoftRecoveryMessage(toolName, arguments string, err error) string {
+	// Truncate arguments preview to avoid flooding the context.
+	argPreview := arguments
+	if len(argPreview) > 300 {
+		argPreview = argPreview[:300] + "... (truncated)"
+	}
+
+	// Try to determine if it's specifically a JSON parse error for a friendlier message.
+	errStr := err.Error()
+	var jsonErr *json.SyntaxError
+	isJSONErr := strings.Contains(strings.ToLower(errStr), "json") ||
+		strings.Contains(strings.ToLower(errStr), "unmarshal")
+	_ = jsonErr // suppress unused
+
+	if isJSONErr {
+		return fmt.Sprintf(
+			"[Tool Error] The arguments for tool '%s' are not valid JSON and could not be parsed.\n"+
+				"Error: %s\n"+
+				"Arguments received: %s\n\n"+
+				"Please fix the JSON (ensure double-quoted keys, matched braces/brackets, no trailing commas, "+
+				"no truncation) and call the tool again.\n\n"+
+				"[工具错误] 工具 '%s' 的参数不是合法 JSON，无法解析。\n"+
+				"错误：%s\n"+
+				"收到的参数：%s\n\n"+
+				"请修正 JSON（确保双引号键名、括号配对、无尾部逗号、无截断），然后重新调用工具。",
+			toolName, errStr, argPreview,
+			toolName, errStr, argPreview,
+		)
+	}
+
+	return fmt.Sprintf(
+		"[Tool Error] Tool '%s' execution failed: %s\n"+
+			"Arguments: %s\n\n"+
+			"Please review the available tools and their expected arguments, then retry.\n\n"+
+			"[工具错误] 工具 '%s' 执行失败：%s\n"+
+			"参数：%s\n\n"+
+			"请检查可用工具及其参数要求，然后重试。",
+		toolName, errStr, argPreview,
+		toolName, errStr, argPreview,
+	)
+}

internal/multiagent/tool_error_middleware_test.go

@@ -0,0 +1,207 @@
+package multiagent
+
+import (
+	"context"
+	"encoding/json"
+	"errors"
+	"io"
+	"strings"
+	"testing"
+
+	"github.com/cloudwego/eino/compose"
+)
+
+func TestIsSoftRecoverableToolError(t *testing.T) {
+	tests := []struct {
+		name     string
+		err      error
+		expected bool
+	}{
+		{
+			name:     "nil error",
+			err:      nil,
+			expected: false,
+		},
+		{
+			name:     "unexpected end of JSON input",
+			err:      errors.New("unexpected end of JSON input"),
+			expected: true,
+		},
+		{
+			name:     "failed to unmarshal task tool input json",
+			err:      errors.New("failed to unmarshal task tool input json: unexpected end of JSON input"),
+			expected: true,
+		},
+		{
+			name:     "invalid tool arguments JSON",
+			err:      errors.New("invalid tool arguments JSON: unexpected end of JSON input"),
+			expected: true,
+		},
+		{
+			name:     "json invalid character",
+			err:      errors.New(`invalid character '}' looking for beginning of value in JSON`),
+			expected: true,
+		},
+		{
+			name:     "subagent type not found",
+			err:      errors.New("subagent type recon_agent not found"),
+			expected: true,
+		},
+		{
+			name:     "tool not found",
+			err:      errors.New("tool nmap_scan not found in toolsNode indexes"),
+			expected: true,
+		},
+		{
+			name:     "unrelated network error",
+			err:      errors.New("connection refused"),
+			expected: true, // default-soft: non-cancel errors are recoverable
+		},
+		{
+			name:     "tool binary not installed",
+			err:      errors.New("[LocalFunc] failed to invoke tool, toolName=grep, err=ripgrep (rg) is not installed or not in PATH"),
+			expected: true,
+		},
+		{
+			name:     "context cancelled",
+			err:      context.Canceled,
+			expected: false,
+		},
+		{
+			name: "real json unmarshal error",
+			err: func() error {
+				var v map[string]interface{}
+				return json.Unmarshal([]byte(`{"key": `), &v)
+			}(),
+			expected: true,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := isSoftRecoverableToolError(tt.err)
+			if got != tt.expected {
+				t.Errorf("isSoftRecoverableToolError(%v) = %v, want %v", tt.err, got, tt.expected)
+			}
+		})
+	}
+}
+
+func TestSoftRecoveryToolCallMiddleware_PassesThrough(t *testing.T) {
+	mw := softRecoveryToolCallMiddleware()
+	called := false
+	next := func(ctx context.Context, input *compose.ToolInput) (*compose.ToolOutput, error) {
+		called = true
+		return &compose.ToolOutput{Result: "success"}, nil
+	}
+	wrapped := mw(next)
+	out, err := wrapped(context.Background(), &compose.ToolInput{
+		Name:      "test_tool",
+		Arguments: `{"key": "value"}`,
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !called {
+		t.Fatal("next endpoint was not called")
+	}
+	if out.Result != "success" {
+		t.Fatalf("expected 'success', got %q", out.Result)
+	}
+}
+
+func TestSoftRecoveryStreamableToolCallMiddleware_LocalStreamFuncJSONError(t *testing.T) {
+	mw := softRecoveryStreamableToolCallMiddleware()
+	next := func(ctx context.Context, input *compose.ToolInput) (*compose.StreamToolOutput, error) {
+		return nil, errors.New(`[LocalStreamFunc] failed to unmarshal arguments in json, toolName=execute, err="Syntax error no sources available, the input json is empty`)
+	}
+	wrapped := mw(next)
+	out, err := wrapped(context.Background(), &compose.ToolInput{
+		Name:      "execute",
+		Arguments: "",
+	})
+	if err != nil {
+		t.Fatalf("expected nil error (soft recovery), got: %v", err)
+	}
+	if out == nil || out.Result == nil {
+		t.Fatal("expected stream result")
+	}
+	var sb strings.Builder
+	for {
+		chunk, rerr := out.Result.Recv()
+		if errors.Is(rerr, io.EOF) {
+			break
+		}
+		if rerr != nil {
+			t.Fatalf("recv: %v", rerr)
+		}
+		sb.WriteString(chunk)
+	}
+	text := sb.String()
+	if !containsAll(text, "[Tool Error]", "execute", "JSON") {
+		t.Fatalf("recovery message missing expected content: %s", text)
+	}
+}
+
+func TestSoftRecoveryToolCallMiddleware_ConvertsJSONError(t *testing.T) {
+	mw := softRecoveryToolCallMiddleware()
+	next := func(ctx context.Context, input *compose.ToolInput) (*compose.ToolOutput, error) {
+		return nil, errors.New("failed to unmarshal task tool input json: unexpected end of JSON input")
+	}
+	wrapped := mw(next)
+	out, err := wrapped(context.Background(), &compose.ToolInput{
+		Name:      "task",
+		Arguments: `{"subagent_type": "recon`,
+	})
+	if err != nil {
+		t.Fatalf("expected nil error (soft recovery), got: %v", err)
+	}
+	if out == nil || out.Result == "" {
+		t.Fatal("expected non-empty recovery message")
+	}
+	if !containsAll(out.Result, "[Tool Error]", "task", "JSON") {
+		t.Fatalf("recovery message missing expected content: %s", out.Result)
+	}
+}
+
+func TestSoftRecoveryToolCallMiddleware_PropagatesNonRecoverable(t *testing.T) {
+	mw := softRecoveryToolCallMiddleware()
+	origErr := errors.New("connection timeout to remote server")
+	next := func(ctx context.Context, input *compose.ToolInput) (*compose.ToolOutput, error) {
+		return nil, origErr
+	}
+	wrapped := mw(next)
+	out, err := wrapped(context.Background(), &compose.ToolInput{
+		Name:      "test_tool",
+		Arguments: `{}`,
+	})
+	// Default-soft: non-cancel errors are converted to tool-result messages.
+	if err != nil {
+		t.Fatalf("expected nil error (soft recovery), got: %v", err)
+	}
+	if out == nil || out.Result == "" {
+		t.Fatal("expected non-empty recovery message")
+	}
+}
+
+func containsAll(s string, subs ...string) bool {
+	for _, sub := range subs {
+		if !contains(s, sub) {
+			return false
+		}
+	}
+	return true
+}
+
+func contains(s, sub string) bool {
+	return len(s) >= len(sub) && searchString(s, sub)
+}
+
+func searchString(s, sub string) bool {
+	for i := 0; i <= len(s)-len(sub); i++ {
+		if s[i:i+len(sub)] == sub {
+			return true
+		}
+	}
+	return false
+}

internal/multiagent/tool_pair_reconciler_middleware.go

@@ -0,0 +1,156 @@
+package multiagent
+
+import (
+	"context"
+	"fmt"
+
+	"github.com/cloudwego/eino/adk"
+	"github.com/cloudwego/eino/schema"
+	"go.uber.org/zap"
+)
+
+const patchedMissingToolResult = "[Tool execution result was lost or interrupted; continue without relying on this call.]"
+
+// toolPairReconcilerMiddleware is the final structural guard before a model call.
+// It makes every assistant tool-call batch immediately followed by exactly one tool
+// result per call ID, and drops tool messages that cannot belong to that batch.
+//
+// This intentionally runs after summarization/reduction/budget middleware: those
+// middlewares rewrite history and can otherwise re-introduce a partial tool round
+// after the ordinary patchtoolcalls middleware has already run.
+type toolPairReconcilerMiddleware struct {
+	adk.BaseChatModelAgentMiddleware
+	logger *zap.Logger
+	phase  string
+}
+
+func newToolPairReconcilerMiddleware(logger *zap.Logger, phase string) adk.ChatModelAgentMiddleware {
+	return &toolPairReconcilerMiddleware{logger: logger, phase: phase}
+}
+
+func (m *toolPairReconcilerMiddleware) BeforeModelRewriteState(
+	ctx context.Context,
+	state *adk.ChatModelAgentState,
+	mc *adk.ModelContext,
+) (context.Context, *adk.ChatModelAgentState, error) {
+	_ = mc
+	if m == nil || state == nil || len(state.Messages) == 0 {
+		return ctx, state, nil
+	}
+
+	usedIDs := make(map[string]struct{}, 16)
+	changed := false
+	patched := 0
+	dropped := 0
+	out := make([]adk.Message, 0, len(state.Messages))
+
+	for i := 0; i < len(state.Messages); {
+		msg := state.Messages[i]
+		if msg == nil {
+			changed = true
+			i++
+			continue
+		}
+		if msg.Role == schema.Tool {
+			// Valid tool results are consumed with their immediately preceding assistant.
+			changed = true
+			dropped++
+			i++
+			continue
+		}
+		if msg.Role != schema.Assistant || len(msg.ToolCalls) == 0 {
+			out = append(out, msg)
+			i++
+			continue
+		}
+
+		assistant := msg
+		calls := append([]schema.ToolCall(nil), msg.ToolCalls...)
+		expected := make(map[string]schema.ToolCall, len(calls))
+		idsChanged := false
+		for callIndex := range calls {
+			id := calls[callIndex].ID
+			_, duplicate := usedIDs[id]
+			if id == "" || duplicate {
+				base := fmt.Sprintf("patched_tool_call_%d_%d", i, callIndex)
+				id = base
+				for suffix := 1; ; suffix++ {
+					if _, exists := usedIDs[id]; !exists {
+						break
+					}
+					id = fmt.Sprintf("%s_%d", base, suffix)
+				}
+				calls[callIndex].ID = id
+				idsChanged = true
+				changed = true
+			}
+			usedIDs[id] = struct{}{}
+			expected[id] = calls[callIndex]
+		}
+		if idsChanged {
+			cloned := *msg
+			cloned.ToolCalls = calls
+			assistant = &cloned
+		}
+		out = append(out, assistant)
+
+		results := make(map[string]adk.Message, len(calls))
+		j := i + 1
+		for j < len(state.Messages) {
+			toolMsg := state.Messages[j]
+			if toolMsg == nil {
+				changed = true
+				j++
+				continue
+			}
+			if toolMsg.Role != schema.Tool {
+				break
+			}
+			id := toolMsg.ToolCallID
+			if _, wanted := expected[id]; !wanted {
+				changed = true
+				dropped++
+				j++
+				continue
+			}
+			if _, duplicate := results[id]; duplicate {
+				changed = true
+				dropped++
+				j++
+				continue
+			}
+			results[id] = toolMsg
+			j++
+		}
+		for _, tc := range calls {
+			if result, ok := results[tc.ID]; ok {
+				out = append(out, result)
+				continue
+			}
+			out = append(out, schema.ToolMessage(
+				patchedMissingToolResult,
+				tc.ID,
+				schema.WithToolName(tc.Function.Name),
+			))
+			changed = true
+			patched++
+		}
+		i = j
+	}
+
+	if !changed {
+		return ctx, state, nil
+	}
+	if m.logger != nil {
+		m.logger.Warn("eino tool-call/result pairs reconciled before model call",
+			zap.String("phase", m.phase),
+			zap.Int("patched_results", patched),
+			zap.Int("dropped_results", dropped),
+			zap.Int("messages_before", len(state.Messages)),
+			zap.Int("messages_after", len(out)),
+		)
+	}
+	ns := *state
+	ns.Messages = out
+	return ctx, &ns, nil
+}

internal/multiagent/tool_pair_reconciler_middleware_test.go

@@ -0,0 +1,141 @@
+package multiagent
+
+import (
+	"context"
+	"testing"
+
+	"github.com/cloudwego/eino/adk"
+	"github.com/cloudwego/eino/schema"
+)
+
+func runToolPairReconciler(t *testing.T, msgs []adk.Message) []adk.Message {
+	t.Helper()
+	mw := newToolPairReconcilerMiddleware(nil, "test").(*toolPairReconcilerMiddleware)
+	_, out, err := mw.BeforeModelRewriteState(
+		context.Background(),
+		&adk.ChatModelAgentState{Messages: msgs},
+		&adk.ModelContext{},
+	)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	return out.Messages
+}
+
+func assertCompleteImmediateToolPairs(t *testing.T, msgs []adk.Message) {
+	t.Helper()
+	for i, msg := range msgs {
+		if msg == nil || msg.Role != schema.Assistant || len(msg.ToolCalls) == 0 {
+			continue
+		}
+		want := make(map[string]struct{}, len(msg.ToolCalls))
+		for _, tc := range msg.ToolCalls {
+			if tc.ID == "" {
+				t.Fatal("empty tool call id remained")
+			}
+			if _, duplicate := want[tc.ID]; duplicate {
+				t.Fatalf("duplicate tool call id remained: %s", tc.ID)
+			}
+			want[tc.ID] = struct{}{}
+		}
+		seen := make(map[string]struct{}, len(want))
+		for j := i + 1; j < len(msgs) && msgs[j] != nil && msgs[j].Role == schema.Tool; j++ {
+			id := msgs[j].ToolCallID
+			if _, ok := want[id]; !ok {
+				t.Fatalf("unexpected tool result %q after assistant %d", id, i)
+			}
+			if _, duplicate := seen[id]; duplicate {
+				t.Fatalf("duplicate tool result %q", id)
+			}
+			seen[id] = struct{}{}
+		}
+		if len(seen) != len(want) {
+			t.Fatalf("assistant %d: want %d results, got %d", i, len(want), len(seen))
+		}
+	}
+}
+
+func TestToolPairReconcilerPatchesPartialMultiToolBatch(t *testing.T) {
+	msgs := []adk.Message{
+		schema.UserMessage("start"),
+		assistantToolCallsMsg("", "c1", "c2"),
+		schema.ToolMessage("r1", "c1"),
+		schema.UserMessage("continue"),
+	}
+	out := runToolPairReconciler(t, msgs)
+	assertCompleteImmediateToolPairs(t, out)
+	if len(out) != 5 || out[3].Role != schema.Tool || out[3].ToolCallID != "c2" {
+		t.Fatalf("missing c2 result was not inserted in place: %+v", out)
+	}
+	if out[3].Content != patchedMissingToolResult {
+		t.Fatalf("unexpected patched content: %q", out[3].Content)
+	}
+}
+
+func TestToolPairReconcilerDropsMisplacedDuplicateAndOrphanResults(t *testing.T) {
+	msgs := []adk.Message{
+		schema.ToolMessage("old", "orphan"),
+		assistantToolCallsMsg("", "c1"),
+		schema.ToolMessage("first", "c1"),
+		schema.ToolMessage("duplicate", "c1"),
+		schema.ToolMessage("wrong", "other"),
+		schema.UserMessage("next"),
+		schema.ToolMessage("late", "c1"),
+	}
+	out := runToolPairReconciler(t, msgs)
+	assertCompleteImmediateToolPairs(t, out)
+	toolCount := 0
+	for _, msg := range out {
+		if msg.Role == schema.Tool {
+			toolCount++
+			if msg.Content != "first" || msg.ToolCallID != "c1" {
+				t.Fatalf("unexpected retained tool result: %+v", msg)
+			}
+		}
+	}
+	if toolCount != 1 {
+		t.Fatalf("want one retained tool result, got %d", toolCount)
+	}
+}
+
+func TestToolPairReconcilerRepairsEmptyAndRepeatedCallIDs(t *testing.T) {
+	msgs := []adk.Message{
+		assistantToolCallsMsg("", "", "same"),
+		schema.ToolMessage("same-1", "same"),
+		assistantToolCallsMsg("", "same"),
+		schema.ToolMessage("same-2", "same"),
+	}
+	out := runToolPairReconciler(t, msgs)
+	assertCompleteImmediateToolPairs(t, out)
+	all := make(map[string]struct{})
+	for _, msg := range out {
+		if msg.Role != schema.Assistant {
+			continue
+		}
+		for _, tc := range msg.ToolCalls {
+			if _, duplicate := all[tc.ID]; duplicate {
+				t.Fatalf("global duplicate tool call id remained: %s", tc.ID)
+			}
+			all[tc.ID] = struct{}{}
+		}
+	}
+}
+
+func TestToolPairReconcilerNoOpForValidHistory(t *testing.T) {
+	msgs := []adk.Message{
+		schema.UserMessage("start"),
+		assistantToolCallsMsg("", "c1", "c2"),
+		schema.ToolMessage("r1", "c1"),
+		schema.ToolMessage("r2", "c2"),
+		schema.AssistantMessage("done", nil),
+	}
+	mw := newToolPairReconcilerMiddleware(nil, "test").(*toolPairReconcilerMiddleware)
+	in := &adk.ChatModelAgentState{Messages: msgs}
+	_, out, err := mw.BeforeModelRewriteState(context.Background(), in, &adk.ModelContext{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if out != in {
+		t.Fatal("valid history should use the no-op fast path")
+	}
+}

internal/multiagent/tool_search_result_sanitizer_middleware.go

@@ -0,0 +1,76 @@
+package multiagent
+
+import (
+	"context"
+	"encoding/json"
+	"strings"
+
+	"github.com/cloudwego/eino/adk"
+	"github.com/cloudwego/eino/schema"
+	"go.uber.org/zap"
+)
+
+// toolSearchResultSanitizerMiddleware prevents malformed historical tool_search
+// results (for example an HTML gateway error page) from crashing Eino's dynamic
+// tool loader on every retry. Eino expects every tool_search result to be a JSON
+// object containing selectedTools.
+type toolSearchResultSanitizerMiddleware struct {
+	adk.BaseChatModelAgentMiddleware
+	logger *zap.Logger
+	phase  string
+}
+
+func newToolSearchResultSanitizerMiddleware(logger *zap.Logger, phase string) adk.ChatModelAgentMiddleware {
+	return &toolSearchResultSanitizerMiddleware{logger: logger, phase: phase}
+}
+
+type toolSearchResultEnvelope struct {
+	SelectedTools []string `json:"selectedTools"`
+}
+
+func validToolSearchResult(content string) bool {
+	var result toolSearchResultEnvelope
+	if err := json.Unmarshal([]byte(content), &result); err != nil {
+		return false
+	}
+	// Reject JSON values such as null. They unmarshal without an error but do not
+	// satisfy the object-shaped contract used by the toolsearch middleware.
+	return strings.HasPrefix(strings.TrimSpace(content), "{")
+}
+
+func (m *toolSearchResultSanitizerMiddleware) BeforeModelRewriteState(
+	ctx context.Context,
+	state *adk.ChatModelAgentState,
+	_ *adk.ModelContext,
+) (context.Context, *adk.ChatModelAgentState, error) {
+	if m == nil || state == nil || len(state.Messages) == 0 {
+		return ctx, state, nil
+	}
+
+	var rewritten []adk.Message
+	repaired := 0
+	for i, msg := range state.Messages {
+		if msg == nil || msg.Role != schema.Tool || !IsToolSearchTool(msg.ToolName) || validToolSearchResult(msg.Content) {
+			continue
+		}
+		if rewritten == nil {
+			rewritten = append([]adk.Message(nil), state.Messages...)
+		}
+		clone := *msg
+		clone.Content = `{"selectedTools":[],"_recovered":true,"reason":"invalid historical tool_search result"}`
+		rewritten[i] = &clone
+		repaired++
+	}
+
+	if repaired == 0 {
+		return ctx, state, nil
+	}
+	if m.logger != nil {
+		m.logger.Warn("invalid historical tool_search results repaired before model call",
+			zap.String("phase", m.phase),
+			zap.Int("repaired_count", repaired))
+	}
+	ns := *state
+	ns.Messages = rewritten
+	return ctx, &ns, nil
+}

internal/multiagent/tool_search_result_sanitizer_middleware_test.go

@@ -0,0 +1,56 @@
+package multiagent
+
+import (
+	"context"
+	"testing"
+
+	"github.com/cloudwego/eino/adk"
+	"github.com/cloudwego/eino/schema"
+)
+
+func TestToolSearchResultSanitizerRepairsMalformedHistory(t *testing.T) {
+	good := &schema.Message{Role: schema.Tool, ToolName: "tool_search", Content: `{"selectedTools":["grep"]}`}
+	bad := &schema.Message{Role: schema.Tool, ToolName: "tool_search", Content: "<html>502 Bad Gateway</html>"}
+	other := &schema.Message{Role: schema.Tool, ToolName: "grep", Content: "plain text is valid for other tools"}
+	state := &adk.ChatModelAgentState{Messages: []adk.Message{good, bad, other}}
+
+	mw := newToolSearchResultSanitizerMiddleware(nil, "test")
+	_, got, err := mw.BeforeModelRewriteState(context.Background(), state, nil)
+	if err != nil {
+		t.Fatalf("BeforeModelRewriteState: %v", err)
+	}
+	if got.Messages[0] != good || got.Messages[0].Content != good.Content {
+		t.Fatal("valid tool_search result was unexpectedly changed")
+	}
+	if got.Messages[1] == bad || !validToolSearchResult(got.Messages[1].Content) {
+		t.Fatalf("malformed result was not safely replaced: %q", got.Messages[1].Content)
+	}
+	if got.Messages[2] != other {
+		t.Fatal("non-tool_search result was unexpectedly changed")
+	}
+	if bad.Content != "<html>502 Bad Gateway</html>" {
+		t.Fatal("middleware mutated the original message")
+	}
+}
+
+func TestToolSearchResultSanitizerFastPath(t *testing.T) {
+	msg := &schema.Message{Role: schema.Tool, ToolName: "tool_search", Content: `{"selectedTools":[]}`}
+	state := &adk.ChatModelAgentState{Messages: []adk.Message{msg}}
+	mw := newToolSearchResultSanitizerMiddleware(nil, "test")
+
+	_, got, err := mw.BeforeModelRewriteState(context.Background(), state, nil)
+	if err != nil {
+		t.Fatalf("BeforeModelRewriteState: %v", err)
+	}
+	if got != state {
+		t.Fatal("valid history should use the allocation-free fast path")
+	}
+}
+
+func TestValidToolSearchResultRejectsNonObjectJSON(t *testing.T) {
+	for _, content := range []string{"null", `[]`, `"text"`, `{"selectedTools":"grep"}`} {
+		if validToolSearchResult(content) {
+			t.Fatalf("expected invalid tool_search result: %s", content)
+		}
+	}
+}