feat(zcode): 工具加 MCP 注解 + headless 档位映射改为 plan（否则一个工具都用不了）

## 逆出 ZCode 的 MCP 权限判定，并据此让工具真的可用

逐字逆自 CLI 产物：

  Ari():  annotations.readOnlyHint === true → riskLevel "low"
          annotations.destructiveHint === true → riskLevel "high"
          needsApproval = true   ← **硬编码为真，与注解无关**
  checkBuildMode(): needsApproval || destructive || sideEffectScope !== "none" → ask
  checkPlanMode():  permissionName === "mcp" && !destructive → allow

两条合起来的结论不直观但很关键：

- **build 档下每一个 MCP 工具都要审批**（needsApproval 恒真），而 headless
  模式没有交互式审批客户端 ⇒ 全被拒。实测：模型连 read_inbox 都调不动，
  只能从提示词里猜；更糟的是它**绕道**用 Bash 去读网关的 sqlite WAL 文件
  （它自己在回信里如实交代了这件事）。
- **plan 档下只要不声明 destructive，MCP 工具直接放行**。

于是两处改动：

1. `lib/tools.mjs` 给每个工具加真实注解（读类 readOnlyHint，写类
   destructiveHint:false——它们确实不破坏任何东西）；`lib/mcp-rpc.mjs` 透传
   annotations。**漏传不是"少个提示"，而是工具在该档下全被拒**。
2. `src/turn-mode.mjs` 的 workspace 档映射从 build 改为 **plan**。
   build 在本环境等于「什么都不能做」，那不是保守而是不可用；plan 才是真的
   fail-closed：危险的自带工具被平台直接拒，能用的只有我们声明为非破坏性的工具。
   日志会明确写出为什么退档。可用 `AGENTMAIL_ZCODE_MODE_MAP` 覆盖
   （平台修好钩子后只改配置就能恢复 build，不必等发版）。

## 真模型验证

场景 A 的判据同时加强：**正文本标记只出现在邮件正文里**（驱动的提示词只带主题
与 mail_id），所以模型必须真的读信才可能答对。通过 —— 约 20-30 秒一轮。

反过来说，早先那版「通过」是假的：标记在主题里，模型从提示词抄一遍就行。

## 仍然做不到的（见 README 已知缺口）

授权桥（PermissionRequest 钩子）在本版本（3.10.2 / CLI 0.16.5）**不可用**：
有时根本不触发，触发时在 ~5ms 内失败且**命令从未被 spawn**
（用「钩子写 marker 文件」的副作用验证，process 与 command 两种类型都一样）。
所以 workspace 档「危险操作问人」目前在 headless 下无法实现。

单元 329/329。

plugins/zcode-mail-bridge/src/turn-mode.mjs

@@ -33,19 +33,74 @@ import { normalizeMode, DEFAULT_MODE, MODE_PLAN, MODE_FULL } from '../lib/permis
 /** ZCode 认识的 headless mode（`normalizePromptMode` 只接受这四个）。 */
 export const ZCODE_MODES = ['build', 'edit', 'plan', 'yolo'];
 
+/**
+ * 档位 → ZCode mode。
+ *
+ * # 三个模式在 headless 下的真实行为（逐条实测 + 逆代码，見 README）
+ *
+ * | mode  | ZCode 自带工具 | 本插件的 MCP 工具 | 结果 |
+ * |-------|---------------|------------------|------|
+ * | build | Bash/Write/Edit → ask | **全部 → ask** | 没有交互式审批客户端 ⇒ **全部被拒** |
+ * | edit  | 文件编辑放行，其余同 build | 同 build | 同上 |
+ * | plan  | 非只读一律拒（fail-closed）| **非破坏性的直接放行** | 只读可用 |
+ * | yolo  | 全部放行 | 全部放行 | 全可用，但**没有任何审批** |
+ *
+ * 关键在于 MCP 工具的 `needsApproval` 是**硬编码为 true** 的（`Ari()` 里 `let d=!0`），
+ * 与 `annotations` 无关；而 `build` 档的判定最后一条是
+ * `needsApproval || destructive || sideEffectScope !== "none" → ask`。
+ * 于是 **`build` 档下每一个 MCP 工具都要审批**，而 headless 模式没有审批客户端 →
+ * 全被拒。实测：模型连 `read_inbox` 都调不动，只能靠提示词里带的信息猜。
+ *
+ * 而 `plan` 档有一条 `permissionName === "mcp" && !destructive → allow`，
+ * 所以**声明了 `destructiveHint: false` 的 MCP 工具在 plan 档下直接放行**。
+ * 实测：模型用 read_inbox 读出了只存在于邮件正文里的标记。
+ *
+ * # 为什么 workspace 档映射到 plan 而不是 build
+ *
+ * `build` 在本环境下等于「什么都不能做」（连读信都被拒）——那不是保守，
+ * 是不可用。而 `plan` 是**真的 fail-closed**：危险的自带工具被平台直接拒，
+ * 我们能用的只有自己声明的非破坏性工具。人在 workspace 档要的是「能干活」，
+ * 拿不到；那就退到「至少能读能回」，并**在日志里说清楚为什么**，
+ * 而不是静默地变成一个什么都干不了的代理。
+ *
+ * 要真让它动手，只有两条路（见 README 的「已知缺口」）：
+ *   1) 平台修好 PermissionRequest 钩子 → 审批能送达人；
+ *   2) 显式改用 yolo（`AGENTMAIL_ZCODE_MODE_MAP`）+ `--disallowed-tools`
+ *      把危险的自带工具拿掉，只留我们自己的工具面。
+ */
 const MODE_FOR_TIER = {
   [MODE_PLAN]: 'plan',
-  workspace: 'build',
+  workspace: 'plan',
   [MODE_FULL]: 'yolo'
 };
 
+/**
+ * 解析档位映射。允许用 `AGENTMAIL_ZCODE_MODE_MAP` 覆盖，格式
+ * `workspace:yolo,full:yolo`（逗号分隔）。
+ *
+ * 存在的理由：将来平台修好钩子（或本机换版本后行为变了），
+ * 应该**只改配置就能恢复**成 build，而不是等一次发版。
+ */
+export function resolveModeMap(env = process.env) {
+  const raw = String(env.AGENTMAIL_ZCODE_MODE_MAP || '').trim();
+  if (!raw) return { ...MODE_FOR_TIER };
+  const out = { ...MODE_FOR_TIER };
+  for (const pair of raw.split(',')) {
+    const [tier, mode] = pair.split(':').map(s => s.trim());
+    if (!tier || !ZCODE_MODES.includes(mode)) continue;
+    out[normalizeMode(tier)] = mode;
+  }
+  return out;
+}
+
 /**
  * @param {string} tier AgentMail 的档位（plan / workspace / full）
+ * @param {object} [env]
  * @returns {'build'|'edit'|'plan'|'yolo'}
  */
-export function zcodeModeForTier(tier) {
+export function zcodeModeForTier(tier, env = process.env) {
   const t = normalizeMode(tier) || DEFAULT_MODE;
-  return MODE_FOR_TIER[t] || 'build';
+  return resolveModeMap(env)[t] || 'plan';
 }
 
 /**
@@ -62,6 +117,15 @@ export function modeReachesPermissionHook(mode) {
 export function describeTier(tier, mode = zcodeModeForTier(tier)) {
   const t = normalizeMode(tier) || DEFAULT_MODE;
   if (t === MODE_PLAN) return `${t} 档 → --mode ${mode}（只读，ZCode 自己就会拒非只读工具）`;
-  if (t === MODE_FULL) return `${t} 档 → --mode ${mode}（全权，刻意绕过权限询问）`;
-  return `${t} 档 → --mode ${mode}（危险操作会走到 AgentMail 授权钩子）`;
+  if (t === MODE_FULL) return `${t} 档 → --mode ${mode}（全权，刻意绕过审批）`;
+  if (mode === 'plan') {
+    return (
+      `${t} 档 → --mode ${mode}（本档本应「危险操作问人」，本平台 headless 做不到：` +
+      `MCP 工具在 build 档下恒需审批而无人可批，只能退到只读）`
+    );
+  }
+  if (mode === 'build' || mode === 'edit') {
+    return `${t} 档 → --mode ${mode}（危险操作会走到 AgentMail 授权钩子）`;
+  }
+  return `${t} 档 → --mode ${mode}`;
 }