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

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 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

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

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.

#: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, …).

Was this page helpful?