ai-guard-plugins 1.1.0

package/install.yaml

@@ -0,0 +1,49 @@
+name: AI Guard Plugins Installer
+description: Install production-hardened plugins for Claude Code & OpenCode
+
+steps:
+  - id: platform
+    type: select
+    message: Which AI coding assistant are you using?
+    choices:
+      - label: OpenCode
+        value: opencode
+      - label: Claude Code
+        value: claude
+      - label: Cline
+        value: cline
+      - label: Cursor
+        value: cursor
+      - label: Kilo Code
+        value: kilo
+
+  - id: plugins
+    type: multiselect
+    message: Which plugins do you want to install?
+    choices:
+      - label: "💳 billing-guard — Catch billing errors before infinite retry freezes"
+        value: billing-guard
+        checked: true
+      - label: "🧹 auto-lint-fix — Auto-format code after every write/edit"
+        value: auto-lint-fix
+        checked: true
+      - label: "📦 auto-summarize-input — Compress large inputs to save tokens"
+        value: auto-summarize-input
+        checked: true
+      - label: "🧠 capture-insights — Learn from recurring mistakes"
+        value: capture-insights
+        checked: true
+      - label: "📏 cursorrules-enforcer — Enforce coding standards on writes"
+        value: cursorrules-enforcer
+        checked: true
+      - label: "🔍 dry-guard — Warn before duplicating existing code"
+        value: dry-guard
+        checked: true
+
+  - id: confirm
+    type: confirm
+    message: "Install selected plugins?"
+
+output:
+  platform: "{{ platform }}"
+  plugins: "{{ plugins }}"

package/llms.txt

@@ -0,0 +1,33 @@
+# ai-guard-plugins
+
+Production-hardened plugins for Claude Code & OpenCode AI coding assistants.
+
+## What this repo contains
+
+6 TypeScript plugins that intercept AI agent behavior to prevent costly mistakes:
+
+1. billing-guard.ts — Detects billing/quota errors and interrupts before infinite retry freezes
+2. auto-lint-fix.ts — Auto-runs Biome formatter after every file write/edit
+3. auto-summarize-input.ts — Compresses inputs >10K chars via Claude Haiku to save context tokens
+4. capture-insights.ts — Tracks recurring mistake patterns across sessions in persistent JSONL
+5. cursorrules-enforcer.ts — Blocks writes containing `as any`, `@ts-ignore`, TODOs, require()
+6. dry-guard.ts — Warns before creating files that duplicate existing code in the project
+
+## Plugin API
+
+All plugins implement the `Plugin` type from `@opencode-ai/plugin` and use these hooks:
+- `tool.execute.before` — intercept before a tool runs (can throw to block)
+- `tool.execute.after` — react after a tool completes
+- `event` — listen to session events like `message.updated` and `session.idle`
+- `tui.prompt.append` — intercept user input before it reaches the model
+
+## Installation
+
+Plugins are standalone .ts files copied to `~/.config/opencode/plugins/` (OpenCode) or `~/.claude/plugins/` (Claude Code).
+
+## Key patterns
+
+- Plugins throw Error to block operations (cursorrules-enforcer, billing-guard)
+- Plugins use console.warn for advisory warnings (dry-guard)
+- Plugins use persistent storage via JSONL files (capture-insights)
+- Plugins shell out via `$` tagged template for system commands (auto-lint-fix, dry-guard)

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "ai-guard-plugins",
+  "version": "1.1.0",
+  "description": "> Production-hardened plugins for [Claude Code](https://docs.anthropic.com/en/docs/claude-code) & [OpenCode](https://opencode.ai) — battle-tested hooks from real AI-assisted development that catch costly mistakes before they happen.",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/YosefHayim/ai-guard-plugins.git"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "type": "commonjs",
+  "bugs": {
+    "url": "https://github.com/YosefHayim/ai-guard-plugins/issues"
+  },
+  "homepage": "https://github.com/YosefHayim/ai-guard-plugins#readme",
+  "devDependencies": {
+    "pr-prism": "^1.1.6"
+  }
+}

package/plugins/auto-lint-fix.ts

@@ -0,0 +1,39 @@
+import type { Plugin } from '@opencode-ai/plugin';
+
+const LINTABLE_EXTS = new Set(['.ts', '.tsx', '.js', '.jsx', '.mts', '.mjs', '.cts', '.cjs']);
+const SKIP_PATHS = ['node_modules', 'dist', '.next', 'build', '.turbo'];
+const BIOME = process.env.BIOME_PATH ?? 'biome';
+
+function getExt(filePath: string): string {
+	const dot = filePath.lastIndexOf('.');
+	return dot === -1 ? '' : filePath.slice(dot);
+}
+
+export const AutoLintFixPlugin: Plugin = async ({ $ }) => {
+	try {
+		await $`which ${BIOME}`.quiet();
+	} catch {
+		console.warn('[auto-lint-fix] biome not found — plugin disabled');
+		return {};
+	}
+
+	return {
+		'tool.execute.after': async (input, _output) => {
+			if (input.tool !== 'write' && input.tool !== 'edit') return;
+
+			const args = (_output?.args ?? input.args) as Record<string, unknown> | undefined;
+			if (!args) return;
+
+			const filePath = (args.filePath ?? args.file_path) as string | undefined;
+			if (!filePath) return;
+
+			if (!LINTABLE_EXTS.has(getExt(filePath))) return;
+			const normalizedPath = filePath.replace(/\\/g, '/');
+			if (SKIP_PATHS.some((p) => normalizedPath.includes(`/${p}/`) || normalizedPath.startsWith(`${p}/`))) return;
+
+			try {
+				await $`${BIOME} check --fix --unsafe ${filePath}`.quiet().nothrow();
+			} catch {}
+		},
+	};
+};

package/plugins/auto-summarize-input.ts

@@ -0,0 +1,45 @@
+import type { Plugin } from '@opencode-ai/plugin';
+
+const THRESHOLD = 10000;
+
+export const AutoSummarizeInputPlugin: Plugin = async ({ client }) => {
+	return {
+		'tui.prompt.append': async (_input, output) => {
+			const text = String(output?.text ?? '');
+			if (text.length <= THRESHOLD) return;
+
+			try {
+				const charCount = text.length;
+				console.log(`📦 Input too large (${charCount} chars). Auto-summarizing via Claude...`);
+
+				const result = await client.chat.create({
+					body: {
+						model: 'claude-haiku-4-5-20250415',
+						max_tokens: 2000,
+						messages: [
+							{
+								role: 'user',
+								content: `Summarize this input for a coding assistant. Keep ALL code snippets, file paths, error messages, and requirements verbatim. Remove ONLY redundancy, repetition, and filler. Output ONLY the summarized input:\n\n${text}`,
+							},
+						],
+					},
+				});
+
+				const summary =
+					result?.content?.find?.((b: Record<string, unknown>) => b.type === 'text')?.text ??
+					result?.content?.[0]?.text ??
+					'';
+
+				if (summary && summary.length < charCount && output?.text === text) {
+					const reduction = Math.round(((charCount - summary.length) / charCount) * 100);
+					output.text = `[Auto-summarized: ${charCount} chars → ${summary.length} chars (${reduction}% reduction)]\n\n${summary}`;
+					console.log(
+						`📦 Auto-summarized: ${charCount} → ${summary.length} chars (${reduction}% saved)`,
+					);
+				}
+			} catch (err) {
+				console.warn(`[auto-summarize] Failed: ${err}`);
+			}
+		},
+	};
+};

package/plugins/billing-guard.ts

@@ -0,0 +1,101 @@
+import type { Plugin } from '@opencode-ai/plugin';
+
+const BILLING_PATTERNS = [
+	/No payment method/i,
+	/Add a payment method/i,
+	/account is not active.*billing/i,
+	/billing details/i,
+	/payment.*required/i,
+	/quota.*exceeded/i,
+	/insufficient.*funds/i,
+	/rate limit.*billing/i,
+	/plan.*expired/i,
+	/subscription.*inactive/i,
+];
+
+function isBillingError(text: string): string | null {
+	for (const pattern of BILLING_PATTERNS) {
+		const match = text.match(pattern);
+		if (match) return match[0];
+	}
+	return null;
+}
+
+function safeStringify(value: unknown): string {
+	try {
+		return typeof value === 'string' ? value : JSON.stringify(value);
+	} catch {
+		return String(value);
+	}
+}
+
+function extractText(msg: Record<string, unknown>): string {
+	if (typeof msg.content === 'string') return msg.content;
+	if (Array.isArray(msg.content)) {
+		return (msg.content as Array<Record<string, unknown>>)
+			.map((p: Record<string, unknown>) => (typeof p.text === 'string' ? p.text : ''))
+			.join(' ');
+	}
+	if (typeof msg.text === 'string') return msg.text;
+	if (typeof msg.output === 'string') return msg.output;
+	if (typeof msg.error === 'string') return msg.error;
+	if (typeof msg.result === 'string') return msg.result;
+	if (Array.isArray(msg.parts)) {
+		return (msg.parts as Array<Record<string, unknown>>)
+			.map((p: Record<string, unknown>) => (typeof p.text === 'string' ? p.text : ''))
+			.join(' ');
+	}
+	return '';
+}
+
+export const BillingGuardPlugin: Plugin = async () => {
+	return {
+		'tool.execute.after': async (_input, output) => {
+			const result = output?.result;
+			if (!result) return;
+
+			const text = safeStringify(result);
+			const match = isBillingError(text);
+
+			if (match) {
+				console.error(`\n💳 BILLING ERROR DETECTED: "${match}"`);
+				console.error('⚡ Interrupting to prevent infinite retry freeze.\n');
+				throw new Error(
+					`BILLING ERROR: ${match}. The API provider requires payment. Fix billing before retrying. Do NOT retry this operation.`,
+				);
+			}
+		},
+
+		'tool.execute.before': async (input, output) => {
+			if (input.tool !== 'task') return;
+
+			const args = (output?.args ?? input.args) as Record<string, unknown> | undefined;
+			if (!args) return;
+
+			const prompt = String(args.prompt ?? '');
+			const match = isBillingError(prompt);
+			if (match) {
+				throw new Error(
+					`BILLING ERROR in task prompt: ${match}. Do NOT delegate — billing issue must be resolved first.`,
+				);
+			}
+		},
+
+		event: async ({ event }) => {
+			if (event.type !== 'message.updated') return;
+
+			const msg = event.properties as Record<string, unknown>;
+			const text = extractText(msg);
+			if (!text) return;
+
+			const match = isBillingError(text);
+			if (match) {
+				console.error(`\n💳 BILLING ERROR in message stream: "${match}"`);
+				console.error('⚡ Agent must stop all operations and notify the user.\n');
+				throw new Error(
+					`BILLING ERROR: ${match}. STOP all operations. Do NOT retry or delegate. Notify the user that billing needs to be fixed.`,
+				);
+			}
+		},
+	};
+};

package/plugins/capture-insights.ts

@@ -0,0 +1,215 @@
+import type { Plugin } from '@opencode-ai/plugin';
+
+const MEMORY_FILE = `${process.env.HOME ?? require('node:os').homedir()}/.claude/memory/insights.jsonl`;
+
+interface InsightEntry {
+	id: string;
+	insight: string;
+	count: number;
+	last: string;
+	projects: string;
+}
+
+const PATTERN_CHECKS: Array<{ regex: RegExp; id: string; insight: string }> = [
+	{
+		regex: /DRY|don't repeat|already exists|duplicat/i,
+		id: 'dry-violation',
+		insight:
+			'Check existing files before creating new ones. Extract shared utils when there is clear reuse.',
+	},
+	{
+		regex: /unused import|unused variable|dead code/i,
+		id: 'unused-code',
+		insight: 'Biome --fix handles unused imports/variables automatically.',
+	},
+	{
+		regex: /as any|ts-ignore|ts-expect-error/i,
+		id: 'type-safety-bypass',
+		insight:
+			'Never use as any, @ts-ignore, or @ts-expect-error. Use the most specific correct type.',
+	},
+	{
+		regex: /refactor.*minimal|minimal change|scope creep/i,
+		id: 'scope-discipline',
+		insight: 'Make the minimal change needed. Do not refactor while fixing.',
+	},
+	{
+		regex: /circular dependency|circular import/i,
+		id: 'circular-dep',
+		insight: 'Restructure module boundaries to break circular dependencies.',
+	},
+	{
+		regex: /re-export|barrel file|index file.*logic/i,
+		id: 're-export',
+		insight: 'Avoid re-exports. Index files may only re-export modules, never logic.',
+	},
+	{
+		regex: /process\.cwd|project root.*monorepo/i,
+		id: 'path-resolution',
+		insight:
+			'Never assume process.cwd() equals project root in monorepos. Use explicit root resolver.',
+	},
+	{
+		regex: /migration|schema change|database migrat/i,
+		id: 'data-migration',
+		insight: 'Verify schema + data integrity after migrations. Make migrations idempotent.',
+	},
+	{
+		regex: /workaround|hack|bandaid|band-aid/i,
+		id: 'workaround',
+		insight: 'Document why workaround was needed and plan a proper fix.',
+	},
+	{
+		regex: /performance|slow query|optimize|bottleneck/i,
+		id: 'performance',
+		insight: "Profile before optimizing. Measure, don't guess.",
+	},
+	{
+		regex: /security|secret|credential|api.key|token leak/i,
+		id: 'security',
+		insight: 'Review credentials handling. Never commit secrets.',
+	},
+	{
+		regex: /test.*mock.*implementation|mock.*detail/i,
+		id: 'test-mock',
+		insight: 'Mock behavior (modules), not implementation details (process.cwd, process.env).',
+	},
+];
+
+function readEntries(): Map<string, InsightEntry> {
+	const map = new Map<string, InsightEntry>();
+	try {
+		const fs = require('node:fs');
+		if (!fs.existsSync(MEMORY_FILE)) return map;
+		const lines = fs.readFileSync(MEMORY_FILE, 'utf-8').split('\n').filter(Boolean);
+		for (const line of lines) {
+			try {
+				const entry = JSON.parse(line) as InsightEntry;
+				map.set(entry.id, entry);
+			} catch {}
+		}
+	} catch {}
+	return map;
+}
+
+function writeEntries(entries: Map<string, InsightEntry>): void {
+	try {
+		const fs = require('node:fs');
+		const path = require('node:path');
+		const dir = path.dirname(MEMORY_FILE);
+		if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+		const content = `${[...entries.values()].map((e) => JSON.stringify(e)).join('\n')}\n`;
+		fs.writeFileSync(MEMORY_FILE, content);
+	} catch {}
+}
+
+export const CaptureInsightsPlugin: Plugin = async ({ directory }) => {
+	let sessionBuffer: string[] = [];
+
+	return {
+		event: async ({ event }) => {
+			if (event.type === 'message.updated') {
+				const msg = event.properties as Record<string, unknown>;
+				const text = extractText(msg);
+				if (text) {
+					sessionBuffer.push(text);
+					if (sessionBuffer.length > 50) sessionBuffer = sessionBuffer.slice(-50);
+				}
+			}
+
+			if (event.type === 'session.idle') {
+				if (sessionBuffer.length === 0) return;
+
+				const combined = sessionBuffer.join('\n');
+				const matched = PATTERN_CHECKS.filter((p) => p.regex.test(combined));
+
+				if (matched.length === 0) {
+					sessionBuffer = [];
+					return;
+				}
+
+				const entries = readEntries();
+				const now = new Date().toISOString().slice(0, 16);
+				const projectName = directory.split('/').pop() ?? 'unknown';
+
+				for (const m of matched) {
+					const existing = entries.get(m.id);
+					if (existing) {
+						existing.count += 1;
+						existing.last = now;
+						const projects = existing.projects.split(',').filter(Boolean);
+						if (!projects.includes(projectName)) {
+							existing.projects += `,${projectName}`;
+						}
+					} else {
+						entries.set(m.id, {
+							id: m.id,
+							insight: m.insight,
+							count: 1,
+							last: now,
+							projects: projectName,
+						});
+					}
+				}
+
+				writeEntries(entries);
+				squeezy(entries);
+
+				const captured = matched.map((m) => {
+					const e = entries.get(m.id);
+					return `  📝 ${m.id} (count: ${e?.count ?? 1})`;
+				});
+				console.log(
+					`🧠 Insights captured (${projectName}, ${entries.size} total entries):\n${captured.join('\n')}`,
+				);
+
+				sessionBuffer = [];
+			}
+		},
+	};
+};
+
+const SQUEEZY_MAX = 15;
+
+function squeezy(entries: Map<string, InsightEntry>): void {
+	if (entries.size <= SQUEEZY_MAX) return;
+
+	const sorted = [...entries.values()].sort((a, b) => b.count - a.count);
+	const kept = sorted.slice(0, SQUEEZY_MAX);
+	const overflow = sorted.slice(SQUEEZY_MAX);
+
+	for (const extra of overflow) {
+		const familyPrefix = extra.id.split('-')[0];
+		const target = kept.find((k) => k.id.split('-')[0] === familyPrefix);
+		if (target) {
+			target.count += extra.count;
+			const combinedInsights = `${target.insight} ${extra.insight}`
+				.split('. ')
+				.filter((v, i, a) => a.indexOf(v) === i)
+				.join('. ');
+			target.insight = combinedInsights;
+			const combinedProjects = `${target.projects},${extra.projects}`
+				.split(',')
+				.filter((v, i, a) => a.indexOf(v) === i)
+				.join(',');
+			target.projects = combinedProjects;
+		}
+	}
+
+	const squeezed = new Map<string, InsightEntry>();
+	for (const entry of kept) {
+		squeezed.set(entry.id, entry);
+	}
+	writeEntries(squeezed);
+}
+
+function extractText(msg: Record<string, unknown>): string {
+	if (typeof msg.content === 'string') return msg.content;
+	if (typeof msg.text === 'string') return msg.text;
+	if (Array.isArray(msg.parts)) {
+		return (msg.parts as Array<Record<string, unknown>>)
+			.map((p) => (typeof p.text === 'string' ? p.text : ''))
+			.join(' ');
+	}
+	return '';
+}

package/plugins/cline/hooks/PostToolUse

@@ -0,0 +1,73 @@
+#!/bin/bash
+# =============================================================================
+# AI Guard Plugin: PostToolUse Hook for Cline
+# Combines: billing-guard (after), auto-lint-fix
+#
+# Requires: jq (https://jqlang.github.io/jq/)
+# Optional: biome (https://biomejs.dev/) for auto-formatting
+# Contract: reads JSON from stdin, outputs JSON to stdout
+# =============================================================================
+
+set -euo pipefail
+
+INPUT=$(cat)
+
+TOOL=$(echo "$INPUT" | jq -r '.postToolUse.tool // empty' 2>/dev/null || true)
+PARAMS=$(echo "$INPUT" | jq -c '.postToolUse.parameters // {}' 2>/dev/null || echo '{}')
+RESULT=$(echo "$INPUT" | jq -r '.postToolUse.result // empty' 2>/dev/null || true)
+
+# Default: allow
+allow() { echo '{"cancel":false,"contextModification":"","errorMessage":""}'; exit 0; }
+cancel() { echo "{\"cancel\":true,\"contextModification\":\"\",\"errorMessage\":$(echo "$1" | jq -Rs .)}"; exit 0; }
+inform() { echo "{\"cancel\":false,\"contextModification\":$(echo "$1" | jq -Rs .),\"errorMessage\":\"\"}"; exit 0; }
+
+[ -z "$TOOL" ] && allow
+
+# =============================================================================
+# 1. BILLING GUARD (after) — detect billing errors in tool results
+# =============================================================================
+if [ -n "$RESULT" ]; then
+  if echo "$RESULT" | grep -qiE \
+    'payment.method|payment.required|account.is.not.active.*billing|billing.details|quota.exceeded|insufficient.funds|rate.limit.*billing|plan.expired|subscription.inactive'; then
+    cancel "BILLING ERROR detected in tool result. The API provider requires payment. Fix billing before retrying. Do NOT retry this operation."
+  fi
+fi
+
+# =============================================================================
+# 2. AUTO LINT FIX — run biome after file writes
+# =============================================================================
+if [ "$TOOL" = "write_to_file" ] || [ "$TOOL" = "insert_code_block" ] || [ "$TOOL" = "search_and_replace" ]; then
+  FILE_PATH=$(echo "$PARAMS" | jq -r '.path // empty' 2>/dev/null || true)
+  [ -z "$FILE_PATH" ] && allow
+
+  # Only lint code files
+  EXT="${FILE_PATH##*.}"
+  case "$EXT" in
+    ts|tsx|js|jsx|mts|mjs|cts|cjs) ;;
+    *) allow ;;
+  esac
+
+  # Skip excluded paths (handle both root-level and nested)
+  for skip in node_modules dist .next build .turbo; do
+    [[ "$FILE_PATH" == "$skip/"* || "$FILE_PATH" == *"/$skip/"* ]] && allow
+  done
+
+  # Find biome binary
+  BIOME="${BIOME_PATH:-biome}"
+  if ! command -v "$BIOME" &>/dev/null; then
+    if [ -f "./node_modules/.bin/biome" ]; then
+      BIOME="./node_modules/.bin/biome"
+    else
+      allow
+    fi
+  fi
+
+  # Run biome fix
+  if "$BIOME" check --fix --unsafe "$FILE_PATH" &>/dev/null; then
+    inform "[auto-lint-fix] Auto-formatted ${FILE_PATH##*/} with Biome."
+  else
+    allow
+  fi
+fi
+
+allow