@rex_koh/subagent-budget-guard 0.3.0 → 0.5.0

package/.claude-plugin/plugin.json

@@ -1,8 +1,8 @@
 {
-  "name": "agent-guard",
-  "displayName": "Agent Guard",
+  "name": "subagent-cap",
+  "displayName": "Subagent Cap",
   "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.3.0",
+  "version": "0.5.0",
   "author": {
     "name": "ClaudeSubAgentSuppressor"
   },

package/README.md

@@ -1,4 +1,4 @@
-# Agent Guard
+# Subagent Cap
 
 Claude Code plugin that guards subagent usage, records verified subagent tokens, and enforces a session budget against Claude Code's 5-hour usage percentage.
 
@@ -8,11 +8,11 @@ Recommended Claude Code install:
 
 ```text
 /plugin marketplace add rexkoh425/ClaudeSubAgentSuppressor
-/plugin install agent-guard@subagent-budget-tools
-/agent-guard:init
+/plugin install subagent-cap@subagent-tools
+/subagent-cap:init
 ```
 
-After `/agent-guard:init`, fully exit and reopen Claude Code so the statusLine bridge from `settings.json` is active. Some Claude Code builds do not provide an in-session plugin reload command.
+After `/subagent-cap:init`, fully exit and reopen Claude Code so the statusLine bridge from `settings.json` is active. Some Claude Code builds do not provide an in-session plugin reload command.
 
 ## NPM Package
 
@@ -22,10 +22,13 @@ Claude Code plugin discovery is marketplace-based, so npm is mainly useful as a
 
 ```bash
 npm install -g @rex_koh/subagent-budget-guard
-agent-guard doctor --offline
-agent-guard status
+subagent-cap doctor --offline
+subagent-cap status
+sub-agent-view
 ```
 
+`sub-agent-view` prints the latest session's recorded subagents with per-subagent status, type, description, verified token count, duration, model, and tool-call count. Use `sub-agent-view --session <session-id>` for a specific saved session, or `sub-agent-view --json` for machine-readable output. The same view is also available as `subagent-cap view`.
+
 Maintainer publish command:
 
 ```bash
@@ -38,7 +41,7 @@ Offline verification:
 node bin/verify.js --offline
 ```
 
-The plugin is strict before setup: `max_concurrent_subagents` defaults to `0`, so normal subagent launches are blocked unless raised. Run `/agent-guard:init` to choose defaults or custom values:
+The plugin is strict before setup: `max_concurrent_subagents` defaults to `0`, so normal subagent launches are blocked unless raised. Run `/subagent-cap:init` to choose defaults or custom values:
 
 ```text
 max_concurrent_subagents=1
@@ -54,13 +57,13 @@ For existing installs, setup also removes obsolete `max_subagents_per_session` a
 The setup skill can ask for custom values. For direct terminal setup, use:
 
 ```bash
-agent-guard init
+subagent-cap init
 ```
 
 Or pass explicit values:
 
 ```bash
-agent-guard init \
+subagent-cap init \
   --config max_concurrent_subagents=2 \
   --config max_subagent_tokens_per_session=250000 \
   --config subagent_token_warning_threshold_percent=90 \

package/bin/setup.js

@@ -15,7 +15,7 @@ const CONFIG_KEY_SET = new Set(CONFIG_KEYS);
 
 function usage() {
   return [
-    'Usage: agent-guard init [--defaults] [--interactive] [--config key=value ...]',
+    'Usage: subagent-cap init [--defaults] [--interactive] [--config key=value ...]',
     '',
     'Config keys:',
     ...CONFIG_KEYS.map((key) => `  ${key} (default ${SETUP_CONFIG[key]})`)
@@ -121,7 +121,7 @@ async function main() {
 
   process.stdout.write(
     [
-      'Agent Guard statusLine bridge installed.',
+      'Subagent Cap statusLine bridge installed.',
       'Plugin config applied:',
       `  max_concurrent_subagents=${result.pluginConfigOptions.max_concurrent_subagents}`,
       `  max_subagent_tokens_per_session=${result.pluginConfigOptions.max_subagent_tokens_per_session}`,

package/bin/{agent-guard.js → subagent-cap.js}

@@ -14,6 +14,10 @@ const COMMANDS = Object.freeze({
     script: 'report.js',
     help: 'show the current guard report'
   },
+  view: {
+    script: 'view.js',
+    help: 'show recorded subagent tokens and duration'
+  },
   doctor: {
     script: 'verify.js',
     help: 'verify the install without spending Claude quota'
@@ -22,16 +26,17 @@ const COMMANDS = Object.freeze({
 
 function usage() {
   return [
-    'Usage: agent-guard <command> [options]',
+    'Usage: subagent-cap <command> [options]',
     '',
     'Commands:',
     ...Object.entries(COMMANDS).map(([name, info]) => `  ${name.padEnd(8)} ${info.help}`),
     '',
     'Examples:',
-    '  agent-guard init',
-    '  agent-guard init --defaults',
-    '  agent-guard status',
-    '  agent-guard doctor --offline'
+    '  subagent-cap init',
+    '  subagent-cap init --defaults',
+    '  subagent-cap status',
+    '  subagent-cap view',
+    '  subagent-cap doctor --offline'
   ].join('\n');
 }
 

package/bin/view.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+import { buildReport, formatSubagentView } 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);
+  const view = {
+    plugin: report.plugin,
+    sessionId: report.sessionId,
+    spawnedSubagents: report.state.subagents.runs.length,
+    verifiedTokens: report.state.subagents.verifiedTokens,
+    totalDurationMs: report.state.subagents.totalDurationMs,
+    subagents: report.state.subagents.runs
+  };
+
+  process.stdout.write(
+    asJson ? `${JSON.stringify(view, null, 2)}\n` : `${formatSubagentView(report)}\n`
+  );
+}
+
+main().catch((error) => {
+  process.stderr.write(`sub-agent-view failed: ${error.stack || error.message}\n`);
+  process.exitCode = 1;
+});

package/lib/guard.js

@@ -17,9 +17,8 @@ import { fileURLToPath } from 'node:url';
 
 const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 
-export const PLUGIN_NAME = 'agent-guard';
-export const PLUGIN_ID = 'agent-guard@subagent-budget-tools';
-export const LEGACY_PLUGIN_ID = 'subagent-budget-guard@subagent-budget-tools';
+export const PLUGIN_NAME = 'subagent-cap';
+export const PLUGIN_ID = 'subagent-cap@subagent-tools';
 
 export const DEFAULT_CONFIG = Object.freeze({
   max_concurrent_subagents: 0,
@@ -88,9 +87,7 @@ function readSettingsOptions(env) {
   try {
     const text = readFileSync(settingsPath, 'utf8');
     const settings = JSON.parse(text.replace(/^\uFEFF/, ''));
-    const options =
-      settings?.pluginConfigs?.[PLUGIN_ID]?.options ||
-      settings?.pluginConfigs?.[LEGACY_PLUGIN_ID]?.options;
+    const options = settings?.pluginConfigs?.[PLUGIN_ID]?.options;
     return isPlainObject(options) ? options : {};
   } catch (error) {
     if (error.code === 'ENOENT') return {};
@@ -760,7 +757,7 @@ export function formatReport(report) {
   const { state, config, summary } = report;
   const fiveHour = state.rateLimits.fiveHour;
   const lines = [
-    `Agent Guard report for ${report.sessionId}`,
+    `Subagent Cap report for ${report.sessionId}`,
     `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`,
@@ -776,13 +773,46 @@ export function formatReport(report) {
     );
   } else {
     lines.push(
-      '5-hour latest: unavailable. Run /agent-guard:init so the statusLine bridge can capture rate_limits.five_hour.used_percentage.'
+      '5-hour latest: unavailable. Run /subagent-cap:init so the statusLine bridge can capture rate_limits.five_hour.used_percentage.'
     );
   }
 
   return lines.join('\n');
 }
 
+function formatDuration(ms) {
+  const value = Number(ms || 0);
+  if (value >= 1000) return `${(value / 1000).toFixed(value % 1000 === 0 ? 0 : 1)}s`;
+  return `${value}ms`;
+}
+
+export function formatSubagentView(report) {
+  const runs = report.state.subagents.runs;
+  const lines = [
+    `Sub-agent view for ${report.sessionId}`,
+    `Spawned subagents: ${runs.length}`,
+    `Verified tokens: ${formatCount(report.state.subagents.verifiedTokens)}`,
+    `Total duration: ${formatDuration(report.state.subagents.totalDurationMs)}`
+  ];
+
+  if (runs.length === 0) {
+    lines.push('No subagents recorded for this session.');
+    return lines.join('\n');
+  }
+
+  for (const [index, run] of runs.entries()) {
+    const type = run.subagentType || 'unknown';
+    const description = run.description ? ` "${run.description}"` : '';
+    lines.push(`#${index + 1} ${run.status} ${type}${description}`);
+    lines.push(`  tokens: ${run.verified ? `${formatCount(run.totalTokens)} verified` : 'pending'}`);
+    lines.push(`  duration: ${formatDuration(run.totalDurationMs)}`);
+    lines.push(`  model: ${run.resolvedModel || 'unknown'}`);
+    lines.push(`  tools: ${Number(run.totalToolUseCount || 0)}`);
+  }
+
+  return lines.join('\n');
+}
+
 function quoteShellArg(value) {
   const normalized = String(value).replace(/\\/g, '/').replace(/"/g, '\\"');
   return `"${normalized}"`;
@@ -822,12 +852,9 @@ function applySetupPluginConfig(
     settings.pluginConfigs = {};
   }
 
-  const legacyEntry = isPlainObject(settings.pluginConfigs[LEGACY_PLUGIN_ID])
-    ? settings.pluginConfigs[LEGACY_PLUGIN_ID]
-    : {};
   const currentEntry = isPlainObject(settings.pluginConfigs[pluginId])
     ? settings.pluginConfigs[pluginId]
-    : legacyEntry;
+    : {};
   const currentOptions = isPlainObject(currentEntry.options)
     ? currentEntry.options
     : {};
@@ -846,10 +873,6 @@ function applySetupPluginConfig(
     ...currentEntry,
     options: nextOptions
   };
-  if (pluginId !== LEGACY_PLUGIN_ID) {
-    delete settings.pluginConfigs[LEGACY_PLUGIN_ID];
-  }
-
   return nextOptions;
 }
 

package/lib/verifier.js

@@ -102,16 +102,16 @@ export async function runOfflineVerification({
     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(marketplace.name === 'subagent-tools', 'marketplace name mismatch');
       assert(Array.isArray(marketplace.plugins), 'marketplace.plugins must be an array');
-      const entry = marketplace.plugins.find((plugin) => plugin.name === 'agent-guard');
-      assert(entry, 'agent-guard entry missing');
+      const entry = marketplace.plugins.find((plugin) => plugin.name === 'subagent-cap');
+      assert(entry, 'subagent-cap 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.3.0', 'marketplace npm version mismatch');
+      assert(entry.source?.version === '0.5.0', 'marketplace npm version mismatch');
       return marketplacePath;
     });
   } else {
@@ -129,7 +129,7 @@ export async function runOfflineVerification({
   await withCheck(result, 'plugin-manifest-no-install-config', async () => {
     const manifestPath = path.join(root, '.claude-plugin', 'plugin.json');
     const manifest = await readJson(manifestPath);
-    assert(manifest.name === 'agent-guard', 'plugin name mismatch');
+    assert(manifest.name === 'subagent-cap', 'plugin name mismatch');
     assert(
       manifest.hooks === undefined,
       'manifest.hooks must be omitted for default hooks/hooks.json to avoid duplicate loading'
@@ -168,10 +168,11 @@ export async function runOfflineVerification({
   await withCheck(result, 'script-paths', async () => {
     const scripts = [
       'bin/hook.js',
-      'bin/agent-guard.js',
+      'bin/subagent-cap.js',
       'bin/statusline.js',
       'bin/setup.js',
       'bin/report.js',
+      'bin/view.js',
       'bin/verify.js',
       'lib/guard.js',
       'lib/verifier.js',
@@ -407,12 +408,12 @@ export async function runLiveVerification({
       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('agent-guard'),
-        'agent-guard is not installed'
+        list.stdout.includes('subagent-cap'),
+        'subagent-cap is not installed'
       );
       assert(
-        !/agent-guard@subagent-budget-tools[\s\S]*failed to load/i.test(list.stdout),
-        'agent-guard is installed but failed to load'
+        !/subagent-cap@subagent-tools[\s\S]*failed to load/i.test(list.stdout),
+        'subagent-cap is installed but failed to load'
       );
       return 'claude plugin list returned output';
     });
@@ -426,7 +427,7 @@ export async function runLiveVerification({
       typeof settings.statusLine?.command === 'string' &&
         settings.statusLine.command.includes('statusline.js') &&
         settings.statusLine.command.includes('--data'),
-      'statusLine bridge is not installed; run /agent-guard:init'
+      'statusLine bridge is not installed; run /subagent-cap:init'
     );
     return settings.statusLine.command;
   });
@@ -437,7 +438,7 @@ export async function runLiveVerification({
 
 export function formatVerificationResult(result) {
   const lines = [
-    `Agent Guard ${result.mode} verification`,
+    `Subagent Cap ${result.mode} verification`,
     result.ok ? 'PASS' : 'FAIL'
   ];
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rex_koh/subagent-budget-guard",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Claude Code plugin that blocks subagents by default, records verified subagent usage, and enforces 5-hour usage budgets.",
   "license": "MIT",
   "author": "ClaudeSubAgentSuppressor",
@@ -32,7 +32,8 @@
     "LICENSE"
   ],
   "bin": {
-    "agent-guard": "bin/agent-guard.js"
+    "subagent-cap": "bin/subagent-cap.js",
+    "sub-agent-view": "bin/view.js"
   },
   "publishConfig": {
     "access": "public"
@@ -41,7 +42,7 @@
     "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 bin/agent-guard.js && node --check lib/guard.js && node --check lib/verifier.js"
+    "prepack": "node --check bin/hook.js && node --check bin/statusline.js && node --check bin/setup.js && node --check bin/report.js && node --check bin/view.js && node --check bin/verify.js && node --check bin/subagent-cap.js && node --check lib/guard.js && node --check lib/verifier.js"
   },
   "engines": {
     "node": ">=20"

package/skills/init/SKILL.md

@@ -1,8 +1,8 @@
 ---
-description: Initialize Agent Guard settings and the statusLine bridge.
+description: Initialize Subagent Cap settings and the statusLine bridge.
 ---
 
-# Init Agent Guard
+# Init Subagent Cap
 
 Ask the user whether to use recommended defaults or custom values.
 
@@ -20,13 +20,13 @@ enforcement_enabled=true
 If they choose defaults, run:
 
 ```bash
-node "${CLAUDE_PLUGIN_ROOT}/bin/agent-guard.js" init --defaults
+node "${CLAUDE_PLUGIN_ROOT}/bin/subagent-cap.js" init --defaults
 ```
 
 If they choose custom values, ask for each value. Accept a blank answer as the default, then run:
 
 ```bash
-node "${CLAUDE_PLUGIN_ROOT}/bin/agent-guard.js" init \
+node "${CLAUDE_PLUGIN_ROOT}/bin/subagent-cap.js" init \
   --config max_concurrent_subagents=<value> \
   --config max_subagent_tokens_per_session=<value> \
   --config subagent_token_warning_threshold_percent=<value> \
@@ -40,5 +40,5 @@ Then tell the user to fully exit and reopen Claude Code, then interact once so t
 For optional terminal verification, run:
 
 ```bash
-node "${CLAUDE_PLUGIN_ROOT}/bin/agent-guard.js" doctor --live
+node "${CLAUDE_PLUGIN_ROOT}/bin/subagent-cap.js" doctor --live
 ```