Files
Agent-Workbench/docs/research/TOOL-LOOP.md
T
2026-10-29 11:23:43 +08:00

12 KiB
Raw Blame History

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 个记录;包含完整主图,供后续离线查询。
  • 惰性切片来源:原始字节与分析包装说明。

统一产品可收录报告与证据索引;完整分析图和第三方函数切片保留在研究目录。