{
  "schemaVersion": "1",
  "revision": "22ce5d34dbcb5a78",
  "id": "factory-environment-policy-questions",
  "slug": "environment-policy-questions",
  "title": "Policy at the agent’s execution boundary — questions and tradeoffs",
  "summary": "Detailed questions and tradeoffs with concrete prompts, observable outcomes, and the limits of the example.",
  "category": "Execution",
  "tags": [
    "environment-policy",
    "questions"
  ],
  "sources": [
    {
      "label": "Policy at the agent’s execution boundary — questions and tradeoffs",
      "url": "https://polite-ravine-6v8g.here.now/dialogue.html"
    }
  ],
  "sourceUnits": [
    "01-env/dialogue.html#The questions"
  ],
  "collection": "factory",
  "categoryId": "execution",
  "wordCount": 1875,
  "url": "/topics/factory-environment-policy-questions/",
  "markdownUrl": "/markdown/factory-environment-policy-questions.md?raw=1&v=22ce5d34dbcb5a78",
  "jsonUrl": "/api/v1/documents/factory-environment-policy-questions.json",
  "headings": [
    {
      "id": "the-questions",
      "text": "The questions",
      "level": 2
    }
  ],
  "markdown": "# Policy at the agent’s execution boundary — questions and tradeoffs\n\nDetailed questions and tradeoffs with concrete prompts, observable outcomes, and the limits of the example.\n\n## The questions\n\nI already tell my agent \"never force push\" in CLAUDE.md. Why isn't that enough?\n\nBecause 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:\n\n``` text\n▶ [session session-A] $ git push --force origin main\n  [git-override session=session-A] force push blocked. Ask the user to run it\n  themselves, or explain why history must be rewritten and wait for approval.\n```\n\nIf 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.\n\nHow much machinery does that take?\n\nTwo files in `.pi/`. The first is a settings file that tells Pi to source a zsh file before every command the agent runs:\n\n``` text\n{\n  \"shellPath\": \"/bin/zsh\",\n  \"shellCommandPrefix\": \"source \\\"$PWD/.pi/agent-shell.zsh\\\"\"\n}\n```\n\nThe 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.\n\nSo it's a sandbox? The agent physically can't delete my files?\n\nNo — 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:\n\n``` text\n▶ [session session-A] $ rm .demo-state/playground/important.txt\n  [rm-override session=session-A] quarantined 1 item(s) in\n  <project>/.demo-state/tmp/pi-rm-quarantine/session-A instead of deleting.\n  [rm-override] restore with: mv \"<quarantine>/<name>\" <dest>. Real deletion\n  requires 'command rm' and explicit user approval.\n```\n\nThe 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.\n\nPi spawns a fresh shell for every command. How does \"tell the agent this once per conversation\" remember anything?\n\nNot 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`:\n\n``` text\npi_instruction_once() {\n  emulate -L zsh\n  local command_name=\"$1\"\n  local state_root=\"${TMPDIR:-/tmp}/pi-command-instructions\"\n  local session_id=\"$(pi_session_id)\"\n  local marker=\"$state_root/$session_id/$command_name\"\n\n  mkdir -p \"$state_root/$session_id\" || return 1\n  if mkdir \"$marker\" 2>/dev/null; then\n    cat\n    return 0\n  fi\n  return 1\n}\n```\n\nThe 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.\n\nWhat happens when I hit /new or /fork — do I inherit stale \"already briefed\" state?\n\nNo, 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:\n\n``` text\n▶ [session session-B] $ ls demo\n  INSTRUCTIONS FOR THE AI:\n  This project overrides rm, git, linear, and ls via .pi/agent-shell.zsh.\n  Deletions are quarantined, force pushes are blocked, and Linear issues are\n  always self-assigned. Run ls again to execute the command normally.\n```\n\nSession-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.\n\nRewriting the agent's commands feels invasive. What does the `linear` override actually change?\n\nOne 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:\n\n``` text\n▶ [session session-A] $ linear issue create --title 'Fix login bug' --assignee someone-else\n  [linear-override session=session-A] enforcing --assignee self\n  [linear-override dry-run] command linear issue create --title Fix\\ login\\ bug --assignee self\n```\n\nEvery 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.\n\nHow do I trust any of this before an agent depends on it mid-session?\n\nRun 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:\n\n``` text\ncommand rm -rf \"${TMPDIR:-/tmp}/pi-command-instructions/check-a\"\nPI_SESSION_ID=check-a zsh -c 'source .pi/agent-shell.zsh && ls'\nPI_SESSION_ID=check-a zsh -c 'source .pi/agent-shell.zsh && ls'\nPI_SESSION_ID=check-b zsh -c 'source .pi/agent-shell.zsh && git push --force origin main'\n```\n\nFirst `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.\n\nDoes this only work in pi? I'm in Claude Code half the day and Codex the other half.\n\nThe 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:\n\n``` text\ncodex -c 'shell_environment_policy.set.CODEX_LOAD_ZSH_DSL=\"1\"'\n```\n\nClaude 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).\n\nIf Codex just runs zsh, why not source my whole .zshrc into its shells and be done with it?\n\nBecause 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.\n\nFine — just give me the file.\n\nHere'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:\n\n``` text\n# .pi/agent-shell.zsh\n#\n# Sourced before EVERY shell command the agent runs, via .pi/settings.json:\n#\n#   { \"shellPath\": \"/bin/zsh\",\n#     \"shellCommandPrefix\": \"source \\\"$PWD/.pi/agent-shell.zsh\\\"\" }\n#\n# Pi spawns a fresh shell per command, so plain shell variables can't carry\n# state between commands. The pi-session-id extension\n# (https://github.com/johnlindquist/pi-session-id) exports PI_SESSION_ID into\n# each of those shells, which lets these overrides keep per-conversation state\n# on disk — e.g. \"show this instruction once per session\".\n\npi_session_id() {\n  print -r -- \"${PI_SESSION_ID:-process-$PPID}\"\n}\n\n# Emit a heredoc the FIRST time a command runs in this session, then get out\n# of the way. State lives under $TMPDIR keyed by session id, so /new, /fork,\n# and parallel Pi processes each get their own \"first time\".\npi_instruction_once() {\n  emulate -L zsh\n  local command_name=\"$1\"\n  local state_root=\"${TMPDIR:-/tmp}/pi-command-instructions\"\n  local session_id=\"$(pi_session_id)\"\n  local marker=\"$state_root/$session_id/$command_name\"\n\n  mkdir -p \"$state_root/$session_id\" || return 1\n  if mkdir \"$marker\" 2>/dev/null; then\n    cat\n    return 0\n  fi\n  return 1\n}\n\n# --- rm: quarantine instead of delete --------------------------------------\n# The agent never permanently deletes anything. Targets move to a\n# session-scoped quarantine dir; the notice tells the agent how to restore.\nrm() {\n  emulate -L zsh\n  local session_id=\"$(pi_session_id)\"\n  local quarantine=\"${TMPDIR:-/tmp}/pi-rm-quarantine/$session_id\"\n  local -a targets\n  local arg\n  for arg in \"$@\"; do\n    [[ \"$arg\" == -* ]] || targets+=(\"$arg\")\n  done\n\n  if (( ${#targets} == 0 )); then\n    command rm \"$@\"\n    return\n  fi\n\n  mkdir -p \"$quarantine\" || return 1\n  local moved=0 target\n  for target in \"${targets[@]}\"; do\n    if [[ -e \"$target\" || -L \"$target\" ]]; then\n      mv -- \"$target\" \"$quarantine/\" && (( moved++ ))\n    else\n      print -u2 -- \"[rm-override] no such file: $target\"\n    fi\n  done\n  print -u2 -- \"[rm-override session=$session_id] quarantined $moved item(s) in $quarantine instead of deleting.\"\n  print -u2 -- \"[rm-override] restore with: mv \\\"$quarantine/<name>\\\" <dest>. Real deletion requires 'command rm' and explicit user approval.\"\n}\n\n# --- git: block destructive operations --------------------------------------\n# Force pushes and hard resets fail loudly with guidance instead of running.\ngit() {\n  emulate -L zsh\n  local session_id=\"$(pi_session_id)\"\n  local arg\n\n  if [[ \"$1\" == \"push\" ]]; then\n    for arg in \"$@\"; do\n      case \"$arg\" in\n        -f|--force|--force-with-lease|--force-if-includes)\n          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.\"\n          return 1\n          ;;\n      esac\n    done\n  fi\n\n  if [[ \"$1\" == \"reset\" ]]; then\n    for arg in \"$@\"; do\n      if [[ \"$arg\" == \"--hard\" ]]; then\n        print -u2 -- \"[git-override session=$session_id] 'git reset --hard' blocked. Prefer 'git stash' or 'git restore <path>' so work is recoverable.\"\n        return 1\n      fi\n    done\n  fi\n\n  command git \"$@\"\n}\n\n# --- linear: enforce team policy on issue creation --------------------------\n# Adapted from a real override in ~/dev/pi-session-test: every issue the agent\n# creates is assigned to the current user, no matter what flags it passed.\nlinear() {\n  emulate -L zsh\n  local session_id=\"$(pi_session_id)\"\n\n  if [[ \"$1\" != \"issue\" || \"$2\" != \"create\" ]]; then\n    command linear \"$@\"\n    return\n  fi\n\n  local -a decorated\n  local skip=0 arg\n  for arg in \"$@\"; do\n    if (( skip )); then skip=0; continue; fi\n    case \"$arg\" in\n      -a|--assignee) skip=1 ;;\n      -a=*|--assignee=*) ;;\n      *) decorated+=(\"$arg\") ;;\n    esac\n  done\n  decorated+=(--assignee self)\n\n  print -u2 -- \"[linear-override session=$session_id] enforcing --assignee self\"\n\n  if [[ -n \"${PI_LINEAR_OVERRIDE_DRY_RUN:-}\" ]]; then\n    print -n -- \"[linear-override dry-run] command linear\"\n    for arg in \"${decorated[@]}\"; do printf ' %q' \"$arg\"; done\n    print\n    return 0\n  fi\n\n  command linear \"${decorated[@]}\"\n}\n\n# --- ls: teach the agent, once per conversation ------------------------------\n# The pattern from the pi-session-id README: the first `ls` of a session\n# returns instructions to the model instead of output; every later `ls` runs\n# normally. Swap the message for anything you want the agent told exactly once.\nls() {\n  if pi_instruction_once ls <<'INSTRUCTIONS'; then\nINSTRUCTIONS FOR THE AI:\nThis project overrides rm, git, linear, and ls via .pi/agent-shell.zsh.\nDeletions are quarantined, force pushes are blocked, and Linear issues are\nalways self-assigned. Run ls again to execute the command normally.\nINSTRUCTIONS\n    return 0\n  fi\n\n  command ls \"$@\"\n}\n```\n\nWant your agent to do the whole setup? Paste this into it:\n\n``` text\nFetch 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.\n```"
}
