@rex_koh/subagent-budget-guard 0.1.3 → 0.1.5

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.3",
+  "version": "0.1.5",
   "author": {
     "name": "ClaudeSubAgentSuppressor"
   },
@@ -21,7 +21,7 @@
       "description": "Maximum simultaneously active subagents. The default 0 blocks all new subagents.",
       "default": 0,
       "min": 0,
-      "required": true
+      "required": false
     },
     "max_subagent_tokens_per_session": {
       "type": "number",
@@ -29,7 +29,7 @@
       "description": "Maximum verified subagent tokens allowed in one session. Set 0 for no token cap.",
       "default": 0,
       "min": 0,
-      "required": true
+      "required": false
     },
     "subagent_token_warning_threshold_percent": {
       "type": "number",
@@ -38,7 +38,7 @@
       "default": 95,
       "min": 1,
       "max": 100,
-      "required": true
+      "required": false
     },
     "session_five_hour_budget_percent": {
       "type": "number",
@@ -47,7 +47,7 @@
       "default": 25,
       "min": 0,
       "max": 100,
-      "required": true
+      "required": false
     },
     "absolute_five_hour_ceiling_percent": {
       "type": "number",
@@ -56,14 +56,14 @@
       "default": 95,
       "min": 0,
       "max": 100,
-      "required": true
+      "required": false
     },
     "enforcement_enabled": {
       "type": "boolean",
       "title": "Enable enforcement",
       "description": "When true, hooks deny over-budget subagents and prompts. When false, the plugin records usage without blocking.",
       "default": true,
-      "required": true
+      "required": false
     }
   }
 }

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,6 +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,7 +13,12 @@ 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,
@@ -24,7 +29,17 @@ export const DEFAULT_CONFIG = Object.freeze({
   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')
@@ -92,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) {
@@ -757,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(),
@@ -778,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);
@@ -794,7 +846,9 @@ export async function installStatusLineBridge({
     settingsPath,
     bridgePath,
     command,
-    previousStatusLine
+    previousStatusLine,
+    pluginConfigApplied: true,
+    pluginConfigOptions
   };
 }
 

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.3', 'marketplace npm version mismatch');
+      assert(entry.source?.version === '0.1.5', 'marketplace npm version mismatch');
       return marketplacePath;
     });
   } else {
@@ -116,6 +119,10 @@ export async function runOfflineVerification({
     );
     for (const key of CONFIG_KEYS) {
       assert(manifest.userConfig?.[key], `missing userConfig.${key}`);
+      assert(
+        manifest.userConfig[key].required !== true,
+        `userConfig.${key} must not be required at install time`
+      );
     }
     return manifestPath;
   });
@@ -287,6 +294,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.3",
+  "version": "0.1.5",
   "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