Tool index
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.
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 iscrates/vulpine_cli/src/tool_index.rs; the TypeScript reader iscatalog/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
{
"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
manifestorpathis 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
- It decodes the document. A wrong
schema, an unknownorigin,installed_byor door, a malformed digest, a bad tool name or a name listed twice refuses the whole index:Invalidin Rust,ToolIndexInvalidin TypeScript. A missing or unreadable file isUnreadable/ToolIndexUnreadable. - It hashes each record’s
manifestandpath, 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 isunavailable. - 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). Abrain_*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 isadopt). - 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
envnames, 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.
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:
tool_disabled: the name is indisabled.door_not_allowed: the door is under[doors]and the name is not in its list.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 inenabled.
| 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|standalonesays it outright. Another value is read asgateway, 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_PATHandVULPINE_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.
#: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.
- 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 aclistub named from its file name (vulpine-fix-plainisfix_plain, or--name), registeredinvocable: false. - A
climanifest’shandler.execandhandler.digestare set to the pinned program. Any other kind keeps its bytes. - Every manifest is linted before anything is written. A
climanifest’s folder then runsvulpine tool check(lint, goldens, the generated negatives). Api_extensionornativemanifest is linted only. - A name another program or origin registered is refused (
already_registered) unless--replaceis given. Adopting the same program again replaces its own records. - The manifests land in
adopted/<name>/beside the index. Each record hasorigin = "adopted",signer = "none",paththe program,sha256its bytes, andinstalled_byfrom--installed-by(defaultcli).
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, …).