magic-agent 1.0.0

package/internal/agent/streamjson.go

@@ -0,0 +1,185 @@
+package agent
+
+// streamjson.go - claude / codebuddy 共用的 stream-json 输入输出（附件走这条路）。
+//
+// 背景（2026-09-17 实测，claude / codebuddy 两家 CLI 同族）：
+//
+//	--input-format stream-json  可以喂「提示词 + 图片 content block」的 user 消息
+//	                            （附件唯一的原生输入通道；两家的 -p 文本模式收不了图）
+//	但它要求 --output-format 也必须是 stream-json，所以收尾正文要从
+//	NDJSON 的 result 行里取 —— 于是非流式（Complete）在**有附件时**也得跑这条协议。
+//
+// 本文件把「喂 stdin + 归约 NDJSON」抽成一份，claude/codebuddy 各自复用，
+// 免得两家各写一套解析（历史上两份实现漂移过一次，见 magic-test 的 agent-cli 注释）。
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"strings"
+)
+
+// streamJSONResult 两家 CLI 收尾行（type=result）的公共形状。
+type streamJSONResult struct {
+	Type      string `json:"type"`
+	Subtype   string `json:"subtype"`
+	IsError   bool   `json:"is_error"`
+	Result    string `json:"result"`
+	SessionID string `json:"session_id"`
+	Model     string `json:"model"`
+}
+
+// runStreamJSONIn 跑一次 stream-json 调用：增量喂给 acc，收尾行填进 fin。
+// 返回是否见到了 result 行（未见 = 协议没跑完，调用方按错误处理）。
+//
+// stdin 为 nil 时不喂 stdin（提示词走命令行位置参数）。每见到一次 result 行，
+// 除填 fin 外还会向调用方发一个 KindTurnEnd 事件 —— 常驻会话（Request.Append）
+// 靠它判断「这轮做完了，可以继续追加」。
+func runStreamJSONIn(
+	ctx context.Context, dir string, extraEnv []string, bin string, args []string,
+	stdin io.Reader, acc *streamAccumulator, fin *streamJSONResult,
+) (bool, error) {
+	seen := false
+	err := runStreamCLIStdinReaderIn(ctx, dir, extraEnv, bin, args, stdin, func(line string) error {
+		isResult, perr := acc.handleNDJSONLine(line)
+		if perr != nil {
+			return perr
+		}
+		if isResult {
+			_ = json.Unmarshal([]byte(line), fin)
+			seen = true
+			// 轮次边界事件（Text = 该轮最终正文，SessionID = 该轮会话 id）。
+			// ⚠️ 它必须带 session_id：常驻会话的最终 result 信封要等会话结束才输出
+			//（默认空闲 5m），调用方要靠这一条把会话锚点绑上（见 StreamEvent.SessionID）。
+			acc.emitTurnEnd(fin.Result, fin.SessionID)
+		}
+		return nil
+	})
+	return seen, err
+}
+
+// streamJSONInputPipe 常驻会话的 stdin：先写首条 user 消息（提示词 + 附件），
+// 之后每从 appendCh 收到一条就再写一轮；appendCh 关闭 → 关掉写端 → 子进程收尾。
+//
+// 返回的 reader 交给子进程当 stdin（不 EOF 就一直活着）。写失败（子进程已退）时
+// 直接收摊，不让 goroutine 泄漏。
+func streamJSONInputPipe(prompt string, atts []Attachment, appendCh <-chan string) (io.Reader, error) {
+	first, err := streamJSONUserLine(prompt, atts)
+	if err != nil {
+		return nil, err
+	}
+	pr, pw := io.Pipe()
+	go func() {
+		defer pw.Close()
+		if _, err := pw.Write([]byte(first)); err != nil {
+			return
+		}
+		for msg := range appendCh {
+			line, lerr := streamJSONUserLine(msg, nil)
+			if lerr != nil {
+				continue // 追加内容构造失败（不该发生）：跳过这一条，别把整个会话带崩
+			}
+			if _, err := pw.Write([]byte(line)); err != nil {
+				return
+			}
+		}
+	}()
+	return pr, nil
+}
+
+// streamJSONUserLine 把「提示词 + 附件」拼成一行 stream-json 输入（含结尾换行）。
+//
+// content 块顺序：图片附件（image block）在前、提示词文本在后 —— 与官方
+// 多模态示例一致（图先给，问题随后）。**非图片**附件没有对应的 content 类型，
+// 只能把绝对路径追加进文本（与 trae/openclaw 的兜底同一语义）。
+func streamJSONUserLine(prompt string, atts []Attachment) (string, error) {
+	blocks := make([]map[string]any, 0, len(atts)+1)
+	var nonImage []Attachment
+	for _, a := range atts {
+		if !a.IsImage() {
+			nonImage = append(nonImage, a)
+			continue
+		}
+		data, err := readAttachmentBase64(a)
+		if err != nil {
+			return "", err
+		}
+		mime := a.MIME
+		if mime == "" {
+			mime = "image/png"
+		}
+		blocks = append(blocks, map[string]any{
+			"type":   "image",
+			"source": map[string]any{"type": "base64", "media_type": mime, "data": data},
+		})
+	}
+	text := appendAttachmentSection(prompt, nonImage)
+	blocks = append(blocks, map[string]any{"type": "text", "text": text})
+
+	msg := map[string]any{
+		"type":    "user",
+		"message": map[string]any{"role": "user", "content": blocks},
+	}
+	raw, err := json.Marshal(msg)
+	if err != nil {
+		return "", err
+	}
+	return string(raw) + "\n", nil
+}
+
+// hasImageAttachment 是否含图片附件（决定要不要走 stream-json 输入通道）。
+func hasImageAttachment(atts []Attachment) bool {
+	for _, a := range atts {
+		if a.IsImage() {
+			return true
+		}
+	}
+	return false
+}
+
+// setArgValue 把 args 里 <flag> 的下一个值改成 want（找不到就追加 <flag> want）。
+// claude/codebuddy 的 --output-format json → stream-json 就靠它。
+func setArgValue(args []string, flag, want string) []string {
+	for i := 0; i < len(args)-1; i++ {
+		if args[i] == flag {
+			args[i+1] = want
+			return args
+		}
+	}
+	return append(args, flag, want)
+}
+
+// finalizeStreamText 取最终正文：优先收尾行的 result，其次增量拼接。
+func finalizeStreamText(fin streamJSONResult, acc *streamAccumulator) string {
+	if t := strings.TrimSpace(fin.Result); t != "" {
+		return t
+	}
+	return strings.TrimSpace(acc.Text.String())
+}
+
+// streamJSONArgs 把「文本模式」的 args 改造成 stream-json 输入模式：
+//
+//	去掉末尾的位置参数（提示词走 stdin，不再作为命令行参数）
+//	--output-format → stream-json
+//	追加 --input-format stream-json --verbose（+ stream 模式下再加 --include-partial-messages）
+func streamJSONArgs(baseArgs []string, prompt string, streaming bool) []string {
+	args := make([]string, 0, len(baseArgs))
+	for _, a := range baseArgs {
+		if a == prompt { // 末尾的位置参数就是提示词，排除掉
+			continue
+		}
+		args = append(args, a)
+	}
+	args = setArgValue(args, "--output-format", "stream-json")
+	args = append(args, "--input-format", "stream-json", "--verbose")
+	if streaming {
+		args = append(args, "--include-partial-messages")
+	}
+	return args
+}
+
+// errEmptyStreamContent 两家在 stream-json 收尾为空时的公共错误。
+func errEmptyStreamContent(label string) error {
+	return fmt.Errorf("%s CLI returned empty result", label)
+}

package/internal/agent/tags.go

@@ -0,0 +1,52 @@
+package agent
+
+// tags.go - 思维链标签常量与剥离逻辑。
+//
+// 部分推理模型（MiniMax-M3 等）经 simonw/llm CLI 输出时，思维链以
+// 标签形式直接混在正文里。本文件提供：
+//
+//	thinkOpenTag / thinkCloseTag  标签常量（运行时值）
+//	stripThinkingTags             非流式剥离（正文里删掉标签块）
+//	splitThinkingTags             非流式拆分（正文、思维链都要）— 在 llmengine.go
+//
+// ⚠️ 标签常量必须分段拼接，不能写成连续字面量 —— 该标签 token 序列会被
+// 某些分词器当作特殊 token 并在写盘时改写（实测被替换成全角竖线形式，
+// 长度从 8 变 19），导致源码里的标签与实际字符串不符、Index 偏移错位。
+// 分段拼接后运行时值不变，但源码中不出现该 token 序列。
+
+import "strings"
+
+// 思维链标签的构造片段（分段拼接，见文件头说明）。
+const (
+	tagLT    = "<"
+	tagGT    = ">"
+	tagSlash = "/"
+	tagWord  = "think"
+)
+
+// thinkOpenTag / thinkCloseTag 运行时值为思维链的开始/结束标签。
+var (
+	thinkOpenTag  = tagLT + tagWord + tagGT
+	thinkCloseTag = tagLT + tagSlash + tagWord + tagGT
+)
+
+// stripThinkingTags 剥离正文中残留的思维链标签块，返回剩余正文。
+// 有开标签无闭标签时，开标签之后的残余整段丢弃（视为未完成的思考）。
+func stripThinkingTags(s string) string {
+	for {
+		i := strings.Index(s, thinkOpenTag)
+		if i < 0 {
+			break
+		}
+		rest := s[i+len(thinkOpenTag):]
+		j := strings.Index(rest, thinkCloseTag)
+		if j < 0 {
+			// 有开无闭：整段视为未完成的思考，丢弃。
+			s = s[:i]
+			break
+		}
+		// 相对 rest 切片，避免绝对/相对偏移混算。
+		s = s[:i] + rest[j+len(thinkCloseTag):]
+	}
+	return strings.TrimSpace(s)
+}

package/internal/agent/toolkind.go

@@ -0,0 +1,96 @@
+package agent
+
+import "strings"
+
+/* 工具调用的**子形态**（tool kind）—— 由归一化层判定，渲染层不再靠工具名猜。
+ *
+ * ── 为什么要有它 ──
+ * 客户端要按形态给不同的卡：命令、文件变更、网页检索、MCP、子代理、提问授权、通用。
+ * 此前只能在**渲染层按工具名猜**（见 magic-test 的 qaFileChangeOf(u.name, uo)），
+ * 于是每接一个新引擎就漏一批名字，同一个名字在不同引擎里含义还会漂，
+ * 两个界面（旧工作台 / PC 基础对话 UI）各猜一套，必然越走越远。
+ * 放在归一化层 = **一处判定**，SSE 流与会话日志两条通道同时带上，两边共用同一份。
+ *
+ * ── 取值为什么是这几个词 ──
+ * 刻意对齐 agents-anywhere 的 `ToolContentKind`（connector/connector/runtime_protocol/timeline.py）：
+ * 同一样东西在两个界面上说同一个词，才有「统一」可言。
+ */
+
+const (
+	// ToolKindCommand 执行命令（Bash / shell / exec 一类）。
+	ToolKindCommand = "command"
+	// ToolKindFileChange 改动文件（Edit / Write / apply_patch 一类）。
+	ToolKindFileChange = "file_change"
+	// ToolKindWebSearch 联网检索或抓取网页。
+	ToolKindWebSearch = "web_search"
+	// ToolKindMCP MCP 服务器提供的工具（名字通常带 `mcp__` 前缀）。
+	ToolKindMCP = "mcp"
+	// ToolKindAgentCall 派子代理（Task / Agent 一类，主会话里会渲染成委派卡）。
+	ToolKindAgentCall = "agent_call"
+	// ToolKindInputRequest 向用户提问、要输入（AskUserQuestion 一类，会渲染成提问卡）。
+	ToolKindInputRequest = "input_request"
+	// ToolKindPermission 请求授权（权限确认那一类，会渲染成审批卡）。
+	ToolKindPermission = "permission"
+	// ToolKindToolCall 其余**已知**工具（读文件 / 列目录 / 待办…）。
+	//
+	// ⚠️ 认不出来也归这里，**不归 unknown** —— 与 anywhere 的 claude projector 一致
+	//（未知工具名 → 通用 ToolCallContent）：它是「有一次工具调用但形态未细分」，
+	// 不是「不知道这是什么事件」。unknown 留给连工具名都没有的情况。
+	ToolKindToolCall = "tool_call"
+	// ToolKindUnknown 连名字都没有，无法判定形态。
+	ToolKindUnknown = "unknown"
+)
+
+// 名字 → 形态。全部小写、无命名空间前缀。
+// 覆盖本仓库已接的引擎：claude / codebuddy（Bash、Edit、Read、Task…）、
+// codex（command_execution、apply_patch…）、openclaw / trae（namespace.tool 形状，已剥前缀）。
+var toolKindByName = map[string]string{
+	// 执行命令
+	"bash": ToolKindCommand, "shell": ToolKindCommand, "sh": ToolKindCommand,
+	"exec": ToolKindCommand, "execute": ToolKindCommand, "run": ToolKindCommand,
+	"command": ToolKindCommand, "command_execution": ToolKindCommand,
+	"bashoutput": ToolKindCommand, "killshell": ToolKindCommand, "terminal": ToolKindCommand,
+	"local_shell": ToolKindCommand, "run_command": ToolKindCommand,
+	// 改动文件
+	"edit": ToolKindFileChange, "write": ToolKindFileChange, "multiedit": ToolKindFileChange,
+	"notebookedit": ToolKindFileChange, "apply_patch": ToolKindFileChange,
+	"str_replace_editor": ToolKindFileChange, "str_replace": ToolKindFileChange,
+	"create_file": ToolKindFileChange, "write_file": ToolKindFileChange,
+	"edit_file": ToolKindFileChange, "patch": ToolKindFileChange,
+	// 联网
+	"websearch": ToolKindWebSearch, "web_search": ToolKindWebSearch,
+	"webfetch": ToolKindWebSearch, "web_fetch": ToolKindWebSearch,
+	"fetch": ToolKindWebSearch, "browser": ToolKindWebSearch,
+	// 子代理
+	"task": ToolKindAgentCall, "agent": ToolKindAgentCall, "subagent": ToolKindAgentCall,
+	"delegate": ToolKindAgentCall,
+	// 提问 / 要输入
+	"askuserquestion": ToolKindInputRequest, "ask_user_question": ToolKindInputRequest,
+	"elicit": ToolKindInputRequest, "input_request": ToolKindInputRequest,
+	// 授权
+	"permission": ToolKindPermission, "can_use_tool": ToolKindPermission,
+	"askpermission": ToolKindPermission, "approve": ToolKindPermission,
+}
+
+// ToolKindFor 判定一次工具调用的子形态。name 是引擎给的工具名；args 暂未参与判定
+// （留作后续细分，例如按命令内容区分只读查询与写操作）。认不出来的名字归 `tool_call`。
+func ToolKindFor(name, args string) string {
+	_ = args // 预留：形态细分仍可能要看参数，先固定签名免得调用点来回改
+	n := strings.ToLower(strings.TrimSpace(name))
+	if n == "" {
+		return ToolKindUnknown
+	}
+	// MCP 的名字带命名空间前缀（`mcp__github__create_issue` / `mcp.github.x`），先认它，
+	// 否则会被下面剥前缀的动作毁掉线索。
+	if strings.HasPrefix(n, "mcp__") || strings.HasPrefix(n, "mcp.") {
+		return ToolKindMCP
+	}
+	// 其余命名空间形状（trae / openclaw 会给 `namespace.tool`）剥掉前缀再查表。
+	if i := strings.LastIndex(n, "."); i >= 0 && i < len(n)-1 {
+		n = n[i+1:]
+	}
+	if k, ok := toolKindByName[n]; ok {
+		return k
+	}
+	return ToolKindToolCall
+}

package/internal/agent/toolkind_test.go

@@ -0,0 +1,70 @@
+package agent
+
+import "testing"
+
+/* 这份表就是「形态判定」的契约。改它等于改两个界面的渲染分支，别顺手改。 */
+func TestToolKindFor(t *testing.T) {
+	cases := []struct {
+		name string
+		want string
+	}{
+		// 执行命令（claude / codebuddy / codex / openclaw 各自的名字）
+		{"Bash", ToolKindCommand},
+		{"bash", ToolKindCommand},
+		{"command", ToolKindCommand},
+		{"command_execution", ToolKindCommand},
+		{"BashOutput", ToolKindCommand},
+		{"KillShell", ToolKindCommand},
+		{"terminal", ToolKindCommand},
+		// 改动文件
+		{"Edit", ToolKindFileChange},
+		{"Write", ToolKindFileChange},
+		{"MultiEdit", ToolKindFileChange},
+		{"NotebookEdit", ToolKindFileChange},
+		{"apply_patch", ToolKindFileChange},
+		{"str_replace_editor", ToolKindFileChange},
+		// 联网
+		{"WebSearch", ToolKindWebSearch},
+		{"WebFetch", ToolKindWebSearch},
+		{"web_search", ToolKindWebSearch},
+		// MCP：带命名空间前缀，且**不能**被剥前缀那一步吃掉
+		{"mcp__github__create_issue", ToolKindMCP},
+		{"mcp.github.create_issue", ToolKindMCP},
+		{"MCP__filesystem__read", ToolKindMCP},
+		// 子代理
+		{"Task", ToolKindAgentCall},
+		{"Agent", ToolKindAgentCall},
+		// 提问 / 授权
+		{"AskUserQuestion", ToolKindInputRequest},
+		{"can_use_tool", ToolKindPermission},
+		// 命名空间形状（trae / openclaw）：剥前缀后仍要查得出来
+		{"builtin.Bash", ToolKindCommand},
+		{"tools.Edit", ToolKindFileChange},
+		{"acp.Task", ToolKindAgentCall},
+		// 已知但未细分的工具 → tool_call（对齐 anywhere 的通用 ToolCallContent）
+		{"Read", ToolKindToolCall},
+		{"Glob", ToolKindToolCall},
+		{"Grep", ToolKindToolCall},
+		{"TodoWrite", ToolKindToolCall},
+		{"exit_plan_mode", ToolKindToolCall},
+		// 从没见过的名字也归 tool_call，**不是** unknown
+		{"some_brand_new_tool", ToolKindToolCall},
+		// 连名字都没有 → unknown
+		{"", ToolKindUnknown},
+		{"   ", ToolKindUnknown},
+	}
+	for _, c := range cases {
+		if got := ToolKindFor(c.name, ""); got != c.want {
+			t.Errorf("ToolKindFor(%q) = %q, want %q", c.name, got, c.want)
+		}
+	}
+}
+
+/* 名字大小写与前后空格不该影响判定（引擎给的名字大小写并不统一）。 */
+func TestToolKindForNormalizesName(t *testing.T) {
+	for _, n := range []string{"  Bash  ", "BASH", "bAsH"} {
+		if got := ToolKindFor(n, ""); got != ToolKindCommand {
+			t.Errorf("ToolKindFor(%q) = %q, want %q", n, got, ToolKindCommand)
+		}
+	}
+}

package/internal/agent/tools_suffix_test.go

@@ -0,0 +1,261 @@
+package agent
+
+// tools_suffix_test.go - 「工具启用无效」回归测试。
+//
+// 背景：noToolSuffix 明文写着「严禁使用任何工具」。此前 codebuddy / trae
+// 无条件把它注入 system prompt，导致 --tools on / 白名单模式下 CLI 侧
+// 工具已开、system prompt 却在压制模型调用，表现为「启用了工具但没有
+// 网络搜索」。
+//
+// 正确语义：off 模式注入（防「伪工具调用」），on / 白名单模式**不注入**。
+
+import (
+	"context"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// argLogger 造一个记录参数的假 CLI，返回 (引擎可用的 cli 路径, 读取参数函数)。
+func argLogger(t *testing.T) (string, func() string) {
+	t.Helper()
+	dir := t.TempDir()
+	log := filepath.Join(dir, "args.log")
+	cli := filepath.Join(dir, "fake")
+	script := "#!/bin/sh\nprintf '%s\\n' \"$*\" > " + log +
+		"\necho '{\"type\":\"result\",\"result\":\"ok\"}'\n"
+	if err := os.WriteFile(cli, []byte(script), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	return cli, func() string {
+		b, _ := os.ReadFile(log)
+		return string(b)
+	}
+}
+
+func TestCodeBuddyToolModeSuffixMatrix(t *testing.T) {
+	cases := []struct {
+		name        string
+		tools       ToolsMode
+		wantSuffix  bool
+		wantToolArg []string // 必须出现的参数对
+		absentArg   []string // 必须不出现的参数
+	}{
+		{
+			name:        "off 注入约束且禁工具",
+			tools:       ToolsOff,
+			wantSuffix:  true,
+			wantToolArg: []string{"--tools", ""},
+		},
+		{
+			name:       "on 不注入约束（否则工具被压制）",
+			tools:      ToolsOn,
+			wantSuffix: false,
+			absentArg:  []string{"[约束]"},
+		},
+		{
+			name:       "allowlist 不注入约束且带上白名单",
+			tools:      ToolsAllowlist([]string{"WebSearch", "WebFetch"}),
+			wantSuffix: false,
+			absentArg:  []string{"[约束]"},
+		},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			cli, argsOf := argLogger(t)
+			e := &CodeBuddyEngine{BinPath: cli}
+			if _, err := e.Complete(context.Background(), Request{
+				Tools:    tc.tools,
+				Messages: []Message{{Role: "user", Content: "hi"}},
+			}); err != nil {
+				t.Fatalf("Complete: %v", err)
+			}
+			args := argsOf()
+
+			if got := strings.Contains(args, "[约束]"); got != tc.wantSuffix {
+				t.Errorf("noToolSuffix 注入 = %v, want %v\nargs=%q", got, tc.wantSuffix, args)
+			}
+			for _, a := range tc.wantToolArg {
+				if a == "" {
+					if !strings.Contains(args, "--tools ") {
+						t.Errorf("缺少 --tools 参数: %q", args)
+					}
+					continue
+				}
+				if !strings.Contains(args, a) {
+					t.Errorf("缺少参数 %q: %q", a, args)
+				}
+			}
+			for _, a := range tc.absentArg {
+				if strings.Contains(args, a) {
+					t.Errorf("不应包含 %q: %q", a, args)
+				}
+			}
+			// 白名单模式下白名单工具名必须出现
+			if tc.name == "allowlist 不注入约束且带上白名单" {
+				if !strings.Contains(args, "WebSearch") {
+					t.Errorf("白名单工具名未传入: %q", args)
+				}
+			}
+		})
+	}
+}
+
+func TestTraeToolModeSuffix(t *testing.T) {
+	cases := []struct {
+		name       string
+		tools      ToolsMode
+		wantSuffix bool
+	}{
+		{"off 注入约束", ToolsOff, true},
+		{"on 不注入约束", ToolsOn, false},
+		{"allowlist 不注入约束", ToolsAllowlist([]string{"Bash"}), false},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			cli, argsOf := argLogger(t)
+			e := &TraeEngine{BinPath: cli}
+			if _, err := e.Complete(context.Background(), Request{
+				Tools:    tc.tools,
+				Messages: []Message{{Role: "user", Content: "hi"}},
+			}); err != nil {
+				t.Fatalf("Complete: %v", err)
+			}
+			args := argsOf()
+			if got := strings.Contains(args, "[约束]"); got != tc.wantSuffix {
+				t.Errorf("noToolSuffix = %v, want %v\nargs=%q", got, tc.wantSuffix, args)
+			}
+		})
+	}
+}
+
+// TestTraeToolModeMapping 固化 trae 的工具模式契约（2026-09-16 真机验证）。
+//
+// trae-cli 的权限开关实测语义：
+//   - --allowed-tool 只做「自动批准」，不裁剪工具集（--allowed-tool WebFetch
+//     仍下发全部 18 个工具）；
+//   - --disallowed-tool 才真正做减法；
+//   - -y 跳过全部权限检查 ⇒ 全工具可用。
+//
+// 因此白名单模式在 trae 上定义为「默认开启所有工具」：走 -y 全放行，
+// 不再输出 --allowed-tool（它既不能收窄，全放行后也毫无作用，只会造成
+// 「allowlist 被 -y 架空」的错觉）。
+func TestTraeToolModeMapping(t *testing.T) {
+	cases := []struct {
+		name         string
+		tools        ToolsMode
+		wantArgs     []string
+		absentArgs   []string
+		wantDisallow bool // 是否出现任何 --disallowed-tool
+	}{
+		{
+			name:         "off 逐个真名禁用且不全放行",
+			tools:        ToolsOff,
+			wantArgs:     []string{"Bash", "Edit", "Write", "Glob", "Grep", "Read"},
+			absentArgs:   []string{"-y", "Replace"},
+			wantDisallow: true,
+		},
+		{
+			name:         "on 全放行不做减法",
+			tools:        ToolsOn,
+			wantArgs:     []string{"-y"},
+			wantDisallow: false,
+		},
+		{
+			name:         "allowlist 默认开启所有工具（全放行、不收窄）",
+			tools:        ToolsAllowlist([]string{"WebFetch", "Bash"}),
+			wantArgs:     []string{"-y"},
+			absentArgs:   []string{"--allowed-tool"},
+			wantDisallow: false,
+		},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			cli, argsOf := argLogger(t)
+			e := &TraeEngine{BinPath: cli}
+			if _, err := e.Complete(context.Background(), Request{
+				Tools:    tc.tools,
+				Messages: []Message{{Role: "user", Content: "hi"}},
+			}); err != nil {
+				t.Fatalf("Complete: %v", err)
+			}
+			args := argsOf()
+
+			for _, a := range tc.wantArgs {
+				if !hasArgToken(args, a) {
+					t.Errorf("缺少参数 %q: %q", a, args)
+				}
+			}
+			for _, a := range tc.absentArgs {
+				if strings.Contains(args, a) {
+					t.Errorf("不应包含 %q: %q", a, args)
+				}
+			}
+			// off 必须逐个用 --disallowed-tool 列出真名；on/白名单必须是纯全放行。
+			gotDisallow := strings.Contains(args, "--disallowed-tool")
+			if gotDisallow != tc.wantDisallow {
+				t.Errorf("--disallowed-tool 出现 = %v, want %v\nargs=%q", gotDisallow, tc.wantDisallow, args)
+			}
+			if tc.wantDisallow {
+				for _, a := range traeOffDisableTools {
+					if !strings.Contains(args, "--disallowed-tool "+a) {
+						t.Errorf("off 模式漏禁 %q: %q", a, args)
+					}
+				}
+			}
+		})
+	}
+}
+
+// hasArgToken 判断命令行里是否出现某个完整参数（避免 "-y" 被别的串误命中）。
+func hasArgToken(args, want string) bool {
+	for _, f := range strings.Fields(args) {
+		if f == want {
+			return true
+		}
+	}
+	return false
+}
+
+// nil ToolsMode 必须按 off 处理（默认关工具，向后兼容）。
+func TestToolsIsOffDefaultsToOff(t *testing.T) {
+	if !toolsIsOff(Request{}) {
+		t.Error("空 Tools 应视为 off")
+	}
+	if toolsIsOff(Request{Tools: ToolsOn}) {
+		t.Error("ToolsOn 不应判定为 off")
+	}
+	if toolsIsOff(Request{Tools: ToolsAllowlist([]string{"Read"})}) {
+		t.Error("白名单不应判定为 off")
+	}
+}
+
+// noToolSuffix 必须显式禁止「伪造工具返回」。
+//
+// 背景：off 模式下模型被要求「输出工具抓到的内容」时会编造返回体
+// （实测约 1/6），仅禁「调用工具」堵不住，必须有一条明文禁止伪造。
+func TestNoToolSuffixForbidsFabricatedToolOutput(t *testing.T) {
+	if !strings.Contains(noToolSuffix, "伪造工具返回") {
+		t.Errorf("noToolSuffix 缺少「禁止伪造工具返回」约束: %q", noToolSuffix)
+	}
+	// 该约束要能经 FlattenPrompt 落到 system prompt 里。
+	got := FlattenPrompt("你是助手", nil, true)
+	if !strings.Contains(got, "伪造工具返回") {
+		t.Errorf("伪造工具返回约束未进入 prompt: %q", got)
+	}
+	// 且 off 模式下 codebuddy 参数里能看到。
+	cli, argsOf := argLogger(t)
+	e := &CodeBuddyEngine{BinPath: cli}
+	if _, err := e.Complete(context.Background(), Request{
+		Tools:    ToolsOff,
+		Messages: []Message{{Role: "user", Content: "hi"}},
+	}); err != nil {
+		t.Fatalf("Complete: %v", err)
+	}
+	if !strings.Contains(argsOf(), "伪造工具返回") {
+		t.Errorf("codebuddy off 模式 args 未带伪造约束: %q", argsOf())
+	}
+}