12 KiB
Claude Code 2.1.312:工具调度、权限与结果机制
本次已建立工具调用的局部机制:校验输入并分类并发,排队进入执行路径,取得权限决定,通过最后检查后调用工具,再用原始 ID 交付结果。可以提炼成我们自己的本地代理执行器。全部结论来自静态发行工件与复制原文,没有运行 Claude Code 或读取个人会话。
工件与证据范围
目标沿用已取得的官方 Windows x64 发行包。EXE 为 D:\Ai-project\REA逆向\Claude-Code-REA\artifacts\package-extracted\package\claude.exe,大小 298690208 字节,SHA256 为 6099672ebe5dcb518b67d1d32dde1e3360bc6bee1dae7f8d28a69c49acc7c865;本次重新计算散列一致。
Bun 模块表已提取 2,581 个 JavaScript/entry 模块。本次实际选读 5 个原始分块中的 27 个函数/方法,组装成 5 份惰性分析文件。所有选段都与 EXE 原始载体字节逐一核对一致,来源索引保存 UTF-16 范围、UTF-8 字节范围、原始 EXE 范围和散列。
函数原文被保留,const 绑定、注释、exports 和部分 Js 类壳为分析时补入的结构。它们不代表原作者的完整源码,也不建立原应用的运行等价性。原来的 B:/~BUN/root/... 虚拟绝对路径、遗漏的依赖与动态关系仍未解析。
| REA 引用 | Evidence ID | 支持范围 |
|---|---|---|
| 主分析 | ev_78494b2b28703e1547eaa7b660ff70a6a1552991cd3b0e2727954779d74b5434 |
五份惰性文件的完整静态分析记录 |
| 摘要 | ev_ec39090d21bdfd4352635ed4831e8518aa4703a7ade7ef8b8c9b18e7b580071d |
选择、解析、覆盖和未知项 |
| 文件事实 | ev_fa12f2ad8dcb53e765a942233134ead88dd4aabc03b0d6e1479be59a62898835 |
原始观察 ID、源散列和 AST 来源位置 |
REA 解析了 5 个文件,共访问 24,566 个 AST 节点,零解析失败;语义保留未被预算截断。应用图仍是 partial,语义图是 unknown,保留 5,046 个语义未知记录。模块页里的 25 个节点含合成导出角色,不能当作 25 个原始应用模块。视图的 complete-within-view 只表示视图已完整返回。
调度与结果(C01、C02、C06;T03–T14、T24–T26)
Js 保留调用 ID、assistant 消息、queued/executing/completed/yielded 状态、进度、桥接事件和结果。getCompletedResults 只把 completed 转为 yielded,输出后移除对应进行中 ID。未知工具以及中断、对话结束和流式回退都有原 ID 的错误结果。
addTool 用 inputSchema.safeParse 的正常成功结果调用 isConcurrencySafe(parsedInput)。解析不成功或并发声明函数抛错时,分类为不适合并发;safeParse 自身的异常并未在这个片段内同样捕获。canExecuteTool 的条件为“没有工具执行”,或者“新工具与所有正在执行的工具都安全”。processQueue 遇到不能启动的非安全排队项就 break,构成独占屏障。
processQueue 虽然 await executeTool,后者只是保存内部异步 promise 后返回,所以不能据此把所有工具解释为串行执行。安全工具的上下文 layers 缓冲到没有工具执行时才应用;非安全工具完成时应用自己的层。层合并 helper 的冲突行为仍未展开。
discardAndAbortInFlight 区分已完成/已交付、排队和执行中调用,但 callStarted 只是生命周期标记。markToolCallStarted 位于原分块 UTF-16 3920135,受保护的 e.call 位于 3921163;两者之间还有协调器拒绝、参数和工作目录检查。该标记不能证明副作用已发生,completed 也可能对应中止后的合成错误。
ud 通过工具调用 ID 找到对应 assistant 消息。RSo 收集结果 ID,并过滤含任一未配对工具调用的整条 assistant 消息;它不会生成成功结果。ID 配对的语法观察是明确的,真实执行是否完成仍需运行和持久化证据。
权限与执行(C03、C04;T15–T23)
选定本地路径在 EU 查找与路由后,经 gYr 进入 bYr。bYr 包含输入转换、schema 校验、可选 validateInput 和 PreToolUse hooks,然后取得 oFr 返回的 decision/input。
bYr 的 No.behavior !== "allow" 分支创建原始 ID 的错误结果并 return,早于其主要工具调用。权限处理器改写 updatedInput 后还要重新做 schema 验证,失败也返回错误。oFr 的条件检查可以把 allow 降为 deny;NVr、JP、WKe 等 helper 的完整语义未解析,不能据这一小段概括全部授权模型。
hv 可返回已有决定,也可进入 SDe。$yr 同时出现先行 allow 直接返回、带条件的 dontAsk 拒绝、自动分类和回退提示路径。本报告只读取相关的有限分支,没有审完该大型策略函数。
yF 在先行决定是 allow/deny 时直接返回;其余路径可以调用配置的 MCP 权限提示工具,并竞速等待提示结果、中止或符合条件的 hook outcome。服务器不可用、中止或 schema-invalid 回复返回 deny;非预期文本结果结构会抛错。某些工具类型或用户交互要求还会拒绝提示工具给出的 allow。AV 根据 stdio、直接决定和配置提示工具选择路径。
因此,“所有工具都需要人点确认”不是本次观察到的通用规则。我们产品的终端人工确认、授权有效期和恢复策略需要作为独立设计实现。这里证明的是选定本地主要调用的静态前置拒绝分支,远程执行器、hooks 的其他效果和全部模式没有端到端验证。
MCP 恢复重试(C05;T27、G08)
ct 的会话恢复分支只在 Mt < 1 时继续循环,因此最多追加一次恢复重试。它还要求以下一项成立:异常声明工具尚未执行(!mayHaveRun)、工具声明输入可并发、或者 MCP 的 idempotentHint 为 true。其他错误或重试耗尽走失败路径。
并发安全是这个客户端采用的条件,不能普遍等同幂等。BM 如何判断 mayHaveRun、远端如何恢复会话以及重复调用的真实影响未被运行验证。我们的实现应该把并发声明和幂等声明分成两项,并保留结果不确定的写操作。
可以落入统一产品的六条独立设计原则
| 原则 | 我们的实现契约 | 可检查结果 |
|---|---|---|
| D01 把调用、启动标记和结果分开记录 | 每个逻辑调用使用稳定 call ID,重试另有 attempt ID;状态记录先于执行,完成结果持久化后才确认完成。预调用标记不能当作副作用提交证明。 | 拒绝、中止、未知工具和成功结果都能配对到原始调用;重启后不会把仅有启动标记的调用显示为成功。 |
| D02 在调度与执行前验证实际输入 | 模型输入、hooks 改写和授权者改写都经过 schema 验证;输入变化后重新评估权限和并发分类。这是我们增加的明确契约。 | 无效输入不会到达执行器;一个改写后的写操作不能继续沿用原读操作的并发分类。 |
| D03 用声明控制并发并保留独占屏障 | 工具显式声明是否适合并发;缺失、分类失败或异常采用独占执行。可并发组完成前阻挡独占写操作,独占队列项阻挡后续调用。 | 两个允许并发的读操作可同时运行;排在其后的独占写操作以及该写操作后的调用按屏障推进。 |
| D04 让授权决定与执行器使用同一份调用 | 保存授权来源、实际输入摘要和决定;执行器只接受仍有效的 allow。我们产品的终端人工确认策略属于独立设计,不能冒充 Claude Code 的通用行为。 | 未解决的 ask、deny、失效授权和不匹配输入不会到达主要工具调用。 |
| D05 中断后保留结果不确定 | 明确区分未启动、已完成和结果不确定的调用;对结果不确定的调用先核对已有结果及外部可观察状态,再决定恢复。 | 运行中崩溃或取消后,界面与日志显示可核对的不确定状态,并保留原调用 ID。 |
| D06 把恢复重试与幂等声明分开 | 恢复重试设次数上限;已知未执行或工具明确承诺幂等时可重试。并发安全和幂等使用不同字段,重试也重新检查授权。 | 可能已经执行的非幂等写操作不会因为网络恢复而自动再执行一次。 |
以上是原创产品设计提案,本次研究没有修改 Agent-Workbench 代码,也没有声明这些契约就是 Claude Code 的全部行为。
来源定位
下表的范围是原始派生分块内的半开 UTF-16 区间;T 编号在 TOOL-LOOP.evidence.json 中继续连接到 EXE 字节范围、散列、REA 源观察和生成切片位置。
| 选择 | 函数/方法 | 原始分块 | UTF-16 范围 |
|---|---|---|---|
| T01 | Js.constructor |
chunk-3vwg1wzf.js |
[57761,57856) |
| T02 | Js.discard |
chunk-3vwg1wzf.js |
[57856,57903) |
| T03 | Js.discardAndAbortInFlight |
chunk-3vwg1wzf.js |
[57903,58418) |
| T04 | Js.addTool |
chunk-3vwg1wzf.js |
[58575,59912) |
| T05 | Js.canExecuteTool |
chunk-3vwg1wzf.js |
[59912,60041) |
| T06 | Js.processQueue |
chunk-3vwg1wzf.js |
[60041,60252) |
| T07 | Js.createSyntheticErrorMessage |
chunk-3vwg1wzf.js |
[60252,61547) |
| T08 | Js.getAbortReason |
chunk-3vwg1wzf.js |
[61547,61729) |
| T09 | Js.buildSameTurnToolUses |
chunk-3vwg1wzf.js |
[62246,62559) |
| T10 | Js.buildSameTurnErroredToolUseIds |
chunk-3vwg1wzf.js |
[62559,62888) |
| T11 | Js.executeTool |
chunk-3vwg1wzf.js |
[62888,65821) |
| T12 | Js.getCompletedResults |
chunk-3vwg1wzf.js |
[65821,66402) |
| T13 | Js.getRemainingResults |
chunk-3vwg1wzf.js |
[66511,67084) |
| T14 | Js.applyEndedRunLayers |
chunk-3vwg1wzf.js |
[67084,67384) |
| T15 | EU |
chunk-9hk5qx04.js |
[3891097,3896902) |
| T16 | gYr |
chunk-9hk5qx04.js |
[3896902,3899334) |
| T17 | bYr |
chunk-9hk5qx04.js |
[3902063,3936718) |
| T18 | oFr |
chunk-9hk5qx04.js |
[3860602,3860892) |
| T19 | hv |
chunk-9hk5qx04.js |
[2927234,2927304) |
| T20 | SDe |
chunk-9hk5qx04.js |
[2927379,2927814) |
| T21 | $yr |
chunk-9hk5qx04.js |
[2928029,2967785) |
| T22 | yF |
chunk-qey7z5yq.js |
[823883,826935) |
| T23 | AV |
chunk-qey7z5yq.js |
[827368,828434) |
| T24 | dd |
chunk-gets36qn.js |
[32523,32832) |
| T25 | ud |
chunk-gets36qn.js |
[32832,33209) |
| T26 | RSo |
chunk-gets36qn.js |
[119632,119984) |
| T27 | ct |
chunk-d8k5k6qc.js |
[112235,114722) |
问题覆盖和剩余未知
| 问题 | 当前状态 | 边界 |
|---|---|---|
| 生命周期、并发屏障、结果 ID 与取消分类 | 已回答选定静态路径 | 工具实现与运行副作用仍未知 |
| 主要工具调用前的输入验证和权限拒绝 | 本地路径已有明确分支 | 远程执行与 helper 关系只部分回答 |
| 权限模式、规则和 MCP 提示 | 部分回答 | 只读了大型策略中的有限相关分支 |
| 会话恢复重试上限与判定条件 | 已回答选定 ct 路径 | 服务端执行确定性及幂等真实性未知 |
| 原客户端完整运行行为与全程序等价重构 | 未验证 | 没有执行目标,完整跨模块关系未建立 |
本次定位与否定结论都限定在选定文件/函数。合成错误、AbortController 和启动标记提供调度层事实,不能推断外部动作已撤销、底层进程已结束或持久化结果已提交。
交付文件
- 证据索引:27 个完整选段、8 个关键语法锚点、结论和独立设计原则。
- 字节验证:EXE 散列重验、27 处载体文本比较和生成位置。
- REA 视图原记录:本次返回的完整摘要与视图 Evidence。
- 完整 REA Bundle:26216217 字节,7 个记录;包含完整主图,供后续离线查询。
- 惰性切片来源:原始字节与分析包装说明。
统一产品可收录报告与证据索引;完整分析图和第三方函数切片保留在研究目录。