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

Tool policy and search

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.

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.
  • 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) 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) 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.

Deployment model

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

Was this page helpful?