Detailed worked example with concrete prompts, observable outcomes, and the limits of the example.
The session
You
Pi runs every shell command my agent executes. I want a project-local hook that runs before each one — override rm, git, and friends for this project without touching my global zshrc.
Agent
Pi has exactly that hook: shellCommandPrefix in the project's .pi/settings.json. It prepends a snippet to every command the agent runs. Pointing it at a sourced zsh file makes every function in that file shadow the command of the same name:
{
"shellPath": "/bin/zsh",
"shellCommandPrefix": "source \"$PWD/.pi/agent-shell.zsh\""
}
The whole integration is two JSON keys. Everything after this beat is plain zsh — no plugin API to learn, and the real binaries stay reachable via command rm, command git.
You
Start with rm. The agent should never permanently delete anything — move targets somewhere recoverable, and tell the agent what happened and how to undo it.
Agent
Added rm() to a new .pi/agent-shell.zsh. Targets move to a session-scoped quarantine dir, and both notices print to stderr, addressed to the model:
print -u2 -- "[rm-override session=$session_id] quarantined $moved item(s) in $quarantine instead of deleting."
print -u2 -- "[rm-override] restore with: mv \"$quarantine/<name>\" <dest>. Real deletion requires 'command rm' and explicit user approval."
Those two stderr lines are the whole design: a message to the model at the moment it acts, not a rule it read forty thousand tokens ago. If you can see the line in the transcript, the agent saw it too.
You
Same idea for git: block push --force and reset --hard, and make the failure message tell the agent what to do instead.
Agent
Done — the override inspects argv and refuses with guidance before real git ever runs. From the captured harness transcript:
▶ [session session-A] $ git push --force origin main
[git-override session=session-A] force push blocked. Ask the user to run it
themselves, or explain why history must be rewritten and wait for approval.
▶ [session session-A] $ git reset --hard HEAD~3
[git-override session=session-A] 'git reset --hard' blocked. Prefer 'git stash'
or 'git restore <path>' so work is recoverable.
Exit code 1, nothing pushed, and the agent gets a next step it can act on in the same turn. command git still bypasses it — this is guidance with teeth, not a sandbox.
You
Now a real team policy: every Linear issue the agent files gets assigned to me. Rewrite linear issue create so --assignee self is enforced no matter what flags the agent passed.
Agent
The override strips any assignee the agent chose and appends --assignee self, announcing the rewrite on stderr. Dry-run mode prints the final argv:
▶ [session session-A] $ linear issue create --title 'Fix login bug' --assignee someone-else
[linear-override session=session-A] enforcing --assignee self
[linear-override dry-run] command linear issue create --title Fix\ login\ bug --assignee self
Adapted from a working policy in a private test project. It rewrites only issue create; every other linear subcommand passes through untouched.
You
The tricky one: brief the model exactly once per conversation. The first ls should return instructions to the AI; every later ls runs normally. But Pi spawns a fresh shell per command — where does "once" live?
Agent
Not in shell variables — a fresh shell forgets everything. State has to live on disk, keyed by the conversation, or /new and /fork would inherit a stale "already briefed" flag. Installed the pi-session-id extension (pi install git:github.com/johnlindquist/pi-session-id), which exports PI_SESSION_ID into every shell Pi spawns. With that key, "once per session" is one atomic mkdir:
pi_instruction_once() {
emulate -L zsh
local command_name="$1"
local state_root="${TMPDIR:-/tmp}/pi-command-instructions"
local session_id="$(pi_session_id)"
local marker="$state_root/$session_id/$command_name"
mkdir -p "$state_root/$session_id" || return 1
if mkdir "$marker" 2>/dev/null; then
cat
return 0
fi
return 1
}
mkdir succeeds exactly once per marker path, so "first time" is race-free even with parallel Pi processes. The extension itself is ~44 lines of TypeScript syncing the session ID on session_start, human ! commands, and every model bash call — with the ID validated before it touches shell source.
You
Prove all of it without Pi in the loop. I want a harness that runs commands exactly the way Pi does, so a broken override never takes down a live session.
Agent
Wrote demo/run-demo.sh: fresh zsh per command, prefix sourced, PI_SESSION_ID set — Pi's execution model, reproduced. Ran it; the captured transcript (checked in as demo/sample-output.txt):
▶ [session session-A] $ ls demo
INSTRUCTIONS FOR THE AI:
This project overrides rm, git, linear, and ls via .pi/agent-shell.zsh.
Deletions are quarantined, force pushes are blocked, and Linear issues are
always self-assigned. Run ls again to execute the command normally.
▶ [session session-A] $ ls demo
run-demo.sh
sample-output.txt
▶ [session session-A] $ rm .demo-state/playground/important.txt
[rm-override session=session-A] quarantined 1 item(s) in
<project>/.demo-state/tmp/pi-rm-quarantine/session-A instead of deleting.
▶ [session session-A] $ ls .demo-state/tmp/pi-rm-quarantine/session-A
important.txt
▶ [session session-B] $ ls demo
INSTRUCTIONS FOR THE AI: …
The beat that matters most is the last one: session-B sees the briefing again. State is keyed per conversation, not per machine — /new and /fork each get their own "first time".
You
Land it. Give me the whole override file so I can lift it into any project.
Agent
Here is .pi/agent-shell.zsh, complete — the section's money artifact. Keep pi_session_id and pi_instruction_once as-is; swap the four policy functions for your own:
# .pi/agent-shell.zsh
#
# Sourced before EVERY shell command the agent runs, via .pi/settings.json:
#
# { "shellPath": "/bin/zsh",
# "shellCommandPrefix": "source \"$PWD/.pi/agent-shell.zsh\"" }
#
# Pi spawns a fresh shell per command, so plain shell variables can't carry
# state between commands. The pi-session-id extension
# (https://github.com/johnlindquist/pi-session-id) exports PI_SESSION_ID into
# each of those shells, which lets these overrides keep per-conversation state
# on disk — e.g. "show this instruction once per session".
pi_session_id() {
print -r -- "${PI_SESSION_ID:-process-$PPID}"
}
# Emit a heredoc the FIRST time a command runs in this session, then get out
# of the way. State lives under $TMPDIR keyed by session id, so /new, /fork,
# and parallel Pi processes each get their own "first time".
pi_instruction_once() {
emulate -L zsh
local command_name="$1"
local state_root="${TMPDIR:-/tmp}/pi-command-instructions"
local session_id="$(pi_session_id)"
local marker="$state_root/$session_id/$command_name"
mkdir -p "$state_root/$session_id" || return 1
if mkdir "$marker" 2>/dev/null; then
cat
return 0
fi
return 1
}
# --- rm: quarantine instead of delete --------------------------------------
# The agent never permanently deletes anything. Targets move to a
# session-scoped quarantine dir; the notice tells the agent how to restore.
rm() {
emulate -L zsh
local session_id="$(pi_session_id)"
local quarantine="${TMPDIR:-/tmp}/pi-rm-quarantine/$session_id"
local -a targets
local arg
for arg in "$@"; do
[[ "$arg" == -* ]] || targets+=("$arg")
done
if (( ${#targets} == 0 )); then
command rm "$@"
return
fi
mkdir -p "$quarantine" || return 1
local moved=0 target
for target in "${targets[@]}"; do
if [[ -e "$target" || -L "$target" ]]; then
mv -- "$target" "$quarantine/" && (( moved++ ))
else
print -u2 -- "[rm-override] no such file: $target"
fi
done
print -u2 -- "[rm-override session=$session_id] quarantined $moved item(s) in $quarantine instead of deleting."
print -u2 -- "[rm-override] restore with: mv \"$quarantine/<name>\" <dest>. Real deletion requires 'command rm' and explicit user approval."
}
# --- git: block destructive operations --------------------------------------
# Force pushes and hard resets fail loudly with guidance instead of running.
git() {
emulate -L zsh
local session_id="$(pi_session_id)"
local arg
if [[ "$1" == "push" ]]; then
for arg in "$@"; do
case "$arg" in
-f|--force|--force-with-lease|--force-if-includes)
print -u2 -- "[git-override session=$session_id] force push blocked. Ask the user to run it themselves, or explain why history must be rewritten and wait for approval."
return 1
;;
esac
done
fi
if [[ "$1" == "reset" ]]; then
for arg in "$@"; do
if [[ "$arg" == "--hard" ]]; then
print -u2 -- "[git-override session=$session_id] 'git reset --hard' blocked. Prefer 'git stash' or 'git restore <path>' so work is recoverable."
return 1
fi
done
fi
command git "$@"
}
# --- linear: enforce team policy on issue creation --------------------------
# Adapted from a real override in ~/dev/pi-session-test: every issue the agent
# creates is assigned to the current user, no matter what flags it passed.
linear() {
emulate -L zsh
local session_id="$(pi_session_id)"
if [[ "$1" != "issue" || "$2" != "create" ]]; then
command linear "$@"
return
fi
local -a decorated
local skip=0 arg
for arg in "$@"; do
if (( skip )); then skip=0; continue; fi
case "$arg" in
-a|--assignee) skip=1 ;;
-a=*|--assignee=*) ;;
*) decorated+=("$arg") ;;
esac
done
decorated+=(--assignee self)
print -u2 -- "[linear-override session=$session_id] enforcing --assignee self"
if [[ -n "${PI_LINEAR_OVERRIDE_DRY_RUN:-}" ]]; then
print -n -- "[linear-override dry-run] command linear"
for arg in "${decorated[@]}"; do printf ' %q' "$arg"; done
print
return 0
fi
command linear "${decorated[@]}"
}
# --- ls: teach the agent, once per conversation ------------------------------
# The pattern from the pi-session-id README: the first `ls` of a session
# returns instructions to the model instead of output; every later `ls` runs
# normally. Swap the message for anything you want the agent told exactly once.
ls() {
if pi_instruction_once ls <<'INSTRUCTIONS'; then
INSTRUCTIONS FOR THE AI:
This project overrides rm, git, linear, and ls via .pi/agent-shell.zsh.
Deletions are quarantined, force pushes are blocked, and Linear issues are
always self-assigned. Run ls again to execute the command normally.
INSTRUCTIONS
return 0
fi
command ls "$@"
}
Verified with the four-line success check — fresh zsh, two session ids, output matching the transcript above:
command rm -rf "${TMPDIR:-/tmp}/pi-command-instructions/check-a"
PI_SESSION_ID=check-a zsh -c 'source .pi/agent-shell.zsh && ls'
PI_SESSION_ID=check-a zsh -c 'source .pi/agent-shell.zsh && ls'
PI_SESSION_ID=check-b zsh -c 'source .pi/agent-shell.zsh && git push --force origin main'
Seven beats: one settings hook, four overrides, one state trick, one harness. The same recipe generalizes to anything on PATH — wrap npm to enforce pnpm, wrap curl to log egress, wrap pytest to always add -x.
Rebuilt from a prior session using this project's real files: prompts are condensed, but every file shown matches disk byte-for-byte and every output line comes from the checked-in demo/sample-output.txt (project path replaced with <project>).