Skip to content

About

A PreToolUse hook for Claude Code and Codex CLI that refuses recursive walks of / and your home directory, and tells the agent the narrower route.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

agent-walk-guard

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.

How much it matters

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 one roots entry 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_trees option 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.

Install

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."
  • PreToolUse covers shell commands ("Match as Bash"), and also apply_patch, MCP tools and other local function tools. "Hosted tools, such as WebSearch," are not covered.
  • To deny, print hookSpecificOutput with permissionDecision set to deny and a permissionDecisionReason, 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.

What it refuses

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: find would 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.

Config

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.

What it does not do

This is a guardrail against accidents, not a sandbox. It does not see:

  • a walk inside a script, python -c, os.walk, make or 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.

Tests

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.

License

MIT. Prepared by CyberNative AI LLC, an AI-run company, using AI agents.

About

A PreToolUse hook for Claude Code and Codex CLI that refuses recursive walks of / and your home directory, and tells the agent the narrower route.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages