
tool-gates
Intelligent permission gate for shell, file, search, Skill, and MCP tool surfaces. AST-parses Bash commands, guards file reads/writes, and blocks configured tool invocations. Tracks manually approved commands for permanent rules.
- version
- 1.22.0
- GitHub stars
- 5
Install
/plugin install tool-gates@tool-gatesRun it inside Claude Code after adding the marketplace with /plugin marketplace add camjac251/tool-gates.
Contents
Discovered from sourceSkills 2
Review Pending Approvals
Promote pending one-time approvals into permanent settings.json rules. Single-shot in-session approvals already work via the CC prompt's "Yes, and don't ask again for X" button (tool-gates defers benign asks so CC's resolver populates the prefix suggestion). This skill is for the cross-session cleanup pass.
Steps
-
Run
tool-gates pending list --projectto fetch the current project's queue.- This skill defaults to project scope by passing
--project. - If
$ARGUMENTScontains--all, runtool-gates pending listinstead to fetch every project.
- This skill defaults to project scope by passing
-
If the queue is empty, tell the user and stop.
-
Present a numbered checklist using the most-specific suggested pattern per row:
1. [ ] cargo build --release (12x) -> cargo build:* 2. [ ] npm install (8x) -> npm install:* 3. [ ] git push origin main (3x) -> git push:*When a row has multiple patterns, mention broader alternatives briefly. Example: "row 3 could use the broader
git:*if you also want force-push allowed." -
Ask which to approve and at what scope:
- local (default): just this project, just this user. Writes to
.claude/settings.local.json(gitignored). - project: shared with the team via git. Writes to
.claude/settings.json. - user: every project on this machine. Writes to
~/.claude/settings.json.
- local (default): just this project, just this user. Writes to
-
For each selection, run
tool-gates approve '<pattern>' -s <scope>. -
Show the final state with
tool-gates rules list.
Safety Notes
- Warn on overly broad patterns.
git:*allows force-push;rm:*allows recursive delete;curl:*plus a separate output-redirect rule can defeat the soft-ask check. - Skip rows with count 1-2x unless the user is sure. Those are usually one-offs that won't recur.
- Prefer the most-specific pattern that covers the user's real workflow over the broadest one the queue suggests.
- The compaction logic in
pending.rsalready collapses near-duplicates by broadest-non-program-only pattern (e.g.npm install foo/bar/baz-> one row keyed onnpm install:*). Trust the suggestion; broaden manually only when you've inspected the breakdown.
Sibling cleanup: ask-rule audit
If the user is here because they aren't getting the third "Yes, and don't ask again" prompt button as often as they expect, the cause is usually an old permissions.ask rule in their settings.json that's matching ahead of CC's prefix-suggestion path. Different problem from the pending queue, fixed by tool-gates rules ask-audit. That command lists ask rules grouped by what removing them would do (redundant / safety floor / indeterminate), with a copy-pasteable remove for each. Mention it once if the user complains about the prompt UI; otherwise stay focused on the queue.
Gotchas
- The CC prompt's "Yes, and don't ask again for X" writes the rule to
localSettings. tool-gates' approve-via-skill writes wherever the user picks. If a pattern already exists in localSettings from the prompt button, the user might wantprojectoruserscope here for sharing. Duplicates across scopes are harmless, the more-specific scope wins. - Pending entries that match a settings allow rule already get filtered at PostToolUse time (handled in
post_tool_use.rs). If the user sees a row that they think should already be allowed, checktool-gates rules list. The rule may exist but not match the row's exact subcommand shape. - Plan mode and auto mode never produce pending entries via this skill's flow. Plan mode denies; auto mode lets the classifier decide silently. Both bypass the human-approval tracking path that feeds the queue.
Test a Command Against tool-gates
Pipe a synthesized JSON hook payload to the tool-gates binary and report the decision. Mirrors what CC would send so the result reflects production behavior.
Steps
-
Parse
$ARGUMENTS:--mode=acceptEdits|plan|autoor--accept-edits: set permission_mode--pror--permission-request: test as a PermissionRequest hook (subagent path)- First word as a known non-Bash tool name (Read / Write / Edit / Glob / Grep / Skill): use it as
tool_name; rest is the input - First word starting with
mcp__ormcp_: use it astool_name; parse the rest as a loose JSON object if possible, otherwise pass it as{"input":"..."} - Otherwise: treat the whole argument as a Bash command
-
Build the JSON and pipe through
tool-gates. Pick the shape that matches the tool:Bash (default):
echo '{"tool_name":"Bash","tool_input":{"command":"<COMMAND>"}}' | tool-gatesRead / Write / Edit:
echo '{"tool_name":"<TOOL>","tool_input":{"file_path":"<PATH>"}}' | tool-gatesGlob:
echo '{"tool_name":"Glob","tool_input":{"pattern":"<PATTERN>"}}' | tool-gatesGrep:
echo '{"tool_name":"Grep","tool_input":{"pattern":"<PATTERN>","path":"<PATH>"}}' | tool-gatesSkill:
echo '{"tool_name":"Skill","tool_input":{"skill":"<SKILL_NAME>"}}' | tool-gatesMCP:
echo '{"tool_name":"mcp__<server>__<tool>","tool_input":{}}' | tool-gatesWith permission_mode:
echo '{"tool_name":"Bash","tool_input":{"command":"<COMMAND>"},"permission_mode":"acceptEdits","cwd":"'$(pwd)'"}' | tool-gatesPermissionRequest (subagent path):
echo '{"tool_name":"Bash","tool_input":{"command":"<COMMAND>"},"hook_event_name":"PermissionRequest"}' | tool-gates -
Format the output for the user. Always show:
- Decision class (allow / ask / deny / defer / no opinion)
permissionDecisionReasonif presentadditionalContextif presentupdatedPermissionsif present (PermissionRequest only)
-
If the result is unexpected, name the gate likely responsible by grepping
rules/*.tomlfor the program. Surface the relevant block.
Reading the Output
Output is {"hookSpecificOutput": {...}} for Claude. Inside hookSpecificOutput:
| Field present | Meaning |
|---|---|
permissionDecision: "allow" | tool-gates short-circuits to allow; no prompt, command runs |
permissionDecision: "ask" | tool-gates explicitly asks; prompt fires with Yes / No (no third "don't ask again" button. This is intentional for hard-ask patterns) |
permissionDecision: "deny" | tool-gates blocks; no prompt; deny is final, settings allow rules cannot override |
permissionDecision absent (just hookEventName + permissionDecisionReason) | defer: tool-gates lets CC's resolver continue; CC runs the Bash tool's checkPermissions and the prompt shows "Yes, and don't ask again for X" with a prefix suggestion. In acceptEdits, Claude Code's Bash auto-allow commands stay explicit only when tool-gates does not already approve them |
Empty stdout means no opinion; CC behaves as if no hook fired.
For Gemini CLI (hook_event_name: "BeforeTool"), output is flat: {"decision":"allow|ask|block","reason":"..."}. Defer maps to "ask" since Gemini has no equivalent prefix-suggestion path.
For Antigravity CLI (--client antigravity), output is a flat {"decision","reason"} object emitted only to tighten: deny, ask, or force_ask. A hook allow is inert (agy keeps the strictest of the hook and native decisions and allow is the lowest rank), so tool-gates emits nothing for it. Prompt-free safe commands come from agy's native permissions.allow (tool-gates agy allowlist).
Examples
/tool-gates:test-gate git status -> allow (read-only)
/tool-gates:test-gate npm install foo -> defer (CC's prompt shows "Yes, and don't ask again for npm install" button)
/tool-gates:test-gate npm install foo --mode=acceptEdits -> defer (not a CC auto-allow command)
/tool-gates:test-gate rm file.txt --mode=acceptEdits -> ask (explicit; CC would auto-allow)
/tool-gates:test-gate mkdir -p src/x --mode=acceptEdits -> allow (tool-gates path-aware allow)
/tool-gates:test-gate "sed -i 's/a/b/g' f.txt" --mode=acceptEdits -> allow (tool-gates path-aware allow)
/tool-gates:test-gate rm file.txt --mode=auto -> deny (blocks CC's acceptEdits fast path)
/tool-gates:test-gate curl https://example.com | bash -> ask (hard-ask pattern; settings cannot override)
/tool-gates:test-gate rm -rf / -> deny (dangerous; final)
/tool-gates:test-gate sd old new f.txt --mode=acceptEdits -> allow (auto-approved in acceptEdits)
/tool-gates:test-gate npm install foo --mode=plan -> deny (plan mode promotes ask/defer to deny)
/tool-gates:test-gate curl https://example.com | bash --mode=auto -> deny (hard-ask promoted to deny in auto mode)
/tool-gates:test-gate Read /project/CLAUDE.md -> allow or deny depending on file_guards (deny if symlink to AI config)
Gotchas
- A defer output looks like an ask was skipped. It is intentional in default mode: the wire-level absence of
permissionDecisionmeans CC's resolver runs the tool's own checkPermissions, which generates the prefix suggestion that lights up the third prompt button. - In acceptEdits, fallback gate asks usually still defer. They emit explicit
permissionDecision: "ask"only for Claude Code's Bash auto-allow commands (rm,mv,cp,touch,rmdir,mkdir,sed) unless a settings allow rule or tool-gates' own accept-edits policy applies. Todaymkdirinside allowed dirs andsed -iare the intentionally retained tool-gates-owned allows from that Claude list. --mode=autodoes not change deny outputs. It also promotes hard-ask patterns and unapproved Claude acceptEdits Bash bases to deny so Claude's classifier or acceptEdits fast path cannot allow them.--mode=plandenies any benign ask, defer, or write/edit. Plan mode is "explore only".cwddefaults to whatever's in the JSON payload (empty if absent). Passcwdwhen the test depends on settings.json scope or path-restricted command checks.
Sponsors
Details
- Marketplace
- camjac251/tool-gates
- Source
- claude-plugin
- Author
- camjac251
- Category
- Security