@rex_koh/subagent-budget-guard 0.1.0

package/lib/verifier.js

@@ -0,0 +1,373 @@
+import { spawn } from 'node:child_process';
+import { mkdtemp, rm } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+import {
+  CONFIG_KEYS,
+  buildReport,
+  handlePostToolUseAgent,
+  handlePreToolUseAgent,
+  handleUserPromptSubmit,
+  installStatusLineBridge,
+  pathExists,
+  updateRateLimitFromStatusLine
+} from './guard.js';
+
+async function readJson(filePath) {
+  const { readFile } = await import('node:fs/promises');
+  const text = await readFile(filePath, 'utf8');
+  return JSON.parse(text.replace(/^\uFEFF/, ''));
+}
+
+function pluginRoot(repoRoot) {
+  return path.join(repoRoot, 'plugins', 'subagent-budget-guard');
+}
+
+async function withCheck(result, name, fn) {
+  try {
+    const detail = await fn();
+    result.checks.push({ name, ok: true, detail: detail || 'ok' });
+  } catch (error) {
+    result.checks.push({ name, ok: false, detail: error.message });
+    result.failures.push(`${name}: ${error.message}`);
+  }
+}
+
+function assert(condition, message) {
+  if (!condition) throw new Error(message);
+}
+
+export async function runOfflineVerification({
+  repoRoot = process.cwd(),
+  env = process.env
+} = {}) {
+  const result = {
+    mode: 'offline',
+    ok: false,
+    checks: [],
+    failures: []
+  };
+  const root = pluginRoot(repoRoot);
+
+  await withCheck(result, 'marketplace-manifest', async () => {
+    const marketplacePath = path.join(repoRoot, '.claude-plugin', 'marketplace.json');
+    const marketplace = await readJson(marketplacePath);
+    assert(marketplace.name === 'subagent-budget-tools', 'marketplace name mismatch');
+    assert(Array.isArray(marketplace.plugins), 'marketplace.plugins must be an array');
+    const entry = marketplace.plugins.find((plugin) => plugin.name === 'subagent-budget-guard');
+    assert(entry, 'subagent-budget-guard entry missing');
+    assert(entry.source?.source === 'npm', 'marketplace source must use npm');
+    assert(
+      entry.source?.package === '@rex_koh/subagent-budget-guard',
+      'marketplace npm package mismatch'
+    );
+    assert(entry.source?.version === '0.1.0', 'marketplace npm version mismatch');
+    return marketplacePath;
+  });
+
+  await withCheck(result, 'plugin-manifest-user-config', async () => {
+    const manifestPath = path.join(root, '.claude-plugin', 'plugin.json');
+    const manifest = await readJson(manifestPath);
+    assert(manifest.name === 'subagent-budget-guard', 'plugin name mismatch');
+    assert(
+      manifest.hooks === undefined,
+      'manifest.hooks must be omitted for default hooks/hooks.json to avoid duplicate loading'
+    );
+    assert(
+      manifest.skills === undefined,
+      'manifest.skills must be omitted for default skills/ scanning to avoid duplicate loading'
+    );
+    for (const key of CONFIG_KEYS) {
+      assert(manifest.userConfig?.[key], `missing userConfig.${key}`);
+    }
+    return manifestPath;
+  });
+
+  await withCheck(result, 'hooks-config', async () => {
+    const hooksPath = path.join(root, 'hooks', 'hooks.json');
+    const hooks = await readJson(hooksPath);
+    const requiredEvents = [
+      'PreToolUse',
+      'PostToolUse',
+      'SubagentStart',
+      'SubagentStop',
+      'TaskCreated',
+      'TaskCompleted',
+      'UserPromptSubmit'
+    ];
+    for (const event of requiredEvents) {
+      assert(Array.isArray(hooks.hooks?.[event]), `missing hooks.${event}`);
+    }
+    assert(hooks.hooks.PreToolUse[0].matcher === 'Agent', 'PreToolUse must match Agent');
+    assert(hooks.hooks.PostToolUse[0].matcher === 'Agent', 'PostToolUse must match Agent');
+    return hooksPath;
+  });
+
+  await withCheck(result, 'script-paths', async () => {
+    const scripts = [
+      'bin/hook.js',
+      'bin/statusline.js',
+      'bin/setup.js',
+      'bin/report.js',
+      'bin/verify.js',
+      'lib/guard.js',
+      'lib/verifier.js',
+      'skills/setup/SKILL.md',
+      'skills/report/SKILL.md',
+      'skills/verify/SKILL.md'
+    ];
+    for (const script of scripts) {
+      assert(await pathExists(path.join(root, script)), `missing ${script}`);
+    }
+    return `${scripts.length} files present`;
+  });
+
+  await withCheck(result, 'pretool-agent-denies-default', async () => {
+    const dataDir = await mkdtemp(path.join(os.tmpdir(), 'sbg-verify-'));
+    try {
+      const checkEnv = {
+        ...env,
+        CLAUDE_PLUGIN_DATA: dataDir,
+        CLAUDE_PLUGIN_ROOT: root
+      };
+      const output = await handlePreToolUseAgent(
+        {
+          session_id: 'offline-pretool',
+          hook_event_name: 'PreToolUse',
+          tool_name: 'Agent',
+          tool_input: { description: 'verify', subagent_type: 'Explore' }
+        },
+        checkEnv
+      );
+      assert(
+        output.stdout?.hookSpecificOutput?.permissionDecision === 'deny',
+        'Agent launch was not denied by default'
+      );
+      return output.stdout.hookSpecificOutput.permissionDecisionReason;
+    } finally {
+      await rm(dataDir, { recursive: true, force: true });
+    }
+  });
+
+  await withCheck(result, 'posttool-agent-records-verified-tokens', async () => {
+    const dataDir = await mkdtemp(path.join(os.tmpdir(), 'sbg-verify-'));
+    try {
+      const checkEnv = {
+        ...env,
+        CLAUDE_PLUGIN_DATA: dataDir,
+        CLAUDE_PLUGIN_ROOT: root
+      };
+      await handlePostToolUseAgent(
+        {
+          session_id: 'offline-posttool',
+          hook_event_name: 'PostToolUse',
+          tool_name: 'Agent',
+          tool_input: { description: 'verify', subagent_type: 'Explore' },
+          tool_response: {
+            status: 'completed',
+            agentId: 'agent-verify',
+            totalTokens: 101,
+            totalToolUseCount: 2,
+            totalDurationMs: 300
+          }
+        },
+        checkEnv
+      );
+      const report = await buildReport('offline-posttool', checkEnv);
+      assert(report.state.subagents.verifiedTokens === 101, 'verified token count mismatch');
+      return report.summary.verifiedTokenLabel;
+    } finally {
+      await rm(dataDir, { recursive: true, force: true });
+    }
+  });
+
+  await withCheck(result, 'statusline-budget-blocks', async () => {
+    const dataDir = await mkdtemp(path.join(os.tmpdir(), 'sbg-verify-'));
+    try {
+      const checkEnv = {
+        ...env,
+        CLAUDE_PLUGIN_DATA: dataDir,
+        CLAUDE_PLUGIN_ROOT: root,
+        CLAUDE_PLUGIN_OPTION_session_five_hour_budget_percent: '3'
+      };
+      await updateRateLimitFromStatusLine(
+        {
+          session_id: 'offline-budget',
+          rate_limits: { five_hour: { used_percentage: 10, resets_at: 1 } }
+        },
+        checkEnv
+      );
+      await updateRateLimitFromStatusLine(
+        {
+          session_id: 'offline-budget',
+          rate_limits: { five_hour: { used_percentage: 13.5, resets_at: 1 } }
+        },
+        checkEnv
+      );
+      const output = await handleUserPromptSubmit(
+        {
+          session_id: 'offline-budget',
+          hook_event_name: 'UserPromptSubmit',
+          prompt: 'continue'
+        },
+        checkEnv
+      );
+      assert(output.stdout?.decision === 'block', 'prompt was not blocked');
+      return output.stdout.reason;
+    } finally {
+      await rm(dataDir, { recursive: true, force: true });
+    }
+  });
+
+  await withCheck(result, 'statusline-setup-wraps-existing-command', async () => {
+    const dataDir = await mkdtemp(path.join(os.tmpdir(), 'sbg-verify-data-'));
+    const homeDir = await mkdtemp(path.join(os.tmpdir(), 'sbg-verify-home-'));
+    try {
+      const { mkdir, writeFile, readFile } = await import('node:fs/promises');
+      const claudeDir = path.join(homeDir, '.claude');
+      await mkdir(claudeDir, { recursive: true });
+      await writeFile(
+        path.join(claudeDir, 'settings.json'),
+        JSON.stringify({
+          statusLine: {
+            type: 'command',
+            command: 'node old-statusline.js'
+          }
+        })
+      );
+      const setup = await installStatusLineBridge({
+        homeDir,
+        pluginRoot: root,
+        pluginData: dataDir
+      });
+      const settings = JSON.parse(await readFile(path.join(claudeDir, 'settings.json'), 'utf8'));
+      assert(settings.statusLine.command.includes('statusline.js'), 'bridge command missing');
+      assert(settings.statusLine.command.includes('--data'), 'bridge data arg missing');
+      return setup.bridgePath;
+    } finally {
+      await rm(dataDir, { recursive: true, force: true });
+      await rm(homeDir, { recursive: true, force: true });
+    }
+  });
+
+  result.ok = result.failures.length === 0;
+  return result;
+}
+
+function commandExists(command) {
+  return new Promise((resolve) => {
+    const child = spawn(process.platform === 'win32' ? 'where.exe' : 'which', [command], {
+      stdio: 'ignore',
+      windowsHide: true
+    });
+    child.on('exit', (code) => resolve(code === 0));
+    child.on('error', () => resolve(false));
+  });
+}
+
+function runCommand(command, args, options = {}) {
+  return new Promise((resolve) => {
+    const child = spawn(command, args, {
+      cwd: options.cwd,
+      shell: false,
+      windowsHide: true
+    });
+    let stdout = '';
+    let stderr = '';
+    child.stdout?.on('data', (chunk) => {
+      stdout += chunk;
+    });
+    child.stderr?.on('data', (chunk) => {
+      stderr += chunk;
+    });
+    child.on('exit', (code) => resolve({ code, stdout, stderr }));
+    child.on('error', (error) =>
+      resolve({ code: 1, stdout, stderr: `${stderr}\n${error.message}` })
+    );
+  });
+}
+
+export async function runLiveVerification({
+  repoRoot = process.cwd(),
+  env = process.env
+} = {}) {
+  const result = {
+    mode: 'live',
+    ok: false,
+    checks: [],
+    failures: [],
+    warnings: []
+  };
+  const offline = await runOfflineVerification({ repoRoot, env });
+  result.checks.push(...offline.checks);
+  result.failures.push(...offline.failures);
+
+  const root = pluginRoot(repoRoot);
+  const hasClaude = await commandExists('claude');
+  if (!hasClaude) {
+    result.warnings.push('claude executable was not found on PATH; skipped claude plugin validate and install-state checks.');
+  } else {
+    await withCheck(result, 'claude-plugin-validate', async () => {
+      const validate = await runCommand('claude', ['plugin', 'validate', root], {
+        cwd: repoRoot
+      });
+      assert(validate.code === 0, validate.stderr || validate.stdout || 'claude plugin validate failed');
+      return validate.stdout.trim() || 'claude plugin validate passed';
+    });
+
+    await withCheck(result, 'claude-plugin-list', async () => {
+      const list = await runCommand('claude', ['plugin', 'list'], { cwd: repoRoot });
+      assert(list.code === 0, list.stderr || list.stdout || 'claude plugin list failed');
+      assert(
+        list.stdout.includes('subagent-budget-guard'),
+        'subagent-budget-guard is not installed'
+      );
+      assert(
+        !/subagent-budget-guard@subagent-budget-tools[\s\S]*failed to load/i.test(list.stdout),
+        'subagent-budget-guard is installed but failed to load'
+      );
+      return 'claude plugin list returned output';
+    });
+  }
+
+  await withCheck(result, 'statusline-bridge-configured', async () => {
+    const home = env.USERPROFILE || env.HOME || os.homedir();
+    const settingsPath = path.join(home, '.claude', 'settings.json');
+    const settings = await readJson(settingsPath);
+    assert(
+      typeof settings.statusLine?.command === 'string' &&
+        settings.statusLine.command.includes('statusline.js') &&
+        settings.statusLine.command.includes('--data'),
+      'statusLine bridge is not installed; run /subagent-budget-guard:setup'
+    );
+    return settings.statusLine.command;
+  });
+
+  result.ok = result.failures.length === 0;
+  return result;
+}
+
+export function formatVerificationResult(result) {
+  const lines = [
+    `Subagent Budget Guard ${result.mode} verification`,
+    result.ok ? 'PASS' : 'FAIL'
+  ];
+
+  for (const check of result.checks) {
+    lines.push(`${check.ok ? 'PASS' : 'FAIL'} ${check.name}: ${check.detail}`);
+  }
+
+  for (const warning of result.warnings || []) {
+    lines.push(`WARN ${warning}`);
+  }
+
+  if (result.failures.length > 0) {
+    lines.push('Failures:');
+    for (const failure of result.failures) {
+      lines.push(`- ${failure}`);
+    }
+  }
+
+  return lines.join('\n');
+}

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@rex_koh/subagent-budget-guard",
+  "version": "0.1.0",
+  "description": "Claude Code plugin that blocks subagents by default, records verified subagent usage, and enforces 5-hour usage budgets.",
+  "license": "MIT",
+  "author": "ClaudeSubAgentSuppressor",
+  "homepage": "https://github.com/rexkoh425/ClaudeSubAgentSuppressor#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/rexkoh425/ClaudeSubAgentSuppressor.git",
+    "directory": "plugins/subagent-budget-guard"
+  },
+  "bugs": {
+    "url": "https://github.com/rexkoh425/ClaudeSubAgentSuppressor/issues"
+  },
+  "keywords": [
+    "claude-code",
+    "claude-plugin",
+    "subagents",
+    "budget",
+    "tokens",
+    "rate-limit"
+  ],
+  "type": "module",
+  "files": [
+    ".claude-plugin/",
+    "hooks/",
+    "skills/",
+    "bin/",
+    "lib/",
+    "README.md",
+    "LICENSE"
+  ],
+  "bin": {
+    "subagent-budget-guard-report": "bin/report.js",
+    "subagent-budget-guard-setup": "bin/setup.js",
+    "subagent-budget-guard-verify": "bin/verify.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "verify:offline": "node bin/verify.js --offline",
+    "verify:live": "node bin/verify.js --live",
+    "prepack": "node --check bin/hook.js && node --check bin/statusline.js && node --check bin/setup.js && node --check bin/report.js && node --check bin/verify.js && node --check lib/guard.js && node --check lib/verifier.js"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/skills/report/SKILL.md

@@ -0,0 +1,18 @@
+---
+description: Show the current Subagent Budget Guard session report with subagent counts, verified token totals, and 5-hour budget state.
+disable-model-invocation: true
+---
+
+# Report Subagent Budget Guard Usage
+
+Run this command:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/bin/report.js"
+```
+
+If the user asks for machine-readable output, run:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/bin/report.js" --json
+```

package/skills/setup/SKILL.md

@@ -0,0 +1,20 @@
+---
+description: Install or refresh the Subagent Budget Guard statusLine bridge so 5-hour rate-limit percentages can be captured for enforcement.
+disable-model-invocation: true
+---
+
+# Setup Subagent Budget Guard
+
+Run this command:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/bin/setup.js"
+```
+
+Then tell the user to interact with Claude Code once so the statusLine bridge receives fresh session JSON. After that, run:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/bin/verify.js" --live
+```
+
+The live verifier does not submit Claude prompts. It checks local plugin shape, Claude plugin validation when `claude` is on `PATH`, and whether the statusLine bridge is configured.

package/skills/verify/SKILL.md

@@ -0,0 +1,20 @@
+---
+description: Verify the Subagent Budget Guard plugin without spending Claude quota, or run live local installation checks.
+disable-model-invocation: true
+---
+
+# Verify Subagent Budget Guard
+
+For default offline verification, run:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/bin/verify.js" --offline
+```
+
+For live local installation checks, run:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/bin/verify.js" --live
+```
+
+The live verifier does not submit Claude prompts. It checks local plugin shape, `claude plugin validate` when available, plugin listing shape, and statusLine bridge setup.