Policy at the agent’s execution boundary — worked example

Detailed worked example with concrete prompts, observable outcomes, and the limits of the example.

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

Source references