Agentic Software Factory · 2026-07-17 · Socratic Dialogue
“Can't I just put the rules in CLAUDE.md?”
The section as the workshop room actually runs it: skeptical questions drive the reveal, and each answer lands the real code exactly where the question demands it.
The questions
Because that rule is something the model read once, maybe forty thousand tokens ago. An override is a message to the model at the exact moment it acts — it lands in the agent's tool output in the same turn as the blocked action:
▶ [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.
If you can see that line in the transcript, the agent saw it too. It reads the guidance and changes course immediately — no hoping it remembered.
Two files in .pi/. The first is a settings file that tells Pi to source a zsh file before every command the agent runs:
{
"shellPath": "/bin/zsh",
"shellCommandPrefix": "source \"$PWD/.pi/agent-shell.zsh\""
}
The second is that zsh file. A zsh function shadows the command of the same name — so rm, git, linear, and ls become yours to shape. No plugin API, no magic.
No — and the overrides say so in their own stderr. command rm and command git bypass the functions by design. This is guidance with teeth, not a security boundary:
▶ [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.
[rm-override] restore with: mv "<quarantine>/<name>" <dest>. Real deletion
requires 'command rm' and explicit user approval.
The decision rule: use overrides to steer — redirect destructive commands, inject policy, brief the model. Use Pi's hooks and permission system to enforce anything you can't afford to have bypassed.
Not with shell variables — those die with each shell. State lives on disk, keyed by conversation. The pi-session-id extension (~44 lines of TypeScript) exports the active conversation ID as PI_SESSION_ID into every shell, and then "once" is a single 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
}
The first ls of a session returns instructions addressed to the AI; every later ls runs normally. The ID is validated against Pi's session-ID syntax before it touches shell source — an invalid value blocks the call rather than permitting injection.
No, and that's exactly why the session ID matters. State is keyed per conversation, so each /new, /fork, and parallel Pi process gets its own "first time". From the captured harness run:
▶ [session session-B] $ 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-A had already been briefed; session-B sees the briefing again. Without the extension, the fallback is process-$PPID — stable per shell process, not per conversation.
linear override actually change?One subcommand, one flag. Only linear issue create is touched: whatever assignee the agent passed is dropped and --assignee self is appended — and the rewrite is announced on stderr so the agent knows policy fired:
▶ [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
Every other linear subcommand passes through untouched. It's adapted from a working policy in a real test project — the point is the override owns the team rule, not the agent's memory of it.
Run it the way Pi does — fresh zsh, prefix sourced, PI_SESSION_ID set — with no agent in the loop. Four lines from your project root:
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'
First ls prints the briefing, second prints your normal listing, and the force push is refused with exit code 1. This project also ships demo/run-demo.sh, a five-act harness version of the same idea — an override you've never executed is a guess.
The mechanism is pi's; the move isn't. Every agent has a seam where its actions pass through, and all three give you a way to speak to the model right there. Codex agent shells are real non-interactive zsh — plain codex doesn't automatically receive your zsh helper/function surface, but a guard in your .zshenv can source chosen function files into agent shells that opt in. Same plain function shadowing as this page, stderr included. The opt-in is one env var — a local marker this setup invented, not a Codex built-in:
codex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL="1"'
Claude Code's seam is the tool call instead of the shell: a PreToolUse hook on Bash can deny a force push and hand the model the same "force push blocked" guidance this page's git() override prints — delivered before the command ever runs, with session_id arriving on the hook's stdin to play the PI_SESSION_ID role. In all three agents, the override's output at the moment of action IS the message to the model. The liftable files for both are in the cross-agent section of the guide.
Because most of .zshrc exists for a human at a prompt — prompt setup, completions, keybindings, fuzzy finders — and in a non-interactive agent shell that machinery can slow, hang, or spam every single command the agent runs. Treat startup as an airlock: .zshrc stays sealed, a narrow agent-safe path carries PATH and non-secret env, and the marker is the valve that admits chosen helper files. The field rule: missing PATH is not permission to pour .zshrc into Codex. A missing tool means you fix the agent-safe path; a missing helper means you opt it in behind the valve. The guide's cross-agent section carries a complete agent setup prompt that builds the clean layout end to end.
Here's .pi/agent-shell.zsh, complete. Keep pi_session_id and pi_instruction_once as-is; swap the four policy functions for your own — anything on PATH is fair game:
# .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 "$@"
}
Want your agent to do the whole setup? Paste this into it:
Fetch https://polite-ravine-6v8g.here.now/agent.md?raw and follow it to set this up in my current project. Run the success check at the end and show me the result.