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. Exit 2 blocks even when JSON is printed, and the JSON cannot override the block. Mixing "stop" with "return a decision as JSON" makes intent hard to read, so 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, I could not confirm from the official docs whether the file_path that reaches the hook is already normalized. So I keep os.path.normpath as a required step rather than defense in depth. It is the reason /repo/content/../src/pricing.ts is denied in the table above.

On Windows, separators are a further concern. I did not measure on Windows, so log the file_path your hook actually receives once and check which separator it uses. A comparison that assumes forward slashes will not match backslash-separated input.

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, how multiple matching hooks combine. I could not find the precedence among deny / ask / allow / defer stated in the official docs. If you stack several gates, first run the case where one returns deny and another returns allow, and see what happens. The more gates you stack, the more that verified fact matters.

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.

Self-Test With Broken Input Every Time

Failing closed is not a one-time write. Someone edits decide(), the try range shifts, and the hook quietly drifts back to exit 1. So I put a small test next to the hook that feeds broken input and checks exit codes.

# gate_selftest.py — 壊れた入力でもフックが exit 2 で落ちるかを確認する
import subprocess
import sys
 
GATE = sys.argv[1] if len(sys.argv) > 1 else ".claude/hooks/agent_write_gate.py"
 
# (名前, stdin, 期待する終了コード)
CASES = [
    ("空入力",         "",                                   2),
    ("JSON ではない",   "not json at all",                    2),
    ("配列が来た",      "[]",                                 2),
    ("tool_input が null",
     '{"tool_name":"Write","agent_type":"doc-writer","tool_input":null}', 0),
    ("範囲外の書き込み",
     '{"tool_name":"Write","agent_type":"doc-writer",'
     '"tool_input":{"file_path":"/repo/content-archive/a.mdx"}}', 0),
]
 
bad = 0
for name, stdin, want in CASES:
    r = subprocess.run([sys.executable, GATE], input=stdin,
                       capture_output=True, text=True)
    ok = r.returncode == want
    bad += not ok
    print(f"{'OK ' if ok else 'NG '} {name}: exit {r.returncode} (期待 {want})")
sys.exit(1 if bad else 0)

Results in my environment:

The last two are exit 0 because decisions travel as JSON. The expected-value column carries the meaning so that nobody reads "exit 0" as "allowed". Add this test to CI or a pre-commit hook and a silent drift back to fail-open is caught the moment you change the file.

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. The self-test above is a few dozen lines and finishes in seconds. Run it against your own hook first; any case that does not return 2 is the next thing to fix.

References

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