Tools Are Contracts, Not Functions

Harness 系列文章之 3，Tools Are Contracts。

如果 Coding Agent 拥有一个世界，那么每次 tool call，就是用 generated text 请求改变其世界的状态。

Tool call 很容易显得过于简单，model 输出 JSON，Harness parse 它，某个本地 function 被执行，result 被放回下一轮 prompt。

这是 tiny agent 版本。

但 coding agent 的 tool call，并非简单的 function。

Tool call 来自 generated text，它正在请求访问 workspace，shell，network，transcript，或者另一个 Agent。

这个差异会改变整个 Coding Agent 的状态和所处的环境。

The model can ask. The harness decides.

The Proposal and Contract

想象 model 输出：

它看起来很 structured，它依然只是一份 proposal。

Model 产出了看似合法的 JSON，并不自动获得 write access。

Harness 仍然需要回答：

• 这个 tool 是否存在？

• args 是否匹配 schema？

• path 是否在 workspace 内？

• 这是 create、overwrite，还是 patch？

• model 最近是否读过现有文件？

• file-state baseline 是否 fresh？

• 这个 action 是否需要 approval？

• approval 前应该给 human 看什么？

• 多少 result output 可以安全进入 context？

• 执行之后需要更新哪些 transcript 和 state？

这一串问题，就是 tool contract。

The Naive Design

naive design 会把 tools 当作一个 function map：

这段代码很短，所以看起来干净， 但它同时把很多责任压进了一行。

Parsing，schema validation，path safety，permission policy，sandbox choice，execution，output clipping，transcript recording，state updates，全都被塞进 tool(…)

Demo 可以这样写。但能够修改真实 repo 的 coding agent，需要更强的边界。问题不在 function 本身，问题在于 tool boundary 有不同的 trust rules。

Function call vs Tool call

普通程序里，function call 是 implementation detail。

coding agent 里，tool call 是 generated text 请求改变真实世界的位置。

What A Tool Contract Contains

有用的 tool contract 不能只有 name 和 handler。它应该描述：

有些字段面向 model。有些字段只属于 harness。

Model 需要足够的信息来正确发起请求，Harness 需要足够的 metadata 来正确裁决。

The Lifecycle

一个最小可用 lifecycle：

每一步拦截不同类型的问题。

• parse 处理 malformed output

• schema validation 处理 missing fields 和 wrong types

• path validation 处理 workspace escape

• policy 处理 risky action、approval、sandbox、denial

• execution 运行真实 handler

• bounding 避免一次 command 或 file read 淹没下一轮 prompt

• recording 让下一轮可以恢复和审计

所以，“just call the function” 这个 mental model 不够用，function 只是 lifecycle 中的很小片段。

Validate Before Approval

validation 应该发生在 approval 之前。

• 如果 patch_file 指向 workspace 外，先 reject

• 如果 old_text 缺失或有歧义，先 reject

• 如果 tool call 立刻重复上一轮失败请求，先 reject 或 retry

• 如果 write 目标是现有文件，但缺少 fresh baseline，先 reject

• approval 是 product surface

用户不应该被要求判断一个本来就无效的请求。，需要 approval 时，summary 应该保持 bounded。

文件编辑的 approval prompt 应该展示 affected path 和 change shape，避免倾倒 unbounded raw content。

Harness 可以之后展示 diff，count，preview。Approval boundary 要小而清楚。

Bounded Results Are Part Of Safety

Tool output 会变成 context，Context 会影响 Agent 行为。

• 如果 search 返回 10,000 条结果，model 并没有更清楚

• 如果 run_shell 打出巨大 log，下一轮可能丢掉真正的 user request

• 如果 read_file 每一轮重复同一个未变化文件，有用 context 会被 duplicate text 挤走

所以 tool contract 需要 result limits：

这不只是 token cost，它关系到 model working set 是否准确。

Harness 应该决定哪些 result evidence 进入 transcript，哪些成为 durable state，哪些保留为 external artifact reference。

评估一个 coding-agent tool 时，不要先问：

model 能不能 call 它？

更应该问：

• argument schema 精确吗？

• 这个 tool 能 read 或 mutate 什么？

• 哪些 paths、commands、resources 被允许？

• 运行前需要哪种 fresh state？

• allow、ask、sandbox、deny 由什么 policy 决定？

• 什么 result evidence 会回到 model？

• success 或 failure 之后，哪些 durable state 会变化？

• 之后如何把这个 call 和 result 配对？

Model 可以请求，Harness 负责裁决。

Tool Call 只在 Harness 裁决批准后执行。

这个过程，就是契约。

简而言之，工具即契约。