Skip to content
Vulpine
Esc
↑↓navigate↵open⌘Jpreview
On this page

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 in prefill_form.ts, the envelope text in catalog/pi/tool-v1-envelope.txt, and the manifest reader and lint in tool_manifest.ts and catalog_manifest.ts. The gateway’s side is crates/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.toml and whatever answers it: a Pi extension, an MCP server or any executable that reads JSON and writes JSON. vulpine tool check lints, 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, tool is the function name and the arguments object is {action, args}. A CLI or MCP handler gets the three keys as one object.
  • action is one of the eight below.
  • args is 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.

  • aborted means the caller’s signal stopped the call: a stop or a barge-in. runV1 settles 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_extension tool passes this object to Pi’s onUpdate (execute’s fourth argument). Pi emits it as tool_execution_update with partialResult set to it, and the gateway reads partialResult.details.progress (crates/voice_gateway/src/progress.rs, ToolProgress).
  • stage is 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’s line_is_speakable. A stage that breaks the rule is dropped where it is made, counted, and never sent or thrown. Counts go in done and total, which are whole numbers. The gateway reads them out (“two of three”) only when total is at most 100.
  • The helper. A handler’s ctx.progress(stage, done?, total?) checks the rule and calls onUpdate (tool_v1.ts: progressReporter). A core behind an adapter builds the same function with progressReporter(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_change and pi_web_image report 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."}}
  • job is the gateway’s background work id: brain_background_work_status and brain_background_work_cancel take it. say is 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 aborted as usual. A stop after it settles the job aborted, which the gateway turns into the background work’s cancel. latency_budget_ms still ends the call (settled timeout).
  • 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 fails tool_call_deadline at the tool’s latency_budget_ms plus 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 say follows the same rule (“I will say when the is 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_history and pi_internet_search set 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 act op or a get view, never a new action.
  • These words are not actions: status is get, remove is delete, read is get, and subscribe is watch. start and stop are create and delete of a job, or an op. capabilities is the tool search’s get.
  • A ninth action needs extra_actions = [{name, reason}]. The kit warns on it.
  • describe is reserved: pi_tool_search answers 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_form picks the form for a brain launch: full (the default) or slim. Under slim the envelope text above goes into the system prompt and each tool is declared by its form; under full every 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 to full.
  • The one line. A tool’s one line is its description’s first sentence plus its action choices 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 read keeps Pi’s; both count as full. The catalog row carries form, line, slim_tokens and guide_tokens.
  • The trace. Every launch writes one tool_prefill line: 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 add fields named in receipt.fields.
  • The incur dialect. dialect = "incur" accepts an incur-style CLI’s {ok, data, error{code, message, cta}}: message and cta become hint.

The cli runtime (catalog/pi/extensions/vulpine-tools/tool_cli_handler.ts):

  • The executable. handler.exec is absolute, or relative to the manifest’s folder; a relative path that leaves its folder is refused. Its sha256 is checked against handler.digest before the first run in the brain process. A mismatch answers refused on every call until the tool is pinned again and the brain restarts. A missing executable answers not_set_up.
  • The call. deadline_ms is relative: handler.timeout_ms. call_id is Pi’s tool-call id. The child runs in the manifest’s folder, in its own process group, with only the handler.env names that are set. PATH is 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’s errors.codes and the shared codes becomes handler_failed, and the tool’s hint is kept. For incur, the code is lower-cased and the hint is message then cta. cta may be a string, {description}, {command} or a list, read from error.cta or meta.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 is timeout_ms + 500 ms. No hint names a path.
  • The receipt. egress_host is the manifest’s first egress host, and receipt.fields are read from data. The trace carries cli_* 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_ms and bytes_out.
  • Registration. At load, every compiled cli manifest 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 kind cli, source cli:<name>, provenance core for a repo manifest, and capabilities and tags from the manifest; a state-changing action derives write.

The conformance kit

vulpine tool check <dir> [--net] [--json] [--against <old tool.toml>]:

  1. 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.
  2. Golden calls. Each golden/<name>.json is {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.
  3. Price. It prints the slim declaration’s and the guide’s tokens, with brain_prompt_cost.py’s estimator.
  4. 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 outside gateway);
    • actions: actions_empty, action_unknown, action_describe, extra_action_no_reason, extra_action (a warning), approval_unknown, approval_floor (waived to the warning approval_floor_waived by a non-empty per-action approval_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, plus clean, which passes.

  • Golden calls. A pi_extension or native tool runs through bun catalog/pi/extensions/vulpine-tools/tool_golden.ts <dir> --json from the repo root (bun from VULPINE_BUN, else bun on PATH). A cli tool runs under the same rules as the cli runtime. The kit does not run an mcp handler. A cli answer with no boolean ok, an empty answer, or ok: false with no error is handler_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, a cli tool that declares network runs 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.

  • --against names 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, a cli tool replays the old folder’s goldens.

  • The report (--json, schema vulpine.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. action is the tool.v1 action, with fields.op or fields.view. fields.legacy_action is 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 on and deferred tools.
  • 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 prepareArguments and receipted with legacy_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.

Was this page helpful?