magic-agent 1.0.3 → 1.0.49

package/internal/agent/arkclaw_stream_test.go

@@ -43,6 +43,68 @@ func arkClawWorkingFrame(contextID string) string {
 		`"history":[]}}`, contextID)
 }
 
+// arkClawSplit 把事件按 kind 拆成「正文增量」与「轮次边界」两组。
+//
+// 为什么测试不能直接 len(events)：completed 帧收尾会多发一条 KindTurnEnd
+// （带权威全文，status=final），它**不是**又一段正文。收齐所有 ev.Text 再拼会
+// 把 final 全文重复算进增量（与 codebuddy-gateway 改测试时踩的同一个坑）。
+// 同理，turn_end 不能触发 AppendSupportOf 的 keep-alive 收工 —— arkclaw 不在名单里。
+func arkClawSplit(events *[]StreamEvent) (texts []StreamEvent, ends []StreamEvent) {
+	for _, ev := range *events {
+		switch ev.Kind {
+		case KindText:
+			texts = append(texts, ev)
+		case KindTurnEnd:
+			ends = append(ends, ev)
+		}
+	}
+	return texts, ends
+}
+
+// arkClawSplitFailed 与 arkClawSplit 同构，但收的是**异常终态** turn_failed。
+// 单独一个入口是为了让「截断/失败」用例不必记住第三种 kind 的存在 ——
+// 终态只有两种（turn_end 成功 / turn_failed 异常），正文永远只是 turn。
+func arkClawSplitFailed(events *[]StreamEvent) (texts []StreamEvent, failed []StreamEvent) {
+	for _, ev := range *events {
+		switch ev.Kind {
+		case KindText:
+			texts = append(texts, ev)
+		case KindTurnFailed:
+			failed = append(failed, ev)
+		}
+	}
+	return texts, failed
+}
+
+// assertArkClawFinal 断言 turn_end 承担了 final：挂在正文 item 上、revision 更高、
+// 正文是权威全文。与 gateway / claude 同一约定。
+func assertArkClawFinal(t *testing.T, texts, ends []StreamEvent, wantFinal string) {
+	t.Helper()
+	if len(texts) == 0 {
+		t.Fatal("缺少正文事件")
+	}
+	if len(ends) != 1 {
+		t.Fatalf("turn_end 事件数 = %d，want 1", len(ends))
+	}
+	end := ends[0]
+	if end.Status != StatusFinal {
+		t.Errorf("turn_end.Status = %q want %q", end.Status, StatusFinal)
+	}
+	if end.Text != wantFinal {
+		t.Errorf("turn_end.Text = %q want 权威全文 %q", end.Text, wantFinal)
+	}
+	if end.ItemID != texts[0].ItemID {
+		t.Errorf("turn_end 应挂在正文 item 上：%q vs %q", end.ItemID, texts[0].ItemID)
+	}
+	if end.ItemRevision <= texts[len(texts)-1].ItemRevision {
+		t.Errorf("turn_end revision 必须更高：正文末帧=%d turn_end=%d",
+			texts[len(texts)-1].ItemRevision, end.ItemRevision)
+	}
+	if end.ItemID == "" {
+		t.Error("turn_end 缺 item_id（状态收敛字段为空）")
+	}
+}
+
 // arkClawArtifactFrame 组一个把正文挂在 artifacts 上的帧（网关将来吐增量时的形态）。
 func arkClawArtifactFrame(state, contextID, text string) string {
 	return fmt.Sprintf(`{"jsonrpc":"2.0","id":"req-1","result":{"kind":"task","id":"task-1",`+
@@ -102,13 +164,16 @@ func TestArkClawStreamSSECompleted(t *testing.T) {
 		t.Errorf("method = %q want message/stream", sent.Method)
 	}
 
-	// 事件：working 帧**不发事件**（网关没有增量可发），completed 帧发一条正文增量。
-	if len(*events) != 1 {
-		t.Fatalf("事件数 = %d want 1: %+v", len(*events), *events)
+	// 事件：working 帧**不发事件**（网关没有增量可发），completed 帧发一条正文增量，
+	// 收尾多发一条 turn_end（final，不是又一段正文 —— 见 arkClawSplit）。
+	texts, ends := arkClawSplit(events)
+	if len(texts) != 1 {
+		t.Fatalf("正文增量数 = %d want 1: %+v", len(texts), *events)
 	}
-	if ev := (*events)[0]; ev.Kind != KindText || ev.Text != text {
+	if ev := texts[0]; ev.Kind != KindText || ev.Text != text {
 		t.Errorf("事件 = %+v want KindText/%q", ev, text)
 	}
+	assertArkClawFinal(t, texts, ends, text)
 
 	if res.Text != text {
 		t.Errorf("Text = %q", res.Text)
@@ -136,8 +201,8 @@ func TestArkClawStreamSkipsHeartbeatAndNonDataLines(t *testing.T) {
 	if err != nil {
 		t.Fatalf("Stream: %v", err)
 	}
-	if len(*events) != 1 || (*events)[0].Text != "正文" {
-		t.Errorf("事件 = %+v want 单条正文", *events)
+	if texts, _ := arkClawSplit(events); len(texts) != 1 || texts[0].Text != "正文" {
+		t.Errorf("正文增量 = %+v want 单条正文", texts)
 	}
 	if res.Text != "正文" {
 		t.Errorf("Text = %q", res.Text)
@@ -160,8 +225,10 @@ func TestArkClawStreamDedupWhenArtifactsRepeat(t *testing.T) {
 	if err != nil {
 		t.Fatalf("Stream: %v", err)
 	}
-	if len(*events) != 1 {
-		t.Fatalf("事件数 = %d want 1（同一份正文不得发两次）: %+v", len(*events), *events)
+	// 正文只发一次（status.message 与 artifacts 同文，去重后差量为空）；
+	// 收尾的 turn_end 不算正文，见 arkClawSplit。
+	if texts, _ := arkClawSplit(events); len(texts) != 1 {
+		t.Fatalf("正文增量数 = %d want 1（同一份正文不得发两次）: %+v", len(texts), *events)
 	}
 	if res.Text != "同一份正文" {
 		t.Errorf("Text = %q", res.Text)
@@ -182,12 +249,16 @@ func TestArkClawStreamForwardsArtifactIncrements(t *testing.T) {
 	if err != nil {
 		t.Fatalf("Stream: %v", err)
 	}
-	if len(*events) != 2 {
-		t.Fatalf("事件数 = %d want 2: %+v", len(*events), *events)
+	// 正文两条增量（第一段 / 第二段），completed 帧的整段前缀去重后无新增。
+	// turn_end 单独承担轮次边界，不计入增量。
+	texts, ends := arkClawSplit(events)
+	if len(texts) != 2 {
+		t.Fatalf("正文增量数 = %d want 2: %+v", len(texts), *events)
 	}
-	if (*events)[0].Text != "第一段" || (*events)[1].Text != "第二段" {
-		t.Errorf("增量 = %q / %q", (*events)[0].Text, (*events)[1].Text)
+	if texts[0].Text != "第一段" || texts[1].Text != "第二段" {
+		t.Errorf("增量 = %q / %q", texts[0].Text, texts[1].Text)
 	}
+	assertArkClawFinal(t, texts, ends, "第一段第二段")
 	if res.Text != "第一段第二段" {
 		t.Errorf("Text = %q", res.Text)
 	}
@@ -256,9 +327,13 @@ func TestArkClawStreamJSONSchemaPostProcess(t *testing.T) {
 	if err := json.Unmarshal([]byte(res.Text), &out); err != nil {
 		t.Fatalf("Text 不是纯 JSON: %v (%q)", err, res.Text)
 	}
-	if len(*events) != 1 || (*events)[0].Text != res.Text {
+	// 增量正文（已 JSONSchema 抽取）必须与收尾正文逐字节相同。
+	// 注意别把 turn_end 的权威全文当成第二段增量算进来。
+	texts, ends := arkClawSplit(events)
+	if len(texts) != 1 || texts[0].Text != res.Text {
 		t.Errorf("增量应与收尾正文一致: events=%+v text=%q", *events, res.Text)
 	}
+	assertArkClawFinal(t, texts, ends, res.Text)
 }
 
 // ---------- 错误路径 ----------
@@ -395,8 +470,15 @@ func TestArkClawStreamNonSSEFallback(t *testing.T) {
 	if res.Text != "一次性正文" || res.SessionID != "ctx-f1" {
 		t.Errorf("res = %+v", res.Response)
 	}
-	if len(*events) != 1 || (*events)[0].Text != "一次性正文" {
-		t.Errorf("事件 = %+v want 单条正文", *events)
+	// 回退路径同样有状态收敛：整段正文一条 text + 一条 turn_end(final)，
+	// 且 item id 取 task id（与 SSE 路径同源，见 arkClawTaskID 的注释）。
+	texts, ends := arkClawSplit(events)
+	if len(texts) != 1 || texts[0].Text != "一次性正文" {
+		t.Errorf("正文增量 = %+v want 单条正文", texts)
+	}
+	assertArkClawFinal(t, texts, ends, "一次性正文")
+	if !strings.HasPrefix(texts[0].ItemID, "arkclaw_msg_") || strings.Contains(texts[0].ItemID, "local_") {
+		t.Errorf("回退路径应沿用原生 task id 而非降级序号: %q", texts[0].ItemID)
 	}
 	if !strings.Contains(buf.String(), "SSE") {
 		t.Errorf("回退应在 stderr 说明原因: %q", buf.String())

package/internal/agent/arkclaw_test.go

@@ -659,10 +659,10 @@ func TestArkClawNoModelNoWarning(t *testing.T) {
 
 func TestDefaultArkClawTimeoutCoversObservedLatency(t *testing.T) {
 	// 实测短问答 8~23s，但**带工具循环的长任务**要 5 分钟（2026-09-24：「生成周报」304s 才回，
-	// 期间每 15s 一个 working 心跳）。默认值必须留足余量，且**不得短于 CLI 的 -t 默认（600s）**
+	// 期间每 15s 一个 working 心跳）。默认值必须留足余量，且**不得短于 CLI 的 -t 默认（1 小时）**
 	// —— 短了就会出现「什么都没显示 · 调用失败 context deadline exceeded」。
-	if DefaultArkClawTimeout < 10*time.Minute {
-		t.Errorf("DefaultArkClawTimeout = %v, 实测长任务 304s + CLI -t 默认 600s，应 ≥ 10 分钟", DefaultArkClawTimeout)
+	if DefaultArkClawTimeout < time.Hour {
+		t.Errorf("DefaultArkClawTimeout = %v, 实测长任务 304s + CLI -t 默认 1h，应 ≥ 1 小时", DefaultArkClawTimeout)
 	}
 }
 

package/internal/agent/attachments.go

@@ -16,8 +16,11 @@ package agent
 //	stdin:stream-json  claude/codebuddy 原生 stream-json input（图片走 content block）
 //	flag:-a            llm CLI 原生 --attachment
 //	part:file          arkclaw 走 A2A 原生 file part（base64 inline）
+//	sdk:content-blocks dsh 的 SDK 通道（默认）把图片作为原生 image content block
+//	                   发出去（base64 inline，真进模型上下文）；显式切 headless 后
+//	                   没有图片通道 → 退化为下面的 prompt 档
 //	prompt             无原生输入通道：把绝对路径写进提示词，靠引擎的读文件工具看
-//	                   （trae / openclaw / dsh —— 需要工具可用，CLI 层会提示）
+//	                   （trae / openclaw —— 需要工具可用，CLI 层会提示）
 //	                   codebuddy-gateway 也归这一档：它走 payload.attachments 原生字段，
 //	                   但网关把它渲染成路径清单塞进 prompt（图不进模型上下文）
 
@@ -111,7 +114,16 @@ func AttachmentSupportOf(engine string) string {
 		return "flag:-a"
 	case "arkclaw":
 		return "part:file"
-	case "trae", "openclaw", "dsh", "codebuddy-gateway":
+	case "dsh":
+		// SDK 通道（默认）把图片作为原生 image content block 发出去（真进模型上下文）；
+		// 显式把通道切成 headless 后没有图片通道，只能退化为提示词里的路径。
+		// dshProfileName() 与引擎的 effectiveProfile 同规则（看 MAGIC_AGENT_DSH_PROFILE），
+		// 这里让 --engines 的能力字段与实际通道一致，不虚报原生。
+		if dshProfileName() == dshSDKProfile {
+			return "sdk:content-blocks"
+		}
+		return "prompt"
+	case "trae", "openclaw", "codebuddy-gateway":
 		// codebuddy-gateway 走 payload.attachments 原生字段（urlType=local-path），
 		// 但网关把它渲染成「附件清单 + 路径」塞进 prompt —— 图**不会**以图片形式
 		// 进模型上下文，故如实报 prompt 而不是 part:file。
@@ -158,9 +170,10 @@ func AppendDefaultOn(engine string) bool {
 
 // AttachmentPromptSection 把附件以「路径清单」的形式拼进提示词正文。
 //
-// 这是**没有原生附件输入通道**的引擎（trae / openclaw / dsh）的兜底：把绝对路径说给模型，
-// 由它自己的读文件工具去看。因此只有在工具可用时才有意义 —— CLI 层会在
-// --tools off 时给出明确提示（不静默丢附件）。
+// 这是**没有原生附件输入通道**的引擎（trae / openclaw）以及 dsh 的 headless 回退路
+// 的兜底：把绝对路径说给模型，由它自己的读文件工具去看。因此只有在工具可用时才有
+// 意义 —— CLI 层会在 --tools off 时给出明确提示（不静默丢附件）。dsh 的 SDK 通道不走
+// 这里：图片作为原生 image 块直接发（见 dshPromptBlocks）。
 func AttachmentPromptSection(atts []Attachment) string {
 	if len(atts) == 0 {
 		return ""

package/internal/agent/attachments_test.go

@@ -107,6 +107,7 @@ func TestNewAttachmentFallsBackToExtension(t *testing.T) {
 }
 
 func TestAttachmentSupportOf(t *testing.T) {
+	t.Setenv(DshProfileEnv, "") // dsh 默认走 SDK 通道 → 原生收图
 	want := map[string]string{
 		"codex":        "flag:-i",
 		"claude":       "stdin:stream-json",
@@ -116,7 +117,7 @@ func TestAttachmentSupportOf(t *testing.T) {
 		"arkclaw":      "part:file",
 		"trae":         "prompt",
 		"openclaw":     "prompt",
-		"dsh":          "prompt",
+		"dsh":          "sdk:content-blocks",
 	}
 	for engine, w := range want {
 		if got := AttachmentSupportOf(engine); got != w {
@@ -127,6 +128,11 @@ func TestAttachmentSupportOf(t *testing.T) {
 	if got := AttachmentSupportOf("nope"); got != "prompt" {
 		t.Errorf("未知引擎应为 prompt, got %q", got)
 	}
+	// dsh 显式切 headless → 没有图片通道，退化为提示词路径
+	t.Setenv(DshProfileEnv, dshDefaultProfile)
+	if got := AttachmentSupportOf("dsh"); got != "prompt" {
+		t.Errorf("headless 下 AttachmentSupportOf(dsh) = %q want prompt", got)
+	}
 }
 
 func TestAppendAttachmentSectionFallback(t *testing.T) {

package/internal/agent/capability_test.go

@@ -127,7 +127,6 @@ func TestCapabilitiesDocumentedEngines(t *testing.T) {
 	}{
 		{"trae", &TraeEngine{}},
 		{"openclaw", &OpenClawEngine{}},
-		{"dsh", &DshEngine{}},
 	} {
 		caps := capabilitiesOfEngine(tc.e)
 		if !hasCap(caps, CapAttachmentPrompt) {
@@ -138,6 +137,17 @@ func TestCapabilitiesDocumentedEngines(t *testing.T) {
 		}
 	}
 
+	// dsh：SDK 通道（默认）把图片作为原生 image block 发出 → attachment.native。
+	// 显式切 headless 后没有图片通道 → 退化为 attachment.prompt（能力随实际通道走）。
+	t.Setenv(DshProfileEnv, "")
+	if caps := capabilitiesOfEngine(&DshEngine{}); !hasCap(caps, CapAttachmentNative) || hasCap(caps, CapAttachmentPrompt) {
+		t.Errorf("dsh(SDK 通道) 应有 %s 而非 %s，实际 %v", CapAttachmentNative, CapAttachmentPrompt, caps)
+	}
+	t.Setenv(DshProfileEnv, dshDefaultProfile)
+	if caps := capabilitiesOfEngine(&DshEngine{}); !hasCap(caps, CapAttachmentPrompt) || hasCap(caps, CapAttachmentNative) {
+		t.Errorf("dsh(headless) 应有 %s 而非 %s，实际 %v", CapAttachmentPrompt, CapAttachmentNative, caps)
+	}
+
 	// arkclaw 的附件走 A2A 原生 file part → 应给出 attachment.native。
 	// 这条直接查表：ArkClawEngine 的名字来自配置（不是常量），不适合直接构造。
 	if got := AttachmentSupportOf("arkclaw"); got != "part:file" {

package/internal/agent/claude.go

@@ -3,15 +3,27 @@ package agent
 // claude.go - Claude Code CLI 引擎。
 //
 // 后端：claude（Claude Code，本机 /opt/homebrew/bin/claude）。
-// 非交互模式：-p（--print）+ --output-format json，拿到稳定 envelope：
 //
-//	{"type":"result","subtype":"success","result":"<正文>",
-//	 "session_id":"...","is_error":false, "total_cost_usd":...}
+// ## 提示词一律走 stdin（2026-10-01 改，Windows 实测）
 //
-// 关键 flags：
+// 以前用 `-p <prompt>` 把提示词当**位置参数**传。实测在 Windows 上这是
+// 结构性不可靠的：npm 装的 claude 是 `claude.cmd` 批处理，含换行的位置参数
+// 会被 cmd.exe 拆坏，子进程拿不到完整 prompt 就**静默退 0、零输出**
+//（对照实验：同一命令单行 20 行 / 含换行 0 行；非流式同样整段丢内容）。
+//
+// 现在 Complete 与 Stream **都**走 `--input-format stream-json` 的 stdin
+// 通道（streamjson.go），提示词永不作为 argv。unix 上协议完全相同，
+// 故**不加平台分支** —— 一条路径两平台通吃。
+//
+// 收尾正文从 NDJSON 的 result 行取（这条协议要求 --output-format 也是
+// stream-json），故连非流式的 Complete 也要归约一遍事件。
+//
+// ## 关键 flags：
 //
 //	--model <m>                    传裸模型名（sonnet / opus / claude-sonnet-4-6...）
 //	--tools ""                     禁用全部内置工具，纯 chat 一次成型
+//	                                 （Windows 上经 launch.go 改写成 --tools=，
+//	                                  空串作独立参数会被 cmd.exe 丢弃）
 //	--permission-mode <mode>       四档权限档位（见 permission.go）：
 //	                               manual → default；accept-edits → acceptEdits；
 //	                               auto → auto；full → bypassPermissions（默认档）
@@ -39,7 +51,6 @@ package agent
 
 import (
 	"context"
-	"encoding/json"
 	"fmt"
 	"io"
 	"os"
@@ -57,8 +68,8 @@ type ClaudeEngine struct {
 // Name 实现 Engine。
 func (e *ClaudeEngine) Name() string { return "claude" }
 
-// DefaultClaudeTimeout 单次尝试默认超时。
-const DefaultClaudeTimeout = 5 * time.Minute
+// DefaultClaudeTimeout 单次尝试默认超时（2026-10-10 由 5 分钟统一上调到 1 小时）。
+const DefaultClaudeTimeout = time.Hour
 
 // DefaultClaudeModel claude 引擎的默认模型（Claude Code CLI 默认即主模型，
 // 显式传空串别名让 CLI 自己决定，不在代理层硬编码具体版本号）。
@@ -121,17 +132,6 @@ func (e *ClaudeEngine) ListModels(_ context.Context) ([]string, error) {
 	return models, nil
 }
 
-// claudeResult 对应 --output-format json 的 envelope。
-type claudeResult 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"`
-	TotalCostUSD float64 `json:"total_cost_usd"`
-}
-
 // Complete 实现 Engine：单次调用 claude CLI。
 func (e *ClaudeEngine) Complete(ctx context.Context, req Request) (Response, error) {
 	start := time.Now()
@@ -145,54 +145,14 @@ func (e *ClaudeEngine) Complete(ctx context.Context, req Request) (Response, err
 		return Response{}, fmt.Errorf("claude: empty prompt")
 	}
 
-	// 附件（截图）：claude 的 -p 文本模式收不了图，唯一的原生通道是
-	// --input-format stream-json（图片作为 content block 走 stdin）。该模式下
-	// --output-format 也必须是 stream-json，所以这里跑一遍流式协议、把事件归约成
-	// 单次结果返回（Complete 的语义就是「一次性拿最终答案」，不给调用方发事件）。
-	if hasImageAttachment(req.Attachments) {
-		return e.completeWithAttachments(ctx, req, prompt, start)
-	}
-
-	args := e.buildArgs(req, prompt)
-
-	// workspace：claude 没有工作目录 flag，子进程 cwd 就是原生方式（见 Request.Workspace）
-	stdout, stderr, err := runCLIIn(ctx, req.Workspace, bin, args...)
-	if err != nil {
-		return Response{}, wrapCliError("claude", stdout, stderr, err)
-	}
-
-	raw := strings.TrimSpace(stdout)
-	if raw == "" {
-		return Response{}, fmt.Errorf("claude CLI returned empty output")
-	}
-
-	var env claudeResult
-	if err := json.Unmarshal([]byte(raw), &env); err != nil {
-		// 个别版本对 --print + json 仍吐纯文本：原样返回。
-		return Response{
-			Text:    raw,
-			Model:   req.Model,
-			Latency: time.Since(start),
-		}, nil
-	}
-	if env.IsError {
-		return Response{}, fmt.Errorf("claude CLI error (subtype=%s): %s", env.Subtype, truncateStr(env.Result, 500))
-	}
-	if env.Result == "" {
-		return Response{}, fmt.Errorf("claude CLI returned empty result")
-	}
-	return Response{
-		Text:      env.Result,
-		Model:     env.Model,
-		SessionID: env.SessionID,
-		Latency:   time.Since(start),
-	}, nil
-}
-
-// completeWithAttachments 走 stream-json 输入通道跑一次带附件的调用，
-// 把事件归约成单次 Response（不向调用方发增量事件）。
-func (e *ClaudeEngine) completeWithAttachments(ctx context.Context, req Request, prompt string, start time.Time) (Response, error) {
-	bin := e.bin()
+	// 提示词走 stdin 的 stream-json 通道（**所有**调用，含无附件的纯文本）。
+	//
+	// 为什么不再用 `-p <prompt>` 位置参数（2026-10-01 改，Windows 实测）：
+	// 位置参数在 Windows 上会被 .cmd 批处理拆坏 —— 含换行时整段内容丢失，
+	// claude 收到空 prompt 后回一句 "How can I help you today?"（实测）。
+	// unix 上位置参数本来能用，但统一走 stdin 可让两平台行为完全一致，
+	// 省掉一类「只在某个平台复现」的问题。代价是要多解析一层 NDJSON，
+	// 而 streamJSONArgs/runStreamJSONIn 已是附件路径的现成实现。
 	args := streamJSONArgs(e.buildArgsBase(req), prompt, false)
 	stdin, err := streamJSONUserLine(prompt, req.Attachments)
 	if err != nil {
@@ -200,12 +160,19 @@ func (e *ClaudeEngine) completeWithAttachments(ctx context.Context, req Request,
 	}
 	acc := &streamAccumulator{Engine: e.Name(), OnSessionID: req.OnSessionID}
 	var fin streamJSONResult
-	seen, err := runStreamJSONIn(ctx, req.Workspace, nil, bin, args, strings.NewReader(stdin), acc, &fin)
+	// stderr 尾巴留一份：非零退出与「没有 result 行」都要拿它拼可读原因
+	//（CLI 崩溃 / 鉴权与额度失败的原因只出现在它的 stderr 里）。
+	var cliStderr streamStderrBuf
+	seen, err := runStreamJSONIn(ctx, req.Workspace, nil, bin, args, strings.NewReader(stdin), acc, &fin, &cliStderr)
 	if err != nil {
-		return Response{}, wrapCliError("claude", "", "", err)
+		return Response{}, wrapCliError("claude", "", cliStderr.String(), err)
 	}
 	if !seen {
-		return Response{}, fmt.Errorf("claude CLI stream ended without result line")
+		// 补终态事件（2026-10-02）：非流式路径通常没有 onEvent，nil 时静默跳过。
+		// 有 onEvent 的场景（观察者）才能看到「这一轮异常结束」而不是凭空消失。
+		err := streamNoResultErr("claude", cliStderr.String())
+		acc.emitTurnFailed(acc.SessionID, err)
+		return Response{}, err
 	}
 	if fin.IsError {
 		return Response{}, fmt.Errorf("claude CLI error (subtype=%s): %s", fin.Subtype, truncateStr(fin.Result, 500))
@@ -222,14 +189,16 @@ func (e *ClaudeEngine) completeWithAttachments(ctx context.Context, req Request,
 	}, nil
 }
 
-// buildArgs 构造 claude CLI 参数（Complete 与 Stream 共用）。
-// outputFormat："json"（单结果 envelope）或 "stream-json"（流式 NDJSON）。
+// buildArgs 构造 claude CLI 参数（含末尾的位置参数 prompt）。
+//
+// ⚠️ 2026-10-01 起**生产路径已不再用它**：Complete 与 Stream 都把提示词
+// 走 stdin（见各自注释里的理由），只有测试与「显式要位置参数」的场合还可能用。
+// 保留是因为 buildArgsBase 的语义（"不含位置参数"）仍被 streamJSONArgs 依赖。
 func (e *ClaudeEngine) buildArgs(req Request, prompt string) []string {
 	return append(e.buildArgsBase(req), prompt)
 }
 
-// buildArgsBase 构造参数（不含末尾的位置参数 prompt）——给附件场景复用：
-// 那条路提示词走 stdin，不能再作为命令行参数传（streamJSONArgs 负责剔除）。
+// buildArgsBase 构造参数（不含末尾的位置参数 prompt）——提示词走 stdin 的路径复用它。
 func (e *ClaudeEngine) buildArgsBase(req Request) []string {
 	// 工具模式 × 权限档位（四档模型见 permission.go）：
 	//	off        --tools ""（无工具调用，权限档位无意义，不传）
@@ -252,7 +221,13 @@ func (e *ClaudeEngine) buildArgsBase(req Request) []string {
 	case tools.IsOff():
 		args = append(args, "--tools", "")
 	case tools.IsOn():
-		args = append(args, "--permission-mode", claudePermissionMode(req.Permission))
+		// ⚠️ 2026-10-01：必须显式 --tools default —— 只传 --permission-mode
+		// 不传 --tools 时，claude CLI 在 stream-json 模式下不发 result 行
+		// （实测）：表现为「stream ended without result line」，魔法端把整轮
+		// 标 turn_failed、UI 一句话都渲染不出来。--tools default 才是「开工具」
+		// 的正路（与 ""=关、name1,name2=白名单 同列；"default" 是「全部内置」）。
+		args = append(args, "--tools", "default",
+			"--permission-mode", claudePermissionMode(req.Permission))
 	default: // allowlist
 		args = append(args, "--tools", strings.Join(tools.Allowlist(), ","),
 			"--permission-mode", claudePermissionMode(req.Permission))
@@ -262,6 +237,14 @@ func (e *ClaudeEngine) buildArgsBase(req Request) []string {
 	} else {
 		args = append(args, "--model", DefaultClaudeModel)
 	}
+	// 推理档位：claude 的 --effort 只认 low/medium/high/xhigh/max（无 minimal），
+	// 传 minimal 时降级为 low，避免 clap 直接拒绝整轮调用。
+	if lv := ReasoningLevel(req.Reasoning); lv != "" {
+		if lv == "minimal" {
+			lv = "low"
+		}
+		args = append(args, "--effort", lv)
+	}
 	// 统一参数矩阵：`--settings` 只接受**一份**载荷（文件路径或内联 JSON），
 	// 所以 MaxTokens 的 env 注入、四档模型的 sandbox / autoMode / permissions
 	// 必须合并进同一个 JSON —— 见 permission.go 的 agentSettingsPayload。
@@ -287,102 +270,57 @@ func (e *ClaudeEngine) Stream(ctx context.Context, req Request, onEvent func(Str
 		return StreamResult{}, fmt.Errorf("claude: empty prompt")
 	}
 
-	// 附件（截图）→ stream-json 输入通道：提示词不再当位置参数，改走 stdin。
-	// 常驻会话（Request.Append 非 nil）走同一条通道 —— 区别只在 stdin 是个**流**：
+	// 提示词一律走 stdin 的 stream-json 输入通道（不再当位置参数）。
+	//
+	// 为什么这是**默认**而不是「附件时才走」（2026-10-01 改，Windows 实测）：
+	// 位置参数在 Windows 上是结构性不可靠的 —— npm 装的 claude 是 .cmd 批处理，
+	// 含换行的位置参数会被 cmd.exe 拆坏，子进程拿不到完整 prompt 就
+	// **静默退 0、零输出**（对照实验：同一命令单行 20 行 / 含换行 0 行）。
+	// 不只是流式受损：非流式的 -p 同样整段丢内容。
+	// agents-anywhere 对此的处理是提示词全走 SDK stdin（connector/runtimes/claude/
+	// sdk/client.py:160 的 query(content)），从架构上就没有这条破路。
+	//
+	// unix 上走 stdin 同样正确（协议一致），故**不加平台分支** ——
+	// 一条路径两平台通吃，避免两套行为漂移。
+	//
+	// 常驻会话（Request.Append 非 nil）的区别只在 stdin 是个**流**：
 	// 追加消息源源不断写进去，通道关闭才 EOF（子进程随之收尾）。
-	args := e.buildArgs(req, prompt)
-	if req.Append != nil || hasImageAttachment(req.Attachments) {
-		var stdin io.Reader
-		if req.Append != nil {
-			pipe, perr := streamJSONInputPipe(prompt, req.Attachments, req.Append)
-			if perr != nil {
-				return StreamResult{}, perr
-			}
-			stdin = pipe
-		} else {
-			line, serr := streamJSONUserLine(prompt, req.Attachments)
-			if serr != nil {
-				return StreamResult{}, serr
-			}
-			stdin = strings.NewReader(line)
-		}
-		args = streamJSONArgs(e.buildArgsBase(req), prompt, true)
-		acc := &streamAccumulator{Engine: e.Name(), OnEvent: onEvent, OnSessionID: req.OnSessionID}
-		var fin streamJSONResult
-		seen, err := runStreamJSONIn(ctx, req.Workspace, nil, bin, args, stdin, acc, &fin)
-		if err != nil {
-			return StreamResult{}, err
-		}
-		if !seen {
-			return StreamResult{}, fmt.Errorf("claude CLI stream ended without result line")
-		}
-		if fin.IsError {
-			return StreamResult{}, fmt.Errorf("claude CLI error (subtype=%s): %s", fin.Subtype, truncateStr(fin.Result, 500))
-		}
-		text := finalizeStreamText(fin, acc)
-		if text == "" {
-			return StreamResult{}, errEmptyStreamContent("claude")
-		}
-		return StreamResult{
-			Response: Response{
-				Engine:    e.Name(),
-				Text:      text,
-				Model:     fin.Model,
-				SessionID: fin.SessionID,
-				Latency:   time.Since(start),
-			},
-			Thinking: acc.Thinking.String(),
-			Tools:    acc.Tools,
-		}, nil
-	}
-
-	// json → stream-json：替换 --output-format 值并追加流式 flags。
-	for i := range args {
-		if args[i] == "--output-format" {
-			args[i+1] = "stream-json"
-			break
-		}
-	}
-	args = append(args, "--include-partial-messages", "--verbose")
-
-	acc := &streamAccumulator{Engine: e.Name(), OnEvent: onEvent}
-	var fin 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"`
-	}
-	seenResult := false
-
-	err := runStreamCLIIn(ctx, req.Workspace, bin, args, func(line string) error {
-		isResult, perr := acc.handleNDJSONLine(line)
+	var stdin io.Reader
+	if req.Append != nil {
+		pipe, perr := streamJSONInputPipe(prompt, req.Attachments, req.Append)
 		if perr != nil {
-			return perr
+			return StreamResult{}, perr
 		}
-		if isResult {
-			_ = json.Unmarshal([]byte(line), &fin)
-			seenResult = true
+		stdin = pipe
+	} else {
+		line, serr := streamJSONUserLine(prompt, req.Attachments)
+		if serr != nil {
+			return StreamResult{}, serr
 		}
-		return nil
-	})
+		stdin = strings.NewReader(line)
+	}
+	args := streamJSONArgs(e.buildArgsBase(req), prompt, true)
+	acc := &streamAccumulator{Engine: e.Name(), OnEvent: onEvent, OnSessionID: req.OnSessionID}
+	var fin streamJSONResult
+	var cliStderr streamStderrBuf
+	seen, err := runStreamJSONIn(ctx, req.Workspace, nil, bin, args, stdin, acc, &fin, &cliStderr)
 	if err != nil {
 		return StreamResult{}, err
 	}
-	if !seenResult {
-		return StreamResult{}, fmt.Errorf("claude CLI stream ended without result line")
+	if !seen {
+		// 补终态事件：流被截断（引擎崩 / 被杀 / 没吐 result）时，已流出去的半截正文
+		// 在事件流上永远停在 running —— 消费方看到的是一条悬空 item。
+		// 对齐 agents-anywhere 的 failed_terminal_event（见 emitTurnFailed）。
+		err := streamNoResultErr("claude", cliStderr.String())
+		acc.emitTurnFailed(acc.SessionID, err)
+		return StreamResult{}, err
 	}
 	if fin.IsError {
 		return StreamResult{}, fmt.Errorf("claude CLI error (subtype=%s): %s", fin.Subtype, truncateStr(fin.Result, 500))
 	}
-
-	text := fin.Result
-	if text == "" {
-		text = strings.TrimSpace(acc.Text.String())
-	}
+	text := finalizeStreamText(fin, acc)
 	if text == "" {
-		return StreamResult{}, fmt.Errorf("claude CLI returned empty result")
+		return StreamResult{}, errEmptyStreamContent("claude")
 	}
 	return StreamResult{
 		Response: Response{