---
schema_version: 1
revision: "22ce5d34dbcb5a78"
id: "factory-environment-policy-questions"
title: "Policy at the agent’s execution boundary — questions and tradeoffs"
---

# Policy at the agent’s execution boundary — questions and tradeoffs

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

## 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:

``` text
▶ [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:

``` text
{
  "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:

``` text
▶ [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`:

``` text
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:

``` text
▶ [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:

``` text
▶ [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:

``` text
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:

``` text
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](https://polite-ravine-6v8g.here.now/index.html#same-trick-in-claude-code-and-codex).

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:

``` text
# .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:

``` text
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.
```

## Original references

- [Policy at the agent’s execution boundary — questions and tradeoffs](https://polite-ravine-6v8g.here.now/dialogue.html)
