The Write Your Permission Mode Never Stops — Auditing an Agent-Scoped PreToolUse Gate Across 150 Payloads

Rewriting It to Fail Closed

Three decisions.

1. Return judgments as exit 0 plus JSON on stdout. Claude Code only parses JSON on exit 0; exit 2 causes JSON to be ignored. Pick one mechanism and stay with it.
2. Exit 2 on unexpected exceptions. Exit 1 fails open. "If I cannot decide, stop" should be expressed in code, not in a comment.
3. Escalate incomplete input to ask, not deny. Rejecting every write with unclear provenance stalls legitimate work. Handing it to a human was the right landing spot.

Here is the rewrite, ready to drop into .claude/hooks/agent_write_gate.py.

#!/usr/bin/env python3
"""PreToolUse: scope subagent writes to per-agent_type allowed roots.
 
Designed around Claude Code's contract:
  - Return decisions as exit 0 + JSON on stdout (never mixed with exit 2)
  - Exit 2 on unexpected exceptions (exit 1 is a non-blocking error and fails open)
  - agent_id / agent_type are optional fields present only inside a subagent
"""
import json
import os
import sys
 
WRITE_TOOLS = {"Write", "Edit", "NotebookEdit"}
 
# agent_type -> roots this agent may write to (absolute paths)
ALLOWED_ROOTS = {
    "doc-writer":         ["/repo/content"],
    "test-runner":        ["/repo/tests", "/repo/fixtures"],
    "my-plugin:reviewer": [],          # read-only: no writes at all
}
DEFAULT_ROOTS = []                      # unknown agent_type writes nothing
 
 
def decide(payload):
    """Return (permissionDecision, reason). None means 'no opinion'."""
    tool = payload.get("tool_name", "")
    if tool not in WRITE_TOOLS:
        return None, None
 
    agent_type = payload.get("agent_type")
    if agent_type is None:
        # Main-thread write. Defer to normal permission evaluation.
        return None, None
 
    tool_input = payload.get("tool_input") or {}
    path = tool_input.get("file_path")
    if not path:
        # Write with unclear provenance. Escalate rather than wave through.
        return "ask", f"{agent_type} issued {tool} without a file_path"
 
    path = os.path.normpath(path)
    roots = ALLOWED_ROOTS.get(agent_type, DEFAULT_ROOTS)
    for r in roots:
        r = os.path.normpath(r)
        if path == r or path.startswith(r + os.sep):
            return "allow", f"{agent_type} is writing inside its allowed root {r}"
 
    return "deny", (
        f"{agent_type} may only write to {roots or '(nothing)'}; "
        f"{path} is out of scope, so the write was stopped"
    )
 
 
def main():
    try:
        payload = json.load(sys.stdin)
        decision, reason = decide(payload)
    except Exception as e:
        # Fail closed. Exit 1 would be a non-blocking error and the write proceeds.
        print(f"agent-write-gate could not decide: {e!r}", file=sys.stderr)
        sys.exit(2)
 
    if decision is None:
        sys.exit(0)                     # No JSON emitted -> normal evaluation
 
    json.dump({
        "hookSpecificOutput": {
            "hookEventName": "PreToolUse",
            "permissionDecision": decision,
            "permissionDecisionReason": reason,
        }
    }, sys.stdout)
    sys.exit(0)
 
 
if __name__ == "__main__":
    main()

Putting hookEventName inside hookSpecificOutput is easy to forget; at the top level the output is not interpreted. permissionDecisionReason is also fed back to the model, so wording it so the model does not retry saves a pointless round trip.

Rerunning the same 150 payloads:

The 54 pass-throughs are gone. Twenty-four now reach a human as ask, and 30 are explicitly deferred to normal permission evaluation as main-thread calls. Both "pass," but intentional delegation and accidental side effect are not the same thing.

I also fed it deliberately broken input.

Prefix Matching Was Widening the Allowlist

There is a second hole I would not have found without measuring: startswith on the allowed root.

I granted doc-writer access to /repo/content. Here is what that actually permits.

Any string beginning with /repo/content includes /repo/content-archive/ and /repo/contentious.txt. Add one sibling directory and territory you never intended silently joins the allowlist. The fix is to make the separator explicit: path == r or path.startswith(r + os.sep).

For .. segments, the docs state that Claude Code expands ~ and relative paths before hooks run, so in practice you receive a normalized absolute path. Treat os.path.normpath as defense in depth — though it does matter when you unit-test the hook locally, as I was doing here.

On Windows there is one more layer. The docs note that file_path arrives with backslash separators even when your hook runs under Git Bash where $PWD looks like /c/project, so a comparison written with forward slashes such as a /src/ check never matches. Path comparison has to be platform-aware.

Measure the Cost Before You Wire It Up

PreToolUse fires every time Claude calls a tool. In a write-heavy pipeline, the hook's own runtime accumulates. Here are 1,000 invocations against an identical payload.

Attributing that cost: python3 -c pass alone has a p50 of 16.8 ms. The decision logic is roughly 5 ms; the rest is interpreter startup. Twenty-two seconds per thousand writes was acceptable for my pipeline, but if you need it tighter, the room is in moving the decision into a single binary or a resident process. The worst outcome would have been to skip hooks entirely on a vague sense that they are slow, without ever taking the number.

Wiring goes in .claude/settings.json.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit|NotebookEdit",
        "hooks": [
          {
            "type": "command",
            "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/hooks/agent_write_gate.py\"",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

The default timeout for command hooks is 600 seconds, which is far too long for a policy gate. Against a measured p99 of 23.7 ms, ten seconds leaves generous headroom.

Two wiring behaviors are worth internalizing. First, all matching hooks run in parallel, and deny takes priority over defer, which takes priority over ask, which takes priority over allow. If any hook returns deny, the operation is blocked no matter what the others say — which means you can add gates incrementally without them fighting each other.

Second, PreToolUse only fires when Claude calls a tool. Files you pull in with @ in a prompt are inserted while building the prompt, with no tool call, so no hook fires — including hooks matching Read. To block paths from @ references, use a Read deny rule instead of a hook.

Two Production Gotchas I Hit

Right after wiring it up, the gate appeared to say nothing for a while. The cause is straightforward: stderr from a hook that exits 0 goes to the debug log only. It never reaches the transcript and Claude never sees it. Sprinkling print(..., file=sys.stderr) for debugging produces nothing on screen. Until I understood that, I could not tell whether the gate was failing to fire or simply failing to log. The workaround is to append your decisions to your own file, or enable debug logging.

Second, a hook process inherits the parent environment — with one exception. Claude Code strips OTEL_* exporter variables from every subprocess it spawns, including hooks. If you planned to ship decisions straight to telemetry, that single detail makes your instrumentation silently go nowhere. For correlation, log the prompt_id from the common input fields yourself; it matches the prompt.id attribute on OpenTelemetry events, so you can join them afterward.

What Remains Unverified

One honest caveat.

What I measured here is how my gate script behaves against the PreToolUse input contract. For turn-by-turn (Task) subagents, the docs explicitly state that agent_id and agent_type are delivered, so it is reasonable to rely on this gate there.

Whether the same hook fires inside the isolated workflow runtime is not something I found documented. If workflows are the core of your autonomous setup, verify that in your own environment before depending on it. Verification is cheap: add a few lines at the top of main() that append the received payload to a log file, run one workflow, and check whether any PreToolUse entries carrying an agent_id appear. If none do, that gate does not exist as far as that runtime is concerned.

What to Do Next

If you run any kind of autonomous pipeline, there is one thing worth checking today.

Pipe deliberately malformed JSON into your existing PreToolUse hook. If the exit code is anything other than 2, that hook is not functioning as a policy gate. Before it can decide wrongly, it is already letting things through undecided.

I spent a long stretch believing I had drawn a boundary. The string in a settings file and the behavior that actually runs are separate things. Running 150 payloads took two short scripts and a few minutes — a reasonable price for finding out which one you have.

References

• Hooks reference — Claude Code Docs
• Intercept and control agent behavior with hooks — Claude Code Docs
• Configure permissions — Claude Code Docs