From e3407ba4ed0667416a479c00a195c23a1ead739b Mon Sep 17 00:00:00 2001 From: AsafMazuz1 <33402080+AsafMazuz1@users.noreply.github.com> Date: Sat, 19 Sep 2026 21:58:42 +0000 Subject: [PATCH] Add toolgate Claude Code / MCP Jev firewall --- README.md | 1 + community/projects/tools/README.md | 1 + community/projects/tools/toolgate.md | 65 ++++++++++++++++++++++++++++ 3 files changed, 67 insertions(+) create mode 100644 community/projects/tools/toolgate.md diff --git a/README.md b/README.md index 5183342..b133c1e 100644 --- a/README.md +++ b/README.md @@ -162,6 +162,7 @@ The [independent model research](community/projects/tools/README.md#independent- - [Stanley Code](https://github.com/devagrawal09/stanley-code) - Routes coding requests into bounded Jev review and triage workflows, with trusted repository extensions and an optional Pi coding-agent fallback. [Project guide](community/projects/tools/stanley-code.md). - [Supercov](https://github.com/supercorp-ai/supercov) - Code quality and test coverage for coding agents: Jev scores each source file so the agent knows what to fix first. [Project guide](community/projects/tools/supercov.md). - [Testimonial miner](https://github.com/AppitStudio/testimonial-miner) - Python CLI that finds quotable user praise in Gmail mailboxes with one Jev request per email (message kind, app, praise quality, and a Noul per sentence) and stores verbatim quotes for review; requires a TypeSafe key and Google app passwords, and sends cleaned email text to TypeSafe. [Project guide](community/projects/tools/testimonial-miner.md). +- [toolgate](https://github.com/RiskAverseTech/toolgate) - Open Claude Code PreToolUse and MCP tool-call firewall with static rules, TypeSafe Jev judgments, YAML policy, and a local audit log. [Project guide](community/projects/tools/toolgate.md). - [TypeSafe Mario](https://github.com/fhshaik/typesafe-mario) - Selects emulator controller inputs with Jev from structured Mario telemetry; includes a synthetic state demo, with upstream licensing unspecified. [Project guide](community/projects/tools/typesafe-mario.md). - [TypeSafe MCP](https://github.com/itsmostafa/typesafe-mcp) - Exposes typed Jev questions to MCP clients and pi, preserving provider responses with configurable direct or OpenRouter access. [Project guide](community/projects/tools/typesafe-mcp.md). - [typesafe-computer-use](https://github.com/awlevin/typesafe-computer-use) - Combines local OCR and Accessibility observations with Jev decisions to operate macOS, with an optional writing model. [Project guide](community/projects/tools/typesafe-computer-use.md). diff --git a/community/projects/tools/README.md b/community/projects/tools/README.md index eac3137..8658a81 100644 --- a/community/projects/tools/README.md +++ b/community/projects/tools/README.md @@ -61,6 +61,7 @@ See the [computer-use guide](../../../docs/computer-use.md) for a comparison, fo | [Skillbox](skillbox.md) | Share versioned agent skills and use optional Jev scores to recommend authorized skills for a task. | TypeScript / Bun / PostgreSQL · skill library, MCP and CLI | | [Stanley Code](stanley-code.md) | Review code changes, triage failures, and extend Jev workflows; optional Pi delegation can edit the repository. | TypeScript · source-built CLI and workflow runtime | | [Supercov](supercov.md) | Code quality and test coverage for coding agents: Jev scores each source file so the agent knows what to fix first. | Rust · CLI via npm, Homebrew, Go or crates.io | +| [toolgate](toolgate.md) | Gate Claude Code and MCP tool calls with static rules plus TypeSafe Jev risk judgments and a local audit log. | TypeScript · CLI, Claude Code hook and MCP proxy | ## Games and simulation diff --git a/community/projects/tools/toolgate.md b/community/projects/tools/toolgate.md new file mode 100644 index 0000000..0aff46b --- /dev/null +++ b/community/projects/tools/toolgate.md @@ -0,0 +1,65 @@ +# toolgate + +[All projects](../README.md) · [Developer tools](README.md#developer-tools) + +Open tool-call firewall for AI agents: static rules first, then TypeSafe Jev risk judgments, shipping as a Claude Code `PreToolUse` hook and an MCP stdio proxy. + +| At a glance | Details | +| --- | --- | +| Source | [Source](https://github.com/RiskAverseTech/toolgate) | +| Maintainer | [RiskAverseTech](https://github.com/RiskAverseTech) (Risk Averse Technology Company LLC). Independently curated; this entry is not an upstream submission or endorsement. | +| Format | TypeScript npm package `@riskaverse/toolgate` **0.7.1** — CLI (`toolgate`), Claude Code hook, and MCP proxy. | +| Requirements | Node.js ≥ 20. Live gating needs `TYPESAFE_API_KEY` or `AI_GATEWAY_API_KEY`. Offline tests use a deterministic `mock` backend. Policy lives in `~/.toolgate/toolgate.yaml` (never the project tree). | +| License | [MIT](https://github.com/RiskAverseTech/toolgate/blob/8b38a2faf620d7923505f3c546ebc0c79ca87f1f/LICENSE). | + +## When to use + +Use it when you want an auditable allow/ask/deny layer beside Claude Code's own permissions (including auto mode), or when wrapping any MCP server so `tools/call` requests are gated before they reach the server. Prefer static-only hooks when you do not want provider calls. + +It complements catalogued Pi guards ([pi-jev](pi-jev.md), [pi-jev-sentinel](pi-jev-sentinel.md), [pi-warden](pi-warden.md)) rather than replacing them: toolgate targets Claude Code hooks and MCP clients with YAML policy and a local audit log. + +## How it works + +1. **Static rules** (user rules, then built-ins such as `rm -rf /` deny and `curl … | sh` ask) match first with no model call. +2. Tools outside `gated_tools` pass through. +3. Remaining calls go to the decision backend—TypeSafe direct (`https://api.typesafe.ai/v1/systemone`, default `jev-latest`) or Vercel AI Gateway—with parallel risk/context questions; thresholds map probabilities to deny / ask / allow, with authorization softening rules documented upstream. +4. Unattended Claude permission modes can escalate ask→deny by default. Model failures follow `fail_mode` (`ask` default). Internal errors never silently allow. + +The [TypeSafe backend](https://github.com/RiskAverseTech/toolgate/blob/8b38a2faf620d7923505f3c546ebc0c79ca87f1f/src/backends/typesafe.ts) and [engine](https://github.com/RiskAverseTech/toolgate/blob/8b38a2faf620d7923505f3c546ebc0c79ca87f1f/src/engine.ts) implement this path. Decisions append to `~/.toolgate/audit.jsonl` with redaction heuristics. + +## Get started + +```sh +npm install -g @riskaverse/toolgate +export TYPESAFE_API_KEY=... +toolgate init # writes policy + hook into ~/.claude/settings.json and runs doctor +``` + +Or inspect the reviewed commit: + +```sh +git clone https://github.com/RiskAverseTech/toolgate.git +cd toolgate +git checkout 8b38a2faf620d7923505f3c546ebc0c79ca87f1f +npm ci --ignore-scripts +npm run build +npm test +``` + +`toolgate check --backend mock …` exercises offline heuristics without a key. Live `doctor` / hook paths can make a billable verdict. This listing did not install into Claude Code or wrap a live MCP server. + +## Examples and demos + +- [`examples/claude-settings.json`](https://github.com/RiskAverseTech/toolgate/blob/8b38a2faf620d7923505f3c546ebc0c79ca87f1f/examples/claude-settings.json) and [`examples/toolgate.yaml`](https://github.com/RiskAverseTech/toolgate/blob/8b38a2faf620d7923505f3c546ebc0c79ca87f1f/examples/toolgate.yaml). +- [test/](https://github.com/RiskAverseTech/toolgate/tree/8b38a2faf620d7923505f3c546ebc0c79ca87f1f/test): policy, engine, hook, install, MCP, and TypeSafe client tests (mock backend for offline paths). +- Upstream `docs/challenge-set-*.md` reports are maintainer challenge results, not catalog-run evaluations. + +## Limits and data handling + +On the model path, tool name/input (redacted/truncated), cwd, permission mode, and limited transcript prompts can leave the machine to TypeSafe or the AI Gateway. Static matches send nothing. Redaction is heuristic. `allow` remains advisory under Claude Code's own deny/confirm lists. toolgate is defense in depth, not a sandbox. Thresholds and challenge write-ups are not measured guarantees for your workload. + +## Review and maintenance + +Reviewed on **2026-09-20** at [commit 8b38a2f](https://github.com/RiskAverseTech/toolgate/tree/8b38a2faf620d7923505f3c546ebc0c79ca87f1f): `@riskaverse/toolgate` **0.7.1**, MIT. AI-assisted source review of engine, backends, hook/MCP paths, README, and license. On Node.js 22.19.0, **`npm run build` then `npm test`: 165 passed** (6 files). An initial `npm test` before build failed 8 CLI e2e cases missing `dist/cli.js`—build-first is required. No live TypeSafe/Gateway calls or Claude Code install were performed. + +Related: [pi-jev-sentinel](pi-jev-sentinel.md), [pi-jev](pi-jev.md), [pi-warden](pi-warden.md).