CST-agent/docs/theory_tool_cst.md

Tool-loop CST：确认前沿推广到工具调用

命题

在 agent 工具环中，对模型输出做确认流式转导：只在 (O_{\mathrm{conf}}) 内不可逆地发射「可执行工具调用 / 可应用补丁 / 可提交会话状态」。相对「拼到合法 JSON 再执行」的缓冲基线，这能降低注意力饥渴导致的残缺工具帧（未闭合括号、半截 arguments）被过早执行或整轮失败的问题。

与论文 CST 的对应

论文（Markdown→HTML）	工具环推广
输入字母表 (\Sigma)	模型文本 / CTL 字节流
指称 (f,g) → HTML	(f_{\mathrm{tool}}) → 已确认 ToolCall / PatchHunk
(O_{\mathrm{conf}}) 不可撤回 HTML	不可撤回：开始执行工具、应用 hunk、写入 transcript
(\mathcal{L}_0) 排除引用式链接	(\mathcal{L}_0^{\mathrm{tool}}) 排除裸 JSON 对象
(K=2L_{\mathrm{line}})	工具帧同样要求有界 pending

为何排除裸 JSON

JSON 对象依赖括号匹配与字符串转义。在未闭合 " / { 时，任意后缀都可能改变已见结构的指称，故 (O_{\mathrm{conf}}) 往往停在空前缀，pending 随流长增长——这与论文中引用式链接的无界后向绑定同构。「等整个 JSON Parse 成功」只是 EOF 缓冲，不是有界 CST。

(\mathcal{L}_0^{\mathrm{tool}})：CTL（CST Tool Language）

行界 (L_{\mathrm{line}})；参数体用长度前缀，避免转义歧义。

call <id> <name>\n
arg <key> <nbytes>\n
<raw bytes exactly nbytes>
end\n

确认规则

1. call 行以 \n 结束：确认 (id, name)（此后不可撤回工具身份）。
2. arg 头以 \n 结束：确认 (key, nbytes)；随后精确消费 nbytes 字节，每字节到达即可确认（无 JSON 转义）。
3. end\n：确认整次调用可执行；转导器发射一个 ToolCall 事件。
4. 行长 (> L_{\mathrm{line}})、非法 token、nbytes 超上限、非 CTL 噪声 → 离开契约，标记 tool_parse_error。

有界 pending (K)

• 解析行头时 pending (\le L_{\mathrm{line}})。
• 读参数体时 pending (\le) 剩余未读字节数，但已读体字节已确认，工作区只需当前行缓冲 + 当前 arg 剩余计数（(O(L_{\mathrm{line}})) 寄存器），不随会话总长增长。

取 (K = L_{\mathrm{line}})（行头）与实现常量 CTL_MAX_ARG（单参上限，契约拒绝更大值）。

不可逆发射

实现是确认忠实的，当且仅当：

• 拼接发射的工具事件序列是 (O_{\mathrm{conf}}(u)) 的前缀；
• 一旦 ToolCall 被发射，runtime 必须执行（或显式记录拒绝），不得因后续字节撤回；
• session transcript 只追加：用户消息、已确认助手文本、工具调用与结果。

对照基线

JSON-buffer：将模型输出拼接到可 cJSON_Parse 的 {"name","arguments"}（或 OpenAI tool_calls 形）才执行；流中途截断则失败。与 CTL 使用同一截断点集合，只换帧语法。

补丁确认

apply_patch 的 patch 文本作为 CTL 的一个 arg；应用侧再要求 unified diff 的每个 hunk 完整（@@ 到下一块或 EOF）才写盘——整 hunk 确认，禁止半截应用。