Extended explanations, comparisons, experiments, and practical actions for the same operating pattern.
Abstract
Agents act through the shell, so the shell is the highest-leverage place to encode project policy. Pi runs every agent command in a fresh shell and lets a trusted project prepend a shellCommandPrefix, which makes one sourced zsh file a checkpoint for everything the agent executes. Stateless overrides can block a force push today; the pi-session-id extension adds a conversation-scoped key, PI_SESSION_ID, so overrides can also keep per-session state such as first-run instructions. The evidence here is the project's own override file and a captured transcript from a harness that reproduces Pi's execution model. The limit is equally concrete: these overrides are guidance the agent reads at the moment it acts, not a sandbox, and command rm walks straight past them.
Notice where your policy actually runs
You have probably written rules for your agent in a CLAUDE.md or AGENTS.md file: never force push, never hard-delete, always assign issues to yourself. Then, forty thousand tokens into a session, the agent runs rm -rf anyway. The mistake is treating instructions the model read once as if they control actions it takes much later.
Every file deletion, push, and issue the agent creates passes through one place: the shell. A message printed by the shell arrives at the exact moment the agent acts, while a static instruction competes with everything else in context. That timing difference is the whole trick, and it is an editorial inference this page then tests against a captured transcript (S5). 1
1. The workshop agenda (S6) frames this section as demoing the pi-session-id project and “overriding rm, linear, git, and other behavior.” The agenda also notes that hooks remain the tool for maximum control — a boundary section 5 returns to. ↩
Watch for the signal as you read: every override in this project prints a tagged line such as [git-override session=…] to stderr. If you can see that line in the agent's tool output, the agent saw it too — and can change course in the same turn.
Explain the two files that rewire every command
The entire mechanism is two files checked into the project. The first is .pi/settings.json, which tells Pi which shell to use and what to run before every command:
{
"shellPath": "/bin/zsh",
"shellCommandPrefix": "source \"$PWD/.pi/agent-shell.zsh\""
}
Figure 1. The project's complete .pi/settings.json (S3), byte-identical to the file in the demo project. Source evidence, not a derived display.
The second file, .pi/agent-shell.zsh, is plain zsh. Because Pi sources it before each command, any function defined there shadows the command of the same name. The pi-session-id README (S1) documents exactly this pattern: a project sources a function file through trusted .pi/settings.json, and PI_SESSION_ID is already present in the child environment before the prefix runs. 2
2. “Trusted” matters: Pi asks you to approve a project's settings before it will run a prefix from them. An override file executes with your full permissions, so read it the way you would read a shell script from the internet — because it is one. ↩
Working definition. On this page, an override is a zsh function that shadows a command name for the agent's shell. The real binary stays reachable through command rm, command git, and so on. This is a convention for this page, not a term from the sources.
This project ships four overrides (S3): rm moves targets to a session-scoped quarantine instead of deleting them; git blocks push --force and reset --hard with guidance; linear rewrites issue create so the issue is always self-assigned; and ls delivers a one-time briefing. The linear override is adapted from a working policy file in a sibling test project (S4), where every issue an agent creates is forced to --assignee self regardless of the flags it passed.
Compare stateless guardrails with session-scoped memory
Here is the fork in the road when you write your own override. Pi spawns a fresh shell process for every command, so a shell variable set during one command is gone by the next. Blocking a force push needs no memory — the evidence is in the argv right in front of you. But “tell the agent this once, then get out of the way” needs state that survives across those throwaway shells.
Storing that state under a fixed path fails in a specific way: /new, /resume, /fork, and a second Pi process would all share one “first time.” The pi-session-id extension (S1, S2) solves this by exporting the active conversation ID as PI_SESSION_ID into each shell, synchronizing it on session_start, on human ! commands, and on every model bash tool call, then clearing it on shutdown. 3
3. The extension (S2) is about 44 lines of TypeScript. It validates the session ID against Pi's allowed syntax before inserting it into shell source; an invalid value blocks the tool call rather than permitting injection (S1). ↩
With that key available, per-conversation state is a directory name. The helper below creates a marker directory the first time a command runs in a session and emits its heredoc only then; the ls override uses it to brief the model once:
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
}
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 "$@"
}
Figure 2. The instruction-once helper and ls override from this project's .pi/agent-shell.zsh (S3), following the pattern published in the pi-session-id README (S1). Source evidence.
The decision rule when you write your own: if the override can judge the command from its arguments alone, keep it stateless. Reach for PI_SESSION_ID only when the behavior must differ between the first occurrence in a conversation and every later one.
Test the overrides before an agent depends on them
An override you have never executed is a guess. The tempting shortcut is to install everything and find out mid-session, when a broken function makes every agent command fail. This project instead ships a harness, demo/run-demo.sh, that reproduces how Pi runs agent commands — a fresh zsh per command, the prefix sourced, PI_SESSION_ID set — so you can watch each override fire without Pi in the loop.
▶ [session session-A] $ ls demo
INSTRUCTIONS FOR THE AI:
This project overrides rm, git, linear, and ls via .pi/agent-shell.zsh. …
▶ [session session-A] $ ls demo
run-demo.sh
▶ [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] $ 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] $ 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
▶ [session session-B] $ ls demo
INSTRUCTIONS FOR THE AI: …
Figure 3. Excerpt from the captured harness transcript (S5), reorganized for length: long lines are wrapped, repeated instruction text is elided with …, and the project's absolute path is shortened to <project>. A derived display of source output.
Evidence limit This transcript comes from the harness, not from a live Pi session, and the linear call ran with a dry-run flag that prints the rewritten argv instead of hitting the Linear API. It demonstrates the shell functions faithfully; it does not by itself prove Pi's trust flow or the extension's lifecycle hooks, which the sources document separately (S1, S2).
Read the transcript against the claims. First ls: instructions to the model. Second ls: normal output — the marker directory did its job. The quarantined file is listed, not gone. The force push never executed. The Linear issue lost its --assignee someone-else and gained --assignee self. And session-B sees the briefing again, because state is keyed by conversation. If you run the harness and any act differs, fix the override before letting an agent near it.
Choose guidance with teeth, not a sandbox
The last judgment call is what to trust these overrides for. The weak position treats them as a security boundary. The strong position treats them as high-signal steering: messages delivered at the moment of action that a cooperative agent reads and obeys.
The coverage limits are documented, not hypothetical. The pi-session-id README (S1) lists what the mechanism does not cover: extension-internal pi.exec() calls, custom tools that spawn processes directly, and commands that clear their environment with env -i or unset PI_SESSION_ID. And within the shell itself, command rm bypasses the function by design — the overrides in this project even say so in their own stderr output (S3).
Evidence limit Nothing here measures how often an agent complies with override guidance versus routing around it. The sources support the mechanism and its coverage, not a compliance rate. Treat “the agent self-corrects” as behavior to observe in your own sessions, not a guarantee.
The decision rule: use shell overrides to steer — redirect destructive commands, inject policy, brief the model — and use Pi's hooks and permission system to enforce anything you cannot afford to have bypassed. If violating the rule merely wastes a turn, an override is enough. If violating it loses data or pushes broken history, put a real control behind the override's friendly message.
Practical action
To give one of your own projects a custom agent environment, in order:
- Install the extension:
pi install git:github.com/johnlindquist/pi-session-id(S1). - Copy the two files from this demo project:
.pi/settings.jsonand.pi/agent-shell.zsh. - Replace the demo overrides with your policy. Keep each function's stderr message short, tagged, and addressed to the agent, and always leave the
command <name>escape hatch documented. - Test with a harness before trusting: run each override in a fresh
zsh -cwithPI_SESSION_IDset, twice, under two session IDs. Your feedback signal is the tagged stderr line and, for stateful overrides, different behavior on the first and second run. - Open the project in Pi, approve the settings when prompted, and ask the agent to do something an override guards. If the agent reads the message and adjusts, the loop works; if it bypasses, move that rule into hooks or permissions.