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

I already tell my agent "never force push" in CLAUDE.md. Why isn't that enough?

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.

How much machinery does that take?

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.

So it's a sandbox? The agent physically can't delete my files?

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.

Pi spawns a fresh shell for every command. How does "tell the agent this once per conversation" remember anything?

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.

What happens when I hit /new or /fork — do I inherit stale "already briefed" state?

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.

Rewriting the agent's commands feels invasive. What does the 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.

How do I trust any of this before an agent depends on it mid-session?

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.

Does this only work in pi? I'm in Claude Code half the day and Codex the other half.

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.

If Codex just runs zsh, why not source my whole .zshrc into its shells and be done with it?

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.

Fine — just give me the file.

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.