@rex_koh/subagent-budget-guard 0.1.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,76 @@
+{
+  "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.0",
+  "author": {
+    "name": "ClaudeSubAgentSuppressor"
+  },
+  "license": "MIT",
+  "keywords": [
+    "subagents",
+    "budget",
+    "rate-limit",
+    "tokens",
+    "hooks"
+  ],
+  "userConfig": {
+    "max_subagents_per_session": {
+      "type": "number",
+      "title": "Max subagents per session",
+      "description": "Maximum normal Agent tool subagents allowed in one Claude Code session. The default 0 blocks all new subagents.",
+      "default": 0,
+      "min": 0,
+      "required": true
+    },
+    "max_concurrent_subagents": {
+      "type": "number",
+      "title": "Max concurrent subagents",
+      "description": "Maximum simultaneously active subagents. The default 0 blocks all new subagents.",
+      "default": 0,
+      "min": 0,
+      "required": true
+    },
+    "max_agent_team_tasks_per_session": {
+      "type": "number",
+      "title": "Max agent-team tasks per session",
+      "description": "Maximum agent-team tasks that may be created in one session. The default 0 suppresses agent-team task creation.",
+      "default": 0,
+      "min": 0,
+      "required": true
+    },
+    "max_subagent_tokens_per_session": {
+      "type": "number",
+      "title": "Max verified subagent tokens per session",
+      "description": "Maximum verified subagent tokens allowed in one session. Set 0 for no token cap.",
+      "default": 0,
+      "min": 0,
+      "required": true
+    },
+    "session_five_hour_budget_percent": {
+      "type": "number",
+      "title": "Session 5-hour budget percent",
+      "description": "Maximum percentage points of the current 5-hour Claude Code limit this session may consume after the statusLine bridge records its baseline.",
+      "default": 25,
+      "min": 0,
+      "max": 100,
+      "required": true
+    },
+    "absolute_five_hour_ceiling_percent": {
+      "type": "number",
+      "title": "Absolute 5-hour ceiling percent",
+      "description": "Block new prompts once Claude Code reports this absolute 5-hour usage percentage, regardless of this session's baseline.",
+      "default": 95,
+      "min": 0,
+      "max": 100,
+      "required": true
+    },
+    "enforcement_enabled": {
+      "type": "boolean",
+      "title": "Enable enforcement",
+      "description": "When true, hooks deny over-budget subagents, agent-team tasks, and prompts. When false, the plugin records usage without blocking.",
+      "default": true,
+      "required": true
+    }
+  }
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ClaudeSubAgentSuppressor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,46 @@
+# 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.
+
+## Install
+
+Recommended Claude Code install:
+
+```text
+/plugin marketplace add rexkoh425/ClaudeSubAgentSuppressor
+/plugin install subagent-budget-guard@subagent-budget-tools
+/reload-plugins
+```
+
+Run after install:
+
+```text
+/subagent-budget-guard:setup
+/subagent-budget-guard:verify
+/subagent-budget-guard:report
+```
+
+## NPM Package
+
+This package is npm-ready as `@rex_koh/subagent-budget-guard`.
+
+Claude Code plugin discovery is marketplace-based, so npm is mainly useful as a plugin source in a marketplace entry or for installing the helper CLIs:
+
+```bash
+npm install -g @rex_koh/subagent-budget-guard
+subagent-budget-guard-verify --offline
+```
+
+Maintainer publish command:
+
+```bash
+npm publish --access public
+```
+
+Offline verification:
+
+```bash
+node bin/verify.js --offline
+```
+
+The plugin is strict by default: `max_subagents_per_session`, `max_concurrent_subagents`, and `max_agent_team_tasks_per_session` all default to `0`.

package/bin/hook.js

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+import {
+  handlePostToolUseAgent,
+  handlePreToolUseAgent,
+  handleSubagentStart,
+  handleSubagentStop,
+  handleTaskCompleted,
+  handleTaskCreated,
+  handleUserPromptSubmit
+} from '../lib/guard.js';
+
+async function readStdin() {
+  let input = '';
+  process.stdin.setEncoding('utf8');
+  for await (const chunk of process.stdin) {
+    input += chunk;
+  }
+  return input ? JSON.parse(input) : {};
+}
+
+function emit(result) {
+  if (result.stdout) {
+    process.stdout.write(`${JSON.stringify(result.stdout)}\n`);
+  }
+  if (result.stderr) {
+    process.stderr.write(`${result.stderr}\n`);
+  }
+  process.exitCode = result.exitCode ?? 0;
+}
+
+const handlers = {
+  'pretool-agent': handlePreToolUseAgent,
+  'posttool-agent': handlePostToolUseAgent,
+  'subagent-start': handleSubagentStart,
+  'subagent-stop': handleSubagentStop,
+  'task-created': handleTaskCreated,
+  'task-completed': handleTaskCompleted,
+  'user-prompt-submit': handleUserPromptSubmit
+};
+
+async function main() {
+  const action = process.argv[2];
+  const handler = handlers[action];
+
+  if (!handler) {
+    throw new Error(`Unknown hook action: ${action || '(missing)'}`);
+  }
+
+  const input = await readStdin();
+  emit(await handler(input, process.env));
+}
+
+main().catch((error) => {
+  process.stderr.write(`subagent-budget-guard hook error: ${error.stack || error.message}\n`);
+  process.exitCode = 1;
+});

package/bin/report.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+import { buildReport, formatReport } from '../lib/guard.js';
+
+function argValue(name) {
+  const index = process.argv.indexOf(name);
+  if (index === -1) return null;
+  return process.argv[index + 1] || null;
+}
+
+async function main() {
+  const asJson = process.argv.includes('--json');
+  const sessionId = argValue('--session');
+  const report = await buildReport(sessionId, process.env);
+
+  process.stdout.write(
+    asJson ? `${JSON.stringify(report, null, 2)}\n` : `${formatReport(report)}\n`
+  );
+}
+
+main().catch((error) => {
+  process.stderr.write(`report failed: ${error.stack || error.message}\n`);
+  process.exitCode = 1;
+});

package/bin/setup.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+import { getDataDir, getHomeDir, getPluginRoot, installStatusLineBridge } from '../lib/guard.js';
+
+async function main() {
+  const result = await installStatusLineBridge({
+    homeDir: getHomeDir(process.env),
+    pluginRoot: getPluginRoot(process.env),
+    pluginData: getDataDir(process.env)
+  });
+
+  process.stdout.write(
+    [
+      'Subagent Budget Guard statusLine bridge installed.',
+      `Settings: ${result.settingsPath}`,
+      `Bridge state: ${result.bridgePath}`,
+      result.previousStatusLine
+        ? 'Existing statusLine command preserved and wrapped.'
+        : 'No previous statusLine command was configured.'
+    ].join('\n') + '\n'
+  );
+}
+
+main().catch((error) => {
+  process.stderr.write(`setup failed: ${error.stack || error.message}\n`);
+  process.exitCode = 1;
+});

package/bin/statusline.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+import { renderStatusLine } from '../lib/guard.js';
+
+function argValue(name) {
+  const index = process.argv.indexOf(name);
+  if (index === -1) return null;
+  return process.argv[index + 1] || null;
+}
+
+async function readStdin() {
+  let input = '';
+  process.stdin.setEncoding('utf8');
+  for await (const chunk of process.stdin) {
+    input += chunk;
+  }
+  return input ? JSON.parse(input) : {};
+}
+
+async function main() {
+  const pluginData = argValue('--data') || process.env.CLAUDE_PLUGIN_DATA;
+  const input = await readStdin();
+  const output = await renderStatusLine(input, { pluginData, env: process.env });
+  process.stdout.write(`${output}\n`);
+}
+
+main().catch((error) => {
+  process.stdout.write(`SBG error: ${error.message}\n`);
+});

package/bin/verify.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+import {
+  formatVerificationResult,
+  runLiveVerification,
+  runOfflineVerification
+} from '../lib/verifier.js';
+
+function modeFromArgs() {
+  if (process.argv.includes('--live')) return 'live';
+  return 'offline';
+}
+
+async function main() {
+  const mode = modeFromArgs();
+  const result =
+    mode === 'live'
+      ? await runLiveVerification({ repoRoot: process.cwd(), env: process.env })
+      : await runOfflineVerification({ repoRoot: process.cwd(), env: process.env });
+
+  process.stdout.write(`${formatVerificationResult(result)}\n`);
+  process.exitCode = result.ok ? 0 : 1;
+}
+
+main().catch((error) => {
+  process.stderr.write(`verification failed: ${error.stack || error.message}\n`);
+  process.exitCode = 1;
+});

package/hooks/hooks.json

@@ -0,0 +1,120 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Agent",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": [
+              "${CLAUDE_PLUGIN_ROOT}/bin/hook.js",
+              "pretool-agent"
+            ],
+            "timeout": 10,
+            "statusMessage": "Checking subagent budget"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Agent",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": [
+              "${CLAUDE_PLUGIN_ROOT}/bin/hook.js",
+              "posttool-agent"
+            ],
+            "timeout": 10,
+            "statusMessage": "Recording subagent usage"
+          }
+        ]
+      }
+    ],
+    "SubagentStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": [
+              "${CLAUDE_PLUGIN_ROOT}/bin/hook.js",
+              "subagent-start"
+            ],
+            "timeout": 10,
+            "statusMessage": "Recording subagent start"
+          }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": [
+              "${CLAUDE_PLUGIN_ROOT}/bin/hook.js",
+              "subagent-stop"
+            ],
+            "timeout": 10,
+            "statusMessage": "Recording subagent stop"
+          }
+        ]
+      }
+    ],
+    "TaskCreated": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": [
+              "${CLAUDE_PLUGIN_ROOT}/bin/hook.js",
+              "task-created"
+            ],
+            "timeout": 10,
+            "statusMessage": "Checking agent-team budget"
+          }
+        ]
+      }
+    ],
+    "TaskCompleted": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": [
+              "${CLAUDE_PLUGIN_ROOT}/bin/hook.js",
+              "task-completed"
+            ],
+            "timeout": 10,
+            "statusMessage": "Recording agent-team completion"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node",
+            "args": [
+              "${CLAUDE_PLUGIN_ROOT}/bin/hook.js",
+              "user-prompt-submit"
+            ],
+            "timeout": 10,
+            "statusMessage": "Checking 5-hour budget"
+          }
+        ]
+      }
+    ]
+  }
+}