Agentic Software Factory · 2026-07-17 · Session Replay

Watch the session that rewired the agent's shell

An annotated replay of the prior session that built this section's .pi/ setup: seven beats from "can we hook every command?" to a policy file you can lift into any project.

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>).