toolgate

toolgate puts a decision model in front of every tool call Claude Code makes. Before a Bash command, a file write or an MCP call runs, it asks TypeSafe’s Jev seven risk questions and turns the probabilities into allow, ask or deny, and it writes every verdict, with its probabilities, to a log on your machine. The engine is the toolgate CLI from npm and the decisions come from a hosted model, so read How it works before you install.

What it does

• Seven risk questions. Is the call destructive? Does it send local data out? Does it escalate privileges or touch security config? Does it print, save or commit a credential? Is it outside the current task? Does it break an explicit “only” or “do not” in your instructions? Does it make a choice you said you would make yourself? The last one never goes above ask.
• One mitigator. Jev is also asked whether your task called for the action. If it did, the verdict softens one step, so a vercel deploy --prod you asked for becomes an ask instead of a deny.
• Floors. Secret exposure, broken constraints and reserved choices can never be softened by the task. Off-task alone is capped at ask: a reason to check with you, never a block.
• Static rules first. Built-in rules deny rm -rf on / or ~ and ask before piping curl into sh or editing ~/.claude/settings* or toolgate’s own policy. Your rules run in between, and none of them can lower a built-in deny.
• An action ledger. When the agent writes a file, the same model call that judges the write also records what the file could do if run: read sensitive data, send data out, destroy data, change privileges. The write itself is judged as text. A later bash helper.sh, python x.py or ./x is judged as what the file does, and if it arrives before the write is confirmed, the verdict is at least ask.
• Ask, not allow, on failure. If Jev is unreachable, times out or returns garbage, the default is a confirmation, not a pass.
• Shadow mode records every verdict and enforces nothing, for measuring before you switch it on.
• /toolgate prints the audit summary (ask and deny rates, latency percentiles, tools, recent asks) and this session’s counts. A status line keeps the running allow, ask and deny totals and the last latency.

The same CLI also runs as a classic PreToolUse hook in ~/.claude/settings.json (toolgate init) and as an MCP proxy that wraps any MCP server for Cursor, Claude Desktop or your own agent (toolgate mcp -- <server command>), with one policy and one audit format across all three. Run the mod or the hook, not both: the mod shows a toast when it finds the hook too. For Jev on the questions Claude asks you rather than on its tool calls, see typesafe-mod.

Install

Needs Claude Code 2.1.287 or later, plus npm for the toolgate CLI and an API key for TypeSafe or OpenRouter.

npm install -g @riskaverse/toolgate
claude plugin marketplace add RiskAverseTech/toolgate
claude plugin install toolgate@riskaverse

When the mod is enabled, Claude Code asks for its settings: a TypeSafe key or an OpenRouter key (both kept in secure storage), the toolgate command, and the mode, enforce or shadow. With both keys empty it uses the key toolgate init saved in ~/.toolgate/env, but init also installs the settings.json hook, and you should keep only one of the two.

From the next session every gated call is decided before it runs. A deny shows its reason to you and to the model. An ask goes to whatever your permission mode uses to settle one: the dialog, or Claude Code’s own classifier in auto mode.

Policy lives in ~/.toolgate/toolgate.yaml: thresholds (deny at 0.85, ask at 0.55), your rules, extra questions and trusted_hosts for your own APIs. toolgate never reads policy from the project directory, so a cloned repo cannot loosen it.

How it works

The mod makes no network call itself. It runs the CLI with process.run, and the CLI calls the model.

• session.start registers /toolgate, reads your settings to spot the hook and finds the CLI, also from a desktop-app launch with no shell PATH, by asking the login shells and the usual Homebrew folders. If the CLI is missing, a toast says toolgate is not gating and the mod steps aside: Claude Code’s own rules and modes apply as if it were not installed.
• tool.check pipes each call to toolgate decide: session id, working directory, tool name and input, plus task context read from the session transcript. That context is your latest prompt, the two before it and the session’s opening request. Pasted content is replaced by a marker, and a compaction summary is never treated as your current instruction. If the CLI gives no answer within 20 seconds, the verdict is ask.
• tool.call runs after the tool, and only reports the outcome (done, failed or denied) to toolgate post to settle the ledger. No model call. The mod never sees tool output, so text the agent read cannot argue for its own approval.

Static rules and ungated tools take about 90 ms and send nothing. By default only Bash, Write, Edit, MultiEdit, NotebookEdit, WebFetch, WebSearch and MCP tools are gated; reads never cost a model call. Everything else is one request to the provider your key selects: TypeSafe’s API, OpenRouter’s Decisions API (your OpenRouter key never reaches TypeSafe) or Vercel AI Gateway. It carries the tool name and input, cut at 40,000 characters (for a write, that input includes the text being written), the working directory and your last three prompts, the latest up to 6,000 characters and the other two up to 3,000. Running a ledgered file adds its path and the capability flags. Tool output and files the agent read are never sent. Secrets are redacted first, but the author calls that a courtesy, not a guarantee: it catches shapes such as KEY=, Authorization: and known token prefixes.

It uses no Claude tokens. Your provider bills each model decision, which the author puts at a fraction of a cent and about a second: 1,060 ms at the median over 1,368 calls from a laptop.

On disk: ~/.toolgate/audit.jsonl gets one line per decision (verdict, static rule or model, the probability for each question, latency), redacted and readable only by you. ~/.toolgate/ledger/ holds one file per session with paths and flags, never file contents.

The author’s numbers

The author measures toolgate on declared windows of real sessions. Over three windows (1,369, 1,633 and 318 decisions) the share of calls stopped for an ask fell from 20.9% to 15.6% to 13.8%. In the second, a separate model labeled 407 decisions blind: toolgate was stricter than that reviewer on 245 and looser on 2. The third had zero permissive misses. A frozen test set checks what a regex cannot: text that only mentions an action, such as a commit message, scored at most 0.32 on every axis, and the action itself 0.91 to 0.98.

All of it comes from one machine, the maintainer’s, and the second labeler is a model, not a person. The author’s bar for 1.0 includes three windows at or under 10% ask and audit data from someone else.

Limitations

• It is defense in depth, not a sandbox. Its allow is advisory: Claude Code’s own deny rules and always-confirm list still apply on top.
• Gating exports what you protect: prompts and tool input go to a hosted model. A local backend is on the roadmap, not shipped.
• The ledger covers files written with Write, Edit, MultiEdit or NotebookEdit and then run from Bash. A script created from Bash itself (echo > x.sh, a heredoc, sed -i) is not tracked yet.
• It judges the command as written, not as a shell parses it, so a quoted string that only contains $(cat .env) can be scored as if it ran. The error falls on the strict side.
• The transcript Claude Code gives hooks can lag a turn, so off-task may be judged against your previous prompt.
• The fallback search for the CLI covers macOS and Linux locations. Elsewhere, if a bare toolgate is not found, put the full path in the toolgate command setting.
• It is pre-1.0, and the policy schema and audit format are not frozen yet.