A hook that stops coding agents from walking / and your home directory.
An agent that cannot find a file runs find / -name foo, grep -r foo ~ or a Glob over your
home directory. The walk takes minutes, loads the disk, and reads folders you never meant it to
see. agent-walk-guard is a PreToolUse hook for Claude Code and Codex CLI. It reads each
command before it runs. If the command is a recursive walk of /, your home directory or a root you
name, it refuses the call and tells the agent which narrower route to take. The agent reads the
refusal and retries with a path that works.
One Python file, standard library only, one optional JSON config file.
On one busy multi-agent host we replayed 7 days of recorded shell calls (60,677) through the guard this one was ported from. It refused 352 of them (0.58 %), and those 352 calls took 18,983 s: 4.2 % of all shell wall-clock time on the host.
- 135 calls (8,436 s, 1.9 %) were walks of
/, the home directory, or the directory that holds every project (a configured root). The defaults plus onerootsentry cover these. - 217 calls (10,547 s, 2.3 %) were recursive content searches over the top of two large repositories
that did not skip their folders of generated files. That is what the
heavy_treesoption is for; it is empty by default.
150 of the 352 ran longer than 60 s; the typical refused find / or grep -r over the project
directory stopped at about 120 s, the tool's timeout. We read every refusal; each was one of the walks
above. That is one host and one week, not a benchmark.
Copy agent_walk_guard.py somewhere stable and register it as a PreToolUse hook. Python 3.9 or later
(CI runs the tests on every push on Python 3.9 to 3.15).
Claude Code — add to ~/.claude/settings.json (all projects) or .claude/settings.json
(hooks reference):
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash|Glob|Grep",
"hooks": [
{ "type": "command", "command": "python3 /absolute/path/to/agent_walk_guard.py" }
]
}
]
}
}Codex CLI — add to ~/.codex/hooks.json (or inline in ~/.codex/config.toml, see
examples/codex-config.toml), then review and trust the hook in Codex:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{ "type": "command", "command": "python3 /absolute/path/to/agent_walk_guard.py" }
]
}
]
}
}What Codex documents (read 2026-11-14, Codex hooks docs, the page developers.openai.com/codex/hooks redirects to)
Codex has a supported hook point, and it takes the same deny reply as Claude Code. From that page:
- "Hooks are enabled by default."
PreToolUsecovers shell commands ("Match asBash"), and alsoapply_patch, MCP tools and other local function tools. "Hosted tools, such asWebSearch," are not covered.- To deny, print
hookSpecificOutputwithpermissionDecisionset todenyand apermissionDecisionReason, exit 0. Exit code 2 with the reason on stderr also blocks. - "Non-managed hooks must be reviewed and trusted before they run." A changed hook is skipped until
trusted again. Project-local hooks load only when the project's
.codex/layer is trusted. - "Treat tool hooks as a useful guardrail, not a complete enforcement boundary."
On Codex the guard checks shell commands (the Bash tool). It does not check other Codex tools. The
Codex side is built from that documented contract and tested with a Codex-shaped payload
(tests/test_walk_guard.py::Bounds::test_codex_payload_shape). We have not yet run it inside a live
Codex session; if you do, an issue with what you saw is welcome.
A walk whose search root resolves, after cd, ., ~, $HOME, and a trailing /*, to /,
/home, /Users, your home directory, or a root you add:
| Command | Refused unless |
|---|---|
find, bfs |
-maxdepth 3 or less (BSD -depth N is not a bound) |
fd, fdfind |
-d 3 or less |
tree |
-L 3 or less |
rg, ugrep |
--max-depth 3 or less (ugrep also -1 to -3) |
grep -r, -R, --recursive, -d recurse (also egrep, fgrep) |
never; name a directory (GNU -2 is context lines, not a depth) |
ls -R, du |
never; name a directory (du -d limits output, not the walk) |
Claude Code Glob and Grep tool |
a narrower path is given |
It follows cd, subshells, bash -c '...', pipes, timeout, env, sudo and similar wrappers. It
ignores text inside quotes, heredocs and redirections, so echo 'find / -name x' > notes.md passes.
A pipe's rg pattern that reads stdin passes.
The refusal names the narrower route, for example:
agent-walk-guard:
findwould walk all of /. A recursive walk from the filesystem root, a home directory or another configured root takes minutes, loads the disk and reads private folders. Search the one project or directory you mean (name it:find <project-dir> -name ..., ...). Inside a git repo, search tracked files from git's index, which is near-instant:git -C <repo> grep -n <pattern>... Your working directory is /home/me/app: start there if the target is in this project.
Optional. Without it the guard covers /, /home, /Users and your home directory. Looked up in
$AGENT_WALK_GUARD_CONFIG, then ~/.config/agent-walk-guard/config.json. See
agent-walk-guard.example.json.
| Key | Meaning |
|---|---|
roots |
More directories whose unbounded walk is refused (exact match: ~/work is guarded, ~/work/app is not). |
allow |
Directories to take out of the guarded set. |
max_depth |
A depth bound at or below this is accepted. Default 3. |
heavy_trees |
{"~/work/monorepo": ["node_modules", "dist"]}. A recursive content search (grep -r, rg, the Grep tool) of that tree's top is refused unless it excludes every listed directory. Rule W2-heavy-tree. Exclusions that count, with plain names only: --exclude-dir=NAME; rg and the Grep tool !NAME, !NAME/, !**/NAME or !{node_modules,dist} (rg -g '!NAME', Grep glob: "!{node_modules,dist}"); ugrep -g '!NAME/' (the trailing / makes it a directory glob; ugrep !NAME skips files only); or a depth bound. Spellings that can leave the directory searchable do not count: !NAME/** (with an absolute path outside the working directory), !./NAME, !/NAME, quoted or nested alternatives. In rg a later glob wins, and every --iglob counts as later than every -g, wherever it is written. So an include glob that can match the name (*, **) cancels the exclusion when it comes later, and --iglob '*' cancels -g '!NAME' in either order. Include filters (--include, -g '*.py', --exclude of files, Grep glob: "*.py" or type) still walk every directory and do not count. |
mode |
"enforce" (default) or "log": record what would be refused and allow the call. Use log for a week to see what your agents do. |
log |
JSONL path. One line per refusal: time, rule, tool, command name, root, SHA-256 of the input. No command text. Off by default. |
hint |
One sentence added to every refusal, for example where your team keeps a file index. |
A config file that cannot be read keeps the guard on with the defaults and prints a warning to stderr.
A value of the wrong type (for example "max_depth": "9") is dropped with a warning and its default
used; it never turns the guard off. A single string for roots or allow is read as a one-item list.
This is a guardrail against accidents, not a sandbox. It does not see:
- a walk inside a script,
python -c,os.walk,makeor a build tool; - command text it cannot resolve: unset variables,
$(...), globs other than a trailing*,cd -. Those calls are allowed; - any tool other than the ones above;
- globs that ripgrep reads from its own config file (
RIPGREP_CONFIG_PATH); - an agent that is trying to get around it. It can write a script. Use OS permissions or a container for that.
Any internal error allows the call (exit 0), so a bug here never blocks your agent. It does not read or write files other than its config and log.
python3 -m unittest discover -s tests -v
The tests run the hook as a subprocess against a throwaway HOME. tests/test_walk_guard.py holds one
generic command for each class of walk found in the replay above (REPLAY), the three calls that made us
write the guard (INCIDENT, paths invented), 33 refused and 33 allowed shell forms, the Glob/Grep
tools, and the config options. HOOK=/path/to/other-hook.py runs the same checks against another hook:
with a hook that never denies, the refusal checks fail.
MIT. Prepared by CyberNative AI LLC, an AI-run company, using AI agents.