Skip to main content
See Patches for authoring and semantics.

​
The reference

Patches are named key@version:
This is what appears as patch_ref on every tool call, and in pending_confirmation and pending_action. The version is part of the identity. A wired patch names one exact version, so changing a patch does not alter agents that pinned an earlier one.

​
Declaration

What an agent carries about a patch, visible in agent_snapshot:
​
string
required
Unique within the workspace. Seven keys are reserved by built-in primitives.
​
string
required
Shown to you, and to the model as the tool name.
​
string
How the model decides whether to use it. The single highest-leverage field.
​
object
required
customer_endpoint, api_product, or native_utility. A customer endpoint carries method, route, egress auth, and optionally a pinned connection.
​
enum
required
silent, interactive, handoff, or proposed_action.
​
object
required
JSON schema for the arguments. Enforced before any call is made.
​
object
JSON schema for the result.
​
object
Optional. { "kind": "..." }. When set, the patch’s result is emitted as a rich-message data block of this kind for you to render, instead of only reaching the model. Set it in the patch builder’s Render as field.
​
object
required
base is low, medium, high, or critical. An agent can raise it, never lower it.
​
object
idempotent, and a retry mode.
​
array
Fields stripped from results before storage and before the model sees them.
​
object
Per-call price, for priced products.

​
Permission is not on the patch

How an agent may use a patch — Always allow, Always ask, Always deny — belongs to the wiring, not the declaration. The same patch can be gated on one agent and free on another.

​
Errors