@xiaobuyu/nodesign 0.0.7 → 0.0.8

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

@@ -0,0 +1,29 @@
+/**
+ * PreToolUse(板工具族) —— 纸内动静插话（2026-08-29 纸范式刀 4）。
+ *
+ * 用户在 agent 干活期间拖动/搬家/擦组，下一轮注入才说太晚 —— agent 这一轮接着
+ * 摆就是按旧位置摆。这里在它**下一次摸板**（write/edit/read/batch/open_sheet/
+ * organize）前插一句「用户刚动过什么」，按会话恰好一次（markSeen 台账）：说过的
+ * 不重复，新动静再说新的。fail-soft —— 注不上不能挡工具。
+ */
+import { dirtyEvents, describeDirty, lastSeen, markSeen } from '../../../lib/board-dirty.js';
+
+export function makePreToolUseBoardDirtyInjector({ projectId, sessionId }) {
+  return async () => {
+    try {
+      if (!projectId || !sessionId) return {};
+      const since = lastSeen(projectId, sessionId);
+      const evts = dirtyEvents(projectId, since);
+      if (!evts.length) return {};
+      markSeen(projectId, sessionId, evts[evts.length - 1].seq);
+      const line = describeDirty(evts, { limit: 6 });
+      return {
+        hookSpecificOutput: {
+          hookEventName: 'PreToolUse',
+          permissionDecision: 'allow',
+          additionalContext: `⚠ 用户刚在板上动过手：${line}。位置以现状为准（拿不准先 read_board），别把他挪过的东西又搬回去。`,
+        },
+      };
+    } catch { return {}; }
+  };
+}

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

@@ -3,6 +3,10 @@
  * （2026-08-14 可维护性行动：从 hooks.js 原样迁出，语义零改动）
  */
 
+import { isResidentRole, isSlotType, ROLE_SLUG_RE, resolveRoleTools } from '../cast.js';
+import { readRoleCard, inferRoleNameFromPrompt } from '../role-card.js';
+import { noteToolCaller, agentNameOf, notePendingRoleName } from '../actor-trail.js';
+import { MCP_SERVER_NAME } from '../../mcp/server-name.js';
 
 /**
  * PreToolUse(Agent) 强制前台 —— 透明改 input，不 hard deny。
@@ -31,10 +35,185 @@
  * 兜底另有一层：DEFAULT_TOOL_ALLOWLIST 里挂了 `TaskOutput`，万一还是漏成后台
  * （比如 isolation:'remote' 强制后台），主 agent 能凭 task_id 把报告捞回来。
  */
-export function makePreToolUseAgentForceForegroundHandler() {
-  return async (input) => {
+/**
+ * 这个角色声明的工具合不合法。合法返回 null，不合法返回一句给模型看的原因。
+ * 读不到文件时放行 —— 那说明角色压根不存在，派发自己会失败（失败会把名字从名册撤回）。
+ */
+async function illegalRoleTools(workspaceRoot, slug) {
+  if (!workspaceRoot) return null;
+  const card = await readRoleCard(workspaceRoot, slug);
+  if (!card) return null;
+  const decl = card.toolsDecl;
+
+  if (decl.kind === 'missing') {
+    return `角色「${slug}」的文件里没有 tools 那一行 —— 那在 SDK 语义里等于**继承你的全部工具**，`
+      + `包括外发和花钱的那些。用 cast_role 重新造这个角色（它会写一份只含板上工具的声明）。`;
+  }
+  if (decl.kind === 'unparsable') {
+    return `角色「${slug}」的 tools 声明看不懂，为安全起见不派。用 cast_role 重新造它。`;
+  }
+  const { rejected } = resolveRoleTools(decl.tools, MCP_SERVER_NAME);
+  if (rejected.length) {
+    return `角色「${slug}」声明了不该给角色的工具：${rejected.join('、')}。`
+      + `角色只能通过画布表达自己 —— 外发、花钱、改工作区结构的工具一律不发给它。`
+      + `用 cast_role 重新造它，或把这些工具从它的文件里去掉。`;
+  }
+  return null;
+}
+
+export function makePreToolUseAgentForceForegroundHandler({ roster = null, workspaceRoot = null, ctx = null } = {}) {
+  return async (input, toolUseId) => {
     const t = input?.tool_input;
     if (!t || typeof t !== 'object') return {};
+
+    // ── 常驻角色（rp-*）走反方向：强制**后台** + 钉死名字 ──
+    //
+    // 为什么它跟上面那段的结论相反：干活型子代理的产出是 tool_result 里的报告，
+    // 前台等着才拿得到；常驻角色（叙事者 / NPC）的产出走**画布和收件箱**，
+    // 它压根没打算结束回合 —— 前台跑等于把整条主线卡在一个不会返回的角色上。
+    //
+    // 名字必须由 harness 钉，不能指望模型传：2026-08-26 探针里三次明确要求
+    // 「name 参数必须写全」，模型三次都省掉了（还振振有词说 schema 里没有）。
+    // 没名字就只能用 agentId 寻址，而 agentId 只在那一条 tool_result 里出现过 ——
+    // 主代理换个话题就再也叫不回这个角色了。钉成 subagent_type 本身：
+    // 一个角色一个常驻实例，寻址名 = 角色名，两边不用对表。
+    // ── 演员位（2026-08-28 重构）：subagent_type 是预注册的 rp-actor / rp-narrator，
+    //    实例身份由 name 决定。name 闸写成硬 deny：探针实测模型漏传 name 被拒一次
+    //    就会补上（写成话术它不听，写成闸它就听 —— castedInRun 时代同款教训）。
+    if (isSlotType(t.subagent_type)) {
+      let name = typeof t.name === 'string' ? t.name.trim() : '';
+      let inferred = false;
+      if (!ROLE_SLUG_RE.test(name) || isSlotType(name)) {
+        // 参数没给/给坏了 → 从 prompt 推（glm 撞闸案：弱模型够不着的参数不当硬前置）
+        const taken = new Set(roster?.list?.() || []);
+        name = await inferRoleNameFromPrompt(workspaceRoot, t.prompt, { taken, isSlot: isSlotType });
+        inferred = !!name;
+      }
+      if (!name) {
+        return {
+          hookSpecificOutput: {
+            hookEventName: 'PreToolUse',
+            permissionDecision: 'deny',
+            // nd:rp-prompt —— 给两条出路：参数，或（弱模型也走得通的）prompt 配方
+            permissionDecisionReason:
+              `派演员位要一个独一无二的角色名（rp- 开头的小写 slug）。两种给法任选：`
+              + `① name 参数写上它；② prompt 第一行照 cast_role 的配方写`
+              + `「你的角色卡：角色/<名>/角色卡.md」（登记过的卡，闸会自己认出名字）。`
+              + `它就是这个角色之后的收件地址（SendMessage 寄给它用）。`,
+          },
+        };
+      }
+      if (roster && roster.has(name)) {
+        return {
+          hookSpecificOutput: {
+            hookEventName: 'PreToolUse',
+            permissionDecision: 'deny',
+            permissionDecisionReason:
+              `「${name}」已经在场了，不用重新派。要它接着演就用 SendMessage 寄给这个名字`
+              + `（它记得之前所有事）。重新派会新起一个失忆的同名角色并顶掉现在这个。`
+              + `真要另起一个角色，换个名字。`,
+          },
+        };
+      }
+      // 白名单仍在派发时收口 —— 演员位文件也在工作区里、模型也能改，判据不因换了
+      // 载体而松：谁改装了演员位的 tools 行，派发时照样被拦。
+      const illegal = await illegalRoleTools(workspaceRoot, t.subagent_type);
+      if (illegal) {
+        return {
+          hookSpecificOutput: {
+            hookEventName: 'PreToolUse',
+            permissionDecision: 'deny',
+            permissionDecisionReason: illegal,
+          },
+        };
+      }
+      if (roster) roster.claim(name);
+      // agent_id ↔ 名字的桥：名字排队等 SubagentStart 那一刻配对（actor-trail.js）。
+      // 不从 tool_result 文本里抠 id —— 那条旧桥 08-28 在生产上断过，症状是署名
+      // 整片落成演员位而没有任何报错。
+      notePendingRoleName(name);
+      // 盖章按**实例名**：byOf / 收件箱 / 板书署名全按名字走，不认演员位（rp-actor
+      // 是位置不是人）。agentId→名字的别名在 PostToolUse 学（hooks/slot-alias.js）。
+      noteToolCaller(toolUseId || input?.tool_use_id, { agentType: name });
+      if (!inferred && t.run_in_background === true && !t.model) return {};
+      // model 参数剥掉（proj_mtd7d4et：glm 会话的 GM 给角色点 sonnet）：角色跟会话
+      // 模型走 —— 免费行的角色拿别名去要订阅模型，打到该会话的 ingress 上游轻则
+      // 400 重则记账错位。演员位定义 model: inherit 是教义，这里是闸。
+      // isolation 一起剥（2026-08-28 真会话：GM 给角色传了 isolation:"worktree"，
+      // meta 里 worktreeCleanlyRemoved:true —— 角色被派进一个**用完就删**的 git 副本。
+      // 常驻角色要在真工作区里活着：它的卡、记忆、板书都在那儿，而 worktree 会被回收。
+      // 跟 model 同一类：模型够得着但不该由它决定的入参，闸上剥掉而不是写进话术。
+      const { model: _dropModel, isolation: _dropIsolation, ...rest } = t;
+      return {
+        hookSpecificOutput: {
+          hookEventName: 'PreToolUse',
+          permissionDecision: 'allow',
+          // 推断出的名字必须回写进 input —— CLI 按它建实例，SendMessage 按它寻址
+          updatedInput: { ...rest, name, run_in_background: true },
+          // nd:rp-prompt
+          additionalContext:
+            `「${name}」已按后台派出${inferred ? '（名字是从你 prompt 里的角色卡认出来的）' : ''}。`
+            + `以后要它说话/接着演，用 SendMessage 寄给 ${name}`
+            + `（它记得之前所有事），不要重新派 —— 重派会新起一个失忆的同名角色顶掉旧的。`,
+        },
+      };
+    }
+
+    if (isResidentRole(t.subagent_type)) {
+      // 旧式一角一定义（会话启动前就躺在 .claude/agents/ 里的角色文件）仍然放行 ——
+      // 它们在初始快照里，派得动。会话中途造新定义的路已随 cast_role 重写关闭
+      //（中途写入的文件只有当时活着的进程认得，resume 后永久 not found —— 08-28 勘定）。
+      // 重派同名角色 = 静默失忆：CLI 的 latest wins 让新角色顶掉这个名字，
+      // 旧角色连同它演过的全部剧情一起失联，而且不报错。只靠提示词劝拦不住，所以硬拦。
+      // ⭐ 工具白名单收口在**派发时**，不是写入时。cast_role 是造角色的正门，但主 agent
+      // 手里有 Write/Edit/Bash，`.claude/agents/` 就在工作区内 —— 手写一份 md 就能
+      // 给自己造一个拿着 publish_site 的"角色"。拦写入拦不干净（Write 拦了还有 Bash，
+      // Bash 拦了还有别的落盘路径），拦派发只有这一个口子。
+      // 见 role-card.js：缺 tools 行 = SDK 语义上继承父代理的全部工具，所以缺失也不放行。
+      const illegal = await illegalRoleTools(workspaceRoot, t.subagent_type);
+      if (illegal) {
+        return {
+          hookSpecificOutput: {
+            hookEventName: 'PreToolUse',
+            permissionDecision: 'deny',
+            // nd:rp-prompt
+            permissionDecisionReason: illegal,
+          },
+        };
+      }
+
+      if (roster && roster.has(t.subagent_type)) {
+        return {
+          hookSpecificOutput: {
+            hookEventName: 'PreToolUse',
+            permissionDecision: 'deny',
+            permissionDecisionReason:
+              `「${t.subagent_type}」已经在场了，不用重新派。要它接着演就用 `
+              + `SendMessage 寄给这个名字（它记得之前所有事）。重新派会新起一个失忆的同名角色`
+              + `并顶掉现在这个，之前演过的全部剧情都会失联。真要另起一个角色，换个名字。`,
+          },
+        };
+      }
+      if (roster) roster.claim(t.subagent_type);
+      // ⭐ 派发这次调用的 toolUseId，正是这个角色之后所有事件的 parentToolUseId
+      //（SDK 用它标"这条消息来自哪个子代理"）。在这儿盖一次章，画布那边就能
+      // 认出"这个事件是墨璃干的"，不用再建第二套映射。见 actor-trail.js
+      noteToolCaller(toolUseId || input?.tool_use_id, { agentType: t.subagent_type });
+      if (t.run_in_background === true && t.name === t.subagent_type) return {};   // 已经对了，别重复改
+      return {
+        hookSpecificOutput: {
+          hookEventName: 'PreToolUse',
+          permissionDecision: 'allow',
+          updatedInput: { ...t, run_in_background: true, name: t.subagent_type },
+          // nd:rp-prompt —— 这句话是 RP 教义的一部分，等提示词层专门过一遍时一起调
+          additionalContext:
+            `「${t.subagent_type}」是常驻角色：已按后台派出并把它的名字钉成 ${t.subagent_type}。`
+            + `以后要它说话/接着演，用 SendMessage 寄给这个名字（它记得之前所有事），不要重新派一次 —— `
+            + `重派会新起一个失忆的同名角色并顶掉旧的。`,
+        },
+      };
+    }
+
     // 显式前台，不动
     if (t.run_in_background === false) return {};
     return {
@@ -82,3 +261,28 @@ export function makePreToolUseGrepContentDefaultHandler() {
     };
   };
 }
+
+/**
+ * PreToolUse：把「这次工具调用是谁发起的」记下来，给 MCP 工具署名用。
+ *
+ * MCP handler 拿不到 agent_id / agent_type（extra 里没有），hook 拿得到 —— 这条旁路是
+ * 板上归属的唯一可信来源。**不要改成从角色文件读**：那份文件模型能改，自称不是实证。
+ * 见 actor-trail.js 的头注释。
+ *
+ * 挂通配（mcp__nodesign__.*，见 hooks.js）：这里曾按「板上写入类才需要」挂手写名单，
+ * 漏过两次（08-26 收件箱三件、08-28 场务四件），每次症状都是 byOf 静默落回 'agent'、
+ * 依赖它的守卫整条失效。一次 Map.set 的代价换「凡用 byOf 的工具永远在闸内」，值。
+ */
+export function makePreToolUseActorStamp() {
+  // 具名函数：装配测试（hooks-assembly.test.js）按 fn.name 认出这道闸挂没挂对
+  return async function actorStamp(input, toolUseId) {
+    noteToolCaller(toolUseId || input?.tool_use_id, {
+      agentId: input?.agent_id || null,
+      // 演员位实例：agent_type 是位置（rp-actor），实例名走别名表解析（08-28 探针
+      // 实证 hook input 没有名字字段）。别名还没学到时落回 agent_type —— 署名难看
+      // 但不失真；下一次 SendMessage/派发的 PostToolUse 会把名字补上。
+      agentType: agentNameOf(input?.agent_id) || input?.agent_type || null,
+    });
+    return {};
+  };
+}

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

@@ -8,7 +8,7 @@
  */
 import path from 'node:path';
 import { toWorkspaceRel } from '../../../lib/workspace-path.js';
-import { kindOfPath, kindDef, KIND_DECK } from '../../../lib/artifact-target.js';
+import { kindOfPath, kindDef, KIND_DECK, KIND_SITE } from '../../../lib/artifact-target.js';
 import { loadToolPrompt } from './tool-prompts.js';
 
 /**
@@ -43,6 +43,9 @@ export function makePreToolUseGetPendingChangesProtocolInjector() {
  * 常驻在 prelude 里是 1.2k tokens，但一次会话里可能一次都用不上。
  */
 export function makePreToolUseAskUserQuestionProtocolInjector() {
+  // 08-28 用户拍板还原：撤掉 08-27 的「提问上板」deny 闸，AskUserQuestion 走回
+  // 侧栏卡片本职。上板问选择仍然可以（nd:controls 是现役件），但那是 agent 的
+  // 版面选择，不再由闸强制。
   let alreadyInjected = false;
   return async (_input, _toolUseId, _options) => {
     if (alreadyInjected) return {};
@@ -77,7 +80,21 @@ export function makePreToolUseHybridReferenceInjector({ workspaceRoot } = {}) {
     const fp = input?.tool_input?.file_path;
     if (typeof fp !== 'string') return {};
     const rel = workspaceRoot ? toWorkspaceRel(fp, workspaceRoot) : fp;
-    const kind = workspaceRoot ? await kindOfPath(workspaceRoot, rel) : KIND_DECK;
+    let kind = workspaceRoot ? await kindOfPath(workspaceRoot, rel) : KIND_DECK;
+    /**
+     * 散装 .html 的内容嗅探（2026-08-30）。kindOfPath 对清单里没有、又不叫
+     * index/canvas 的 .html 一律回落 deck —— 而 site-craft 的试作恰恰规定放
+     * `_drafts/<名字>.html`，于是**每场按方法论走的站点会话，第一笔试作都被
+     * 塞一份 deck 参考**（data-page/importmap/Babel，文不对题），该到的 site
+     * 参考（相对路径铁律/目录约定）反而没到（真案 proj_mtfz7n8p）。
+     * 嗅探判据：deck 有模板 verbatim 军规兜底，正身必带 __nd-deck-wrap /
+     * data-page；一个都没有的散装 .html 当 site 对待。
+     */
+    if (kind === KIND_DECK && path.extname(fp).toLowerCase() === '.html') {
+      const body = typeof input?.tool_input?.content === 'string' ? input.tool_input.content : '';
+      const base = path.basename(fp).toLowerCase();
+      if (base !== 'canvas.html' && !body.includes('__nd-deck-wrap') && !body.includes('data-page=')) kind = KIND_SITE;
+    }
     // 触发条件从「写 .html」改成「写的文件跟这个形态的入口同类型」（2026-08-01）。
     // 写死 .html 的年代只有 deck 和 site，两者入口都是 html 所以恰好没错；非 html 入口的形态
     // 的入口不是 .html，于是它的技术参考**永远不会被注入**，agent 一辈子不知道

package/server/engine/agent/hooks/pre-peer-guard.js

@@ -0,0 +1,88 @@
+/**
+ * hooks/pre-peer-guard.js —— SendMessage 收件人闸（2026-08-26）
+ *
+ * ## 为什么要有
+ *
+ * 把 `SendMessage` 挂进 DEFAULT_TOOL_ALLOWLIST（常驻角色的唯一叫醒方式）的同时，
+ * 也就打开了这个工具的**另一半寻址空间**：同一台机器上其他 Claude 会话。
+ * 2026-08-26 探针实测，`ListAgents` 在这台机器上列出了 4 个 peer session
+ * （站主自己的交互会话、tmux 里的、别的项目的），SendMessage 的 `to` 是自由字符串，
+ * 猜中一个名字就寄得过去。
+ *
+ * 对 Nodesign 这是明确不能有的东西：会话属于不同用户，跨会话寄信 =
+ * 一个用户的 agent 能给另一个人的 agent 递指令。SDK 侧的 `crossSessionInbound`
+ * 只管**收**（我们收不收别人的），管不了**发**。所以发这一侧自己装闸。
+ *
+ * ## 判据（白名单，不是黑名单）
+ *
+ * 只放行三种收件人：
+ *   1. `main`         —— 子代理跟主代理说话（CLI 保留字，寄到主对话）
+ *   2. `rp-*`         —— 本会话的常驻角色（见 cast.js）
+ *   3. `a<16 位十六进制>` —— 本会话某个子代理的 agentId（派发时那条 tool_result 给的，
+ *                        天生只在本会话内有意义）
+ * 其余一律 deny。**黑名单在这里必然漏**：peer session 的名字是别人机器/别人会话
+ * 起的，形状不受我们控制，枚举不完。
+ *
+ * ⚠️ 判据要能被攻：探针 _probe-resident-agent.mjs 里有一条「寄给 peer session 名字
+ * 必须被拒」的反向断言 —— 只看"它没放过坏东西"是不够的，得给它一个**按规定必须拦
+ * 的东西**看它拦不拦（记忆 feedback-verify-guards-by-attacking）。
+ */
+
+/* 判据是「本会话真的派过它」，不是「名字长得像角色」—— 理由见 cast.js 的 createRoleRoster */
+
+/**
+ * 本会话子代理的 agentId 形状（派发 tool_result 里的 `agentId: a67e7b9568aa4698b`）。
+ * ⚠️ 这是 CLI 2.1.237 的实测形状；SendMessage 的 schema 文档把格式写成 `a...-...`
+ * （存在带连字符的变体）。CLI 换版若改长度或加连字符，合法 agentId 会被误拒 ——
+ * 方向是过拦、症状可见（deny 会把原因回显给模型），不会静默放行，所以钉死可接受。
+ */
+const AGENT_ID_RE = /^a[0-9a-f]{16}$/;
+
+/** CLI 保留字：寄到主对话 */
+const MAIN = 'main';
+
+export function makePreToolUseSendMessageRecipientGuard({ roster = null } = {}) {
+  return async (input) => {
+    const to = input?.tool_input?.to;
+    // 形状不对也拒：白名单闸的缺省必须是拒。真 schema 里 `to` 是 string 且
+    // additionalProperties:false，所以今天走不到这里 —— 但那是**CLI 版本事实**，
+    // 不是我们的不变量，翻成 deny 零成本。
+    if (typeof to !== 'string') return deny(String(to));
+    const target = to.trim();
+
+    // 闸判的是 trim 后的值，工具收到的是原值 —— 两个字符串不一致就是两套判据。
+    // allow 时顺手回写（SendMessage matcher 下只有这一个 handler，不踩 updatedInput 互抹的坑）。
+    const pass = () => (target === to ? {} : {
+      hookSpecificOutput: {
+        hookEventName: 'PreToolUse',
+        permissionDecision: 'allow',
+        updatedInput: { ...input.tool_input, to: target },
+      },
+    });
+
+    if (target === MAIN || AGENT_ID_RE.test(target)) return pass();
+    // ⭐ 关键：问名册「这个角色是不是本会话派的」，不是问名字长得像不像。
+    // 形状判据会把裸名放给 CLI 去全机器解析，本会话没有同名 agent 时它会落到
+    // 别人的会话上（多用户共机 + 统一命名教义 = 必然撞名）。
+    // 没接名册时**不退回形状判据**：那是静默降级（闸看起来还在，判据已经换成不安全的那个）。
+    // 漏接线的症状必须是「角色寄不出信」这种看得见的坏，不是悄悄放宽。
+    if (roster?.has(target)) return pass();
+
+    return deny(target);
+  };
+}
+
+function deny(target) {
+  return {
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      // nd:rp-prompt —— 拒绝话术属于 RP 教义，等提示词层专门过时一起调
+      permissionDecisionReason:
+        `收件人「${target}」不在本会话里。SendMessage 只能寄给：main（主对话）、`
+        + `本会话已经派出的常驻角色、或本会话子代理的 agentId（形如 a1234567890abcdef，`
+        + `裸 id 不要带 [ref] 后缀）。这台机器上可能有别人的会话，跨会话寄信一律不放行；`
+        + `角色如果还没派出来（比如服务重启过），先派它，不要直接寄信。`,
+    },
+  };
+}

package/server/engine/agent/hooks/pre-unknown-params.js

@@ -0,0 +1,82 @@
+/**
+ * PreToolUse(nodesign 工具族) —— 未知参数不许静默消失（2026-08-30）
+ *
+ * 病根：SDK 按 tool() 的 schema 校验入参，zod 的 object **默认 strip 未知键**
+ * —— 不报错、不警告、不留痕。于是模型自造的参数连同它承载的内容一起蒸发，
+ * 那一步照跑，只丢半个意图。
+ *
+ * 真会话实锤（全库 358 份转录）：`write_on_board.facts` 直调 18 次 + batch 内 2 次，
+ * 每次都是一长串「本章确立的事实」，一个字没落盘、一句话没报回去。另有
+ * `edit_board.op/on`（模型把单条 op 摊平写）4 次、`edit_board.screenshotAfter` 4 次。
+ *
+ * 工具自己看不见这些键（进 handler 前就没了），只有钩子拿得到原始 tool_input。
+ * 所以探针挂这儿，判据只有一条：**这个键不在该工具的 schema 里**。
+ *
+ * 不 block —— 拦下来会让整批停摆，而多数情况正事是做得成的。做法是放行 + 点名：
+ * 「你传的 X 没有生效，内容没落盘」，模型下一轮自己补。
+ * 归属：`feedback-tool-input-no-silent-drop`（入参不许静默丢/静默改口径）。
+ */
+import { TOOL_PARAM_KEYS } from '../../mcp/index.js';
+
+const BATCH_TOOLS = new Set(['mcp__nodesign__board_batch', 'mcp__nodesign__browser_batch', 'mcp__nodesign__artifact_batch']);
+/** batch 自己的旋钮，不算未知 */
+const BATCH_OWN = new Set(['actions', 'screenshotAfter']);
+
+/**
+ * 一个工具的未知键（schema 没登记过的）。台账里没有这个工具 → 返回空，别瞎报。
+ *
+ * ⚠️ 名字两种写法都要认：台账按 tool() 的**裸名**建（write_on_board），而钩子拿到的
+ * tool_name 是**带前缀**的（mcp__nodesign__write_on_board），batch 里模型两种都写过。
+ * 第一版只查带前缀那一种，于是钩子从来不响 —— 我自己的冒烟测试给 map 塞的正好是
+ * 带前缀的键，把这个洞盖住了（判据本身要先验一遍，量具错得比 bug 还多）。
+ */
+const PREFIX = 'mcp__nodesign__';
+function schemaOf(name) {
+  if (typeof name !== 'string') return null;
+  return TOOL_PARAM_KEYS.get(name) || TOOL_PARAM_KEYS.get(name.startsWith(PREFIX) ? name.slice(PREFIX.length) : `${PREFIX}${name}`) || null;
+}
+function unknownKeysOf(name, input) {
+  const own = schemaOf(name);
+  if (!own || !own.size || !input || typeof input !== 'object') return [];
+  return Object.keys(input).filter((k) => !own.has(k) && !k.startsWith('__'));
+}
+
+export function makePreToolUseUnknownParamsProbe() {
+  return async (input) => {
+    try {
+      const name = input?.tool_name;
+      if (typeof name !== 'string' || !name.startsWith('mcp__nodesign__')) return {};
+      const args = input?.tool_input;
+      if (!args || typeof args !== 'object') return {};
+      const lines = [];
+
+      if (BATCH_TOOLS.has(name)) {
+        for (const k of Object.keys(args)) {
+          if (!BATCH_OWN.has(k) && !k.startsWith('__')) lines.push(`batch 这一层的 \`${k}\` 不是它的参数`);
+        }
+        const actions = Array.isArray(args.actions) ? args.actions : [];
+        actions.forEach((a, i) => {
+          if (!a || typeof a !== 'object') return;
+          const bad = unknownKeysOf(a.name, a.input);
+          if (bad.length) lines.push(`第 ${i + 1} 步 ${a.name} 的 \`${bad.join('`/`')}\``);
+        });
+      } else {
+        const bad = unknownKeysOf(name, args);
+        if (bad.length) lines.push(`\`${bad.join('`/`')}\``);
+      }
+      if (!lines.length) return {};
+
+      const own = BATCH_TOOLS.has(name) ? null : schemaOf(name);
+      const take = own?.size ? `${name.replace(PREFIX, '')} 收的是：${[...own].join(' / ')}。` : '';
+      return {
+        hookSpecificOutput: {
+          hookEventName: 'PreToolUse',
+          permissionDecision: 'allow',
+          additionalContext: `⛔ 这次调用里 ${lines.join('；')} —— 不是这个工具的参数，**整个被丢掉了**，`
+            + `里面的内容一个字都没到工具手上（这一步其余部分照跑）。${take}`
+            + '要保留那些内容就换个真实存在的参数重写一遍，别以为它已经生效了。',
+        },
+      };
+    } catch { return {}; }
+  };
+}

package/server/engine/agent/hooks/pre-workspace-scope-guard.js

@@ -18,8 +18,11 @@
  *   - 自己出错就放行（fail-open）—— 闸崩了不该把整个会话堵死。
  */
 
+import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
+import { CHALK_DIR } from '../../../lib/chalk.js';
+import { ROLE_SLUG_RE } from '../cast.js';
 
 const TARGET_FIELDS = ['file_path', 'path', 'notebook_path'];
 const WRITE_TOOLS = new Set(['Write', 'Edit', 'MultiEdit', 'NotebookEdit']);
@@ -46,6 +49,36 @@ export function checkWorkspaceScope(toolInput, { workspaceRoot, dataRoot, toolNa
     const v = toolInput?.[field];
     if (typeof v !== 'string' || !v) continue;
     const abs = path.resolve(ws, v);          // 相对路径按工作区解析
+    // ⛔ 角色文件是**判据本身**，不许模型手写（2026-08-26 fable 验收）。
+    //
+    // 派发闸靠读 `.claude/agents/<slug>.md` 的 tools 行决定放不放行，可那份文件
+    // 模型自己能改 —— 于是闸校验的和 CLI 真正使用的**不是同一份内容**：
+    //   ① TOCTOU：写宽版 → 结束回合（CLI 缓存了宽版）→ 覆写成窄版 → 同回合派发。
+    //      我们现读磁盘拿窄版放行，CLI 用回合开工的宽版快照 → 角色真拿到外发/花钱工具。
+    //   ② 解析器分歧：重复的 `tools:` 键，我们的正则取第一处、CLI 的 YAML 取最后一处。
+    // 两条都不是对主 agent 提权（它本来就有这些工具），但这条线的正常用法是**导入
+    // 酒馆卡/世界书**——外来文本能借主 agent 的手造出一个拿着外发工具的角色。
+    // 修法只能是「让判据不可被它改」：正门 cast_role 走服务端 fs（不过这道闸），
+    // 模型这侧一律拒。⚠️ Bash 不归这道闸管，那半靠沙盒（isolation.js）。
+    if (isWrite && insideDir(abs, path.join(ws, '.claude', 'agents'))) {
+      return '角色文件不能手写 —— 用 cast_role。'
+        + '那个目录里的文件同时是「这个角色能用哪些工具」的判据，'
+        + '手写等于自己给自己发权限，所以一律拒绝（改已有角色也走 cast_role）。';
+    }
+    // 接续权的文件面（2026-08-27 编排）：角色写的板书文件，主 agent 不许 Edit/Write。
+    // 板上那半（reply_to/chain）在 write-on-board 闸；这里堵的是「直接改文件正文」——
+    // 改别人的台词比接别人的话头更越界。作者看文件自己的 by: 章（harness 盖的，
+    // 角色没有 Write 工具伪造不了）。读不到/没有章 → 放行（fail-open，主 agent 自己的板书本来就能改）。
+    if (isWrite && insideDir(abs, path.join(ws, ...CHALK_DIR.split('/')))) {
+      try {
+        const m = fs.readFileSync(abs, 'utf8').slice(0, 400).match(/^by:\s*(\S+)/m);
+        // 判据统一走 ROLE_SLUG_RE（08-27 审计）：真角色名必过它
+        if (m && ROLE_SLUG_RE.test(m[1])) {
+          return `这份板书是角色「${m[1]}」写的，它的话不是你的稿子 —— 不改、不润色、不代笔。`
+            + '想让它改：把意见寄给它（SendMessage）或让用户直接跟它说。';
+        }
+      } catch { /* 新建/读不到 → 放行 */ }
+    }
     if (insideDir(abs, ws)) continue;         // 自己的工作区，放行
     if (isWrite) {
       if (tempDirs().some(d => insideDir(abs, d))) continue;   // 临时文件随便写

package/server/engine/agent/hooks/resident-role-lifecycle.js

@@ -0,0 +1,100 @@
+/**
+ * hooks/resident-role-lifecycle.js —— 常驻角色名册的退场那一侧（2026-08-26）
+ *
+ * 进场在 `pre-defaults.js`（PreToolUse 的 rp 分支 `roster.claim()`），退场在这里。
+ * 两边分开是因为事件族不同，不是因为职责不同 —— 改任何一边都要看另一边。
+ *
+ * ## 为什么必须有退场
+ *
+ * claim 发生在 **Agent 工具执行之前**（PreToolUse）。派发要是失败了（最现实的路径：
+ * 模型在角色的 `.claude/agents/<name>.md` 写出来之前就先派了这个还不存在的类型），
+ * 名字已经登记进名册，而进程里根本没有这个 agent。后果两条，都很迷惑：
+ *
+ *   1. **收件人闸的洞在这个窄窗口里重开**：闸看名册说「在场」→ 放行 → 而本会话没有
+ *      同名 in-process agent → CLI 的裸名解析回落到**全机范围** → 信可能落到别人的会话。
+ *      （这正是 H1 的病，名册修好了主干，这里是它的补角。）
+ *   2. **这个名字整个会话被 brick**：重派被硬 deny 且文案谎报「已经在场了」，
+ *      SendMessage 又叫不醒，模型只剩换名一条路。
+ *
+ * claim 留在 PreToolUse 不动（它挡住了同一回合并发派两次同名的竞态，这点比挪到
+ * PostToolUse 更值），失败时在这里补一次 release —— 进场乐观、退场兜底。
+ */
+
+import { isResidentRole, isSlotType } from '../cast.js';
+import { agentNameOf, noteAgentName, takePendingRoleName } from '../actor-trail.js';
+import { noteRoleStart, noteRoleFinish } from '../stage-status.js';
+
+/**
+ * SubagentStart：把这个 agent_id 认成刚派出去的那个角色（2026-08-29）。
+ *
+ * hook input 只有 `agent_id` + `agent_type`（演员位），没有实例名 —— 名字在派发闸
+ * 那一刻就知道了，所以闸把它排进队列（actor-trail.notePendingRoleName），这里取队头
+ * 配对。**这是署名的正门**：harness 在起飞那一刻亲手给的 id，不解析任何模型可写的文本。
+ *
+ * 只认演员位起飞：干活型子代理（vision-checker 那类）不进别名表。
+ */
+export function makeSubagentStartRoleAlias({ projectId = null } = {}) {
+  return async function subagentStartRoleAlias(input) {
+    if (!isSlotType(input?.agent_type) || !input?.agent_id) return {};
+    const known = agentNameOf(input.agent_id);        // 已经认过（唤醒重入）
+    const name = known || takePendingRoleName();
+    if (!name) return {};
+    if (!known) noteAgentName(input.agent_id, name);
+    noteRoleStart(projectId, name);                  // 台上一览：它开始写了
+    return {};
+  };
+}
+
+export function makePostToolUseFailureRoleRelease({ roster = null } = {}) {
+  return async (input) => {
+    if (!roster) return {};
+    // 演员位派发失败：登记的是实例名（tool_input.name），撤的也是它
+    const type = isSlotType(input?.tool_input?.subagent_type)
+      ? input?.tool_input?.name
+      : input?.tool_input?.subagent_type;
+    if (!isResidentRole(type)) return {};
+    if (!roster.release(type)) return {};
+
+    // 「还没拾取到」跟「角色不存在」是两回事，指引也不同。前者**必须原样重派**，
+    // 而模型不会自己这么做：2026-08-26 探针里它撞了 not found 之后既没重试，
+    // 还回了一句「已派」谎报成功 —— 所以这句话要说得比"你可以再派一次"硬。
+    const notFound = /not found/i.test(String(input?.error || ''));
+    return {
+      hookSpecificOutput: {
+        hookEventName: 'PostToolUseFailure',
+        // nd:rp-prompt
+        additionalContext: notFound
+          ? `「${type}」没派出来：CLI 还没拾取到它的角色文件（监视器有几秒防抖）。`
+          + `**原样再派一次**，别改参数、别跳过、更不要说"已派"—— 它现在还没上场。`
+          : `「${type}」没派出来，已经把这个名字从在场名册里撤了 —— 你可以再派一次。`
+          + `（如果是因为这个角色还不存在，先用 cast_role 把它的角色文件写出来。）`,
+      },
+    };
+  };
+}
+
+/**
+ * SubagentStop：角色收笔了，记一笔进台上一览（2026-08-26 建；08-29 改写）。
+ *
+ * 08-29 之前这里做两件事：标「散场」+ 用 systemMessage 教主控怎么召回。两件都随
+ * 常驻/散场概念一起退役 —— 新回路里角色本来就写一段结束一轮，「结束」是正常节拍
+ * 不是事故。而且 systemMessage 这条路 08-28 真会话里查无痕迹（SDK 的 SubagentStop
+ * 只有 additionalContext，且按类型定义那是**发给子代理**的），主持人真正收到的是
+ * SDK 自带的 task-notification。所以这里不再试图跟主持人说话，只记账 ——
+ * 状态由每回合状态块的「台上」一节统一注入（user-prompt-submit.js）。
+ *
+ * ⛔ **不 release 名字**：角色收笔 ≠ 不存在了。它的转录还在，SendMessage 叫得回来；
+ * 把名字放回去等于允许重派，而重派会新起一个失忆的同名角色顶掉它。
+ */
+export function makeSubagentStopRoleNotice({ projectId = null } = {}) {
+  return async (input) => {
+    // 角色位实例：agent_type 是位置（rp-role），实例名走别名表。别名没学到就跳过
+    // （不知道是谁收的笔 —— 别把 'rp-role' 当角色记进台上一览）。
+    const name = isSlotType(input?.agent_type)
+      ? agentNameOf(input?.agent_id)
+      : input?.agent_type;
+    if (!name || !isResidentRole(name) || isSlotType(name)) return {};
+    noteRoleFinish(projectId, name, input?.last_assistant_message || null);
+    return {};
+  };
+}

package/server/engine/agent/hooks/slot-alias.js

@@ -0,0 +1,30 @@
+/**
+ * hooks/slot-alias.js —— 唤醒时重新认一遍角色的 agent_id（2026-08-28 建；08-29 收窄）
+ *
+ * 派发那条路 08-29 搬去 `SubagentStart`（harness 亲手给 id，不解析文本，见
+ * resident-role-lifecycle.js 的 makeSubagentStartRoleAlias）。这里只剩**唤醒**一条：
+ * `SendMessage({to:"rp-x"})` 的结果 JSON 带 `resumedAgentId`，服务器重启后别名表
+ * 清零、而角色还活着时，靠这一条重新学回来。
+ *
+ * 匹配用正则怼序列化文本而不是解构对象：tool_response 的形状（数组/对象/字符串）
+ * 随 SDK 版本漂，id 的形状（十六进制串）比包装稳定得多。
+ */
+
+import { isSlotType, ROLE_SLUG_RE } from '../cast.js';
+import { noteAgentName } from '../actor-trail.js';
+
+// 引号写成 \\?"：结果 JSON 常作为字符串再被包一层（stringify 转义成 \"），两层都认
+const RESUMED_RE = /\\?"resumedAgentId\\?"\s*:\s*\\?"([0-9a-f]{8,32})\\?"/;
+
+export function makePostToolUseSlotAliasHandler() {
+  return async function slotAlias(input) {
+    const t = input?.tool_input;
+    if (!t || typeof t !== 'object') return {};
+    // 按名寄信的恢复结果 → 重新学（覆盖重启后别名表清零的窗口）
+    if (typeof t.to === 'string' && ROLE_SLUG_RE.test(t.to) && !isSlotType(t.to)) {
+      const m = RESUMED_RE.exec(JSON.stringify(input?.tool_response ?? ''));
+      if (m) noteAgentName(m[1], t.to);
+    }
+    return {};
+  };
+}