---
title: "Tool index"
description: "tool-index.v1 (accepted, ADR 0063; S1 and S2 built): the one list of registered tools, tool-index.json in the vulpine config folder, each with its provenance record (origin, signer, the sha256 and path of what runs, installed_at/by, requires, doors, invocable, last_used, calls_30d); a reader in Rust (vulpine_cli) and in TypeScript (vulpine-tools, Effect) marks a tool unavailable when a pinned file is missing or its sha256 differs; vulpine tool list / why / describe / doctor read it, JSON on a pipe, and list shows vulpine-* PATH programs as found_on_path, not registered, not runnable, never run; brain_* tools are invocable only at the gateway door."
type: "living"
source: "docs/contracts/tool-index.v1.md"
verified: "2026-11-14"
group: "Contracts"
---

> **Living doc**, checked against the code 2026-11-14

tool-index.v1 — the one list of registered tools, each with its provenance record

- Status: accepted with ADR 0063, version 1.0. The schema is
  `tool-index.v1.schema.json`. The Rust reader is `crates/vulpine_cli/src/tool_index.rs`;
  the TypeScript reader is `catalog/pi/extensions/vulpine-tools/tool_index.ts`.
- The gateway and MCP do not read the index to decide what they register. The gateway applies the tools policy by
  name. The index is not signed.
- Scope: which tools exist for Vulpine, where each came from, and whether it can run. A tool exists only when its
  tool.v1 manifest is registered here. A program's name never registers it, and a folder on PATH does not either.


## Where it lives

`tool-index.json` in the Vulpine config folder: `~/.config/vulpine`, or `~/.config/foxline` on an install that has
only that one. Rust resolves it through `admin_markers::roots`, TypeScript through `configRootIn`, with the same rule.
Every verb also takes `--index <path>`.

## The document

```json
{
  "schema": "vulpine.tool-index.v1",
  "written_at": "2026-11-02T18:00:00Z",
  "written_by": "vulpine tool index",
  "tools": [
    {
      "name": "pi_calendar_today", "version": "2.0.0", "summary": "…", "kind": "pi_extension",
      "manifest": "/…/catalog/pi/tools/pi_calendar_today/tool.toml", "manifest_sha256": "sha256:…",
      "origin": "bundled", "signer": "none",
      "path": "/…/catalog/pi/tools/pi_calendar_today/tool.toml", "sha256": "sha256:…",
      "installed_at": "2026-11-02T18:00:00Z", "installed_by": "cli",
      "requires": [], "doors": ["gateway", "pi", "cli", "mcp"], "invocable": true,
      "last_used": null, "calls_30d": null, "loadouts": ["laptop", "vigil"]
    }
  ]
}
```

Every record holds the ADR's provenance fields, plus `kind`, `manifest`, `manifest_sha256` and `loadouts`:

| field | meaning |
|---|---|
| `name`, `version`, `summary` | from the manifest (`summary` is its `purpose`) |
| `kind` | the manifest's handler kind: `native`, `pi_extension`, `mcp`, `cli` |
| `manifest`, `manifest_sha256` | the `tool.toml`, pinned |
| `origin` | `bundled`, `pack`, `local`, `adopted` |
| `signer` | the Team ID or index key that signed it; `none` when unsigned |
| `path`, `sha256` | what runs, pinned: a `cli` handler's executable, else the manifest itself (the code behind a native or Pi tool is pinned by the bundle it ships in) |
| `installed_at`, `installed_by` | RFC 3339 UTC; `admin`, `cli`, `agent`, `installer` |
| `requires` | the manifest's own `requires` first (`gateway` for a tool that only works on the gateway's Pi), then `gateway` for a native handler when that did not name it, then `host:<name>` for each egress host; `tcc:<grant>` and `model:<id>` are reserved |
| `doors` | `gateway` only for a native handler, else all four |
| `invocable` | false for a listed-only record |
| `last_used`, `calls_30d` | from receipts, `null` until derived |
| `loadouts` | the catalog loadouts that enable it, as of the write |

- **Paths.** A `manifest` or `path` is absolute, or relative to the index's own folder. The registration step writes
  absolute paths.
- **Versions.** A reader ignores fields it does not know, so adding a field is a minor revision. Removing or renaming
  a field, or adding an enum value a v1 reader would refuse, needs tool-index.v2.

## What a reader does

1. It decodes the document. A wrong `schema`, an unknown `origin`, `installed_by` or door, a malformed digest, a bad
   tool name or a name listed twice refuses the whole index: `Invalid` in Rust, `ToolIndexInvalid` in TypeScript.
   A missing or unreadable file is `Unreadable` / `ToolIndexUnreadable`.
2. It hashes each record's `manifest` and `path`, each file once, and never runs anything. The problems are, in
   order: `manifest_missing`, `manifest_sha256_mismatch`, `missing_file`, `sha256_mismatch`. A record with any
   problem is `unavailable`.
3. A door may call a tool when it is registered invocable, available, and the door is in its `doors`. That is the
   door's tool set (`door_tools` / `doorTools`). A `brain_*` tool is listed in every context and is invocable only at
   the gateway.

## The verbs

Every verb writes JSON when stdout is not a terminal, or when `--json` is given. The reading door is `cli` unless
`--door` names another. The exit codes are 0 ok, 1 findings, 2 I/O (no index) and 64 usage.

| verb | prints | schema |
|---|---|---|
| `vulpine tool list` | the registered tools with their status and `invocable` for the reading door. Then each `vulpine-*` executable on PATH that no record pins, marked `found_on_path, not registered, not runnable` | `vulpine.tool-list.v1` |
| `vulpine tool why <name>` | the record, its status, and the loadouts that enable it | `vulpine.tool-why.v1` |
| `vulpine tool describe <name> [--form slim\|full]` | `{name, description, parameters}` as built from the manifest: the one line for slim, the guide (else the purpose) for full. Also the declaration's tokens and the kit's `slim_tokens` and `guide_tokens` (`price.rs`) | `vulpine.tool-describe.v1` |
| `vulpine tool doctor` | every unavailable tool and its problems; exit 1 when there is any | `vulpine.tool-doctor.v1` |
| `vulpine tool index --write <path>` | registers each `<name>/tool.toml` under `--tools` (default: the checkout's `catalog/pi/tools`) that lints. It keeps `installed_at` and `installed_by` for a tool whose pinned bytes did not change, and exits 1 when it skipped a folder | `vulpine.tool-index-write.v1` |

The PATH listing:
- It reads directory entries and mode bits only. Nothing found on PATH is opened or run, not even with
  `--vulpine-manifest` (that is `adopt`).
- It skips a relative PATH entry.
- It keeps the first find for each name, as a PATH lookup would.
- A find is never in the index, so it is in no door's tool set.

For Pi tools, the slim declaration that `describe` prints is the words Pi sees. A tool whose TypeScript code
registers its own `parameters` gives Pi those parameters, not the manifest's.

## The cli door: `vulpine tool run`

`vulpine tool run <name> <action> [--args '<json object>'] [--index <path>] [--json]` makes one call through the
`cli` door. It prints the tool.v1 envelope with its `receipt` last. It appends that receipt to the spool the brain's
calls use: `VULPINE_TOOL_RECEIPTS_PATH`, else `tool-receipts.jsonl` in the Vulpine state folder, never on a volume.
The receipt has the same shape as receipts.ts's. Its fields are the call's `action`, the manifest's `receipt.fields`
read from `data`, `origin = "cli"`, the handler's `cli_path`, `cli_exit_code` and `cli_bytes_out`, and `op` /
`view`. Exit codes: 0 when the envelope is ok, 1 when the tool answered `ok: false` or the door refused, 2 I/O (no
index), 64 usage.

The index alone decides what runs, checked in this order. Each refusal is an envelope with a shared `code` and a
typed `error.reason`. Only a registered tool gets a receipt.

| reason | code | when |
|---|---|---|
| `found_on_path` | `refused` | the name is not registered but matches a `vulpine-*` find on PATH, which is never run |
| `not_registered` | `refused` | the index has no such tool |
| `requires_gateway` | `refused` | its `requires` names `gateway` (every `brain_*` and `native` tool) |
| `not_invocable` | `refused` | the record is listed-only |
| `door_not_allowed` | `refused` | `cli` is not in its `doors` |
| `manifest_missing`, `manifest_sha256_mismatch`, `missing_file`, `sha256_mismatch` | `unavailable` | the pinned files are not what the index recorded at install |
| `handler_unsupported` | `refused` | the handler is not `cli`; a `pi_extension` or `mcp` tool answers through the `pi` door |
| `manifest_invalid`, `path_mismatch` | `unavailable` | the pinned manifest does not lint, names another tool, or names another program than the index pinned |
| `digest_mismatch` | `refused` | the executable is not `handler.digest` at bind |

The call runs through the kit's runner, `runner.rs`, with the runtime's cli handler semantics:

- The manifest's decode runs first.
- The executable is pinned by absolute path. The env is scrubbed to the manifest's `env` names, with no PATH.
- The call goes on stdin. The answer is one result object of at most 64 KiB. The deadline is `handler.timeout_ms`.

A golden call answers through `run` byte for byte what it answers through `vulpine tool check`.

## The tools policy

`tools.toml` in the Vulpine config folder, beside the index. Every door reads it, and no door widens it. An absent
file changes nothing.

```toml
schema = "vulpine.tools-policy.v1"      # optional; another value refuses the file
path_discovery = "list"                 # "list": PATH finds listed, never run. "off": PATH is not scanned
allowed_origins = ["bundled", "pack"]   # the default once a file exists; without a file every origin is allowed
enabled = []                            # per-tool opt-in; also lets a local or adopted tool through
disabled = ["pi_obs"]                   # off at every door; wins over enabled

[doors]                                 # a door named here exposes only these tools; a door not named narrows nothing
mcp = ["pi_calendar_today"]
```

The file is refused whole if it has an unknown key, another `schema`, a `path_discovery` other than `list` or
`off`, an unknown origin or door, or a name that is not a tool name. The checks run in this order, and each refusal
is a typed reason:

1. `tool_disabled`: the name is in `disabled`.
2. `door_not_allowed`: the door is under `[doors]` and the name is not in its list.
3. `origin_not_allowed`: only where the door knows the tool's origin (from the index). The origin is not allowed
   and the name is not in `enabled`.

| reader | when it reads | what a refusal does | a file that does not read |
|---|---|---|---|
| `vulpine tool run` (cli) | every run | the refused envelope with the reason; `path_discovery = "off"` names no PATH find | every call is refused `policy_unreadable` |
| `vulpine tool list` | every run | `path_discovery = "off"` lists no PATH find | lists as before |
| the `pi` door (`tool_policy.ts`) | once at load | the tool is not registered. The door is the `host` profile's: `gateway` for the gateway's Pi, `pi` for a standalone one | registers as before and says why on stderr |
| the gateway (`tool_policy_gate.rs`) | at start, then whenever the file's modification time or length changes (a stat every 2 s on its own thread) | the typed tool door refuses the call. At the next bind the tool leaves `allowed_pi` for `off_pi`, so Pi is never given it. A locked safety tool (`tool_toggles::LOCKED`) stays bound | keeps the last good policy, or none at start |

The door and the bind read the gateway's held copy, so the policy costs 0 ms per turn and per call. The cli door and a
standalone Pi read origins from the index. The gateway's Pi and the gateway read no origins.

`vulpine tool enable|disable <name> [--policy <path>]` writes the file. It uses toml_edit, so comments and layout
survive. The write goes to a sibling file (0600), then a rename. A file that does not read is never edited. A new file
starts from a commented template. `disable` moves the name into `disabled`, and `enable` moves it into `enabled`.

## The host profile

The standalone Pi's door is the same `vulpine-tools` extension. `host_detect.ts` names the host once at load, and
`host_profile.ts` (an Effect Layer) holds what follows from it.

How the host is read:
- `VULPINE_HOST=gateway|standalone` says it outright. Another value is read as `gateway`, with a line on stderr.
- Otherwise the Pi is the gateway's when any name of the gateway's handshake env is present, even empty:
  `VULPINE_BRAIN_LANE` (set on every Pi the gateway launches), `VULPINE_GATEWAY_MUTATION_SOCKET_PATH` and
  `VULPINE_GATEWAY_MUTATION_TOKEN` (both spellings), `VULPINE_TOOL_FORM`, `VULPINE_DEFERRED_TOOLS`.
- With none of them the Pi is standalone.

| | the gateway's Pi | a standalone Pi |
|---|---|---|
| policy door | `gateway` | `pi` |
| a tool whose `requires` names `gateway` | registers | never registers |
| the tool index | not read | read when it exists. It decides what exists, in `vulpine tool run`'s order: `not_registered`, `requires_gateway`, `not_invocable`, `door_not_allowed`, then the first problem. Then the policy, with the record's origin |
| without an index | — | `requires` comes from the compiled manifest by the writer's rule (the manifest's own `requires`, then a native handler needs the gateway), and the policy is read with no origin |
| `VULPINE_DEFERRED_TOOLS` | honored | not read: nothing is deferred |
| `VULPINE_TOOL_FORM` | honored | honored, so the eval can compare forms |
| an index that does not read | — | registers as if there were none and says why on stderr |

The host profile does not change what the gateway's Pi registers: its declarations hash the same with and without
the profile, under the slim and full forms. No `pi_*` manifest has a native handler. 17 of them say
`requires = ["gateway"]`, so a standalone Pi without an index registers 44 of the 61 `pi_*` tools. The 17 each call
the gateway's mutation socket for their answer, or its approval socket before they act:
`pi_calendar_change`, `pi_feature_request`, `pi_fleet_status`, `pi_home_act`, `pi_house_now`, `pi_meeting_minutes`,
`pi_memory_propose`, `pi_memory_recall`, `pi_notify`, `pi_recall_window`, `pi_restart_worker`, `pi_show_camera`,
`pi_show_file`, `pi_show_page`, `pi_show_render`, `pi_show_visual` and `pi_web_capture`.

`pi_tool_search` stays. Its `get` serves every tool's guide with no gateway call. With nothing deferred, its
`search` answers no match. The brain-tools extension's 28 `brain_*` tools are refused wherever the profile gates
them. The catalog generator and the golden runner load the extension as the gateway's Pi (`asGatewayHost`), so the
catalog lists all 61.


## Adoption

### A helper describes itself: `--vulpine-manifest`

A helper that backs a tool prints, on `--vulpine-manifest` (the flag alone), the `vulpine.helper-manifest.v1` stream:
one segment per file, a header line and then the file's exact bytes.

```text
#:vulpine-manifest <tool> <file> <length in bytes>
<the file's bytes>
```

`<file>` is `tool.toml` or the guide the manifest names. A tool's `tool.toml` comes first. The bytes are the
catalog's own `catalog/pi/tools/<tool>/` files, embedded at build time by `catalog_tool!` in
`crates/helper_manifest`. The CLI reads the stream with the same crate. A third-party program may print one bare TOML
manifest instead.

| helper | tools it prints |
|---|---|
| `brainctl` | `pi_calendar_today`, `pi_mac_control`, `pi_presence`, `pi_reminders`, `pi_room_speak`, `pi_where_is`, `pi_write_selection` |
| `roomctl` | `pi_room_ambience`, `pi_room_speak` |
| `herdrctl` | `pi_herdr_activity` (`checks`), `pi_herdr_convo` (`convo`), `pi_herdr_report` (`verify`), `pi_herdr_standup` (`standup`); `courier` is the gateway's |
| `vulpine-home` | `pi_home_recap` |

`vulpine-fleet`, `vulpine-provider` and `vulpine-wechat` print none: they back no brain tool.

`vulpine tool check --helper <program> [--tools <dir>]` runs the program with that flag (no environment, 5 s, 1 MiB).
It compares each file with the catalog copy under `--tools` (default: the checkout's `catalog/pi/tools`) and reports
`match`, `differs`, `missing` or `no_catalog_copy` per file, plus the lint. Schema `vulpine.tool-check-helper.v1`;
exit 1 on any finding.

### `vulpine tool adopt <program|path>`

A bare word is looked up in PATH's absolute entries as itself, then as `vulpine-<word>`. A path is used as given.
Either way the program is pinned by its canonical absolute path and its sha256.

1. The program is asked for its manifests as above. With `--manifest <tool.toml>` that file is used instead (with
   its guide from its folder). A program that answers nothing (a non-zero exit, a timeout, no output) gets a `cli`
   stub named from its file name (`vulpine-fix-plain` is `fix_plain`, or `--name`), registered `invocable: false`.
2. A `cli` manifest's `handler.exec` and `handler.digest` are set to the pinned program. Any other kind keeps its
   bytes.
3. Every manifest is linted before anything is written. A `cli` manifest's folder then runs `vulpine tool check`
   (lint, goldens, the generated negatives). A `pi_extension` or `native` manifest is linted only.
4. A name another program or origin registered is refused (`already_registered`) unless `--replace` is given.
   Adopting the same program again replaces its own records.
5. The manifests land in `adopted/<name>/` beside the index. Each record has `origin = "adopted"`, `signer = "none"`,
   `path` the program, `sha256` its bytes, and `installed_by` from `--installed-by` (default `cli`).

A rebuilt binary has another sha256, so every reader marks its records `unavailable` (`sha256_mismatch`) at every door
until it is adopted again. Adoption never edits `tools.toml`. Where the policy limits origins, an adopted tool still
needs `vulpine tool enable <name>`. Schema `vulpine.tool-adopt.v1`; refusals carry a `reason` (`not_found`,
`stream_invalid`, `manifest_invalid`, `check_failed`, `already_registered`, …).

