---
title: "Brain tools"
description: "The bundled pi extension that gives the voice brain its gateway tools: work capture and status, background work, alarms and timers, the self-tools over the Admin socket, and the bounded Herdr tools."
type: "living"
source: "crates/voice_gateway/extensions/brain-tools/README.md"
verified: "2026-11-14"
group: "The brain"
---

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

The bundled Pi extension that gives the voice brain its `brain_*` tools: work capture and status, background work,
alarms, watches, self-reports and bounded Herdr control. Each tool is a closed request that the Gateway validates.

## Tools

- `brain_capture_work`: submits bounded text to the webhook receiver (the Receiver MCP below) as a durable,
  idempotent inbox envelope. Success means **captured for review**, not landed in Memento.
- `brain_work_status`: reads bounded canonical workflow status from `mm serve` via `memory_work_status`.
- `brain_background_work_start`, `brain_background_work_status` and `brain_background_work_cancel`: background work
  owned by the calling brain continuity. The Gateway mints the work IDs, caps global and per-continuity admission,
  and owns the accepted/running/completed/canceled/failed state. Each attempt runs in a separate ephemeral Pi process
  with no tools, extensions, skills, context files, approval or persistent session. Foreground loadout tools never
  cross into it. `[tools] background_toolset = "herdr-readonly"` gives the attempt the fixed read-only Herdr status
  toolset and the extension bundles that define it. `research-readonly` (the operator loadouts) adds `pi_code_search`
  and the `fox9docs` reads. A call to a tool outside the attempt's grant stops it (`background_work_tool_refused`). A
  completed job's sources (titles and hosts) show as one `card.v1` panel beside the spoken result. These tools expose
  no session selector, caller ID, command, shell, MCP method, transcript or approval field.
- `brain_alarm_set`, `brain_alarm_list` and `brain_alarm_cancel`: schedule, list and cancel Gateway-owned alarms and
  timers. The Gateway fires them with a chime and a spoken line on the live frontend, never on a room speaker. The
  set and list answers carry `rings_on` (the frontend's room, the gateway machine's default output).
- `brain_watch_set`, `brain_watch_list` and `brain_watch_cancel`: "tell me when X". A watch is a typed condition
  (`arrive_home`, `enter_room`, a herdr `agent` reaching done or needs-you, an agent's `ci` passing or failing, a
  `camera` label, a `sound` class heard in a room, an `output` marker printed by a Gateway-owned pane) plus the line
  to say. The Gateway keeps it in `<state>/watches.json` (owner-only, at most 32 open)
  and speaks the line through its announcement governor when the condition happens, with no brain turn. Ids are
  `watch-<n>`, never read aloud. There is no URL condition.
- `brain_mic_recalibrate`, `brain_gateway_health`, `brain_frontend_status` and `brain_frontend_control`: self-tools
  over the Gateway Admin socket. They run one rate-limited mic recalibration step, read the health (the grouped issue
  line when something is wrong, else the components) and capture liveness, and queue one desktop-client `reconnect`,
  `status` or `showcase` action. The outcome lands on the Admin event timeline.
- `brain_vulpine_report {topic, window_hours?, host?}`: Vulpine's report on itself over the Admin socket
  (`get_vulpine_report`, owner-local). The topics:
  `health`; `latency` (felt reply time per hour from a two-day ring, the slowest hour in the asker's local time and
  its slowest leg); `nightly` (the newest harness nightly receipt and its failed suites); `errors` (warnings and
  failures by component, and the usage ledger's failed tools); `events` (today's gateway events as hourly counts);
  `connections` (connector, device and extension rows: set up, broken, never seen); `usage`; `host` (one inventory
  host's uptime, load, memory, disk and GPU from the fleet store's last probe, plus the Vulpine launchd jobs on the
  gateway's own host); `tools` (the tools by kind and each MCP server); `setup` (what is not set up, each with its
  next step); and `features` (the feature switches that ship and are off). A `host` label outside the
  inventory is refused with the inventory's labels. The tool speaks the gateway's `say` and labeled facts and puts up
  its `card.v1`. A report holds counts and names only: never an event message, a transcript word, a path, an id or a
  hex token.
- `brain_herdr_state`, `brain_herdr_agent` and `brain_herdr_pane`: bounded read-only Herdr workspace/agent/pane
  observation.
- `brain_herdr_work_graph`: no arguments. Reads the current continuity's Gateway-owned work/ownership/agent/pane
  graph, observer freshness, and deduplicated blocked/done attention. Blocked and done are lifecycle states, never
  verified task success. It returns no pane output, transcript, path contents or cross-continuity records.
- `brain_herdr_attention`: takes one Gateway-owned `ownership_id` and returns what changed in that pane's repository:
  at most 32 sorted relative paths with status and addition/deletion counts, in at most 17 KiB, with no file contents
  or patch bodies. The root is the loadout's configured relative project root and must be a direct, non-linked
  repository with an ordinary `.git` directory.
- `brain_herdr_command`: takes a Gateway-owned `ownership_id` and one closed recipe (`working_directory` or
  `git_status_short`). The Gateway reserves an available owned pane and asks Vigil for a single-use confirmation. No
  native command method is admitted: approval settles as `command_held`, and nothing runs.
- `brain_herdr_create_agent_pane` and `brain_herdr_start_agent`: create one Gateway-owned pane from exact source
  context, then start one closed agent kind using only the returned ownership ID.
- `brain_herdr_cancel_owned_agent`: closes one exact continuity-owned started-agent pane, with bounded
  reconciliation on uncertain transport.
- `brain_herdr_wait`: starts one Gateway-owned wait bound to the current monitored target, pane, continuity and
  observer generation.
- `brain_herdr_focus`: sends one typed `pane_id` to the Gateway dispatch socket and waits for the Gateway's result. It
  does not call Herdr.
- `brain_herdr_close` (the bundled operator loadouts allow it): closes exactly one named pane
  (`pane_id`) or workspace (`workspace_id`) in two calls. The first call closes nothing. The Gateway reads the session
  and HOLDs on any doubt (a working or blocked agent, the last pane or workspace, a Gateway-owned pane, a worktree
  workspace, a name two targets answer to), or answers with a read-back and a single-use code. The operator says the
  exact words the read-back names (`close <name>`); the Gateway hears them itself, and a plain yes is not enough. The
  second call carries the code. The Gateway re-reads the session, saves each closing pane's recent output to
  `herdr-closed/` in its private state folder, closes, and proves the other panes or workspaces are still there. The
  schema has no confirmation field a model could fill.

Every tool here speaks tool.v1: it is called as `{action, args}` and declared from its manifest,
`catalog/pi/tools/<name>/tool.toml` (handler `native`). The old flat call is still accepted. A new brain tool adds a
manifest and a row in `v1.ts` beside its registration, and a row in `crates/voice_gateway/src/routing/brain_v1.rs`
when the gateway reads its call.


Agent prompts are not a brain-tools tool. The extension does not register `brain_herdr_prompt_agent`, and Agent
loadouts do not allow it. The brain messages Herdr panes through `pi_herdr_prompt` in
`catalog/pi/extensions/vulpine-tools/`, which re-checks the pane's identity before it sends.


No generic approval, message bus, session selection, arbitrary MCP call, shell execution or model-selected Herdr
method is exposed. Every Herdr mutation not listed above is absent.

Background status keeps the raw final result text for at most five minutes. After that, status may return a
result-free tombstone with `payload_retained: false`. The Gateway persists the work ledger in a private Redb store, so
a restart keeps the accepted queue. An attempt in flight at a restart settles as failed.


Brain loop containment (`catalog/pi/extensions/vulpine-tools/containment.ts`) watches for a brain that repeats
itself. Each assistant message is reduced to its normalized text plus its tool-call shapes (name and key-sorted
arguments) and hashed. When the tail of a session repeats the same message, or the same cycle of two, three times
within 120 s, the extension writes one `brain_loop_suspected` receipt to the tool-receipt spool. The receipt's tool
is `pi_brain_containment`, with fields `session` (an ordinal), `repeats`, `window` (the cycle length), `lane`
(`foreground` or `background`) and `aborted`. The Admin's Tools view lists it with the other receipts.

- It is observe-only and on by default. `VULPINE_BRAIN_CONTAINMENT=0` turns it off.
- With `VULPINE_BRAIN_CONTAINMENT_ABORT_BACKGROUND=1` (default off), a background lane whose tail reaches five
  repeats is aborted and leaves a second receipt with code `BRAIN_LOOP_ABORTED`. A foreground voice turn is never
  aborted.
- Only the read-only remote background tier loads it. The tool-free tier runs Pi without extensions and is not
  watched.


## Adding a tool: the six places it must be registered

A brain tool missing from any one of these places fails silently: the brain says the tool is unavailable, or never
calls it, and nothing logs an error. Most new tools are `pi_*` tools in
[`catalog/pi/extensions/vulpine-tools/`](/docs/the-brain/tool-policy); the `brain_*`
tools in this bundle differ only in places 1 and 6. In order:

| # | place | the file | the check that proves it |
|---|---|---|---|
| 1 | **The registration** in the Pi extension | `pi_*`: the domain's `register<Domain>Tools(cx)` in `catalog/pi/extensions/vulpine-tools/<domain>.ts` through `cx.registerTool` (schema in `schemas.ts`, the guard's per-tool rule in `guard.ts`). `brain_*`: `crates/voice_gateway/extensions/brain-tools/index.ts`, plus the gateway's closed operation for it | `bun run test` in `catalog/pi/extensions/vulpine-tools` (or `bun test crates/voice_gateway/extensions/brain-tools/index.test.ts catalog/agents/brain-tools-loadouts.test.ts`) |
| 2 | **The receipt fields** (`pi_*` only) | `TOOL_RECEIPT_FIELDS` in `catalog/pi/extensions/vulpine-tools/receipts.ts` (the closed params/details keys), and a `TOOL_EGRESS` line when the tool reaches a fixed host | the catalog lint (place 5) refuses a `pi_*` tool with no receipt field subset |
| 3 | **The loadouts** | the tool name in `[tools] allowed_pi` of `catalog/agents/operator/.vulpine/loadout.toml` AND of every per-client loadout a client binds (`catalog/agents/operator/.vulpine/loadouts/laptop.toml`, `vigil.toml`, …); the extension itself in the loadout's `extensions` list (`local:vulpine-tools`, `builtin:brain-tools`). `allowed_pi` alone does nothing: the gateway spawns pi with `--no-extensions` and only the listed extensions | the catalog lint (place 5): a registered tool no loadout allows, or a loadout naming a tool nothing registers |
| 4 | **The gateway's allow-list test** | the exact `allowed_pi` array of `loadout.toml`, copied in `crates/voice_gateway/src/loadout.rs` (`repository_voice_loadout_resolves_the_bundled_brain_tools`); the gateway also caps each tool's declared `risk` against the loadout's `tools.max_risk` at bind | `cargo test -p vulpine-voice-gateway --lib loadout`; the catalog lint flags the array drifting from `loadout.toml` |
| 5 | **The catalog and the reference** | the tool's capability family (its domain capability and search tags, ADR 0050 §2) in `FAMILIES` of `catalog/pi/extensions/vulpine-tools/catalog_provenance.ts`; `catalog/pi/tool-catalog.json`, regenerated by `bun run catalog` in `catalog/pi/extensions/vulpine-tools`; then `docs/reference/brain-tools.md`, regenerated from the catalog by `just docs-reference` | the `tool-catalog` hk step (`bun catalog.ts --check`, fast tier, every commit touching the extensions, the loadouts or `loadout.rs`) refuses a stale catalog or a lint error (a row no family covers is a `capabilities_undeclared` warning); the `docs-reference` hk step (`tools/docs/docs_reference.py --check` and `docs_coverage.py --fail-on tool`) refuses a stale reference page |
| 6 | **The deploy** | `pi_*`: the brain loads `catalog/pi/extensions/vulpine-tools` from the gateway host's own checkout, so the commit reaches it by `just mini-sync-checkout` (a fast-forward and a gateway kickstart; it does not install packages, so run `npm ci` in the extension dir there when `package.json` changed). `brain_*`: this bundle reaches the runtime root by `just deploy-brain-tools` (built `--target node`, load-tested in Pi on the gateway host before install). An overlay roll carries neither | the newest session trace's `brain_identity_bound` names the loadout the client bound and its `--tools` list holds the new name; the call itself shows in the Pi session log |

Two traps beside the six. Every spawn inside a tool uses absolute paths, the interpreter included (`/bin/sh`), because
the gateway's launchd PATH is minimal. And a receipt field the gateway adds must be added to the bundle's reply
parser too, or the call reads as unavailable.

## Deployment environment

Credentials and endpoints are deployment configuration. They are never model-visible tool arguments and are never
committed.

Receiver MCP:

- `VULPINE_RECEIVER_MCP_URL`
- `VULPINE_RECEIVER_ACCESS_CLIENT_ID` and `VULPINE_RECEIVER_ACCESS_CLIENT_SECRET`, required together for non-loopback
  endpoints. A literal `http://127.0.0.1/...` or `http://[::1]/...` deployment may omit both only when the receiver
  runs as a separate loopback-only, non-tunnelled service. Credentialed endpoints require HTTPS, may not contain URL
  userinfo, and reject redirects rather than forward Access headers to another origin.

Herdr Unix socket:

- `VULPINE_HERDR_SOCKET_PATH`: required absolute path to the deployment-owned Herdr Unix-domain socket. The gateway
  launch environment supplies it, never Pi/model arguments or agent files.
- The Gateway service account needs read/write permission on that socket. The socket directory must not be writable
  by the voice process.
- Transport is Node's built-in `node:net`: one newline-delimited JSON request per connection, `{id,method,params}` to
  `{id,result}` or `{id,error}`. Bounds: 10 seconds, 64 KiB transport, 32 KiB projected text/result.
- Read tools use this socket directly. Mutation tools do not. Only the Gateway collects owned-pane attention, through
  fixed, bounded Git metadata commands; linked-worktree Gitfiles fail closed. The Gateway sends `pane.focus` only
  after validated frontend approval. It never sends native `agent.prompt`.

Gateway mutation dispatch:

- The Gateway creates a per-brain private Unix socket and a random 64-hex token, and injects both into that Pi child
  as `VULPINE_GATEWAY_MUTATION_SOCKET_PATH` and `VULPINE_GATEWAY_MUTATION_TOKEN`. Neither is a model argument.
- The extension sends only closed, operation-specific envelopes. The Gateway rejects any request whose fields do not
  match the active brain tool call.
- Vigil must advertise `herdr.pane.focus`. The Gateway issues a 30-second, single-use challenge bound to the exact
  action, pane and session. Pi never confirms its own request; Vigil only returns the human decision.


Gateway Admin socket:

- `VULPINE_ADMIN_SOCKET_PATH`: optional absolute path for the self-tools; defaults to
  `~/.local/state/vulpine/admin/admin.sock`.

Memento stdio MCP:

- `VULPINE_MEMENTO_ROOT`: required absolute workspace root.
- `VULPINE_MEMENTO_COMMAND`: optional deployment-owned command path; defaults to `mm`.

Capture keys are `fox9_` plus the SHA-256 of the complete Pi tool-call ID. Success requires an exact matching
receiver delivery ID. MCP handshakes and calls are bounded to ten seconds and propagate Pi cancellation. Memento stdio
messages are capped at 64 KiB and status text at 32 KiB. The Memento child inherits only the MCP SDK safe environment
allowlist plus `MEMENTO_ROOT`.


The Nix Gateway package bundles this extension and its MCP SDK dependencies into
`share/foxline/extensions/brain-tools/index.js`. The Gateway wrapper sets `VULPINE_RUNTIME_ROOT`, and persisted
config cannot redirect the bundled extension directory away from that immutable root.

