From c1e701ff963373fb7d48cc6a8f8473f6362f8fcc Mon Sep 17 00:00:00 2001 From: Francis Eytan Dortort Date: Tue, 24 Feb 2026 23:58:07 -0500 Subject: [PATCH 1/8] chore: add badges to README Add CI status, npm version, TypeScript, license, Node.js, and Vercel AI SDK badges for at-a-glance project info. Co-Authored-By: Claude Opus 4.6 --- README.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/README.md b/README.md index bfe63ea..6335172 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,12 @@ # ai-tool-guard +[![CI](https://github.com/dortort/ai-tool-guard/actions/workflows/ci.yml/badge.svg)](https://github.com/dortort/ai-tool-guard/actions/workflows/ci.yml) +[![npm version](https://img.shields.io/npm/v/ai-tool-guard)](https://www.npmjs.com/package/ai-tool-guard) +[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue?logo=typescript&logoColor=white)](https://www.typescriptlang.org/) +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) +[![Node.js](https://img.shields.io/badge/Node.js-%E2%89%A520-green?logo=node.js&logoColor=white)](https://nodejs.org/) +[![Vercel AI SDK](https://img.shields.io/badge/Vercel_AI_SDK-%E2%89%A54.0-black?logo=vercel&logoColor=white)](https://sdk.vercel.ai) + Policy enforcement middleware for [Vercel AI SDK](https://sdk.vercel.ai) tool calls. Guards, approvals, argument validation, rate limiting, output filtering, prompt-injection detection, MCP drift detection, and OpenTelemetry observability — as a composable middleware layer around your AI SDK tools. From d1807eeec717057c65f78fd2e5ec189192375887 Mon Sep 17 00:00:00 2001 From: Francis Eytan Dortort Date: Wed, 25 Feb 2026 00:04:41 -0500 Subject: [PATCH 2/8] chore: add Read the Docs badge to README Co-Authored-By: Claude Opus 4.6 --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index 6335172..15a23f6 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,7 @@ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Node.js](https://img.shields.io/badge/Node.js-%E2%89%A520-green?logo=node.js&logoColor=white)](https://nodejs.org/) [![Vercel AI SDK](https://img.shields.io/badge/Vercel_AI_SDK-%E2%89%A54.0-black?logo=vercel&logoColor=white)](https://sdk.vercel.ai) +[![Docs](https://readthedocs.org/projects/ai-tool-guard/badge/?version=latest)](https://ai-tool-guard.readthedocs.io/) Policy enforcement middleware for [Vercel AI SDK](https://sdk.vercel.ai) tool calls. From 569144081519ba237b014a68501231e032165967 Mon Sep 17 00:00:00 2001 From: Francis Eytan Dortort Date: Wed, 25 Feb 2026 01:34:51 -0500 Subject: [PATCH 3/8] chore: add prominent docs link to README body Co-Authored-By: Claude Opus 4.6 --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 15a23f6..29c59d6 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,8 @@ Policy enforcement middleware for [Vercel AI SDK](https://sdk.vercel.ai) tool ca Guards, approvals, argument validation, rate limiting, output filtering, prompt-injection detection, MCP drift detection, and OpenTelemetry observability — as a composable middleware layer around your AI SDK tools. +**[Read the full documentation](https://ai-tool-guard.readthedocs.io/)** + ``` npm install ai-tool-guard ``` From 83a055b2fd3ac73df9ab70158557cdc6e2497109 Mon Sep 17 00:00:00 2001 From: Francis Eytan Dortort Date: Wed, 25 Feb 2026 01:41:06 -0500 Subject: [PATCH 4/8] fix: align architecture diagram top box borders The content row was 1 character wider than the border rows, causing the right edge to render misaligned. Co-Authored-By: Claude Opus 4.6 --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 29c59d6..4b451de 100644 --- a/README.md +++ b/README.md @@ -87,9 +87,9 @@ const result = await generateText({ ## Architecture ``` - ┌─────────────────────────────────────────┐ - │ createToolGuard(options) │ - └──────────────┬──────────────────────────┘ + ┌────────────────────────────────────────┐ + │ createToolGuard(options) │ + └──────────────┬─────────────────────────┘ │ ┌──────────────────────┼──────────────────────┐ │ │ │ From 4d9603eb657297da3712470dd4d7e1c9c055b0e5 Mon Sep 17 00:00:00 2001 From: Francis Eytan Dortort Date: Wed, 25 Feb 2026 01:46:03 -0500 Subject: [PATCH 5/8] fix: convert architecture diagram from ASCII to Mermaid ASCII box-drawing characters render with inconsistent widths across fonts, causing persistent misalignment. Mermaid renders as an SVG on GitHub so it displays correctly everywhere. Co-Authored-By: Claude Opus 4.6 --- README.md | 47 +++++++++++++++++++++++------------------------ 1 file changed, 23 insertions(+), 24 deletions(-) diff --git a/README.md b/README.md index 4b451de..a292a43 100644 --- a/README.md +++ b/README.md @@ -86,30 +86,29 @@ const result = await generateText({ ## Architecture -``` - ┌────────────────────────────────────────┐ - │ createToolGuard(options) │ - └──────────────┬─────────────────────────┘ - │ - ┌──────────────────────┼──────────────────────┐ - │ │ │ - guardTool(name,tool,cfg) guardTools({...}) (config) - │ │ │ - └──────────┬───────────┘ │ - ▼ │ - ┌─── Execution Pipeline ───┐ │ - │ │ │ - │ 1. Injection detection │ ┌──────────┴─────┐ - │ 2. Argument validation │ │ PolicyBackend │ - │ 3. Policy evaluation ◄──┼─────┤ (OPA, Cedar) │ - │ 4. Approval flow │ └────────────────┘ - │ 5. Rate limiting │ - │ 6. Tool execution │ - │ 7. Output filtering │ - │ │ - │ OTel spans emitted │ - │ at each step │ - └──────────────────────────┘ +```mermaid +graph TD + A["createToolGuard(options)"] --> B["guardTool(name, tool, cfg)"] + A --> C["guardTools({...})"] + A --> D["(config)"] + + B --> E["Execution Pipeline"] + C --> E + + D --> F["PolicyBackend\n(OPA, Cedar)"] + + E --> E1["1. Injection detection"] + E1 --> E2["2. Argument validation"] + E2 --> E3["3. Policy evaluation"] + E3 --> E4["4. Approval flow"] + E4 --> E5["5. Rate limiting"] + E5 --> E6["6. Tool execution"] + E6 --> E7["7. Output filtering"] + + F -.-> E3 + + style E fill:#f0f0f0,stroke:#333 + style F fill:#f0f0f0,stroke:#333 ``` ## API reference From d0ae91bf3548f49b073d0d44180e780bb9c83717 Mon Sep 17 00:00:00 2001 From: Francis Eytan Dortort Date: Wed, 25 Feb 2026 01:48:08 -0500 Subject: [PATCH 6/8] fix: use
instead of \n for Mermaid line break Mermaid renders \n literally in node labels;
is the correct line break syntax. Co-Authored-By: Claude Opus 4.6 --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index a292a43..5b92bc6 100644 --- a/README.md +++ b/README.md @@ -95,7 +95,7 @@ graph TD B --> E["Execution Pipeline"] C --> E - D --> F["PolicyBackend\n(OPA, Cedar)"] + D --> F["PolicyBackend
(OPA, Cedar)"] E --> E1["1. Injection detection"] E1 --> E2["2. Argument validation"] From 2caba17e318ccbd0a2671981ec611a3b717c0be7 Mon Sep 17 00:00:00 2001 From: Francis Eytan Dortort Date: Wed, 25 Feb 2026 01:52:03 -0500 Subject: [PATCH 7/8] docs: replace README diagram with link to canonical docs version Two divergent architecture diagrams are a maintenance risk. Keep the detailed version in docs/index.md as the single source of truth and link to it from the README. Co-Authored-By: Claude Opus 4.6 --- README.md | 25 ++----------------------- 1 file changed, 2 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index 5b92bc6..9da1ac4 100644 --- a/README.md +++ b/README.md @@ -86,30 +86,9 @@ const result = await generateText({ ## Architecture -```mermaid -graph TD - A["createToolGuard(options)"] --> B["guardTool(name, tool, cfg)"] - A --> C["guardTools({...})"] - A --> D["(config)"] +Every guarded tool call passes through a 7-stage execution pipeline: injection detection, argument validation, policy evaluation, approval flow, rate limiting, tool execution, and output filtering. Each stage emits an OpenTelemetry span. - B --> E["Execution Pipeline"] - C --> E - - D --> F["PolicyBackend
(OPA, Cedar)"] - - E --> E1["1. Injection detection"] - E1 --> E2["2. Argument validation"] - E2 --> E3["3. Policy evaluation"] - E3 --> E4["4. Approval flow"] - E4 --> E5["5. Rate limiting"] - E5 --> E6["6. Tool execution"] - E6 --> E7["7. Output filtering"] - - F -.-> E3 - - style E fill:#f0f0f0,stroke:#333 - style F fill:#f0f0f0,stroke:#333 -``` +See the **[architecture overview](https://ai-tool-guard.readthedocs.io/#architecture)** for the full pipeline diagram. ## API reference From d0ba170770902ec327802dc022f30770794fe43d Mon Sep 17 00:00:00 2001 From: Francis Eytan Dortort Date: Wed, 25 Feb 2026 01:56:41 -0500 Subject: [PATCH 8/8] fix: align vertical lines in docs architecture diagram All three boxes had content rows 1 character wider than their border rows, causing the right edge to render misaligned. Co-Authored-By: Claude Opus 4.6 --- docs/index.md | 36 ++++++++++++++++++------------------ 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/docs/index.md b/docs/index.md index 22886b5..5c97a02 100644 --- a/docs/index.md +++ b/docs/index.md @@ -44,30 +44,30 @@ npm install ai-tool-guard The execution pipeline wraps each tool call in a series of composable stages: ``` - ┌─────────────────────────────────────────────────────────────────┐ - │ createToolGuard │ + ┌──────────────────────────────────────────────────────────────────┐ + │ createToolGuard │ │ (configuration & backends) │ - └──────────────────────────────┬──────────────────────────────────┘ + └──────────────────────────────┬───────────────────────────────────┘ │ ┌────────────────▼────────────────┐ - │ guardTool / guardTools │ - │ (wraps Vercel AI SDK tools) │ + │ guardTool / guardTools │ + │ (wraps Vercel AI SDK tools) │ └────────────────┬────────────────┘ │ ┌────────────────▼────────────────┐ - │ Pipeline │ - │ │ - │ 1. Injection detection │◄── OTel span - │ 2. Argument validation │◄── OTel span - │ 3. Policy evaluation │◄── PolicyBackend - │ ├─ allow │ - │ ├─ block ──────────────────► │ DecisionRecord - │ └─ require-approval ───────► │ ApprovalRequest - │ 4. Approval flow │◄── OTel span - │ └─ approve / edit / deny │ - │ 5. Rate limit check │◄── OTel span - │ 6. Tool execution │◄── OTel span - │ 7. Output filtering │◄── OTel span + │ Pipeline │ + │ │ + │ 1. Injection detection │◄── OTel span + │ 2. Argument validation │◄── OTel span + │ 3. Policy evaluation │◄── PolicyBackend + │ ├─ allow │ + │ ├─ block ─────────────────► │ DecisionRecord + │ └─ require-approval ──────► │ ApprovalRequest + │ 4. Approval flow │◄── OTel span + │ └─ approve / edit / deny │ + │ 5. Rate limit check │◄── OTel span + │ 6. Tool execution │◄── OTel span + │ 7. Output filtering │◄── OTel span └────────────────┬────────────────┘ │ ┌───────────▼───────────┐