feat(acp-bridge): session/new 透传 toolAllowlist/toolDenylist

[jasonQin6]

基于 #52（session/new model 钉定）之上的增量提交，只评审最后一个 commit（20fa2b0）。

动机

0.16 stdio 下 mode=plan 是 advisory——工具照常自动执行，调用方只能在事后（快照 diff）发现越界。会话级前置只读目前没有手段：引擎 session/create 的 toolAllowlist/toolDenylist 映射 PermissionService 的硬 deny/allow，不经过权限模式判断、hook 也不能覆盖，正是这个缺口需要的原语。

变更

session/new 新增可选 toolAllowlist / toolDenylist（非空字符串数组，空条目剔除）原样并入 session/create 参数。缺省、空数组或非数组时 create 参数与旧版逐字一致（向后兼容：不传名单的调用方行为不变；传了名单而后端拒收未知字段时，create 的报错如实透出）。

测试

• 新增回归用例：C5（透传 + 空条目剔除）、C5a（缺省 / 空数组 / 非数组 → create 参数不变）
• 全套 pytest tests/ -q → 549 passed + 34 subtests

[tizerluo]

感谢这个增量——动机踩得很准（plan 模式是 advisory 的痛点本仓在 README「重要限制」里也有记录）。结论：修后可合并（两条 P1 是同一处校验语义的正面缺口，改动量小）。以下是维护者侧独立审查；独立代码审查 agent 的意见见下一评论。

核心声明活体验证（本机 0.16.9 官方 app-server）

声明	验证	结果
create 接受 toolDenylist	活体 session/create 带 toolDenylist:["Write","Edit"]	✅ 接受，会话正常创建
allow+deny 同传	活体同传两键	✅ 后端不拒（优先级见下）
测试声明	本地 worktree 实跑（含叠层的 #52）	✅ 549 passed，ruff 干净
与 main 兼容	GitHub mergeability	✅ MERGEABLE（基于 #52）

意见

应修（合并前）：

1. 非法输入静默忽略 = 对安全原语 fail-open（与下一评论 P1-1 一致，我读 diff 时的同款担忧）："toolDenylist": "Write"（常见手滑：字符串而非数组）会被静默跳过、不报错无日志——调用方以为只读已生效，实际全量放行。C5a 还把这个行为钉成了契约。旧客户端从不发这两个键，改成「键存在但值非法 → -32602」不会破坏任何现有调用方；且同一作者在 feat(acp-bridge): session/new 可选 model 锁定会话模型 + setModel 对象形态修复 (0.16 实测) #52 的 setModel 就是严格校验风格，两 PR 应一致。元素校验同理：非字符串元素（[123]/[null]）当前被 str() 强转成无效名后静默不生效。
2. 空名单语义需要定契约：当前实现把空数组/全空条目当「未提供」丢弃。而独立审查从引擎 bundle 找到的语义是：空 allowlist = 一个工具都不放行（deny-all）、空 denylist 才是无限制。也就是说显式请求「锁死」的调用方（toolAllowlist: []）拿到的是全量访问——方向恰好反了。建议：键存在即原样透传 []（保留引擎 deny-all 语义，也符合 PR 标题「透传」），或显式 -32602 拒绝空名单，并加 C5b 钉死所选语义。

建议：

3. README/SKILL.md 未同步（增量只改了桥和测试）：session/new 的 README 扩展说明只有 feat(acp-bridge): session/new 可选 model 锁定会话模型 + setModel 对象形态修复 (0.16 实测) #52 的 model；且 README「重要限制」第 7 条（yolo 权限风险）正好应该交叉引用本 PR 的 toolDenylist 作为缓解手段——这是本 PR 对仓库安全叙事的真正价值，不写出来读者发现不了。
4. 同传优先级写进文档：引擎语义是「交集、deny 优先」（内置与 MCP 两条注册路径一致）——桥不需要拒绝同传，但调用方不该靠猜。
5. Node REPL 绕过提示：README 第 122 行记录过「只禁 Write/Edit/Bash 可被 Node REPL 族 execSync 打穿」。docstring 把 toolDenylist 称为「唯一会话级前置只读手段」时，应附建议名单（含 js/mcp__node_repl__js* 族），并请作者核实 ACP 会话的实际注册工具集。
6. 机制归属小误：docstring 写「映射 PermissionService」，实际（bundle 证据）是工具集注册级物理过滤（先于权限层、与 mode 无关）；PermissionService 是 settings.permission.* 驱动的另一条路径。行为断言对，心智模型建议改准。

合并顺序

本 PR 叠在 #52 上：先合 #52，本 PR rebase 后再走（若 #52 按审查意见修改，本 PR 需要跟着动 _on_session_new 区域）。

[tizerluo]

独立代码审查（code-reviewer agent）意见——由维护者代发，与上一条维护者审查互不参考。

结论：修后可合并（无 P0；2 条 P1 校验语义 + 5 条 P2 文档/验证）

一、对作者声明的引擎侧核实（bundle 证据）

作者声明	核实结果
session/create 接受两名单且为严格 schema	✅ create 入参 zod schema 含 toolAllowlist/toolDenylist: array(string).optional()，整对象 .strict()——未知字段会被拒，「报错如实透出」在 0.16.9 成立
映射 PermissionService 硬 allow/deny	效果成立、归属不准确：实际路径是工具集级注册过滤（内置工具与 MCP 工具注册均按 allowedTools/disallowedTools 物理过滤，先于权限层、与 mode 无关）；PermissionService 是 settings.permission.* 驱动的另一条路径，create 字段并不流入它
mode=plan 是 advisory	✅ 与仓库既有文档（upgrade-0.16.1-spec / README）记录一致
allow+deny 同传谁优先（作者未说明）	引擎有确定语义：交集、deny 优先（两条路径一致）——桥无需拒绝同传，但应写进文档
空数组语义（作者未说明）	⚠️ 与桥的处理相反：引擎对 toolAllowlist: [] 按 new Set([])（truthy）处理，过滤条件对所有工具成立——空 allowlist = 禁用全部工具；空 denylist 才等于无限制

二、问题清单

P1（应修）

1. zcode-acp-bridge:1358-1364（测试同见 test_app_server_methods.py:446-459）— 输入校验对安全原语是 fail-open：① 非列表值（常见误写 "toolDenylist": "Write"）被静默忽略，不报错无日志，调用方以为只读已生效实际全量放行，C5a 还钉死为契约；② str(item) 强转：[123]→"123"、[null]→"None"，引擎只做字符串集合匹配，不认识的名字静默不生效（denylist 即无声放行）；③ 只对 str(item).strip() 判空、存回未 strip 原串：" Write" 在引擎 allowlist 侧（不 trim）静默失效。为什么必须修：旧客户端从不发送这两个键，「键存在但值非法 → -32602」不破坏任何既有调用方，向后兼容论据不成立；同 PR 内 setModel（feat(acp-bridge): session/new 可选 model 锁定会话模型 + setModel 对象形态修复 (0.16 实测) #52）已是严格风格，此处不一致。修法：key not in params 才跳过；否则要求非空字符串数组（元素 isinstance str 且 strip 非空），非法即 -32602；C5a 字符串用例改期望；docstring 补齐契约。
2. zcode-acp-bridge:1360-1363 — 显式空名单的语义反转：toolAllowlist: []（及 [""]）被桥当作「未提供」，create 参数里没有该键——而引擎把「存在空 allowlist」解释为一个工具都不放行。显式请求锁死的调用方拿到的是全量工具访问，只有一行未打印的 log 作信号。修法：键存在时原样透传 []（保住引擎 deny-all 语义，也符合「透传」标题），或产品上不接受空名单则显式 -32602；补 C5b 钉死。与 P1-1 可合并为一次契约修但语义不同，故分列。

P2（建议）

3. 文档未同步：README 的 session/new 扩展说明只写了 feat(acp-bridge): session/new 可选 model 锁定会话模型 + setModel 对象形态修复 (0.16 实测) #52 的 model；README「重要限制 docs: 同步 skill 到 App 3.3.0 (补 prompt/enhance) #7」（yolo 权限风险）未指向本 PR 的 toolDenylist 缓解手段；SKILL.md 同步缺失。
4. precedence 未文档化：引擎证据是交集/deny 优先——桥不需要拒绝同传，但 docstring/README 应写明（并按仓库惯例附实测出处）。
5. 旧版 fail-open 前提未验证：「后端拒收未知字段」目前只有 0.16.9 的 .strict() 证据；仓库支持 0.16.1/0.16.5 且有「同号构建漂移」先例——若某构建既不认识字段又不 strict，名单会被静默丢弃且桥无从感知。建议按 docs/recheck-*.md 惯例补一次 0.16.1 活体验证，或在校验失败路径给出可诊断文案。
6. Node REPL 绕过风险未提示：README 第 122 行记录过 Node REPL 族可打穿「只禁 Write/Edit/Bash」的名单；docstring 把 toolDenylist 称为「唯一会话级前置只读手段」时应附建议名单（含 js/mcp__node_repl__js*），并核实 ACP 会话的实际工具集（未作为已证漏洞，但需作者确认）。
7. 测试覆盖：缺非字符串元素（[null]/[123]/嵌套）、带空白字符串、全空条目列表 [""]、仅传单边名单；P1-2 契约定了以后补空数组用例；C5a 字符串用例在修法落地后改期望。

P3（提示）

8. create 失败统一映射 -32603 "zcode create failed: ..."（既有行为，D7 有意钉死），后端因未知字段返的 -32602 丢码只留文案——调用方想程序化识别「后端不支持该字段」只能字符串匹配；可在 message 带后端原始 code。
9. docstring「映射 PermissionService」与 bundle 证据不符，建议改准心智模型。
10. str(item) 在列表推导里求值两次，纯风格，随 P1-1 重写消失。
11. 流程：20fa2b0 父提交是 feat(acp-bridge): session/new 可选 model 锁定会话模型 + setModel 对象形态修复 (0.16 实测) #52 的 head，两 PR 改同一函数/测试区域——需先合 feat(acp-bridge): session/new 可选 model 锁定会话模型 + setModel 对象形态修复 (0.16 实测) #52 再 rebase 本 PR；feat(acp-bridge): session/new 可选 model 锁定会话模型 + setModel 对象形态修复 (0.16 实测) #52 若按评审修改则本 PR 跟着动。

未发现问题的维度：性能（O(n) 单遍归一）；注入（工具名作数据下发，日志只记数量不泄内容）；崩溃/边界（非 dict/缺键/空列表不抛异常）；向后兼容的「缺省」分支经 C5a 与代码核实成立。

亮点：增量 commit 隔离干净；「缺省绝不改变旧行为」用 C5a 多形态断言钉死，超出常见测试质量；日志只输出条目数；对引擎行为的调研基本可被 bundle 证实（strict schema、工具集级硬过滤）——对首个外部 PR 而言证据意识很强。

---

给贡献者的一句话：这是一份调研扎实、测试自觉的高质量 PR——增量隔离清楚、兼容性有断言护住，感谢把引擎行为吃透后再动手；需要补齐的是把「名单是安全原语」贯彻到非法输入与空输入的处理（fail-closed 而非静默放行），并把 README/SKILL.md 与 precedence、Node REPL 提示一起补上，改完即可合。

[tizerluo]

感谢这个增量，同样先道个歉：搁了近两周才被看到是我们的问题；为不再耽误，我们在你的分支上直接代为修复后合并了（rebase 到 #52 的修复版之上，你的提交经 amend 保留了你的作者署名，446737c）。

处理经构

1. 两轮独立审查：核心机制正确、「缺省不改变旧行为」的纪律被测试钉得很扎实；两条 P1 集中在校验语义——非法输入静默忽略（对安全原语 fail-open）与空名单语义反转（桥丢弃空数组，引擎语义是空 allowlist=全部禁用）；
2. 代修内容（amend 进你的提交）：严格校验 fail-closed（键存在必须是字符串数组、元素 strip 后非空，非法本地 -32602 且零后端调用、连子进程都不拉起）+ 字面空数组原样透传（保留引擎 deny-all 语义）+ 文档同步（README/SKILL：交集 deny 优先、空数组语义、Node REPL 族建议名单、限制docs: 同步 skill 到 App 3.3.0 (补 prompt/enhance) #7 交叉引用）+ docstring 机制归属修正（实际是工具集注册级物理过滤而非 PermissionService，引擎 bundle 可证）+ C5 系测试扩为 6 例；
3. 修复后活体验证：toolDenylist: "Write"（非法形态）→ -32602 且零会话创建；model + toolDenylist（8 项含 Node REPL 族）→ 会话创建、模型锁定成功、真实 turn end_turn。已合并。

贡献记录

你的提交以原始作者署名保留在 main 历史（合并提交 a26f8be）。工具名单这个「会话级前置只读」原语是本仓安全叙事里缺的一块（与 review 体系的 --disallowed-tools 黑名单思路呼应），从动机到实现都记在你的名下。

欢迎继续贡献，后续不会再让 PR 晾着。