@rex_koh/subagent-budget-guard 0.1.2 → 0.1.4

package/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "subagent-budget-guard",
   "displayName": "Subagent Budget Guard",
   "description": "Hard-deny subagent launches, record verified subagent usage, and enforce a session budget against Claude Code's 5-hour rate-limit percentage.",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "author": {
     "name": "ClaudeSubAgentSuppressor"
   },
@@ -31,6 +31,15 @@
       "min": 0,
       "required": true
     },
+    "subagent_token_warning_threshold_percent": {
+      "type": "number",
+      "title": "Subagent token warning threshold percent",
+      "description": "Warn Claude to stop using subagents once verified subagent token usage reaches this percentage of max_subagent_tokens_per_session.",
+      "default": 95,
+      "min": 1,
+      "max": 100,
+      "required": true
+    },
     "session_five_hour_budget_percent": {
       "type": "number",
       "title": "Session 5-hour budget percent",

package/README.md

@@ -1,6 +1,6 @@
 # Subagent Budget Guard
 
-Claude Code plugin that blocks subagents by default, records verified subagent usage, and enforces a session budget against Claude Code's 5-hour usage percentage.
+Claude Code plugin that blocks subagents before setup, records verified subagent usage, and enforces a session budget against Claude Code's 5-hour usage percentage.
 
 ## Install
 
@@ -10,13 +10,14 @@ Recommended Claude Code install:
 /plugin marketplace add rexkoh425/ClaudeSubAgentSuppressor
 /plugin install subagent-budget-guard@subagent-budget-tools
 /reload-plugins
+/subagent-budget-guard:setup
+/reload-plugins
+/subagent-budget-guard:verify
 ```
 
-Run after install:
+Useful after install:
 
 ```text
-/subagent-budget-guard:setup
-/subagent-budget-guard:verify
 /subagent-budget-guard:report
 ```
 
@@ -43,4 +44,17 @@ Offline verification:
 node bin/verify.js --offline
 ```
 
-The plugin is strict by default: `max_concurrent_subagents` defaults to `0`, so normal subagent launches are blocked unless raised.
+The plugin is strict before setup: `max_concurrent_subagents` defaults to `0`, so normal subagent launches are blocked unless raised. Run `/subagent-budget-guard:setup` to replace the long `--config ...` install command with the recommended config:
+
+```text
+max_concurrent_subagents=1
+max_subagent_tokens_per_session=100000
+subagent_token_warning_threshold_percent=95
+session_five_hour_budget_percent=25
+absolute_five_hour_ceiling_percent=95
+enforcement_enabled=true
+```
+
+For existing installs, setup also removes obsolete `max_subagents_per_session` and `max_agent_team_tasks_per_session` options from this plugin's Claude settings.
+
+`max_subagent_tokens_per_session` is enforced from verified `Agent.totalTokens` values after each completed subagent. `subagent_token_warning_threshold_percent` defaults to `95`; once verified subagent usage reaches that percentage, the plugin tells Claude to stop using subagents and blocks future subagent launches. Claude Code does not expose mid-run per-token subagent streaming to hooks, so a single running subagent can only be evaluated when it reports its final token total.

package/bin/setup.js

@@ -11,6 +11,13 @@ async function main() {
   process.stdout.write(
     [
       'Subagent Budget Guard statusLine bridge installed.',
+      'Recommended plugin config applied:',
+      `  max_concurrent_subagents=${result.pluginConfigOptions.max_concurrent_subagents}`,
+      `  max_subagent_tokens_per_session=${result.pluginConfigOptions.max_subagent_tokens_per_session}`,
+      `  subagent_token_warning_threshold_percent=${result.pluginConfigOptions.subagent_token_warning_threshold_percent}`,
+      `  session_five_hour_budget_percent=${result.pluginConfigOptions.session_five_hour_budget_percent}`,
+      `  absolute_five_hour_ceiling_percent=${result.pluginConfigOptions.absolute_five_hour_ceiling_percent}`,
+      `  enforcement_enabled=${result.pluginConfigOptions.enforcement_enabled}`,
       `Settings: ${result.settingsPath}`,
       `Bridge state: ${result.bridgePath}`,
       result.previousStatusLine

package/lib/guard.js

@@ -13,17 +13,33 @@ import {
 } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
 export const PLUGIN_NAME = 'subagent-budget-guard';
+export const PLUGIN_ID = 'subagent-budget-guard@subagent-budget-tools';
 
 export const DEFAULT_CONFIG = Object.freeze({
   max_concurrent_subagents: 0,
   max_subagent_tokens_per_session: 0,
+  subagent_token_warning_threshold_percent: 95,
   session_five_hour_budget_percent: 25,
   absolute_five_hour_ceiling_percent: 95,
   enforcement_enabled: true
 });
 
+export const SETUP_CONFIG = Object.freeze({
+  ...DEFAULT_CONFIG,
+  max_concurrent_subagents: 1,
+  max_subagent_tokens_per_session: 100000
+});
+
 export const CONFIG_KEYS = Object.freeze(Object.keys(DEFAULT_CONFIG));
+export const REMOVED_CONFIG_KEYS = Object.freeze([
+  'max_subagents_per_session',
+  'max_agent_team_tasks_per_session'
+]);
 
 const NUMBER_KEYS = new Set(
   CONFIG_KEYS.filter((key) => typeof DEFAULT_CONFIG[key] === 'number')
@@ -78,6 +94,10 @@ export function loadConfig(env = process.env) {
     100,
     config.absolute_five_hour_ceiling_percent
   );
+  config.subagent_token_warning_threshold_percent = Math.min(
+    100,
+    Math.max(1, config.subagent_token_warning_threshold_percent)
+  );
 
   return config;
 }
@@ -87,7 +107,7 @@ export function getHomeDir(env = process.env) {
 }
 
 export function getPluginRoot(env = process.env) {
-  return env.CLAUDE_PLUGIN_ROOT || path.resolve('.');
+  return env.CLAUDE_PLUGIN_ROOT || PACKAGE_ROOT;
 }
 
 export function getDataDir(env = process.env) {
@@ -125,6 +145,9 @@ function initialState(sessionId) {
       verifiedTokens: 0,
       totalDurationMs: 0,
       totalToolUseCount: 0,
+      tokenBudgetWarnings: 0,
+      tokenBudgetExceeded: false,
+      lastTokenBudgetNoticeAt: null,
       runs: []
     },
     agentTeam: {
@@ -191,7 +214,23 @@ async function acquireLock(sessionId, env, timeoutMs = 3000) {
 }
 
 async function readState(sessionId, env) {
-  return readJson(stateFile(sessionId, env), initialState(sessionId));
+  return normalizeState(await readJson(stateFile(sessionId, env), initialState(sessionId)), sessionId);
+}
+
+function normalizeState(state, sessionId) {
+  const fresh = initialState(sessionId);
+  state.subagents = { ...fresh.subagents, ...(state.subagents || {}) };
+  state.agentTeam = { ...fresh.agentTeam, ...(state.agentTeam || {}) };
+  state.rateLimits = {
+    ...fresh.rateLimits,
+    ...(state.rateLimits || {}),
+    fiveHour: {
+      ...fresh.rateLimits.fiveHour,
+      ...(state.rateLimits?.fiveHour || {})
+    }
+  };
+  state.events = Array.isArray(state.events) ? state.events : [];
+  return state;
 }
 
 async function updateState(sessionId, env, updater) {
@@ -298,12 +337,62 @@ function fiveHourBudgetDecision(state, config) {
   return null;
 }
 
+function formatCount(value) {
+  return Number(value || 0).toLocaleString('en-US');
+}
+
+function subagentTokenBudgetStatus(state, config) {
+  const limit = config.max_subagent_tokens_per_session;
+  if (!limit || limit <= 0) return null;
+
+  const used = Number(state.subagents.verifiedTokens || 0);
+  const percent = limit > 0 ? (used / limit) * 100 : 0;
+  const warningThreshold = config.subagent_token_warning_threshold_percent;
+
+  return {
+    used,
+    limit,
+    percent,
+    warningThreshold,
+    warningTokens: Math.ceil((limit * warningThreshold) / 100),
+    atWarning: percent >= warningThreshold,
+    atCap: used >= limit
+  };
+}
+
+function subagentTokenBudgetDecision(state, config, { includeWarning = true } = {}) {
+  if (!config.enforcement_enabled) return null;
+  const status = subagentTokenBudgetStatus(state, config);
+  if (!status) return null;
+
+  if (status.atCap) {
+    return {
+      severity: 'cap',
+      status,
+      reason: `Verified subagent token cap reached: ${formatCount(status.used)}/${formatCount(status.limit)} tokens (${status.percent.toFixed(1)}%). Stop using subagents and ask the user before continuing.`
+    };
+  }
+
+  if (includeWarning && status.atWarning) {
+    return {
+      severity: 'warning',
+      status,
+      reason: `Verified subagent token usage reached ${status.percent.toFixed(1)}% of the configured cap (${formatCount(status.used)}/${formatCount(status.limit)} tokens; warning threshold ${status.warningThreshold}%). Stop using subagents and ask the user before continuing.`
+    };
+  }
+
+  return null;
+}
+
 function agentDenyReason(state, config) {
   if (!config.enforcement_enabled) return null;
 
   const budgetReason = fiveHourBudgetDecision(state, config);
   if (budgetReason) return budgetReason;
 
+  const tokenBudgetReason = subagentTokenBudgetDecision(state, config);
+  if (tokenBudgetReason) return tokenBudgetReason.reason;
+
   if (config.max_concurrent_subagents === 0) {
     return 'Subagent launch denied: max_concurrent_subagents is 0.';
   }
@@ -312,13 +401,6 @@ function agentDenyReason(state, config) {
     return `Subagent launch denied: max_concurrent_subagents ${config.max_concurrent_subagents} already reached.`;
   }
 
-  if (
-    config.max_subagent_tokens_per_session > 0 &&
-    state.subagents.verifiedTokens >= config.max_subagent_tokens_per_session
-  ) {
-    return `Subagent launch denied: verified subagent tokens ${state.subagents.verifiedTokens} reached max_subagent_tokens_per_session ${config.max_subagent_tokens_per_session}.`;
-  }
-
   return null;
 }
 
@@ -377,11 +459,13 @@ function usageTotal(usage = {}) {
 
 export async function handlePostToolUseAgent(input, env = process.env) {
   const sessionId = input?.session_id || 'unknown-session';
+  const config = loadConfig(env);
   const response = input?.tool_response || {};
   const status = response.status || 'unknown';
   const totalTokens =
     numberOrNull(response.totalTokens) ?? usageTotal(response.usage || {});
   const verified = status === 'completed' && totalTokens > 0;
+  let tokenBudgetNotice = null;
 
   await updateState(sessionId, env, (state) => {
     const run = {
@@ -409,6 +493,14 @@ export async function handlePostToolUseAgent(input, env = process.env) {
       state.subagents.verifiedTokens += totalTokens;
       state.subagents.totalDurationMs += run.totalDurationMs;
       state.subagents.totalToolUseCount += run.totalToolUseCount;
+      tokenBudgetNotice = subagentTokenBudgetDecision(state, config);
+      if (tokenBudgetNotice) {
+        state.subagents.tokenBudgetWarnings += 1;
+        state.subagents.lastTokenBudgetNoticeAt = nowIso();
+        if (tokenBudgetNotice.severity === 'cap') {
+          state.subagents.tokenBudgetExceeded = true;
+        }
+      }
     } else if (status === 'async_launched') {
       state.subagents.backgroundLaunched += 1;
     }
@@ -420,9 +512,22 @@ export async function handlePostToolUseAgent(input, env = process.env) {
       verified,
       totalTokens: run.totalTokens
     });
+    if (tokenBudgetNotice) {
+      pushEvent(state, {
+        type: 'subagent-token-budget-notice',
+        severity: tokenBudgetNotice.severity,
+        used: tokenBudgetNotice.status.used,
+        limit: tokenBudgetNotice.status.limit,
+        percent: tokenBudgetNotice.status.percent
+      });
+    }
     return state;
   });
 
+  if (tokenBudgetNotice) {
+    return { exitCode: 2, stdout: null, stderr: tokenBudgetNotice.reason };
+  }
+
   return { exitCode: 0, stdout: null, stderr: '' };
 }
 
@@ -530,7 +635,10 @@ export async function handleUserPromptSubmit(input, env = process.env) {
   const sessionId = input?.session_id || 'unknown-session';
   const config = loadConfig(env);
   const state = await readState(sessionId, env);
-  const reason = fiveHourBudgetDecision(state, config);
+  const tokenBudgetReason = subagentTokenBudgetDecision(state, config, {
+    includeWarning: false
+  });
+  const reason = tokenBudgetReason?.reason || fiveHourBudgetDecision(state, config);
 
   if (!reason) {
     return { exitCode: 0, stdout: null, stderr: '' };
@@ -588,6 +696,7 @@ export async function buildReport(sessionId, env = process.env) {
     fiveHour.latestUsedPercentage !== null && fiveHour.baselineUsedPercentage !== null
       ? Math.max(0, fiveHour.latestUsedPercentage - fiveHour.baselineUsedPercentage)
       : null;
+  const tokenBudget = subagentTokenBudgetStatus(state, config);
 
   return {
     plugin: PLUGIN_NAME,
@@ -596,6 +705,9 @@ export async function buildReport(sessionId, env = process.env) {
     state,
     summary: {
       verifiedTokenLabel: `${state.subagents.verifiedTokens.toLocaleString('en-US')} verified tokens`,
+      subagentTokenBudget: tokenBudget
+        ? `${formatCount(tokenBudget.used)}/${formatCount(tokenBudget.limit)} verified tokens (${tokenBudget.percent.toFixed(1)}%)`
+        : 'no verified-token cap',
       activeSubagents: `${state.subagents.active}/${config.max_concurrent_subagents}`,
       fiveHourBudget:
         consumed === null
@@ -614,6 +726,7 @@ export function formatReport(report) {
     `Enforcement: ${config.enforcement_enabled ? 'enabled' : 'disabled'}`,
     `Subagents: allowed ${state.subagents.allowed}, denied ${state.subagents.denied}, active ${state.subagents.active}, lifecycle starts ${state.subagents.lifecycleStarted}, lifecycle stops ${state.subagents.lifecycleStopped}`,
     `Verified usage: ${summary.verifiedTokenLabel}, ${state.subagents.totalToolUseCount} subagent tool calls, ${state.subagents.totalDurationMs} ms`,
+    `Subagent token budget: ${summary.subagentTokenBudget}`,
     `Background launches: ${state.subagents.backgroundLaunched} lifecycle-counted, token totals pending`,
     `Agent-team tasks: created ${state.agentTeam.created}, denied ${state.agentTeam.denied}, completed ${state.agentTeam.completed}`,
     `5-hour budget: ${summary.fiveHourBudget}`
@@ -659,6 +772,42 @@ function isBridgeStatusLine(statusLine) {
   );
 }
 
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function applySetupPluginConfig(
+  settings,
+  { pluginId = PLUGIN_ID, setupConfig = SETUP_CONFIG } = {}
+) {
+  if (!isPlainObject(settings.pluginConfigs)) {
+    settings.pluginConfigs = {};
+  }
+
+  const currentEntry = isPlainObject(settings.pluginConfigs[pluginId])
+    ? settings.pluginConfigs[pluginId]
+    : {};
+  const currentOptions = isPlainObject(currentEntry.options)
+    ? currentEntry.options
+    : {};
+  const nextOptions = { ...currentOptions };
+
+  for (const key of REMOVED_CONFIG_KEYS) {
+    delete nextOptions[key];
+  }
+
+  for (const key of CONFIG_KEYS) {
+    nextOptions[key] = setupConfig[key];
+  }
+
+  settings.pluginConfigs[pluginId] = {
+    ...currentEntry,
+    options: nextOptions
+  };
+
+  return nextOptions;
+}
+
 export async function installStatusLineBridge({
   homeDir = getHomeDir(),
   pluginRoot = getPluginRoot(),
@@ -680,6 +829,7 @@ export async function installStatusLineBridge({
     padding: existing?.padding ?? previousStatusLine?.padding ?? 0,
     refreshInterval: existing?.refreshInterval ?? 5
   };
+  const pluginConfigOptions = applySetupPluginConfig(settings);
 
   settings.statusLine = nextStatusLine;
   await writeJsonAtomic(settingsPath, settings);
@@ -696,7 +846,9 @@ export async function installStatusLineBridge({
     settingsPath,
     bridgePath,
     command,
-    previousStatusLine
+    previousStatusLine,
+    pluginConfigApplied: true,
+    pluginConfigOptions
   };
 }
 
@@ -751,8 +903,8 @@ export async function renderStatusLine(input, {
 
   const guardSegment =
     fiveHour.latestUsedPercentage === null
-      ? `SBG agents ${report.state.subagents.active}/${report.config.max_concurrent_subagents} | 5h unknown`
-      : `SBG agents ${report.state.subagents.active}/${report.config.max_concurrent_subagents} | 5h ${fiveHour.latestUsedPercentage.toFixed(1)}%`;
+      ? `SBG agents ${report.state.subagents.active}/${report.config.max_concurrent_subagents} | tokens ${report.summary.subagentTokenBudget} | 5h unknown`
+      : `SBG agents ${report.state.subagents.active}/${report.config.max_concurrent_subagents} | tokens ${report.summary.subagentTokenBudget} | 5h ${fiveHour.latestUsedPercentage.toFixed(1)}%`;
 
   return previous ? `${previous} | ${guardSegment}` : guardSegment;
 }

package/lib/verifier.js

@@ -5,6 +5,9 @@ import path from 'node:path';
 
 import {
   CONFIG_KEYS,
+  PLUGIN_ID,
+  REMOVED_CONFIG_KEYS,
+  SETUP_CONFIG,
   buildReport,
   handlePostToolUseAgent,
   handlePreToolUseAgent,
@@ -87,7 +90,7 @@ export async function runOfflineVerification({
         entry.source?.package === '@rex_koh/subagent-budget-guard',
         'marketplace npm package mismatch'
       );
-      assert(entry.source?.version === '0.1.2', 'marketplace npm version mismatch');
+      assert(entry.source?.version === '0.1.4', 'marketplace npm version mismatch');
       return marketplacePath;
     });
   } else {
@@ -287,6 +290,53 @@ export async function runOfflineVerification({
     }
   });
 
+  await withCheck(result, 'setup-applies-plugin-config', 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 } = await import('node:fs/promises');
+      const claudeDir = path.join(homeDir, '.claude');
+      const settingsPath = path.join(claudeDir, 'settings.json');
+      await mkdir(claudeDir, { recursive: true });
+      await writeFile(
+        settingsPath,
+        JSON.stringify({
+          pluginConfigs: {
+            [PLUGIN_ID]: {
+              options: {
+                max_subagents_per_session: 9,
+                max_concurrent_subagents: 0,
+                max_agent_team_tasks_per_session: 4,
+                max_subagent_tokens_per_session: 0,
+                enforcement_enabled: false
+              }
+            }
+          }
+        })
+      );
+
+      await installStatusLineBridge({
+        homeDir,
+        pluginRoot: root,
+        pluginData: dataDir
+      });
+
+      const settings = await readJson(settingsPath);
+      const options = settings.pluginConfigs?.[PLUGIN_ID]?.options;
+      assert(options, `missing pluginConfigs.${PLUGIN_ID}.options`);
+      for (const key of CONFIG_KEYS) {
+        assert(options[key] === SETUP_CONFIG[key], `setup config ${key} mismatch`);
+      }
+      for (const key of REMOVED_CONFIG_KEYS) {
+        assert(!(key in options), `obsolete option ${key} was not removed`);
+      }
+      return `${PLUGIN_ID} recommended setup config applied`;
+    } finally {
+      await rm(dataDir, { recursive: true, force: true });
+      await rm(homeDir, { recursive: true, force: true });
+    }
+  });
+
   result.ok = result.failures.length === 0;
   return result;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rex_koh/subagent-budget-guard",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Claude Code plugin that blocks subagents by default, records verified subagent usage, and enforces 5-hour usage budgets.",
   "license": "MIT",
   "author": "ClaudeSubAgentSuppressor",

package/skills/setup/SKILL.md

@@ -1,5 +1,5 @@
 ---
-description: Install or refresh the Subagent Budget Guard statusLine bridge so 5-hour rate-limit percentages can be captured for enforcement.
+description: Install or refresh the Subagent Budget Guard statusLine bridge and apply the recommended plugin config.
 disable-model-invocation: true
 ---
 
@@ -11,7 +11,18 @@ Run this command:
 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:
+This applies the recommended config in Claude settings:
+
+```text
+max_concurrent_subagents=1
+max_subagent_tokens_per_session=100000
+subagent_token_warning_threshold_percent=95
+session_five_hour_budget_percent=25
+absolute_five_hour_ceiling_percent=95
+enforcement_enabled=true
+```
+
+Then tell the user to run `/reload-plugins`, interact with Claude Code once so the statusLine bridge receives fresh session JSON, and run:
 
 ```bash
 node "${CLAUDE_PLUGIN_ROOT}/bin/verify.js" --live