---
title: "Tools"
description: "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."
type: "living"
source: "docs/contracts/tool.v1.md"
verified: "2026-11-14"
group: "Contracts"
---

> **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](/docs/contracts/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](#versions) is this contract's own
  rule.

## The call

```json
{"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

```json
{"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.

```json
{"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:

```json
{"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 <tool> 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 <tool> 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):

```text
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.

```toml
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](#progress-minor-revision-toolv11). 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.

