Agents and LLMsHarness and toolingreference
Guard extensions that enforce prose and process rules in a coding agent
A system-prompt rule is read once, at session start, by the same model that will later ignore it under pressure. Every process rule that matters on this fleet eventually gets a second existence as code: a harness extension that hooks the tool call and blocks, prompts or annotates when the rule is about to be broken. This page covers nine of those guards (what each catches, how it decides, its kill switch and the failure that made it exist) and the stow-link incident that turned “it will load after a restart” into a banned claim. It is the sibling of Keeping credentials out of coding-agent transcripts, which covers the secret layer and whose registry design and numbers are not repeated here.
Everything below was read from the extension sources and their headers in
the dotfiles repo (.pi/agent/extensions/ and .pi/agent/extensions/lib/),
the repo’s AGENTS.md, and the epistemics skill: 2026-10-04 for the
original six guards, 2026-10-20 for the rm audit, tool-guard, taint-filter,
epistemic and untrusted-content work. The dotfiles repo is private, so file
names, commit subjects and test-file names are cited as text rather than
links.
- Each guard is a TypeScript extension: a harness-agnostic core in
lib/*-core.tsplus a thin adapter per harness. - pi’s
tool_callhook can block a call or rewrite its input in place. The first block short-circuits the other handlers, so block reasons say how to resubmit. epistemic-guardblocks a write carrying a version, flag, path, URL, CVE or number that appears in no tool result this session.ai-tell-guardblocks the sentence shapes that make persisted prose read as generated.ascii-punctuation-guardfolds smart punctuation to ASCII in written files and blocks it in commits and heredocs, where it mis-decodes on paste.confidential-write-guardrecords the user’s block and allow decisions, then enforces blocked terms deterministically.git-gh-gateruns routine git with an audit log, prompts for rewrites and remote changes, and always refuses mutations in a background job.dangerous-cmd-guardsplits destructive shell commands into an always-blockcriticaltier and a promptconfirmtier.tool-guardredirects sleep-polling loops, hand-written lockfiles and generated-file edits.cd-agents-reloadshows a child repo’s AGENTS.md the first time the agentcds into it.untrusted-contentwraps and scans third-party web results for prompt injection and never blocks.- On 2026-08-27 a guard was written, tested and committed but never stow-linked, so it could not load.
The shared shape
Section titled “The shared shape”- The eight
tool_callgates run on a tool call before it executes. The first block wins and the agent resubmits with the fix. - If nothing blocks, the tool runs.
- A web or fetch result goes through
untrusted-contentontool_resultbefore the model reads it. epistemic-guardalso annotates the final chat answer onmessage_end.
Every guard lives in the harness’s extension directory, stow-linked into the
live config, as a default-exported function that receives the extension API.
Most register on tool_call and return { block: true, reason } to stop the
call, or nothing to let it through.
Shared cores
Section titled “Shared cores”The detection logic is pure and imports nothing from either harness. The pi adapter and the Claude Code PreToolUse hook run the same core, so a rule cannot exist in one harness and not the other.
| Guard | Core module | Hook (pi) |
|---|---|---|
epistemic-guard | lib/epistemic-guard-core.ts | tool_call, message_end |
ai-tell-guard | lib/ai-tell-core.ts | tool_call |
ascii-punctuation-guard | lib/ascii-core.ts | tool_call, tool_result |
confidential-write-guard | lib/confidential-write-guard-core.ts | input, tool_call, tool_result |
git-gh-gate | lib/git-gh-gate-core.ts | tool_call |
dangerous-cmd-guard | lib/dangerous-cmd-guard-core.ts | tool_call |
tool-guard | lib/tool-guard-core.ts | tool_call, tool_result, input, session events |
cd-agents-reload | lib/cd-agents-reload-core.ts | tool_call, tool_result |
untrusted-content | lib/untrusted-content-core.ts | tool_result |
Only the hook mechanics differ between harnesses:
- pi’s
tool_callhook can block or mutateevent.input. The ASCII guard rewrites write payloads in place; the other guards block, and the agent resubmits with the offending text fixed. - The Claude Code port of the ASCII guard rewrites the input the same way, via
updatedInput. - The Claude Code port of
untrusted-contentis a PostToolUse hook that returnsupdatedToolOutput. Built-in tools keep their output schema or Claude Code drops the rewrite, so the port rewrites the string fields in place (WebFetch’s result, WebSearch’s strings, MCP text blocks). Its delimiter id hashes the session id because every hook call is a new process.
The reason string is the remediation. A block that does not say what matched and what to do instead produces a retry loop, and several of the fixes below are reason-string fixes.
Catalogue
Section titled “Catalogue”| Guard | Catches | Kill switch |
|---|---|---|
epistemic-guard | specifics with no provenance in the session: versions, flags, paths, URLs, CVEs, dates, prices, performance numbers, entity attributions | PI_EPISTEMIC_GUARD_OFF=1; PI_EPISTEMIC_FOOTER_OFF=1 (chat annotation only); PI_EPISTEMIC_MAX_BLOCKS=0 (observe-only unattended) |
ai-tell-guard | the high-precision AI prose tells, in prose files and commit messages | PI_AI_TELL_GUARD_OFF=1 |
ascii-punctuation-guard | em/en dashes, smart quotes, ellipsis characters in any written payload | PI_ASCII_GUARD_OFF=1; PI_ASCII_GUARD_SCOPE=prose (prose files only) |
confidential-write-guard | user-blocked identifiers in writes, commit messages and staged diffs; nudges the ask-loop on first prose write and first commit per repo; in public-mirrored repos also blocks tainted (internal-sourced) tokens the repo does not already publish | PI_CONFIDENTIAL_GUARD_OFF=1 |
git-gh-gate | history rewrites, force or delete pushes, destructive working-tree commands, remote and config edits, gh writes and hook or identity bypasses without a human yes; writes to .git internals; any mutation in a background job | none by design |
cd-agents-reload | a cd into a repo whose AGENTS.md was never loaded | PI_NO_CD_AGENTS_RELOAD=1 |
dangerous-cmd-guard | recursive deletes, block-device writes and other state-destroying shell commands: critical (always block) vs confirm (prompt), with a narrow build-and-scratch allowlist | DANGEROUS_CMD_GUARD_OFF=1 |
tool-guard | anti-pattern tool use before it fires: sleep-polling off the bash timeout, hand-written lockfiles, generated-file edits, reformulation loops, docs-first and research-routing nudges | none documented |
untrusted-content | prompt injection in third-party web and fetch results; rewrites the result (wrap + scan), never blocks | PI_UNTRUSTED_GUARD_OFF=1 |
epistemic-guard: specifics need provenance
Section titled “epistemic-guard: specifics need provenance”The guard catches a specific literal in the agent’s own output that appears
in nothing the agent saw this session: a version (Caddy 2.8.4), a flag
(--dns-01), a system path, a deep URL, a CVE id, a date, a price, a
performance number or an entity attribution. The claim classes are version,
url, cve, perf, flag, syspath, date, price and entity. A literal with no
provenance is recalled from training by construction, which is the failure
the system prompt’s “do not be confidently wrong” rule names, stated in a
form the harness can check.
The session is the corpus. Every tool result, bash output, user message and the system prompt is absorbed into a set of seen literals. The set is re-derived from the session manager rather than accumulated in-process, so a resumed or forked session inherits its provenance. A write, edit, patch or commit message is scanned for claims, and each claim is looked up in the corpus. When the agent verifies a claim with any tool, the literal enters the corpus and does not flag again. Three surfaces carry the result:
- A
tool_callgate on write/edit/write_stream/apply_patch and on the message half of agit commit/gh prbash command. It blocks and lists the unprovenanced specifics. - A
message_endhook that appends a one-line “recalled, not verified” footer to a final chat answer. It never blocks, and it is off when there is no UI, where the assistant text is the stdout. - A
/epistemicscommand reporting corpus size and what has been flagged this session.
The companion epistemics skill documents the three exits when the guard fires, in preference order: verify (one tool call, the intended path), label the claim next to the claim, or drop the specific.
Noise control
Section titled “Noise control”- Prose files get every claim class. Code files get only dependency pins and CVEs. Scratch paths (
/tmp, lockfiles, vendored and build directories) are skipped. - A fenced code block inside a markdown doc counts as code: a
--helpflag in a usage example is an instruction to the shell, not a claim about the world. - A claim labelled
unverifiedorfrom memorywithin 160 characters of itself counts as labelled. The window is small on purpose, so that the exemption costs about as much as verifying andunverifieddoes not become a word sprinkled once per document. - A performance number inside a because-clause (
shares one link, so it caps at ...) is flagged as derived rather than recalled. A number reasoned to is a recalled rule applied without checking its preconditions, and it needs a different correction. - Unattended runs get a block budget (
PI_EPISTEMIC_MAX_BLOCKS, default 3), becausepi -prestarts with an empty corpus each pass and would otherwise re-block the same specifics forever. 0 makes the gate observe-only.
Motivating failure
Section titled “Motivating failure”There is no single incident; the failure shape is named in the extension header. The system prompt carries an epistemic-calibration section and two skills cover adjacent ground (one for claims about your own work, one for external runtime behaviour). All three are read-time guidance and none fires at claim time: the model states a version, a flag or a path, and nothing in the harness knows whether it read that or remembered it.
False positives from agent-written content
Section titled “False positives from agent-written content”What the guard scans is mostly what the agent itself writes, and two false-positive classes came out of that:
- The commit-message extractor took heredoc bodies only when the heredoc opener was the commit or PR command. A
cat > file <<EOFin the same command is file content, and it was being scanned as message prose. - The worded-version pattern spanned a line break, so a heading word followed by a numbered list item was read as a product version. It no longer spans one.
The change being committed (the diff against HEAD plus untracked files in the repos the command touches) is provenance for its own message, so a commit message may name the flags and paths that commit introduces.
Released versions are provenance
Section titled “Released versions are provenance”A version the agent writes is not recalled when it is already defined: the
tag argument of a git tag or gh release create in the same command, a
changelog-style heading at any depth, a [x.y.z]: link reference, or the
repo’s own version (from package.json / Cargo.toml / pyproject.toml,
existing git tags, cached per repo). Prose versions still flag: saying the
fleet runs one Postgres version is a claim, not a definition.
ai-tell-guard: sentence shapes that read as generated
Section titled “ai-tell-guard: sentence shapes that read as generated”The guard catches the highest-precision subset of the AI prose tells. There are seven rules, each a regex with a reason string that states the fix, and negative parallelism accounts for three of them.
| Tell | Matches |
|---|---|
| Negative parallelism | not just X, but Y; isn't about X, it's about Y; the cross-sentence form |
| Compressed aphorism | No X, no Y. Just Z. |
| Mystery-tease framing | hides a classic ... |
| Importance-announcing | worth noting, important to note |
| Slop watchlist | delve, tapestry, game-changer, stands as a testament, nestled, undergird |
It is a tool_call gate over write/edit/write_stream/apply_patch payloads on
prose paths only (.md, .mdx, .txt, .rst, .adoc, .org,
.markdown, anything under a docs/ directory) plus bash commands that
write or commit, so a commit message carrying a tell is blocked. Precision is
the design constraint, and the core header says why: a guard that
false-positives gets disabled, so only shapes unambiguous enough to gate are
rules. Code spans and double-quoted spans in a file are masked before
matching, so a doc that quotes a tell as an example passes. The fuzzy tells
(decorative bold, participle tails, triplets, metaphor coherence) are too
ambiguous to gate; an advisory reviewer covers them (next section). The
adapter caps blocks at two per rule per session, so a weaker model that
cannot rephrase does not loop forever.
The rule set comes from a 2026-08-27 Reddit thread roasting an AI-written
post, which itemised the tells readers flag on sight. The second failure was
in the guard itself. The bash surface initially reused the file surface’s
masking, and a commit message lives inside the quotes, so masking quoted
spans blanked the payload. Measured: git commit -m "not just X, but Y"
scanned clean while the single-quoted form was caught, which left the guard
half dead without any signal. The bash surface now masks code spans only. A
third fix narrowed the bash trigger to write-ish commands after read-only
search commands were blocked for carrying a tell as a search pattern.
erfi-review: the fuzzy tells, flagged by a local model
Section titled “erfi-review: the fuzzy tells, flagged by a local model”erfi-review is a CLI that flags the tells a regex cannot see and never
rewrites. It runs one regex for trailing judgement clauses (, making ...,
, ensuring ...; a clause that carries a number states a fact and is
skipped) and a Gemma 4 12B model with a review prompt, on the author’s own
hardware: the NAS GPU first, the dev box second. Output is one
file:line: kind: "quote" line per flag, and a quote the model returns
that is not in the text is dropped. erfi-review --changed reviews only
the prose paragraphs touched since HEAD, which is the pass this site
runs before a prose commit (How this site is written
places it among the site’s other checks). It exits 0 with flags, so it advises and never
gates CI (the runner has no model). Claude Code reaches it through the
review_tells tool of the shared toolkit MCP server.
The probe behind it (2026-11-17) took 12 paragraphs from this site and a copy of each with four injected tells: a participle tail, a mystery tease, a rhythm triplet and a mixed metaphor. Measured:
| Check | Injected tells found | Clean copies |
|---|---|---|
ai-tell-guard regex | 0 of 4 kinds | - |
| A voice-rewriting model run over the text | 0 of 48 removed | about 4% of words changed |
| Gemma 4 12B with the review prompt | 36 of 48 | 5 flags over 12 paragraphs |
The rewriter was trained to keep every fact of its input in order, so a slop sentence is content it keeps. The reviewer missed 11 of 12 participle tails, which is why the regex runs beside it. The 5 flags on clean copies looked like real tells in agent-edited text. The injected sentences were off-topic and identical across items, so 75% is an upper bound until a hand-labelled set of real paragraphs is scored. A first run scored 48 of 48 because the prompt’s metaphor example was the injected sentence; the table is the rerun with neutral examples.
ascii-punctuation-guard: mojibake-prone punctuation
Section titled “ascii-punctuation-guard: mojibake-prone punctuation”The guard catches smart punctuation in any payload the agent writes: em/en dashes, curly quotes and the ellipsis character. These mis-decode as garbage when pasted into a non-UTF-8 web composer, so the rule is ASCII equivalents in anything that gets committed or copy-pasted.
The check is deterministic: a code point either is mojibake-prone or it is
not, so there is no precision trade-off and no per-rule cap. Since 2026-10-23
(dotfiles#196) a write/edit/write_stream/apply_patch payload containing one
of the characters is rewritten in place to ASCII and runs, with a one-line
note on the tool result naming what changed; edit oldText and patch context
lines are never rewritten. A write-ish bash command (a commit, a heredoc, a
tee, an append) is still blocked, because folding a shell string can change
what it does, and the reason names which characters to swap. Bash that only prints unicode, such as echoing
search results, is ignored because the trigger matches only commands that
write or commit. Chat text is out of scope: the harness has no
assistant-output hook the guard can use, so prompt rules cover the prose
register there.
It exists because of 2026-06-30, when the agent emitted em dashes into a GitHub issue draft. Pasted into a web composer they rendered as garbage (UTF-8 em-dash bytes mis-decoded as CP437/Latin-1), and the user could not cleanly copy-paste their own draft.
confidential-write-guard: novel identifiers out of tracked files
Section titled “confidential-write-guard: novel identifiers out of tracked files”The guard catches third-party identifiers that must not reach a tracked file in a repo with a remote: names of outside organisations and people, private project codenames, and plans that are not public. The dangerous case is a novel name appearing for the first time, which no denylist can know about, so the work is split three ways: the agent is the classifier, the user is the source of truth, and the guard is the memory.
- A system-prompt rule tells the agent to vet its own draft before persisting prose to a repo with a remote, and to ask the user about any term it is not certain is safe, using a placeholder until they answer.
- The
confidential_termstool records the answer as ablockorallowin a local, never-committed store: per-repo under.git/info/, global under the agent directory. - The guard blocks any write, patch or commit whose payload contains a blocked term. The commit payload is the message text, any
-F/--body-filecontents and the staged diff, so an identifier in staged content is caught.
The block reason masks the term as [REDACTED] in a short context snippet.
Echoing the term into the block reason would re-propagate it into the
session log, which is the mistake the guard exists to prevent. Enforcement
never scans arbitrary bash: a read or search command that carries the term
as a pattern, including the git filter-repo run that removes it, must not
be blocked.
Two moments get a once-per-repo nudge to run the ask-loop, each tracked independently: the first prose-file write into a repo, and the first commit/PR/issue persist. A commit message plus staged diff is the highest-risk persist-to-remote moment for a novel identifier.
Two hooks close the cross-session gap, where a commit was authored before a term was blocked:
- A git pre-push hook installed via
core.hooksPathscans every commit being pushed: blocked terms, sensitive file names and gitleaks on every repo. For a repo whose content becomes public (directly or through a server-side push mirror) it also checks identifier shapes, wording that says where content came from, and runs a review by a local model. - A pre-receive hook on the self-hosted Forgejo repeats the secret and blocked-term scan for the public-mirrored repos, where a client-side
--no-verifycannot reach.
It exists because of 2026-06-26, when the agent summarised a pasted internal message into a plan doc, committed it and pushed to a public repo. A regex or denylist could not have helped, since it only knows terms already flagged.
Taint, for repos that mirror to a public forge
Section titled “Taint, for repos that mirror to a public forge”The confirmed-term list only stops a name somebody already flagged. Since 2026-10-05 the guard also records identifier-shaped tokens (proper names, ids, refs, emails, handles, URL hosts) from what enters the session as internal:
- prompts the user types or pastes;
- results of internal-source tools (chat, CRM, ticketing, notes, meeting and analytics connectors, session history);
- reads of files in a sops-encrypted path.
They go into a local rolling store (~/.cache/confidential-taint.json, 30-day
TTL). A write or commit into a repo whose content reaches a public forge (per
the visibility cache; an unknown GitHub, GitLab or Codeberg remote, or one
with no fresh cache, counts as public) is blocked when it carries a tainted token that the repo’s tracked files do
not already contain. Paths the repo’s .sops.yaml encrypts are exempt.
Nothing is hardcoded: the session’s own inputs define what counts as
internal.
The agent tainted its own words
Section titled “The agent tainted its own words”Every background worker, subagent, loop agent and LLM judge is a separate
pi -p process that loads the same guard, and the prompt the parent agent
writes for it arrived at the guard as typed input. Each delegation marked the
proper nouns in the agent’s own prose (Windows, You, a band name from a
research task) as confidential for 30 days, and later edits that used them
were blocked. One session worked around it with 79 manually allowed terms.
The first diagnosis blamed the completion notices a finished worker sends
back, but the harness delivers those as custom messages, which never reach
the input hook. The taint timestamps matched worker start times instead.
Since 2026-10-14 only a human-facing session (an interactive terminal or an
RPC client) taints its prompts, and worker processes are also excluded by
their environment markers. A reproduction, one pi -p run with a made-up
name in the prompt followed by a lookup in the store, showed the old guard
recording the name and the fixed one not.
The filter, tightened
Section titled “The filter, tightened”The sweep still over-recorded: it stored every capitalised word from
internal content, so common single words and all-common phrases kept blocking
writes. Since 2026-10-20 a worthiness filter runs on entry and exit. It keeps
emails, ids and refs, distinctive single tokens, and phrases with at least
one uncommon word, judged against a common-word list (the top-5,000 English
words plus programming and product names). On the live store it dropped 1,831
of 4,941 entries (37%), kept every id, email and ref, and every user-blocked
term still counts as taint-worthy. The confidential_terms tool’s own
arguments are never scanned, since they record the decision that unblocks a
term. A proposed secret-guard exemption was dropped in review because it
would have let a registered secret into the terms file unmasked.
git-gh-gate: tiers instead of a prompt per command
Section titled “git-gh-gate: tiers instead of a prompt per command”Mutating git and gh commands fall into two tiers since 2026-10-20. Routine, recoverable commands run without a prompt, and each is appended to an audit log with the session that ran it. Everything else waits for a yes.
| Tier | Commands |
|---|---|
| Routine: run, audit-logged | commit (including --amend), push without force, delete or mirror flags, tag creation, worktree add and remove, merge, switch or checkout of a branch, cherry-pick, revert, stash push/pop/apply, non-forced mv/rm and branch -d, apply |
| Gated: wait for a yes | reset, rebase, clean, checkout -- <path> and restore, force, delete and mirror pushes, push options, forced branch deletion (-D, --force), tag deletion, filter-branch/filter-repo, update-ref, config, remote and submodule changes, every mutating gh command |
| Always gated | --no-verify, -c core.hooksPath=, -c user.name=, --author, GIT_AUTHOR_* and GIT_DIR assignments, the guards’ own kill switches; writes to .git internals (COMMIT_EDITMSG, hooks, refs, config) through the write/edit tools |
| Always blocked | any mutating git/gh command inside bg_bash, or in a session with no UI (pi -p subagents, bg workers, loop agents; dotfiles#140, 2026-10-20) |
- A command inside
bg_bash, or in a worker session with no UI, is blocked. - A command that skips hooks or changes attribution waits for a yes.
- Routine git in a repo on the global hooks path runs and is logged.
- Everything else, including every gh write, waits for a yes.
The command is parsed into segments, so cd /repo && git commit -m ... is
judged on its git segment, and short flags are read even when clustered
(-qam). Routine commands are allowed only in a repo whose effective
core.hooksPath is the global hooks directory, because the pre-push leak
gate has to be in the path. A repo that installs its own hooks keeps
prompting. With a UI, gated commands show the command, truncated to one
logical line plus a hidden-lines hint (a 20-line heredoc in the dialog used
to balloon the modal), and wait for a yes. The ban on Co-Authored-By
trailers and AI-attribution footers stays a prompt-level content rule.
The original gate prompted for every mutating command: over 30 days it raised 3,833 prompts across 205 sessions and the user denied 4, two of them misclicks. A prompt answered yes 99.9% of the time was not catching the leaks that had needed a history rewrite (tokens in committed files, internal context in a public repo). Protection moved to scanners that read the bytes being pushed; the prompt now covers only what a scanner cannot judge.
The older incident was a headless writer subagent, refused by the bash gate,
that committed through bg_bash, whose detached tmux session has no prompt
either. Since 2026-10-04 a mutating git/gh command inside bg_bash is always
blocked.
dangerous-cmd-guard: destructive shell commands, two tiers
Section titled “dangerous-cmd-guard: destructive shell commands, two tiers”The guard catches commands that destroy state no undo can recover: recursive
deletes, block-device writes, fork bombs, power cycles, disk partitioning,
and infrastructure mutations (nixos-rebuild switch, zpool destroy,
docker system prune).
| Tier | Behaviour | Examples |
|---|---|---|
critical | always blocks, no prompt even in a UI | recursive delete on /, $HOME or the session cwd itself; --no-preserve-root; cwd-wipe globs; dd of=/dev/...; mkfs; wipefs; fork bombs; recursive chmod/chown on / or $HOME |
confirm | prompts, or denies when headless | a recursive delete on any path outside the scratch allowlist; the same shapes nested inside an ssh host '<cmd>' payload |
The remote command string of an ssh payload is re-classified with a root view
(remote cwd and home), so ssh root@nas 'nixos-rebuild switch' no longer
passes as a harmless ssh.
Recursive deletes in build-and-scratch territory run without a prompt: /tmp,
/var/tmp, /dev/shm, /private/tmp, ~/.cache, and build-artifact
basenames (node_modules, dist, build, target). The list is narrow:
anything under $HOME that is not a known build artifact prompts.
It exists because of 2026-08, when an agent typo’d a path while editing a file, then cleaned up with a recursive delete in the same compound command as its verification steps and deleted the working trees of three real repos. Prompt rules did not stop it, and a runtime gate does.
The rm audit: 24 bypasses, closed and pinned
Section titled “The rm audit: 24 bypasses, closed and pinned”A 2026-10-20 adversarial probe of the recursive-delete classifier found 24 delete shapes that ran without a prompt. Each was closed and pinned:
- A
cdorpushdearlier in the same command changed what a relative target resolves to, and the classifier read the target against the session cwd only:cd ~ && rm -rf infrapassed from a/tmpcwd. - Nothing inside
trap '...',bash -c,eval,find -exec ... rm, or afor/if/{}body was parsed as a delete. - A delete on a command substitution vanished from the segment (
rm -rf $(git rev-parse --show-toplevel)). - Inline-script deletes (
shutil.rmtree,fs.rmSync(recursive),perl -MFile::Path) andrsync --deletewere invisible. /tmpitself,~/.cacheitself, and~/tmp,~/out,~/buildcounted as scratch.
The fixes make the classifier conservative about what one command line knows:
- Every
cd/pushdtarget joins the candidate cwds, and a relative target is scratch only when it is scratch under all of them. - A variable resolves only when it is assigned exactly once, at top level, in the same command, to a literal or to
$(mktemp ...)whose directory is below a temp root (TMPDIR,-p, the template and--tmpdirall handled). - Anything else (a variable set in an earlier tool call, a loop variable, a command substitution) is unknown, and a recursive delete on an unknown target asks.
- Nested payloads are classified, including ssh payloads whose variables are remote.
- Two filesystem escapes ask: a scratch target that is a symlink pointing out of scratch, and one that is a mount point, since a bind mount under
/tmpcan hold real data. The adapters supply the realpath and mount checks.
rm-guard-audit.test.ts pins 171 cases, each run under two session cwds (a
scratch directory and a real repo). A replay of 29,820 recorded commands
moved the prompt count from 212 to 187. The 40 newly allowed are all deletes
of mktemp directories or literals below /tmp. The 15 newly asked are
script deletes, unresolved targets and a remote rsync --delete.
tool-guard: anti-patterns redirected before they fire
Section titled “tool-guard: anti-patterns redirected before they fire”tool-guard is the broad anti-pattern gate: a tool_call hook with a
block-with-reason for patterns the model fires despite prompt rules, such as
a bash find where a built-in file tool exists, a raw fetch of a docs-server
URL instead of the docs tools, or a reformulation search loop. The rule table
lives in lib/tool-guard-core.ts and is shared one-to-one with the Claude
Code PreToolUse hook. Two rule families and a splitter rewrite landed in
2026-10.
Sleep-polling
Section titled “Sleep-polling”A bash call that sleeps past pi’s ~30-second tool timeout parks the turn. The
sleep_poll rule redirects two shapes: a loop whose sleeps can total 30
seconds or more (counted for loops by iterations times sleep; while /
until unless bounded by a timeout under 30 seconds), and a standalone
sleep of 30 seconds or more. The redirect points at the background-task
tools: bg_bash for the waiter, bg_wait or the completion nudge for the
result. Quoted arguments are ignored except bash -c / ssh payloads, so a
sleep that only exists inside file data never trips it, and short retry loops
pass. A replay of 30 days of recorded bash commands found 399 that would have
been redirected.
Lockfiles and generated files
Section titled “Lockfiles and generated files”A lockfile is regenerated by the package manager from the manifest, so
hand-writing one (sed -i, a redirect, or tee into the file) is blocked
with a pointer to the manifest and the manager command that rewrites it
reproducibly: bun install, cargo update, uv lock, go mod tidy or
nix flake update. The write-side edit_lockfile rule gained uv.lock and
flake.lock. A separate edit_pb_go rule refuses edits to generated
protocol-buffer files, and a file whose head carries a “Code generated …
DO NOT EDIT” header blocks the same way. Rules for dist/ and build/
directories were dropped in review, since real source directories use those
names.
Quote-aware command splitting
Section titled “Quote-aware command splitting”The bash segment splitter started as a regex, and it cut quotes apart. Rules
such as env-dump and secret-read test each segment ^-anchored. An rg
pattern like '^(function|...|type)', split naively, produced bare-word
segments that read as commands, so a search pattern blocked as if it were an
environment dump.
The replacement, lib/shell-text.ts splitShellSegments:
- splits only at
&&,||,;,|,&and newlines that sit outside quotes; - treats
2>&1-style redirections as redirections rather than operators; - drops heredoc bodies, keeping the opener line, which still marks a file write;
- returns command substitutions, including ones inside double quotes, as their own segments, because those run;
- keeps quoted strings whole, so an
rgpattern alternation is one argument and abash -c 'x && y'is one segment the caller descends into itself.
skill-guard adopted the same idea and tests its rules against the runnable
text only. Heredoc bodies and the quoted arguments of ordinary commands are
data, while quotes around ssh / bash -c / env / nix payloads are kept
and inspected.
cd-agents-reload: the mid-session cd context gap
Section titled “cd-agents-reload: the mid-session cd context gap”Both harnesses load AGENTS.md / CLAUDE.md from the startup directory and its
parents at session start, and neither re-loads when the agent cds into
another repo mid-session. Project instructions in the target repo (canonical
build commands, Makefile targets, repo-specific gotchas) stay invisible, and
the agent substitutes generic docker compose build / npm run build calls
for the repo’s own commands.
The guard is a tool_call gate on bash. It extracts every cd <dir> segment,
resolves it against the startup cwd, skips targets already covered by the
startup load, and once per session per target directory attaches a bounded
head of the repo’s AGENTS.md (80 lines or 4,000 characters, whichever comes
first) to the command’s result. Only a build, deploy or infrastructure-apply
command (docker compose up, make, a package manager’s build script,
nixos-rebuild, tofu apply, kubectl apply, systemctl restart and
similar) is blocked until the rules are read. Until 2026-10-20 every command
was blocked, and 751 blocks in 30 days were mostly reads and edits that the
agent then had to re-run verbatim.
Two refinements cover the blocking case:
- The block reason states that the entire command was swallowed (no segment executed, including any heredoc or
git add) and must be re-run verbatim. - When the blocked command is also a commit persist, this guard delivers the confidential-write guard’s once-per-repo nudge itself and marks it delivered. pi short-circuits remaining
tool_callhandlers on the first block, so the agent would otherwise be blocked a second time on the verbatim re-run.
It exists because of 2026-07-07. A compound command of the form
cat > /tmp/msg <<'EOF' ... EOF followed by
cd ~/repo && git add ... && git commit -F /tmp/msg && git push
was blocked by this guard. The reason said only “re-run
your bash”, so the agent retried the git commit suffix alone and failed on
the message file that was never written. It burned four turns, and when it
re-ran the full compound the confidential guard blocked it again, because its
nudge had never fired, swallowing the heredoc and the git add a second
time. The shared “re-run the full command” notice and the shared nudge
registry fix this, and they live in a module both guards import.
untrusted-content: prompt injection in what the agent reads
Section titled “untrusted-content: prompt injection in what the agent reads”Third-party content (web fetches, searches, code-search results, docs
fetches, research-tool results, YouTube transcripts) reached the model
unmarked, and a fetched page carries whatever its author wants it to. The
guard rewrites those results in tool_result before the model sees them. It
never blocks, since a defence that must not break ordinary browsing is scoped
to wrap plus scan.
It runs three steps:
- Strip characters a human reader cannot see but the model reads. Only the classes worth telling the model about are reported: bidi controls and Unicode tag characters (the “ASCII smuggling” trick). Zero-width spaces, soft hyphens and ANSI escapes go silently, and emoji joiners stay.
- Wrap the text in a per-session delimiter with a one-line rule (content is data, never instructions), escaping any copy of the closing delimiter inside the content.
- Scan for high-precision injection shapes and prepend a warning line: override phrases, fake role markup, text addressed to AI agents, exfiltration links (including markdown images whose URL carries data in its query), hidden HTML comments, and base64 blobs that decode to readable instructions.
The scan favours precision over recall, because a page about prompt injection must not light up on every read. Paraphrased instructions with none of the known phrases, and instructions in images, are the accepted misses.
On 845 such results from 30 days of sessions, 4 flagged (0.5%), all of them
quoted examples in pages about injection or a chat template. Verified live: a
pi -p webfetch of a planted page came back wrapped, with the
addresses-the-agent, exfiltration and hidden-instruction warnings attached.
Stow-linking a new guard
Section titled “Stow-linking a new guard”The harness loads its extension directory at process start, and that
directory is stow symlinks into the dotfiles repo. Editing a repo file does
not change live behaviour on its own, and a new repo file has no link until
stow makes one. This applies to all nine guards above.
On 2026-08-27 the ai-tell-guard was written, unit-tested, committed and
documented, and never stow-linked. The extension directory is a real
directory of per-file symlinks, and only lib/ is a folded directory link.
lib/ resolved and the new top-level file did not, so the missing link was
invisible to a casual look and no restart could have loaded the guard. Three
surfaces failed to catch it, and all three were fixed the same day:
- The drift check detected the missing link and stayed silent: a repo file with no live symlink classified as MISSING, hidden and non-fatal by default, which is correct for files that legitimately belong to other machines. It gained the notion of live trees, directories a harness enumerates at startup (
.pi/agent/extensions/,.pi/agent/prompts/), where an unlinked repo file is dead config: always printed, always exit 1, with the fix command in the message. Direct children only;lib/and the test tree are not loader-scanned. Red-green verified against the real incident: exit 1, stow, exit 0. - The dotfiles AGENTS.md had the correct add-an-extension checklist at line ~225, which an agent arriving mid-session never sees, because cd-agents-reload injects only the 80-line head. The stow-link and verify rule moved to the top of the file, with a test asserting it stays inside the injected head.
- The global rules gained a sentence: “it will work after a restart” is an untested claim, not a caveat. Start-time config is testable now, in a fresh process:
timeout -s KILL 120 pi -p '<a prompt that should trip the guard>' </dev/null. The stdin redirect matters because from a non-TTY tool, print mode blocks on an open stdin. An install-path change is verified at its live path, not assumed from the repo.
Measuring a guard: replay the commands
Section titled “Measuring a guard: replay the commands”A guard change is evaluated the same way every time: replay the trailing 30
days of recorded session commands against the live classifier core, before
and after the change, and compare what would have prompted or blocked. The
measurement scripts live in the dotfiles repo’s research-raw directory for
the command-git-safety work
(docs/research/raw/2026-10-20-agent-command-git-safety/scripts/). They read
the session logs locally. The gate replays ran each recorded bash command
through the live classifyBashCommand cores for git-gh-gate and
dangerous-cmd-guard; that replay harness is not committed with them.
A replay covers every command the agent ran, including the ones that should have stayed friction-free, so an over-broad rule shows up as newly prompted commands. Production observation is the complement. The git-gh-gate and cd-agents-reload counts below are observed, not replayed.
How it was checked
Section titled “How it was checked”| Claim | Figure | How it was checked |
|---|---|---|
| rm guard bypass shapes | 24 closed | adversarial probe, every shape pinned in rm-guard-audit.test.ts - measured |
| rm guard pinned cases | 171, under two cwds | rm-guard-audit.test.ts - measured |
| rm guard live replay | 29,820 commands; 212 -> 187 prompts; 40 allowed, 15 asked | 30-day session-log replay through dangerous-cmd-guard-core.ts classifyBashCommand - measured |
| sleep-poll redirects | 399 | 30-day session-log replay through tool-guard-core.ts - measured |
| untrusted-content flag rate | 4 of 845 results (0.5%) | 845 third-party results from 30 days of sessions - measured |
| taint filter dropout | 1,831 of 4,941 entries (37%) | scan of the live taint store - measured |
| git-gh-gate prompt volume | 3,833 prompts / 205 sessions / 4 denied | production observation over 30 days before the tiers - measured |
| cd-agents-reload block volume | 751 blocks / 30 days | production observation before the scope narrowing - measured |
| kill switches and the tier definitions (critical/confirm, scratch allowlist) | - | design decisions, documented in the core headers; behaviour asserted by the unit suites - design, test-corroborated |
What they do not catch
Section titled “What they do not catch”- Chat text is only annotated, never blocked: the harness exposes no hook that can mutate an assistant message before it renders, so the epistemic footer and the prompt-level rules are the ceiling there.
- A confidential term nobody has asked about yet. The nudges make the ask likely and cannot make the classifier right. The pre-push hook and the server-side pre-receive hook are the backstop, and they fire after the term is in local history but before it reaches a public remote.
- Anything in an unattended run past its block budget, and anything on a guard whose kill switch is set. A set switch means the guard needs fixing.
- The fuzzy prose tells (triplets, participle tails, decorative bold, metaphor coherence) are judgement, not a harness gate.
erfi-reviewflags some of them before a commit, and it is advisory: a flag nobody reads changes nothing, and its precision on real text is unmeasured. This site has gated them in CI since 2026-11-18, with a cloud model on the paragraphs each push touches (How this site is written). - Prompt injection in images, and paraphrased instructions with none of the known phrases.
Related docs
Section titled “Related docs”- Keeping credentials out of coding-agent transcripts: the secret layer over the same hook machinery, with a registry of secret stores, keyed digests, and the read-block / typed-value / output-mask guards.
- A cross-client memory store for coding agents: the store the transcripts sync to, and the reason anything a guard misses is durable.
- Kanban board for coding agents: the work-tracking half of the same harness setup.
- Running agent git commands without per-command approval prompts: the reasoning behind the tiered git/gh gate documented here as a mechanism, including the measured move from prompts to byte-level scanners.
- The pi harness journey: the hub that maps every extension here to its history, layout and place in the harness.
- Subagents, worktrees, and parallel agent work: workers edit files in a worktree the main session created; only the main session commits, merges and pushes.
- Context, prompt cache, and compaction in a coding-agent harness: the prompt-prepend and compaction machinery the guards operate inside.
Linked from
- A personal knowledge graph with a local LLM
- A sensor-gated coding-agent loop compared with 2026 harnesses
- A skills system for coding agents
- Context, prompt cache, and compaction in a coding-agent harness
- History of the pi coding-agent harness
- How this site is written
- Keeping credentials out of coding-agent transcripts
- Labelling AI use with the 0rwx framework
- Running agent git commands without per-command approval prompts
- Sharing guards and tools between two coding-agent harnesses
- Subagents, worktrees, and parallel agent work
- Testing the assumption a plan depends on before building it