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-gates

Run it inside Claude Code after adding the marketplace with /plugin marketplace add camjac251/tool-gates.

Contents

Discovered from source

Skills 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

  1. Run tool-gates pending list --project to fetch the current project's queue.

    • This skill defaults to project scope by passing --project.
    • If $ARGUMENTS contains --all, run tool-gates pending list instead to fetch every project.
  2. If the queue is empty, tell the user and stop.

  3. 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."

  4. 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.
  5. For each selection, run tool-gates approve '<pattern>' -s <scope>.

  6. 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.rs already collapses near-duplicates by broadest-non-program-only pattern (e.g. npm install foo/bar/baz -> one row keyed on npm 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 want project or user scope 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, check tool-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

  1. Parse $ARGUMENTS:

    • --mode=acceptEdits|plan|auto or --accept-edits: set permission_mode
    • --pr or --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__ or mcp_: use it as tool_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
  2. 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-gates
    

    Read / Write / Edit:

    echo '{"tool_name":"<TOOL>","tool_input":{"file_path":"<PATH>"}}' | tool-gates
    

    Glob:

    echo '{"tool_name":"Glob","tool_input":{"pattern":"<PATTERN>"}}' | tool-gates
    

    Grep:

    echo '{"tool_name":"Grep","tool_input":{"pattern":"<PATTERN>","path":"<PATH>"}}' | tool-gates
    

    Skill:

    echo '{"tool_name":"Skill","tool_input":{"skill":"<SKILL_NAME>"}}' | tool-gates
    

    MCP:

    echo '{"tool_name":"mcp__<server>__<tool>","tool_input":{}}' | tool-gates
    

    With permission_mode:

    echo '{"tool_name":"Bash","tool_input":{"command":"<COMMAND>"},"permission_mode":"acceptEdits","cwd":"'$(pwd)'"}' | tool-gates
    

    PermissionRequest (subagent path):

    echo '{"tool_name":"Bash","tool_input":{"command":"<COMMAND>"},"hook_event_name":"PermissionRequest"}' | tool-gates
    
  3. Format the output for the user. Always show:

    • Decision class (allow / ask / deny / defer / no opinion)
    • permissionDecisionReason if present
    • additionalContext if present
    • updatedPermissions if present (PermissionRequest only)
  4. If the result is unexpected, name the gate likely responsible by grepping rules/*.toml for the program. Surface the relevant block.

Reading the Output

Output is {"hookSpecificOutput": {...}} for Claude. Inside hookSpecificOutput:

Field presentMeaning
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 permissionDecision means 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. Today mkdir inside allowed dirs and sed -i are the intentionally retained tool-gates-owned allows from that Claude list.
  • --mode=auto does 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=plan denies any benign ask, defer, or write/edit. Plan mode is "explore only".
  • cwd defaults to whatever's in the JSON payload (empty if absent). Pass cwd when 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