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
bashpolicy (configure it with Pi CLI args). pi_file_searcher, with actionscapabilities,find_paths,grep_contentandlist_dir.pi_github: read-only GitHub status over the host’s authenticatedgh. The repo is always passed explicitly and must be inVULPINE_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,issuesandrelease_latest. The guard refuses any other action. - Each result has a
summarywritten to be spoken (counts, titles, relative times; no ids, shas or links) and compactrows. gh errors become a typedcodeand one sentence. pr_listandissuesspeak the repo’s true open count. A full page spends one GraphQLtotalCountcall, the result carriescounts.open,counts.shownandtruncated, and a failed count says “at least”.starsnames the operator’s newest stars and when each was starred (no links; descriptions in one nonce fence).repo_readopens 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 owncard.v1.
- Actions
pi_health: read-only Apple Health facts throughruntime/health/healthctl.py(mode=roSQLite):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, throughruntime/dot_worker/dotctl.pyand 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 countspi_dot:submitas outbound andpi_dot:resultas 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 withno_receiptafter 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 kindvisual.v1: a sandboxed Luau program whose view is aui.*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 kindfile.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_byteswith 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 onlyfound(shownwithfile_kind, orasked_userwithchoices) or a refusal (no_matchbecomesfound: not_found), never a name, folder, size or date.
- The gateway resolves the path against
pi_feature_request {ask, missing, kind, family?, beyond_held?}logs an ask Vulpine cannot do yet.kind: proactivemeans the brain found the gap itself;kind: askedmeans the operator said “log that as a feature request”.- The gateway keeps it in
feature-requests.jsonunder its state root: owner-only, at most 500 requests, deduped on the normalized ask. - The answer is
notedornoted_againwith 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::harvestturns 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: truelogs it anyway.ask_back: the ask names no capability, so the brain asks what Vulpine should do.
- The gateway keeps it in
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 throughfile.v1. Every hop passes the private-network guard, with at most 3 redirects. - The answer keeps
source_url,image_url,licenseandsource; the title and creator come back fenced. Thesayline 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_statusreports it asimage_search, fromweb-image-providers.jsonbeside the receipt spool. Receipts carryprovider,fallback_from,primary_reasonandprimary_ok_age_s.
- It searches Openverse (keyless,
- 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 asversions.pi_restart_worker {action: crashed|restart, name?}.crashedreadslaunchctl listandprint.restartacts on one allow-listed target (RESTART_TARGETSinselfcare/restart.ts) after the approval socket says yes:launchctl kickstart -kfor 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_POLICYinselfcare/logs.ts). Rotated copies older than two days are deleted; live logs over 8 MB are cut to their last megabyte.trimsays 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’scalendar change, launched withopen -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 isunverified, never “not changed”. The catalog row isapproval: confirm_before_write.
- Every call previews (
pi_tool_search {query, limit?}finds and loads a deferred tool: one set todeferredin the Admin’s tool toggles, enabled but out of the prefill. The gateway lists deferred tools in--toolsandVULPINE_DEFERRED_TOOLS, and offerspi_tool_searchonly 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.
- A deferred tool gets pi’s
pi_memory_recall {query?}andpi_memory_propose {fact, source}are the memory core tools, answered at the gateway’s mutation socket. The three operator loadouts allow both.sourceisoperator,toolorpage. Anoperatorfact 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_notifysource, 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;urgentis 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
queuedordeduped. The receipt carries the urgency and the outcome.
- The line goes on the operator’s board as the
pi_house_nowreads the house in one call: ahouse.v1document 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,staleorunknown. 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.
- 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 (
pi_herdr_dispatch policy_diff {repo}is a read-only, door-only verb (a brain call is refused): onegit diff HEAD -- .vulpine/policy.tomlin 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_todonever deletes.removearchives: the record keeps anarchived_atstamp, drops out of the default list, comes back withinclude_archivedand is restored byunarchive.clear_completedarchives too. Declaredrisk=write.pi_satellite_timerdeclaresstopinstead ofcancel(a stopped timer is re-settable, so it is a write).cancelis still accepted as an alias.pi_herdr_dispatchstaysdestructiveand gets its confirm from the approval socket (the catalog showsrequires_confirm: truewithout aconfirm_codeparameter).prepare,pipelineandremove(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,listandpreflightare not gated.- The
prepare/pipelinecard is anexecnaming the checkout. Theremovecard is adeletenaming the task, with the worktree path indetail. The gateway always asks for it: no policy file, 24-hour grant or learned trust pre-authorizes adelete. - Every gated ask names its pi
toolCallIdinagent.call_id, so the card and the “yes” stay in the session that asked.
pi_internet_search, with actions:providers_statussearch_webfetch_urlpapers: keyless OpenAlex works search (api.openalex.org) — title, year, venue, first three authors, citations;VULPINE_OPENALEX_MAILTOjoins OpenAlex’s polite pool when sethn: keyless HN Algolia story search (hn.algolia.com) — points, comments, the story link or its discussion. Both takequery,maxResultsand an optionalsinceDays.
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 nameGetSceneListreturned. The password is read at call time from~/.config/vulpine/obs.env(OBS_HOST,OBS_PORT,OBS_PASSWORD;VULPINE_OBS_ENVoverrides); missing isobs_not_configured. No stream start, no freeform request.pi_mail(bound once ready): read-only Gmail search onfrom/subject/unread/label/since, every operator word quoted. Metadata only (From, Subject, Date), no bodies. The spokensummaryis counts and times; sender names and subjects travel only underuntrusted_mail. The gmail.readonly token is read at call time from~/.config/vulpine/gmail-token.json(VULPINE_GMAIL_TOKENoverrides).tools/mail/gmail_auth.pysigns 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 itscause.pi_feeds(bound once ready): the operator’s RSS and Atom feeds over the headless storetools/feeds/feedctl.py(no feed server). Closed actionsunread {limit},read {id},mark {id}(idempotent). The spokensummaryis counts. Titles, text and links travel only underuntrusted_feedswith a data-not-instructions notice. Fetching is not a brain action:feedctl refreshruns on its own behind the page fetch’s SSRF guard.unreadputs the list on the screen as its owncard.v1(alist.v1of title, feed and age).pi_whatsapp(bound once ready): the operator’s unread WhatsApp chats overruntime/messages/wactl.py, which runs an installedwacliread-only (three allowlisted read commands; it never installs, pairs or marks read). Closed actionsunread {limit}andread {chat | ref, limit}. The spokensummaryis counts and names (contact names through the grant holder, a number masked to its last two digits). Message text travels only underuntrusted_messages, each in the nonce fence.- Search fallback chains:
- local content:
rg -> grep -> builtin - local paths:
fd -> find -> builtin - web search:
searxng -> exa_mcp -> duckduckgounderauto. The self-hosted SearXNG is asked only whenVULPINE_SEARXNG_URLnames one; a failure cools it for two minutes, whichproviders_statusshows. - page extraction: local
defuddleover alinkedomDOM, so no operator URL leaves the machines. The remotejina readerruns only withVULPINE_FETCH_EXTRACTOR=jina, or as a named fallback after a local failure (provider: "jina_reader_fallback"andfallback_reasonin the receipt).VULPINE_FETCH_REMOTE_FALLBACK=offfails closed. Receipts carrytitle,site,word_count,extractorandparse_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 iscredentials_in_url: ….VULPINE_FETCH_PRIVATE_ALLOW(comma-separatedhostorhost:port, default the QA suite’s loopback slow page127.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=offswitches to the plainfetch(). - Nonce fence:
fetch_url’scontentand every non-emptysearch_websnippet 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=offturns 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.extractorisdocument_<format>, a scanned PDF is the typedneeds_ocrrefusal, 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=offturns that off.
- local content:
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:
- 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.
- On the Mac OBS runs on, write
~/.config/vulpine/obs.envwith three lines,OBS_HOST=127.0.0.1,OBS_PORT=4455andOBS_PASSWORD=followed by that password, thenchmod 600it.VULPINE_OBS_ENVnames another file. - 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
/,$HOMEand 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,*.tomlunder the state dir); - disk destruction (
mkfs*,diskutil erase*,dd of=/dev/…, redirects onto block devices,shred/wipefson devices); git push --force/+ref/--deletetomaster|main(or force with no branch named),git branch -D master|main, andgit reset --hardwhile HEAD ismaster|main(read from.git/HEAD, no git spawned);- fork bombs; recursive
chmod/chownon roots; a network download piped into a shell (curl … | sh,sh -c "$(curl …)",bash <(curl …));launchctl bootout|unload|kill|…/pkill/killallof 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, GitHubgh?_/github_pat_tokens, GoogleAIzakeys, PEM private keys, Slackxox?-tokens and AWSAKIA/ASIAids. It checks bash commands (quoted data too), write content, edit new text (not old text, so removing a key works), herdr prompts andbrain_*missions. The read-onlyread/grep/find/lsare 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-charactersk-,sk-in prose,ghp_in a URL fragment, a PUBLIC KEY block.
- recursive deletes of
- Tier
policy(operator deny list, add-only):$VULPINE_STATE_DIR/guard/policy.toml(default~/.local/state/vulpine/guard/policy.toml; overrideVULPINE_GUARD_POLICY), plusVULPINE_GUARD_DENY_TOOLS/_DENY_PATHS. Shapes:[tools] deny = [...],[paths] deny = [globs],[[commands]] id / command / args,[[text]] id / tools / pattern(forbrain_*prose fields, which the destructive tier never shell-classifies). The shipped defaultguard-policy.default.tomlis comments only. Keys named allow/exempt/disable/enabled/mode are ignored and counted. A parse error rejects the file, logspolicy_load_error, and changes nothing else. - Tier
provenance:pi_*rules apply only when the call conforms to the schema this extension registered. An unregisteredpi_*name, a malformed tool name, a contract violation onpi_utility/pi_herdr_remote/pi_mac_control, or an internal guard failure is refused. - Tiers
flowandbreaker(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 witharmed = false. Their denial rows are written with tierpolicy.
- After a turn reads private text (
- Shell handling matches executed spans only: command words (after peeling
sudo/env/nohup/xargs/…,\rm,/bin/rm),-c/-einline code,$(…)/backticks, heredocs and here-strings fed to a shell,eval, text piped into a shell,ssh host …tails. Quoted data, commit messages,greppatterns and heredocs fed tocatare 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. Optionaldetail(the credential family, orfix: <the agent rule's fix line>) andpane(aw<ws>:p<id>HERDR_PANE_ID) reach theguard_deniedtrace row and the Admin guard row (“Brain guard blocked write: credential_literal: a GitHub credential (destructive tier)”). - Transform: a
bashcall may be REWRITTEN before it is judged. The rewrite is what the rules judge and, when allowed, what pi runs. One rewrite exists: a recursivermwhose 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-levelrmsegments are touched; heredoc lines,$( … ),bash -cand groups are judged as written. Applied rewrites go to$VULPINE_STATE_DIR/guard/transforms.jsonlas{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,editand pi’sread/grep/find/lsgo as they are. An editor extension’s tool (apply_patch,apply_edits,replace,insert, …) becomes onewriteper 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_unjudgedfor pi-utils’{code, paths}).git -c alias.*and GIT_CONFIG_* aliases are expanded once and re-judged; a chain or agit config alias.*write refusesagent_git_alias_unverifiedin a pane. The harnesses’ own config refusesharness_config_write, and a pane agent’s credential reads refuseagent_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.