@xiaobuyu/nodesign 0.0.1

package/server/engine/agent/hooks/post-guidance.js

@@ -0,0 +1,206 @@
+/**
+ * PostToolUse 行为引导族 —— 工具跑完后注 additionalContext 引导 agent 下一步
+ * （截图后自检 / 交付后告知 / 重生看门狗 / 风格锚落盘提醒）。
+ * （2026-08-14 可维护性行动：从 hooks.js 原样迁出，语义零改动）
+ *
+ * makePostToolUseRecordDecisionHandler — 已移除（git 历史可查）。
+ * 之前注 "继续做用户的当前任务" 跟 SDK preset 'claude_code' 教的内容重复，
+ * 让 agent 行为像被牵着走。删除后 agent 记完决策自己判断下一步，更接近
+ * SDK 默认行为。如未来观察到 agent 反复 record_decision 信号稀释，再考虑
+ * 加回（那时改成更精准的 anti-loop 检测，不是无脑注引导）。
+ */
+import path from 'node:path';
+
+/**
+ * PostToolUse(screenshot_canvas) handler — agent 截图后引导它做视觉自检。
+ *
+ * input: PostToolUseHookInput (sdk.d.ts:1926)
+ *   - tool_name / tool_input / tool_response / tool_use_id / duration_ms?
+ *
+ * output: PostToolUseHookSpecificOutput (sdk.d.ts:1938)
+ *   - additionalContext?: string         注入下一轮 prompt
+ *   - updatedToolOutput?: unknown        替换 tool 输出（不用）
+ *
+ * 注意：tool_response 里包含 image content block（base64）。agent 收到这条
+ * additionalContext 时已经能"看到"图（multimodal）—— 我们只是用文字提示
+ * 它接下来该做什么，不替换 image。
+ *
+ * 截图后的引导（2026-07-28；硬上限已撤销）：
+ * 实测一个真实会话 9-33 张截图，每张 0.6 倍光栅后 ≈1k vision tokens，且
+ * **永久留在上下文里**（SDK 不能回改历史工具输出）。
+ *
+ * 曾经加过"整会话超 12 张就把图换成文字"的硬闸，撤掉了：那等于在 agent 检查
+ * 自己作品的时候把它的眼睛蒙上，而且蒙得悄无声息 —— 它只会以为"看起来 OK"。
+ * 省下来的几十 k 换不来这个代价。现在只报数、给建议，看不看由它自己判断；
+ * 真正的省是 0.6 倍光栅（每张 1.85k→1.0k）和压缩阈值，不是拦着不让看。
+ */
+const SCREENSHOT_BUSY_HINT_AT = 6;   // 累到这个数开始提醒"大面积检查交给子代理"
+
+export function makePostToolUseScreenshotHandler({ ctx }) {
+  let takenInSession = 0;
+  let takenInTurn = 0;
+  let lastTurn = -1;
+  // 不 emit run.screenshot_taken —— mcp/tools/screenshot.js:114 已经 emit
+  // 完整字段（sizeBytes / viewport / fullPage）。hook 只负责注 additionalContext
+  // 引导 agent 行为，业务事件由 MCP 工具内部负责。
+  return async (input, _toolUseId, _options) => {
+    const args = input?.tool_input || {};
+    const wasFullPage = args.fullPage === true;
+    const wasPerPage = typeof args.pageIndex === 'number';
+    const turn = ctx?.counters?.turns ?? 0;
+    if (turn !== lastTurn) { lastTurn = turn; takenInTurn = 0; }
+    takenInTurn += 1;
+    takenInSession += 1;
+
+    // fullPage 截图体积是 viewport 的 N×（N=页数），且会留在 context 多 turn
+    // 直到 autoCompact。push agent 下次整 deck 自检走 vision-checker subagent，
+    // subagent context 是隔离的，主线只收文字 critique，几 K vs 几百 K 的差距。
+    // 08-21 起这里只注**状态**（张数计数），不再每张截图注一段"点 3 个问题 / 派 vision-checker"
+    // 的说教 —— 那些住 prelude（做完之前先自己看 / 何时请外援），每张都说是 N 倍重复，而且
+    // "整 deck 自检请派 vision-checker"跟 prelude 定的触发条件（自检两轮用户仍不满意）矛盾。
+    void wasFullPage; void wasPerPage;
+    if (takenInSession < SCREENSHOT_BUSY_HINT_AT) return {};
+    return {
+      hookSpecificOutput: {
+        hookEventName: 'PostToolUse',
+        additionalContext:
+          `**上下文提示**：本轮 ${takenInTurn} 张、本会话累计 ${takenInSession} 张截图（每张约 1k tokens，进了上下文不会释放）。没有额度上限，该看就看。`,
+      },
+    };
+  };
+}
+
+/**
+ * PostToolUse(export_handoff) handler — agent 打交付包后引导它告知用户路径。
+ */
+export function makePostToolUseExportHandler({ ctx: _ctx }) {
+  // 不 emit run.export_built —— mcp/tools/export-handoff.js:83 已经 emit
+  // 完整字段（format / path / sizeBytes / notes）。hook 从 tool_response 字符串
+  // substring 拼出来的 path 反而不准。hook 只负责注 additionalContext。
+  // 08-21：只在本 session 第一次打包时提醒一次；"收尾消息要自足"prelude 已讲，每次都注是重复
+  let said = false;
+  return async (_input, _toolUseId, _options) => {
+    if (said) return {};
+    said = true;
+    return {
+      hookSpecificOutput: {
+        hookEventName: 'PostToolUse',
+        additionalContext: '已生成交付包。把打包文件路径告诉用户（他从 UI 下载）；同一个交付只打包一次。',
+      },
+    };
+  };
+}
+
+// ── Phase Image-4：generate_image 重生看门狗 ──
+//
+// agent 同 outputName 调 generate_image 第 3 次起，注 systemMessage 建议：
+//   - 直接 chat 邀请用户在最近 2-3 张候选里选最好的（generate_image 已返 image
+//     content block，前端 chat 自动渲染，用户能直接看到）
+//   - 或 accept 当前最好的一版继续后续工作
+// 防"agent 闷头改 5-10 次同 prompt 浪费 token + 用户也得不到更好版本"。
+//
+// 计数策略：
+//   - in-memory Map（key: outputName 去 timestamp 的 base，value: count）
+//   - 进程重启清；session 内累积；不区分 session（agent 进程同步 hook）
+//   - 阈值固定 3，可后续 env 化
+//
+// outputName base 提取：
+//   - "deck-cover-v1" → "deck-cover"（去掉 -v\d / -\d / -draft 等 suffix）
+//   - 同 base 不同 suffix 仍计入同一组（避免 agent 改名绕过 watchdog）
+export function makePostToolUseGenerateImageRegenWatchdog() {
+  let nudgedOnce = false;   // 08-21：邀请反馈的判断准则每 session 说一次就够（以前每个 base 组第一张都说）
+  const REGEN_THRESHOLD = 3;
+  const counts = new Map();
+
+  function extractBase(outputName) {
+    if (!outputName || typeof outputName !== 'string') return null;
+    return outputName
+      .replace(/-(?:v\d+|draft\d*|final|new|old|alt|\d+)$/i, '')
+      .replace(/[-_]+/g, '-')
+      .toLowerCase();
+  }
+
+  return async (input, _toolUseId, _options) => {
+    try {
+      const outputName = input?.tool_input?.outputName;
+      const base = extractBase(outputName);
+      if (!base) return {};
+
+      const next = (counts.get(base) || 0) + 1;
+      counts.set(base, next);
+
+      // 第 1 次：邀请反馈 nudge（按 SKILL.md 高代价 / 低代价节点判断）
+      if (next === 1 && !nudgedOnce) {
+        nudgedOnce = true;
+        return {
+          hookSpecificOutput: {
+            hookEventName: 'PostToolUse',
+            additionalContext:
+              `<system-reminder>\n[image-feedback-nudge] 这是本组（base="${base}"）第 1 张图。\n\n`
+            + `如果是 cover / portrait / 跨页 anchor 这类高代价节点（会被当 referenceImages 种子用于全 deck），可以在 chat 里自然邀请用户确认一下方向（"这个 cover 当全 deck 视觉锚 OK 吗？"），收到反馈再做后续；section-divider / decoration / icon 这类单张可直接继续，工具 caption 已自动在 chat 显示。\n\n`
+            + `判断诀窍：错了会不会导致全 deck 重生？会 → 邀请反馈；不会 → 继续。\n`
+            + `</system-reminder>`,
+          },
+        };
+      }
+
+      if (next < REGEN_THRESHOLD) return {};
+
+      // ≥ 3 次同 base outputName → 注 systemMessage
+      return {
+        hookSpecificOutput: {
+          hookEventName: 'PostToolUse',
+          additionalContext:
+            `<system-reminder>\n[regen-watchdog] 你已经对 outputName base "${base}" 调 generate_image ${next} 次。\n\n`
+          + `如果是 conversational editing 微调（"再暖一点 / 换日落色"），可以继续；\n`
+          + `如果在反复尝试不同方向（每次 prompt 大改），**强烈建议**：\n`
+          + `  1. 直接在 chat 里邀请用户从最近 2-3 张候选选最好的（image content block 已自动在 chat 渲染）\n`
+          + `  2. 或 accept 当前最满意的那张，专心后续工作\n`
+          + `理由：reroll 同 prompt 越多次 token 浪费越大，且用户也未必能在第 N 张里看出明显差别。\n`
+          + `</system-reminder>`,
+        },
+      };
+    } catch (err) {
+      console.warn(`[hooks/regen-watchdog] threw:`, err.message);
+      return {};
+    }
+  };
+}
+
+/**
+ * PostToolUse(record_decision) —— 锚定风格那一笔之后提醒落两处长期资产
+ * （2026-07-28，配合"记忆归 SDK / 品牌归我们 / 指引归用户"的分工）
+ *
+ * 只在这一笔上注、每 session 一次：
+ *   - 品牌档案 `agent-memory/brand/memory.md` —— 前端 BrandCard 会把色板 /
+ *     字体渲染出来，是结构化资产，agent 不写就永远空着
+ *   - 项目指引 `.claude/CLAUDE.md` —— SDK 每次 session 自动读进 system prompt，
+ *     但只有用户能决定要不要固化，所以是"问一句"不是"直接写"
+ *
+ * 通用偏好不在这儿管：那是 SDK 自动记忆的活（autoMemoryDirectory 已指到
+ * .claude/agent-memory/auto，前端记忆卡直接显示）。
+ */
+export function makePostToolUseStyleAnchorNudge({ sharedRoot }) {
+  let nudged = false;
+  const ANCHOR_RE = /(style-anchor|风格锚|锚定|视觉基调|palette|配色方案)/i;
+  return async (input, _toolUseId, _options) => {
+    if (nudged) return {};
+    const t = input?.tool_input || {};
+    const blob = `${t.topic || ''} ${t.title || ''} ${t.decision || ''} ${t.rationale || ''}`;
+    if (!ANCHOR_RE.test(blob)) return {};
+    nudged = true;
+    const guidePath = sharedRoot ? path.join(sharedRoot, '.claude', 'CLAUDE.md') : '.claude/CLAUDE.md';
+    return {
+      hookSpecificOutput: {
+        hookEventName: 'PostToolUse',
+        additionalContext:
+          '这一笔看起来是在锚定这个项目的视觉方向。顺手做两件事（都只做一次）：\n'
+        + '1. 把这版风格写进 `.claude/agent-memory/brand/memory.md`（色号 / 字体链 / 版式语言 / 动效预算；⚠️ 带 .claude/ 前缀，写错位置 BrandCard 读不到），'
+        + '前端品牌档案卡会把色板和字体渲染出来给用户看，不写就一直空着。\n'
+        + `2. 如果这次定下来的还包含**项目级约束**（不只这一个 deck 适用，比如"这个项目一律不用 emoji"），`
+        + `在收尾时问用户一句要不要写进项目指引（${guidePath}，SDK 每次 session 自动读它）。用户点头你再写。\n`
+        + '用户的通用偏好不用你手动记，系统的自动记忆会管。',
+      },
+    };
+  };
+}

package/server/engine/agent/hooks/post-subagent-report.js

@@ -0,0 +1,104 @@
+/**
+ * hooks/post-subagent-report.js — 子代理报告丢了的时候别整轮重跑（2026-08-18）
+ *
+ * ## 问题
+ *
+ * SDK 的子代理触到 `maxTurns` 时返回的是 SDKResultError，**那个类型没有 result
+ * 字段** —— 最后一条 assistant 消息（也就是报告本身）直接消失，主 agent 拿到的
+ * 是空的或者只有开场白。工作已经做完、token 已经烧掉，结果拿不到。
+ *
+ * 2026-08-05 真实记录：两次派 explorer，一次 59292 tokens / 16 轮工具调用 / 110s，
+ * 回来只有一句开场白；一次 31228 tokens / 17 轮，回来 "(returned no output.)"。
+ * 中间轮次少的那次正常。主 agent 的绕行只能是"拆小重派"或"放弃子代理" ——
+ * 等于放弃了子代理隔离上下文的全部价值，长研究任务反而不敢派了。
+ *
+ * ## 做法
+ *
+ * 我们改不了 SDK 那个类型，但 `task_notification` 上带着 **`output_file`** ——
+ * 子代理的完整转录 JSONL。所以：报告看起来是空的时候，把转录路径递给主 agent，
+ * 让它 Read 一遍把结论捞出来。**从"整轮白烧"变成"多读一个文件"。**
+ *
+ * ⚠️ 判据故意保守（只在摘要短得不像报告时才提示）：把这句话贴在每次正常的
+ * 子代理返回后面是噪音，而噪音会训练 agent 忽略提示。
+ */
+
+/** tool_use_id → 最近一次 task_notification（agent-shared 在收到时写进来） */
+const lastNotification = new Map();
+const MAX_TRACKED = 200;
+
+export function recordTaskNotification(msg) {
+  if (!msg?.tool_use_id) return;
+  lastNotification.set(msg.tool_use_id, {
+    status: msg.status,
+    summary: msg.summary || '',
+    outputFile: msg.output_file || null,
+    toolUses: msg.usage?.tool_uses ?? null,
+    tokens: msg.usage?.total_tokens ?? null,
+  });
+  // 别无限长：一个会话里子代理数量有限，但进程是长命的
+  if (lastNotification.size > MAX_TRACKED) {
+    const first = lastNotification.keys().next().value;
+    lastNotification.delete(first);
+  }
+}
+
+/** 已经消费过的 id（用来区分"没记上"和"记过又用掉了"，见下面那段） */
+const consumed = new Set();
+let missing = 0;
+
+/** 报告"看起来是空的"的判据 —— 短于这个就不像一份报告 */
+const SUSPICIOUS_LEN = 200;
+
+export function makePostToolUseSubagentReportRecovery() {
+  return async (input) => {
+    const id = input?.tool_use_id;
+    if (!id) return {};
+    const note = lastNotification.get(id);
+    if (!note) {
+      // ⚠️ 这条分支是「静默死」的经典形状：`recordTaskNotification` 必须**先于**
+      // 这个 hook 跑，否则整个 handler 什么都不做而且一声不响。这个仓库为
+      // 「hook 静默死」付过三次账（最贵一次 19 个会话 0 触发、38k tokens 白跑），
+      // 所以宁可留一行日志：真出问题时它会成堆出现，而不是一片安静。
+      // 正常也会走到这儿（同一个 id 第二次进来，note 已被一次性消费掉），
+      // 所以只在**从来没见过这个 id** 时才记。
+      if (!consumed.has(id)) {
+        missing += 1;
+        console.warn(`[subagent-report] tool_use_id ${id} 没有对应的 task_notification`
+          + `（累计 ${missing} 次）—— 如果这个数字在涨，说明 recordTaskNotification`
+          + ' 没有跑在这个 hook 之前，兜底其实是死的。');
+      }
+      return {};
+    }
+    consumed.add(id);
+    if (consumed.size > MAX_TRACKED) consumed.delete(consumed.values().next().value);
+    lastNotification.delete(id);          // 一次性
+
+    const looksEmpty = note.summary.trim().length < SUSPICIOUS_LEN;
+    // 摘要有内容就什么都不说 —— 报告回来了，再贴一段提示是噪音，
+    // 而噪音会训练 agent 忽略提示。
+    if (!looksEmpty) return {};
+    const didRealWork = (note.toolUses ?? 0) >= 4 || (note.tokens ?? 0) >= 8000;
+
+    const lines = [
+      `⚠️ 这个子代理回来的内容只有 ${note.summary.trim().length} 个字符`
+      + `（status=${note.status}${note.toolUses != null ? `，跑了 ${note.toolUses} 次工具调用` : ''}`
+      + `${note.tokens != null ? `，${note.tokens} tokens` : ''}）。`,
+    ];
+    if (didRealWork) {
+      lines.push('它**确实干了活**，但最终报告没回传 —— SDK 的子代理触到轮次上限时'
+        + '返回的错误类型不带 result 字段，最后那条消息会整个丢掉。');
+    }
+    if (note.outputFile) {
+      lines.push(`完整转录在 \`${note.outputFile}\`。**Read 它把结论捞出来，别整轮重派** ——`
+        + 'token 已经烧掉了，重跑一遍只是再烧一次。转录是 JSONL，从后往前读最快。');
+    } else {
+      lines.push('没有转录路径可捞。要重派的话把任务拆小（工具调用轮次少的时候不会丢）。');
+    }
+    return {
+      hookSpecificOutput: {
+        hookEventName: 'PostToolUse',
+        additionalContext: lines.join('\n'),
+      },
+    };
+  };
+}

package/server/engine/agent/hooks/post-trim.js

@@ -0,0 +1,58 @@
+/**
+ * PostToolUse(Edit|Write) handler —— 干掉 tool_response.originalFile 防上下文累积。
+ * （2026-08-14 可维护性行动：从 hooks.js 原样迁出，语义零改动）
+ *
+ * 背景：
+ *   FileEditOutput.originalFile / FileWriteOutput.originalFile (sdk-tools.d.ts:2270, 2328)
+ *   是完整原文件内容。canvas.html 25KB 一次 Edit 在 tool_result 里等于 6k tokens。
+ *   30 turn 累积 ≈ 180k tokens → 跟 Kimi 256k 上限挤爆（用户实测 418k 报错）。
+ *
+ *   structuredPatch（diff 行）是模型理解改动所需的全部信息；oldString/newString
+ *   是模型自己刚才传的 input，本来就在上下文里。originalFile 对模型基本无用 —
+ *   要看完整文件后续再 Read 即可。
+ *
+ * 行为：
+ *   updatedToolOutput 是 SDK 提供的"改写发给 model 的 tool_result"通道
+ *   (sdk.d.ts:1944)。**只影响 model 视图**，jsonl 持久化仍是原 tool_response。
+ *   也就是 forkSession / 断线恢复看到的还是完整产物 — 不丢数据。
+ *
+ *   保留字段：filePath / oldString / newString / structuredPatch / type / gitDiff
+ *   清掉字段：originalFile（替换为 null，保持类型 string|null）
+ *
+ *   非 Edit/Write 的 tool_response 形态（如 input 不带 originalFile） noop。
+ *
+ * input: PostToolUseHookInput (sdk.d.ts:1926)
+ * output: PostToolUseHookSpecificOutput (sdk.d.ts:1938)
+ */
+export function makePostToolUseEditWriteTrimHandler({ ctx }) {
+  return async (input, _toolUseId, _options) => {
+    try {
+      const resp = input?.tool_response;
+      if (!resp || typeof resp !== 'object') return {};
+      if (!('originalFile' in resp)) return {};
+      const originalSize = typeof resp.originalFile === 'string' ? resp.originalFile.length : 0;
+      if (originalSize === 0) return {};  // 新建文件 originalFile 本就是 null
+
+      const trimmed = { ...resp, originalFile: null };
+
+      try {
+        ctx.emit({
+          type: 'run.tool_response_trimmed',
+          tool: input?.tool_name || 'Edit/Write',
+          field: 'originalFile',
+          savedChars: originalSize,
+        });
+      } catch { /* emit fail-safe */ }
+
+      return {
+        hookSpecificOutput: {
+          hookEventName: 'PostToolUse',
+          updatedToolOutput: trimmed,
+        },
+      };
+    } catch (err) {
+      console.warn(`[hooks/PostToolUse Edit|Write trim] handler threw:`, err.message);
+      return {};
+    }
+  };
+}

package/server/engine/agent/hooks/pre-board-neighborhood.js

@@ -0,0 +1,34 @@
+/**
+ * PreToolUse(Read|Edit|Write) —— 关系线邻域注入（2026-08-14 切片③）。
+ *
+ * agent 正要摸的文件身上如果连着线（用户手画的标注、改自/对照谱系），这一刻
+ * 就是它最相关的时刻。每个文件一个会话只注一次（线是慢变数据，重复注是噪音）；
+ * fail-soft —— 注不上不能挡工具。
+ *
+ * UserPromptSubmit 的全图摘要截断后，这里做精确补充。
+ */
+import { fileNeighborhood } from '../../../lib/board-relations.js';
+import { toWorkspaceRel } from '../../../lib/workspace-path.js';
+
+export function makePreToolUseBoardNeighborhoodInjector({ workspaceRoot, projectId }) {
+  const seen = new Set();
+  return async (input) => {
+    try {
+      if (!projectId) return {};
+      const fp = input?.tool_input?.file_path;
+      if (typeof fp !== 'string' || !fp) return {};
+      const rel = toWorkspaceRel(fp, workspaceRoot);
+      if (!rel || seen.has(rel)) return {};
+      seen.add(rel);
+      const brief = await fileNeighborhood(projectId, rel, { limit: 6 });
+      if (!brief) return {};
+      return {
+        hookSpecificOutput: {
+          hookEventName: 'PreToolUse',
+          permissionDecision: 'allow',
+          additionalContext: `画布上连着 ${rel} 的关系线：\n${brief}`,
+        },
+      };
+    } catch { return {}; }
+  };
+}

package/server/engine/agent/hooks/pre-defaults.js

@@ -0,0 +1,84 @@
+/**
+ * PreToolUse 默认值矫正族 —— 透明改 tool_input，agent 无感，结果更有用。
+ * （2026-08-14 可维护性行动：从 hooks.js 原样迁出，语义零改动）
+ */
+
+
+/**
+ * PreToolUse(Agent) 强制前台 —— 透明改 input，不 hard deny。
+ *
+ * ⚠️ 2026-08-03 修：**默认值翻了面，这个 hook 之前形同虚设。**
+ *
+ * 老 SDK：`run_in_background` 不传 = 前台，所以只需拦 `=== true`。
+ * 新 SDK（sdk-tools.d.ts AgentInput 原文）："Agents run in the background by
+ * default; you will be notified when one completes. **Set to false** to run this
+ * agent synchronously when you need its result before continuing."
+ *
+ * 也就是说**不传 = 后台**。模型自然写法就是不传（探针实测 bg=undefined），于是：
+ * 主 agent 只拿到一句 "Async agent launched successfully"，报告永远不回来。
+ * 真实事故：2026-08-03 一个 explorer 烧了 38k tokens / 20 次工具调用 / 108 秒查
+ * 完时局资料，主 agent 收到的 tool_result 里一个字都没有，只好自己重搜四轮，
+ * 还跟用户说了句"研究员跑完了但报告没回传到我这儿"。
+ *
+ * 所以判据从"等于 true 才改"改成"**不是显式 false 就补 false**"。
+ * 显式传了 false 的（模型自己知道要前台）原样放过，不重复改也不发提示。
+ *
+ * 为什么 NoDesign 一定要前台：创作的核心反馈环是 agent 看 explorer /
+ * vision-checker 传回的素材 URL 与 critique → 据此改产物 → 再自检。
+ * fire-and-forget 等于把这个环剪断，agent 拿不到结果只能盲写。
+ * forwardSubagentText 已开，前台等的时候用户看得见子代理实时进度，不会卡死。
+ *
+ * 兜底另有一层：DEFAULT_TOOL_ALLOWLIST 里挂了 `TaskOutput`，万一还是漏成后台
+ * （比如 isolation:'remote' 强制后台），主 agent 能凭 task_id 把报告捞回来。
+ */
+export function makePreToolUseAgentForceForegroundHandler() {
+  return async (input) => {
+    const t = input?.tool_input;
+    if (!t || typeof t !== 'object') return {};
+    // 显式前台，不动
+    if (t.run_in_background === false) return {};
+    return {
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'allow',
+        updatedInput: { ...t, run_in_background: false },
+        // 一句事实就够：为什么要前台 prelude 硬规则里已经讲了，每次派遣重复一遍是 N 倍说教
+        additionalContext: '已改为前台执行（run_in_background: false），报告会在这次 tool_result 里回来。',
+      },
+    };
+  };
+}
+
+/**
+ * PreToolUse(Grep) handler：把缺省 output_mode 改成 'content'。
+ *
+ * SDK Grep 工具默认 output_mode='files_with_matches' —— 只返回匹配到的文件名
+ * 列表，不返回行内容。Agent 拿到文件名后还得再 Read 一遍，多一个 turn，浪费
+ * tokens 和时延。NoDesign 设计场景下 agent grep 几乎都是想看实际文本（CSS
+ * 类名定义在哪、某个 token 怎么用），'content' 是更合理的默认。
+ *
+ * 拦截规则：
+ *   - 没传 output_mode 或传了空字符串 → updatedInput 改成 'content'
+ *   - 显式传 'files_with_matches' / 'count' → 不动（agent 知道自己在做什么）
+ *
+ * ⚠️ Grep 的输入改写只许有这一个 handler：两个 handler 各返回 updatedInput，
+ * 后跑的那个是拿原始 tool_input 拼的，会把前一个的改动抹掉（2026-08-15 演出
+ * 隐私闸想在这儿加排除 glob 时踩明白的，那版已按用户决定撤回）。
+ *
+ * 不发 additionalContext —— agent 不需要知道这个变换，行为对它透明，结果
+ * 直接更有用。
+ */
+export function makePreToolUseGrepContentDefaultHandler() {
+  return async (input) => {
+    const t = input?.tool_input;
+    if (!t || typeof t !== 'object') return {};
+    if (t.output_mode && t.output_mode !== '') return {};
+    return {
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'allow',
+        updatedInput: { ...t, output_mode: 'content' },
+      },
+    };
+  };
+}