Tools
tool.v1 (accepted, ADR 0058; S1-S3 built): every catalog tool takes one call shape, {tool, action, args}, with eight shared actions (list, get, search, create, update, delete, act with an op, watch) and answers {ok, data, receipt, ask_back?, error{code, hint}}; a tool is declared by one tool.toml manifest (typed bounded args, capabilities and egress, approval, receipt fields, error codes, a latency budget, provenance, a guide) answered by a native, pi extension, MCP or JSON-in/JSON-out CLI handler; the brain's prefill teaches the envelope once (about 177 tokens) and declares each on tool slim (typed args, a one-line description, the guide on demand through pi_tool_search get); vulpine tool check lints, golden-tests and prices a tool; semver rules per contract and per tool.
Living doc, checked against the code 2026-11-14
tool.v1 — a catalog tool: one call shape, eight shared actions, one manifest, any handler
- Status: accepted (ADR 0058). The envelope and the eight actions live
in
catalog/pi/extensions/vulpine-tools/tool_v1.ts, the slim declarations inprefill_form.ts, the envelope text incatalog/pi/tool-v1-envelope.txt, and the manifest reader and lint intool_manifest.tsandcatalog_manifest.ts. The gateway’s side iscrates/voice_gateway/src/tool_prefill.rs. - Scope: the shape every catalog tool speaks to the brain, and the manifest a tool is declared by, whoever wrote it. A catalog tool is the middle tier of ADR 0050 §1: a core tool, a first-party plugin or a user’s own. Gateway verbs (ADR 0015) and skills (skill.v1) are other tiers.
- The plugin point: a tool is one folder, a
tool.tomland whatever answers it: a Pi extension, an MCP server or any executable that reads JSON and writes JSON.vulpine tool checklints, prices and golden-tests it. - tool.v1 is one contract of the versioned extension API (ADR 0059). Versions is this contract’s own rule.
The call
{"tool": "pi_herdr_dispatch", "action": "create", "args": {"kind": "worktree", "name": "fix the docs"}}
- In a native function call,
toolis the function name and the arguments object is{action, args}. A CLI or MCP handler gets the three keys as one object. actionis one of the eight below.argsis the object the manifest types for that action. Every string is bounded.
The result
{"ok": true, "data": {"worktree": "ready", "branch": "lane/fix-the-docs"},
"receipt": {"schema": 1, "tool": "pi_herdr_dispatch", "action": "create", "ok": true, "ms": 412, "fields": {"kind": "worktree"}}}
{"ok": false, "error": {"code": "unknown_host", "hint": "Name one of the fleet's hosts.", "retryable": false},
"receipt": {"schema": 1, "tool": "pi_herdr_dispatch", "action": "create", "ok": false, "code": "unknown_host", "ms": 3, "fields": {}}}
{"ok": true, "ask_back": {"question": "Which kitchen light, the ceiling or the counter?", "options": ["ceiling", "counter"], "field": "subject"},
"receipt": {"schema": 1, "tool": "pi_home_act", "action": "act", "ok": true, "ms": 40, "fields": {"op": "on"}}}
| field | type | rule |
|---|---|---|
ok |
boolean | false for every failure. Pi’s isError is !ok |
data |
object | the typed answer, at most 16 KiB serialized unless the manifest says less. truncated: true when it was cut |
receipt |
object | the spool row of receipts.ts (ToolReceipt): schema, tool, action, ok, code?, ms, egress_host?, and fields from the manifest’s closed list. It holds no query, page text, URL beyond a host, or path |
ask_back |
object, optional | {question, options? (at most 6), field}. The brain asks the operator, then calls again with the answer in args[field]. The usage ledger counts the outcome ask_back |
error |
object, when ok is false |
code: from the manifest’s errors.codes or the shared set below, ^[a-z][a-z0-9_]{1,47}$. hint: one plain sentence that says what to change, naming no host, path or secret. retryable? |
The model reads {ok, data, ask_back?, error?}. The receipt rides in Pi’s details for the spool, the gateway and
the Admin. error.code is copied to details.reason.
On the spool the receipt’s code is upper-cased to the schema-1 shape (A-Z and _, at most 40): unknown_plant
travels as UNKNOWN_PLANT, and a code with a digit or past 40 characters as TOOL_ERROR. The envelope’s
error.code and details.reason keep the exact code.
The shared error codes are unknown_action, args_invalid (the hint names the argument), not_set_up, refused
(the guard or an approval said no), timeout, handler_failed, unavailable and aborted.
abortedmeans the caller’s signal stopped the call: a stop or a barge-in.runV1settles the call at once, whatever the handler does with the signal. An already-aborted signal never starts the handler.- Retry advice. Timeout, abort and unclassified unavailability default to non-retryable, because a dispatched action may already have taken effect. An action may opt in when it is safe to retry. A handler’s own classified unavailability keeps its retry advice. The advice never causes an automatic retry.
Progress (minor revision tool.v1.1)
A slow call may say where it is before it answers. It is an optional update, never part of the result: a tool that sends none still conforms, and a reader that does not know it ignores it.
{"content": [], "details": {"envelope": "tool.v1", "progress": {"stage": "hearing back from the sources", "done": 2, "total": 3}}}
- The crossing. A
pi_extensiontool passes this object to Pi’sonUpdate(execute’s fourth argument). Pi emits it astool_execution_updatewithpartialResultset to it, and the gateway readspartialResult.details.progress(crates/voice_gateway/src/progress.rs,ToolProgress). stageis a closed template the tool wrote, never the operator’s words or a value it read: under ten words, at most 120 characters, and no digit, no/ \ _ # ~or backtick, and no word of eight or more hex digits. That is the gateway’sline_is_speakable. A stage that breaks the rule is dropped where it is made, counted, and never sent or thrown. Counts go indoneandtotal, which are whole numbers. The gateway reads them out (“two of three”) only whentotalis at most 100.- The helper. A handler’s
ctx.progress(stage, done?, total?)checks the rule and callsonUpdate(tool_v1.ts:progressReporter). A core behind an adapter builds the same function withprogressReporter(onUpdate). - What the room hears. The gateway says a new stage in place of its next elapsed-time cue: at most three cues a turn, ten seconds apart, never over audio. It says nothing while a tool waits on the operator, so a tool sends no stage while it waits for an approval or an answer.
- Emitters.
pi_fleet_digest,pi_internet_search,pi_herdr_remote(each hop),pi_herdr_prompt,pi_calendar_changeandpi_web_imagereport their stages.
The soft deadline (tool.v1.1)
Pi delivers a steer only once the running tool returns, so a slow read holds the operator’s next answer until it
ends. A manifest may give soft_budget_ms (tool level, or on one action, which wins), below latency_budget_ms.
Only a read action whose approval is free gets one. A write or an approval never spills. Past the soft budget,
runV1 asks the gateway to adopt the running call as background work (tool_call_adopt on the mutation socket). If
the gateway adopts it, the turn answers a pending result and the call keeps running:
{"ok": true, "data": {"pending": true, "job": "fox9-work-…", "say": "Still on it; I will tell you when it is ready."}}
jobis the gateway’s background work id:brain_background_work_statusandbrain_background_work_canceltake it.sayis one speakable line for the brain to relay.- When the call ends, its bounded result (data cut to 3 KiB, or the error) settles the job (
tool_call_settle). The gateway owns the settlement, and the governor decides when it is spoken. The extension never starts a brain turn. - A stop before the spill answers
abortedas usual. A stop after it settles the jobaborted, which the gateway turns into the background work’s cancel.latency_budget_msstill ends the call (settledtimeout). - When the gateway refuses or does not answer, the call blocks until it ends. Every call blocks while the soft budget is unset (the default).
- The receipt counts the spill (
soft_deadline_spill,spill_ms). - The gateway (
crates/voice_gateway/src/adopted_calls.rs) adopts a call only when its tool call id is open in the live session’s running turn and the compiled manifest gives that action a soft budget on a free read. A settle ends only the job its own tool call adopted. An unsettled job failstool_call_deadlineat the tool’slatency_budget_msplus 30 s. - The relay speaks a sentence, not the data: “The
is ready. Ask me about it.” The tool’s words come from a closed table, never from the call’s arguments. A tool with no label, or a line that is not speakable, gets “The thing you asked me to look up is ready; ask me and I will go over it.” The pending sayfollows the same rule (“I will say when theis ready.”). - The data stays in the job’s result, at most 4 KiB as the status answer carries it.
brain_background_work_status(job)hands it to the brain. The board scores and holds the line like any background-work settlement (completed 0.7). pi_fleet_digest,pi_git_historyandpi_internet_searchset the budget.
The eight actions
| action | meaning | state |
|---|---|---|
list |
the records, bounded, newest first | reads |
get |
one record by id or subject. With no id, the tool’s status. args.what picks a view from the manifest’s views |
reads |
search |
records matching args.words |
reads |
create |
make one record | writes |
update |
change one record | writes |
delete |
remove, cancel or close one record | writes |
act |
one named effect, args.op from the manifest’s ops |
writes |
watch |
a standing condition. It returns an id, and delete with that id stops it |
writes |
- A domain verb is an
actop or agetview, never a new action. - These words are not actions:
statusisget,removeisdelete,readisget, andsubscribeiswatch.startandstoparecreateanddeleteof a job, or an op.capabilitiesis the tool search’sget. - A ninth action needs
extra_actions = [{name, reason}]. The kit warns on it. describeis reserved:pi_tool_searchanswers it for every tool.
The prefill
Once per session, in the system prompt (744 bytes, about 177 tokens by brain_prompt_cost.py’s estimate):
Tools follow tool.v1: call a tool with {action, args}; it answers {ok, data, receipt, ask_back?, error?}.
Actions mean the same on every tool: list, get, search only read; create, update, delete change one record; act does one named thing (args.op names it); watch keeps a standing condition (delete its id to stop it).
A tool's description is one line and its args are typed. When that is not enough, pi_tool_search {action: "get", args: {names: [...]}} returns the tool's guide. {action: "search", args: {words}} finds a tool you do not have yet and makes it callable this turn.
ok false: read error.code and error.hint, fix the call once, or say plainly what failed. ask_back: ask the operator its question, then call again with the answer.
Each tool in state on (ADR 0050 §6) has one prefill form:
| form | what Pi declares | when |
|---|---|---|
slim (default) |
the typed {action, args} parameters and a one-line description: purpose plus its actions, at most 100 characters |
every on tool unless the kit says otherwise |
full |
slim plus the guide | guide_pinned = true, granted only on the kit’s evidence |
deferred |
nothing. pi_tool_search finds and loads it. The optional hint line is the one-line format |
ADR 0050 §6. Hint off by default |
pi_tool_search {action: "get", args: {names}} returns each tool’s guide and schema, and loads a deferred one for the
session. A tool loaded or described once stays so for the session.
- The launch’s form. The gateway’s
[brain] tool_formpicks the form for a brain launch:full(the default) orslim. Underslimthe envelope text above goes into the system prompt and each tool is declared by its form; underfullevery tool is declared in full and the envelope text is not sent. A launch whose slim declarations would not pay for the envelope text falls back tofull. - The one line. A tool’s one line is its description’s first sentence plus its
actionchoices in brackets, cut to 100 characters. When the choices would leave the purpose under 40 characters, they are left to the typed parameter. - What is slimmed. vulpine-tools and brain-tools declarations. MCP tools keep their profile’s declarations, and
Pi’s built-in
readkeeps Pi’s; both count asfull. The catalog row carriesform,line,slim_tokensandguide_tokens. - The trace. Every launch writes one
tool_prefillline: the form, the tools declared, the full price, the declared price, the envelope’s share and the tokens saved.
The manifest
catalog/pi/tools/<name>/tool.toml for a repo tool. A user’s is <workspace>/.vulpine/tools/<name>/tool.toml,
admitted only through the pinned registration of ADR 0050 §2; nothing reads workspace manifests yet.
schema = "vulpine.tool.v1"
name = "pi_plant_moisture" # ^[a-z][a-z0-9_]{1,63}$, unique in the catalog
version = "1.0.0" # this tool's semver (see Versions)
purpose = "Soil moisture of the house plants"
tags = ["plants", "water", "soil"]
latency_budget_ms = 800 # call to result; the usage ledger's p95 is checked against it
soft_budget_ms = 400 # optional (tool.v1.1): the read actions' in-turn budget; see "The soft deadline"
guide = "guide.md" # optional, at most 16 KiB, served by pi_tool_search get
guide_pinned = false
requires = [] # optional: ["gateway"] keeps it out of a standalone Pi
[handler]
kind = "cli" # native | pi_extension | mcp | cli
exec = "bin/plantctl" # manifest-relative or absolute; digest pinned at install
timeout_ms = 2000
env = [] # the only variables the child sees; no PATH is inherited
[capabilities]
set = ["network", "house"] # the closed set of ADR 0050 §2
egress = ["sensors.example.net"] # required with network
[receipt]
fields = ["plant", "count"] # the closed subset of args and data keys a receipt may carry
[errors]
codes = ["unknown_plant", "sensor_offline"]
[actions.list]
summary = "every plant and its last reading"
approval = "free"
[actions.get]
summary = "one plant's moisture"
approval = "free"
args.plant = { type = "string", required = true, max = 40, doc = "the plant's name" }
[actions.act]
summary = "water one plant"
ops = ["water"]
approval = "confirm_before_write"
args.plant = { type = "string", required = true, max = 40 }
args.seconds = { type = "integer", min = 1, max = 60 }
| key | rule |
|---|---|
| argument types | string (needs max), integer and number (min, max), boolean, enum (values), list (of, max_items), object (fields); or schema = "<file>.json", a JSON Schema with every string bounded |
approval |
per action, one of free, confirm_before_write or always_ask. The catalog row’s approval is the strictest action’s, and that tool-level class is the one enforced in v1 |
provenance, source |
derived for repo tools (catalog_provenance.ts). A user’s manifest is forced to user_extension and starts at confirm_before_write, or always_ask for write or messaging, until trusted |
extra_actions |
[{name, reason}]. A warning, counted in the Admin |
requires |
optional: what the tool needs beyond its handler. The one value is gateway: the tool works only on the Pi the gateway launched (it calls the gateway’s mutation or approval socket for its answer), so a standalone Pi never registers it and vulpine tool run refuses it with requires_gateway. Absent is the handler’s rule alone (a native handler needs the gateway). host:<name> comes from egress, never from this key; tcc:<grant> and model:<id> stay reserved. The index writer puts this list first in the record’s requires |
views, ops |
closed lists for get’s args.what and act’s args.op |
The generator (bun catalog.ts) lints every catalog/pi/tools/<name>/tool.toml and compiles the passing ones,
guides inlined, into catalog/pi/tool-manifests.json, which the runtime reads. A passing manifest gives its catalog
row version, latency_budget_ms, handler and manifest, and sets its approval to the strictest action’s. The
generator refuses a manifest whose approval is below the row’s derived class (manifest_approval_below_derived),
that leaves out a capability the row derives (manifest_capability_undeclared), or that names a tool no extension
registers (manifest_unregistered, except a cli handler). From a compiled manifest the runtime declares action
as an enum and args as one object, and decodes each action’s arguments by the manifest’s types. An act op list
becomes a required args.op enum, and a get view list an optional args.what enum.
Handlers
| kind | answers | crossing |
|---|---|---|
native |
the gateway (Rust) through the brain-tools bridge or the door socket | the envelope as typed protocol structs |
pi_extension |
a TypeScript tool registered with Pi | the native function call. Results are built with the envelope helpers |
mcp |
an MCP server named by a profile | [handler.map] maps each action, or action.op, to one MCP tool. args is its input. Content blocks become data.text or data.items |
cli |
any executable | stdin: {"schema": "vulpine.tool-call.v1", "tool", "action", "args", "call_id", "deadline_ms"}. stdout: one result object, at most 64 KiB. Exit 0, even when ok is false |
The rules for a cli handler:
- Failures. A non-zero exit, a timeout, a second JSON object or bytes that are not JSON become
handler_failed. - The receipt. The runtime fills it:
ms, and the egress hosts from the manifest. The CLI may addfieldsnamed inreceipt.fields. - The incur dialect.
dialect = "incur"accepts an incur-style CLI’s{ok, data, error{code, message, cta}}:messageandctabecomehint.
The cli runtime (catalog/pi/extensions/vulpine-tools/tool_cli_handler.ts):
- The executable.
handler.execis absolute, or relative to the manifest’s folder; a relative path that leaves its folder is refused. Its sha256 is checked againsthandler.digestbefore the first run in the brain process. A mismatch answersrefusedon every call until the tool is pinned again and the brain restarts. A missing executable answersnot_set_up. - The call.
deadline_msis relative:handler.timeout_ms.call_idis Pi’s tool-call id. The child runs in the manifest’s folder, in its own process group, with only thehandler.envnames that are set.PATHis never passed, even when named, so a script names its interpreter by absolute path. stderr is dropped. - The answer.
{ok, data?, error?{code, hint, retryable?}, ask_back?}. A code outside the manifest’serrors.codesand the shared codes becomeshandler_failed, and the tool’s hint is kept. For incur, the code is lower-cased and the hint ismessagethencta.ctamay be a string,{description},{command}or a list, read fromerror.ctaormeta.cta, and it is never run. - Failures. A timeout, a non-zero exit and a stdout over 64 KiB kill the child’s process group.
runV1’s own backstop istimeout_ms+ 500 ms. No hint names a path. - The receipt.
egress_hostis the manifest’s first egress host, andreceipt.fieldsare read fromdata. The trace carriescli_*fields:path(ok, ask_back, tool_error, timeout, aborted, exit_nonzero, oversized, malformed, spawn_failed, missing or digest_mismatch),exit_code,digest_ms,digest_cached,spawn_ms,wait_ms,parse_msandbytes_out. - Registration. At load, every compiled
climanifest that no TypeScript code registered is registered through the same wrapper as any tool (guard, deferred exposure, prefill form, receipt). Its description is the purpose. Its catalog row has kindcli, sourcecli:<name>, provenancecorefor a repo manifest, and capabilities and tags from the manifest; a state-changing action deriveswrite.
The conformance kit
vulpine tool check <dir> [--net] [--json] [--against <old tool.toml>]:
- Lint. Every rule above: names, the purpose line, actions, bounded arguments, capabilities and egress, the approval floor, receipt fields, error codes, the guide’s size and the latency budget.
- Golden calls. Each
golden/<name>.jsonis{call, expect}, run through the real handler. Generated negatives must answer a typed error with a hint: an unknown action, a missing argument, an oversized argument, a timeout. - Price. It prints the slim declaration’s and the guide’s tokens, with
brain_prompt_cost.py’s estimator. - Against. It names the semver bump the change needs, and the old golden calls must pass on a minor.
The catalog generator runs the lint on every repo manifest. A failing manifest is refused, and so is its row.
The kit is the vulpine binary (crates/vulpine_cli); just catalog::tool-check <dir> runs it.
-
Lint rules, by name, the same as the generator’s:
- the shape:
manifest_shape,schema_version,name_invalid,name_mismatch,version_invalid; - the purpose and budget:
purpose_empty,purpose_long,latency_budget_missing; - the handler:
handler_kind_unknown,handler_exec_missing,handler_timeout_missing,handler_dialect_unknown; - capabilities:
capability_unknown,egress_missing,egress_invalid; - requires:
requires_unknown(a value outsidegateway); - actions:
actions_empty,action_unknown,action_describe,extra_action_no_reason,extra_action(a warning),approval_unknown,approval_floor(waived to the warningapproval_floor_waivedby a non-empty per-actionapproval_reason),summary_invalid; - arguments:
arg_type_unknown,arg_unbounded,arg_name_invalid; - ops and views:
ops_missing,ops_misplaced,views_misplaced,op_invalid; - receipts and errors:
receipt_field_invalid,receipt_field_content,error_code_invalid; - the guide:
guide_missing,guide_too_large,guide_pinned_without_guide.
Lengths count UTF-16 units.
catalog/pi/tools/lint-corpus/<rule>/holds one manifest that trips each rule, plusclean, which passes. - the shape:
-
Golden calls. A
pi_extensionornativetool runs throughbun catalog/pi/extensions/vulpine-tools/tool_golden.ts <dir> --jsonfrom the repo root (bun fromVULPINE_BUN, elsebunon PATH). Aclitool runs under the same rules as thecliruntime. The kit does not run anmcphandler. Aclianswer with no booleanok, an empty answer, orok: falsewith noerrorishandler_failed; a failure with no hint fails the case. The generated negatives are an unknown action and, per action, a missing required and an oversized argument. Without--net, aclitool that declaresnetworkruns only its negatives, and the report counts the skipped cases. -
The price is the one line plus the declared parameters as compact JSON at 4.7 bytes per token, and the guide at 4.2.
-
--againstnames the bump. Major: an action, op, view or argument removed, a type changed, a bound tightened, an argument made required or a required one added, or a stricter approval. Minor: an action, op, view, optional argument or enum value added, or a bound loosened. Patch: any other difference. It fails when the declared bump is smaller or the version went down. On a minor, aclitool replays the old folder’s goldens. -
The report (
--json, schemavulpine.tool-check.v1) carries the lint lines, each golden verdict with its ms, the runner, the price, the bump and counts, never a path. Exit 0 pass, 1 findings, 64 usage, 2 I/O.
What other seams see
- Guard: the same verdicts. A migrated tool is evaluated through its adapter’s legacy view.
- Approvals: the tool-level class.
- Receipts: the same spool schema.
actionis the tool.v1 action, withfields.oporfields.view.fields.legacy_actionis carried for one release after a migration. - The usage ledger: keyed by the native tool name. The action comes from
args.action. - The tool door and the door socket: the same
onanddeferredtools. - The Admin: the Tools panel, with each tool’s state and prefill price, and the Usage view. There is no manifest view.
Tools that predate tool.v1
The older catalog tools keep their names and their cores behind an adapter, and each declares the {action, args}
shape. A migrated tool takes three call shapes:
- a tool.v1 call, decoded by its manifest, checked on its legacy view and answered in the envelope;
- a model’s legacy call, turned into a tool.v1 call by Pi’s
prepareArgumentsand receipted withlegacy_action; - a legacy call that reaches the tool directly (the typed door, vulpine-glyphctl, the Admin’s pipeline door), which
runs the core and answers the legacy result. Its receipt names
fields.legacy_action.
The guard judges a tool.v1 call on its legacy view, so its rules and flow entries (tool:action) still apply. A core’s
refusal words stay the error codes, and its details become data.
Versions
- The contract.
-
A minor revision (tool.v1.1, …) may add optional manifest keys, optional result fields, shared error codes, handler kinds, CLI dialects and appended catalog row fields. Readers ignore unknown keys.
-
A minor revision may not:
- rename or remove a field, or change a field’s type or meaning;
- add a required key;
- change the call shape;
- add, remove or redefine one of the eight actions;
- tighten a bound so that a passing manifest fails.
Any of those is tool.v2: a new file beside this one, served through the adapter for at least one release.
-
tool.v1.1 adds the optional progress update. It is an update beside the result, not a result field, and nothing about the call or the result changed.
-
- A tool.
- Patch: a guide, a summary or a fix.
- Minor: a new action, op, view, optional argument or data field.
- Major: an action, op or argument renamed or removed, a type changed, or a stricter approval.
- The promise. The stability promise and the conformance suite of the extension API are ADR 0059’s. This kit is the tool part of that suite.