JianFeeeee
c774904c0c
第二步：让 ZCode 上的 Bash/Write/Edit 授权走 AgentMail 的人工审批，
而不是只靠本地界面。
钩子契约从 CLI 产物里逆出来（不猜协议）：
- 输入走 stdin：{hook_event_name, tool_name, tool_input, session_id, permission_mode…}
- 输出走 stdout，schema **严格**：{"decision":"approve"} / {"decision":"block","reason"}
多一个键就会报 "Hook stdout failed HookJSONOutput schema validation"
- 空输出 / 不以 { 开头 = 不表态；exit 2 = 拒绝；其它非零 = 钩子失败
- 注入的环境变量含 ZCODE_PLUGIN_ROOT / ZCODE_PLUGIN_DATA / ZCODE_SESSION_ID
（MCP 配置里用 ZCODE_SESSION_ID 反而会抛「需要运行时会话上下文」）
档位判定与 pi 桥逐条对齐（plan 直接拒 / workspace 问人 / full 批准），
判定逻辑抽成纯函数 lib/hook-policy.mjs 以便穷举：
其中 full 档必须**返回批准而不是不表态** —— 钩子一旦触发说明 ZCode 本会去问人，
不表态等于让那个询问照常发生，full 档就退化成了 workspace 档。
钩子自己开 SSE 等决定，不依赖桥进程：网关的 SSE 是扇出的
（clients 按唯一 id 存，SendToAgent 推给该 Agent 的所有客户端），
一次性进程也能订阅到自己那条 permission_decision。这样交互模式下同样可用
（人自己开着 ZCode 干活时并没有桥在跑）。先建连再发请求是有意的：
反过来会有一个窗口，人在窗口内点的同意推送给当时还不存在的客户端。
fail closed 但区分模式：永久失败（409/4xx）一律拒绝；暂时失败在
AGENTMAIL_SESSION_ID 非空（邮件驱动、没有本地界面兜底）时拒绝，
交互模式则不表态让人就地决定。
「一直同意」落盘（lib/grants-file.mjs）：钩子是一个事件一个进程，
不落盘那个选项就是骗人的。判定仍交给共用的 permission-grants.js。
共用模块同源范围扩到 9 个（新增 permission-mode / relay-key /
permission-grants / sse-client）—— 档位语义与决策判定分叉会让「同意」
在 ZCode 上悄悄变成另一种意思。
验证：
- 单元 229/229（新增 hook-policy 14 项、grants-file 8 项，含反向对照）
- 共用模块四方同源检查通过
- 授权桥端到端 5/5，全部带反向对照：
同意→approve；拒绝→block 且原因必须来自人的拒绝（不能是超时兜底）；
plan 档拒绝且**不产生**任何权限邮件；无人可问(409)→fail closed；
非守卫工具→不表态
- `zcode plugins list` → agentmail@inline [enabled]，hooks: 1，
mcp: plugin:agentmail:agentmail
我自己写错的两处判据（都已修，值得记下）：
1. 待决权限列表里有历史积压（实测 6 条，含其它 Agent 的条目），
只按「第一条新的」取会拿到无关请求 —— 于是人点了同意而钩子在等自己那条，
最后超时。第一版还把这个超时误报成「拒绝路径通过」。
现在按「启动前快照差集 + session_id + agent_name」三重过滤。
2. 「无人可问」控制组最初传了个非 UUID 的 session id，走的是 400（参数错），
验不到 409 那条真实路径。改为真的造一条只有 Agent 没有人类的会话。
93 lines
3.7 KiB
JavaScript
93 lines
3.7 KiB
JavaScript
/**
|
||
* ZCode 授权钩子的**判定策略**（纯函数，不碰 I/O）。
|
||
*
|
||
* 语义与 pi 桥的 `permissionExtension()` 逐条对齐 —— 档位判定是给产品定的，
|
||
* 不是给平台定的：同一个「plan 档」在 ZCode 上必须是同一个意思，
|
||
* 否则同一封邮件派到两个 Agent 上会得到两种行为，而人只会以为自己派错了。
|
||
*
|
||
* 只把「该做什么」算出来，真正的 I/O（问人、等决定、写 stdout）留在钩子入口，
|
||
* 于是这里可以被穷举测试。
|
||
*/
|
||
|
||
import {
|
||
normalizeMode,
|
||
DEFAULT_MODE,
|
||
MODE_FULL,
|
||
MODE_PLAN
|
||
} from './permission-mode.js';
|
||
|
||
/**
|
||
* 被守卫的工具名。
|
||
*
|
||
* 对应 pi 桥的 `GUARDED = new Set(['bash', 'write', 'edit'])`。
|
||
* ZCode 的工具名是首字母大写，且 `Write`/`Edit` 有一个来自 `ApplyPatch` 的别名，
|
||
* 所以这里做大小写无关匹配并收进 `applypatch`。
|
||
*/
|
||
const GUARDED = new Set(['bash', 'write', 'edit', 'applypatch']);
|
||
|
||
/** ZCode 的钩子事件名（七个之一）。本模块只关心这一个。 */
|
||
export const PERMISSION_EVENT = 'PermissionRequest';
|
||
|
||
export function isGuardedTool(toolName) {
|
||
return GUARDED.has(String(toolName ?? '').trim().toLowerCase());
|
||
}
|
||
|
||
/**
|
||
* 算出这次钩子该采取的动作。
|
||
*
|
||
* @param {{event?: string, toolName?: string, mode?: string}} input
|
||
* @returns {{action: 'none'|'approve'|'block'|'ask', reason?: string}}
|
||
*
|
||
* - `none`：不表态。ZCode 会继续它自己的权限流程（该问谁就问谁）——
|
||
* 这是「不该由我们插手」的唯一正确表达方式；返回 approve 会越权放行，
|
||
* 返回空字符串 stdout 也一样是「不表态」，但显式写出来更清楚。
|
||
* - `approve` / `block`：直接给结论。
|
||
* - `ask`：交给 AgentMail 问人，等决定。
|
||
*/
|
||
export function decidePolicy({ event, toolName, mode } = {}) {
|
||
if (event !== PERMISSION_EVENT) return { action: 'none' };
|
||
|
||
// 非守卫工具不表态。钩子的 matcher 已经在 hooks.json 里限定了范围，
|
||
// 这里再判一次是纵深防御：matcher 被人改宽时不会静默变成「什么都批准」。
|
||
if (!isGuardedTool(toolName)) return { action: 'none' };
|
||
|
||
const m = normalizeMode(mode) || DEFAULT_MODE;
|
||
|
||
// full 档：发件人已声明全权，pi 桥在这一档直接不拦截。
|
||
// ZCode 上「不拦截」的等价物就是批准 —— 钩子一旦触发，ZCode 本会去问人，
|
||
// 而我们正是要在这一档免掉那个询问。返回 none 会退回询问，语义就反了。
|
||
if (m === MODE_FULL) return { action: 'approve' };
|
||
|
||
// plan 档：该档语义是「只读不动手」，没什么可问人的。
|
||
// 文案与 pi 桥同源，模型收到的措辞一致。
|
||
if (m === MODE_PLAN) {
|
||
return {
|
||
action: 'block',
|
||
reason:
|
||
`plan 档下不允许执行 ${toolName}。本档只允许读与查，请把方案写在回信里。` +
|
||
`如需动手请让发件人把档位改成 workspace。`
|
||
};
|
||
}
|
||
|
||
return { action: 'ask' };
|
||
}
|
||
|
||
/**
|
||
* 把一次工具调用摘要成人能判断的文本。
|
||
*
|
||
* 与 pi 桥的 `describeToolCall` 同源（同样的字段截断长度），
|
||
* 差别只在 ZCode 的入参字段名（它给的是 `tool_input`）。
|
||
*/
|
||
export function describeToolCall(toolName, toolInput) {
|
||
const input = toolInput && typeof toolInput === 'object' ? toolInput : {};
|
||
const name = String(toolName ?? '').toLowerCase();
|
||
if (name === 'bash') {
|
||
return `命令：\n${String(input.command ?? '').slice(0, 800)}`;
|
||
}
|
||
if (name === 'write' || name === 'edit' || name === 'applypatch') {
|
||
const p = input.file_path ?? input.path ?? input.filePath ?? '(未给出)';
|
||
return `文件：${p}`;
|
||
}
|
||
return JSON.stringify(input).slice(0, 800);
|
||
}
|