---
title: "Tool policy and search"
description: "vulpine-tools (was foxline-tools), the canonical pi extension for the voice brain's policy and tools (local search, the Herdr dispatch tools, the tool-call guard, the bash policy, Exa MCP) and its test runtimes."
type: "living"
source: "catalog/pi/extensions/vulpine-tools/README.md"
verified: "2026-10-04"
group: "The brain"
---

> **Living doc**, checked against the code 2026-10-04

This extension holds the brain's `pi_*` tools and the tool-call guard.

The package is `vulpine-tools` (`@voidfab/vulpine-tools`). A Pi settings file or a script names `vulpine-tools`. The
loadouts name it `local:vulpine-tools`, and the agents' `.vulpine/extensions/vulpine-tools` link points at this
folder; a loadout that still says `local:foxline-tools` binds the same package. The guard's refusal tag is
`[foxline-guard]`.


## Features

- Does not manage `bash` policy (configure it with Pi CLI args).
- `pi_file_searcher`, with actions `capabilities`, `find_paths`, `grep_content` and `list_dir`.
- `pi_github`: read-only GitHub status over the host's authenticated `gh`. The repo is always passed explicitly and
  must be in `VULPINE_GITHUB_REPOS`. With no env set, the default is the private checkout's repository, spoken as "the
  private repo".
  - Actions `runs`, `pr_list`, `pr_checks`, `issues` and `release_latest`. The guard refuses any other action.
  - Each result has a `summary` written to be spoken (counts, titles, relative times; no ids, shas or links) and
    compact `rows`. gh errors become a typed `code` and one sentence.
  - `pr_list` and `issues` speak the repo's true open count. A full page spends one GraphQL `totalCount` call, the
    result carries `counts.open`, `counts.shown` and `truncated`, and a failed count says "at least".
  - `stars` names the operator's newest stars and when each was starred (no links; descriptions in one nonce fence).
    `repo_read` opens one starred repo, named as spoken ("daedalus") or as owner/name, else the newest star. It
    answers the repo's facts, a file-tree summary (top folders, language mix, root manifests) and its README inside
    the fence. A repo outside the newest 100 stars and the allowlist is not read. Both put up their own `card.v1`.
- `pi_health`: read-only Apple Health facts through `runtime/health/healthctl.py` (`mode=ro` SQLite): `metrics`,
  `daily{metric, days ≤ 30}`, `recent{metric, n ≤ 20}`. The summary is facts only, never advice. Refusals are typed
  (`no_store`, `unknown_metric`, `bad_args`). The receipt carries the metric name and window, never a number. Bound
  once its readiness probe passes.
- `pi_dot`: hands a request to the operator's OpenAI Dot and reads the answer later, through
  `runtime/dot_worker/dotctl.py` and the loopback dot2api. `submit{task ≤ 2000 chars}` queues and returns at once;
  `result{task_id?}` reads the newest task. A completed answer reaches the brain only inside the nonce fence. The
  guard's flow tier counts `pi_dot:submit` as outbound and `pi_dot:result` as a private read. The receipt carries the
  action, status and length, never the text. Bound once its readiness probe passes.
- **The pipelines rounds** (`pi_herdr_dispatch pipeline`: the ripwire task map and rounds 9 to 12) are on
  [their own page](/docs/the-brain/pipelines-rounds).
- **`pi_show_render {kind, body}`** posts one render to the gateway's mutation socket (a body over 7 KiB is refused)
  and answers from the session's render router: drawn, refused, dropped, or sent with `no_receipt` after 3 s. The
  three operator loadouts (default, laptop, vigil) allow it.
- **`pi_show_visual {title, summary, script}` ([docs/contracts/visual.v1.md](/docs/contracts/visual.v1))**
  sends one script visual as kind `visual.v1`: a sandboxed Luau program whose view is a `ui.*` tree (charts, tables,
  stats, controls, canvases, 3D scenes, Shadertoy shaders). The gateway dry-runs the script first and answers a
  failure with its first error and line (`error: "visual:14: ..."`). A panel that draws cards but no scripts gets the
  visual's card (`projected_to: card.v1`). The screen loadouts (default, laptop, vigil) allow it.
- **`pi_show_file {path, title?, page?}` ([docs/contracts/file.v1.md](/docs/contracts/file.v1))**
  shows one file from the gateway's own disk in the conversation window's file pane, as kind `file.v1`. The screen
  loadouts allow it.
  - The gateway resolves the path against `[files] roots`. It refuses hidden or secret files, folders and files over
    `[files] max_bytes` with a closed reason and words to say, and sniffs the type from the bytes.
  - The window fetches the bytes by hash, never through the brain. A panel that draws cards gets the file's card.
  - `{describe, folder?, title?}` in place of the path makes the gateway find the file: its name index of the allowed
    folders, the local decision model for a close call, else a chooser of three on the operator's screen. The answer
    is only `found` (`shown` with `file_kind`, or `asked_user` with `choices`) or a refusal (`no_match` becomes
    `found: not_found`), never a name, folder, size or date.
- **`pi_feature_request {ask, missing, kind, family?, beyond_held?}`** logs an ask Vulpine cannot do yet. `kind:
  proactive` means the brain found the gap itself; `kind: asked` means the operator said "log that as a feature
  request".
  - The gateway keeps it in `feature-requests.json` under its state root: owner-only, at most 500 requests, deduped
    on the normalized ask.
  - The answer is `noted` or `noted_again` with a line to say, never an id or the stored words. The receipt carries
    the kind and the outcome. The catalog declares the tool a local write.
  - The three operator loadouts allow it. `just feedback::harvest` turns the requests into tracker drafts.
  - Two answers log nothing. `held`: the request names a tool not set up on this host (`VULPINE_HELD_TOOLS`, `{tool,
    label, next_step}`), so the answer says the next setup step; `beyond_held: true` logs it anyway. `ask_back`: the
    ask names no capability, so the brain asks what Vulpine should do.
- **`pi_web_image {query}`** finds a picture on the web and shows it. The three operator loadouts allow it.
  - It searches Openverse (keyless, `mature=false`), then Wikimedia Commons (keyless, free licenses) when Openverse
    does not answer. Mature results, and Commons results whose name or category reads as nudity or sex, are dropped.
  - The first PNG, JPEG, GIF or WebP of at most 8 MiB from a public host is saved as `<hash>.<ext>` under
    `~/Pictures/Vulpine/web` (the newest 40 of its own files kept) and shown through `file.v1`. Every hop passes the private-network
    guard, with at most 3 redirects.
  - The answer keeps `source_url`, `image_url`, `license` and `source`; the title and creator come back fenced. The
    `say` line names the subject, source and license, never a link or the file's name.
  - A fast transient failure (5xx, a 429 asking for at most 2 s, a network error) is retried once after 400 ms. A
    failed provider cools for five minutes. `pi_internet_search action=providers_status` reports it as
    `image_search`, from `web-image-providers.json` beside the receipt spool. Receipts carry `provider`,
    `fallback_from`, `primary_reason` and `primary_ok_age_s`.
- **The operator self-care tools (`selfcare/`).** The three operator loadouts allow all three.
  - `pi_versions {component?}` (read-only) compares what is installed with what is newest: Pi from the npm registry
    and its published CHANGELOG, herdr from herdr.dev/latest.json, and the gateway, the desktop client (`glyph`), the
    Admin (`admin`) and the web client (`vigil`) by the commits under their folders in the local repo since the installed build. Web notes come back fenced. The answer
    (without notes) is kept in `<state>/versions/versions.json` (0600), which the host report reads as `versions`.
  - `pi_restart_worker {action: crashed|restart, name?}`. `crashed` reads `launchctl list` and `print`. `restart`
    acts on one allow-listed target (`RESTART_TARGETS` in `selfcare/restart.ts`) after the approval socket says yes:
    `launchctl kickstart -k` for a job, quit and reopen for the Admin. It never restarts the gateway or the desktop client.
  - `pi_logs {action: size|plan|trim}` acts on the operator's own plain log files in the known log folders
    (`LOG_POLICY` in `selfcare/logs.ts`). Rotated copies older than two days are deleted; live logs over 8 MB are cut
    to their last megabyte. `trim` says the dry-run plan on the approval card first and re-checks each file before it
    acts. Session archives, receipts, traces and stores are never touched.
- **`pi_calendar_change {action, at, day?, title?, to_at?, to_day?, minutes?, calendar?}`** moves, creates or cancels
  one event through the grant holder's `calendar change`, launched with `open -W -b`. The three operator loadouts
  allow it.
  - Every call previews (`--dry-run`) and asks the approval socket with the change in words (the others invited as a
    count, a recurring event as "only this one"). It writes only on approved, and the holder re-reads the store after
    the save.
  - A meeting someone else organizes is refused (`not_organizer`). A write with no readable answer is `unverified`,
    never "not changed". The catalog row is `approval: confirm_before_write`.
- **`pi_tool_search {query, limit?}`** finds and loads a deferred tool: one set to `deferred` in the Admin's tool
  toggles, enabled but out of the prefill. The gateway lists deferred tools in `--tools` and `VULPINE_DEFERRED_TOOLS`,
  and offers `pi_tool_search` only when something is deferred.
  - A deferred tool gets pi's `exposure: "deferred"` and no prompt snippet; a deferred MCP tool is left out of the
    requests.
  - The search ranks deferred tools with BM25 over name, description and parameter names (no model), loads the
    matches for the session, and returns their names and schemas. The receipt never carries the query.
- **`pi_memory_recall {query?}` and `pi_memory_propose {fact, source}`** are the memory core tools, answered at the
  gateway's mutation socket. The three operator loadouts allow both.
  - `source` is `operator`, `tool` or `page`. An `operator` fact is kept at once only when the gateway heard the
    operator say it (their recent turns, or their yes to an ask-back naming it). Anything else is a proposal until
    they say yes, and lapses after 30 days.
  - Recall answers up to five facts as text, each kept or unconfirmed, with its age in days; never an id.
    Credential-shaped facts are refused for every source, and an instruction-shaped tool or page fact is refused.
  - The receipts carry the source, the outcome and counts, never a fact or a query.
- **`pi_notify {text, title?, urgency?}`** tells the operator something where they are. The three operator loadouts
  allow it.
  - The line goes on the operator's board as the `brain_notify` source, spoken when the room allows. It is pushed to
    their phone (Home Assistant companion app or ntfy) when they are in no session or it goes unspoken; `urgent` is
    pushed at once too.
  - The words are one plain sentence of at most 200 characters with no id, hex run, long number, path, file name,
    link, address or tool name. Repeats within ten minutes are sent once, at most ten an hour.
  - The answer is `queued` or `deduped`. The receipt carries the urgency and the outcome.
- **`pi_house_now`** reads the house in one call: a `house.v1` document from the gateway's room presence and the home
  bridge's state, with no new egress and no write. `[brain] house_now` (on) is the switch; the three operator loadouts
  allow it.
  - The document holds the operator's room, who of the household is home (never the zone of someone away), the rooms
    with occupancy, lights and players, the devices that are on, and the latest camera events as labels and ages. An
    interior (`announce: false`) camera is counted, never listed.
  - Each source says `ok`, `stale` or `unknown`. A home bridge that is down adds no rooms, people or devices.
  - The tool says one short line and puts up its own status card. The receipt carries counts only.
- **`pi_herdr_dispatch policy_diff {repo}`** is a read-only, door-only verb (a brain call is refused): one `git diff
  HEAD -- .vulpine/policy.toml` in that checkout on this host, capped at 8 KiB and 200 lines, for the Admin's "show
  the diff from HEAD" button.
- **Risk declarations.**
  - `pi_todo` never deletes. `remove` archives: the record keeps an `archived_at` stamp, drops out of the default
    list, comes back with `include_archived` and is restored by `unarchive`. `clear_completed` archives too. Declared
    `risk=write`.
  - `pi_satellite_timer` declares `stop` instead of `cancel` (a stopped timer is re-settable, so it is a write).
    `cancel` is still accepted as an alias.
  - `pi_herdr_dispatch` stays `destructive` and gets its confirm from the **approval socket** (the catalog shows
    `requires_confirm: true` without a `confirm_code` parameter). `prepare`, `pipeline` and `remove` (it deletes a
    dispatched task's worktree) ask first, and refuse with `{ok:false, error:"approval_refused"}` on a denial, a
    deadline, a cancellation or an absent socket or key. `collect`, `advance`, `retry`, `list` and `preflight` are not
    gated.
  - The `prepare` / `pipeline` card is an `exec` naming the checkout. The `remove` card is a **`delete`** naming the task, with the
    worktree path in `detail`. The gateway always asks for it: no policy file, 24-hour grant or learned trust
    pre-authorizes a `delete`.
  - Every gated ask names its pi `toolCallId` in `agent.call_id`, so the card and the "yes" stay in the session that
    asked.
- `pi_internet_search`, with actions:
  - `providers_status`
  - `search_web`
  - `fetch_url`
  - `papers`: keyless OpenAlex works search
    (`api.openalex.org`) — title, year, venue, first three authors, citations;
    `VULPINE_OPENALEX_MAILTO` joins OpenAlex's polite pool when set
  - `hn`: keyless HN Algolia story search (`hn.algolia.com`) — points,
    comments, the story link or its discussion. Both take `query`,
    `maxResults` and an optional `sinceDays`.
- `pi_obs` (the laptop loadout, bound once ready): OBS over obs-websocket v5 with 14 closed actions (recording, replay
  buffer, scenes, stream status/stop, virtual camera). Every write reads status first and answers a typed refusal
  (`already_recording`, `not_recording`, …). A scene is only a name `GetSceneList` returned. The password is read at
  call time from `~/.config/vulpine/obs.env` (`OBS_HOST`, `OBS_PORT`, `OBS_PASSWORD`; `VULPINE_OBS_ENV` overrides);
  missing is `obs_not_configured`. No stream start, no freeform request.
- `pi_mail` (bound once ready): read-only Gmail search on `from` / `subject` / `unread` / `label` / `since`, every
  operator word quoted. Metadata only (From, Subject, Date), no bodies. The spoken `summary` is counts and times;
  sender names and subjects travel only under `untrusted_mail`. The gmail.readonly token is read at call time from
  `~/.config/vulpine/gmail-token.json` (`VULPINE_GMAIL_TOKEN` overrides). `tools/mail/gmail_auth.py` signs in once and
  stores a refresh token; the tool refreshes the access token under 60 s left and rewrites the file 0600. Every
  refusal names its `cause`.
- `pi_feeds` (bound once ready): the operator's RSS and Atom feeds over the headless store `tools/feeds/feedctl.py`
  (no feed server). Closed actions `unread {limit}`, `read {id}`, `mark {id}` (idempotent). The spoken `summary` is
  counts. Titles, text and links travel only under `untrusted_feeds` with a data-not-instructions notice. Fetching is
  not a brain action: `feedctl refresh` runs on its own behind the page fetch's SSRF guard. `unread` puts the list on
  the screen as its own `card.v1` (a `list.v1` of title, feed and age).
- `pi_whatsapp` (bound once ready): the operator's unread WhatsApp chats over `runtime/messages/wactl.py`, which runs
  an installed `wacli` read-only (three allowlisted read commands; it never installs, pairs or marks read). Closed
  actions `unread {limit}` and `read {chat | ref, limit}`. The spoken `summary` is counts and names (contact names
  through the grant holder, a number masked to its last two digits). Message text travels only under
  `untrusted_messages`, each in the nonce fence.
- Search fallback chains:
  - local content: `rg -> grep -> builtin`
  - local paths: `fd -> find -> builtin`
  - web search: `searxng -> exa_mcp -> duckduckgo` under `auto`. The self-hosted SearXNG is asked only when
    `VULPINE_SEARXNG_URL` names one; a failure cools it for two minutes, which `providers_status` shows.
  - page extraction: local `defuddle` over a `linkedom` DOM, so no operator URL leaves the machines. The remote `jina
    reader` runs only with `VULPINE_FETCH_EXTRACTOR=jina`, or as a named fallback after a local failure (`provider:
    "jina_reader_fallback"` and `fallback_reason` in the receipt). `VULPINE_FETCH_REMOTE_FALLBACK=off` fails closed.
    Receipts carry `title`, `site`, `word_count`, `extractor` and `parse_ms`.
  - SSRF guard: before any fetch, local or remote, the host is resolved and the URL is refused when ANY address is not
    global (loopback, RFC 1918, Tailscale's 100.64/10, link-local, 0.0.0.0, IPv4-mapped v6, unique-local, multicast,
    reserved): `private_host: …`. Redirects are followed by hand, at most 5 hops, each hop re-checked
    (`redirect_private: …`, `too_many_redirects: …`). A URL with a user name or password is `credentials_in_url: …`.
    `VULPINE_FETCH_PRIVATE_ALLOW` (comma-separated `host` or `host:port`, default the QA suite's loopback slow page
    `127.0.0.1:8797`) names the private targets the operator allows, for the requested URL only.
  - Pinned dial: the local GET connects only to the addresses the guard checked, so a rebinding name cannot pass the
    check and then reach the LAN. Host header and TLS SNI stay the URL's name; every redirect hop re-pins.
    `VULPINE_FETCH_PIN=off` switches to the plain `fetch()`.
  - Nonce fence: `fetch_url`'s `content` and every non-empty `search_web` snippet reach the brain as
    `<<PAGE id=<nonce> origin=<host>>> … <<END id=<nonce>>>`, with a fresh 64-bit CSPRNG id per call. Markers inside
    the page become `[marker stripped]`, and a notice says the block is page data, not instructions.
    `VULPINE_FETCH_FENCE=off` turns it off. The typed door (`VULPINE_TOOL_ORIGIN=glyphctl`) always gets the bare text.
  - Linked documents and YouTube: with `VULPINE_FETCH_DOCUMENTS=on` (default off), a PDF, DOCX, PPTX, XLSX or EPUB
    link is converted to markdown here (no OCR) and fenced like a page. `extractor` is `document_<format>`, a scanned
    PDF is the typed `needs_ocr` refusal, and no document refusal falls back to the remote reader. A page on
    youtube.com, www./m.youtube.com or youtu.be yields its transcript and description, asked of YouTube's own origin
    only. `VULPINE_FETCH_YOUTUBE_ASYNC=off` turns that off.

`defuddle` and `linkedom` are npm dependencies of this directory (`node_modules` is ignored). On each brain host, in
the checkout:

    cd catalog/pi/extensions/vulpine-tools && npm ci

Without them the local path reports itself unavailable, and `fetch_url` uses the remote fallback and says so.


## Connect OBS (pi_obs)

`pi_obs` is in the laptop loadout and is bound once its connection file is there. The desktop app's
welcome window and the Admin's Setup section show these steps from here:

1. In OBS, open Tools, WebSocket Server Settings: turn on Enable WebSocket server and keep Enable Authentication on.
   Show Connect Info gives the port (4455 by default) and the server's password.
2. On the Mac OBS runs on, write `~/.config/vulpine/obs.env` with three lines, `OBS_HOST=127.0.0.1`,
   `OBS_PORT=4455` and `OBS_PASSWORD=` followed by that password, then `chmod 600` it. `VULPINE_OBS_ENV` names
   another file.
3. Nothing else: the next session on the laptop loadout binds `pi_obs`, and the Admin's Setup row for OBS turns to
   set up. Switch it off in the Admin's Tools section; delete the file to unlink it.

## Tool-call guard

`guard.ts` registers a `tool_call` interceptor (`pi.on("tool_call", …)`) that can only refuse, never approve. It runs
before every tool the brain calls: this extension's `pi_*` tools, the `brain_*` tools from brain-tools, and pi's
built-in `bash` / `write` / `edit` when a loadout enables them. The brain has freedom by default: code refuses only
destructive calls, and everything else is an operator deny list.

- **Tier `destructive` (hard-coded, not configurable):**
  - recursive deletes of `/`, `$HOME` and its top-level dirs, system roots, `/Users` `/Volumes` `/Applications` (and a
    volume's top-level dirs), a repo root or its `.git`, the cwd or an ancestor of it, `~/.ssh`, `~/Library`, and the
    fox9 control state (`bin/`, `runtime-root/`, `guard/`, `overlay.env`, `*.toml` under the state dir);
  - disk destruction (`mkfs*`, `diskutil erase*`, `dd of=/dev/…`, redirects onto block devices, `shred`/`wipefs` on
    devices);
  - `git push --force`/`+ref`/`--delete` to `master`|`main` (or force with no branch named), `git branch -D
    master|main`, and `git reset --hard` while HEAD is `master`|`main` (read from `.git/HEAD`, no git spawned);
  - fork bombs; recursive `chmod`/`chown` on roots; a network download piped into a shell (`curl … | sh`,
    `sh -c "$(curl …)"`, `bash <(curl …)`); `launchctl bootout|unload|kill|…` / `pkill` / `killall` of fox9's own
    agents and processes;
  - writes to persistence files (`~/.ssh`, shell profiles, LaunchAgents/Daemons, cron, sudoers, PAM), and to this
    extension, the bundles, any `.vulpine/` (or `.foxline/`) dir, the brain's loadout and the guard policy itself;
  - `csrutil disable`, `spctl --master-disable`, `security add-trusted-cert`, `tccutil`;
  - a credential literal anywhere in a call's text (`credential_literal`): `sk-` keys, GitHub `gh?_` / `github_pat_`
    tokens, Google `AIza` keys, PEM private keys, Slack `xox?-` tokens and AWS `AKIA`/`ASIA` ids. It checks bash
    commands (quoted data too), write content, edit new text (not old text, so removing a key works), herdr prompts
    and `brain_*` missions. The read-only `read`/`grep`/`find`/`ls` are exempt. The refusal names the pattern family
    ("the call carries a GitHub token in plain text"), never the matched text. Near misses that pass: a 19-character
    `sk-`, `sk-` in prose, `ghp_` in a URL fragment, a PUBLIC KEY block.
- **Tier `policy` (operator deny list, add-only):** `$VULPINE_STATE_DIR/guard/policy.toml` (default
  `~/.local/state/vulpine/guard/policy.toml`; override `VULPINE_GUARD_POLICY`), plus `VULPINE_GUARD_DENY_TOOLS` /
  `_DENY_PATHS`. Shapes: `[tools] deny = [...]`, `[paths] deny = [globs]`, `[[commands]] id / command / args`,
  `[[text]] id / tools / pattern` (for `brain_*` prose fields, which the destructive tier never shell-classifies). The
  shipped default `guard-policy.default.toml` is comments only. Keys named allow/exempt/disable/enabled/mode are
  ignored and counted. A parse error rejects the file, logs `policy_load_error`, and changes nothing else.
- **Tier `provenance`:** `pi_*` rules apply only when the call conforms to the schema this extension registered. An
  unregistered `pi_*` name, a malformed tool name, a contract violation on `pi_utility` / `pi_herdr_remote` /
  `pi_mac_control`, or an internal guard failure is refused.
- **Tiers `flow` and `breaker` (stateful, armed by default):**
  - After a turn reads private text (`pi_mail`, `pi_messages`, `pi_recall_window`, `pi_meeting_minutes`,
    `pi_calendar_today`, `pi_file_searcher`, or a prompt carrying the screen/selection block), the outbound tools
    (herdr prompt/answer/dispatch, room posts and speech, `pi_home_act`, agent missions) are refused in that turn
    (`flow_private_then_outbound`). The operator's next request opens a new turn.
  - The breaker sorts refused shell/file calls into five intent classes. The third attempt at one class in a brain
    session is refused whatever its spelling and opens the class for 10 minutes (`intent_breaker_open_<class>`).
  - Both extend in the policy TOML (`[flow]`, `[breaker]`) and switch off there with `armed = false`. Their denial
    rows are written with tier `policy`.
- Shell handling matches executed spans only: command words (after peeling `sudo`/`env`/`nohup`/`xargs`/…, `\rm`,
  `/bin/rm`), `-c`/`-e` inline code, `$(…)`/backticks, heredocs and here-strings fed to a shell, `eval`, text piped
  into a shell, `ssh host …` tails. Quoted data, commit messages, `grep` patterns and heredocs fed to `cat` are not
  commands. Paths match on the typed path AND the symlink-resolved path.
- Denial log: append-only JSONL at `$VULPINE_STATE_DIR/guard/denials.jsonl`, records `{ts, tool, tier, rule,
  redacted_args_hash}`, never argument text. Allows are not logged. Optional `detail` (the credential family, or
  `fix: <the agent rule's fix line>`) and `pane` (a `w<ws>:p<id>` `HERDR_PANE_ID`) reach the `guard_denied` trace row
  and the Admin guard row ("Brain guard blocked write: credential_literal: a GitHub credential (destructive tier)").
- Transform: a `bash` call may be REWRITTEN before it is judged. The rewrite is what the rules judge and, when
  allowed, what pi runs. One rewrite exists: a recursive `rm` whose argument starts with a bare `$VAR`/`${VAR}` gets
  `${VAR:?}`, so an unset variable aborts the shell instead of reaching `/` (`rm -rf $TMPDIR/build` →
  `rm -rf ${TMPDIR:?}/build`, allowed). Only top-level `rm` segments are touched; heredoc lines, `$( … )`, `bash -c`
  and groups are judged as written. Applied rewrites go to `$VULPINE_STATE_DIR/guard/transforms.jsonl` as `{ts, tool,
  rule, original_hash, rewritten_hash}`, both forms by hash only.
- No LLM classifier, no ask/approve path: a refused call returns a short speakable reason (tier word + rule text, no
  hashes) and stops there.

The same guard is installed by `crates/voice_gateway/extensions/brain-tools`, so every persona's brain has it. Pi
returns at the first blocking handler, so a denial is logged once.


### Agent rule packs

An agent the gateway dispatches into a herdr pane (`HERDR_ENV=1` with a `HERDR_PANE_ID`, or
`VULPINE_TRIPWIRE_REQUIRED=1`, which the gateway sets on every agent pane) meets the JSON packs in `agent-packs/` on
each `bash` call. The voice brain never meets them. A rule is data (id, a command shape, reason, fix, source); two
shapes need code and name a `matcher`. The packs judge the command as typed, before the rm rewrite. A hit refuses with
`[foxline-guard] refused (agent rule <id>) — <reason>. Fix: <fix>.` (tier `policy`, rule = the id, one denial-log
row; never an approval request). A pack that fails to load refuses every `bash` call.

| Pack | Rule | Refuses |
|---|---|---|
| delete | `agent_rm_unset_var` | recursive `rm` whose target starts with a variable neither assigned non-empty in the same command nor set in the agent's environment (`${S:?}` passes) |
| delete | `agent_rm_root` | `/`, `~`, `$HOME`, a system or volume root, a folder holding home |
| delete | `agent_rm_checkout_root` | a checkout root, its `.git`, a folder holding the checkout |
| delete | `agent_rm_outside_scope` | anything outside the cwd's checkout and the scratch root (the judged env's TMPDIR, else the system temp folder) |
| git | `agent_git_stash` | `git stash` in any form but `list` / `show` (the stash stack is shared by every worktree) |
| git | `agent_git_reset_hard` | `git reset --hard` |
| git | `agent_git_push_force` | `push --force*`, `-f`, `+ref`, `--mirror` |
| git | `agent_no_verify`, `agent_no_verify_commit_n` | `--no-verify`, `-c core.hooksPath=`, `commit -n` |
| git | `agent_git_discard`, `agent_git_clean` | `checkout -- <path>` / `restore .` / `clean -f` outside a linked worktree |
| git | `agent_git_add_all` | `git add -A` / `.` |
| git | `agent_vulpine_policy_commit` | `add`/`stage`/`commit`/`checkout`/`restore`/`mv`/`update-index` naming `.vulpine/policy.toml` or its folder |
| host | `agent_chmod_checkout` | `chmod`/`chown -R` at, below or above the checkout; any mode change on its root or a parent |
| host | `agent_gcloud_config_set` | `gcloud config set/unset`, `config configurations activate` |
| host | `agent_launchctl_mutation` | launchctl bootstrap/bootout/kickstart/load/… |
| host | `agent_rg_replace` | `rg -r` / `--replace` |
| herdr | `agent_herdr_start_agent` | `herdr agent start`, `workspace create`, `pane split` |
| herdr | `agent_herdr_drive_pane` | `herdr agent prompt`, `pane send-keys`/`send-text`, `pane close`, `workspace close` (reads stay allowed) |


A Pi in a pane loads only the global extensions, never vulpine-tools, so the packs reach a pane through
`catalog/pi/extensions/fox9-agent-guard`. It is gated like fox9-report (`HERDR_ENV=1` and a `HERDR_PANE_ID`) and
installs this guard with an empty registry, no operator policy file and no stateful tiers.

- Every pane tool call is mapped first. `bash`, `write`, `edit` and pi's `read`/`grep`/`find`/`ls` go as they are. An
  editor extension's tool (`apply_patch`, `apply_edits`, `replace`, `insert`, …) becomes one `write` per file it
  names, and one that names none is refused (`edit_path_unjudged`). Any other tool is judged as a write of each
  path-shaped key it carries.
- A pane bash call with no timeout gets half of `VULPINE_PIPELINE_STALL_MINUTES` (900 s at the default 30). Every tool
  result has its credential literals redacted.
- A path-less write/edit fails closed (`edit_path_unjudged`, `script_edit_unjudged` for pi-utils' `{code, paths}`).
  `git -c alias.*` and GIT_CONFIG_* aliases are expanded once and re-judged; a chain or a `git config alias.*` write
  refuses `agent_git_alias_unverified` in a pane. The harnesses' own config refuses `harness_config_write`, and a pane
  agent's credential reads refuse `agent_credential_read`.
- Dispatch and prompt prose with C1, bidi, zero-width or U+2028/2029 characters is refused (`AGENT_TEXT_UNSAFE_RE`).
  The gateway refuses the same set on the dispatch card.

It ships as ONE bundled file (`bun run build:agent-guard`, about 430 KB) through `just herdr::deploy-agent-guard
host=<alias> --dry-run|--install`, installed as `~/.pi/agent/extensions/fox9-agent-guard.js`. Its refusals land in
the same denial log, so the Admin guard row shows them (rule prefix `agent_`). After a change to guard.ts or a pack,
re-run the deploy: the bundle on a host does not follow the checkout.


## Bash policy

Use the Pi CLI to block bash for a run, with `--exclude-tools bash`:

- `pi --no-extensions -e ./catalog/pi/extensions/vulpine-tools/index.ts --exclude-tools bash`

## Exa MCP

The default Exa MCP URL is `https://mcp.exa.ai/mcp`; `EXA_MCP_URL` overrides it. Latency tuning:

- `VULPINE_EXA_TIMEOUT_MS` (default: `900`)
- `VULPINE_DDG_TIMEOUT_MS` (default: `3000`)
- `VULPINE_JINA_TIMEOUT_MS` (default: `6000`)
- `VULPINE_FETCH_MAX_CHARS` (default: `20000`)
- `VULPINE_FETCH_EXTRACTOR` (default: `defuddle`; `jina` = remote reader)
- `VULPINE_FETCH_REMOTE_FALLBACK` (default: `jina`; `off` = fail closed)
- `VULPINE_FETCH_PAGE_TIMEOUT_MS` (default: `8000`)
- `VULPINE_FETCH_MAX_HTML_CHARS` (default: `5000000`)

## Layout

A new tool goes into its domain's `register<Domain>Tools(cx)` function, beside the domain's code. `cx.registerTool`
records the tool for the guard and wraps it in a receipt.


Each catalog row carries `provenance` (core, first_party_plugin or user_extension) and its `source`, `capabilities`
from a closed set (agents, files, house, memory, messaging, network, screen, write), `approval` (free,
confirm_before_write or always_ask), search `tags` and `schema_tokens`. A user extension declares its capabilities.
One that declares none is refused when the catalog is built, and it starts at confirm_before_write (always_ask when it
writes or sends) until it is trusted.

A new tool must also be registered in five more places (the receipt fields, the loadouts, the gateway's allow-list
test, the catalog and reference, the deploy): the table is in
[the brain-tools README](/docs/the-brain/brain-tools#adding-a-tool-the-six-places-it-must-be-registered).

## Deployment model

This directory is symlinked into each agent extension directory with relative symlinks. Use
`scripts/sync-pi-extensions.sh` from the repo root.
