opus-shield

Opus Shield

AI-powered permission gatekeeper for Claude Code. Routes permission requests to Opus 4.5 for context-aware auto-approval, with an instant safety net for dangerous patterns.

Why not type: "prompt"?

Other approaches use Claude Code's built-in type: "prompt" hooks for permission evaluation. This doesn't work. Due to a known issue, type: "prompt" hooks acknowledge the permission but the dialog still appears — defeating the purpose.

Opus Shield uses type: "command" with hookSpecificOutput JSON, which is the only approach that actually suppresses the permission dialog.

How it works

Permission request arrives
│
├── In your AllowList? → auto-approved instantly (hook never fires)
│
└── Not in AllowList? → Opus Shield fires
    │
    ├── DENY safety net (~40ms)
    │   Instant regex matching for dangerous patterns:
    │   • rm -rf /, sudo, chmod 777
    │   • Pipe-to-shell (curl | bash)
    │   • Data exfiltration (pipe to curl/wget/ssh)
    │   • System path edits (/etc, /usr, /bin)
    │   • Secrets access (.ssh, .aws, .env)
    │   • Internal IP access (localhost, 127.0.0.1)
    │
    └── Opus 4.5 review (~2-4s)
        Context-aware AI evaluation via AWS Bedrock or Anthropic API.
        Reads your session transcript to understand what you're working on.
        Returns ALLOW or DENY based on whether the action makes sense.

Coverage

Tool	What's checked
Bash	Command content, working directory, description
Edit/Write	File path (blocks system paths, secrets, .env)
WebFetch	URL, domain (blocks internal IPs, auth tokens in URLs)

Prerequisites

• Claude Code 1.0.33+
• jq installed (brew install jq)
• aws CLI installed (for Bedrock backend) or curl (for Anthropic API)
• AWS Bedrock access to Claude Opus 4.5, or an Anthropic API key

Installation

From marketplace

/plugin marketplace add sanchay/opus-shield
/plugin install opus-shield@sanchay

Manual install

git clone https://github.com/sanchay/opus-shield.git
claude --plugin-dir ./opus-shield

Setup

After installing, run the setup:

bash opus-shield/src/setup.sh

This copies the hook script to ~/.opus-shield/ and creates a credential file.

Edit ~/.opus-shield/.env with your credentials:

Option A — AWS Bedrock (recommended):

AWS_REGION=us-east-1
AWS_ACCESS_KEY_ID=your-key
AWS_SECRET_ACCESS_KEY=your-secret

Option B — Anthropic API:

ANTHROPIC_API_KEY=sk-ant-...

Restart Claude Code for hooks to take effect.

Recommended: Expand your AllowList

Opus Shield works best when paired with a generous AllowList. Safe commands in the AllowList are auto-approved instantly (0ms) and never fire the hook. Only unknown/risky commands reach Opus Shield.

Add this to your ~/.claude/settings.json:

{
  "permissions": {
    "allow": [
      "Read", "Glob", "Grep", "Task", "WebSearch",
      "Bash(git:*)", "Bash(npm:*)", "Bash(pnpm:*)", "Bash(yarn:*)",
      "Bash(npx:*)", "Bash(node:*)", "Bash(tsc:*)", "Bash(tsx:*)",
      "Bash(python3:*)", "Bash(biome:*)", "Bash(eslint:*)",
      "Bash(prettier:*)", "Bash(jest:*)", "Bash(vitest:*)",
      "Bash(ls:*)", "Bash(cat:*)", "Bash(grep:*)", "Bash(find:*)",
      "Bash(head:*)", "Bash(tail:*)", "Bash(wc:*)", "Bash(mkdir:*)",
      "Bash(touch:*)", "Bash(cp:*)", "Bash(mv:*)", "Bash(diff:*)",
      "Bash(sort:*)", "Bash(jq:*)", "Bash(echo:*)", "Bash(pwd:*)",
      "Bash(which:*)", "Bash(file:*)", "Bash(stat:*)"
    ]
  }
}

Commands NOT in this list (like curl, rm, docker, lsof) will be evaluated by Opus Shield.

Performance

Path	Latency	When
AllowList	0ms	Safe commands (git, npm, ls, etc.)
DENY safety net	~40ms	Dangerous patterns (sudo, rm -rf /, etc.)
Opus L2	2-4s	Everything else (curl, docker, unknown commands)

Gotcha: settings.local.json

Claude Code accumulates user-approved commands in .claude/settings.local.json (project-level). These bypass hooks entirely. If a command isn't hitting Opus Shield, check this file and clean out accumulated permissions.

Comparison with other approaches

Feature	Opus Shield	type: "prompt" plugins	AllowList only
Actually auto-approves	Yes	No (dialog still shows)	Yes
Context-aware	Yes (reads session)	Partial	No
Instant dangerous blocks	Yes (DENY net)	No	No
Covers Edit/Write/WebFetch	Yes	Usually Bash only	N/A
Latency for unknown commands	2-4s	N/A (broken)	N/A (shows dialog)

Debugging

Check if hooks are loaded:

/hooks

Enable debug mode to see hook execution:

claude --debug

Check the debug log for PermissionRequest entries to verify the hook is firing.

License

MIT