The work-root guard I run before letting an agent near several repositories

Collecting the checks into one file

Remembering to normalise is not a strategy that survives a busy week. I moved the checks into a single script that every agent task has to pass through first.

#!/usr/bin/env bash
# workroot-guard.sh — settle which directory an agent is allowed to work in
set -euo pipefail
 
ALLOWED_ROOT="${ALLOWED_ROOT:?ALLOWED_ROOT is not set}"
DECLARED_WORK="${1:?pass the working root as an argument}"
 
[ -d "$DECLARED_WORK" ] || { echo "guard: no such working root: $DECLARED_WORK" >&2; exit 2; }
 
ROOT_REAL=$(realpath -e "$ALLOWED_ROOT")
WORK_REAL=$(realpath -e "$DECLARED_WORK")
 
# (1) reject anything outside the allowed root, judged after .. and symlinks collapse
case "$WORK_REAL/" in
  "$ROOT_REAL"/*) : ;;
  *) echo "guard: outside the allowed root: $WORK_REAL (allowed: $ROOT_REAL)" >&2; exit 3 ;;
esac
 
# (2) never let the allowed root itself be the working root
[ "$WORK_REAL" != "$ROOT_REAL" ] || { echo "guard: the allowed root cannot be the working root" >&2; exit 4; }
 
# (3) ask the filesystem whether the declared path really is the git toplevel
TOP=$(git -C "$WORK_REAL" rev-parse --show-toplevel 2>/dev/null || true)
[ -n "$TOP" ] || { echo "guard: not a git repository: $WORK_REAL" >&2; exit 5; }
[ "$(realpath -e "$TOP")" = "$WORK_REAL" ] || {
  echo "guard: not the toplevel. actual toplevel: $TOP" >&2; exit 6; }
 
echo "$WORK_REAL"

On success it prints one line: the resolved path. Callers take it with WORK=$(workroot-guard.sh "$1") and touch nothing else afterwards. On failure the exit code separates the reasons, so the log tells you which check refused.

The -e in realpath -e means "error if the path does not exist". Without it, a misspelled path that points nowhere gets normalised and sails through. Do not drop it.

Seven inputs, seven expected outcomes

Once written, run it. I lined up the inputs I expected to see and checked that each stops in the intended place.

export ALLOWED_ROOT="$T/repos"
run(){ printf '%-38s -> ' "$1"; out=$(./workroot-guard.sh "$2" 2>&1) \
  && echo "OK  $out" || echo "exit=$? $out"; }
 
run "repository toplevel"      "$T/repos/siteA"
run "with a trailing slash"    "$T/repos/siteA/"
run "through a symlink alias"  "$T/repos/siteA-link"
run "a subdirectory inside it" "$T/repos/siteA/src"
run "the allowed root itself"  "$T/repos"
run "escaping with ../"        "$T/repos/../repos/../"
run "not under git at all"     "$T/bin"

Results:

The first three rows converging on the same .../repos/siteA is the guard doing its job. Three textually different inputs become one value for everything downstream.

Asking "is this a git repository?" is not enough

Row four was the one that surprised me.

git -C .../siteA/src rev-parse --show-toplevel succeeds. It does not error. It happily returns .../siteA, the correct toplevel. So to the question "is the path you were handed a git repository?", a subdirectory answers yes with complete confidence.

I had been treating that call as a test for "is this the repository root". It is only a test for "is this somewhere inside a repository". To confirm the toplevel, you have to take the answer and compare it against the declared path yourself. That is why check (3) in the script spans two lines instead of one.

The distinction matters most when an agent inherits its position from a previous task. Standing in src/ and being told "work in this repository" passes cleanly, because it genuinely is inside the repository. Then every relative output path sprouts one level deeper than you expected.

Hand the same resolved path to the cleanup

The value the guard returns is for tidying up as well as for working. Here is the opening cleanup loop, rewritten against resolved paths:

ROOT_REAL=$(realpath "$ALLOWED_ROOT")
WORK_REAL=$(./workroot-guard.sh "$DECLARED_WORK")   # stops here, and the sweep never runs
 
find "$ROOT_REAL" -mindepth 1 -maxdepth 1 -print0 | while IFS= read -r -d '' P; do
  PR=$(realpath -e "$P") || continue
  if [ "$PR" = "$WORK_REAL" ]; then echo "  keep : $P"; continue; fi
  echo "  sweep: $P"
  rm -rf -- "$PR"
done

Running it with siteA, siteB, siteC and a symlink present, declaring the working root through the symlink:

  keep : .../repos/siteA
  sweep: .../repos/siteB
  sweep: .../repos/siteC
  keep : .../repos/siteA-link

The marker file inside siteA survived, and the repos directory itself survived. Declaring through an alias still protected the right thing.

The -- in rm -rf -- "$PR" stops a directory whose name begins with a hyphen from being read as an option. Nobody creates such names by hand, but build output manages it.

Forget -mindepth 1 and the parent goes too

If your cleanup uses find, -mindepth 1 is not decoration. find includes its own starting point in the results, so leaving it out puts the parent directory on the list.

# starting point included
find "$T/cache" -maxdepth 1 -type d -exec rm -rf {} +
#   → does cache still exist: NO
 
# with -mindepth 1
find "$T2/cache" -mindepth 1 -maxdepth 1 -type d -exec rm -rf {} +
#   → does cache still exist: yes
#   → does keep.txt still exist: yes

The first form took cache with it. I only wanted a/ and b/ gone, but keep.txt sitting beside them disappeared as well. The second form left cache and keep.txt in place and removed only the directories.

While you are using -delete, non-empty directories fail loudly and you notice. The moment you switch to -exec rm -rf {} +, it goes through in silence. Check for -mindepth 1 precisely when you change that form.

What set -u covers, and what it does not

Of the set -euo pipefail at the top of the script, -u is the one carrying weight here. Expanding an undefined variable stops the script on the spot.

( set -u; rm -rf "${UNSET_VAR}/build" )
#   → bash: UNSET_VAR: unbound variable
 
echo "${UNSET_VAR2}/build"
#   → /build

Without set -u, "${UNSET_VAR2}/build" becomes the string /build. A typo in a variable name is enough to aim a deletion at the root of the filesystem.

But -u catches undefined only. An empty string passes straight through: WORK="" is defined, so it silently becomes /build. When empty must be refused too, use the ${WORK:?...} form. That is exactly why the script opens with ALLOWED_ROOT="${ALLOWED_ROOT:?...}".

Wiring it into agent instructions

With the guard in place, the remaining work is shaping things so the agent never picks a path itself. Three habits carried most of the benefit for me.

Settle the working root once, at the start of the task, and leave it alone. Rather than telling the agent to cd somewhere inside the prompt, pass the absolute path the guard returned and spell it out each time as git -C "$WORK" .... The less your commands depend on the current directory, the less a drifting position changes the outcome.

Write anything that deletes only downstream of a successful guard. If the guard exits 3, not one line of the sweep runs. With set -e in place you get that without writing an explicit if.

And keep the guard's output in the log. A single line reading guard: not the toplevel. actual toplevel: ... tells you later where you thought you were working. Agent logs grow long, but that one line earns a findable spot.

For deciding the scope of work in the first place, Re-drawing the workspace surface when read access is auto-approved in review mode covers related ground. And if a guard's exit code never reaches the caller, The Antigravity CLI failure was being swallowed by the caller's pipe describes that shape of problem.

One next step

Start by checking whether realpath appears anywhere in the cleanup lines you already run. If it does not, adding the two lines that resolve both sides before comparing is enough to begin.

Until I put this guard in place, I assumed I simply would not get the working directory wrong. People do not get it wrong. Notation drift in a path just never looks like a mistake.